apple-notes-mcp 2.8.25 → 2.8.27

package/build/index.js

@@ -3268,8 +3268,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path5) {
-      let input = path5;
+    function removeDotSegments(path7) {
+      let input = path7;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3674,8 +3674,8 @@ var require_schemes = __commonJS({
       }
       if (wsComponent.resourceName) {
         const queryIndex = wsComponent.resourceName.indexOf("?");
-        const path5 = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
-        wsComponent.path = path5 && path5 !== "/" ? path5 : void 0;
+        const path7 = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
+        wsComponent.path = path7 && path7 !== "/" ? path7 : void 0;
         wsComponent.query = queryIndex === -1 ? void 0 : wsComponent.resourceName.slice(queryIndex + 1);
         wsComponent.resourceName = void 0;
       }
@@ -7181,12 +7181,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs5, exportName) {
+    function addFormats(ajv, list, fs7, exportName) {
       var _a;
       var _b;
       (_a = (_b = ajv.opts.code).formats) !== null && _a !== void 0 ? _a : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs5[f]);
+        ajv.addFormat(f, fs7[f]);
     }
     module.exports = exports = formatsPlugin;
     Object.defineProperty(exports, "__esModule", { value: true });
@@ -12238,32 +12238,32 @@ var require_URL = __commonJS({
           else
             return basepath.substring(0, lastslash + 1) + refpath;
         }
-        function remove_dot_segments(path5) {
-          if (!path5) return path5;
+        function remove_dot_segments(path7) {
+          if (!path7) return path7;
           var output = "";
-          while (path5.length > 0) {
-            if (path5 === "." || path5 === "..") {
-              path5 = "";
+          while (path7.length > 0) {
+            if (path7 === "." || path7 === "..") {
+              path7 = "";
               break;
             }
-            var twochars = path5.substring(0, 2);
-            var threechars = path5.substring(0, 3);
-            var fourchars = path5.substring(0, 4);
+            var twochars = path7.substring(0, 2);
+            var threechars = path7.substring(0, 3);
+            var fourchars = path7.substring(0, 4);
             if (threechars === "../") {
-              path5 = path5.substring(3);
+              path7 = path7.substring(3);
             } else if (twochars === "./") {
-              path5 = path5.substring(2);
+              path7 = path7.substring(2);
             } else if (threechars === "/./") {
-              path5 = "/" + path5.substring(3);
-            } else if (twochars === "/." && path5.length === 2) {
-              path5 = "/";
-            } else if (fourchars === "/../" || threechars === "/.." && path5.length === 3) {
-              path5 = "/" + path5.substring(4);
+              path7 = "/" + path7.substring(3);
+            } else if (twochars === "/." && path7.length === 2) {
+              path7 = "/";
+            } else if (fourchars === "/../" || threechars === "/.." && path7.length === 3) {
+              path7 = "/" + path7.substring(4);
               output = output.replace(/\/?[^\/]*$/, "");
             } else {
-              var segment = path5.match(/(\/?([^\/]*))/)[0];
+              var segment = path7.match(/(\/?([^\/]*))/)[0];
               output += segment;
-              path5 = path5.substring(segment.length);
+              path7 = path7.substring(segment.length);
             }
           }
           return output;
@@ -24465,14 +24465,14 @@ var require_turndown_cjs = __commonJS({
         } else if (node.nodeType === 1) {
           replacement = replacementForNode.call(self, node);
         }
-        return join12(output, replacement);
+        return join14(output, replacement);
       }, "");
     }
     function postProcess(output) {
       var self = this;
       this.rules.forEach(function(rule) {
         if (typeof rule.append === "function") {
-          output = join12(output, rule.append(self.options));
+          output = join14(output, rule.append(self.options));
         }
       });
       return output.replace(/^[\t\r\n]+/, "").replace(/[\t\r\n\s]+$/, "");
@@ -24484,7 +24484,7 @@ var require_turndown_cjs = __commonJS({
       if (whitespace.leading || whitespace.trailing) content = content.trim();
       return whitespace.leading + rule.replacement(content, node, this.options) + whitespace.trailing;
     }
-    function join12(output, replacement) {
+    function join14(output, replacement) {
       var s1 = trimTrailingNewlines(output);
       var s2 = trimLeadingNewlines(replacement);
       var nls = Math.max(output.length - s1.length, replacement.length - s2.length);
@@ -24979,8 +24979,8 @@ function getErrorMap() {
 
 // node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path5, errorMaps, issueData } = params;
-  const fullPath = [...path5, ...issueData.path || []];
+  const { data, path: path7, errorMaps, issueData } = params;
+  const fullPath = [...path7, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -25096,11 +25096,11 @@ var errorUtil;
 
 // node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path5, key) {
+  constructor(parent, value, path7, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path5;
+    this._path = path7;
     this._key = key;
   }
   get path() {
@@ -28737,10 +28737,10 @@ function assignProp(target, prop, value) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path5) {
-  if (!path5)
+function getElementAtPath(obj, path7) {
+  if (!path7)
     return obj;
-  return path5.reduce((acc, key) => acc?.[key], obj);
+  return path7.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -29060,11 +29060,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path5, issues) {
+function prefixIssues(path7, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path5);
+    iss.path.unshift(path7);
     return iss;
   });
 }
@@ -32475,11 +32475,11 @@ function normalizeObjectSchema(schema) {
   }
   return void 0;
 }
-function getDotPath(path5) {
-  if (path5.length === 0) {
+function getDotPath(path7) {
+  if (path7.length === 0) {
     return "object root";
   }
-  return path5.reduce((acc, seg, index) => {
+  return path7.reduce((acc, seg, index) => {
     if (index === 0) {
       return String(seg);
     }
@@ -39839,9 +39839,392 @@ function assertLinkedWrite(rich, content, format, allowLinkChanges = false) {
   }
 }
 
+// src/utils/smartFolders.ts
+import { execFileSync as execFileSync4 } from "child_process";
+import * as fs2 from "fs";
+import * as os2 from "os";
+import * as path2 from "path";
+var NOTES_DB_PATH2 = path2.join(
+  os2.homedir(),
+  "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
+);
+var FDA_MESSAGE = `Full Disk Access is required to read smart folders. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
+var COCOA_EPOCH_OFFSET = 978307200;
+var MAX_DEPTH = 32;
+var RELATIVE_RANGES = {
+  0: "today",
+  1: "yesterday",
+  2: "in the last 7 days",
+  3: "in the last 30 days",
+  4: "in the last 3 months",
+  5: "in the last 12 months"
+};
+var CUSTOM_UNITS = {
+  0: "hours",
+  1: "days",
+  2: "weeks",
+  3: "months",
+  4: "years"
+};
+var ATTACHMENT_SECTIONS = {
+  1: "Photos & Videos",
+  2: "Drawings",
+  3: "Maps",
+  4: "Websites",
+  5: "Audio",
+  6: "Documents",
+  7: "Scans"
+};
+var isClause = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isDeletedWrapper = (value) => isClause(value) && Object.keys(value).length === 1 && typeof value.deleted === "boolean";
+function cocoaDate(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const date3 = new Date((value + COCOA_EPOCH_OFFSET) * 1e3);
+  return Number.isNaN(date3.getTime()) ? null : date3.toISOString();
+}
+var Decoder = class {
+  constructor(context) {
+    this.context = context;
+  }
+  context;
+  fullyDecoded = true;
+  unknown(key, value, excluded) {
+    this.fullyDecoded = false;
+    return {
+      type: "unknown",
+      ...key === null ? {} : { key },
+      value,
+      ...excluded ? { excluded: true } : {},
+      description: "Unrecognized clause (see value)"
+    };
+  }
+  /** Decode a list of sibling clauses, dropping inner `deleted` wrappers. */
+  list(clauses, excluded, depth) {
+    if (!Array.isArray(clauses)) return [this.clause(clauses, excluded, depth)];
+    return clauses.filter((clause) => !isDeletedWrapper(clause)).map((clause) => this.clause(clause, excluded, depth));
+  }
+  group(match, clauses, excluded, depth) {
+    const items = Array.isArray(clauses) ? clauses.filter((clause) => !isDeletedWrapper(clause)) : [clauses];
+    if (items.length === 1) return this.clause(items[0], excluded, depth + 1);
+    const filters = this.list(items, false, depth + 1);
+    const joiner = match === "all" ? "all of" : "any of";
+    return {
+      type: "group",
+      match,
+      ...excluded ? { excluded: true } : {},
+      filters,
+      description: `${excluded ? "not " : ""}${joiner}: ${filters.map((f) => f.description).join("; ")}`
+    };
+  }
+  /** Mark a positively described leaf as an Exclude rule. */
+  negate(filter) {
+    const text = filter.description;
+    const negated = text.startsWith("has ") ? text.replace(/^has /, "does not have ") : text.startsWith("is ") ? text.replace(/^is /, "is not ") : text.startsWith("mentions ") ? text.replace(/^mentions /, "does not mention ") : `not ${text}`;
+    return { ...filter, excluded: true, description: negated };
+  }
+  clause(clause, excluded, depth) {
+    if (depth > MAX_DEPTH || !isClause(clause)) return this.unknown(null, clause, excluded);
+    const keys = Object.keys(clause);
+    if (keys.length !== 1) {
+      return this.group(
+        "all",
+        keys.map((key2) => ({ [key2]: clause[key2] })),
+        excluded,
+        depth
+      );
+    }
+    const [key] = keys;
+    const value = clause[key];
+    if (key === "and" || key === "or") {
+      if (!Array.isArray(value)) return this.unknown(key, value, excluded);
+      return this.group(key === "and" ? "all" : "any", value, excluded, depth);
+    }
+    if (key === "not") return this.clause(value, !excluded, depth + 1);
+    const leaf = this.leaf(key, value, excluded);
+    if (!leaf) return this.unknown(key, value, excluded);
+    return excluded && !leaf.excluded ? this.negate(leaf) : leaf;
+  }
+  /**
+   * Decode one leaf clause. Boolean flags describe their own negation (an
+   * excluded `pinned: true` reads "is not pinned"); other leaves are described
+   * positively and negated by the caller.
+   */
+  leaf(key, value, excluded) {
+    const flag = (description, negative) => typeof value === "boolean" ? {
+      type: key,
+      value,
+      ...excluded ? { excluded: true } : {},
+      description: value !== excluded ? description : negative
+    } : null;
+    switch (key) {
+      case "checklist":
+        return flag("has a checklist", "has no checklist");
+      case "checklistInProgress":
+        return flag("has an unfinished checklist", "has no unfinished checklist");
+      case "checklistCompleted":
+        return flag("has a completed checklist", "has no completed checklist");
+      case "attachment":
+        return flag("has attachments", "has no attachments");
+      case "pinned":
+        return flag("is pinned", "is not pinned");
+      case "systemPaper":
+        return flag("is a Quick Note", "is not a Quick Note");
+      case "passwordProtected":
+        return flag("is locked", "is not locked");
+      case "shared":
+        return flag("is shared", "is not shared");
+      case "mention":
+        return flag("mentions anyone", "mentions no one");
+      case "tagged":
+        return flag("has any tag", "has no tags");
+      case "attachmentSection": {
+        if (typeof value !== "number" || !ATTACHMENT_SECTIONS[value]) return null;
+        return {
+          type: key,
+          value,
+          name: ATTACHMENT_SECTIONS[value],
+          description: `has ${ATTACHMENT_SECTIONS[value]} attachments`
+        };
+      }
+      case "tag": {
+        if (typeof value !== "string") return null;
+        const names = this.context.tags?.[value] ?? [];
+        const name = names.length === 1 ? names[0] : void 0;
+        return {
+          type: key,
+          value,
+          ...name ? { name } : {},
+          description: `has tag #${name ?? value}`
+        };
+      }
+      case "folder": {
+        if (typeof value !== "string") return null;
+        const folder = this.context.folders?.[value];
+        return {
+          type: key,
+          value,
+          ...folder ? { folderId: folder.id } : {},
+          ...folder?.title ? { name: folder.title } : {},
+          description: folder?.title ? `is in folder "${folder.title}"` : `is in folder ${value}${folder ? "" : " (not found)"}`
+        };
+      }
+      case "sharedParticipant":
+      case "mentionParticipant":
+        return typeof value === "string" ? {
+          type: key,
+          value,
+          description: key === "sharedParticipant" ? `is shared with participant ${value}` : `mentions participant ${value}`
+        } : null;
+      case "creationDateRelativeRange":
+      case "modificationDateRelativeRange": {
+        if (!isClause(value) || typeof value.type !== "number") return null;
+        const verb = key.startsWith("creation") ? "created" : "edited";
+        if (value.type === 6) {
+          const amount = value.customAmount;
+          const unit = typeof value.customUnit === "number" ? CUSTOM_UNITS[value.customUnit] : null;
+          if (typeof amount !== "number" || !unit) return null;
+          return {
+            type: key,
+            value,
+            description: `${verb} in the last ${amount} ${unit}`
+          };
+        }
+        const range = RELATIVE_RANGES[value.type];
+        return range ? { type: key, value, description: `${verb} ${range}` } : null;
+      }
+      case "creationDateRange":
+      case "modificationDateRange": {
+        if (!isClause(value)) return null;
+        const from = cocoaDate(value.fromDate);
+        const to = cocoaDate(value.toDate);
+        if (!from || !to) return null;
+        const verb = key.startsWith("creation") ? "created" : "edited";
+        return {
+          type: key,
+          value,
+          from,
+          to,
+          description: `${verb} between ${from} and ${to}`
+        };
+      }
+      default:
+        return null;
+    }
+  }
+};
+function decodeSmartFolderQuery(raw, context = {}) {
+  if (raw === null || raw.trim() === "") {
+    return { match: null, filters: [], query: null, fullyDecoded: false };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { match: null, filters: [], query: raw, fullyDecoded: false };
+  }
+  const decoder = new Decoder(context);
+  const type = isClause(parsed) ? parsed.type : void 0;
+  if (!isClause(type)) {
+    return {
+      match: null,
+      filters: [decoder.unknown(null, parsed, false)],
+      query: parsed,
+      fullyDecoded: false
+    };
+  }
+  let includesRecentlyDeleted;
+  let inner = [type];
+  if (Object.keys(type).length === 1 && Array.isArray(type.and)) {
+    const wrapper = type.and.find(isDeletedWrapper);
+    if (wrapper) {
+      includesRecentlyDeleted = wrapper.deleted;
+      inner = type.and.filter((clause) => !isDeletedWrapper(clause));
+    }
+  }
+  const query = inner.length === 1 ? inner[0] : { and: inner };
+  let match = "all";
+  let filters;
+  const only = inner.length === 1 && isClause(inner[0]) ? inner[0] : void 0;
+  const onlyKey = only && Object.keys(only).length === 1 ? Object.keys(only)[0] : void 0;
+  if (only && onlyKey === "and" && Array.isArray(only.and)) {
+    filters = decoder.list(only.and, false, 1);
+  } else if (only && onlyKey === "or" && Array.isArray(only.or)) {
+    match = "any";
+    filters = decoder.list(only.or, false, 1);
+  } else if (only && onlyKey === "not" && isClause(only.not) && Object.keys(only.not).length === 1 && Array.isArray(only.not.or)) {
+    match = "none";
+    filters = decoder.list(only.not.or, false, 1);
+  } else {
+    filters = decoder.list(inner, false, 1);
+  }
+  return {
+    match,
+    filters,
+    query,
+    ...includesRecentlyDeleted === void 0 ? {} : { includesRecentlyDeleted },
+    fullyDecoded: decoder.fullyDecoded
+  };
+}
+var SMART_FOLDERS_SQL = `BEGIN;
+SELECT Z_UUID FROM Z_METADATA;
+SELECT json_group_array(json_object(
+  'pk', f.Z_PK,
+  'identifier', f.ZIDENTIFIER,
+  'title', f.ZTITLE2,
+  'folderType', f.ZFOLDERTYPE,
+  'query', f.ZSMARTFOLDERQUERYJSON,
+  'parentPk', p.Z_PK,
+  'parentIdentifier', p.ZIDENTIFIER,
+  'parentTitle', p.ZTITLE2,
+  'accountPk', a.Z_PK,
+  'accountIdentifier', a.ZIDENTIFIER,
+  'accountName', a.ZNAME))
+FROM ZICCLOUDSYNCINGOBJECT f
+LEFT JOIN ZICCLOUDSYNCINGOBJECT p ON p.Z_PK = f.ZPARENT
+LEFT JOIN ZICCLOUDSYNCINGOBJECT a ON a.Z_PK = f.ZOWNER
+WHERE f.Z_ENT = (SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME = 'ICFolder')
+  AND (f.ZFOLDERTYPE = 2 OR f.ZSMARTFOLDERQUERYJSON IS NOT NULL)
+  AND COALESCE(f.ZMARKEDFORDELETION, 0) = 0;
+SELECT json_group_object(ZIDENTIFIER, json_object('pk', Z_PK, 'title', ZTITLE2))
+FROM ZICCLOUDSYNCINGOBJECT
+WHERE Z_ENT = (SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME = 'ICFolder')
+  AND ZIDENTIFIER IS NOT NULL;
+SELECT json_group_array(json_object('standardized', ZSTANDARDIZEDCONTENT, 'display', ZDISPLAYTEXT))
+FROM ZICCLOUDSYNCINGOBJECT
+WHERE Z_ENT = (SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME = 'ICHashtag')
+  AND ZSTANDARDIZEDCONTENT IS NOT NULL
+  AND COALESCE(ZMARKEDFORDELETION, 0) = 0;
+COMMIT;`;
+var REQUIRED_COLUMNS = [
+  "ZIDENTIFIER",
+  "ZTITLE2",
+  "ZFOLDERTYPE",
+  "ZSMARTFOLDERQUERYJSON",
+  "ZPARENT",
+  "ZOWNER",
+  "ZNAME",
+  "ZMARKEDFORDELETION",
+  "ZSTANDARDIZEDCONTENT",
+  "ZDISPLAYTEXT"
+];
+function buildSmartFolders(output) {
+  const lines = output.trim().split("\n");
+  if (lines.length < 4) throw new Error("Unexpected smart folder query output");
+  const [storeUuid, rowsJson, foldersJson, tagsJson] = lines;
+  if (!/^[0-9A-F-]+$/i.test(storeUuid)) throw new Error("Unexpected Notes store identifier");
+  const coreDataId2 = (entity2, pk) => `x-coredata://${storeUuid}/${entity2}/p${pk}`;
+  const rows = JSON.parse(rowsJson);
+  const folderRows = JSON.parse(foldersJson || "{}");
+  const tagRows = JSON.parse(tagsJson || "[]");
+  const folders = {};
+  for (const [identifier, row] of Object.entries(folderRows)) {
+    folders[identifier] = { id: coreDataId2("ICFolder", row.pk), title: row.title };
+  }
+  const tags = {};
+  for (const tag of tagRows) {
+    if (!tag.display) continue;
+    const names = tags[tag.standardized] ||= [];
+    if (!names.includes(tag.display)) names.push(tag.display);
+  }
+  return rows.map((row) => {
+    const decoded = decodeSmartFolderQuery(row.query, { folders, tags });
+    return {
+      id: coreDataId2("ICFolder", row.pk),
+      identifier: row.identifier,
+      name: row.title,
+      account: row.accountName,
+      accountId: row.accountPk === null ? null : coreDataId2("ICAccount", row.accountPk),
+      accountIdentifier: row.accountIdentifier,
+      parent: row.parentTitle,
+      parentId: row.parentPk === null ? null : coreDataId2("ICFolder", row.parentPk),
+      parentIdentifier: row.parentIdentifier,
+      match: decoded.match,
+      filters: decoded.filters,
+      ...decoded.includesRecentlyDeleted === void 0 ? {} : { includesRecentlyDeleted: decoded.includesRecentlyDeleted },
+      fullyDecoded: decoded.fullyDecoded,
+      query: decoded.query,
+      rawQuery: row.query
+    };
+  }).sort(
+    (a, b) => (a.account ?? "").localeCompare(b.account ?? "") || (a.name ?? "").localeCompare(b.name ?? "") || a.id.localeCompare(b.id)
+  );
+}
+function runSqlite(dbPath2, sql) {
+  return execFileSync4("sqlite3", ["-readonly", dbPath2, sql], {
+    encoding: "utf8",
+    timeout: 5e3,
+    maxBuffer: 16 * 1024 * 1024,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+}
+function readSmartFolders(dbPath2 = NOTES_DB_PATH2) {
+  if (!fs2.existsSync(dbPath2)) return { folders: null, error: "no_fda", message: FDA_MESSAGE };
+  try {
+    const columns = new Set(
+      runSqlite(dbPath2, "SELECT name FROM pragma_table_info('ZICCLOUDSYNCINGOBJECT');").trim().split("\n")
+    );
+    const missing = REQUIRED_COLUMNS.filter((column) => !columns.has(column));
+    if (missing.length) {
+      return {
+        folders: null,
+        error: "unsupported_schema",
+        message: `This Notes database does not have the columns smart folders need (${missing.join(", ")}).`
+      };
+    }
+    return { folders: buildSmartFolders(runSqlite(dbPath2, SMART_FOLDERS_SQL)) };
+  } catch (error2) {
+    const message = error2 instanceof Error ? error2.message : String(error2);
+    if (message.includes("authorization denied") || message.includes("unable to open database")) {
+      return { folders: null, error: "no_fda", message: FDA_MESSAGE };
+    }
+    console.error(`Failed to read smart folders: ${message}`);
+    return { folders: null, error: "query_error", message: "Failed to read smart folders." };
+  }
+}
+
 // src/utils/attachmentFs.ts
 import {
-  existsSync as existsSync2,
+  existsSync as existsSync3,
   lstatSync,
   mkdirSync,
   mkdtempSync,
@@ -39850,11 +40233,11 @@ import {
   rmSync,
   statSync
 } from "fs";
-import { dirname, isAbsolute, join as join3, relative, resolve, sep } from "path";
-import { homedir as homedir3, tmpdir } from "os";
+import { dirname, isAbsolute, join as join4, relative, resolve, sep } from "path";
+import { homedir as homedir4, tmpdir } from "os";
 function allowedSaveRoots() {
   return [
-    resolve(homedir3()),
+    resolve(homedir4()),
     resolve(tmpdir()),
     "/Volumes",
     "/private/var/folders",
@@ -39862,8 +40245,8 @@ function allowedSaveRoots() {
     "/private/tmp"
   ];
 }
-function canonicalize(path5) {
-  return realpathSync.native(path5);
+function canonicalize(path7) {
+  return realpathSync.native(path7);
 }
 function isWithinRoots(candidate, roots) {
   return roots.some((root) => {
@@ -39885,9 +40268,9 @@ function canonicalRoots(roots) {
   }
   return canonical;
 }
-function entryExists(path5) {
+function entryExists(path7) {
   try {
-    lstatSync(path5);
+    lstatSync(path7);
     return true;
   } catch (e) {
     const code = e.code;
@@ -39928,7 +40311,7 @@ function assertSafeSavePath(p, roots = allowedSaveRoots()) {
   if (suffix.split(sep).includes("..")) {
     throw new Error(`Refusing to write outside allowed locations (home, temp, /Volumes): "${abs}"`);
   }
-  const canonicalDest = suffix ? join3(canonicalAncestor, suffix) : canonicalAncestor;
+  const canonicalDest = suffix ? join4(canonicalAncestor, suffix) : canonicalAncestor;
   const allowed = canonicalRoots(roots);
   if (!isWithinRoots(canonicalAncestor, allowed) || !isWithinRoots(canonicalDest, allowed)) {
     throw new Error(
@@ -39970,16 +40353,16 @@ function makeTempDir() {
 }
 function cleanupTempDir(dir) {
   try {
-    if (existsSync2(dir)) rmSync(dir, { recursive: true, force: true });
+    if (existsSync3(dir)) rmSync(dir, { recursive: true, force: true });
   } catch {
   }
 }
 
 // src/services/appleNotesManager.ts
 var import_turndown = __toESM(require_turndown_cjs(), 1);
-import { existsSync as existsSync3 } from "fs";
-import { homedir as homedir4 } from "os";
-import { join as join4 } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { homedir as homedir5 } from "os";
+import { join as join5 } from "path";
 var FIELD_SEP = "";
 var RECORD_SEP = "";
 var AS_FIELD_SEP = "(character id 31)";
@@ -40203,12 +40586,12 @@ function buildAppLevelScript(command) {
     end tell
   `;
 }
-function getNoteLinkFromDB(coreDataId) {
-  const match = coreDataId.match(/\/p(\d+)$/);
+function getNoteLinkFromDB(coreDataId2) {
+  const match = coreDataId2.match(/\/p(\d+)$/);
   if (!match) return null;
   const pk = parseInt(match[1], 10);
-  const dbPath2 = join4(homedir4(), "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite");
-  if (!existsSync3(dbPath2)) return null;
+  const dbPath2 = join5(homedir5(), "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite");
+  if (!existsSync4(dbPath2)) return null;
   try {
     const { DatabaseSync } = __require("node:sqlite");
     const db = new DatabaseSync(dbPath2, { readOnly: true });
@@ -40849,6 +41232,58 @@ var AppleNotesManager = class {
         return resultList as text
       `;
   }
+  /**
+   * Lists every smart folder with its decoded query, read-only.
+   *
+   * Folder metadata and queries come from the NoteStore database (Full Disk
+   * Access). With `includeMatchingNotes`, Notes.app itself is asked which notes
+   * each smart folder currently shows, so membership reflects Notes' own
+   * evaluation of the query rather than a reimplementation of it.
+   *
+   * @param options.includeMatchingNotes - Also list the notes each folder shows
+   * @param options.limit - Maximum matching notes per folder (default 50)
+   * @throws Error when the database cannot be read (message says why)
+   */
+  listSmartFolders(options = {}) {
+    const result = readSmartFolders();
+    if (!result.folders) throw new Error(result.message || "Failed to read smart folders.");
+    if (!options.includeMatchingNotes) return result.folders;
+    const limit = options.limit ?? 50;
+    return result.folders.map((folder) => {
+      try {
+        const { total, notes } = this.listSmartFolderNoteRefs(folder.id, limit);
+        return { ...folder, matchingNoteCount: total, matchingNotes: notes };
+      } catch (error2) {
+        return {
+          ...folder,
+          matchingNotesError: error2 instanceof Error ? error2.message : String(error2)
+        };
+      }
+    });
+  }
+  /**
+   * Asks Notes.app for the notes one smart folder currently shows.
+   *
+   * @returns The folder's total note count and up to `limit` (title, id) pairs
+   */
+  listSmartFolderNoteRefs(folderId2, limit) {
+    if (!/^x-coredata:\/\/[0-9a-f-]+\/ICFolder\/p\d+$/i.test(folderId2))
+      throw new Error("An exact folder ID is required");
+    const safeLimit = Math.max(1, Math.floor(limit));
+    const script = buildAppLevelScript(
+      this.buildBulkListCommand({ folderRef: `folder id "${folderId2}"`, sliceLimit: safeLimit })
+    );
+    const result = executeAppleScript(script);
+    if (!result.success) {
+      throw new Error(`Failed to list smart folder notes: ${result.error ?? "unknown error"}`);
+    }
+    const sepIdx = result.output.indexOf(RECORD_SEP);
+    const header = sepIdx === -1 ? result.output : result.output.slice(0, sepIdx);
+    const total = Number.parseInt(header.trim(), 10);
+    if (Number.isNaN(total)) throw new Error("Unexpected smart folder listing output");
+    const records = sepIdx === -1 ? "" : result.output.slice(sepIdx + 1);
+    return { total, notes: this.parseBulkListOutput(records, safeLimit) };
+  }
   /**
    * Parses bulk listing output into deduplicated (title, id) pairs.
    *
@@ -41206,9 +41641,9 @@ var AppleNotesManager = class {
     );
     const idResult = executeAppleScript(idScript);
     const [rawId = "", rawAccount = ""] = idResult.success ? idResult.output.split(FIELD_SEP) : [];
-    const folderId = idResult.success ? extractCoreDataId(rawId, "folder") : "";
+    const folderId2 = idResult.success ? extractCoreDataId(rawId, "folder") : "";
     return {
-      id: folderId,
+      id: folderId2,
       name,
       account: rawAccount.trim() || targetAccount || ""
     };
@@ -42009,7 +42444,7 @@ var AppleNotesManager = class {
     if (parts[0] !== "OK") {
       return { success: false, error: parts[1]?.trim() || "attachment not found" };
     }
-    if (!existsSync3(abs) || fileSize(abs) === 0) {
+    if (!existsSync4(abs) || fileSize(abs) === 0) {
       return { success: false, error: `Notes reported success but no file was written to ${abs}` };
     }
     return {
@@ -42452,15 +42887,15 @@ var AppleNotesManager = class {
 };
 
 // src/utils/syncDetection.ts
-import { execFileSync as execFileSync4 } from "child_process";
-import * as fs2 from "fs";
-import * as path2 from "path";
-import * as os2 from "os";
-var NOTES_DB_PATH2 = path2.join(
-  os2.homedir(),
+import { execFileSync as execFileSync5 } from "child_process";
+import * as fs3 from "fs";
+import * as path3 from "path";
+import * as os3 from "os";
+var NOTES_DB_PATH3 = path3.join(
+  os3.homedir(),
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
 );
-var WAL_PATH = `${NOTES_DB_PATH2}-wal`;
+var WAL_PATH = `${NOTES_DB_PATH3}-wal`;
 var RECENT_ACTIVITY_THRESHOLD_SECONDS = 5;
 var SYNC_STATUS_CACHE_TTL_MS = 2e3;
 var cachedSyncStatus = null;
@@ -42476,14 +42911,14 @@ function getSyncStatus(useCache = true) {
     recentActivity: false
   };
   try {
-    if (!fs2.existsSync(NOTES_DB_PATH2)) {
+    if (!fs3.existsSync(NOTES_DB_PATH3)) {
       status.error = "Notes database not found";
       cachedSyncStatus = status;
       cacheTimestamp = Date.now();
       return status;
     }
-    if (fs2.existsSync(WAL_PATH)) {
-      const walStats = fs2.statSync(WAL_PATH);
+    if (fs3.existsSync(WAL_PATH)) {
+      const walStats = fs3.statSync(WAL_PATH);
       const secondsAgo = (Date.now() - walStats.mtimeMs) / 1e3;
       status.secondsSinceLastChange = Math.round(secondsAgo);
       status.recentActivity = secondsAgo < RECENT_ACTIVITY_THRESHOLD_SECONDS;
@@ -42497,9 +42932,9 @@ function getSyncStatus(useCache = true) {
         WHERE object.ZCLOUDSTATE = state.Z_PK
       );
     `;
-    const result = execFileSync4(
+    const result = execFileSync5(
       "sqlite3",
-      ["-readonly", NOTES_DB_PATH2, query.replace(/\n/g, " ")],
+      ["-readonly", NOTES_DB_PATH3, query.replace(/\n/g, " ")],
       {
         encoding: "utf8",
         timeout: 5e3,
@@ -42556,15 +42991,15 @@ function withSyncAwarenessSync(operation, fn) {
 }
 
 // src/utils/noteMetadata.ts
-import { execFileSync as execFileSync5 } from "child_process";
-import * as fs3 from "fs";
-import * as path3 from "path";
-import * as os3 from "os";
-var NOTES_DB_PATH3 = path3.join(
-  os3.homedir(),
+import { execFileSync as execFileSync6 } from "child_process";
+import * as fs4 from "fs";
+import * as path4 from "path";
+import * as os4 from "os";
+var NOTES_DB_PATH4 = path4.join(
+  os4.homedir(),
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
 );
-var FDA_MESSAGE = `Full Disk Access is required to read note metadata. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
+var FDA_MESSAGE2 = `Full Disk Access is required to read note metadata. In System Settings > Privacy & Security > Full Disk Access, grant access to the app that launches this server (Claude Desktop / Terminal / iTerm2), then fully quit and relaunch it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL} \u2014 run the doctor tool to verify.`;
 var COLUMN_MAP = [
   { key: "pinned", column: "ZISPINNED", type: "bool" },
   { key: "hasChecklist", column: "ZHASCHECKLIST", type: "bool" },
@@ -42576,15 +43011,15 @@ var COLUMN_MAP = [
   { key: "widgetSnippet", column: "ZWIDGETSNIPPET", type: "text" },
   { key: "smartFolderQuery", column: "ZSMARTFOLDERQUERYJSON", type: "text" }
 ];
-function runSqlite(query) {
-  return execFileSync5("sqlite3", ["-readonly", NOTES_DB_PATH3, query], {
+function runSqlite2(query) {
+  return execFileSync6("sqlite3", ["-readonly", NOTES_DB_PATH4, query], {
     encoding: "utf8",
     timeout: 5e3,
     stdio: ["pipe", "pipe", "pipe"]
   }).trim();
 }
 function presentColumns() {
-  const out = runSqlite("PRAGMA table_info(ZICCLOUDSYNCINGOBJECT);");
+  const out = runSqlite2("PRAGMA table_info(ZICCLOUDSYNCINGOBJECT);");
   const cols = /* @__PURE__ */ new Set();
   for (const line of out.split("\n")) {
     const name = line.split("|")[1];
@@ -42602,8 +43037,8 @@ function getNoteMetadata(noteId3) {
     };
   }
   const pk = pkMatch[1];
-  if (!fs3.existsSync(NOTES_DB_PATH3)) {
-    return { metadata: null, error: "no_fda", message: FDA_MESSAGE };
+  if (!fs4.existsSync(NOTES_DB_PATH4)) {
+    return { metadata: null, error: "no_fda", message: FDA_MESSAGE2 };
   }
   try {
     const available = presentColumns();
@@ -42612,7 +43047,7 @@ function getNoteMetadata(noteId3) {
       return { metadata: {} };
     }
     const pairs = selected.map((c) => `'${c.key}', ${c.column}`).join(", ");
-    const row = runSqlite(
+    const row = runSqlite2(
       `SELECT json_object(${pairs}) FROM ZICCLOUDSYNCINGOBJECT WHERE Z_PK = ${pk};`
     );
     if (!row) {
@@ -42637,13 +43072,251 @@ function getNoteMetadata(noteId3) {
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     if (message.includes("authorization denied") || message.includes("unable to open database")) {
-      return { metadata: null, error: "no_fda", message: FDA_MESSAGE };
+      return { metadata: null, error: "no_fda", message: FDA_MESSAGE2 };
     }
     console.error(`Failed to read note metadata: ${message}`);
     return { metadata: null, error: "query_error", message: "Failed to read note metadata." };
   }
 }
 
+// src/utils/noteIdentifiers.ts
+import { execFileSync as execFileSync7 } from "child_process";
+import * as fs5 from "fs";
+import * as os5 from "os";
+import * as path5 from "path";
+var NOTES_DB_PATH5 = path5.join(
+  os5.homedir(),
+  "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
+);
+var UUID_PATTERN = /^[0-9A-Fa-f]{8}(?:-[0-9A-Fa-f]{4}){3}-[0-9A-Fa-f]{12}$/;
+var NUMERIC_KEY_PATTERN = /^\d{1,18}$/;
+var NOTE_ID_MESSAGE = "A canonical Apple Note ID is required (x-coredata://.../ICNote/p...), or the note's Notes UUID or numeric key";
+function identifierForm(value) {
+  if (UUID_PATTERN.test(value)) return "uuid";
+  if (NUMERIC_KEY_PATTERN.test(value)) return "key";
+  return "other";
+}
+function isAlternateIdentifier(value) {
+  return identifierForm(value) !== "other";
+}
+var IdentifierResolutionError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "IdentifierResolutionError";
+  }
+  code;
+};
+var ENTITY_LABEL = {
+  ICNote: "note",
+  ICFolder: "folder",
+  ICAccount: "account"
+};
+var NO_FDA_MESSAGE = `Resolving a Notes UUID or numeric key reads the Notes database, which needs Full Disk Access for the app that launches this server (System Settings > Privacy & Security > Full Disk Access, then fully quit and relaunch it). x-coredata ids from search-notes, list-notes, or list-folders work without it. Setup guide: ${FULL_DISK_ACCESS_GUIDE_URL}`;
+function canonicalKey(value) {
+  return BigInt(value).toString();
+}
+function assertAll(values, pattern, label) {
+  for (const value of values) {
+    if (!pattern.test(value)) throw new Error(`Refusing to query with an invalid ${label}`);
+  }
+}
+function entityClause(entity2) {
+  return `(SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME = '${entity2}')`;
+}
+function buildResolveSql(entity2, keys, uuids) {
+  assertAll(keys, NUMERIC_KEY_PATTERN, "numeric key");
+  assertAll(uuids, UUID_PATTERN, "UUID");
+  const matches = [];
+  if (keys.length > 0) {
+    matches.push(`o.Z_PK IN (${[...new Set(keys.map(canonicalKey))].join(", ")})`);
+  }
+  if (uuids.length > 0) {
+    const variants = /* @__PURE__ */ new Set();
+    for (const uuid2 of uuids) {
+      variants.add(uuid2);
+      variants.add(uuid2.toUpperCase());
+      variants.add(uuid2.toLowerCase());
+    }
+    matches.push(`o.ZIDENTIFIER IN (${[...variants].map((v) => `'${v}'`).join(", ")})`);
+  }
+  const where = matches.length > 0 ? matches.join(" OR ") : "0";
+  return `SELECT json_object('store', (SELECT Z_UUID FROM Z_METADATA LIMIT 1), 'rows', (SELECT json_group_array(json_object('pk', o.Z_PK, 'identifier', o.ZIDENTIFIER)) FROM ZICCLOUDSYNCINGOBJECT o WHERE o.Z_ENT = ${entityClause(entity2)} AND (${where})));`;
+}
+function buildLookupSql(entity2, keys) {
+  assertAll(keys, NUMERIC_KEY_PATTERN, "numeric key");
+  const pks = [...new Set(keys.map(canonicalKey))];
+  const inList = pks.length > 0 ? pks.join(", ") : "NULL";
+  let fields = "'pk', o.Z_PK, 'identifier', o.ZIDENTIFIER";
+  let joins = "";
+  if (entity2 === "ICNote") {
+    fields += ", 'folderIdentifier', f.ZIDENTIFIER, 'accountIdentifier', a.ZIDENTIFIER";
+    joins = "LEFT JOIN ZICCLOUDSYNCINGOBJECT f ON f.Z_PK = o.ZFOLDER LEFT JOIN ZICCLOUDSYNCINGOBJECT a ON a.Z_PK = f.ZOWNER ";
+  } else if (entity2 === "ICFolder") {
+    fields += ", 'parentIdentifier', p.ZIDENTIFIER, 'accountIdentifier', a.ZIDENTIFIER";
+    joins = "LEFT JOIN ZICCLOUDSYNCINGOBJECT p ON p.Z_PK = o.ZPARENT LEFT JOIN ZICCLOUDSYNCINGOBJECT a ON a.Z_PK = o.ZOWNER ";
+  }
+  return `SELECT json_object('store', (SELECT Z_UUID FROM Z_METADATA LIMIT 1), 'rows', (SELECT json_group_array(json_object(${fields})) FROM ZICCLOUDSYNCINGOBJECT o ${joins}WHERE o.Z_ENT = ${entityClause(entity2)} AND o.Z_PK IN (${inList})));`;
+}
+function runJsonQuery(sql, dbPath2) {
+  if (!fs5.existsSync(dbPath2)) throw new IdentifierResolutionError("no_fda", NO_FDA_MESSAGE);
+  let out;
+  try {
+    out = execFileSync7("sqlite3", ["-readonly", dbPath2, sql], {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+  } catch (error2) {
+    const detail = error2 instanceof Error ? `${error2.message} ${String(error2.stderr ?? "")}` : String(error2);
+    if (detail.includes("authorization denied") || detail.includes("unable to open database")) {
+      throw new IdentifierResolutionError("no_fda", NO_FDA_MESSAGE);
+    }
+    console.error(`Identifier query failed: ${detail}`);
+    throw new IdentifierResolutionError("query_error", "Failed to read the Notes database.");
+  }
+  const parsed = JSON.parse(out || "{}");
+  const rows = typeof parsed.rows === "string" ? JSON.parse(parsed.rows) : parsed.rows;
+  return { store: parsed.store ?? null, rows: rows ?? [] };
+}
+function coreDataId(store, entity2, pk) {
+  return `x-coredata://${store}/${entity2}/p${pk}`;
+}
+function resolveIdentifiers(values, entity2, dbPath2 = NOTES_DB_PATH5) {
+  const resolved = /* @__PURE__ */ new Map();
+  const keys = [];
+  const uuids = [];
+  for (const value of values) {
+    const form = identifierForm(value);
+    if (form === "key") keys.push(value);
+    else if (form === "uuid") uuids.push(value);
+    else resolved.set(value, value);
+  }
+  if (keys.length === 0 && uuids.length === 0) return resolved;
+  const { store, rows } = runJsonQuery(
+    buildResolveSql(entity2, keys, uuids),
+    dbPath2
+  );
+  if (!store) {
+    throw new IdentifierResolutionError(
+      "query_error",
+      "The Notes database has no store UUID, so an x-coredata id cannot be built."
+    );
+  }
+  const byKey = new Map(rows.map((row) => [String(row.pk), row]));
+  const byUuid = new Map(
+    rows.filter((row) => row.identifier).map((row) => [String(row.identifier).toUpperCase(), row])
+  );
+  const label = ENTITY_LABEL[entity2];
+  const missing = [];
+  for (const key of keys) {
+    const row = byKey.get(canonicalKey(key));
+    if (row) resolved.set(key, coreDataId(store, entity2, row.pk));
+    else missing.push(`numeric key ${key}`);
+  }
+  for (const uuid2 of uuids) {
+    const row = byUuid.get(uuid2.toUpperCase());
+    if (row) resolved.set(uuid2, coreDataId(store, entity2, row.pk));
+    else missing.push(`identifier ${uuid2}`);
+  }
+  if (missing.length > 0) {
+    throw new IdentifierResolutionError(
+      "not_found",
+      `No ${label} found for ${missing.join(", ")}. A numeric key must belong to a ${label}, not another object type.`
+    );
+  }
+  return resolved;
+}
+var COREDATA_PARTS = /^x-coredata:\/\/([0-9A-Fa-f-]+)\/(ICNote|ICFolder|ICAccount)\/p(\d{1,18})$/;
+function lookupStableIdentifiers(ids, entity2, dbPath2 = NOTES_DB_PATH5) {
+  const result = /* @__PURE__ */ new Map();
+  const wanted = /* @__PURE__ */ new Map();
+  for (const id2 of ids) {
+    const match = COREDATA_PARTS.exec(id2);
+    if (!match || match[2] !== entity2) continue;
+    const pk = canonicalKey(match[3]);
+    const list = wanted.get(pk) ?? [];
+    list.push({ id: id2, store: match[1] });
+    wanted.set(pk, list);
+  }
+  if (wanted.size === 0) return result;
+  let query;
+  try {
+    query = runJsonQuery(buildLookupSql(entity2, [...wanted.keys()]), dbPath2);
+  } catch {
+    return result;
+  }
+  const store = query.store?.toUpperCase();
+  for (const row of query.rows) {
+    const fields = {};
+    for (const key of [
+      "identifier",
+      "folderIdentifier",
+      "parentIdentifier",
+      "accountIdentifier"
+    ]) {
+      const value = row[key];
+      if (typeof value === "string" && value) fields[key] = value;
+    }
+    for (const target of wanted.get(String(row.pk)) ?? []) {
+      if (target.store.toUpperCase() === store) result.set(target.id, fields);
+    }
+  }
+  return result;
+}
+function withStableIdentifiers(items, entity2, dbPath2 = NOTES_DB_PATH5) {
+  const ids = items.map((item) => item.id).filter((id2) => typeof id2 === "string");
+  if (ids.length === 0) return items;
+  const found = lookupStableIdentifiers(ids, entity2, dbPath2);
+  if (found.size === 0) return items;
+  return items.map(
+    (item) => item.id && found.has(item.id) ? { ...item, ...found.get(item.id) } : item
+  );
+}
+var defaultResolver = (values, entity2) => resolveIdentifiers(values, entity2);
+var DEFAULT_MAX_ID_LENGTH = 2e3;
+function acceptAlternateForms(pattern) {
+  return new RegExp(
+    `${pattern.source}|${UUID_PATTERN.source}|${NUMERIC_KEY_PATTERN.source}`,
+    pattern.flags
+  );
+}
+function resolveInSchema(values, entity2, ctx, resolver) {
+  if (!values.some(isAlternateIdentifier)) return new Map(values.map((v) => [v, v]));
+  try {
+    return resolver(values, entity2);
+  } catch (error2) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      message: error2 instanceof Error ? error2.message : String(error2)
+    });
+    return null;
+  }
+}
+function exactIdInput(entity2, pattern, message, options = {}) {
+  const resolver = options.resolver ?? defaultResolver;
+  return external_exports.string().max(options.maxLength ?? DEFAULT_MAX_ID_LENGTH).regex(acceptAlternateForms(pattern), message).transform((value, ctx) => {
+    const map = resolveInSchema([value], entity2, ctx, resolver);
+    return map ? map.get(value) ?? value : external_exports.NEVER;
+  });
+}
+function exactIdArrayInput(entity2, pattern, message, options = {}) {
+  const resolver = options.resolver ?? defaultResolver;
+  const item = external_exports.string().max(options.maxLength ?? DEFAULT_MAX_ID_LENGTH).regex(acceptAlternateForms(pattern), message);
+  const array2 = options.maxItems === void 0 ? external_exports.array(item) : external_exports.array(item).max(options.maxItems);
+  return array2.transform((values, ctx) => {
+    const map = resolveInSchema(values, entity2, ctx, resolver);
+    return map ? values.map((value) => map.get(value) ?? value) : external_exports.NEVER;
+  });
+}
+function looseIdTransform(entity2, resolver = defaultResolver) {
+  return (value, ctx) => {
+    if (!isAlternateIdentifier(value)) return value;
+    const map = resolveInSchema([value], entity2, ctx, resolver);
+    return map ? map.get(value) ?? value : external_exports.NEVER;
+  };
+}
+
 // src/utils/contentWarnings.ts
 function detectChecklistAttempt(content) {
   if (!content) return null;
@@ -43179,13 +43852,13 @@ function positiveTextTerms(node, negated = false) {
 }
 
 // src/utils/noteQueryStore.ts
-import { execFileSync as execFileSync6 } from "child_process";
-import * as fs4 from "fs";
-import * as os4 from "os";
-import * as path4 from "path";
+import { execFileSync as execFileSync8 } from "child_process";
+import * as fs6 from "fs";
+import * as os6 from "os";
+import * as path6 from "path";
 import { gunzipSync as gunzipSync3 } from "zlib";
-var NOTES_DB_PATH4 = path4.join(
-  os4.homedir(),
+var NOTES_DB_PATH6 = path6.join(
+  os6.homedir(),
   "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite"
 );
 var QUERY_SCAN = { DEFAULT: 500, MAX: 5e3 };
@@ -43272,13 +43945,13 @@ function countWords(text) {
   }
   return count;
 }
-var REQUIRED_COLUMNS = ["Z_PK", "Z_ENT", "ZTITLE1", "ZFOLDER", "ZMODIFICATIONDATE1"];
+var REQUIRED_COLUMNS2 = ["Z_PK", "Z_ENT", "ZTITLE1", "ZFOLDER", "ZMODIFICATIONDATE1"];
 function col(available, alias, name) {
   return available.has(name) ? `${alias}.${name}` : "NULL";
 }
 var entity = (name) => `(SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME='${name}')`;
 function buildScanSql(available, options) {
-  const missing = REQUIRED_COLUMNS.filter((c) => !available.has(c));
+  const missing = REQUIRED_COLUMNS2.filter((c) => !available.has(c));
   if (missing.length) {
     throw new NoteQueryStoreError(
       `This macOS version's Notes database lacks columns query-notes needs (${missing.join(", ")}).`,
@@ -43319,8 +43992,8 @@ function buildScanSql(available, options) {
     "COMMIT;"
   ].join(" ");
 }
-function runSqlite2(dbPath2, query) {
-  return execFileSync6("sqlite3", ["-readonly", dbPath2, query], {
+function runSqlite3(dbPath2, query) {
+  return execFileSync8("sqlite3", ["-readonly", dbPath2, query], {
     encoding: "utf8",
     timeout: 3e4,
     maxBuffer: 512 * 1024 * 1024,
@@ -43329,7 +44002,7 @@ function runSqlite2(dbPath2, query) {
 }
 function presentColumns2(dbPath2) {
   const cols = /* @__PURE__ */ new Set();
-  for (const line of runSqlite2(dbPath2, "PRAGMA table_info(ZICCLOUDSYNCINGOBJECT);").split("\n")) {
+  for (const line of runSqlite3(dbPath2, "PRAGMA table_info(ZICCLOUDSYNCINGOBJECT);").split("\n")) {
     const name = line.split("|")[1];
     if (name) cols.add(name);
   }
@@ -43347,12 +44020,12 @@ function resolveFolders(rows) {
     seen.add(pk);
     const parent = row.parent !== null ? resolve3(row.parent, seen) : void 0;
     const name = row.name ?? "";
-    const path5 = parent ? `${parent.path}/${escapeSegment(name)}` : escapeSegment(name);
+    const path7 = parent ? `${parent.path}/${escapeSegment(name)}` : escapeSegment(name);
     const plainPath = parent ? `${parent.plainPath}/${name}` : name;
     const info = {
-      path: path5,
+      path: path7,
       plainPath,
-      keys: [...new Set([name, plainPath, path5].map(normalizeForMatch))],
+      keys: [...new Set([name, plainPath, path7].map(normalizeForMatch))],
       accountPk: row.owner ?? parent?.accountPk ?? null,
       shared: Boolean(row.shared) || Boolean(parent?.shared)
     };
@@ -43384,12 +44057,12 @@ function queryNotes(expression, options = {}) {
   const includeDeleted = options.includeDeleted ?? false;
   const withBodies = needsContent(ast);
   const withTags = needsTags(ast);
-  const dbPath2 = options.dbPath ?? NOTES_DB_PATH4;
-  if (!fs4.existsSync(dbPath2)) throw new NoteQueryStoreError(QUERY_FDA_MESSAGE, "no_fda");
+  const dbPath2 = options.dbPath ?? NOTES_DB_PATH6;
+  if (!fs6.existsSync(dbPath2)) throw new NoteQueryStoreError(QUERY_FDA_MESSAGE, "no_fda");
   let output;
   try {
     const available = presentColumns2(dbPath2);
-    output = runSqlite2(
+    output = runSqlite3(
       dbPath2,
       buildScanSql(available, { scanLimit, includeDeleted, withBodies, withTags })
     );
@@ -43520,10 +44193,10 @@ function queryNotes(expression, options = {}) {
 import { spawnSync } from "child_process";
 
 // src/services/nativeTags.ts
-import { execFileSync as execFileSync7 } from "node:child_process";
+import { execFileSync as execFileSync9 } from "node:child_process";
 import { mkdtempSync as mkdtempSync2, writeFileSync, rmSync as rmSync2 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
-import { join as join8 } from "node:path";
+import { join as join10 } from "node:path";
 
 // src/services/shortcutConsent.ts
 function shortcutConsentHint(shortcut) {
@@ -43599,7 +44272,7 @@ function addNativeTags(request, deps) {
   };
 }
 function listInstalledShortcuts() {
-  return execFileSync7("/usr/bin/shortcuts", ["list", "--show-identifiers"], {
+  return execFileSync9("/usr/bin/shortcuts", ["list", "--show-identifiers"], {
     encoding: "utf8",
     timeout: 15e3,
     maxBuffer: 1024 * 1024,
@@ -43625,11 +44298,11 @@ function runNativeTagsShortcut(input) {
   const status = nativeTagsStatus();
   if (!status.installed)
     throw new Error(`Import the supplied ${status.shortcut}.shortcut in Shortcuts first`);
-  const directory = mkdtempSync2(join8(tmpdir2(), "apple-notes-native-tags-"));
+  const directory = mkdtempSync2(join10(tmpdir2(), "apple-notes-native-tags-"));
   try {
-    const path5 = join8(directory, "request.json");
-    writeFileSync(path5, JSON.stringify(input), { mode: 384 });
-    execFileSync7("/usr/bin/shortcuts", ["run", status.identifier, "--input-path", path5], {
+    const path7 = join10(directory, "request.json");
+    writeFileSync(path7, JSON.stringify(input), { mode: 384 });
+    execFileSync9("/usr/bin/shortcuts", ["run", status.identifier, "--input-path", path7], {
       encoding: "utf8",
       timeout: 6e4,
       maxBuffer: 1024 * 1024,
@@ -43648,10 +44321,10 @@ function runNativeTagsShortcut(input) {
 }
 
 // src/services/backgroundNotes.ts
-import { execFileSync as execFileSync8 } from "node:child_process";
+import { execFileSync as execFileSync10 } from "node:child_process";
 import { mkdtempSync as mkdtempSync3, writeFileSync as writeFileSync2, rmSync as rmSync3 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join9 } from "node:path";
+import { join as join11 } from "node:path";
 
 // src/utils/appendMarkdown.ts
 var escape2 = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -43840,9 +44513,9 @@ function runBackgroundShortcut(input, status = backgroundStatus()) {
     throw new Error(
       `Install the supplied "${status.shortcut}" Shortcut once; Shortcuts must list it exactly once`
     );
-  const directory = mkdtempSync3(join9(tmpdir3(), "apple-notes-background-"));
+  const directory = mkdtempSync3(join11(tmpdir3(), "apple-notes-background-"));
   try {
-    const file = join9(directory, "request.json");
+    const file = join11(directory, "request.json");
     writeFileSync2(
       file,
       JSON.stringify({
@@ -43862,7 +44535,7 @@ function runBackgroundShortcut(input, status = backgroundStatus()) {
       { mode: 384 }
     );
     try {
-      execFileSync8("/usr/bin/shortcuts", ["run", status.identifier, "--input-path", file], {
+      execFileSync10("/usr/bin/shortcuts", ["run", status.identifier, "--input-path", file], {
         encoding: "utf8",
         timeout: 6e4,
         maxBuffer: 1024 * 1024,
@@ -44065,7 +44738,7 @@ function createMarkdownNote(manager, request, run = runBackgroundShortcut) {
     throw new Error(
       `Install the supplied "${status.shortcut}" Shortcut once; Shortcuts must list it exactly once`
     );
-  const segments = (path5) => JSON.stringify(splitFolderPath(path5).map((part) => part.toLocaleLowerCase()));
+  const segments = (path7) => JSON.stringify(splitFolderPath(path7).map((part) => part.toLocaleLowerCase()));
   if (request.folder) {
     const wanted = segments(request.folder);
     if (!manager.listAccounts().some(
@@ -44154,7 +44827,7 @@ ${request.content}`
 }
 
 // src/services/capabilityMatrix.ts
-import { execFileSync as execFileSync9 } from "node:child_process";
+import { execFileSync as execFileSync11 } from "node:child_process";
 import { release } from "node:os";
 var MACOS_SHORTCUTS_CLI = "12.0";
 var MACOS_MARKDOWN_IMPORT = "26.0";
@@ -44361,7 +45034,7 @@ function evaluateFeatures(env, features = FEATURES) {
 function readMacOSVersion() {
   if (process.platform !== "darwin") return null;
   try {
-    const out = execFileSync9("/usr/bin/sw_vers", ["-productVersion"], {
+    const out = execFileSync11("/usr/bin/sw_vers", ["-productVersion"], {
       encoding: "utf8",
       timeout: 3e3,
       stdio: ["ignore", "pipe", "ignore"]
@@ -44394,9 +45067,9 @@ function getCapabilityMatrix(probe = probeCapabilityEnvironment) {
   return evaluateFeatures(probe());
 }
 function formatCapabilityMatrix(matrix) {
-  const os5 = matrix.runtimeOS;
+  const os7 = matrix.runtimeOS;
   const lines = [
-    `Feature matrix (macOS ${os5.macOSVersion ?? "unknown"}, Darwin ${os5.darwinRelease}):`
+    `Feature matrix (macOS ${os7.macOSVersion ?? "unknown"}, Darwin ${os7.darwinRelease}):`
   ];
   for (const [name, status] of Object.entries(matrix.features)) {
     lines.push(
@@ -44514,19 +45187,19 @@ function formatDoctorReport(r) {
 }
 
 // src/services/fileConfig.ts
-import { existsSync as existsSync7, readFileSync as readFileSync2 } from "fs";
-import { join as join10 } from "path";
-import { homedir as homedir8 } from "os";
+import { existsSync as existsSync9, readFileSync as readFileSync2 } from "fs";
+import { join as join12 } from "path";
+import { homedir as homedir10 } from "os";
 function fileConfigPath(env = process.env) {
   const override = env.APPLE_NOTES_MCP_CONFIG_FILE;
   if (override && override.trim()) return override.trim();
-  return join10(homedir8(), "Library", "Application Support", "apple-notes-mcp", "config.json");
+  return join12(homedir10(), "Library", "Application Support", "apple-notes-mcp", "config.json");
 }
-function loadFileConfig(env = process.env, path5 = fileConfigPath(env)) {
+function loadFileConfig(env = process.env, path7 = fileConfigPath(env)) {
   const applied = [];
   try {
-    if (!existsSync7(path5)) return applied;
-    const parsed = JSON.parse(readFileSync2(path5, "utf8"));
+    if (!existsSync9(path7)) return applied;
+    const parsed = JSON.parse(readFileSync2(path7, "utf8"));
     if (!parsed || typeof parsed !== "object") return applied;
     for (const [k, v] of Object.entries(parsed)) {
       if (typeof v !== "string") continue;
@@ -44536,7 +45209,7 @@ function loadFileConfig(env = process.env, path5 = fileConfigPath(env)) {
       }
     }
   } catch (e) {
-    console.error(`Failed to load apple-notes-mcp config file ${path5}: ${String(e)}`);
+    console.error(`Failed to load apple-notes-mcp config file ${path7}: ${String(e)}`);
   }
   return applied;
 }
@@ -45047,9 +45720,14 @@ import {
   writeFileSync as writeFileSync3
 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { basename, isAbsolute as isAbsolute2, join as join11 } from "node:path";
-var noteId = external_exports.string().regex(/^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i);
+import { basename, isAbsolute as isAbsolute2, join as join13 } from "node:path";
+var noteId = exactIdInput(
+  "ICNote",
+  /^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i,
+  NOTE_ID_MESSAGE
+);
 var revision = external_exports.string().regex(/^sha256:[a-f0-9]{64}$/);
+var folderId = external_exports.string().max(2e3).transform(looseIdTransform("ICFolder"));
 function readSnapshot(manager, id2) {
   const note = manager.getNoteById(id2);
   if (!note) throw new Error("Note not found");
@@ -45085,9 +45763,9 @@ function assertExistingContentPreserved(before, after) {
       throw new Error("Existing native object content or presentation changed");
   }
 }
-function localAttachment(path5) {
-  if (!isAbsolute2(path5)) throw new Error("An absolute local file path is required");
-  const descriptor = openSync(path5, constants.O_RDONLY | constants.O_NOFOLLOW);
+function localAttachment(path7) {
+  if (!isAbsolute2(path7)) throw new Error("An absolute local file path is required");
+  const descriptor = openSync(path7, constants.O_RDONLY | constants.O_NOFOLLOW);
   try {
     const stat = fstatSync(descriptor);
     if (!stat.isFile() || stat.size === 0 || stat.size > 64 * 1024 * 1024)
@@ -45126,15 +45804,18 @@ function registerDirectOperations(server2, manager) {
   tool(
     "get-folder-by-id",
     "Use when: reading the exact folder name and parent before a guarded rename.\nReturns: folder id, current name, and parent id.\nDo not use when: listing folders by path (list-folders).\nSafety: read-only.",
-    { id: external_exports.string().max(2e3) },
-    ({ id: id2 }) => manager.getFolderById(id2),
+    { id: folderId },
+    ({ id: id2 }) => {
+      const folder = manager.getFolderById(id2);
+      return { ...folder, ...lookupStableIdentifiers([folder.id], "ICFolder").get(folder.id) };
+    },
     true
   );
   tool(
     "rename-folder",
     "Use when: renaming one previously read folder in place.\nReturns: the unchanged folder id, new name, and parent id after readback.\nDo not use when: creating, moving, or deleting a folder.\nSafety: requires the expected current name and parent; refuses stale metadata and sibling conflicts.",
     {
-      id: external_exports.string().max(2e3),
+      id: folderId,
       expectedName: external_exports.string().max(1e3),
       expectedParentId: external_exports.string().max(2e3),
       newName: external_exports.string().min(1).max(1e3)
@@ -45148,13 +45829,13 @@ function registerDirectOperations(server2, manager) {
     "add-attachment",
     "Use when: adding one local file to an exact note without replacing its body.\nReturns: the new attachment id, byte count, and post-write content hash after exact byte verification.\nDo not use when: reading or exporting an existing attachment.\nSafety: requires a fresh rich revision, copies at most 64 MiB through a private temporary file, never retries insertion, and verifies existing content plus fetched bytes.",
     { id: noteId, expectedContentHash: revision, path: external_exports.string().min(1).max(4096) },
-    ({ id: id2, expectedContentHash, path: path5 }) => {
+    ({ id: id2, expectedContentHash, path: path7 }) => {
       const before = readSnapshot(manager, id2);
       if (before.hash !== expectedContentHash) throw new Error("Note revision changed");
-      const bytes = localAttachment(path5);
+      const bytes = localAttachment(path7);
       const beforeAttachments = manager.listAttachmentsById(id2);
-      const directory = mkdtempSync4(join11(tmpdir4(), "notes-attachment-add-"));
-      const temporaryFile = join11(directory, basename(path5));
+      const directory = mkdtempSync4(join13(tmpdir4(), "notes-attachment-add-"));
+      const temporaryFile = join13(directory, basename(path7));
       try {
         writeFileSync3(temporaryFile, bytes, { mode: 384 });
         if (readSnapshot(manager, id2).hash !== before.hash)
@@ -45206,7 +45887,11 @@ function registerDirectOperations(server2, manager) {
 }
 
 // src/tools/nativeTagsBridge.ts
-var noteId2 = external_exports.string().regex(/^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i);
+var noteId2 = exactIdInput(
+  "ICNote",
+  /^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i,
+  NOTE_ID_MESSAGE
+);
 var revision2 = external_exports.string().regex(/^sha256:[a-f0-9]{64}$/);
 function registerNativeTagsBridge(server2, manager) {
   function tool(name, description, inputSchema, handler) {
@@ -45318,7 +46003,7 @@ function requireValidated(name) {
       UNAVAILABLE[name] || LIVE_VALIDATION_BLOCKERS[name] || `${name} has not passed live background validation in this build; see get-capabilities`
     );
 }
-var id = external_exports.string().regex(/^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i);
+var id = exactIdInput("ICNote", /^x-coredata:\/\/[0-9a-f-]+\/ICNote\/p\d+$/i, NOTE_ID_MESSAGE);
 var revision3 = external_exports.string().regex(/^sha256:[a-f0-9]{64}$/);
 var common = {
   id,
@@ -45696,7 +46381,7 @@ function registerNativeOperations(server2, manager) {
 
 // src/setupShortcuts.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync8 } from "node:fs";
+import { existsSync as existsSync10 } from "node:fs";
 import { release as release2 } from "node:os";
 import { dirname as dirname2, resolve as resolve2 } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -45716,16 +46401,16 @@ var shortcutFiles = [
 ];
 function setupShortcuts(checkOnly, dependencies = {}) {
   const status = dependencies.status || nativeTagsStatus;
-  const exists = dependencies.exists || existsSync8;
-  const open = dependencies.open || ((path5) => {
-    const result = spawnSync2("/usr/bin/open", [path5], { encoding: "utf8" });
+  const exists = dependencies.exists || existsSync10;
+  const open = dependencies.open || ((path7) => {
+    const result = spawnSync2("/usr/bin/open", [path7], { encoding: "utf8" });
     return result.status === 0 ? { ok: true } : { ok: false, error: result.stderr || result.error?.message || "open failed" };
   });
   const baseDirectory = dependencies.baseDirectory || resolve2(dirname2(fileURLToPath(import.meta.url)), "../shortcuts");
   const osRelease = (dependencies.osRelease || release2)();
   const darwinMajor = Number.parseInt(osRelease.split(".")[0], 10);
   const items = shortcutFiles.map(({ name, file, optional: optional2 }) => {
-    const path5 = resolve2(baseDirectory, file);
+    const path7 = resolve2(baseDirectory, file);
     let installed = false;
     let identifier;
     let error2;
@@ -45741,9 +46426,9 @@ function setupShortcuts(checkOnly, dependencies = {}) {
     if (!installed && !checkOnly) {
       if (optional2 && !(darwinMajor >= MARKDOWN_MIN_DARWIN_MAJOR))
         skipped = `requires macOS 26 or later (this Mac reports Darwin ${osRelease})`;
-      else if (!exists(path5)) error2 = `Packaged Shortcut is missing: ${path5}`;
+      else if (!exists(path7)) error2 = `Packaged Shortcut is missing: ${path7}`;
       else {
-        const result = open(path5);
+        const result = open(path7);
         opened = result.ok;
         if (!result.ok) error2 = result.error || `Could not open ${file}`;
       }
@@ -45752,7 +46437,7 @@ function setupShortcuts(checkOnly, dependencies = {}) {
       name,
       installed,
       identifier,
-      file: path5,
+      file: path7,
       opened,
       ...optional2 ? { optional: optional2 } : {},
       ...skipped ? { skipped } : {},
@@ -45838,10 +46523,25 @@ var noteTitleSchema = {
     "Account name (defaults to Notes.app's default account; exact or unique-prefix match)"
   )
 };
-var noteIdInput = external_exports.string().min(1, "Note ID is required").max(MAX.ID).regex(
-  /^x-coredata:\/\/[0-9A-Fa-f-]+\/ICNote\/p\d+$/,
-  "A canonical Apple Note ID is required (x-coredata://.../ICNote/p...)"
-).describe("Exact CoreData note ID returned by search-notes, list-notes, or create-note");
+var NOTE_COREDATA_ID = /^x-coredata:\/\/[0-9A-Fa-f-]+\/ICNote\/p\d+$/;
+var NOTE_ID_FORMS = "x-coredata id, Notes UUID, or numeric key";
+var noteIdInput = exactIdInput("ICNote", NOTE_COREDATA_ID, NOTE_ID_MESSAGE, {
+  maxLength: MAX.ID
+}).describe(`Exact note ID returned by search-notes, list-notes, or create-note: ${NOTE_ID_FORMS}`);
+var noteIdArrayInput = exactIdArrayInput("ICNote", NOTE_COREDATA_ID, NOTE_ID_MESSAGE, {
+  maxLength: MAX.ID,
+  maxItems: MAX.BATCH_IDS
+});
+var looseNoteId = (base) => base.max(MAX.ID).transform(looseIdTransform("ICNote"));
+var looseFolderId = (base) => base.max(MAX.ID).transform(looseIdTransform("ICFolder"));
+var noteIdentifierOutput = {
+  identifier: external_exports.string().optional(),
+  folderIdentifier: external_exports.string().optional(),
+  accountIdentifier: external_exports.string().optional()
+};
+function noteIdentifiers(id2) {
+  return lookupStableIdentifiers([id2], "ICNote").get(id2) ?? {};
+}
 var expectedContentHashInput = external_exports.string().regex(/^sha256:[a-f0-9]{64}$/, "expectedContentHash must come from get-note-content").describe(
   "Revision token returned by get-note-content for this exact ID. The mutation stops if the note changed since that read."
 );
@@ -46017,7 +46717,7 @@ ${syncWarnings.join(" ")}` : "";
     return successResponse(
       `Found ${notes.length} notes (searched ${searchType}${folderInfo}${dateInfo}${limitInfo}):
 ${noteList}${truncationNote}${syncNote}`,
-      { notes, count: notes.length }
+      { notes: withStableIdentifiers(notes, "ICNote"), count: notes.length }
     );
   }, "Error searching notes")
 );
@@ -46101,7 +46801,7 @@ registerTool(
   {
     description: "Use when: reading the full body text of one known note, by id (preferred) or title.\nReturns: the exact note id, content, contentHash revision token, parsed hashtags, nativeTags, restored links, richContentComplete/writable, and strippedImages/truncated when the body was capped. Read the warning when writable is false.\nDo not use when: you only need metadata (get-note-details) or Markdown with checklist state (get-note-markdown).\nNote: password-protected notes must be unlocked in Notes.app first.\nSafety: inline images larger than APPLE_NOTES_MCP_MAX_INLINE_IMAGE_BYTES (default 256 KB) are replaced with '[inline image omitted: ...]' text placeholders, so the returned body is lossy whenever truncated is true. Mutations refuse attachment-bearing notes; edit those in Notes.app.",
     inputSchema: {
-      id: external_exports.string().max(MAX.ID).optional().describe("Note ID (preferred - more reliable than title)"),
+      id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe(
         "Account name (defaults to Notes.app's default account; exact or unique-prefix match, ignored if id is provided)"
@@ -46109,6 +46809,7 @@ registerTool(
     },
     outputSchema: {
       id: external_exports.string().optional(),
+      ...noteIdentifierOutput,
       title: external_exports.string().optional(),
       content: external_exports.string().optional(),
       contentHash: external_exports.string().optional(),
@@ -46148,6 +46849,7 @@ registerTool(
       const warning2 = [strippedImagesWarning(stripped2), rich2.warning].filter(Boolean).join("\n\n");
       return successResponse(warning2 ? content2 + warning2 : content2, {
         id: id2,
+        ...noteIdentifiers(id2),
         title: note2.title,
         content: content2,
         contentHash: richContentHash(rawContent2, rich2),
@@ -46189,6 +46891,7 @@ registerTool(
     const warning = [strippedImagesWarning(stripped), rich.warning].filter(Boolean).join("\n\n");
     return successResponse(warning ? content + warning : content, {
       id: note.id,
+      ...noteIdentifiers(note.id),
       title,
       content,
       contentHash: richContentHash(rawContent, rich),
@@ -46213,7 +46916,7 @@ registerTool(
   {
     description: "Use when: reading one note's body as plain text with no HTML, by id (preferred) or title.\nReturns: the note's plaintext exactly as Notes exposes it.\nDo not use when: you need the HTML body (get-note-content) or Markdown with checklist state (get-note-markdown).\nNote: this reads the note's native plaintext property, so it skips the HTML-to-text conversion; password-protected notes must be unlocked in Notes.app first.",
     inputSchema: {
-      id: external_exports.string().max(MAX.ID).optional().describe("Note ID (preferred - more reliable than title)"),
+      id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe(
         "Account name (defaults to Notes.app's default account; exact or unique-prefix match, ignored if id is provided)"
@@ -46265,7 +46968,9 @@ registerTool(
   {
     description: "Use when: you have a note id and need its metadata only.\nReturns: id, title, created, modified, shared, passwordProtected.\nDo not use when: you need the body text (get-note-content) or only have a title (get-note-details).",
     inputSchema: {
-      id: external_exports.string().min(1, "Note ID is required").max(MAX.ID)
+      id: looseNoteId(external_exports.string().min(1, "Note ID is required")).describe(
+        `Note ID: ${NOTE_ID_FORMS}`
+      )
     },
     outputSchema: {
       id: external_exports.string().optional(),
@@ -46273,7 +46978,8 @@ registerTool(
       created: external_exports.string().optional(),
       modified: external_exports.string().optional(),
       shared: external_exports.boolean().optional(),
-      passwordProtected: external_exports.boolean().optional()
+      passwordProtected: external_exports.boolean().optional(),
+      ...noteIdentifierOutput
     }
   },
   withErrorHandling(({ id: id2 }) => {
@@ -46287,7 +46993,8 @@ registerTool(
       created: note.created.toISOString(),
       modified: note.modified.toISOString(),
       shared: note.shared,
-      passwordProtected: note.passwordProtected
+      passwordProtected: note.passwordProtected,
+      ...noteIdentifiers(note.id)
     };
     return successResponse(JSON.stringify(metadata, null, 2), metadata);
   }, "Error retrieving note")
@@ -46304,7 +47011,8 @@ registerTool(
       modified: external_exports.string().optional(),
       shared: external_exports.boolean().optional(),
       passwordProtected: external_exports.boolean().optional(),
-      account: external_exports.string().optional()
+      account: external_exports.string().optional(),
+      ...noteIdentifierOutput
     }
   },
   withErrorHandling(({ title, account }) => {
@@ -46319,7 +47027,8 @@ registerTool(
       modified: note.modified.toISOString(),
       shared: note.shared,
       passwordProtected: note.passwordProtected,
-      account: note.account
+      account: note.account,
+      ...noteIdentifiers(note.id)
     };
     return successResponse(JSON.stringify(metadata, null, 2), metadata);
   }, "Error retrieving note details")
@@ -46329,7 +47038,9 @@ registerTool(
   {
     description: "Use when: the user wants to reveal a known note in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need note content (get-note-content) or metadata (get-note-by-id).\nNote: this opens or focuses the Notes UI.",
     inputSchema: {
-      id: external_exports.string().min(1, "Note ID is required").max(MAX.ID),
+      id: looseNoteId(external_exports.string().min(1, "Note ID is required")).describe(
+        `Note ID: ${NOTE_ID_FORMS}`
+      ),
       separately: external_exports.boolean().optional().describe("Open in a separate note window when supported by Notes.app")
     },
     outputSchema: {
@@ -46350,7 +47061,7 @@ registerTool(
   {
     description: "Use when: you need the notes:// deep-link URL for a note so it can be stored in a Reminders task, shared, or opened directly.\nReturns: a notes://showNote?identifier=<uuid> URL that opens the note in Notes.app on iOS and macOS.\nDo not use when: you only need the note's CoreData id (get-note-by-id) or want to reveal the note on screen (show-note).\nNote: the primary path reads the note's identifier from the Notes database, so it needs Full Disk Access for the app that launches this server; macOS 12-15 can fall back to the AppleScript 'note link' property, which macOS 26+ no longer exposes. Password-protected notes cannot be linked.",
     inputSchema: {
-      id: external_exports.string().max(MAX.ID).optional().describe("Note ID (preferred - more reliable than title)"),
+      id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the note (ignored if id is provided)")
     },
@@ -46405,7 +47116,9 @@ registerTool(
   {
     description: "Use when: the user wants to reveal a known folder in Notes.app by id.\nReturns: confirmation that Notes.app accepted the show command.\nDo not use when: you only need the folder list (list-folders).\nNote: this opens or focuses the Notes UI. Get the id from list-folders.",
     inputSchema: {
-      id: external_exports.string().min(1, "Folder ID is required").max(MAX.ID),
+      id: looseFolderId(external_exports.string().min(1, "Folder ID is required")).describe(
+        "Folder ID from list-folders: x-coredata id, Notes UUID, or numeric key"
+      ),
       separately: external_exports.boolean().optional().describe("Open in a separate window when supported by Notes.app")
     },
     outputSchema: {
@@ -46949,7 +47662,15 @@ registerTool(
       limit: external_exports.number().int().positive().optional().describe("Maximum number of notes to return")
     },
     outputSchema: {
-      notes: external_exports.array(external_exports.object({ title: external_exports.string(), id: external_exports.string() })).optional(),
+      notes: external_exports.array(
+        external_exports.object({
+          title: external_exports.string(),
+          id: external_exports.string(),
+          identifier: external_exports.string().optional(),
+          folderIdentifier: external_exports.string().optional(),
+          accountIdentifier: external_exports.string().optional()
+        })
+      ).optional(),
       count: external_exports.number().optional()
     }
   },
@@ -46986,7 +47707,7 @@ ${syncWarnings.join(" ")}` : "";
     return successResponse(
       `Found ${notes.length} notes${location}${acct}${dateInfo}${limitInfo}:
 ${noteList}${syncNote}`,
-      { notes, count: notes.length }
+      { notes: withStableIdentifiers(notes, "ICNote"), count: notes.length }
     );
   }, "Error listing notes")
 );
@@ -47010,7 +47731,10 @@ registerTool(
     }
     const noteList = notes.map((n) => `  - ${n.title} [id: ${n.id}]`).join("\n");
     return successResponse(`Selected note(s):
-${noteList}`, { notes, count: notes.length });
+${noteList}`, {
+      notes: withStableIdentifiers(notes, "ICNote"),
+      count: notes.length
+    });
   }, "Error getting selected notes")
 );
 registerTool(
@@ -47051,12 +47775,61 @@ ${syncWarnings.join(" ")}` : "";
       `Found ${folders.length} folders${resolvedAcct}:
 ${folderList}${syncNote}`,
       {
-        folders,
+        folders: withStableIdentifiers(folders, "ICFolder"),
         count: folders.length
       }
     );
   }, "Error listing folders")
 );
+registerTool(
+  "list-smart-folders",
+  {
+    description: `Use when: listing Smart Folders and the rules that define them.
+Returns: each smart folder's name, ids, account, and parent, its rules decoded as match ("all"/"any"/"none") plus filters (each with a readable description), the stored query with the outer deleted wrapper removed, and the raw stored query JSON. With includeMatchingNotes, also the notes Notes.app currently shows in each folder.
+Do not use when: listing ordinary folders (list-folders) or searching notes (search-notes).
+Safety: read-only; reads the NoteStore database and requires Full Disk Access. includeMatchingNotes asks Notes.app (Automation permission) for each folder's current contents rather than re-evaluating the rules. Unrecognized rules are kept as "unknown" filters and set fullyDecoded false.`,
+    inputSchema: {
+      includeMatchingNotes: external_exports.boolean().optional().describe(
+        "Also list the notes Notes.app currently shows in each smart folder (default false)"
+      ),
+      limit: external_exports.number().int().min(1).max(500).optional().describe("Maximum matching notes returned per folder (default 50; count is always total)")
+    },
+    outputSchema: {
+      smartFolders: external_exports.array(external_exports.object({}).passthrough()).optional(),
+      count: external_exports.number().optional(),
+      fullyDecoded: external_exports.boolean().optional()
+    },
+    annotations: { readOnlyHint: true }
+  },
+  withErrorHandling(({ includeMatchingNotes = false, limit }) => {
+    const folders = notesManager.listSmartFolders({ includeMatchingNotes, limit });
+    const fullyDecoded = folders.every((folder) => folder.fullyDecoded);
+    if (folders.length === 0) {
+      return successResponse("No smart folders found.", {
+        smartFolders: [],
+        count: 0,
+        fullyDecoded
+      });
+    }
+    const lines = folders.map((folder) => {
+      const joiner = folder.match === "any" ? " OR " : " AND ";
+      const rules = folder.filters.map((filter) => filter.description).join(joiner);
+      const prefix = folder.match === "none" ? "none of: " : "";
+      const where = [folder.account, folder.parent].filter(Boolean).join(" / ");
+      const matches = folder.matchingNoteCount !== void 0 ? ` [${folder.matchingNoteCount} note(s)]` : folder.matchingNotesError ? ` [notes unavailable: ${folder.matchingNotesError}]` : "";
+      return `  - ${folder.name ?? "(untitled)"}${where ? ` (${where})` : ""}: ${prefix}${rules || "(no rules)"}${matches}`;
+    });
+    return successResponse(
+      `Found ${folders.length} smart folder(s):
+${lines.join("\n")}${fullyDecoded ? "" : '\n\nSome rules were not recognized; see filters of type "unknown".'}`,
+      {
+        smartFolders: folders,
+        count: folders.length,
+        fullyDecoded
+      }
+    );
+  }, "Error listing smart folders")
+);
 registerTool(
   "create-folder",
   {
@@ -47127,7 +47900,7 @@ registerTool(
     }).join("\n");
     return successResponse(`Found ${accounts.length} accounts:
 ${accountList}`, {
-      accounts,
+      accounts: withStableIdentifiers(accounts, "ICAccount"),
       count: accounts.length
     });
   }, "Error listing accounts")
@@ -47146,7 +47919,9 @@ registerTool(
     const location = notesManager.getDefaultLocation();
     const message = `Default account: ${location.account.name} [id: ${location.account.id}]
 Default folder: ${location.folder.name} [id: ${location.folder.id}]`;
-    return successResponse(message, { ...location });
+    const [account] = withStableIdentifiers([location.account], "ICAccount");
+    const [folder] = withStableIdentifiers([location.folder], "ICFolder");
+    return successResponse(message, { account, folder });
   }, "Error getting default Notes location")
 );
 registerTool(
@@ -47176,7 +47951,7 @@ registerTool(
 ${noteList}
 
 \u26A0\uFE0F Changes to shared notes are visible to all collaborators.`,
-      { notes: sharedNotes, count: sharedNotes.length }
+      { notes: withStableIdentifiers(sharedNotes, "ICNote"), count: sharedNotes.length }
     );
   }, "Error listing shared notes")
 );
@@ -47317,7 +48092,7 @@ registerTool(
   {
     description: "Use when: listing the attachments of one note, by id (preferred) or title.\nReturns: each attachment's name, content type, and id (use with save-attachment/fetch-attachment).\nDo not use when: you want the attachment bytes (fetch-attachment) or a file on disk (save-attachment).",
     inputSchema: {
-      id: external_exports.string().max(MAX.ID).optional().describe("Note ID (preferred - more reliable than title)"),
+      id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the note (ignored if id is provided)")
     },
@@ -47425,7 +48200,9 @@ registerTool(
   {
     description: "Use when: moving multiple notes by id into one destination folder.\nReturns: per-id success/failure counts after destination-folder verification.\nDo not use when: moving a single note (move-note).\nSafety: each moved note's actual container ID is compared with the destination folder ID before success is reported. The destination folder must already exist (create-folder).",
     inputSchema: {
-      ids: external_exports.array(noteIdInput).max(MAX.BATCH_IDS).describe(`Array of note IDs to move (max ${MAX.BATCH_IDS} per request)`),
+      ids: noteIdArrayInput.describe(
+        `Array of note IDs to move (max ${MAX.BATCH_IDS} per request)`
+      ),
       folder: external_exports.string().max(MAX.FOLDER).describe(
         'Destination folder name or nested path (e.g. "Work/Clients"). Must already exist \u2014 create-folder first.'
       ),
@@ -47469,7 +48246,9 @@ registerTool(
   {
     description: "Use when: writing one note attachment to a file on disk.\nReturns: the saved path.\nDo not use when: you want the bytes in-memory as base64 (fetch-attachment).\nSafety: writes a file; savePath must be absolute and under the home directory, a temp dir, or /Volumes. Get the ids from list-attachments first.",
     inputSchema: {
-      noteId: external_exports.string().min(1, "noteId is required").max(MAX.ID).describe("CoreData note id (from search/list)"),
+      noteId: looseNoteId(external_exports.string().min(1, "noteId is required")).describe(
+        `Note id (from search/list): ${NOTE_ID_FORMS}`
+      ),
       attachmentId: external_exports.string().min(1, "attachmentId is required").max(MAX.ATTACHMENT_ID).describe("Attachment id (from list-attachments)"),
       savePath: external_exports.string().min(1, "savePath is required").max(MAX.SAVE_PATH).describe("Absolute destination file path (must be under home, temp, or /Volumes)")
     },
@@ -47496,7 +48275,9 @@ registerTool(
   {
     description: "Use when: retrieving one note attachment's bytes inline as base64 (no file written).\nReturns: name, content type, byte count, and base64 data.\nDo not use when: you want it saved to disk (save-attachment).\nNote: get the ids from list-attachments first.",
     inputSchema: {
-      noteId: external_exports.string().min(1, "noteId is required").max(MAX.ID).describe("CoreData note id (from search/list)"),
+      noteId: looseNoteId(external_exports.string().min(1, "noteId is required")).describe(
+        `Note id (from search/list): ${NOTE_ID_FORMS}`
+      ),
       attachmentId: external_exports.string().min(1, "attachmentId is required").max(MAX.ATTACHMENT_ID).describe("Attachment id (from list-attachments)")
     },
     outputSchema: {
@@ -47522,7 +48303,9 @@ registerTool(
   {
     description: "Use when: the user wants to reveal one note attachment in Notes.app.\nReturns: confirmation that Notes.app revealed the attachment.\nDo not use when: you want the bytes (fetch-attachment) or a file on disk (save-attachment).\nNote: this opens or focuses the Notes UI. Get the ids from list-attachments first.",
     inputSchema: {
-      noteId: external_exports.string().min(1, "noteId is required").max(MAX.ID).describe("CoreData note id (from search/list)"),
+      noteId: looseNoteId(external_exports.string().min(1, "noteId is required")).describe(
+        `Note id (from search/list): ${NOTE_ID_FORMS}`
+      ),
       attachmentId: external_exports.string().min(1, "attachmentId is required").max(MAX.ATTACHMENT_ID).describe("Attachment id (from list-attachments)"),
       separately: external_exports.boolean().optional().describe("Open in a separate window when supported by Notes.app")
     },
@@ -47622,7 +48405,7 @@ registerTool(
   {
     description: "Use when: reading a note as Markdown, with checklist items annotated [x]/[ ] when Full Disk Access is granted.\nReturns: the note's Markdown.\nDo not use when: you need the raw HTML/plaintext body (get-note-content) or only metadata (get-note-details).\nNote: falls back to plain lists (no checkmarks) without Full Disk Access.",
     inputSchema: {
-      id: external_exports.string().max(MAX.ID).optional().describe("Note ID (preferred - more reliable than title)"),
+      id: looseNoteId(external_exports.string()).optional().describe(`Note ID (preferred - more reliable than title): ${NOTE_ID_FORMS}`),
       title: external_exports.string().max(MAX.TITLE).optional().describe("Note title (use id instead when available)"),
       account: external_exports.string().max(MAX.ACCOUNT).optional().describe("Account containing the note (ignored if id is provided)")
     },
@@ -47655,7 +48438,9 @@ registerTool(
   {
     description: "Use when: reading the checked/unchecked state of a note's checklist items, by id.\nReturns: each item's text and done state plus checked/total counts.\nDo not use when: you only have a title (get the id via search-notes first) or want the full body text (get-note-content).\nNote: requires Full Disk Access; reads the NoteStore database directly.",
     inputSchema: {
-      id: external_exports.string().min(1, "Note ID is required. Use search-notes to find the note ID first.").max(MAX.ID)
+      id: looseNoteId(
+        external_exports.string().min(1, "Note ID is required. Use search-notes to find the note ID first.")
+      ).describe(`Note ID: ${NOTE_ID_FORMS}`)
     },
     outputSchema: {
       items: external_exports.array(external_exports.object({}).passthrough()).optional(),
@@ -47691,7 +48476,9 @@ registerTool(
   {
     description: "[BETA] Use when: reading note metadata AppleScript cannot expose \u2014 pinned state, checklist flags, trash/recovery state, preview snippet, password hint \u2014 by id.\nReturns: a metadata object; fields vary by macOS version and are omitted when unavailable.\nDo not use when: you need the body (get-note-content) or per-item checklist state (get-checklist-state).\nNote: reads the NoteStore SQLite database read-only and requires Full Disk Access. BETA \u2014 the database schema changes between macOS releases, so some fields may be absent. Works on trashed notes that AppleScript can no longer resolve.",
     inputSchema: {
-      id: external_exports.string().min(1, "Note ID is required. Use search-notes to find the note ID first.").max(MAX.ID)
+      id: looseNoteId(
+        external_exports.string().min(1, "Note ID is required. Use search-notes to find the note ID first.")
+      ).describe(`Note ID: ${NOTE_ID_FORMS}`)
     },
     outputSchema: {
       pinned: external_exports.boolean().optional(),