neuro-vault-mcp 5.3.0 → 5.5.0

package/README.md

@@ -126,7 +126,7 @@ User guide lives in [`docs/guide/`](./docs/guide/README.md):
 
 - [Installation](./docs/guide/installation.md)
 - [Semantic Search](./docs/guide/semantic-search.md) — `search_notes`, `get_similar_notes`, `find_duplicates`, `get_stats`
-- [Vault Operations](./docs/guide/vault-operations.md) — note CRUD, daily notes, properties, tags, structured queries (`query_notes`)
+- [Vault Operations](./docs/guide/vault-operations.md) — note CRUD, daily notes, properties, tags, structured queries (`query_notes`), vault snapshot (`get_vault_overview`)
 - [Routing Between Tools](./docs/guide/routing.md)
 - [Configuration](./docs/guide/configuration.md) — CLI args, troubleshooting, limitations, **migration to 2.0**, development
 
@@ -134,6 +134,12 @@ Architecture / internals: [`docs/architecture/`](./docs/architecture/).
 
 ---
 
+### Vault-specific conventions for external agents
+
+When the server starts, it looks for `<vault>/.neuro-vault/for-external-agents.md`. If the file exists, its content is appended to the MCP `instructions` that clients receive at `initialize`, under a `## Vault-specific conventions` section. Use this file to teach external agents vault-specific rules that cannot be derived from the snapshot — for example, closed sets of frontmatter `type` values, or folders that are off-limits for writes. The file is optional; without it the server still ships sane defaults plus a pointer to `get_vault_overview`.
+
+---
+
 ## 📄 License
 
 ISC — see [LICENSE](LICENSE).

package/dist/cli.d.ts

@@ -242,11 +242,11 @@ interface OperationsModuleDeps {
     graph?: WikilinkGraphIndex;
 }
 
-type ToolServer = Pick<McpServer, 'registerTool' | 'connect'>;
+type ToolServer = Pick<McpServer, 'registerTool' | 'registerResource' | 'connect'>;
 interface NeuroVaultStartupDependencies {
     semantic?: SemanticModuleDeps;
     operations?: OperationsModuleDeps;
-    serverFactory?: () => ToolServer;
+    serverFactory?: (instructions: string) => ToolServer;
     transportFactory?: () => StdioServerTransport;
 }
 

package/dist/cli.js

@@ -33,6 +33,9 @@ async function parseConfig(argv) {
   }).option("obsidian-cli", {
     type: "string",
     describe: 'Path to the obsidian CLI binary (default: "obsidian" from PATH)'
+  }).option("vault-name", {
+    type: "string",
+    describe: `Override the Obsidian vault name used in CLI invocations. Defaults to the basename of --vault. Set this only if you renamed the vault in Obsidian's "Manage vaults" UI and the display name differs from the directory name.`
   }).strict().help().version(false).parse();
   if (!path.isAbsolute(args.vault)) {
     throw new Error("--vault must be an absolute path");
@@ -40,6 +43,9 @@ async function parseConfig(argv) {
   if (!args.semantic && !args.operations) {
     throw new Error("At least one module must be enabled (--semantic or --operations)");
   }
+  if (args["vault-name"] !== void 0 && args["vault-name"].trim() === "") {
+    throw new Error("--vault-name must not be empty");
+  }
   const normalizedVaultPath = path.resolve(args.vault);
   return {
     vaultPath: normalizedVaultPath,
@@ -51,13 +57,16 @@ async function parseConfig(argv) {
     },
     operations: {
       enabled: args.operations,
-      binaryPath: args["obsidian-cli"]
+      binaryPath: args["obsidian-cli"],
+      vaultName: args["vault-name"]?.trim() ?? path.basename(normalizedVaultPath)
     }
   };
 }
 
 // src/server.ts
 import { createRequire } from "module";
+import fs4 from "fs/promises";
+import path9 from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -321,9 +330,9 @@ function buildBasenameIndex(paths) {
     resolveAll
   };
 }
-function baseOf(path8) {
-  const slash = path8.lastIndexOf("/");
-  const tail = slash >= 0 ? path8.slice(slash + 1) : path8;
+function baseOf(path10) {
+  const slash = path10.lastIndexOf("/");
+  const tail = slash >= 0 ? path10.slice(slash + 1) : path10;
   return tail.endsWith(".md") ? tail.slice(0, -3) : tail;
 }
 
@@ -1716,10 +1725,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path8) {
-  if (!path8)
+function getElementAtPath(obj, path10) {
+  if (!path10)
     return obj;
-  return path8.reduce((acc, key) => acc?.[key], obj);
+  return path10.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -2102,11 +2111,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path8, issues) {
+function prefixIssues(path10, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path8);
+    iss.path.unshift(path10);
     return iss;
   });
 }
@@ -2289,7 +2298,7 @@ function formatError(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path8 = []) => {
+  const processError = (error49, path10 = []) => {
     var _a2, _b;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -2299,7 +2308,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path8, ...issue2.path];
+        const fullpath = [...path10, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -2331,8 +2340,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path8 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path8) {
+  const path10 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path10) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -14309,13 +14318,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path8 = ref.slice(1).split("/").filter(Boolean);
-  if (path8.length === 0) {
+  const path10 = ref.slice(1).split("/").filter(Boolean);
+  if (path10.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path8[0] === defsKey) {
-    const key = path8[1];
+  if (path10[0] === defsKey) {
+    const key = path10[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -14910,9 +14919,9 @@ async function invokeTool(handler) {
 // src/lib/tool-registry.ts
 function formatZodError(error48) {
   const issues = error48.issues.map((issue2) => {
-    const path8 = issue2.path.length > 0 ? issue2.path.join(".") : "<root>";
+    const path10 = issue2.path.length > 0 ? issue2.path.join(".") : "<root>";
     const expected = issue2.expected;
-    const formatted = { path: path8, message: issue2.message };
+    const formatted = { path: path10, message: issue2.message };
     if (typeof expected === "string") formatted.expected = expected;
     return formatted;
   });
@@ -15079,10 +15088,10 @@ async function getNoteLinks(opts) {
   for (const target of rawTargets) {
     const normalized = normalizeWikilinkTarget(target);
     if (!normalized) continue;
-    const path8 = basenameIndex.resolve(normalized);
-    if (!path8) continue;
-    if (path8 === notePath) continue;
-    resolved.add(path8);
+    const path10 = basenameIndex.resolve(normalized);
+    if (!path10) continue;
+    if (path10 === notePath) continue;
+    resolved.add(path10);
   }
   return resolved;
 }
@@ -15686,7 +15695,7 @@ function computeExpansion(args) {
       }
     }
   }
-  return [...bestByPath.entries()].map(([path8, similarity]) => ({ path: path8, similarity, via_expansion: true })).sort((a, b) => b.similarity - a.similarity || a.path.localeCompare(b.path)).slice(0, totalLimit);
+  return [...bestByPath.entries()].map(([path10, similarity]) => ({ path: path10, similarity, via_expansion: true })).sort((a, b) => b.similarity - a.similarity || a.path.localeCompare(b.path)).slice(0, totalLimit);
 }
 async function executeRetrieval(input) {
   const { query, mode, sources, embeddingProvider, searchEngine } = input;
@@ -15944,9 +15953,9 @@ function isFilterEmpty(filter) {
 }
 function narrowSources(sources, allowed) {
   const out = /* @__PURE__ */ new Map();
-  for (const path8 of allowed) {
-    const src = sources.get(path8);
-    if (src) out.set(path8, src);
+  for (const path10 of allowed) {
+    const src = sources.get(path10);
+    if (src) out.set(path10, src);
   }
   return out;
 }
@@ -16183,10 +16192,10 @@ var ObsidianCLIProvider = class {
   }
   async readDaily() {
     const { stdout: pathStdout } = await this.runCommand("daily:path", []);
-    const path8 = pathStdout.trim();
+    const path10 = pathStdout.trim();
     const { stdout } = await this.runCommand("daily:read", []);
     const { frontmatter, content } = splitFrontmatter(stdout);
-    return { path: path8, frontmatter, content };
+    return { path: path10, frontmatter, content };
   }
   async setProperty(input) {
     const tokens = [`name=${input.name}`, `value=${this.serializeValue(input.value)}`];
@@ -16301,6 +16310,13 @@ var ObsidianCLIProvider = class {
         { details: { stderr, command }, cause: error48 }
       );
     }
+    if (/vault (not found|does not exist)/i.test(stderr)) {
+      return new ToolHandlerError(
+        "VAULT_NOT_FOUND",
+        `Obsidian does not recognize a vault named '${this.vaultName}'. This usually means the vault was renamed in Obsidian's "Manage vaults" UI and the display name no longer matches the directory basename. Re-launch the server with --vault-name <exact-name-in-obsidian>.`,
+        { details: { stderr, vaultName: this.vaultName }, cause: error48 }
+      );
+    }
     if (/not found/i.test(stderr)) {
       return new ToolHandlerError("NOT_FOUND", `Note not found: ${stderr.trim() || "unknown"}`, {
         details: { stderr, command },
@@ -16512,18 +16528,18 @@ function buildEditNoteTool(deps) {
           input.name === void 0 ? "name" : "path"
         );
       }
-      const path8 = await resolveToPath(input, reader);
+      const path10 = await resolveToPath(input, reader);
       if (input.replace !== void 0) {
         if (input.replace === "") {
           throw invalidArgument("replace must not be empty", "replace");
         }
         return writer.replaceInNote({
-          path: path8,
+          path: path10,
           find: input.replace,
           content: input.content
         });
       }
-      return writer.replaceFullBody({ path: path8, content: input.content });
+      return writer.replaceFullBody({ path: path10, content: input.content });
     }
   };
 }
@@ -16574,22 +16590,91 @@ function buildGetNoteLinksTool(deps) {
     description: DESCRIPTION,
     inputSchema: inputSchema7,
     handler: async (input) => {
-      const path8 = normalizePath(input.path);
+      const path10 = normalizePath(input.path);
       await graph.ensureFresh();
-      return graph.getNoteLinks(path8);
+      return graph.getNoteLinks(path10);
     }
   };
 }
 
-// src/modules/operations/tools/list-properties.ts
+// src/lib/obsidian/top-by-backlinks.ts
+import path7 from "path";
+function topByBacklinks(input) {
+  const { paths, graph, limit } = input;
+  return paths.map((p) => ({
+    path: p,
+    title: basenameWithoutExt(p),
+    backlink_count: graph.getBacklinkCount(p)
+  })).sort(
+    (a, b) => b.backlink_count !== a.backlink_count ? b.backlink_count - a.backlink_count : a.path.localeCompare(b.path)
+  ).slice(0, limit);
+}
+function basenameWithoutExt(notePath) {
+  const base = path7.posix.basename(notePath);
+  return base.endsWith(".md") ? base.slice(0, -3) : base;
+}
+
+// src/lib/obsidian/vault-overview.ts
+var TOP_TAGS_LIMIT = 30;
+var TOP_PROPERTIES_LIMIT = 30;
+var TOP_BACKLINKS_LIMIT = 10;
+var ROOT_FOLDER_SENTINEL = "/";
+async function computeVaultOverview(deps) {
+  const { reader, provider, graph } = deps;
+  await graph.ensureFresh();
+  const paths = await reader.scan();
+  const [tags, props] = await Promise.all([provider.listTags(), provider.listProperties()]);
+  if (paths.length === 0) {
+    return {
+      total_notes: 0,
+      folders: [],
+      top_tags: tags.slice(0, TOP_TAGS_LIMIT),
+      properties: props.slice(0, TOP_PROPERTIES_LIMIT),
+      top_by_backlinks: []
+    };
+  }
+  const folders = /* @__PURE__ */ new Map();
+  for (const p of paths) {
+    const folder = topLevelFolder(p);
+    folders.set(folder, (folders.get(folder) ?? 0) + 1);
+  }
+  return {
+    total_notes: paths.length,
+    folders: sortFolders(folders),
+    top_tags: tags.slice(0, TOP_TAGS_LIMIT),
+    properties: props.slice(0, TOP_PROPERTIES_LIMIT),
+    top_by_backlinks: topByBacklinks({ paths, graph, limit: TOP_BACKLINKS_LIMIT })
+  };
+}
+function topLevelFolder(notePath) {
+  const ix = notePath.indexOf("/");
+  return ix === -1 ? ROOT_FOLDER_SENTINEL : notePath.slice(0, ix);
+}
+function sortFolders(map2) {
+  return [...map2.entries()].map(([path10, count]) => ({ path: path10, count })).sort((a, b) => b.count !== a.count ? b.count - a.count : a.path.localeCompare(b.path));
+}
+
+// src/modules/operations/tools/get-vault-overview.ts
 var inputSchema8 = external_exports.object({});
+function buildGetVaultOverviewTool(deps) {
+  return {
+    name: "get_vault_overview",
+    title: "Get Vault Overview",
+    description: "Returns a single snapshot of vault structure: top-level folders with note counts, top tags, frontmatter properties, total note count, and the top 10 notes by inbound wikilinks. Call this once at the start of a session to orient yourself before reaching for `list_tags`, `list_properties`, or exploratory `query_notes`.",
+    inputSchema: inputSchema8,
+    handler: async (_input) => computeVaultOverview(deps)
+  };
+}
+
+// src/modules/operations/tools/list-properties.ts
+var inputSchema9 = external_exports.object({});
 function buildListPropertiesTool(deps) {
   const { provider } = deps;
   return {
     name: "list_properties",
     title: "List Properties",
     description: "List all frontmatter properties used across the vault, sorted by occurrence count desc. Returns `[{name, count}]`. Useful for understanding the vault's metadata ontology.",
-    inputSchema: inputSchema8,
+    inputSchema: inputSchema9,
     handler: async (_input) => {
       return provider.listProperties();
     }
@@ -16597,14 +16682,14 @@ function buildListPropertiesTool(deps) {
 }
 
 // src/modules/operations/tools/list-tags.ts
-var inputSchema9 = external_exports.object({});
+var inputSchema10 = external_exports.object({});
 function buildListTagsTool(deps) {
   const { provider } = deps;
   return {
     name: "list_tags",
     title: "List Tags",
     description: "List all tags used across the vault, sorted by occurrence count desc. Returns `[{name, count}]`.",
-    inputSchema: inputSchema9,
+    inputSchema: inputSchema10,
     handler: async (_input) => {
       return provider.listTags();
     }
@@ -16616,7 +16701,7 @@ var queryNotesSortSchema = external_exports.object({
   field: external_exports.string().min(1),
   order: external_exports.enum(["asc", "desc"])
 });
-var inputSchema10 = external_exports.object({
+var inputSchema11 = external_exports.object({
   filter: external_exports.record(external_exports.string(), external_exports.unknown()),
   path_prefix: external_exports.string().optional(),
   sort: queryNotesSortSchema.optional(),
@@ -16629,7 +16714,7 @@ function buildQueryNotesTool(deps) {
     name: "query_notes",
     title: "Query Notes",
     description: 'Run a structured MongoDB-style query against the vault\'s frontmatter, tags, and wikilink graph. `filter` is a sift/MongoDB filter object evaluated against `NoteRecord` shape `{ path, frontmatter, tags, backlink_count }` \u2014 `tags` is an array of strings (no leading `#`) extracted from the `tags:` frontmatter field; `backlink_count` is the number of vault-wide wikilinks (and `![[embeds]]`) that point at the note. Reference frontmatter keys with the dotted prefix `frontmatter.<key>`. Supported operators: `$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists`, `$regex`, `$options`, `$and`, `$or`, `$nor`, `$not`. `$regex` is case-insensitive by default; pass `$options` (e.g. `\'\'` for case-sensitive, `\'m\'` for multiline-only) to override. Optional `path_prefix` restricts the scan to a vault subtree (vault-relative POSIX, no leading slash). Optional `sort` is `{ field, order }` \u2014 `field` must be `"path"`, `"backlink_count"`, or start with `"frontmatter."`. Optional `limit` defaults to 100, max 1000. Optional `include_content` (default false) \u2014 when true, each result also carries `content` (note body). Returns `{ results, count, truncated }`; each result item carries `backlink_count`. `truncated` is true when more notes matched than `limit` allowed. Reads directly from disk and does not require Obsidian to be running.',
-    inputSchema: inputSchema10,
+    inputSchema: inputSchema11,
     handler: async (input) => {
       return runQueryNotes(input, reader, graph);
     }
@@ -16639,14 +16724,14 @@ function buildQueryNotesTool(deps) {
 // src/modules/operations/tools/read-daily.ts
 var NOTES_TODAY_CAP = 200;
 var DAILY_BASENAME_RE = /(\d{4}-\d{2}-\d{2})\.md$/;
-var inputSchema11 = external_exports.object({});
+var inputSchema12 = external_exports.object({});
 function buildReadDailyTool(deps) {
   const { provider, reader, graph } = deps;
   return {
     name: "read_daily",
     title: "Read Daily",
     description: 'Read today\'s daily note. Returns `{ path, frontmatter, content, notes_today }` where `frontmatter` is the parsed YAML object (or `null` if absent/malformed), `content` is the body without the YAML block, and `notes_today` lists vault notes created today (matched by `frontmatter.created`) excluding daily notes themselves \u2014 metadata only, sorted by path ascending, capped at 200 entries. Useful for "what\'s on my agenda?" / "what happened today?" questions without a separate `query_notes` call.',
-    inputSchema: inputSchema11,
+    inputSchema: inputSchema12,
     handler: async (_input) => {
       const daily = await provider.readDaily();
       const today = deriveToday(daily.path);
@@ -16690,7 +16775,7 @@ function formatLocalDate(d) {
 
 // src/modules/operations/tools/read-notes.ts
 var readNotesFieldSchema = external_exports.enum(["frontmatter", "content"]);
-var inputSchema12 = external_exports.object({
+var inputSchema13 = external_exports.object({
   paths: external_exports.union([external_exports.string().min(1), external_exports.array(external_exports.string()).min(1).max(50)]),
   fields: external_exports.array(readNotesFieldSchema).min(1).optional()
 });
@@ -16700,7 +16785,7 @@ function buildReadNotesTool(deps) {
     name: "read_notes",
     title: "Read Notes",
     description: "Read one or more notes in one call. `paths` is a vault-relative POSIX path string or an array of 1\u201350 such paths; duplicates are de-duplicated and results returned in input order. `fields` projects which parts of each note to return \u2014 choose from `frontmatter` and `content`; default `['frontmatter','content']`. One missing or unreadable path does not fail the others \u2014 per-item errors come back inline. A single MCP roundtrip with parallel disk reads. Reads are direct from disk and do not require Obsidian to be running.",
-    inputSchema: inputSchema12,
+    inputSchema: inputSchema13,
     handler: async (input) => {
       const { paths, fields } = validateReadNotesInput(input);
       const seen = /* @__PURE__ */ new Set();
@@ -16752,7 +16837,7 @@ function buildReadNotesTool(deps) {
 }
 
 // src/modules/operations/tools/read-property.ts
-var inputSchema13 = external_exports.object({
+var inputSchema14 = external_exports.object({
   name: external_exports.string().optional(),
   path: external_exports.string().optional(),
   key: external_exports.string()
@@ -16763,7 +16848,7 @@ function buildReadPropertyTool(deps) {
     name: "read_property",
     title: "Read Property",
     description: "Read a frontmatter property value from a note. Provide `name` or `path`, plus `key`. Returns `{ value }`. Use `read_notes` if you need the full frontmatter or accurate type information.",
-    inputSchema: inputSchema13,
+    inputSchema: inputSchema14,
     handler: async (input) => {
       const identifier = resolveIdentifier(input.name, input.path);
       if (!input.key || input.key.trim() === "") {
@@ -16775,7 +16860,7 @@ function buildReadPropertyTool(deps) {
 }
 
 // src/modules/operations/tools/remove-property.ts
-var inputSchema14 = external_exports.object({
+var inputSchema15 = external_exports.object({
   name: external_exports.string().optional(),
   path: external_exports.string().optional(),
   key: external_exports.string()
@@ -16786,7 +16871,7 @@ function buildRemovePropertyTool(deps) {
     name: "remove_property",
     title: "Remove Property",
     description: "Remove a frontmatter property from a note. Provide `name` or `path`, plus `key`. Idempotent \u2014 succeeds whether or not the property existed.",
-    inputSchema: inputSchema14,
+    inputSchema: inputSchema15,
     handler: async (input) => {
       const identifier = resolveIdentifier(input.name, input.path);
       if (!input.key || input.key.trim() === "") {
@@ -16799,7 +16884,7 @@ function buildRemovePropertyTool(deps) {
 }
 
 // src/modules/operations/tools/set-property.ts
-var inputSchema15 = external_exports.object({
+var inputSchema16 = external_exports.object({
   name: external_exports.string().optional(),
   path: external_exports.string().optional(),
   key: external_exports.string(),
@@ -16812,7 +16897,7 @@ function buildSetPropertyTool(deps) {
     name: "set_property",
     title: "Set Property",
     description: "Set a frontmatter property on a note. Provide either `name` (wikilink-style) or `path` (vault-relative). `key` is the frontmatter property name (e.g. `status`, `due`). `value` may be string/number/boolean/array \u2014 `type` is inferred from the JS type unless given. For `date`/`datetime` you MUST pass `type` explicitly AND use ISO format (`YYYY-MM-DD` for date, `YYYY-MM-DDTHH:mm:ss[.sss][Z|\xB1HH:mm]` for datetime) \u2014 non-ISO values are silently dropped by obsidian-cli, so this tool rejects them up front. List items must not contain commas (obsidian-cli limitation). Existing properties are overwritten.",
-    inputSchema: inputSchema15,
+    inputSchema: inputSchema16,
     handler: async (input) => {
       const identifier = resolveIdentifier(input.name, input.path);
       if (!input.key || input.key.trim() === "") {
@@ -16838,13 +16923,58 @@ function buildOperationsTools(deps) {
     registerTool(buildRemovePropertyTool(deps)),
     registerTool(buildListPropertiesTool(deps)),
     registerTool(buildListTagsTool(deps)),
-    registerTool(buildGetNoteLinksTool(deps))
+    registerTool(buildGetNoteLinksTool(deps)),
+    registerTool(buildGetVaultOverviewTool(deps))
   ];
 }
 
+// src/lib/resource-registry.ts
+function registerResource(resource) {
+  const mimeType = resource.mimeType ?? "application/json";
+  return {
+    name: resource.name,
+    uri: resource.uri,
+    metadata: {
+      ...resource.title !== void 0 ? { title: resource.title } : {},
+      description: resource.description,
+      mimeType
+    },
+    handler: async (uri) => {
+      const payload = await resource.handler(uri);
+      const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+      return {
+        contents: [
+          {
+            uri: resource.uri,
+            mimeType,
+            text
+          }
+        ]
+      };
+    }
+  };
+}
+
+// src/modules/operations/resources/vault-overview.ts
+function buildVaultOverviewResource(deps) {
+  return {
+    name: "vault-overview",
+    uri: "vault://overview",
+    title: "Vault Overview",
+    description: "Snapshot of vault structure (folders, tags, properties, top-10 notes by backlinks). Same payload as the `get_vault_overview` tool; exposed as a resource so clients that auto-load resources can pull it into context without an explicit tool call.",
+    mimeType: "application/json",
+    handler: async () => computeVaultOverview(deps)
+  };
+}
+
+// src/modules/operations/resources/index.ts
+function buildOperationsResources(deps) {
+  return [registerResource(buildVaultOverviewResource(deps))];
+}
+
 // src/lib/obsidian/vault-writer.ts
 import { readFile as fsReadFile2, writeFile as fsWriteFile } from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 var FsVaultWriter = class {
   vaultRoot;
   readFile;
@@ -16855,7 +16985,7 @@ var FsVaultWriter = class {
     this.writeFile = opts.writeFile ?? ((p, d, enc) => fsWriteFile(p, d, enc));
   }
   async replaceInNote(input) {
-    const absPath = path7.join(this.vaultRoot, input.path);
+    const absPath = path8.join(this.vaultRoot, input.path);
     const raw = await this.readRaw(absPath, input.path);
     const { prefix, body } = splitRawFrontmatter(raw);
     const result = applyReplace(body, input.find, input.content);
@@ -16874,7 +17004,7 @@ var FsVaultWriter = class {
     await this.writeFile(absPath, prefix + result.body, "utf8");
   }
   async replaceFullBody(input) {
-    const absPath = path7.join(this.vaultRoot, input.path);
+    const absPath = path8.join(this.vaultRoot, input.path);
     const raw = await this.readRaw(absPath, input.path);
     const { prefix } = splitRawFrontmatter(raw);
     await this.writeFile(absPath, prefix + input.content, "utf8");
@@ -16904,18 +17034,31 @@ function createOperationsModule(config2, deps = {}) {
   const providerFactory = deps.vaultProviderFactory ?? ((opts) => new ObsidianCLIProvider(opts));
   const readerFactory = deps.vaultReaderFactory ?? ((opts) => new FsVaultReader({ vaultRoot: opts.vaultRoot }));
   const writerFactory = deps.vaultWriterFactory ?? ((opts) => new FsVaultWriter({ vaultRoot: opts.vaultRoot }));
-  const provider = providerFactory({ binaryPath: config2.binaryPath });
+  const provider = providerFactory({ binaryPath: config2.binaryPath, vaultName: config2.vaultName });
   const reader = readerFactory({ vaultRoot: config2.vaultPath });
   const writer = writerFactory({ vaultRoot: config2.vaultPath });
   const graph = deps.graph ?? new WikilinkGraphIndex({ reader });
   const toolDeps = { provider, reader, writer, graph };
-  return { tools: buildOperationsTools(toolDeps) };
+  return {
+    tools: buildOperationsTools(toolDeps),
+    resources: buildOperationsResources({ reader, provider, graph })
+  };
 }
 
 // src/server.ts
 var require2 = createRequire(import.meta.url);
 var { name: SERVER_NAME, version: SERVER_VERSION } = require2("../package.json");
-var SERVER_INSTRUCTIONS = `This server provides two capability sets for an Obsidian vault: semantic search (when enabled) and direct vault operations (when enabled). Use the right one based on the user's intent.
+var EXTERNAL_AGENT_INSTRUCTIONS_PATH = ".neuro-vault/for-external-agents.md";
+async function readExternalAgentInstructions(vaultPath) {
+  const filePath = path9.join(vaultPath, EXTERNAL_AGENT_INSTRUCTIONS_PATH);
+  try {
+    const raw = await fs4.readFile(filePath, "utf8");
+    return raw.trim();
+  } catch {
+    return null;
+  }
+}
+var STATIC_SERVER_INSTRUCTIONS = `This server provides two capability sets for an Obsidian vault: semantic search (when enabled) and direct vault operations (when enabled). Use the right one based on the user's intent.
 
 ## Role: a second brain alongside the project
 
@@ -16998,11 +17141,20 @@ If the user gives an exact anchor (note path, daily note, tag, frontmatter field
 
 For tag-driven questions ("which notes are tagged X?", "show me everything in #ai") use \`query_notes\` with \`{ filter: { tags: '<name>' } }\`, not \`search_notes\` \u2014 the answer is exact, not fuzzy.
 `;
-function defaultServerFactory() {
-  return new McpServer(
-    { name: SERVER_NAME, version: SERVER_VERSION },
-    { instructions: SERVER_INSTRUCTIONS }
-  );
+var GET_VAULT_OVERVIEW_HINT = `## Orientation
+
+Before reaching for \`list_tags\`, \`list_properties\`, or exploratory \`query_notes\`, call \`get_vault_overview\` once at the start of a session. It returns the top-level folder layout with counts, the top tags, frontmatter properties with inferred types, the total note count, and the top 10 notes by inbound wikilinks \u2014 enough to orient yourself in a single call. The same payload is available as the MCP resource \`vault://overview\` for clients that auto-load resources.`;
+async function buildServerInstructions(vaultPath) {
+  let result = STATIC_SERVER_INSTRUCTIONS;
+  result += "\n\n" + GET_VAULT_OVERVIEW_HINT;
+  const extra = await readExternalAgentInstructions(vaultPath);
+  if (extra !== null && extra !== "") {
+    result += "\n\n## Vault-specific conventions\n\n" + extra;
+  }
+  return result;
+}
+function defaultServerFactory(instructions) {
+  return new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions });
 }
 function defaultTransportFactory() {
   return new StdioServerTransport();
@@ -17011,16 +17163,18 @@ async function startNeuroVaultServer(config2, deps = {}) {
   if (!config2.semantic.enabled && !config2.operations.enabled) {
     throw new Error("No modules enabled \u2014 pass --semantic or --operations");
   }
+  const instructions = await buildServerInstructions(config2.vaultPath);
   const serverFactory = deps.serverFactory ?? defaultServerFactory;
   const transportFactory = deps.transportFactory ?? defaultTransportFactory;
-  const server = serverFactory();
+  const server = serverFactory(instructions);
   const sharedReader = new FsVaultReader({ vaultRoot: config2.vaultPath });
   const sharedGraph = new WikilinkGraphIndex({ reader: sharedReader });
   const sharedListMatchingPaths = createListMatchingPaths({
     reader: sharedReader,
     graph: sharedGraph
   });
-  const registrations = [];
+  const toolRegistrations = [];
+  const resourceRegistrations = [];
   let warmup = async () => {
   };
   if (config2.semantic.enabled) {
@@ -17037,22 +17191,27 @@ async function startNeuroVaultServer(config2, deps = {}) {
         ...deps.semantic
       }
     );
-    registrations.push(...semantic.tools);
+    toolRegistrations.push(...semantic.tools);
     warmup = semantic.warmup;
   }
   if (config2.operations.enabled) {
     const operations = createOperationsModule(
       {
         vaultPath: config2.vaultPath,
+        vaultName: config2.operations.vaultName,
         binaryPath: config2.operations.binaryPath
       },
       { graph: sharedGraph, ...deps.operations }
     );
-    registrations.push(...operations.tools);
+    toolRegistrations.push(...operations.tools);
+    resourceRegistrations.push(...operations.resources);
   }
-  for (const tool of registrations) {
+  for (const tool of toolRegistrations) {
     server.registerTool(tool.name, tool.spec, tool.handler);
   }
+  for (const resource of resourceRegistrations) {
+    server.registerResource(resource.name, resource.uri, resource.metadata, resource.handler);
+  }
   await server.connect(transportFactory());
   void warmup().catch((error48) => {
     const message = error48 instanceof Error ? error48.message : String(error48);