@coreyuan/vector-mind 1.0.20 → 1.0.30

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import path from "node:path";
 import fs from "node:fs";
+import * as readline from "node:readline";
 import crypto from "node:crypto";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
@@ -11,8 +12,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { BUILTIN_CONVENTIONS } from "./builtin-conventions.js";
+import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.19";
+const SERVER_VERSION = "1.0.30";
 const rootFromEnv = process.env.VECTORMIND_ROOT?.trim() ?? "";
 const prettyJsonOutput = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_PRETTY_JSON ?? "").trim().toLowerCase());
 const debugLogEnabled = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_DEBUG_LOG ?? "").trim().toLowerCase());
@@ -61,6 +64,28 @@ const PENDING_PRUNE_EVERY = (() => {
         return 500;
     return n;
 })();
+function getCodexHomeDir() {
+    const raw = process.env.CODEX_HOME?.trim();
+    if (raw)
+        return path.resolve(raw);
+    return path.join(os.homedir(), ".codex");
+}
+function getAgentsHomeDir() {
+    const raw = process.env.AGENTS_HOME?.trim();
+    if (raw)
+        return path.resolve(raw);
+    return path.join(os.homedir(), ".agents");
+}
+function getAllowedCodexTextRoots() {
+    const codexHome = getCodexHomeDir();
+    const agentsHome = getAgentsHomeDir();
+    return Array.from(new Set([
+        path.join(codexHome, "skills"),
+        path.join(codexHome, "prompts"),
+        path.join(codexHome, "rules"),
+        path.join(agentsHome, "skills"),
+    ].map((p) => path.resolve(p))));
+}
 const INDEX_MAX_CODE_BYTES = (() => {
     const raw = process.env.VECTORMIND_INDEX_MAX_CODE_BYTES?.trim();
     if (!raw)
@@ -227,8 +252,18 @@ function summarizeActivityEvent(e) {
             return `pending_list returned=${String(d.returned ?? "")} total=${String(d.total ?? "")}`;
         case "semantic_search":
             return `semantic_search mode=${String(d.mode ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
+        case "grep":
+            return `grep q=${String(d.query ?? "")} matches=${String(d.matches ?? "")} truncated=${String(d.truncated ?? "")}`;
         case "query_codebase":
             return `query_codebase q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
+        case "read_file_lines":
+            return `read_file_lines file=${String(d.file_path ?? "")} returned=${String(d.returned ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "read_file_text":
+            return `read_file_text file=${String(d.file_path ?? "")} returned=${String(d.returned_chars ?? "")}/${String(d.total_chars ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "list_project_files":
+            return `list_project_files path=${String(d.path ?? "")} returned=${String(d.returned ?? "")} scanned=${String(d.scanned ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "read_codex_text_file":
+            return `read_codex_text_file file=${String(d.file_path ?? "")} returned=${String(d.returned_chars ?? "")}/${String(d.total_chars ?? "")} truncated=${String(d.truncated ?? "")}`;
         case "start_requirement":
             return `start_requirement #${String(d.req_id ?? "")} ${String(d.title ?? "")}`;
         case "sync_change_intent":
@@ -1133,6 +1168,65 @@ const SyncChangeIntentArgsSchema = ProjectRootArgSchema.merge(z.object({
 const QueryCodebaseArgsSchema = ProjectRootArgSchema.merge(z.object({
     query: z.string().min(1),
 }));
+const GrepArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Pattern to search for. Defaults to regex mode for parity with tools like ripgrep.
+    query: z.string().min(1),
+    mode: z.enum(["regex", "literal"]).optional().default("regex"),
+    // If case_sensitive is omitted and smart_case=true, uppercase => case-sensitive, otherwise case-insensitive.
+    smart_case: z.boolean().optional().default(true),
+    case_sensitive: z.boolean().optional(),
+    // Optional hint used to narrow candidates quickly when mode=regex and the pattern has few literals.
+    literal_hint: z.string().optional().default(""),
+    // Defaults to code/doc chunks; can be widened if needed.
+    kinds: z.array(z.string().min(1)).optional(),
+    include_paths: z.array(z.string().min(1)).optional(),
+    exclude_paths: z.array(z.string().min(1)).optional(),
+    max_results: z.number().int().min(1).max(5000).optional().default(200),
+    max_candidates: z.number().int().min(1).max(50_000).optional(),
+}));
+const ReadFileLinesArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative to project_root, or an absolute path under project_root.
+    path: z.string().min(1),
+    from_line: z.number().int().min(1).optional().default(1),
+    to_line: z.number().int().min(1).optional(),
+    // Convenience for "head": if set, reads from_line..(from_line+total_count-1) unless to_line is provided.
+    total_count: z.number().int().min(1).optional(),
+    // Hard limits to avoid huge token blow-ups.
+    max_lines: z.number().int().min(1).max(2000).optional().default(400),
+    max_chars: z.number().int().min(200).max(200_000).optional().default(20_000),
+}));
+const ReadFileTextArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative to project_root, or an absolute path under project_root.
+    path: z.string().min(1),
+    // Character offset in the decoded UTF-8 text.
+    offset: z.number().int().min(0).optional().default(0),
+    // Hard limit on returned text to avoid huge outputs.
+    max_chars: z.number().int().min(1).max(200_000).optional().default(20_000),
+    // Safety guard for raw reads; use read_file_lines on larger files.
+    max_file_bytes: z.number().int().min(1_000).max(5_000_000).optional().default(1_000_000),
+}));
+const ReadCodexTextFileArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Absolute path, file:// URI, or a path under CODEX_HOME / AGENTS_HOME allowed roots.
+    path: z.string().min(1),
+    offset: z.number().int().min(0).optional().default(0),
+    max_chars: z.number().int().min(1).max(200_000).optional().default(20_000),
+    max_file_bytes: z.number().int().min(1_000).max(5_000_000).optional().default(1_000_000),
+}));
+const ListProjectFilesArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative directory/file path under project_root. "." means the project root.
+    path: z.string().optional().default("."),
+    recursive: z.boolean().optional().default(false),
+    max_depth: z.number().int().min(1).max(20).optional().default(4),
+    include_files: z.boolean().optional().default(true),
+    include_dirs: z.boolean().optional().default(true),
+    include_hidden: z.boolean().optional().default(false),
+    respect_ignore: z.boolean().optional().default(true),
+    include_paths: z.array(z.string().min(1)).optional(),
+    exclude_paths: z.array(z.string().min(1)).optional(),
+    extensions: z.array(z.string().min(1)).optional(),
+    max_results: z.number().int().min(1).max(5000).optional().default(200),
+    include_stats: z.boolean().optional().default(false),
+}));
 const UpsertProjectSummaryArgsSchema = ProjectRootArgSchema.merge(z.object({
     summary: z.string().min(1),
 }));
@@ -1429,6 +1523,34 @@ function toMemoryItemPreview(row, includeContent, previewChars, contentMaxChars)
         updated_at: row.updated_at,
     };
 }
+function getBuiltinConventionRows() {
+    return BUILTIN_CONVENTIONS.map((spec, idx) => ({
+        id: -1000 - idx,
+        kind: "convention",
+        title: spec.key,
+        content: spec.content,
+        file_path: null,
+        start_line: null,
+        end_line: null,
+        req_id: null,
+        metadata_json: safeJson({ source: "builtin", key: spec.key, tags: spec.tags ?? [] }),
+        content_hash: sha256Hex(spec.content),
+        created_at: "builtin",
+        updated_at: "builtin",
+    }));
+}
+function getConventionPreviews(conventionsLimit, previewChars, contentMaxChars) {
+    if (conventionsLimit <= 0)
+        return [];
+    const builtin = getBuiltinConventionRows()
+        .map((row) => toMemoryItemPreview(row, false, previewChars, contentMaxChars))
+        .slice(0, conventionsLimit);
+    if (builtin.length >= conventionsLimit)
+        return builtin;
+    const remaining = conventionsLimit - builtin.length;
+    const stored = listConventionsStmt.all(remaining).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+    return [...builtin, ...stored];
+}
 function toRequirementPreview(req, includeContent, previewChars, contentMaxChars) {
     const context = req.context_data ?? null;
     const contextPreview = context ? makePreviewText(context, previewChars) : null;
@@ -1687,18 +1809,357 @@ async function semanticSearchHybridInternal(opts) {
     }
     return likeSearchInternal(opts);
 }
-const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
-    capabilities: { tools: {} },
-    instructions: [
+function escapeRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function hasUppercaseAscii(s) {
+    return /[A-Z]/.test(s);
+}
+function extractLongestLiteralFromRegex(pattern) {
+    // Best-effort extraction: pull the longest literal run to use as an indexed candidate hint.
+    // This is intentionally conservative; if we can't find a reasonable literal anchor, callers
+    // should pass `literal_hint` or narrow with include_paths.
+    let best = "";
+    let cur = "";
+    let inClass = false;
+    const flush = () => {
+        if (cur.length > best.length)
+            best = cur;
+        cur = "";
+    };
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i] ?? "";
+        if (!ch)
+            break;
+        if (inClass) {
+            // Skip until the closing bracket.
+            if (ch === "]")
+                inClass = false;
+            flush();
+            continue;
+        }
+        if (ch === "[") {
+            inClass = true;
+            flush();
+            continue;
+        }
+        if (ch === "\\") {
+            const next = pattern[i + 1] ?? "";
+            if (!next) {
+                flush();
+                continue;
+            }
+            // Common regex escapes that are NOT literal characters.
+            if (/[dDsSwWbB0-9]/.test(next)) {
+                flush();
+                i += 1;
+                continue;
+            }
+            // Treat \x as literal x (e.g. \( \) \. \\).
+            cur += next;
+            i += 1;
+            continue;
+        }
+        // Regex metacharacters.
+        if (".*+?^$|(){}".includes(ch)) {
+            flush();
+            continue;
+        }
+        cur += ch;
+    }
+    flush();
+    return best;
+}
+function normalizePathNeedle(s) {
+    return s.replace(/\\/g, "/").toLowerCase();
+}
+function passesPathFilters(filePath, includePaths, excludePaths) {
+    const fp = filePath.toLowerCase();
+    if (excludePaths?.length) {
+        for (const raw of excludePaths) {
+            const n = normalizePathNeedle(raw);
+            if (!n)
+                continue;
+            if (fp.includes(n))
+                return false;
+        }
+    }
+    if (includePaths?.length) {
+        for (const raw of includePaths) {
+            const n = normalizePathNeedle(raw);
+            if (!n)
+                continue;
+            if (fp.includes(n))
+                return true;
+        }
+        return false;
+    }
+    return true;
+}
+function buildLineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10)
+            starts.push(i + 1); // '\n'
+    }
+    return starts;
+}
+function lineIndexForOffset(lineStarts, offset) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const v = lineStarts[mid] ?? 0;
+        if (v <= offset)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    return Math.max(0, lo - 1);
+}
+function compileGrepRegex(opts) {
+    const flags = `${opts.caseSensitive ? "" : "i"}gm`;
+    const source = opts.mode === "literal" ? escapeRegExp(opts.query) : opts.query;
+    return new RegExp(source, flags);
+}
+function resolveProjectPathUnderRoot(inputPath, opts = {}) {
+    const normalizedInput = inputPath.trim() || ".";
+    const abs = path.isAbsolute(normalizedInput) ? normalizedInput : path.join(projectRoot, normalizedInput);
+    const absPath = path.resolve(abs);
+    const root = path.resolve(projectRoot);
+    const rel = path.relative(root, absPath);
+    const insideRoot = rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    if (!insideRoot) {
+        throw new Error(`[VectorMind] Path must be under project_root: ${inputPath}`);
+    }
+    if (rel === "" && !opts.allowRoot) {
+        throw new Error(`[VectorMind] Path must not be the project_root itself: ${inputPath}`);
+    }
+    return {
+        absPath,
+        dbFilePath: rel === "" ? "." : normalizeToDbPath(absPath),
+    };
+}
+function resolveReadPathUnderProjectRoot(inputPath) {
+    return resolveProjectPathUnderRoot(inputPath, { allowRoot: false });
+}
+function resolveCodexTextPath(inputPath) {
+    const trimmed = inputPath.trim();
+    if (!trimmed)
+        throw new Error("[VectorMind] path is required");
+    const uriPath = trimmed.startsWith("file:") ? parseFileUriToPath(trimmed) : null;
+    const absPath = path.resolve(uriPath ?? trimmed);
+    const allowedRoot = getAllowedCodexTextRoots().find((root) => {
+        const rel = path.relative(root, absPath);
+        return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    });
+    if (!allowedRoot) {
+        throw new Error(`[VectorMind] Path must be under one of the allowed local text roots: ${getAllowedCodexTextRoots().join(", ")}`);
+    }
+    return { absPath, displayPath: absPath, allowedRoot };
+}
+function isHiddenBaseName(name) {
+    return name.startsWith(".") && name !== "." && name !== "..";
+}
+function normalizeExtensionsFilter(values) {
+    if (!values?.length)
+        return null;
+    const normalized = values
+        .map((v) => v.trim().toLowerCase())
+        .filter(Boolean)
+        .map((v) => (v.startsWith(".") ? v : `.${v}`));
+    return normalized.length ? Array.from(new Set(normalized)) : null;
+}
+async function readTextFileLines(opts) {
+    let lineNo = 0;
+    const lines = [];
+    let totalChars = 0;
+    let truncated = false;
+    const stream = fs.createReadStream(opts.absPath, { encoding: "utf8" });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            lineNo += 1;
+            if (lineNo < opts.fromLine)
+                continue;
+            if (lineNo > opts.toLine)
+                break;
+            const rendered = `${lineNo}:${line}`;
+            totalChars += rendered.length + 1;
+            if (lines.length >= opts.maxLines || totalChars > opts.maxChars) {
+                truncated = true;
+                break;
+            }
+            lines.push(rendered);
+        }
+    }
+    finally {
+        try {
+            rl.close();
+        }
+        catch { }
+        try {
+            stream.destroy();
+        }
+        catch { }
+    }
+    return { text: lines.join("\n"), returned: lines.length, truncated };
+}
+function readTextFileSlice(opts) {
+    const st = fs.statSync(opts.absPath);
+    if (!st.isFile())
+        throw new Error("Not a file");
+    if (st.size > opts.maxFileBytes) {
+        throw new Error(`File is too large for raw text read (${st.size} bytes > limit ${opts.maxFileBytes}). Use read_file_lines instead.`);
+    }
+    const text = fs.readFileSync(opts.absPath, "utf8");
+    const totalChars = text.length;
+    const safeOffset = Math.min(opts.offset, totalChars);
+    const slice = text.slice(safeOffset, safeOffset + opts.maxChars);
+    const returnedChars = slice.length;
+    const truncated = safeOffset + returnedChars < totalChars;
+    return { text: slice, totalChars, returnedChars, truncated };
+}
+function listProjectFilesInternal(opts) {
+    const entries = [];
+    let scanned = 0;
+    let truncated = false;
+    const pushEntry = (entry) => {
+        if (entries.length >= opts.maxResults) {
+            truncated = true;
+            return;
+        }
+        entries.push(entry);
+    };
+    const startStat = fs.statSync(opts.startAbsPath);
+    if (startStat.isFile()) {
+        const relPath = opts.startDbPath;
+        if ((!opts.respectIgnore || !shouldIgnoreDbFilePath(relPath)) && passesPathFilters(relPath, opts.includePaths, opts.excludePaths)) {
+            const ext = path.extname(relPath).toLowerCase();
+            if (!opts.extensions || opts.extensions.includes(ext)) {
+                pushEntry({
+                    path: relPath,
+                    kind: "file",
+                    depth: 0,
+                    ...(opts.includeStats ? { size: startStat.size, mtime: startStat.mtime.toISOString() } : {}),
+                });
+            }
+        }
+        return { entries, returned: entries.length, scanned: 1, truncated };
+    }
+    const effectiveMaxDepth = opts.recursive ? opts.maxDepth : 1;
+    const stack = [{ absPath: opts.startAbsPath, depth: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            break;
+        let dirEntries;
+        try {
+            dirEntries = fs.readdirSync(current.absPath, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        dirEntries.sort((a, b) => a.name.localeCompare(b.name));
+        for (let idx = dirEntries.length - 1; idx >= 0; idx -= 1) {
+            const child = dirEntries[idx];
+            if (!child)
+                continue;
+            if (!opts.includeHidden && isHiddenBaseName(child.name))
+                continue;
+            const childAbs = path.join(current.absPath, child.name);
+            const childRel = normalizeToDbPath(childAbs);
+            if (opts.respectIgnore && shouldIgnoreDbFilePath(childRel))
+                continue;
+            scanned += 1;
+            const childDepth = current.depth + 1;
+            const matchesPath = passesPathFilters(childRel, opts.includePaths, opts.excludePaths);
+            if (child.isDirectory()) {
+                if (opts.includeDirs && matchesPath) {
+                    let stats = null;
+                    if (opts.includeStats) {
+                        try {
+                            stats = fs.statSync(childAbs);
+                        }
+                        catch {
+                            stats = null;
+                        }
+                    }
+                    pushEntry({
+                        path: childRel,
+                        kind: "dir",
+                        depth: childDepth,
+                        ...(stats ? { size: stats.size, mtime: stats.mtime.toISOString() } : {}),
+                    });
+                    if (truncated)
+                        break;
+                }
+                if (childDepth < effectiveMaxDepth) {
+                    stack.push({ absPath: childAbs, depth: childDepth });
+                }
+                continue;
+            }
+            if (!child.isFile())
+                continue;
+            if (!opts.includeFiles || !matchesPath)
+                continue;
+            const ext = path.extname(childRel).toLowerCase();
+            if (opts.extensions && !opts.extensions.includes(ext))
+                continue;
+            let stats = null;
+            if (opts.includeStats) {
+                try {
+                    stats = fs.statSync(childAbs);
+                }
+                catch {
+                    stats = null;
+                }
+            }
+            pushEntry({
+                path: childRel,
+                kind: "file",
+                depth: childDepth,
+                ...(stats ? { size: stats.size, mtime: stats.mtime.toISOString() } : {}),
+            });
+            if (truncated)
+                break;
+        }
+        if (truncated)
+            break;
+    }
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return { entries, returned: entries.length, scanned, truncated };
+}
+function buildServerInstructions() {
+    return [
         "VectorMind MCP is available in this session. Use it to avoid guessing project context.",
+        "This package ships built-in baseline policy. If a client supports MCP instructions, these rules auto-apply as soon as the MCP is installed and connected; no user-side config file is required.",
+        "The write-operation rules below are strict workflow constraints. Do not claim that the environment has real git branch locks, checkout APIs, or file-lock tools unless such tools are actually available in the current client/runtime. If such tools are absent, you must still enforce the same exclusivity semantics through explicit coordination and serialized same-file edits.",
         "Project root resolution order: tool argument project_root (recommended for clients without roots/list), then VECTORMIND_ROOT (avoid hardcoding in global config), then MCP roots/list (best-effort; falls back quickly if unsupported), then process.cwd() (so start your MCP client in the project directory for per-project isolation).",
         "If root_source is fallback, file watching/indexing is disabled (pass project_root to enable per-project tracking).",
         "",
+        "Built-in write-operation policy:",
+        BUILTIN_WRITE_POLICY_INSTRUCTIONS,
+        "",
+        "Built-in task-list / Plan-Lite policy:",
+        BUILTIN_PLAN_LITE_INSTRUCTIONS,
+        "",
+        "Built-in destructive-operation guard policy:",
+        BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS,
+        "",
+        "Built-in architecture and code-organization policy:",
+        BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS,
+        "",
         "Required workflow:",
         "- On every new conversation/session: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
         "  - Output is compact by default. Use include_content=true only when you truly need full text (it increases tokens).",
         "  - Tune output size with: requirements_limit/changes_limit/notes_limit, preview_chars, pending_limit/pending_offset.",
         "  - Prefer read_memory_item(id, offset, limit) to fetch full text on demand instead of returning large content in other tool outputs.",
+        "- To read local Codex skill/prompt/rule files (for example SKILL.md under CODEX_HOME or AGENTS_HOME), prefer read_codex_text_file({ path }) instead of assuming a filesystem MCP resource server exists.",
+        "- For project file/directory browsing, prefer list_project_files({ path, recursive?, max_depth? }) over shelling out to Get-ChildItem/ls. It respects ignore rules and keeps output bounded.",
+        "- For small/medium raw file reads, prefer read_file_text({ path, offset?, max_chars? }) over Get-Content -Raw. Use read_file_lines(...) when you need deterministic line ranges or the file may be large.",
+        "- For an rg/Select-String-style search with exact file+line+col matches, prefer grep({ query: <pattern> }) over shelling out (uses the indexed code/doc chunks).",
+        "- To read a bounded segment of a file, prefer read_file_lines({ path: <file>, from_line/to_line or total_count }) over unbounded file reads.",
         "- BEFORE editing code: call start_requirement(title, background) to set the active requirement.",
         "- AFTER editing + saving: call get_pending_changes() to see unsynced files, then call sync_change_intent(intent, files). (You can omit files to auto-link all pending changes.)",
         "- After major milestones/decisions: call upsert_project_summary(summary) and/or add_note(...) to persist durable context locally.",
@@ -1708,7 +2169,11 @@ const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
         "- When you need to recall relevant context from history/code/docs: call semantic_search(query, ...) instead of guessing.",
         "",
         "If tool output conflicts with assumptions, trust the tool output.",
-    ].join("\n"),
+    ].join("\n");
+}
+const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+    capabilities: { tools: {} },
+    instructions: buildServerInstructions(),
 });
 async function resolveProjectRootFromMcpRoots() {
     const caps = server.getClientCapabilities();
@@ -2265,6 +2730,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Clear the in-memory debug activity log. Enable logging with VECTORMIND_DEBUG_LOG=1.",
                 inputSchema: toJsonSchemaCompat(ClearActivityLogArgsSchema),
             },
+            {
+                name: "grep",
+                description: "Fast indexed grep across code/doc chunks with precise file/line/col matches. Prefer this over shelling out to rg/Select-String when possible.",
+                inputSchema: toJsonSchemaCompat(GrepArgsSchema),
+            },
+            {
+                name: "list_project_files",
+                description: "AI-friendly, ignore-aware file/directory listing under project_root with bounded output. Prefer this over Get-ChildItem/ls for local repository browsing.",
+                inputSchema: toJsonSchemaCompat(ListProjectFilesArgsSchema),
+            },
+            {
+                name: "read_codex_text_file",
+                description: "Read bounded text from local Codex/agents files such as SKILL.md, prompt files, and rules under CODEX_HOME/AGENTS_HOME. Prefer this over assuming a filesystem MCP resource server exists.",
+                inputSchema: toJsonSchemaCompat(ReadCodexTextFileArgsSchema),
+            },
+            {
+                name: "read_file_lines",
+                description: "Read a specific line range from a file under project_root (with strict size limits). Prefer this over Get-Content for deterministic reads.",
+                inputSchema: toJsonSchemaCompat(ReadFileLinesArgsSchema),
+            },
+            {
+                name: "read_file_text",
+                description: "Read bounded raw UTF-8 text from a file under project_root. Prefer this over Get-Content -Raw for small/medium text files; use read_file_lines for large files or line-specific reads.",
+                inputSchema: toJsonSchemaCompat(ReadFileTextArgsSchema),
+            },
             {
                 name: "query_codebase",
                 description: "Search the symbol index for class/function/type names (or substrings) to locate definitions by file path and signature. Use this when you need to find code—do not guess locations.",
@@ -2610,7 +3100,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
-            const conventions = listConventionsStmt.all(conventionsLimit).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+            const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
             const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
@@ -2706,7 +3196,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
-            const conventions = listConventionsStmt.all(conventionsLimit).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+            const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
             const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
@@ -2935,6 +3425,441 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             clearActivityLog();
             return { content: [{ type: "text", text: toolJson({ ok: true }) }] };
         }
+        if (toolName === "grep") {
+            const args = GrepArgsSchema.parse(rawArgs);
+            const q = args.query;
+            const mode = args.mode;
+            const smartCase = args.smart_case;
+            const kinds = args.kinds?.length ? args.kinds : ["code_chunk", "doc_chunk"];
+            const includePaths = args.include_paths?.length ? args.include_paths : null;
+            const excludePaths = args.exclude_paths?.length ? args.exclude_paths : null;
+            const maxResults = args.max_results;
+            const hint = (() => {
+                if (mode === "literal")
+                    return q;
+                const explicit = args.literal_hint.trim();
+                if (explicit)
+                    return explicit;
+                return extractLongestLiteralFromRegex(q);
+            })();
+            if (mode === "regex" && hint.trim().length < 3) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                error: "Regex has no sufficiently long literal anchor for indexed narrowing. Provide literal_hint (>= 3 chars) or narrow with include_paths.",
+                                query: q,
+                                mode,
+                                literal_hint: args.literal_hint,
+                            }),
+                        },
+                    ],
+                };
+            }
+            const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
+            let re;
+            try {
+                re = compileGrepRegex({ query: q, mode, caseSensitive });
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({ ok: false, error: `Invalid pattern: ${String(err)}`, query: q, mode }),
+                        },
+                    ],
+                };
+            }
+            const maxCandidates = args.max_candidates ?? Math.min(50_000, Math.max(1000, maxResults * 200));
+            const candidates = (() => {
+                if (ftsAvailable) {
+                    const matchQuery = buildFtsMatchQuery(hint);
+                    const placeholders = kinds.map(() => "?").join(", ");
+                    const stmt = db.prepare(`
+            SELECT
+              m.id as id,
+              m.kind as kind,
+              m.content as content,
+              m.file_path as file_path,
+              m.start_line as start_line,
+              m.end_line as end_line
+            FROM ${FTS_TABLE_NAME}
+            JOIN memory_items m ON m.id = ${FTS_TABLE_NAME}.rowid
+            WHERE ${FTS_TABLE_NAME} MATCH ?
+              AND m.kind IN (${placeholders})
+            ORDER BY m.file_path ASC, m.start_line ASC, m.id ASC
+            LIMIT ?
+          `);
+                    return stmt.all(matchQuery, ...kinds, maxCandidates);
+                }
+                const needle = mode === "literal" ? q : hint;
+                const escaped = escapeLike(needle);
+                const like = `%${escaped}%`;
+                const placeholders = kinds.map(() => "?").join(", ");
+                const stmt = db.prepare(`
+          SELECT
+            id,
+            kind,
+            content,
+            file_path,
+            start_line,
+            end_line
+          FROM memory_items
+          WHERE content LIKE ? ESCAPE '\\'
+            AND kind IN (${placeholders})
+          ORDER BY file_path ASC, start_line ASC, id ASC
+          LIMIT ?
+        `);
+                return stmt.all(like, ...kinds, maxCandidates);
+            })();
+            const matches = [];
+            let candidatesScanned = 0;
+            let truncated = false;
+            for (const c of candidates) {
+                candidatesScanned += 1;
+                if (!c.file_path || c.start_line == null)
+                    continue;
+                if (shouldIgnoreDbFilePath(c.file_path))
+                    continue;
+                if (!passesPathFilters(c.file_path, includePaths, excludePaths))
+                    continue;
+                const content = c.content ?? "";
+                const lineStarts = buildLineStarts(content);
+                re.lastIndex = 0;
+                let m;
+                while ((m = re.exec(content)) !== null) {
+                    const idx = m.index ?? 0;
+                    const matched = m[0] ?? "";
+                    if (!matched) {
+                        if (re.lastIndex >= content.length)
+                            break;
+                        re.lastIndex += 1;
+                        continue;
+                    }
+                    const lineIdx = lineIndexForOffset(lineStarts, idx);
+                    const lineStart = lineStarts[lineIdx] ?? 0;
+                    const lineEnd = lineIdx + 1 < lineStarts.length
+                        ? (lineStarts[lineIdx + 1] ?? content.length) - 1
+                        : content.length;
+                    const previewRaw = content.slice(lineStart, Math.max(lineStart, lineEnd));
+                    const preview = previewRaw.length > 500 ? `${previewRaw.slice(0, 500)}…` : previewRaw;
+                    const matchText = matched.length > 200 ? `${matched.slice(0, 200)}…` : matched;
+                    matches.push({
+                        file_path: c.file_path,
+                        kind: c.kind,
+                        line: c.start_line + lineIdx,
+                        col: idx - lineStart + 1,
+                        preview,
+                        match: matchText,
+                    });
+                    if (matches.length >= maxResults) {
+                        truncated = true;
+                        break;
+                    }
+                }
+                if (truncated)
+                    break;
+            }
+            logActivity("grep", {
+                query: q,
+                mode,
+                case_sensitive: caseSensitive,
+                smart_case: smartCase,
+                hint,
+                kinds,
+                include_paths: includePaths ?? [],
+                exclude_paths: excludePaths ?? [],
+                candidates: candidates.length,
+                candidates_scanned: candidatesScanned,
+                matches: matches.length,
+                truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            query: q,
+                            mode,
+                            case_sensitive: caseSensitive,
+                            smart_case: smartCase,
+                            hint,
+                            kinds,
+                            include_paths: includePaths ?? [],
+                            exclude_paths: excludePaths ?? [],
+                            candidates: { total: candidates.length, scanned: candidatesScanned },
+                            matches,
+                            truncated,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "list_project_files") {
+            const args = ListProjectFilesArgsSchema.parse(rawArgs);
+            const resolved = resolveProjectPathUnderRoot(args.path, { allowRoot: true });
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `Path not found: ${String(err)}` }) }],
+                };
+            }
+            const includePaths = args.include_paths?.length ? args.include_paths : null;
+            const excludePaths = args.exclude_paths?.length ? args.exclude_paths : null;
+            const extensions = normalizeExtensionsFilter(args.extensions);
+            const result = listProjectFilesInternal({
+                startAbsPath: resolved.absPath,
+                startDbPath: resolved.dbFilePath,
+                recursive: args.recursive,
+                maxDepth: args.max_depth,
+                includeFiles: args.include_files,
+                includeDirs: args.include_dirs,
+                includeHidden: args.include_hidden,
+                respectIgnore: args.respect_ignore,
+                includePaths,
+                excludePaths,
+                extensions,
+                maxResults: args.max_results,
+                includeStats: args.include_stats,
+            });
+            logActivity("list_project_files", {
+                path: resolved.dbFilePath,
+                recursive: args.recursive,
+                max_depth: args.max_depth,
+                include_files: args.include_files,
+                include_dirs: args.include_dirs,
+                include_hidden: args.include_hidden,
+                respect_ignore: args.respect_ignore,
+                include_paths: includePaths ?? [],
+                exclude_paths: excludePaths ?? [],
+                extensions: extensions ?? [],
+                returned: result.returned,
+                scanned: result.scanned,
+                truncated: result.truncated,
+                path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            path: resolved.dbFilePath,
+                            path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
+                            recursive: args.recursive,
+                            max_depth: args.recursive ? args.max_depth : 1,
+                            include_files: args.include_files,
+                            include_dirs: args.include_dirs,
+                            include_hidden: args.include_hidden,
+                            respect_ignore: args.respect_ignore,
+                            include_paths: includePaths ?? [],
+                            exclude_paths: excludePaths ?? [],
+                            extensions: extensions ?? [],
+                            returned: result.returned,
+                            scanned: result.scanned,
+                            truncated: result.truncated,
+                            entries: result.entries,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_file_text") {
+            const args = ReadFileTextArgsSchema.parse(rawArgs);
+            const resolved = resolveReadPathUnderProjectRoot(args.path);
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) }],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            let result;
+            try {
+                result = readTextFileSlice({
+                    absPath: resolved.absPath,
+                    offset: args.offset,
+                    maxChars: args.max_chars,
+                    maxFileBytes: args.max_file_bytes,
+                });
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            logActivity("read_file_text", {
+                file_path: resolved.dbFilePath,
+                offset: args.offset,
+                returned_chars: result.returnedChars,
+                total_chars: result.totalChars,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.dbFilePath,
+                            offset: args.offset,
+                            returned_chars: result.returnedChars,
+                            total_chars: result.totalChars,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_codex_text_file") {
+            const args = ReadCodexTextFileArgsSchema.parse(rawArgs);
+            let resolved;
+            try {
+                resolved = resolveCodexTextPath(args.path);
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) }],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            let result;
+            try {
+                result = readTextFileSlice({
+                    absPath: resolved.absPath,
+                    offset: args.offset,
+                    maxChars: args.max_chars,
+                    maxFileBytes: args.max_file_bytes,
+                });
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            logActivity("read_codex_text_file", {
+                file_path: resolved.displayPath,
+                allowed_root: resolved.allowedRoot,
+                offset: args.offset,
+                returned_chars: result.returnedChars,
+                total_chars: result.totalChars,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.displayPath,
+                            allowed_root: resolved.allowedRoot,
+                            offset: args.offset,
+                            returned_chars: result.returnedChars,
+                            total_chars: result.totalChars,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_file_lines") {
+            const args = ReadFileLinesArgsSchema.parse(rawArgs);
+            const resolved = resolveReadPathUnderProjectRoot(args.path);
+            let fromLine = args.from_line;
+            let toLine = args.to_line;
+            if (toLine == null) {
+                const total = args.total_count ?? 200;
+                toLine = fromLine + total - 1;
+            }
+            if (toLine < fromLine) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                error: "to_line must be >= from_line",
+                                path: args.path,
+                                from_line: fromLine,
+                                to_line: toLine,
+                            }),
+                        },
+                    ],
+                };
+            }
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [
+                        { type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) },
+                    ],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            const maxLines = Math.max(1, Math.min(2000, args.max_lines));
+            const maxChars = Math.max(200, Math.min(200_000, args.max_chars));
+            const result = await readTextFileLines({
+                absPath: resolved.absPath,
+                fromLine,
+                toLine,
+                maxLines,
+                maxChars,
+            });
+            logActivity("read_file_lines", {
+                file_path: resolved.dbFilePath,
+                from_line: fromLine,
+                to_line: toLine,
+                returned: result.returned,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.dbFilePath,
+                            from_line: fromLine,
+                            to_line: toLine,
+                            returned: result.returned,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
         if (toolName === "query_codebase") {
             const args = QueryCodebaseArgsSchema.parse(rawArgs);
             const q = args.query.trim();