codesearch-mcp 0.0.17-alpha.1 → 0.0.18-alpha

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [Unreleased]
+
+## [0.0.18-alpha] - 2026-07-04
+
+### Added
+
+- **Web dashboard (`rag-web`)** — a local browser UI at `http://127.0.0.1:4319` (`--port` to change), bound to `127.0.0.1` only, no auth (single-user local tool). Three tabs: a **schema-driven config editor** (form generated from the config JSON Schema; shows the applied default for any unset key, a strict dropdown for the embedding model, and comboboxes suggesting the user's installed Ollama models for the translate/reranker models), a **project overview**, and the **interactive dependency graph** (the same page as `project-graph.html`, embedded via iframe — filters, legend, and project toggles included). The DB password never reaches the browser (masked as `********`, preserved on save). Requires a valid `config.json`; a failed DB/Ollama connection is non-fatal (config editing still works). Full reference: `docs/web-dashboard.md`.
+- **Config JSON Schema + `rag-config edit`** — `config.json` now gets a generated `config.schema.json` sibling, referenced via `"$schema"`, so schema-aware editors (VS Code, JetBrains) provide key autocomplete, type hints, and inline validation. `rag-config edit` opens the config in `$VISUAL` / `$EDITOR` (falls back to `nano` / `notepad`) and re-validates on save.
+- **Nx monorepo support** — when `workspaceRoot` is an Nx workspace (detected by `nx.json`), projects under `apps/`, `libs/`, and `packages/` are discovered as separate indexed projects instead of a single flat scan. Cross-project imports (`@scope/lib`) resolve through the workspace-wide `tsconfig.base.json` path aliases, so `get_dependencies` / `get_dependents` see edges across projects. Non-Nx (flat) workspaces are unaffected.
+- **`IMonorepoResolver` interface + `NxMonorepoResolver`** — resolver abstraction for monorepo tooling. `NxMonorepoResolver` detects `nx.json`, discovers projects via `workspace.json` / `angular.json` or an `apps/`/`libs/`/`packages/` scan for `project.json` / `package.json`, and resolves the root tsconfig (`tsconfig.base.json`, falling back to `tsconfig.json`).
+- **`MonorepoAwareDiscoveryService`** — implements `IProjectDiscovery` and is wired as the default discovery in the container. Uses the resolver when a monorepo is detected; otherwise delegates to `ProjectDiscoveryService` (flat `package.json` scan). Exposes `analyzeWorkspace()` for full workspace metadata.
+- **`DiscoveredProject` metadata** — discovery now carries optional `packageName` (npm scope + name), `type` (`app` | `lib`), and `rootTsConfigPath` per project.
+- **Nested Nx monorepo under a flat workspace** — when `workspaceRoot` is a flat directory but one of its top-level subdirectories is itself an Nx repo, that repo is discovered as a single selectable unit whose sub-projects (`<repo>/<project>`, e.g. `micros-learning/account`) are expanded and indexed individually. `DiscoveredProject` gains an optional `children` field; the exported `toLeafProjects()` helper expands units into their leaf projects and is shared by `IndexCommand` (indexing loop) and `SearcherService` (name → path resolution). Each sub-project carries the repo's `tsconfig.base.json` as `rootTsConfigPath` for cross-project alias resolution.
+- **Root-level Nx libs via `tsconfig.base.json` paths** — `NxMonorepoResolver` now also discovers projects referenced only through `compilerOptions.paths` aliases (e.g. `contracts/`, `interfaces/` living at the repo root), which the `apps/`/`libs/`/`packages/` scan misses. Only targets that resolve to a real project (with `project.json` / `package.json`) are added; the `tsconfig` reader tolerates JSONC (comments, trailing commas).
+- **Tabbed project graph** — `project-graph.html` and the dashboard's `/graph` now have inner tabs: a **Workspace** tab (flat projects + each nested Nx repo collapsed to one node, double-click to open) and **one tab per Nx repo** showing its sub-projects with real import edges between them. Intra-repo edges come from `SearcherService.getProjectEdges()`, which aggregates `code_dependency` (file → file) into project → project links (most-specific owner wins). `getProjectEdges` is exposed on `ISearcher`.
+
+### Changed
+
+- **Single source of truth for config defaults** — built-in defaults now live once in `CONFIG_DEFAULTS` (`config-store.ts`); `config.ts` references them in its schema `.default(...)` calls, so the runtime default and the value the dashboard shows for an unset key cannot diverge. No behavior change.
+- **`analyzeProject` / `scanAndIndex` accept `rootTsConfigPath`** — for monorepo projects the AST parser loads the workspace-wide tsconfig (`tsconfig.base.json`) so ts-morph resolves cross-project path aliases; flat-workspace projects continue to use their local `tsconfig.json`.
+- **`workspace.json` parsing hardened** — a project entry missing a valid `root` is skipped with a warning instead of aborting discovery of the remaining projects in that file.
+- **Nx project discovery deduplicated across strategies** — `workspace.json` / `angular.json`, the directory scan, `tsconfig` paths, and the root-level fallback are now merged and deduped by absolute project path, so a project surfaced by more than one strategy is reported once.
+- **`SearcherService` resolves project names to real roots** — takes the discovery service and builds a lazily-cached `name → filesystem root` map, so nested-monorepo names (`repo/app`) map to their true path (`repo/apps/app`) instead of a naïve `workspaceRoot/name` join. The cache rebuilds on a miss, so projects added or renamed while a long-running `rag-mcp` / `rag-web` server is up are picked up without a restart. `listProjects`, `grepSymbol`, `find_symbol` grep fallback, and `list_files` use it.
+- **Project graph build is non-fatal in `rag-index`** — a failure while computing import edges or writing `project-graph.html` after a successful index is now caught and logged instead of failing the whole run.
+
 ## [0.0.17-alpha] - 2026-05-13
 
 ### Added

package/README.md

@@ -54,6 +54,14 @@ rag-index --reindex         # force re-embed all files (use after model change)
 rag-index --select --reindex
 ```
 
+## Monorepo support
+
+If `workspaceRoot` is an [Nx](https://nx.dev) workspace (detected by `nx.json`), `rag-index` discovers each project under `apps/`, `libs/`, and `packages/` as a **separate indexed project** rather than scanning the workspace as one blob. Cross-project imports like `@scope/shared` resolve through the workspace `tsconfig.base.json` path aliases, so `get_dependencies` / `get_dependents` report edges **across** projects.
+
+**Nested Nx repos.** `workspaceRoot` may also be a plain directory that *contains* an Nx repo in one of its immediate subdirectories (alongside ordinary projects). That nested repo is detected and expanded into its own projects, named `<repo>/<project>` (e.g. `micros-learning/account`), each resolved with the repo's own `tsconfig.base.json`. In the project selector the whole Nx repo appears as **one** selectable entry (so `.ragprojects` stores just `micros-learning`); selecting it indexes all its sub-projects. Ordinary sibling directories are unaffected.
+
+No configuration needed — detection is automatic. Plain (non-Nx) workspaces keep the original behavior: each immediate subdirectory with a `package.json` is one project.
+
 ## Register with Claude Code
 
 ```bash
@@ -62,6 +70,18 @@ claude mcp add codesearch-mcp -s user -- rag-mcp
 
 Then ask Claude anything about your code — it will use the tools below automatically.
 
+## Web dashboard
+
+```bash
+rag-web                 # http://127.0.0.1:4319  (--port to change)
+```
+
+A local web UI (bound to `127.0.0.1` only) with a schema-driven config editor,
+an overview of indexed projects, and the interactive dependency graph. The
+config form shows the applied default for any unset key and offers dropdowns for
+model fields (the embedding model is restricted to dimension-compatible models).
+See [docs/web-dashboard.md](docs/web-dashboard.md) for the full reference.
+
 ## MCP Tools
 
 | Tool | Description |

package/dist/app.js

@@ -42,6 +42,7 @@ const IndexCommand_1 = require("./src/commands/IndexCommand");
 const McpCommand_1 = require("./src/commands/McpCommand");
 const BackfillCommand_1 = require("./src/commands/BackfillCommand");
 const ConfigCommand_1 = require("./src/commands/ConfigCommand");
+const WebCommand_1 = require("./src/commands/WebCommand");
 const setup_1 = require("./src/setup");
 async function main() {
     const argv1 = path.basename(process.argv[1] ?? '');
@@ -49,10 +50,11 @@ async function main() {
     const isMcp = argv1 === 'rag-mcp' || process.argv[2] === 'mcp' || process.argv[2] === 'rag-mcp';
     const isSetup = argv1 === 'rag-setup' || process.argv[2] === 'setup' || process.argv[2] === 'rag-setup';
     const isConfig = argv1 === 'rag-config' || process.argv[2] === 'config' || process.argv[2] === 'rag-config';
+    const isWeb = argv1 === 'rag-web' || process.argv[2] === 'web' || process.argv[2] === 'rag-web';
     const isBackfill = process.argv[2] === 'backfill' ||
         (process.argv[2] === 'rag-index' && process.argv[3] === 'backfill');
-    const mode = isBackfill ? 'backfill' : isIndex ? 'index' : isMcp ? 'mcp' : isSetup ? 'setup' : isConfig ? 'config' : (process.argv[2] ?? '');
-    const isBinary = ['rag-index', 'rag-mcp', 'rag-setup', 'rag-config'].includes(argv1);
+    const mode = isBackfill ? 'backfill' : isIndex ? 'index' : isMcp ? 'mcp' : isSetup ? 'setup' : isConfig ? 'config' : isWeb ? 'web' : (process.argv[2] ?? '');
+    const isBinary = ['rag-index', 'rag-mcp', 'rag-setup', 'rag-config', 'rag-web'].includes(argv1);
     if (process.argv.includes('--help') || process.argv.includes('-h')) {
         (0, help_1.printHelp)(isBinary ? argv1 : mode);
         process.exit(0);
@@ -75,6 +77,24 @@ async function main() {
             process.exit(1);
         }
     }
+    else if (mode === 'web') {
+        for (let i = 0; i < effectiveArgs.length; i++) {
+            if (effectiveArgs[i] === '--port') {
+                const raw = effectiveArgs[i + 1];
+                const n = Number(raw);
+                if (!raw || !Number.isInteger(n) || n < 1 || n > 65535) {
+                    console.error(`Invalid --port value: ${raw ?? '(missing)'}\n`);
+                    (0, help_1.printHelp)(isBinary ? argv1 : 'rag-web');
+                    process.exit(1);
+                }
+                i++;
+                continue; // skip its (validated) value
+            }
+            console.error(`Unexpected argument: ${effectiveArgs[i]}\n`);
+            (0, help_1.printHelp)(isBinary ? argv1 : 'rag-web');
+            process.exit(1);
+        }
+    }
     else if (mode === 'backfill') {
         const knownBackfillFlags = new Set(['--calls']);
         const backfillIdx = process.argv.indexOf('backfill');
@@ -95,7 +115,7 @@ async function main() {
         process.exit(0);
     }
     // All other modes require a valid config.json
-    const loggerName = mode === 'index' || mode === 'backfill' ? 'indexer' : mode === 'mcp' ? 'mcp' : undefined;
+    const loggerName = mode === 'index' || mode === 'backfill' ? 'indexer' : mode === 'mcp' ? 'mcp' : mode === 'web' ? 'web' : undefined;
     let container;
     try {
         container = (0, container_1.createContainer)(loggerName);
@@ -114,20 +134,24 @@ async function main() {
         console.error(`workspaceRoot is not configured. ${hint}`);
         process.exit(1);
     }
-    const commands = {
-        index: new IndexCommand_1.IndexCommand(container, argv1),
-        mcp: new McpCommand_1.McpCommand(container),
-        backfill: new BackfillCommand_1.BackfillCommand(container),
+    // Construct only the selected command — building every command eagerly would
+    // run each constructor's arg parsing (e.g. WebCommand's --port) for modes that
+    // never use it.
+    const factories = {
+        index: () => new IndexCommand_1.IndexCommand(container, argv1),
+        mcp: () => new McpCommand_1.McpCommand(container),
+        backfill: () => new BackfillCommand_1.BackfillCommand(container),
+        web: () => new WebCommand_1.WebCommand(container, effectiveArgs),
     };
-    const cmd = commands[mode];
-    if (!cmd) {
+    const factory = factories[mode];
+    if (!factory) {
         const hasUnknownArg = mode !== '';
         if (hasUnknownArg)
             console.error(`Unknown command: ${mode}\n`);
         (0, help_1.printHelp)('default');
         process.exit(hasUnknownArg ? 1 : 0);
     }
-    await cmd.execute();
+    await factory().execute();
     await container.db.destroy();
     process.exit(0);
 }

package/dist/src/commands/ConfigCommand.d.ts

@@ -8,5 +8,6 @@ export declare class ConfigCommand implements ICommand {
     private get;
     private set;
     private reset;
+    private edit;
 }
 export { ALL_KEYS };

package/dist/src/commands/ConfigCommand.js

@@ -1,6 +1,41 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ALL_KEYS = exports.ConfigCommand = void 0;
+const fs = __importStar(require("fs"));
+const child_process_1 = require("child_process");
 const config_store_1 = require("../config-store");
 Object.defineProperty(exports, "ALL_KEYS", { enumerable: true, get: function () { return config_store_1.ALL_KEYS; } });
 const help_1 = require("../help");
@@ -16,6 +51,7 @@ class ConfigCommand {
             case 'get': return this.get(key);
             case 'set': return this.set(key, value);
             case 'reset': return this.reset(key);
+            case 'edit': return this.edit();
             default:
                 if (sub)
                     console.error(`Unknown subcommand: ${sub}\n`);
@@ -29,7 +65,7 @@ class ConfigCommand {
             cfg = (0, config_store_1.readConfigJson)();
         }
         catch (e) {
-            console.error(e.message);
+            console.error(e instanceof Error ? e.message : String(e));
             process.exit(1);
         }
         if (!cfg) {
@@ -52,7 +88,7 @@ class ConfigCommand {
             cfg = (0, config_store_1.readConfigJson)();
         }
         catch (e) {
-            console.error(e.message);
+            console.error(e instanceof Error ? e.message : String(e));
             process.exit(1);
         }
         if (!cfg) {
@@ -74,7 +110,7 @@ class ConfigCommand {
             console.log(`${key} = ${value}`);
         }
         catch (e) {
-            console.error(e.message);
+            console.error(e instanceof Error ? e.message : String(e));
             process.exit(1);
         }
     }
@@ -90,7 +126,51 @@ class ConfigCommand {
             console.log(`${key} reset to default`);
         }
         catch (e) {
-            console.error(e.message);
+            console.error(e instanceof Error ? e.message : String(e));
+            process.exit(1);
+        }
+    }
+    edit() {
+        // Ensure config + schema exist so the editor has something to open and
+        // resolve the schema against.
+        try {
+            if (!fs.existsSync(config_store_1.CONFIG_FILE)) {
+                (0, config_store_1.writeConfigJson)({});
+            }
+            else {
+                (0, config_store_1.writeSchemaFile)();
+                // Migrate existing configs: re-add the "$schema" reference if absent
+                // (rewrite through writeConfigJson) so editors bind to the schema.
+                // Skip silently if the file is currently invalid — the user will fix
+                // it in the editor and validation runs on save.
+                try {
+                    const cfg = (0, config_store_1.readConfigJson)();
+                    if (cfg)
+                        (0, config_store_1.writeConfigJson)(cfg);
+                }
+                catch { /* invalid file — leave as-is for the user to edit */ }
+            }
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            process.exit(1);
+        }
+        const editor = process.env.VISUAL ||
+            process.env.EDITOR ||
+            (process.platform === 'win32' ? 'notepad' : 'nano');
+        const res = (0, child_process_1.spawnSync)(editor, [config_store_1.CONFIG_FILE], { stdio: 'inherit' });
+        if (res.error) {
+            console.error(`Cannot launch editor "${editor}": ${res.error.message}`);
+            console.error('Set $EDITOR or edit the file directly: ' + config_store_1.CONFIG_FILE);
+            process.exit(1);
+        }
+        // Validate what the user saved; readConfigJson throws with a helpful message.
+        try {
+            (0, config_store_1.readConfigJson)();
+            console.log('Config OK');
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
             process.exit(1);
         }
     }

package/dist/src/commands/IndexCommand.js

@@ -4,6 +4,7 @@ exports.IndexCommand = void 0;
 const interrupt_1 = require("../interrupt");
 const project_selector_1 = require("../project-selector");
 const graph_1 = require("../graph");
+const MonorepoAwareDiscoveryService_1 = require("../services/MonorepoAwareDiscoveryService");
 const file_utils_1 = require("../file-utils");
 class IndexCommand {
     container;
@@ -13,7 +14,7 @@ class IndexCommand {
         this.argv1 = argv1;
     }
     async execute() {
-        const { db, indexer, config } = this.container;
+        const { db, indexer, searcher, config, discovery } = this.container;
         const args = process.argv.slice(this.argv1 === 'rag-index' ? 2 : 3);
         const force = args.includes('--reindex');
         const forceSelect = args.includes('--select');
@@ -21,10 +22,13 @@ class IndexCommand {
         const controller = new AbortController();
         const teardown = (0, interrupt_1.setupInterrupt)(controller);
         try {
-            const discovered = indexer.discoverProjects(config.workspaceRoot);
-            const projects = await new project_selector_1.ProjectSelector(config.workspaceRoot).select(discovered, forceSelect);
-            if (projects.length === 0)
+            const discovered = discovery.discover(config.workspaceRoot);
+            const selected = await new project_selector_1.ProjectSelector(config.workspaceRoot).select(discovered, forceSelect);
+            if (selected.length === 0)
                 return;
+            // Expand any selected nested-monorepo unit (e.g. an Nx repo) into its
+            // sub-projects; ordinary projects pass through unchanged.
+            const projects = (0, MonorepoAwareDiscoveryService_1.toLeafProjects)(selected);
             const filesPerProject = projects.map(p => (0, file_utils_1.collectFiles)(p.path, (0, file_utils_1.loadIgnore)(p.path), p.path));
             const totalFiles = filesPerProject.reduce((sum, f) => sum + f.length, 0);
             console.log(`\n${projects.length} projects — ${totalFiles} files total`);
@@ -34,7 +38,7 @@ class IndexCommand {
             for (let i = 0; i < projects.length; i++) {
                 if (controller.signal.aborted)
                     break;
-                const stats = await indexer.scanAndIndex(projects[i].path, projects[i].name, force, controller.signal, filesPerProject[i]);
+                const stats = await indexer.scanAndIndex(projects[i].path, projects[i].name, force, controller.signal, filesPerProject[i], { rootTsConfigPath: projects[i].rootTsConfigPath ?? undefined });
                 allStats.push(stats);
                 const remaining = projects.length - allStats.length;
                 if (remaining > 0 && !controller.signal.aborted) {
@@ -45,8 +49,19 @@ class IndexCommand {
             if (controller.signal.aborted)
                 console.log('\nIndexing interrupted.');
             this.printSummary(allStats);
-            if (!controller.signal.aborted)
-                (0, graph_1.generateProjectGraph)(projects, config.workspaceRoot);
+            if (!controller.signal.aborted) {
+                // The graph is a post-index nicety — a failure here (DB dropped after a
+                // long run, unreadable dir) must not fail the whole run: indexing already
+                // succeeded and the summary is printed.
+                try {
+                    // Real import edges (code_dependency, just written) → intra-repo graph links.
+                    const projectEdges = await searcher.getProjectEdges();
+                    (0, graph_1.generateProjectGraph)(projects, projectEdges, config.workspaceRoot);
+                }
+                catch (err) {
+                    console.error(`  ⚠ Could not build project graph: ${err.message}`);
+                }
+            }
         }
         finally {
             teardown();

package/dist/src/commands/McpCommand.js

@@ -13,14 +13,15 @@ class McpCommand {
             await db.initDb();
         }
         catch (err) {
-            startupError = err;
-            logger.error('McpCommand: database connection failed', { reason: err.message });
+            startupError = err instanceof Error ? err : new Error(String(err));
+            logger.error('McpCommand: database connection failed', { reason: startupError.message });
         }
         try {
             await mcp.start(startupError);
         }
         catch (err) {
-            logger.error('McpCommand: MCP server failed to start', { reason: err.message });
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.error('McpCommand: MCP server failed to start', { reason });
             return;
         }
         // server.connect() resolves immediately after setup; keep the process alive

package/dist/src/commands/WebCommand.d.ts

@@ -0,0 +1,8 @@
+import type { Container } from '../container';
+import type { ICommand } from './ICommand';
+export declare class WebCommand implements ICommand {
+    private container;
+    private readonly port;
+    constructor(container: Container, args?: string[]);
+    execute(): Promise<void>;
+}

package/dist/src/commands/WebCommand.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebCommand = void 0;
+const WebServerService_1 = require("../services/WebServerService");
+const DEFAULT_PORT = 4319;
+class WebCommand {
+    container;
+    port;
+    constructor(container, args = []) {
+        this.container = container;
+        this.port = parsePort(args) ?? DEFAULT_PORT;
+    }
+    async execute() {
+        const { db, searcher, config, logger, embedder } = this.container;
+        try {
+            await db.initDb();
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.error('WebCommand: database connection failed', { reason });
+            console.error(`Database connection failed: ${reason}`);
+            // Continue: config editing still works; project/graph tabs will error in-page.
+        }
+        const server = new WebServerService_1.WebServer(searcher, config, logger, embedder);
+        const host = '127.0.0.1';
+        try {
+            await server.start(this.port, host);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.error('WebCommand: server failed to start', { reason });
+            console.error(`Failed to start web server on ${host}:${this.port}: ${reason}`);
+            return;
+        }
+        console.log(`RAG dashboard: http://${host}:${this.port}  (Ctrl+C to stop)`);
+        // Keep execute() pending until a shutdown signal, otherwise app.ts tears
+        // down the DB and exits immediately (mirrors McpCommand's keep-alive).
+        await new Promise(resolve => {
+            const shutdown = () => { void server.stop().then(resolve); };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+        });
+    }
+}
+exports.WebCommand = WebCommand;
+function parsePort(args) {
+    const i = args.indexOf('--port');
+    if (i === -1)
+        return undefined;
+    const raw = args[i + 1];
+    const n = Number(raw);
+    if (!raw || !Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new Error(`Invalid --port value: ${raw ?? '(missing)'}`);
+    }
+    return n;
+}

package/dist/src/config-store.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 export declare const CONFIG_DIR: string;
 export declare const CONFIG_FILE: string;
+export declare const SCHEMA_FILE: string;
 declare const jsonSchema: z.ZodObject<{
     db: z.ZodOptional<z.ZodObject<{
         host: z.ZodOptional<z.ZodString>;
@@ -45,8 +46,50 @@ declare const jsonSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type JsonConfig = z.infer<typeof jsonSchema>;
 export declare const ALL_KEYS: string[];
+/**
+ * Single source of truth for built-in defaults, keyed by raw config.json dotted
+ * key. Consumed both by the web dashboard (`GET /api/defaults`) and by
+ * `resolvedSchema` in `src/config.ts`, whose `.default(...)` calls reference
+ * these values — so the runtime default and the dashboard-displayed default
+ * cannot diverge. `as const` keeps the literal types so those `.default()`
+ * lookups stay type-safe. Keys omitted here have no static default (required
+ * fields like db.host, or values derived at runtime like db.name → rag_<user>
+ * and reranker.url → ${ollama.host}/api/rerank).
+ */
+export declare const CONFIG_DEFAULTS: {
+    readonly 'db.port': 5433;
+    readonly 'ollama.host': "http://localhost:11434";
+    readonly 'ollama.model': string;
+    readonly 'indexing.chunkSize': 1500;
+    readonly 'indexing.chunkOverlap': 200;
+    readonly 'indexing.embedBatchSize': 5;
+    readonly 'indexing.astBatchSize': 3000;
+    readonly 'search.similarityThreshold': 0.6;
+    readonly 'search.defaultLimit': 5;
+    readonly 'search.maxLimit': 20;
+    readonly 'search.autoTranslate': false;
+    readonly 'search.translateModel': "llama3.2";
+    readonly 'reranker.enabled': false;
+    readonly 'reranker.model': "";
+    readonly 'reranker.overfetch': 3;
+    readonly 'logging.level': "error";
+};
 export declare function readConfigJson(): JsonConfig | null;
+/**
+ * Validate a parsed config object against the Zod schema. Unknown keys (e.g.
+ * the "$schema" editor reference) are stripped. Throws with a caller-friendly
+ * message on validation failure. Pure — no file I/O.
+ */
+export declare function parseConfig(raw: unknown, source?: string): JsonConfig;
+/** Build the JSON Schema object generated from the Zod config schema. Pure. */
+export declare function buildJsonSchema(): Record<string, unknown>;
 export declare function writeConfigJson(data: JsonConfig): void;
+/**
+ * Generate a JSON Schema from the Zod config schema and write it next to
+ * config.json. Editors resolve it via the "$schema" reference and provide
+ * key autocomplete, type hints, and inline validation while editing.
+ */
+export declare function writeSchemaFile(): void;
 export declare function getNestedValue(cfg: JsonConfig, key: string): unknown;
 export declare function setNestedValue(cfg: JsonConfig, key: string, raw: string): JsonConfig;
 export declare function deleteNestedValue(cfg: JsonConfig, key: string): JsonConfig;