@openez-graph/cli 0.3.0 → 0.3.2

package/LICENSE

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

package/README.md

@@ -1,6 +1,23 @@
 # @openez-graph/cli
 
-Local-first code intelligence CLI. Zero-config. SQLite-only.
+> Local-first code intelligence engine — index, query, and graph your codebase with zero config.
+
+[![npm version](https://img.shields.io/npm/v/@openez-graph/cli.svg)](https://www.npmjs.com/package/@openez-graph/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+OpenEZ Graph indexes your codebase into a local SQLite database, builds a code graph (symbols, files, chunks, edges), and exposes it through MCP tools for AI coding agents like Claude Code, Codex, and OpenCode.
+
+**Zero config. No Docker. No Postgres. No Redis. Just install and go.**
+
+## Features
+
+- **Zero-config** — auto-registers workspace, auto-indexes, auto-syncs on file changes
+- **SQLite-first** — all data stored locally in `.openez/` per workspace
+- **MCP-first** — exposes `memory_query`, `code_context`, `graph_neighbors`, `memory_write`, `index_workspace`, `list_workspaces` tools
+- **Multi-workspace** — register and query across multiple codebases
+- **Code graph** — symbols, files, chunks, and edges (calls, imports, contains)
+- **Web dashboard** — built-in graph explorer and workspace management UI
+- **Auto-sync** — file watcher re-indexes on changes (2s debounce)
 
 ## Install
 
@@ -9,24 +26,87 @@ npm install -g @openez-graph/cli
 openez setup claude    # or: codex, opencode
 ```
 
+Restart your agent. Done.
+
+## Quick start
+
+```bash
+# 1. Install
+npm install -g @openez-graph/cli
+
+# 2. Wire up your agent
+openez setup claude       # Claude Code
+openez setup codex        # Codex
+openez setup opencode     # OpenCode
+
+# 3. Restart your agent — it will auto-index and auto-sync
+```
+
 ## Commands
 
 ```bash
-openez init [path]           # register + index a workspace
-openez index [path]          # incremental index
-openez reindex [path]        # full rebuild
-openez watch [path]          # watch + auto-reindex on changes
-openez serve --mcp           # start MCP server (auto-index + auto-sync)
-openez serve --web           # start web dashboard API server (default port 11368)
-openez serve --web --port 8080 # start web dashboard API server on custom port
-openez status [path]         # show workspace status
-openez list                  # list registered workspaces
-openez setup claude          # wire up Claude Code
-openez setup codex           # wire up Codex
-openez setup opencode        # wire up OpenCode
+openez init [path]              # register + index a workspace
+openez index [path]             # incremental index
+openez reindex [path]           # full rebuild
+openez watch [path]             # watch + auto-reindex on changes
+openez serve --mcp              # start MCP server (auto-index + auto-sync)
+openez serve --web              # start web dashboard (default port 17881)
+openez serve --web --port 8080  # start web dashboard on custom port
+openez status [path]            # show workspace status
+openez list                     # list registered workspaces
+openez setup claude             # wire up Claude Code
+openez setup codex              # wire up Codex
+openez setup opencode           # wire up OpenCode
 ```
 
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_workspaces` | List all registered workspaces |
+| `memory_query` | Full-text search + graph expansion for retrieval context |
+| `code_context` | Get symbol context with callers, callees, and related files |
+| `graph_neighbors` | Traverse graph edges from a node or label |
+| `memory_write` | Write a memory entry (notes, decisions, patterns) |
+| `index_workspace` | Trigger indexing for a workspace |
+
+## How it works
+
+1. **`openez setup claude`** writes MCP server config to `~/.claude/settings.json`
+2. When Claude Code starts, it launches the MCP server via `openez serve --mcp`
+3. The MCP server auto-registers the current project as a workspace
+4. It auto-indexes if the workspace has no documents yet
+5. It watches for file changes and re-indexes automatically (2s debounce)
+6. All data is stored in `<project>/.openez/index.sqlite` — local, portable, gitignored
+
+## Supported languages
+
+| Language | Indexing depth |
+|----------|---------------|
+| TypeScript / JavaScript | Richest — `ts-morph` symbol extraction, imports, calls |
+| Python | Basic top-level symbol extraction |
+| Go | Basic top-level symbol extraction |
+| Rust | Basic top-level symbol extraction |
+| YAML / JSON / TOML | Structure-aware chunking |
+| Markdown | Section-oriented chunking |
+
+## Web dashboard
+
+```bash
+openez serve --web
+```
+
+Opens a full web dashboard at `http://localhost:17881` with:
+- Workspace overview (documents, chunks, nodes, edges)
+- Graph explorer with force-directed layout
+- Query interface for memory retrieval
+- Indexing control and run history
+
 ## Requirements
 
 - Node.js 20+
-- No Docker, Postgres, or Redis needed
+- No external services needed
+
+## License
+
+MIT © [Asta Nguyen](https://github.com/asta-nguyen)

package/dist/cli.cjs

@@ -2912,7 +2912,7 @@ var require_command = __commonJS({
     var EventEmitter2 = require("events").EventEmitter;
     var childProcess = require("child_process");
     var path19 = require("path");
-    var fs16 = require("fs");
+    var fs17 = require("fs");
     var process3 = require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -3906,7 +3906,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} subcommandName
        */
       _checkForMissingExecutable(executableFile, executableDir, subcommandName) {
-        if (fs16.existsSync(executableFile)) return;
+        if (fs17.existsSync(executableFile)) return;
         const executableDirMessage = executableDir ? `searched for local subcommand relative to directory '${executableDir}'` : "no directory for search for local subcommand, use .executableDir() to supply a custom directory";
         const executableMissing = `'${executableFile}' does not exist
  - if '${subcommandName}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead
@@ -3925,10 +3925,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
           const localBin = path19.resolve(baseDir, baseName);
-          if (fs16.existsSync(localBin)) return localBin;
+          if (fs17.existsSync(localBin)) return localBin;
           if (sourceExt.includes(path19.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs16.existsSync(`${localBin}${ext}`)
+            (ext) => fs17.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -3940,7 +3940,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs16.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs17.realpathSync(this._scriptPath);
           } catch {
             resolvedScriptPath = this._scriptPath;
           }
@@ -12514,7 +12514,7 @@ var require_package = __commonJS({
 var require_main = __commonJS({
   "../../node_modules/.pnpm/dotenv@16.6.1/node_modules/dotenv/lib/main.js"(exports2, module3) {
     "use strict";
-    var fs16 = require("fs");
+    var fs17 = require("fs");
     var path19 = require("path");
     var os6 = require("os");
     var crypto4 = require("crypto");
@@ -12623,7 +12623,7 @@ var require_main = __commonJS({
       if (options && options.path && options.path.length > 0) {
         if (Array.isArray(options.path)) {
           for (const filepath of options.path) {
-            if (fs16.existsSync(filepath)) {
+            if (fs17.existsSync(filepath)) {
               possibleVaultPath = filepath.endsWith(".vault") ? filepath : `${filepath}.vault`;
             }
           }
@@ -12633,7 +12633,7 @@ var require_main = __commonJS({
       } else {
         possibleVaultPath = path19.resolve(process.cwd(), ".env.vault");
       }
-      if (fs16.existsSync(possibleVaultPath)) {
+      if (fs17.existsSync(possibleVaultPath)) {
         return possibleVaultPath;
       }
       return null;
@@ -12682,7 +12682,7 @@ var require_main = __commonJS({
       const parsedAll = {};
       for (const path20 of optionPaths) {
         try {
-          const parsed = DotenvModule.parse(fs16.readFileSync(path20, { encoding }));
+          const parsed = DotenvModule.parse(fs17.readFileSync(path20, { encoding }));
           DotenvModule.populate(parsedAll, parsed, options);
         } catch (e) {
           if (debug) {
@@ -29609,11 +29609,11 @@ var require_source_map_support = __commonJS({
     "use strict";
     var SourceMapConsumer = require_source_map().SourceMapConsumer;
     var path19 = require("path");
-    var fs16;
+    var fs17;
     try {
-      fs16 = require("fs");
-      if (!fs16.existsSync || !fs16.readFileSync) {
-        fs16 = null;
+      fs17 = require("fs");
+      if (!fs17.existsSync || !fs17.readFileSync) {
+        fs17 = null;
       }
     } catch (err) {
     }
@@ -29684,7 +29684,7 @@ var require_source_map_support = __commonJS({
       }
       var contents = "";
       try {
-        if (!fs16) {
+        if (!fs17) {
           var xhr = new XMLHttpRequest();
           xhr.open(
             "GET",
@@ -29696,8 +29696,8 @@ var require_source_map_support = __commonJS({
           if (xhr.readyState === 4 && xhr.status === 200) {
             contents = xhr.responseText;
           }
-        } else if (fs16.existsSync(path20)) {
-          contents = fs16.readFileSync(path20, "utf8");
+        } else if (fs17.existsSync(path20)) {
+          contents = fs17.readFileSync(path20, "utf8");
         }
       } catch (er) {
       }
@@ -29961,9 +29961,9 @@ var require_source_map_support = __commonJS({
         var line = +match[2];
         var column = +match[3];
         var contents = fileContentsCache[source];
-        if (!contents && fs16 && fs16.existsSync(source)) {
+        if (!contents && fs17 && fs17.existsSync(source)) {
           try {
-            contents = fs16.readFileSync(source, "utf8");
+            contents = fs17.readFileSync(source, "utf8");
           } catch (er) {
             contents = "";
           }
@@ -33724,10 +33724,10 @@ var require_typescript = __commonJS({
       function and2(f, g2) {
         return (arg) => f(arg) && g2(arg);
       }
-      function or2(...fs16) {
+      function or2(...fs17) {
         return (...args) => {
           let lastResult;
-          for (const f of fs16) {
+          for (const f of fs17) {
             lastResult = f(...args);
             if (lastResult) {
               return lastResult;
@@ -35302,7 +35302,7 @@ ${lanes.join("\n")}
       var tracing;
       var tracingEnabled;
       ((tracingEnabled2) => {
-        let fs16;
+        let fs17;
         let traceCount = 0;
         let traceFd = 0;
         let mode;
@@ -35311,9 +35311,9 @@ ${lanes.join("\n")}
         const legend = [];
         function startTracing2(tracingMode, traceDir, configFilePath) {
           Debug.assert(!tracing, "Tracing already started");
-          if (fs16 === void 0) {
+          if (fs17 === void 0) {
             try {
-              fs16 = require("fs");
+              fs17 = require("fs");
             } catch (e) {
               throw new Error(`tracing requires having fs
 (original error: ${e.message || e})`);
@@ -35324,8 +35324,8 @@ ${lanes.join("\n")}
           if (legendPath === void 0) {
             legendPath = combinePaths(traceDir, "legend.json");
           }
-          if (!fs16.existsSync(traceDir)) {
-            fs16.mkdirSync(traceDir, { recursive: true });
+          if (!fs17.existsSync(traceDir)) {
+            fs17.mkdirSync(traceDir, { recursive: true });
           }
           const countPart = mode === "build" ? `.${process.pid}-${++traceCount}` : mode === "server" ? `.${process.pid}` : ``;
           const tracePath = combinePaths(traceDir, `trace${countPart}.json`);
@@ -35335,10 +35335,10 @@ ${lanes.join("\n")}
             tracePath,
             typesPath
           });
-          traceFd = fs16.openSync(tracePath, "w");
+          traceFd = fs17.openSync(tracePath, "w");
           tracing = tracingEnabled2;
           const meta = { cat: "__metadata", ph: "M", ts: 1e3 * timestamp(), pid: 1, tid: 1 };
-          fs16.writeSync(
+          fs17.writeSync(
             traceFd,
             "[\n" + [{ name: "process_name", args: { name: "tsc" }, ...meta }, { name: "thread_name", args: { name: "Main" }, ...meta }, { name: "TracingStartedInBrowser", ...meta, cat: "disabled-by-default-devtools.timeline" }].map((v) => JSON.stringify(v)).join(",\n")
           );
@@ -35347,10 +35347,10 @@ ${lanes.join("\n")}
         function stopTracing() {
           Debug.assert(tracing, "Tracing is not in progress");
           Debug.assert(!!typeCatalog.length === (mode !== "server"));
-          fs16.writeSync(traceFd, `
+          fs17.writeSync(traceFd, `
 ]
 `);
-          fs16.closeSync(traceFd);
+          fs17.closeSync(traceFd);
           tracing = void 0;
           if (typeCatalog.length) {
             dumpTypes(typeCatalog);
@@ -35422,11 +35422,11 @@ ${lanes.join("\n")}
         function writeEvent(eventType, phase, name, args, extras, time3 = 1e3 * timestamp()) {
           if (mode === "server" && phase === "checkTypes") return;
           mark("beginTracing");
-          fs16.writeSync(traceFd, `,
+          fs17.writeSync(traceFd, `,
 {"pid":1,"tid":1,"ph":"${eventType}","cat":"${phase}","ts":${time3},"name":"${name}"`);
-          if (extras) fs16.writeSync(traceFd, `,${extras}`);
-          if (args) fs16.writeSync(traceFd, `,"args":${JSON.stringify(args)}`);
-          fs16.writeSync(traceFd, `}`);
+          if (extras) fs17.writeSync(traceFd, `,${extras}`);
+          if (args) fs17.writeSync(traceFd, `,"args":${JSON.stringify(args)}`);
+          fs17.writeSync(traceFd, `}`);
           mark("endTracing");
           measure("Tracing", "beginTracing", "endTracing");
         }
@@ -35448,9 +35448,9 @@ ${lanes.join("\n")}
           var _a3, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s;
           mark("beginDumpTypes");
           const typesPath = legend[legend.length - 1].typesPath;
-          const typesFd = fs16.openSync(typesPath, "w");
+          const typesFd = fs17.openSync(typesPath, "w");
           const recursionIdentityMap = /* @__PURE__ */ new Map();
-          fs16.writeSync(typesFd, "[");
+          fs17.writeSync(typesFd, "[");
           const numTypes = types.length;
           for (let i = 0; i < numTypes; i++) {
             const type = types[i];
@@ -35546,13 +35546,13 @@ ${lanes.join("\n")}
               flags: Debug.formatTypeFlags(type.flags).split("|"),
               display
             };
-            fs16.writeSync(typesFd, JSON.stringify(descriptor));
+            fs17.writeSync(typesFd, JSON.stringify(descriptor));
             if (i < numTypes - 1) {
-              fs16.writeSync(typesFd, ",\n");
+              fs17.writeSync(typesFd, ",\n");
             }
           }
-          fs16.writeSync(typesFd, "]\n");
-          fs16.closeSync(typesFd);
+          fs17.writeSync(typesFd, "]\n");
+          fs17.closeSync(typesFd);
           mark("endDumpTypes");
           measure("Dump types", "beginDumpTypes", "endDumpTypes");
         }
@@ -35560,7 +35560,7 @@ ${lanes.join("\n")}
           if (!legendPath) {
             return;
           }
-          fs16.writeFileSync(legendPath, JSON.stringify(legend));
+          fs17.writeFileSync(legendPath, JSON.stringify(legend));
         }
         tracingEnabled2.dumpLegend = dumpLegend;
       })(tracingEnabled || (tracingEnabled = {}));
@@ -244613,8 +244613,8 @@ var require_utils3 = __commonJS({
     exports2.array = array2;
     var errno = require_errno();
     exports2.errno = errno;
-    var fs16 = require_fs();
-    exports2.fs = fs16;
+    var fs17 = require_fs();
+    exports2.fs = fs17;
     var path19 = require_path();
     exports2.path = path19;
     var pattern = require_pattern();
@@ -244798,12 +244798,12 @@ var require_fs2 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.createFileSystemAdapter = exports2.FILE_SYSTEM_ADAPTER = void 0;
-    var fs16 = require("fs");
+    var fs17 = require("fs");
     exports2.FILE_SYSTEM_ADAPTER = {
-      lstat: fs16.lstat,
-      stat: fs16.stat,
-      lstatSync: fs16.lstatSync,
-      statSync: fs16.statSync
+      lstat: fs17.lstat,
+      stat: fs17.stat,
+      lstatSync: fs17.lstatSync,
+      statSync: fs17.statSync
     };
     function createFileSystemAdapter(fsMethods) {
       if (fsMethods === void 0) {
@@ -244820,12 +244820,12 @@ var require_settings = __commonJS({
   "../../node_modules/.pnpm/@nodelib+fs.stat@2.0.5/node_modules/@nodelib/fs.stat/out/settings.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    var fs16 = require_fs2();
+    var fs17 = require_fs2();
     var Settings = class {
       constructor(_options = {}) {
         this._options = _options;
         this.followSymbolicLink = this._getValue(this._options.followSymbolicLink, true);
-        this.fs = fs16.createFileSystemAdapter(this._options.fs);
+        this.fs = fs17.createFileSystemAdapter(this._options.fs);
         this.markSymbolicLink = this._getValue(this._options.markSymbolicLink, false);
         this.throwErrorOnBrokenSymbolicLink = this._getValue(this._options.throwErrorOnBrokenSymbolicLink, true);
       }
@@ -244982,8 +244982,8 @@ var require_utils4 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.fs = void 0;
-    var fs16 = require_fs3();
-    exports2.fs = fs16;
+    var fs17 = require_fs3();
+    exports2.fs = fs17;
   }
 });
 
@@ -245178,14 +245178,14 @@ var require_fs4 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.createFileSystemAdapter = exports2.FILE_SYSTEM_ADAPTER = void 0;
-    var fs16 = require("fs");
+    var fs17 = require("fs");
     exports2.FILE_SYSTEM_ADAPTER = {
-      lstat: fs16.lstat,
-      stat: fs16.stat,
-      lstatSync: fs16.lstatSync,
-      statSync: fs16.statSync,
-      readdir: fs16.readdir,
-      readdirSync: fs16.readdirSync
+      lstat: fs17.lstat,
+      stat: fs17.stat,
+      lstatSync: fs17.lstatSync,
+      statSync: fs17.statSync,
+      readdir: fs17.readdir,
+      readdirSync: fs17.readdirSync
     };
     function createFileSystemAdapter(fsMethods) {
       if (fsMethods === void 0) {
@@ -245204,12 +245204,12 @@ var require_settings2 = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     var path19 = require("path");
     var fsStat = require_out();
-    var fs16 = require_fs4();
+    var fs17 = require_fs4();
     var Settings = class {
       constructor(_options = {}) {
         this._options = _options;
         this.followSymbolicLinks = this._getValue(this._options.followSymbolicLinks, false);
-        this.fs = fs16.createFileSystemAdapter(this._options.fs);
+        this.fs = fs17.createFileSystemAdapter(this._options.fs);
         this.pathSegmentSeparator = this._getValue(this._options.pathSegmentSeparator, path19.sep);
         this.stats = this._getValue(this._options.stats, false);
         this.throwErrorOnBrokenSymbolicLink = this._getValue(this._options.throwErrorOnBrokenSymbolicLink, true);
@@ -246590,16 +246590,16 @@ var require_settings4 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.DEFAULT_FILE_SYSTEM_ADAPTER = void 0;
-    var fs16 = require("fs");
+    var fs17 = require("fs");
     var os6 = require("os");
     var CPU_COUNT = Math.max(os6.cpus().length, 1);
     exports2.DEFAULT_FILE_SYSTEM_ADAPTER = {
-      lstat: fs16.lstat,
-      lstatSync: fs16.lstatSync,
-      stat: fs16.stat,
-      statSync: fs16.statSync,
-      readdir: fs16.readdir,
-      readdirSync: fs16.readdirSync
+      lstat: fs17.lstat,
+      lstatSync: fs17.lstatSync,
+      stat: fs17.stat,
+      statSync: fs17.statSync,
+      readdir: fs17.readdir,
+      readdirSync: fs17.readdirSync
     };
     var Settings = class {
       constructor(_options = {}) {
@@ -279303,30 +279303,30 @@ type XMLHttpRequestResponseType = "" | "arraybuffer" | "blob" | "document" | "js
           yield path20;
       }
     }
-    var fs16 = runtime.fs;
+    var fs17 = runtime.fs;
     var RealFileSystemHost = class {
       async delete(path20) {
         try {
-          await fs16.delete(path20);
+          await fs17.delete(path20);
         } catch (err) {
           throw this.#getFileNotFoundErrorIfNecessary(err, path20);
         }
       }
       deleteSync(path20) {
         try {
-          fs16.deleteSync(path20);
+          fs17.deleteSync(path20);
         } catch (err) {
           throw this.#getFileNotFoundErrorIfNecessary(err, path20);
         }
       }
       readDirSync(dirPath) {
         try {
-          const entries = fs16.readDirSync(dirPath);
+          const entries = fs17.readDirSync(dirPath);
           for (const entry of entries) {
             entry.name = FileUtils.pathJoin(dirPath, entry.name);
             if (entry.isSymlink) {
               try {
-                const info = fs16.statSync(entry.name);
+                const info = fs17.statSync(entry.name);
                 if (info != null) {
                   entry.isDirectory = info.isDirectory();
                   entry.isFile = info.isFile();
@@ -279342,84 +279342,84 @@ type XMLHttpRequestResponseType = "" | "arraybuffer" | "blob" | "document" | "js
       }
       async readFile(filePath, encoding = "utf-8") {
         try {
-          return await fs16.readFile(filePath, encoding);
+          return await fs17.readFile(filePath, encoding);
         } catch (err) {
           throw this.#getFileNotFoundErrorIfNecessary(err, filePath);
         }
       }
       readFileSync(filePath, encoding = "utf-8") {
         try {
-          return fs16.readFileSync(filePath, encoding);
+          return fs17.readFileSync(filePath, encoding);
         } catch (err) {
           throw this.#getFileNotFoundErrorIfNecessary(err, filePath);
         }
       }
       async writeFile(filePath, fileText) {
-        return fs16.writeFile(filePath, fileText);
+        return fs17.writeFile(filePath, fileText);
       }
       writeFileSync(filePath, fileText) {
-        fs16.writeFileSync(filePath, fileText);
+        fs17.writeFileSync(filePath, fileText);
       }
       mkdir(dirPath) {
-        return fs16.mkdir(dirPath);
+        return fs17.mkdir(dirPath);
       }
       mkdirSync(dirPath) {
-        fs16.mkdirSync(dirPath);
+        fs17.mkdirSync(dirPath);
       }
       move(srcPath, destPath) {
-        return fs16.move(srcPath, destPath);
+        return fs17.move(srcPath, destPath);
       }
       moveSync(srcPath, destPath) {
-        fs16.moveSync(srcPath, destPath);
+        fs17.moveSync(srcPath, destPath);
       }
       copy(srcPath, destPath) {
-        return fs16.copy(srcPath, destPath);
+        return fs17.copy(srcPath, destPath);
       }
       copySync(srcPath, destPath) {
-        fs16.copySync(srcPath, destPath);
+        fs17.copySync(srcPath, destPath);
       }
       async fileExists(filePath) {
         try {
-          return (await fs16.stat(filePath))?.isFile() ?? false;
+          return (await fs17.stat(filePath))?.isFile() ?? false;
         } catch {
           return false;
         }
       }
       fileExistsSync(filePath) {
         try {
-          return fs16.statSync(filePath)?.isFile() ?? false;
+          return fs17.statSync(filePath)?.isFile() ?? false;
         } catch {
           return false;
         }
       }
       async directoryExists(dirPath) {
         try {
-          return (await fs16.stat(dirPath))?.isDirectory() ?? false;
+          return (await fs17.stat(dirPath))?.isDirectory() ?? false;
         } catch {
           return false;
         }
       }
       directoryExistsSync(dirPath) {
         try {
-          return fs16.statSync(dirPath)?.isDirectory() ?? false;
+          return fs17.statSync(dirPath)?.isDirectory() ?? false;
         } catch {
           return false;
         }
       }
       realpathSync(path20) {
-        return fs16.realpathSync(path20);
+        return fs17.realpathSync(path20);
       }
       getCurrentDirectory() {
-        return FileUtils.standardizeSlashes(fs16.getCurrentDirectory());
+        return FileUtils.standardizeSlashes(fs17.getCurrentDirectory());
       }
       glob(patterns) {
-        return fs16.glob(backSlashesToForward(patterns));
+        return fs17.glob(backSlashesToForward(patterns));
       }
       globSync(patterns) {
-        return fs16.globSync(backSlashesToForward(patterns));
+        return fs17.globSync(backSlashesToForward(patterns));
       }
       isCaseSensitive() {
-        return fs16.isCaseSensitive();
+        return fs17.isCaseSensitive();
       }
       #getDirectoryNotFoundErrorIfNecessary(err, path20) {
         return FileUtils.isNotExistsError(err) ? new exports2.errors.DirectoryNotFoundError(FileUtils.getStandardizedAbsolutePath(this, path20)) : err;
@@ -317461,12 +317461,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs16, exportName) {
+    function addFormats(ajv, list, fs17, exportName) {
       var _a3;
       var _b;
       (_a3 = (_b = ajv.opts.code).formats) !== null && _a3 !== void 0 ? _a3 : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs16[f]);
+        ajv.addFormat(f, fs17[f]);
     }
     module3.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -318403,6 +318403,27 @@ function jsonResponse(result) {
     ]
   };
 }
+async function catchUpWorkspaceIndex(workspaceId) {
+  const now = Date.now();
+  const current = catchupState.get(workspaceId);
+  if (current?.inFlight) {
+    await current.inFlight;
+    return;
+  }
+  if (current && now - current.lastRunAt < MCP_CATCHUP_INTERVAL_MS) {
+    return;
+  }
+  const inFlight = indexWorkspace({ workspaceId, mode: "incremental" }).then(() => void 0).catch((error2) => {
+    console.error(`OpenEZ MCP catch-up indexing failed: ${error2 instanceof Error ? error2.message : String(error2)}`);
+  }).finally(() => {
+    catchupState.set(workspaceId, { lastRunAt: Date.now() });
+  });
+  catchupState.set(workspaceId, { lastRunAt: current?.lastRunAt ?? 0, inFlight });
+  await inFlight;
+}
+async function catchUpReadWorkspaces(workspaces2) {
+  await Promise.all(workspaces2.map((workspace) => catchUpWorkspaceIndex(workspace.id)));
+}
 async function createAndStartMcpServer(options) {
   const resolver = createWorkspaceResolver(options);
   const server2 = new Server(
@@ -318514,6 +318535,7 @@ async function createAndStartMcpServer(options) {
       case "memory_query": {
         const input = memoryQuerySchema.parse(request.params.arguments ?? {});
         const workspaces2 = await resolver.resolveReadWorkspaces(input);
+        await catchUpReadWorkspaces(workspaces2);
         const results = await Promise.all(
           workspaces2.map(async (workspace) => ({
             workspace,
@@ -318548,6 +318570,7 @@ ${result.answerContext}`).join("\n\n");
       case "code_context": {
         const input = codeContextSchema.parse(request.params.arguments ?? {});
         const workspaces2 = await resolver.resolveReadWorkspaces(input);
+        await catchUpReadWorkspaces(workspaces2);
         const results = await Promise.all(
           workspaces2.map(async (workspace) => ({
             workspaceId: workspace.id,
@@ -318565,6 +318588,7 @@ ${result.answerContext}`).join("\n\n");
       case "graph_neighbors": {
         const input = graphNeighborsSchema.parse(request.params.arguments ?? {});
         const workspaces2 = await resolver.resolveReadWorkspaces(input);
+        await catchUpReadWorkspaces(workspaces2);
         const results = await Promise.all(
           workspaces2.map(async (workspace) => ({
             workspaceId: workspace.id,
@@ -318615,8 +318639,7 @@ async function autoIndexAndSync(searchRoot) {
     }
   }
   if (!workspace) {
-    workspace = await registry2.ensureWorkspace({ rootPath: resolvedRoot });
-    await writeLocalWorkspaceConfig(workspace);
+    return;
   }
   if (workspace.indexingStatus === "pending" || workspace.documentCount === 0) {
     try {
@@ -318624,6 +318647,9 @@ async function autoIndexAndSync(searchRoot) {
     } catch {
     }
   }
+  if (!WATCH_ENABLED) {
+    return;
+  }
   let debounceTimer = null;
   const watcher = esm_default.watch(resolvedRoot, {
     ignored: WATCH_IGNORE_PATTERNS,
@@ -318642,8 +318668,12 @@ async function autoIndexAndSync(searchRoot) {
   watcher.on("add", triggerReindex);
   watcher.on("change", triggerReindex);
   watcher.on("unlink", triggerReindex);
+  watcher.on("error", (error2) => {
+    console.error(`OpenEZ MCP auto-sync watcher disabled: ${error2 instanceof Error ? error2.message : String(error2)}`);
+    void watcher.close();
+  });
 }
-var import_node_fs8, import_node_path12, memoryQuerySchema, codeContextSchema, graphNeighborsSchema, memoryWriteSchema, indexWorkspaceSchema, WATCH_DEBOUNCE_MS, WATCH_IGNORE_PATTERNS;
+var import_node_fs8, import_node_path12, memoryQuerySchema, codeContextSchema, graphNeighborsSchema, memoryWriteSchema, indexWorkspaceSchema, MCP_CATCHUP_INTERVAL_MS, catchupState, WATCH_DEBOUNCE_MS, WATCH_ENABLED, WATCH_IGNORE_PATTERNS;
 var init_mcp_core = __esm({
   "../mcp/src/mcp-core.ts"() {
     "use strict";
@@ -318697,7 +318727,10 @@ var init_mcp_core = __esm({
       path: external_exports.string().optional(),
       mode: external_exports.enum(["incremental", "full"]).optional()
     });
+    MCP_CATCHUP_INTERVAL_MS = Number(process.env.OPENEZ_MCP_CATCHUP_INTERVAL_MS ?? 5e3);
+    catchupState = /* @__PURE__ */ new Map();
     WATCH_DEBOUNCE_MS = 2e3;
+    WATCH_ENABLED = ["1", "true", "yes"].includes((process.env.OPENEZ_MCP_WATCH ?? "").toLowerCase());
     WATCH_IGNORE_PATTERNS = [
       "**/node_modules/**",
       "**/.git/**",
@@ -318914,6 +318947,9 @@ function initializeWorkspaceSchema2(db) {
 }
 function getWorkspaceDb2(rootPath) {
   const normalized = normalizeRootPath2(rootPath);
+  if (normalized === "/" || normalized === "" || !import_node_fs9.default.existsSync(normalized)) {
+    throw new Error(`Workspace root path does not exist: "${rootPath}"`);
+  }
   const cached2 = workspaceDbs.get(normalized);
   if (cached2) {
     return cached2;
@@ -319175,9 +319211,9 @@ function mapWorkspace2(ws) {
 }
 function resolveWebDist() {
   const sourceDist = import_node_path14.default.resolve(__dirname, "..", "dist");
-  if ((0, import_node_fs11.existsSync)(import_node_path14.default.join(sourceDist, "index.html"))) return sourceDist;
+  if ((0, import_node_fs10.existsSync)(import_node_path14.default.join(sourceDist, "index.html"))) return sourceDist;
   const cliDist = import_node_path14.default.resolve(__dirname, "web");
-  if ((0, import_node_fs11.existsSync)(import_node_path14.default.join(cliDist, "index.html"))) return cliDist;
+  if ((0, import_node_fs10.existsSync)(import_node_path14.default.join(cliDist, "index.html"))) return cliDist;
   return null;
 }
 function createWebServer() {
@@ -319186,22 +319222,21 @@ function createWebServer() {
     app.use("/*", (0, import_serve_static.serveStatic)({ root: webDist, rewriteRequestPath: (p) => p }));
     app.get("*", (c) => {
       const indexPath = import_node_path14.default.join(webDist, "index.html");
-      const index2 = (0, import_node_fs11.readFileSync)(indexPath, "utf-8");
+      const index2 = (0, import_node_fs10.readFileSync)(indexPath, "utf-8");
       return c.html(index2);
     });
   }
   return app;
 }
-var import_hono, import_cors, import_serve_static, import_node_crypto3, import_node_fs10, import_node_fs11, import_node_path14, app, DEFAULT_INCLUDE_GLOBS, DEFAULT_EXCLUDE_GLOBS;
+var import_serve_static, import_hono, import_cors, import_node_crypto3, import_node_fs10, import_node_path14, app, DEFAULT_INCLUDE_GLOBS, DEFAULT_EXCLUDE_GLOBS;
 var init_server3 = __esm({
   "../web/src/server/index.ts"() {
     "use strict";
+    import_serve_static = require("@hono/node-server/serve-static");
     import_hono = require("hono");
     import_cors = require("hono/cors");
-    import_serve_static = require("@hono/node-server/serve-static");
     import_node_crypto3 = __toESM(require("crypto"), 1);
     import_node_fs10 = require("fs");
-    import_node_fs11 = require("fs");
     import_node_path14 = __toESM(require("path"), 1);
     init_sqlite2();
     init_src3();
@@ -319231,7 +319266,13 @@ var init_server3 = __esm({
     app.get("/api/dashboard", (c) => {
       try {
         const all = listRegistryWorkspaces();
-        const target = all[0];
+        const target = all.find((ws) => {
+          try {
+            return ws.rootPath && ws.rootPath !== "/" && (0, import_node_fs10.existsSync)(ws.rootPath);
+          } catch {
+            return false;
+          }
+        }) ?? all[0];
         if (!target) {
           return c.json({
             workspace: { id: "", name: "No workspace", root: "" },
@@ -319312,11 +319353,20 @@ var init_server3 = __esm({
       try {
         const dbPath = resolveRegistryDbPath2();
         const all = listRegistryWorkspaces();
-        const data = all.map((ws) => ({
-          ...mapWorkspace2(ws),
-          latestIndexRun: getLatestIndexRun(ws.rootPath),
-          latestGraphRun: getLatestGraphRun(ws.rootPath)
-        }));
+        const data = all.map((ws) => {
+          let latestIndexRun = null;
+          let latestGraphRun = null;
+          try {
+            latestIndexRun = getLatestIndexRun(ws.rootPath);
+            latestGraphRun = getLatestGraphRun(ws.rootPath);
+          } catch {
+          }
+          return {
+            ...mapWorkspace2(ws),
+            latestIndexRun,
+            latestGraphRun
+          };
+        });
         return c.json({ ok: true, data });
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -319577,6 +319627,14 @@ function resolveCliInvocation() {
     };
   }
   const repoRoot = import_node_path15.default.resolve(thisDir, "../../..");
+  const builtCliPath = import_node_path15.default.resolve(thisDir, "../dist/cli.cjs");
+  if (import_node_fs11.default.existsSync(builtCliPath)) {
+    return {
+      command: process.execPath,
+      args: [builtCliPath, "serve", "--mcp"],
+      repoRoot
+    };
+  }
   const tsxPath = import_node_path15.default.join(repoRoot, "node_modules", ".bin", "tsx");
   const cliPath = import_node_path15.default.resolve(thisDir, "./cli.ts");
   return {
@@ -319585,10 +319643,11 @@ function resolveCliInvocation() {
     repoRoot
   };
 }
-var import_node_path15, import_meta4;
+var import_node_fs11, import_node_path15, import_meta4;
 var init_resolve_cli = __esm({
   "src/resolve-cli.ts"() {
     "use strict";
+    import_node_fs11 = __toESM(require("fs"), 1);
     import_node_path15 = __toESM(require("path"), 1);
     import_meta4 = {};
   }
@@ -320714,7 +320773,7 @@ var {
 init_src();
 init_src4();
 var program2 = new Command();
-program2.name("openez").description("OpenEZ Graph - Local-first knowledge retrieval system").version("0.2.0");
+program2.name("openez").description("OpenEZ Graph - Local-first knowledge retrieval system").version("0.3.0");
 program2.command("init").description("Initialize a workspace at the given path and run initial index").argument("[path]", "path to the project directory", process.cwd()).option("--no-index", "skip initial indexing").action(async (targetPath, options) => {
   const resolvedPath = import_node_path19.default.resolve(targetPath);
   if (!import_node_fs15.default.existsSync(resolvedPath)) {
@@ -320758,6 +320817,7 @@ program2.command("index").description("Index files in a workspace").argument("[p
     });
     console.log(`Auto-registered workspace '${workspace.name}' (${workspace.id})`);
   }
+  await writeLocalWorkspaceConfig(workspace);
   const summary = await indexWorkspace({ workspaceId: workspace.id });
   console.log(JSON.stringify(summary, null, 2));
 });
@@ -320769,6 +320829,7 @@ program2.command("reindex").description("Full rebuild of a workspace index").arg
     console.error(`Error: no workspace registered at ${resolvedPath}. Run 'openez init' first.`);
     process.exit(1);
   }
+  await writeLocalWorkspaceConfig(workspace);
   const summary = await indexWorkspace({ workspaceId: workspace.id, mode: "full" });
   console.log(JSON.stringify(summary, null, 2));
 });
@@ -320782,8 +320843,10 @@ program2.command("watch").description("Watch files and re-index on changes").arg
     });
     console.log(`Auto-registered workspace '${workspace.name}' (${workspace.id})`);
   }
+  await writeLocalWorkspaceConfig(workspace);
+  const workspaceId = workspace.id;
   console.log(`Running initial index for ${resolvedPath}...`);
-  await indexWorkspace({ workspaceId: workspace.id });
+  await indexWorkspace({ workspaceId });
   const watcher = esm_default.watch(resolvedPath, {
     ignored: [
       "**/node_modules/**",
@@ -320798,14 +320861,39 @@ program2.command("watch").description("Watch files and re-index on changes").arg
     ignoreInitial: true,
     persistent: true
   });
-  const reindex = async () => {
-    console.log("Change detected, re-indexing...");
-    const summary = await indexWorkspace({ workspaceId: workspace.id });
-    console.log(JSON.stringify(summary, null, 2));
+  let debounceTimer;
+  let isIndexing = false;
+  let hasPendingChange = false;
+  const runReindex = async () => {
+    if (isIndexing) {
+      hasPendingChange = true;
+      return;
+    }
+    isIndexing = true;
+    do {
+      hasPendingChange = false;
+      console.log("Change detected, re-indexing...");
+      try {
+        const summary = await indexWorkspace({ workspaceId });
+        console.log(JSON.stringify(summary, null, 2));
+      } catch (error2) {
+        console.error("Re-index failed:");
+        console.error(error2);
+      }
+    } while (hasPendingChange);
+    isIndexing = false;
+  };
+  const scheduleReindex = () => {
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(() => {
+      void runReindex();
+    }, 250);
   };
-  watcher.on("add", reindex);
-  watcher.on("change", reindex);
-  watcher.on("unlink", reindex);
+  watcher.on("add", scheduleReindex);
+  watcher.on("change", scheduleReindex);
+  watcher.on("unlink", scheduleReindex);
   console.log(`Watching ${resolvedPath} for changes...`);
 });
 program2.command("serve").description("Start the web dashboard or MCP server").option("--mcp", "run as MCP server instead of web").option("--web", "start the web dashboard API server").option("-p, --path <path>", "workspace path").option("--port <port>", "API server port (default: 11368)").action(async (options) => {

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@openez-graph/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
+  "description": "Local-first code intelligence engine — index, query, and graph your codebase with zero config. SQLite-only, MCP-first.",
+  "license": "MIT",
+  "author": "Asta Nguyen",
+  "homepage": "https://github.com/asta-nguyen/openez-graph",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/asta-nguyen/openez-graph.git",
+    "directory": "apps/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/asta-nguyen/openez-graph/issues"
+  },
+  "keywords": [
+    "code-intelligence",
+    "code-graph",
+    "mcp",
+    "model-context-protocol",
+    "code-indexing",
+    "codebase",
+    "retrieval",
+    "sqlite",
+    "local-first",
+    "developer-tools",
+    "ai-coding",
+    "claude-code",
+    "codex"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "type": "module",
   "main": "./src/cli.ts",
   "types": "./src/cli.ts",
@@ -9,7 +39,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "main": "./dist/cli.cjs",