mindcache 3.4.3 → 3.5.0

package/dist/index.js

@@ -471,12 +471,872 @@ var SystemTagHelpers = {
   isLLMReadable: (attrs) => attrs.systemTags.includes("SystemPrompt") || attrs.systemTags.includes("LLMRead"),
   /** Check if key is included in system prompt */
   isInSystemPrompt: (attrs) => attrs.systemTags.includes("SystemPrompt"),
-  /** Check if key is protected from deletion */
-  isProtected: (attrs) => attrs.systemTags.includes("protected"),
   /** Check if key uses template injection */
   hasTemplateInjection: (attrs) => attrs.systemTags.includes("ApplyTemplate")
 };
 
+// src/core/MarkdownSerializer.ts
+var MarkdownSerializer = class {
+  /**
+     * Export MindCache data to Markdown format.
+     */
+  static toMarkdown(mc) {
+    const now = /* @__PURE__ */ new Date();
+    const lines = [];
+    const appendixEntries = [];
+    let appendixCounter = 0;
+    lines.push("# MindCache STM Export");
+    lines.push("");
+    lines.push(`Export Date: ${now.toISOString().split("T")[0]}`);
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    lines.push("## STM Entries");
+    lines.push("");
+    const sortedKeys = mc.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      const attributes = mc.get_attributes(key);
+      const value = mc.get_value(key);
+      lines.push(`### ${key}`);
+      const entryType = attributes?.type || "text";
+      lines.push(`- **Type**: \`${entryType}\``);
+      lines.push(`- **System Tags**: \`${attributes?.systemTags?.join(", ") || "none"}\``);
+      lines.push(`- **Z-Index**: \`${attributes?.zIndex ?? 0}\``);
+      if (attributes?.contentTags && attributes.contentTags.length > 0) {
+        lines.push(`- **Tags**: \`${attributes.contentTags.join("`, `")}\``);
+      }
+      if (attributes?.contentType) {
+        lines.push(`- **Content Type**: \`${attributes.contentType}\``);
+      }
+      if (entryType === "image" || entryType === "file") {
+        const label = String.fromCharCode(65 + appendixCounter);
+        appendixCounter++;
+        lines.push(`- **Value**: [See Appendix ${label}]`);
+        appendixEntries.push({
+          key,
+          type: entryType,
+          contentType: attributes?.contentType || "application/octet-stream",
+          base64: value,
+          label
+        });
+      } else if (entryType === "json") {
+        lines.push("- **Value**:");
+        lines.push("```json");
+        try {
+          const jsonValue = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+          lines.push(jsonValue);
+        } catch {
+          lines.push(String(value));
+        }
+        lines.push("```");
+      } else {
+        lines.push("- **Value**:");
+        lines.push("```");
+        lines.push(String(value));
+        lines.push("```");
+      }
+      lines.push("");
+    });
+    if (appendixEntries.length > 0) {
+      lines.push("---");
+      lines.push("");
+      lines.push("## Appendix: Binary Data");
+      lines.push("");
+      appendixEntries.forEach((entry) => {
+        lines.push(`### Appendix ${entry.label}: ${entry.key}`);
+        lines.push(`- **Type**: \`${entry.type}\``);
+        lines.push(`- **Content Type**: \`${entry.contentType}\``);
+        lines.push("- **Base64 Data**:");
+        lines.push("```");
+        lines.push(entry.base64);
+        lines.push("```");
+        lines.push("");
+      });
+    }
+    return lines.join("\n");
+  }
+  /**
+     * Import Markdown into MindCache data.
+     * @param markdown The markdown string to import
+     * @param mc The MindCache instance to import into
+     * @param merge If false (default), clears existing data before importing
+     */
+  static fromMarkdown(markdown, mc, merge = false) {
+    const lines = markdown.split("\n");
+    let currentKey = null;
+    let currentAttributes = {};
+    let currentValue = null;
+    let inCodeBlock = false;
+    let codeBlockContent = [];
+    if (!merge) {
+      mc.clear();
+    }
+    for (const line of lines) {
+      if (line.startsWith("### ") && !line.startsWith("### Appendix")) {
+        if (currentKey && currentValue !== null) {
+          mc.set_value(currentKey, currentValue.trim(), currentAttributes);
+        }
+        currentKey = line.substring(4).trim();
+        currentAttributes = {};
+        currentValue = null;
+        continue;
+      }
+      if (line.startsWith("### Appendix ")) {
+        if (currentKey && currentValue !== null) {
+          mc.set_value(currentKey, currentValue.trim(), currentAttributes);
+        }
+        const match = line.match(/### Appendix ([A-Z]): (.+)/);
+        if (match) {
+          currentKey = match[2];
+          currentAttributes = {};
+          currentValue = null;
+        }
+        continue;
+      }
+      if (line.startsWith("- **Type**:")) {
+        const type = line.match(/`(.+)`/)?.[1];
+        if (type) {
+          currentAttributes.type = type;
+        }
+        continue;
+      }
+      if (line.startsWith("- **System Tags**:")) {
+        const tagsStr = line.match(/`([^`]+)`/)?.[1] || "";
+        if (tagsStr !== "none") {
+          currentAttributes.systemTags = tagsStr.split(", ").filter((t) => t);
+        }
+        continue;
+      }
+      if (line.startsWith("- **Z-Index**:")) {
+        const zIndex = parseInt(line.match(/`(\d+)`/)?.[1] || "0", 10);
+        currentAttributes.zIndex = zIndex;
+        continue;
+      }
+      if (line.startsWith("- **Tags**:")) {
+        const tags = line.match(/`([^`]+)`/g)?.map((t) => t.slice(1, -1)) || [];
+        currentAttributes.contentTags = tags;
+        continue;
+      }
+      if (line.startsWith("- **Content Type**:")) {
+        currentAttributes.contentType = line.match(/`(.+)`/)?.[1];
+        continue;
+      }
+      if (line.startsWith("- **Base64 Data**:")) {
+        currentValue = "";
+        continue;
+      }
+      if (line.startsWith("- **Value**:")) {
+        const afterValue = line.substring(12).trim();
+        if (afterValue.includes("[See Appendix")) {
+          if (currentKey) {
+            mc.set_value(currentKey, "", currentAttributes);
+          }
+          currentValue = null;
+          continue;
+        }
+        if (afterValue === "") {
+          currentValue = "";
+        } else if (afterValue === "```" || afterValue === "```json") {
+          inCodeBlock = true;
+          codeBlockContent = [];
+          currentValue = "";
+        } else if (afterValue.startsWith("```")) {
+          inCodeBlock = true;
+          codeBlockContent = [afterValue.substring(3)];
+          currentValue = "";
+        } else {
+          currentValue = afterValue;
+        }
+        continue;
+      }
+      const trimmedLine = line.trim();
+      if (trimmedLine === "```json" || trimmedLine === "```") {
+        if (inCodeBlock) {
+          inCodeBlock = false;
+          if (currentKey && codeBlockContent.length > 0) {
+            currentValue = codeBlockContent.join("\n");
+          }
+          codeBlockContent = [];
+        } else {
+          inCodeBlock = true;
+          codeBlockContent = [];
+        }
+        continue;
+      }
+      if (inCodeBlock) {
+        codeBlockContent.push(line);
+      } else if (currentKey && currentValue !== null) {
+        if (line.trim() === "---" || line.startsWith("## Appendix")) {
+          mc.set_value(currentKey, currentValue.trim(), currentAttributes);
+          currentKey = null;
+          currentValue = null;
+          currentAttributes = {};
+        } else {
+          currentValue += "\n" + line;
+        }
+      }
+    }
+    if (currentKey && currentValue !== null) {
+      mc.set_value(currentKey, currentValue.trim(), currentAttributes);
+    }
+    const hasParsedKeys = lines.some((line) => line.startsWith("### ") && !line.startsWith("### Appendix"));
+    const isSTMExport = markdown.includes("# MindCache STM Export") || markdown.includes("## STM Entries");
+    if (!hasParsedKeys && !isSTMExport && markdown.trim().length > 0) {
+      mc.set_value("imported_content", markdown.trim(), {
+        type: "text",
+        systemTags: ["SystemPrompt", "LLMWrite"],
+        // Default assumptions
+        zIndex: 0
+      });
+    }
+  }
+  /**
+     * Parse markdown and return STM data without applying to a MindCache instance.
+     * Useful for validation or preview.
+     */
+  static parseMarkdown(markdown) {
+    const result = {};
+    const lines = markdown.split("\n");
+    let currentKey = null;
+    let currentAttributes = {};
+    let currentValue = null;
+    let inCodeBlock = false;
+    let codeBlockContent = [];
+    const saveEntry = () => {
+      if (currentKey && currentValue !== null) {
+        result[currentKey] = {
+          value: currentValue.trim(),
+          attributes: { ...DEFAULT_KEY_ATTRIBUTES, ...currentAttributes }
+        };
+      }
+    };
+    for (const line of lines) {
+      if (line.startsWith("### ") && !line.startsWith("### Appendix")) {
+        saveEntry();
+        currentKey = line.substring(4).trim();
+        currentAttributes = {};
+        currentValue = null;
+        continue;
+      }
+      if (line.startsWith("### Appendix ")) {
+        saveEntry();
+        const match = line.match(/### Appendix ([A-Z]): (.+)/);
+        if (match) {
+          currentKey = match[2];
+          currentAttributes = {};
+          currentValue = null;
+        }
+        continue;
+      }
+      if (line.startsWith("- **Type**:")) {
+        const type = line.match(/`(.+)`/)?.[1];
+        if (type) {
+          currentAttributes.type = type;
+        }
+        continue;
+      }
+      if (line.startsWith("- **System Tags**:")) {
+        const tagsStr = line.match(/`([^`]+)`/)?.[1] || "";
+        if (tagsStr !== "none") {
+          currentAttributes.systemTags = tagsStr.split(", ").filter((t) => t);
+        }
+        continue;
+      }
+      if (line.startsWith("- **Z-Index**:")) {
+        const zIndex = parseInt(line.match(/`(\d+)`/)?.[1] || "0", 10);
+        currentAttributes.zIndex = zIndex;
+        continue;
+      }
+      if (line.startsWith("- **Tags**:")) {
+        const tags = line.match(/`([^`]+)`/g)?.map((t) => t.slice(1, -1)) || [];
+        currentAttributes.contentTags = tags;
+        continue;
+      }
+      if (line.startsWith("- **Content Type**:")) {
+        currentAttributes.contentType = line.match(/`(.+)`/)?.[1];
+        continue;
+      }
+      if (line.startsWith("- **Base64 Data**:")) {
+        currentValue = "";
+        continue;
+      }
+      if (line.startsWith("- **Value**:")) {
+        const afterValue = line.substring(12).trim();
+        if (afterValue.includes("[See Appendix")) {
+          currentValue = "";
+          continue;
+        }
+        if (afterValue === "" || afterValue === "```" || afterValue === "```json") {
+          inCodeBlock = afterValue !== "";
+          codeBlockContent = [];
+          currentValue = "";
+        } else if (afterValue.startsWith("```")) {
+          inCodeBlock = true;
+          codeBlockContent = [afterValue.substring(3)];
+          currentValue = "";
+        } else {
+          currentValue = afterValue;
+        }
+        continue;
+      }
+      const trimmedLine = line.trim();
+      if (trimmedLine === "```json" || trimmedLine === "```") {
+        if (inCodeBlock) {
+          inCodeBlock = false;
+          if (currentKey && codeBlockContent.length > 0) {
+            currentValue = codeBlockContent.join("\n");
+          }
+          codeBlockContent = [];
+        } else {
+          inCodeBlock = true;
+          codeBlockContent = [];
+        }
+        continue;
+      }
+      if (inCodeBlock) {
+        codeBlockContent.push(line);
+      } else if (currentKey && currentValue !== null) {
+        if (line.trim() === "---" || line.startsWith("## Appendix")) {
+          saveEntry();
+          currentKey = null;
+          currentValue = null;
+          currentAttributes = {};
+        } else {
+          currentValue += "\n" + line;
+        }
+      }
+    }
+    saveEntry();
+    const hasParsedKeys = lines.some((line) => line.startsWith("### ") && !line.startsWith("### Appendix"));
+    const isSTMExport = markdown.includes("# MindCache STM Export") || markdown.includes("## STM Entries");
+    if (!hasParsedKeys && !isSTMExport && markdown.trim().length > 0) {
+      result["imported_content"] = {
+        value: markdown.trim(),
+        attributes: {
+          ...DEFAULT_KEY_ATTRIBUTES,
+          systemTags: ["SystemPrompt", "LLMWrite"]
+        }
+      };
+    }
+    return result;
+  }
+};
+
+// src/core/AIToolBuilder.ts
+var AIToolBuilder = class _AIToolBuilder {
+  /**
+     * Sanitize key name for use in tool names
+     */
+  static sanitizeKeyForTool(key) {
+    return key.replace(/[^a-zA-Z0-9_-]/g, "_");
+  }
+  /**
+     * Find original key from sanitized tool name
+     */
+  static findKeyFromSanitizedTool(mc, sanitizedKey) {
+    for (const key of mc.keys()) {
+      if (_AIToolBuilder.sanitizeKeyForTool(key) === sanitizedKey) {
+        return key;
+      }
+    }
+    return void 0;
+  }
+  /**
+     * Generate Vercel AI SDK compatible tools for writable keys.
+     * For document type keys, generates additional tools: append_, insert_, edit_
+     *
+     * Security: All tools use llm_set_key internally which:
+     * - Only modifies VALUES, never attributes/systemTags
+     * - Prevents LLMs from escalating privileges
+     */
+  static createVercelAITools(mc) {
+    const tools = {};
+    for (const key of mc.keys()) {
+      if (key.startsWith("$")) {
+        continue;
+      }
+      if (!mc.keyMatchesContext(key)) {
+        continue;
+      }
+      const attributes = mc.get_attributes(key);
+      const isWritable = attributes?.systemTags?.includes("LLMWrite");
+      if (!isWritable) {
+        continue;
+      }
+      const sanitizedKey = _AIToolBuilder.sanitizeKeyForTool(key);
+      const isDocument = attributes?.type === "document";
+      tools[`write_${sanitizedKey}`] = {
+        description: isDocument ? `Rewrite the entire "${key}" document` : `Write a value to the STM key: ${key}`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            value: { type: "string", description: isDocument ? "New document content" : "The value to write" }
+          },
+          required: ["value"]
+        },
+        execute: async ({ value }) => {
+          const success = mc.llm_set_key(key, value);
+          if (success) {
+            return {
+              result: `Successfully wrote "${value}" to ${key}`,
+              key,
+              value
+            };
+          }
+          return {
+            result: `Failed to write to ${key} - permission denied or key not found`,
+            key,
+            error: true
+          };
+        }
+      };
+      if (isDocument) {
+        tools[`append_${sanitizedKey}`] = {
+          description: `Append text to the end of "${key}" document`,
+          inputSchema: {
+            type: "object",
+            properties: {
+              text: { type: "string", description: "Text to append" }
+            },
+            required: ["text"]
+          },
+          execute: async ({ text }) => {
+            if (!attributes?.systemTags?.includes("LLMWrite")) {
+              return { result: `Permission denied for ${key}`, key, error: true };
+            }
+            const yText = mc.get_document(key);
+            if (yText) {
+              yText.insert(yText.length, text);
+              return {
+                result: `Successfully appended to ${key}`,
+                key,
+                appended: text
+              };
+            }
+            return { result: `Document ${key} not found`, key };
+          }
+        };
+        tools[`insert_${sanitizedKey}`] = {
+          description: `Insert text at a position in "${key}" document`,
+          inputSchema: {
+            type: "object",
+            properties: {
+              index: { type: "number", description: "Position to insert at (0 = start)" },
+              text: { type: "string", description: "Text to insert" }
+            },
+            required: ["index", "text"]
+          },
+          execute: async ({ index, text }) => {
+            if (!attributes?.systemTags?.includes("LLMWrite")) {
+              return { result: `Permission denied for ${key}`, key, error: true };
+            }
+            mc.insert_text(key, index, text);
+            return {
+              result: `Successfully inserted text at position ${index} in ${key}`,
+              key,
+              index,
+              inserted: text
+            };
+          }
+        };
+        tools[`edit_${sanitizedKey}`] = {
+          description: `Find and replace text in "${key}" document`,
+          inputSchema: {
+            type: "object",
+            properties: {
+              find: { type: "string", description: "Text to find" },
+              replace: { type: "string", description: "Replacement text" }
+            },
+            required: ["find", "replace"]
+          },
+          execute: async ({ find, replace }) => {
+            if (!attributes?.systemTags?.includes("LLMWrite")) {
+              return { result: `Permission denied for ${key}`, key, error: true };
+            }
+            const yText = mc.get_document(key);
+            if (yText) {
+              const text = yText.toString();
+              const idx = text.indexOf(find);
+              if (idx !== -1) {
+                yText.delete(idx, find.length);
+                yText.insert(idx, replace);
+                return {
+                  result: `Successfully replaced "${find}" with "${replace}" in ${key}`,
+                  key,
+                  find,
+                  replace,
+                  index: idx
+                };
+              }
+              return { result: `Text "${find}" not found in ${key}`, key };
+            }
+            return { result: `Document ${key} not found`, key };
+          }
+        };
+      }
+    }
+    return tools;
+  }
+  /**
+     * Generate a system prompt containing all visible STM keys and their values.
+     * Indicates which tools can be used to modify writable keys.
+     */
+  static getSystemPrompt(mc) {
+    const lines = [];
+    for (const key of mc.keys()) {
+      if (key.startsWith("$")) {
+        continue;
+      }
+      if (!mc.keyMatchesContext(key)) {
+        continue;
+      }
+      const attributes = mc.get_attributes(key);
+      const isVisible = attributes?.systemTags?.includes("SystemPrompt") || attributes?.systemTags?.includes("LLMRead");
+      if (!isVisible) {
+        continue;
+      }
+      const value = mc.get_value(key);
+      const displayValue = typeof value === "object" ? JSON.stringify(value) : value;
+      const isWritable = attributes?.systemTags?.includes("LLMWrite");
+      const isDocument = attributes?.type === "document";
+      const sanitizedKey = _AIToolBuilder.sanitizeKeyForTool(key);
+      if (isWritable) {
+        if (isDocument) {
+          lines.push(
+            `${key}: ${displayValue}. Document tools: write_${sanitizedKey}, append_${sanitizedKey}, edit_${sanitizedKey}`
+          );
+        } else {
+          const oldValueHint = displayValue ? ` This tool DOES NOT append \u2014 start your response with the old value (${displayValue})` : "";
+          lines.push(
+            `${key}: ${displayValue}. You can rewrite "${key}" by using the write_${sanitizedKey} tool.${oldValueHint}`
+          );
+        }
+      } else {
+        lines.push(`${key}: ${displayValue}`);
+      }
+    }
+    return lines.join("\n");
+  }
+  /**
+     * Execute a tool call by name with the given value.
+     * Returns the result or null if tool not found.
+     */
+  static executeToolCall(mc, toolName, value) {
+    const match = toolName.match(/^(write|append|insert|edit)_(.+)$/);
+    if (!match) {
+      return null;
+    }
+    const [, action, sanitizedKey] = match;
+    const key = _AIToolBuilder.findKeyFromSanitizedTool(mc, sanitizedKey);
+    if (!key) {
+      return null;
+    }
+    const attributes = mc.get_attributes(key);
+    if (!attributes) {
+      return null;
+    }
+    const isWritable = attributes?.systemTags?.includes("LLMWrite");
+    if (!isWritable) {
+      return null;
+    }
+    const isDocument = attributes?.type === "document";
+    switch (action) {
+      case "write":
+        if (isDocument) {
+          mc._replaceDocumentText(key, value);
+        } else {
+          mc.set_value(key, value);
+        }
+        return {
+          result: `Successfully wrote "${value}" to ${key}`,
+          key,
+          value
+        };
+      case "append":
+        if (isDocument) {
+          const yText = mc.get_document(key);
+          if (yText) {
+            yText.insert(yText.length, value);
+            return {
+              result: `Successfully appended to ${key}`,
+              key,
+              value
+            };
+          }
+        }
+        return null;
+      case "insert":
+        if (isDocument && typeof value === "object" && value.index !== void 0 && value.text) {
+          mc.insert_text(key, value.index, value.text);
+          return {
+            result: `Successfully inserted at position ${value.index} in ${key}`,
+            key,
+            value: value.text
+          };
+        }
+        return null;
+      case "edit":
+        if (isDocument && typeof value === "object" && value.find && value.replace !== void 0) {
+          const yText = mc.get_document(key);
+          if (yText) {
+            const text = yText.toString();
+            const idx = text.indexOf(value.find);
+            if (idx !== -1) {
+              yText.delete(idx, value.find.length);
+              yText.insert(idx, value.replace);
+              return {
+                result: `Successfully replaced "${value.find}" with "${value.replace}" in ${key}`,
+                key,
+                value: value.replace
+              };
+            }
+          }
+        }
+        return null;
+      default:
+        return null;
+    }
+  }
+};
+
+// src/core/TagManager.ts
+var TagManager = class _TagManager {
+  // ============================================
+  // Content Tag Methods
+  // ============================================
+  /**
+     * Add a content tag to a key.
+     * @returns true if the tag was added, false if key doesn't exist or tag already exists
+     */
+  static addTag(mc, key, tag) {
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return false;
+    }
+    const attributes = entryMap.get("attributes");
+    const contentTags = attributes?.contentTags || [];
+    if (contentTags.includes(tag)) {
+      return false;
+    }
+    mc.doc.transact(() => {
+      const newContentTags = [...contentTags, tag];
+      entryMap.set("attributes", {
+        ...attributes,
+        contentTags: newContentTags,
+        tags: newContentTags
+        // Sync legacy tags array
+      });
+    });
+    mc.notifyGlobalListeners();
+    return true;
+  }
+  /**
+     * Remove a content tag from a key.
+     * @returns true if the tag was removed
+     */
+  static removeTag(mc, key, tag) {
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return false;
+    }
+    const attributes = entryMap.get("attributes");
+    const contentTags = attributes?.contentTags || [];
+    const tagIndex = contentTags.indexOf(tag);
+    if (tagIndex === -1) {
+      return false;
+    }
+    mc.doc.transact(() => {
+      const newContentTags = contentTags.filter((t) => t !== tag);
+      entryMap.set("attributes", {
+        ...attributes,
+        contentTags: newContentTags,
+        tags: newContentTags
+        // Sync legacy tags array
+      });
+    });
+    mc.notifyGlobalListeners();
+    return true;
+  }
+  /**
+     * Get all content tags for a key.
+     */
+  static getTags(mc, key) {
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return [];
+    }
+    const attributes = entryMap.get("attributes");
+    return attributes?.contentTags || [];
+  }
+  /**
+     * Get all unique content tags across all keys.
+     */
+  static getAllTags(mc) {
+    const allTags = /* @__PURE__ */ new Set();
+    for (const [, val] of mc.rootMap) {
+      const entryMap = val;
+      const attributes = entryMap.get("attributes");
+      if (attributes?.contentTags) {
+        attributes.contentTags.forEach((tag) => allTags.add(tag));
+      }
+    }
+    return Array.from(allTags);
+  }
+  /**
+     * Check if a key has a specific content tag.
+     */
+  static hasTag(mc, key, tag) {
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return false;
+    }
+    const attributes = entryMap.get("attributes");
+    return attributes?.contentTags?.includes(tag) || false;
+  }
+  /**
+     * Get all keys with a specific content tag as formatted string.
+     */
+  static getTagged(mc, tag) {
+    const entries = [];
+    const keys = mc.getSortedKeys();
+    keys.forEach((key) => {
+      if (_TagManager.hasTag(mc, key, tag)) {
+        entries.push([key, mc.get_value(key)]);
+      }
+    });
+    return entries.map(([key, value]) => `${key}: ${value}`).join(", ");
+  }
+  /**
+     * Get array of keys with a specific content tag.
+     */
+  static getKeysByTag(mc, tag) {
+    const keys = mc.getSortedKeys();
+    return keys.filter((key) => _TagManager.hasTag(mc, key, tag));
+  }
+  // ============================================
+  // System Tag Methods (requires system access)
+  // ============================================
+  /**
+     * Add a system tag to a key (requires system access).
+     */
+  static systemAddTag(mc, key, tag) {
+    if (!mc.hasSystemAccess) {
+      console.warn("MindCache: systemAddTag requires system access level");
+      return false;
+    }
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return false;
+    }
+    const attributes = entryMap.get("attributes");
+    const systemTags = attributes?.systemTags || [];
+    if (systemTags.includes(tag)) {
+      return false;
+    }
+    mc.doc.transact(() => {
+      const newSystemTags = [...systemTags, tag];
+      const normalizedTags = mc.normalizeSystemTags(newSystemTags);
+      entryMap.set("attributes", {
+        ...attributes,
+        systemTags: normalizedTags
+      });
+    });
+    mc.notifyGlobalListeners();
+    return true;
+  }
+  /**
+     * Remove a system tag from a key (requires system access).
+     */
+  static systemRemoveTag(mc, key, tag) {
+    if (!mc.hasSystemAccess) {
+      console.warn("MindCache: systemRemoveTag requires system access level");
+      return false;
+    }
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return false;
+    }
+    const attributes = entryMap.get("attributes");
+    const systemTags = attributes?.systemTags || [];
+    const tagIndex = systemTags.indexOf(tag);
+    if (tagIndex === -1) {
+      return false;
+    }
+    mc.doc.transact(() => {
+      const newSystemTags = systemTags.filter((t) => t !== tag);
+      entryMap.set("attributes", {
+        ...attributes,
+        systemTags: newSystemTags
+      });
+    });
+    mc.notifyGlobalListeners();
+    return true;
+  }
+  /**
+     * Get all system tags for a key (requires system access).
+     */
+  static systemGetTags(mc, key) {
+    if (!mc.hasSystemAccess) {
+      console.warn("MindCache: systemGetTags requires system access level");
+      return [];
+    }
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return [];
+    }
+    const attributes = entryMap.get("attributes");
+    return attributes?.systemTags || [];
+  }
+  /**
+     * Check if a key has a specific system tag (requires system access).
+     */
+  static systemHasTag(mc, key, tag) {
+    if (!mc.hasSystemAccess) {
+      console.warn("MindCache: systemHasTag requires system access level");
+      return false;
+    }
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return false;
+    }
+    const attributes = entryMap.get("attributes");
+    return attributes?.systemTags?.includes(tag) || false;
+  }
+  /**
+     * Set all system tags for a key at once (requires system access).
+     */
+  static systemSetTags(mc, key, tags) {
+    if (!mc.hasSystemAccess) {
+      console.warn("MindCache: systemSetTags requires system access level");
+      return false;
+    }
+    const entryMap = mc.rootMap.get(key);
+    if (!entryMap) {
+      return false;
+    }
+    mc.doc.transact(() => {
+      const attributes = entryMap.get("attributes");
+      entryMap.set("attributes", {
+        ...attributes,
+        systemTags: [...tags]
+      });
+    });
+    mc.notifyGlobalListeners();
+    return true;
+  }
+  /**
+     * Get all keys with a specific system tag (requires system access).
+     */
+  static systemGetKeysByTag(mc, tag) {
+    if (!mc.hasSystemAccess) {
+      console.warn("MindCache: systemGetKeysByTag requires system access level");
+      return [];
+    }
+    const keys = mc.getSortedKeys();
+    return keys.filter((key) => _TagManager.systemHasTag(mc, key, tag));
+  }
+};
+
 // src/core/MindCache.ts
 var MindCache = class {
   // Public doc for adapter access
@@ -494,7 +1354,7 @@ var MindCache = class {
     const normalized = [];
     const seen = /* @__PURE__ */ new Set();
     for (const tag of tags) {
-      if (["SystemPrompt", "LLMRead", "LLMWrite", "protected", "ApplyTemplate"].includes(tag)) {
+      if (["SystemPrompt", "LLMRead", "LLMWrite", "ApplyTemplate"].includes(tag)) {
         if (!seen.has(tag)) {
           seen.add(tag);
           normalized.push(tag);
@@ -509,8 +1369,10 @@ var MindCache = class {
   _isLoaded = true;
   // Default true for local mode
   _cloudConfig = null;
-  // Access level for system operations
+  // Access level for admin operations
   _accessLevel = "user";
+  // Context filtering (client-local, not persisted)
+  _contextRules = null;
   _initPromise = null;
   // Y-IndexedDB provider
   _idbProvider = null;
@@ -575,6 +1437,9 @@ var MindCache = class {
     if (options?.accessLevel) {
       this._accessLevel = options.accessLevel;
     }
+    if (options?.context) {
+      this._contextRules = options.context;
+    }
     const initPromises = [];
     if (options?.cloud) {
       this._cloudConfig = options.cloud;
@@ -749,7 +1614,101 @@ var MindCache = class {
     return this._accessLevel;
   }
   get hasSystemAccess() {
-    return this._accessLevel === "system";
+    return this._accessLevel === "admin";
+  }
+  // ============================================
+  // Context Methods (client-local filtering)
+  // ============================================
+  /**
+   * Check if context filtering is currently active.
+   */
+  get hasContext() {
+    return this._contextRules !== null;
+  }
+  /**
+   * Get current context rules, or null if no context is set.
+   */
+  get_context() {
+    return this._contextRules;
+  }
+  /**
+   * Set context filtering rules.
+   * When context is set, only keys with ALL specified tags are visible.
+   *
+   * @param rules - Context rules, or array of tags (shorthand for { tags: [...] })
+   */
+  set_context(rules) {
+    if (Array.isArray(rules)) {
+      this._contextRules = { tags: rules };
+    } else {
+      this._contextRules = rules;
+    }
+  }
+  /**
+   * Clear context filtering. All keys become visible again.
+   */
+  reset_context() {
+    this._contextRules = null;
+  }
+  /**
+   * Check if a key matches the current context rules.
+   * Returns true if no context is set.
+   */
+  keyMatchesContext(key) {
+    if (key.startsWith("$")) {
+      return true;
+    }
+    if (!this._contextRules) {
+      return true;
+    }
+    if (this._contextRules.tags.length === 0) {
+      return true;
+    }
+    const entryMap = this.rootMap.get(key);
+    if (!entryMap) {
+      return false;
+    }
+    const attrs = entryMap.get("attributes");
+    const contentTags = attrs?.contentTags || [];
+    return this._contextRules.tags.every((tag) => contentTags.includes(tag));
+  }
+  /**
+   * Create a new key with optional default tags from context.
+   *
+   * @throws Error if key already exists
+   */
+  create_key(key, value, attributes) {
+    if (this.rootMap.has(key)) {
+      throw new Error(`Key already exists: ${key}. Use set_value to update.`);
+    }
+    let finalAttributes = { ...attributes };
+    if (this._contextRules) {
+      const contextContentTags = this._contextRules.defaultContentTags || this._contextRules.tags;
+      const existingContentTags = finalAttributes.contentTags || [];
+      finalAttributes.contentTags = [.../* @__PURE__ */ new Set([...existingContentTags, ...contextContentTags])];
+      if (this._contextRules.defaultSystemTags) {
+        const existingSystemTags = finalAttributes.systemTags || [];
+        finalAttributes.systemTags = [.../* @__PURE__ */ new Set([...existingSystemTags, ...this._contextRules.defaultSystemTags])];
+      }
+    }
+    const entryMap = new Y__namespace.Map();
+    this.rootMap.set(key, entryMap);
+    this.getUndoManager(key);
+    this.doc.transact(() => {
+      const baseAttributes = {
+        ...DEFAULT_KEY_ATTRIBUTES,
+        ...finalAttributes
+      };
+      if (baseAttributes.systemTags) {
+        baseAttributes.systemTags = this.normalizeSystemTags(baseAttributes.systemTags);
+      }
+      let valueToSet = value;
+      if (baseAttributes.type === "document" && !(valueToSet instanceof Y__namespace.Text)) {
+        valueToSet = new Y__namespace.Text(typeof value === "string" ? value : String(value ?? ""));
+      }
+      entryMap.set("value", valueToSet);
+      entryMap.set("attributes", baseAttributes);
+    });
   }
   async _initCloud() {
     if (!this._cloudConfig) {
@@ -924,10 +1883,11 @@ var MindCache = class {
         this.rootMap.set(key, entryMap);
         entryMap.set("value", entry.value);
         const attrs = entry.attributes || {};
+        const contentTags = attrs.contentTags || attrs.tags || [];
         const normalizedAttrs = {
           type: attrs.type || "text",
           contentType: attrs.contentType,
-          contentTags: attrs.contentTags || [],
+          contentTags,
           systemTags: this.normalizeSystemTags(attrs.systemTags || []),
           zIndex: attrs.zIndex ?? 0
         };
@@ -970,10 +1930,21 @@ var MindCache = class {
     return false;
   }
   // InjectSTM replacement (private helper)
+  // Handles special template variables: $date, $time, $version
   _injectSTMInternal(template, _processingStack) {
     return template.replace(/\{\{([^}]+)\}\}/g, (_, key) => {
-      const val = this.get_value(key.trim(), _processingStack);
-      return val !== void 0 ? String(val) : `{{${key}}}`;
+      const trimmedKey = key.trim();
+      if (trimmedKey === "$date") {
+        return (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+      }
+      if (trimmedKey === "$time") {
+        return (/* @__PURE__ */ new Date()).toTimeString().split(" ")[0];
+      }
+      if (trimmedKey === "$version") {
+        return this.version;
+      }
+      const val = this.get_value(trimmedKey, _processingStack);
+      return val !== void 0 ? String(val) : "";
     });
   }
   /**
@@ -988,10 +1959,10 @@ var MindCache = class {
   getAll() {
     const result = {};
     for (const [key] of this.rootMap) {
-      result[key] = this.get_value(key);
+      if (this.keyMatchesContext(key)) {
+        result[key] = this.get_value(key);
+      }
     }
-    result["$date"] = this.get_value("$date");
-    result["$time"] = this.get_value("$time");
     return result;
   }
   /**
@@ -1002,30 +1973,24 @@ var MindCache = class {
   getAllEntries() {
     const result = {};
     for (const [key] of this.rootMap) {
-      const value = this.get_value(key);
-      const attributes = this.get_attributes(key);
-      if (attributes) {
-        result[key] = { value, attributes };
+      if (this.keyMatchesContext(key)) {
+        const value = this.get_value(key);
+        const attributes = this.get_attributes(key);
+        if (attributes) {
+          result[key] = { value, attributes };
+        }
       }
     }
     return result;
   }
   get_value(key, _processingStack) {
-    if (key === "$date") {
-      const today = /* @__PURE__ */ new Date();
-      return today.toISOString().split("T")[0];
-    }
-    if (key === "$time") {
-      const now = /* @__PURE__ */ new Date();
-      return now.toTimeString().split(" ")[0];
-    }
-    if (key === "$version") {
-      return this.version;
-    }
     const entryMap = this.rootMap.get(key);
     if (!entryMap) {
       return void 0;
     }
+    if (!this.keyMatchesContext(key)) {
+      return void 0;
+    }
     const attributes = entryMap.get("attributes");
     const value = entryMap.get("value");
     if (attributes?.type === "document" && value instanceof Y__namespace.Text) {
@@ -1044,28 +2009,21 @@ var MindCache = class {
     return value;
   }
   get_attributes(key) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return {
-        type: "text",
-        contentTags: [],
-        systemTags: ["SystemPrompt", "protected"],
-        zIndex: 999999
-      };
-    }
     const entryMap = this.rootMap.get(key);
     return entryMap ? entryMap.get("attributes") : void 0;
   }
   /**
    * Update only the attributes of a key without modifying the value.
    * Useful for updating tags, permissions etc. on document type keys.
+   * @returns true if attributes were updated, false if key doesn't exist or is protected
    */
   set_attributes(key, attributes) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return;
-    }
     const entryMap = this.rootMap.get(key);
     if (!entryMap) {
-      return;
+      return false;
+    }
+    if (this._contextRules && !this.keyMatchesContext(key)) {
+      throw new Error(`Cannot modify key "${key}": does not match current context`);
     }
     this.doc.transact(() => {
       const existingAttrs = entryMap.get("attributes");
@@ -1083,13 +2041,14 @@ var MindCache = class {
         entryMap.set("value", currentValue.toString());
       }
     });
+    return true;
   }
   set_value(key, value, attributes) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return;
-    }
     const existingEntry = this.rootMap.get(key);
     if (existingEntry) {
+      if (this._contextRules && !this.keyMatchesContext(key)) {
+        throw new Error(`Cannot modify key "${key}": does not match current context`);
+      }
       const existingAttrs = existingEntry.get("attributes");
       if (existingAttrs?.type === "document") {
         if (!attributes?.type || attributes.type === "document") {
@@ -1103,6 +2062,10 @@ var MindCache = class {
         }
       }
     }
+    if (!existingEntry && this._contextRules) {
+      this.create_key(key, value, attributes);
+      return;
+    }
     if (!existingEntry && attributes?.type === "document") {
       this.set_document(key, typeof value === "string" ? value : "", attributes);
       return;
@@ -1143,9 +2106,6 @@ var MindCache = class {
    * Used by create_vercel_ai_tools() to prevent LLMs from escalating privileges.
    */
   llm_set_key(key, value) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
     const entryMap = this.rootMap.get(key);
     if (!entryMap) {
       return false;
@@ -1166,9 +2126,6 @@ var MindCache = class {
     return true;
   }
   delete_key(key) {
-    if (key === "$date" || key === "$time") {
-      return;
-    }
     this.rootMap.delete(key);
   }
   clear() {
@@ -1184,19 +2141,16 @@ var MindCache = class {
    * Check if a key exists in MindCache.
    */
   has(key) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return true;
+    if (!this.rootMap.has(key)) {
+      return false;
     }
-    return this.rootMap.has(key);
+    return this.keyMatchesContext(key);
   }
   /**
    * Delete a key from MindCache.
    * @returns true if the key existed and was deleted
    */
   delete(key) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
     if (!this.rootMap.has(key)) {
       return false;
     }
@@ -1222,9 +2176,7 @@ var MindCache = class {
   update(data) {
     this.doc.transact(() => {
       for (const [key, value] of Object.entries(data)) {
-        if (key !== "$date" && key !== "$time" && key !== "$version") {
-          this.set_value(key, value);
-        }
+        this.set_value(key, value);
       }
     });
     this.notifyGlobalListeners();
@@ -1233,38 +2185,48 @@ var MindCache = class {
    * Get the number of keys in MindCache.
    */
   size() {
-    return this.rootMap.size + 2;
+    let count = 0;
+    for (const [key] of this.rootMap) {
+      if (this.keyMatchesContext(key)) {
+        count++;
+      }
+    }
+    return count;
   }
   /**
-   * Get all keys in MindCache (including temporal keys).
+   * Get all keys in MindCache.
    */
   keys() {
-    const keys = Array.from(this.rootMap.keys());
-    keys.push("$date", "$time");
+    const keys = [];
+    for (const [key] of this.rootMap) {
+      if (this.keyMatchesContext(key)) {
+        keys.push(key);
+      }
+    }
     return keys;
   }
   /**
-   * Get all values in MindCache (including temporal values).
+   * Get all values in MindCache.
    */
   values() {
     const result = [];
     for (const [key] of this.rootMap) {
-      result.push(this.get_value(key));
+      if (this.keyMatchesContext(key)) {
+        result.push(this.get_value(key));
+      }
     }
-    result.push(this.get_value("$date"));
-    result.push(this.get_value("$time"));
     return result;
   }
   /**
-   * Get all key-value entries (including temporal entries).
+   * Get all key-value entries.
    */
   entries() {
     const result = [];
     for (const [key] of this.rootMap) {
-      result.push([key, this.get_value(key)]);
+      if (this.keyMatchesContext(key)) {
+        result.push([key, this.get_value(key)]);
+      }
     }
-    result.push(["$date", this.get_value("$date")]);
-    result.push(["$time", this.get_value("$time")]);
     return result;
   }
   /**
@@ -1285,7 +2247,6 @@ var MindCache = class {
   }
   /**
    * Get the STM as an object with values directly (no attributes).
-   * Includes system keys ($date, $time).
    * @deprecated Use getAll() for full STM format
    */
   getSTMObject() {
@@ -1293,8 +2254,6 @@ var MindCache = class {
     for (const [key] of this.rootMap) {
       result[key] = this.get_value(key);
     }
-    result["$date"] = this.get_value("$date");
-    result["$time"] = this.get_value("$time");
     return result;
   }
   /**
@@ -1302,479 +2261,132 @@ var MindCache = class {
    * @returns true if the tag was added, false if key doesn't exist or tag already exists
    */
   addTag(key, tag) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return false;
-    }
-    const attributes = entryMap.get("attributes");
-    const contentTags = attributes?.contentTags || [];
-    if (contentTags.includes(tag)) {
-      return false;
-    }
-    this.doc.transact(() => {
-      const newContentTags = [...contentTags, tag];
-      entryMap.set("attributes", {
-        ...attributes,
-        contentTags: newContentTags,
-        tags: newContentTags
-        // Sync legacy tags array
-      });
-    });
-    this.notifyGlobalListeners();
-    return true;
+    return TagManager.addTag(this, key, tag);
   }
   /**
    * Remove a content tag from a key.
    * @returns true if the tag was removed
    */
   removeTag(key, tag) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return false;
-    }
-    const attributes = entryMap.get("attributes");
-    const contentTags = attributes?.contentTags || [];
-    const tagIndex = contentTags.indexOf(tag);
-    if (tagIndex === -1) {
-      return false;
-    }
-    this.doc.transact(() => {
-      const newContentTags = contentTags.filter((t) => t !== tag);
-      entryMap.set("attributes", {
-        ...attributes,
-        contentTags: newContentTags,
-        tags: newContentTags
-        // Sync legacy tags array
-      });
-    });
-    this.notifyGlobalListeners();
-    return true;
-  }
-  /**
-   * Get all content tags for a key.
-   */
-  getTags(key) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return [];
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return [];
-    }
-    const attributes = entryMap.get("attributes");
-    return attributes?.contentTags || [];
-  }
-  /**
-   * Get all unique content tags across all keys.
-   */
-  getAllTags() {
-    const allTags = /* @__PURE__ */ new Set();
-    for (const [, val] of this.rootMap) {
-      const entryMap = val;
-      const attributes = entryMap.get("attributes");
-      if (attributes?.contentTags) {
-        attributes.contentTags.forEach((tag) => allTags.add(tag));
-      }
-    }
-    return Array.from(allTags);
-  }
-  /**
-   * Check if a key has a specific content tag.
-   */
-  hasTag(key, tag) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return false;
-    }
-    const attributes = entryMap.get("attributes");
-    return attributes?.contentTags?.includes(tag) || false;
-  }
-  /**
-   * Get all keys with a specific content tag as formatted string.
-   */
-  getTagged(tag) {
-    const entries = [];
-    const keys = this.getSortedKeys();
-    keys.forEach((key) => {
-      if (this.hasTag(key, tag)) {
-        entries.push([key, this.get_value(key)]);
-      }
-    });
-    return entries.map(([key, value]) => `${key}: ${value}`).join(", ");
+    return TagManager.removeTag(this, key, tag);
   }
-  /**
-   * Get array of keys with a specific content tag.
-   */
-  getKeysByTag(tag) {
-    const keys = this.getSortedKeys();
-    return keys.filter((key) => this.hasTag(key, tag));
-  }
-  // ============================================
-  // System Tag Methods (requires system access level)
-  // ============================================
-  /**
-   * Add a system tag to a key (requires system access).
-   * System tags: 'SystemPrompt', 'LLMRead', 'LLMWrite', 'readonly', 'protected', 'ApplyTemplate'
-   */
-  systemAddTag(key, tag) {
-    if (!this.hasSystemAccess) {
-      console.warn("MindCache: systemAddTag requires system access level");
-      return false;
-    }
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return false;
-    }
-    const attributes = entryMap.get("attributes");
-    const systemTags = attributes?.systemTags || [];
-    if (systemTags.includes(tag)) {
-      return false;
-    }
-    this.doc.transact(() => {
-      const newSystemTags = [...systemTags, tag];
-      const normalizedTags = this.normalizeSystemTags(newSystemTags);
-      entryMap.set("attributes", {
-        ...attributes,
-        systemTags: normalizedTags
-      });
-    });
-    this.notifyGlobalListeners();
-    return true;
-  }
-  /**
-   * Remove a system tag from a key (requires system access).
-   */
-  systemRemoveTag(key, tag) {
-    if (!this.hasSystemAccess) {
-      console.warn("MindCache: systemRemoveTag requires system access level");
-      return false;
-    }
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return false;
-    }
-    const attributes = entryMap.get("attributes");
-    const systemTags = attributes?.systemTags || [];
-    const tagIndex = systemTags.indexOf(tag);
-    if (tagIndex === -1) {
-      return false;
-    }
-    this.doc.transact(() => {
-      const newSystemTags = systemTags.filter((t) => t !== tag);
-      entryMap.set("attributes", {
-        ...attributes,
-        systemTags: newSystemTags
-      });
-    });
-    this.notifyGlobalListeners();
-    return true;
+  /**
+   * Get all content tags for a key.
+   */
+  getTags(key) {
+    return TagManager.getTags(this, key);
   }
   /**
-   * Get all system tags for a key (requires system access).
+   * Get all unique content tags across all keys.
    */
-  systemGetTags(key) {
-    if (!this.hasSystemAccess) {
-      console.warn("MindCache: systemGetTags requires system access level");
-      return [];
-    }
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return [];
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return [];
-    }
-    const attributes = entryMap.get("attributes");
-    return attributes?.systemTags || [];
+  getAllTags() {
+    return TagManager.getAllTags(this);
   }
   /**
-   * Check if a key has a specific system tag (requires system access).
+   * Check if a key has a specific content tag.
    */
-  systemHasTag(key, tag) {
-    if (!this.hasSystemAccess) {
-      console.warn("MindCache: systemHasTag requires system access level");
-      return false;
-    }
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return false;
-    }
-    const attributes = entryMap.get("attributes");
-    return attributes?.systemTags?.includes(tag) || false;
+  hasTag(key, tag) {
+    return TagManager.hasTag(this, key, tag);
   }
   /**
-   * Set all system tags for a key at once (requires system access).
+   * Get all keys with a specific content tag as formatted string.
    */
-  systemSetTags(key, tags) {
-    if (!this.hasSystemAccess) {
-      console.warn("MindCache: systemSetTags requires system access level");
-      return false;
-    }
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return false;
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return false;
-    }
-    this.doc.transact(() => {
-      const attributes = entryMap.get("attributes");
-      entryMap.set("attributes", {
-        ...attributes,
-        systemTags: [...tags]
-      });
-    });
-    this.notifyGlobalListeners();
-    return true;
+  getTagged(tag) {
+    return TagManager.getTagged(this, tag);
   }
   /**
-   * Get all keys with a specific system tag (requires system access).
+   * Get array of keys with a specific content tag.
    */
-  systemGetKeysByTag(tag) {
-    if (!this.hasSystemAccess) {
-      console.warn("MindCache: systemGetKeysByTag requires system access level");
-      return [];
-    }
-    const keys = this.getSortedKeys();
-    return keys.filter((key) => this.systemHasTag(key, tag));
+  getKeysByTag(tag) {
+    return TagManager.getKeysByTag(this, tag);
   }
+  // ============================================
+  // System Tag Methods (requires system access level)
+  // ============================================
   /**
-   * Helper to get sorted keys (by zIndex).
+   * Add a system tag to a key (requires system access).
+   * System tags: 'SystemPrompt', 'LLMRead', 'LLMWrite', 'ApplyTemplate'
    */
-  getSortedKeys() {
-    const entries = [];
-    for (const [key, val] of this.rootMap) {
-      const entryMap = val;
-      const attributes = entryMap.get("attributes");
-      entries.push({ key, zIndex: attributes?.zIndex ?? 0 });
-    }
-    return entries.sort((a, b) => a.zIndex - b.zIndex).map((e) => e.key);
+  systemAddTag(key, tag) {
+    return TagManager.systemAddTag(this, key, tag);
   }
   /**
-   * Serialize to JSON string.
+   * Remove a system tag from a key (requires system access).
    */
-  toJSON() {
-    return JSON.stringify(this.serialize());
+  systemRemoveTag(key, tag) {
+    return TagManager.systemRemoveTag(this, key, tag);
   }
   /**
-   * Deserialize from JSON string.
+   * Get all system tags for a key (requires system access).
    */
-  fromJSON(jsonString) {
-    try {
-      const data = JSON.parse(jsonString);
-      this.deserialize(data);
-    } catch (error) {
-      console.error("MindCache: Failed to deserialize JSON:", error);
-    }
+  systemGetTags(key) {
+    return TagManager.systemGetTags(this, key);
   }
   /**
-   * Export to Markdown format.
+   * Check if a key has a specific system tag (requires system access).
    */
-  toMarkdown() {
-    const now = /* @__PURE__ */ new Date();
-    const lines = [];
-    const appendixEntries = [];
-    let appendixCounter = 0;
-    lines.push("# MindCache STM Export");
-    lines.push("");
-    lines.push(`Export Date: ${now.toISOString().split("T")[0]}`);
-    lines.push("");
-    lines.push("---");
-    lines.push("");
-    lines.push("## STM Entries");
-    lines.push("");
-    const sortedKeys = this.getSortedKeys();
-    sortedKeys.forEach((key) => {
-      const entryMap = this.rootMap.get(key);
-      if (!entryMap) {
-        return;
-      }
-      const attributes = entryMap.get("attributes");
-      const value = entryMap.get("value");
-      if (attributes?.systemTags?.includes("protected")) {
-        return;
-      }
-      lines.push(`### ${key}`);
-      const entryType = attributes?.type || "text";
-      lines.push(`- **Type**: \`${entryType}\``);
-      lines.push(`- **System Tags**: \`${attributes?.systemTags?.join(", ") || "none"}\``);
-      lines.push(`- **Z-Index**: \`${attributes?.zIndex ?? 0}\``);
-      if (attributes?.contentTags && attributes.contentTags.length > 0) {
-        lines.push(`- **Tags**: \`${attributes.contentTags.join("`, `")}\``);
-      }
-      if (attributes?.contentType) {
-        lines.push(`- **Content Type**: \`${attributes.contentType}\``);
-      }
-      if (entryType === "image" || entryType === "file") {
-        const label = String.fromCharCode(65 + appendixCounter);
-        appendixCounter++;
-        lines.push(`- **Value**: [See Appendix ${label}]`);
-        appendixEntries.push({
-          key,
-          type: entryType,
-          contentType: attributes?.contentType || "application/octet-stream",
-          base64: value,
-          label
-        });
-      } else if (entryType === "json") {
-        lines.push("- **Value**:");
-        lines.push("```json");
-        try {
-          const jsonValue = typeof value === "string" ? value : JSON.stringify(value, null, 2);
-          lines.push(jsonValue);
-        } catch {
-          lines.push(String(value));
-        }
-        lines.push("```");
-      } else {
-        lines.push("- **Value**:");
-        lines.push("```");
-        lines.push(String(value));
-        lines.push("```");
-      }
-      lines.push("");
-    });
-    if (appendixEntries.length > 0) {
-      lines.push("---");
-      lines.push("");
-      lines.push("## Appendix: Binary Data");
-      lines.push("");
-      appendixEntries.forEach((entry) => {
-        lines.push(`### Appendix ${entry.label}: ${entry.key}`);
-        lines.push(`- **Type**: \`${entry.type}\``);
-        lines.push(`- **Content Type**: \`${entry.contentType}\``);
-        lines.push("- **Base64 Data**:");
-        lines.push("```");
-        lines.push(entry.base64);
-        lines.push("```");
-        lines.push("");
-      });
-    }
-    return lines.join("\n");
+  systemHasTag(key, tag) {
+    return TagManager.systemHasTag(this, key, tag);
   }
   /**
-   * Import from Markdown format.
+   * Set all system tags for a key at once (requires system access).
    */
-  fromMarkdown(markdown) {
-    const lines = markdown.split("\n");
-    let currentKey = null;
-    let currentAttributes = {};
-    let currentValue = null;
-    let inCodeBlock = false;
-    let codeBlockContent = [];
-    for (const line of lines) {
-      if (line.startsWith("### ") && !line.startsWith("### Appendix")) {
-        if (currentKey && currentValue !== null) {
-          this.set_value(currentKey, currentValue.trim(), currentAttributes);
-        }
-        currentKey = line.substring(4).trim();
-        currentAttributes = {};
-        currentValue = null;
-        continue;
-      }
-      if (line.startsWith("### Appendix ")) {
-        const match = line.match(/### Appendix ([A-Z]): (.+)/);
-        if (match) {
-          currentKey = match[2];
-        }
-        continue;
-      }
-      if (line.startsWith("- **Type**:")) {
-        const type = line.match(/`(.+)`/)?.[1];
-        if (type) {
-          currentAttributes.type = type;
-        }
-        continue;
-      }
-      if (line.startsWith("- **System Tags**:")) {
-        const tagsStr = line.match(/`([^`]+)`/)?.[1] || "";
-        if (tagsStr !== "none") {
-          currentAttributes.systemTags = tagsStr.split(", ").filter((t) => t);
-        }
-        continue;
-      }
-      if (line.startsWith("- **Z-Index**:")) {
-        const zIndex = parseInt(line.match(/`(\d+)`/)?.[1] || "0", 10);
-        currentAttributes.zIndex = zIndex;
-        continue;
-      }
-      if (line.startsWith("- **Tags**:")) {
-        const tags = line.match(/`([^`]+)`/g)?.map((t) => t.slice(1, -1)) || [];
-        currentAttributes.contentTags = tags;
-        continue;
-      }
-      if (line.startsWith("- **Content Type**:")) {
-        currentAttributes.contentType = line.match(/`(.+)`/)?.[1];
-        continue;
-      }
-      if (line.startsWith("- **Value**:") && !line.includes("[See Appendix")) {
-        const afterValue = line.substring(12).trim();
-        if (afterValue === "") {
-          currentValue = "";
-        } else if (afterValue === "```" || afterValue === "```json") {
-          inCodeBlock = true;
-          codeBlockContent = [];
-          currentValue = "";
-        } else if (afterValue.startsWith("```")) {
-          inCodeBlock = true;
-          codeBlockContent = [afterValue.substring(3)];
-          currentValue = "";
-        } else {
-          currentValue = afterValue;
-        }
-        continue;
-      }
-      const trimmedLine = line.trim();
-      if (trimmedLine === "```json" || trimmedLine === "```") {
-        if (inCodeBlock) {
-          inCodeBlock = false;
-          if (currentKey && codeBlockContent.length > 0) {
-            currentValue = codeBlockContent.join("\n");
-          }
-          codeBlockContent = [];
-        } else {
-          inCodeBlock = true;
-          codeBlockContent = [];
-        }
+  systemSetTags(key, tags) {
+    return TagManager.systemSetTags(this, key, tags);
+  }
+  /**
+   * Get all keys with a specific system tag (requires system access).
+   */
+  systemGetKeysByTag(tag) {
+    return TagManager.systemGetKeysByTag(this, tag);
+  }
+  /**
+   * Helper to get sorted keys (by zIndex).
+   * Respects context filtering when set.
+   */
+  getSortedKeys() {
+    const entries = [];
+    for (const [key, val] of this.rootMap) {
+      if (!this.keyMatchesContext(key)) {
         continue;
       }
-      if (inCodeBlock) {
-        codeBlockContent.push(line);
-      } else if (currentKey && currentValue !== null) {
-        currentValue += "\n" + line;
-      }
-    }
-    if (currentKey && currentValue !== null) {
-      this.set_value(currentKey, currentValue.trim(), currentAttributes);
+      const entryMap = val;
+      const attributes = entryMap.get("attributes");
+      entries.push({ key, zIndex: attributes?.zIndex ?? 0 });
     }
-    const hasParsedKeys = lines.some((line) => line.startsWith("### ") && !line.startsWith("### Appendix"));
-    if (!hasParsedKeys && markdown.trim().length > 0) {
-      this.set_value("imported_content", markdown.trim(), {
-        type: "text",
-        systemTags: ["SystemPrompt", "LLMWrite"],
-        // Default assumptions
-        zIndex: 0
-      });
+    return entries.sort((a, b) => a.zIndex - b.zIndex).map((e) => e.key);
+  }
+  /**
+   * Serialize to JSON string.
+   */
+  toJSON() {
+    return JSON.stringify(this.serialize());
+  }
+  /**
+   * Deserialize from JSON string.
+   */
+  fromJSON(jsonString) {
+    try {
+      const data = JSON.parse(jsonString);
+      this.deserialize(data);
+    } catch (error) {
+      console.error("MindCache: Failed to deserialize JSON:", error);
     }
   }
+  /**
+   * Export to Markdown format.
+   */
+  toMarkdown() {
+    return MarkdownSerializer.toMarkdown(this);
+  }
+  /**
+   * Import from Markdown format.
+   * @param markdown The markdown string to import
+   * @param merge If false (default), clears existing data before importing. If true, merges with existing data.
+   */
+  fromMarkdown(markdown, merge = false) {
+    MarkdownSerializer.fromMarkdown(markdown, this, merge);
+  }
   /**
    * Set base64 binary data.
    */
@@ -1855,9 +2467,6 @@ var MindCache = class {
    * Note: This exposes Yjs Y.Text directly for editor bindings (y-quill, y-codemirror, etc.)
    */
   set_document(key, initialText, attributes) {
-    if (key === "$date" || key === "$time" || key === "$version") {
-      return;
-    }
     let entryMap = this.rootMap.get(key);
     if (!entryMap) {
       entryMap = new Y__namespace.Map();
@@ -1913,223 +2522,95 @@ var MindCache = class {
     const yText = this.get_document(key);
     if (yText) {
       yText.delete(index, length2);
-    }
-  }
-  /**
-   * Replace all text in a document key (private - use set_value for public API).
-   * Uses diff-based updates when changes are < diffThreshold (default 80%).
-   * This preserves concurrent edits and provides better undo granularity.
-   */
-  _replaceDocumentText(key, newText, diffThreshold = 0.8) {
-    const yText = this.get_document(key);
-    if (!yText) {
-      return;
-    }
-    const oldText = yText.toString();
-    if (oldText === newText) {
-      return;
-    }
-    if (oldText.length === 0) {
-      yText.insert(0, newText);
-      return;
-    }
-    const diffs = diff__default.default(oldText, newText);
-    let changedChars = 0;
-    for (const [op, text] of diffs) {
-      if (op !== 0) {
-        changedChars += text.length;
-      }
-    }
-    const changeRatio = changedChars / Math.max(oldText.length, newText.length);
-    if (changeRatio > diffThreshold) {
-      this.doc.transact(() => {
-        yText.delete(0, yText.length);
-        yText.insert(0, newText);
-      });
-      return;
-    }
-    this.doc.transact(() => {
-      let cursor = 0;
-      for (const [op, text] of diffs) {
-        if (op === 0) {
-          cursor += text.length;
-        } else if (op === -1) {
-          yText.delete(cursor, text.length);
-        } else if (op === 1) {
-          yText.insert(cursor, text);
-          cursor += text.length;
-        }
-      }
-    });
-  }
-  // ... (subscribe methods)
-  subscribe(key, listener) {
-    if (!this.listeners[key]) {
-      this.listeners[key] = [];
-    }
-    this.listeners[key].push(listener);
-    return () => {
-      this.listeners[key] = this.listeners[key].filter((l) => l !== listener);
-    };
-  }
-  subscribeToAll(listener) {
-    this.globalListeners.push(listener);
-    return () => {
-      this.globalListeners = this.globalListeners.filter((l) => l !== listener);
-    };
-  }
-  unsubscribeFromAll(listener) {
-    this.globalListeners = this.globalListeners.filter((l) => l !== listener);
-  }
-  notifyGlobalListeners() {
-    this.globalListeners.forEach((l) => l());
-  }
-  // Sanitize key name for use in tool names
-  sanitizeKeyForTool(key) {
-    return key.replace(/[^a-zA-Z0-9_-]/g, "_");
-  }
-  // Find original key from sanitized tool name
-  findKeyFromSanitizedTool(sanitizedKey) {
-    for (const [key] of this.rootMap) {
-      if (this.sanitizeKeyForTool(key) === sanitizedKey) {
-        return key;
-      }
-    }
-    return void 0;
-  }
-  /**
-   * Generate Vercel AI SDK compatible tools for writable keys.
-   * For document type keys, generates additional tools: append_, insert_, edit_
-   *
-   * Security: All tools use llm_set_key internally which:
-   * - Only modifies VALUES, never attributes/systemTags
-   * - Prevents LLMs from escalating privileges
-   */
-  create_vercel_ai_tools() {
-    const tools = {};
-    for (const [key, val] of this.rootMap) {
-      if (key.startsWith("$")) {
-        continue;
-      }
-      const entryMap = val;
-      const attributes = entryMap.get("attributes");
-      const isWritable = attributes?.systemTags?.includes("LLMWrite");
-      if (!isWritable) {
-        continue;
-      }
-      const sanitizedKey = this.sanitizeKeyForTool(key);
-      const isDocument = attributes?.type === "document";
-      tools[`write_${sanitizedKey}`] = {
-        description: isDocument ? `Rewrite the entire "${key}" document` : `Write a value to the STM key: ${key}`,
-        inputSchema: {
-          type: "object",
-          properties: {
-            value: { type: "string", description: isDocument ? "New document content" : "The value to write" }
-          },
-          required: ["value"]
-        },
-        execute: async ({ value }) => {
-          const success = this.llm_set_key(key, value);
-          if (success) {
-            return {
-              result: `Successfully wrote "${value}" to ${key}`,
-              key,
-              value
-            };
-          }
-          return {
-            result: `Failed to write to ${key} - permission denied or key not found`,
-            key,
-            error: true
-          };
-        }
-      };
-      if (isDocument) {
-        tools[`append_${sanitizedKey}`] = {
-          description: `Append text to the end of "${key}" document`,
-          inputSchema: {
-            type: "object",
-            properties: {
-              text: { type: "string", description: "Text to append" }
-            },
-            required: ["text"]
-          },
-          execute: async ({ text }) => {
-            if (!attributes?.systemTags?.includes("LLMWrite")) {
-              return { result: `Permission denied for ${key}`, key, error: true };
-            }
-            const yText = this.get_document(key);
-            if (yText) {
-              yText.insert(yText.length, text);
-              return {
-                result: `Successfully appended to ${key}`,
-                key,
-                appended: text
-              };
-            }
-            return { result: `Document ${key} not found`, key };
-          }
-        };
-        tools[`insert_${sanitizedKey}`] = {
-          description: `Insert text at a position in "${key}" document`,
-          inputSchema: {
-            type: "object",
-            properties: {
-              index: { type: "number", description: "Position to insert at (0 = start)" },
-              text: { type: "string", description: "Text to insert" }
-            },
-            required: ["index", "text"]
-          },
-          execute: async ({ index, text }) => {
-            if (!attributes?.systemTags?.includes("LLMWrite")) {
-              return { result: `Permission denied for ${key}`, key, error: true };
-            }
-            this.insert_text(key, index, text);
-            return {
-              result: `Successfully inserted text at position ${index} in ${key}`,
-              key,
-              index,
-              inserted: text
-            };
-          }
-        };
-        tools[`edit_${sanitizedKey}`] = {
-          description: `Find and replace text in "${key}" document`,
-          inputSchema: {
-            type: "object",
-            properties: {
-              find: { type: "string", description: "Text to find" },
-              replace: { type: "string", description: "Replacement text" }
-            },
-            required: ["find", "replace"]
-          },
-          execute: async ({ find, replace }) => {
-            if (!attributes?.systemTags?.includes("LLMWrite")) {
-              return { result: `Permission denied for ${key}`, key, error: true };
-            }
-            const yText = this.get_document(key);
-            if (yText) {
-              const text = yText.toString();
-              const idx = text.indexOf(find);
-              if (idx !== -1) {
-                yText.delete(idx, find.length);
-                yText.insert(idx, replace);
-                return {
-                  result: `Successfully replaced "${find}" with "${replace}" in ${key}`,
-                  key,
-                  find,
-                  replace,
-                  index: idx
-                };
-              }
-              return { result: `Text "${find}" not found in ${key}`, key };
-            }
-            return { result: `Document ${key} not found`, key };
-          }
-        };
+    }
+  }
+  /**
+   * Replace all text in a document key.
+   * Uses diff-based updates when changes are < diffThreshold (default 80%).
+   * This preserves concurrent edits and provides better undo granularity.
+   */
+  _replaceDocumentText(key, newText, diffThreshold = 0.8) {
+    const yText = this.get_document(key);
+    if (!yText) {
+      return;
+    }
+    const oldText = yText.toString();
+    if (oldText === newText) {
+      return;
+    }
+    if (oldText.length === 0) {
+      yText.insert(0, newText);
+      return;
+    }
+    const diffs = diff__default.default(oldText, newText);
+    let changedChars = 0;
+    for (const [op, text] of diffs) {
+      if (op !== 0) {
+        changedChars += text.length;
       }
     }
-    return tools;
+    const changeRatio = changedChars / Math.max(oldText.length, newText.length);
+    if (changeRatio > diffThreshold) {
+      this.doc.transact(() => {
+        yText.delete(0, yText.length);
+        yText.insert(0, newText);
+      });
+      return;
+    }
+    this.doc.transact(() => {
+      let cursor = 0;
+      for (const [op, text] of diffs) {
+        if (op === 0) {
+          cursor += text.length;
+        } else if (op === -1) {
+          yText.delete(cursor, text.length);
+        } else if (op === 1) {
+          yText.insert(cursor, text);
+          cursor += text.length;
+        }
+      }
+    });
+  }
+  // ... (subscribe methods)
+  subscribe(key, listener) {
+    if (!this.listeners[key]) {
+      this.listeners[key] = [];
+    }
+    this.listeners[key].push(listener);
+    return () => {
+      this.listeners[key] = this.listeners[key].filter((l) => l !== listener);
+    };
+  }
+  subscribeToAll(listener) {
+    this.globalListeners.push(listener);
+    return () => {
+      this.globalListeners = this.globalListeners.filter((l) => l !== listener);
+    };
+  }
+  unsubscribeFromAll(listener) {
+    this.globalListeners = this.globalListeners.filter((l) => l !== listener);
+  }
+  notifyGlobalListeners() {
+    this.globalListeners.forEach((l) => l());
+  }
+  // Sanitize key name for use in tool names
+  sanitizeKeyForTool(key) {
+    return AIToolBuilder.sanitizeKeyForTool(key);
+  }
+  // Find original key from sanitized tool name
+  findKeyFromSanitizedTool(sanitizedKey) {
+    return AIToolBuilder.findKeyFromSanitizedTool(this, sanitizedKey);
+  }
+  /**
+   * Generate Vercel AI SDK compatible tools for writable keys.
+   * For document type keys, generates additional tools: append_, insert_, edit_
+   *
+   * Security: All tools use llm_set_key internally which:
+   * - Only modifies VALUES, never attributes/systemTags
+   * - Prevents LLMs from escalating privileges
+   */
+  create_vercel_ai_tools() {
+    return AIToolBuilder.createVercelAITools(this);
   }
   /**
    * @deprecated Use create_vercel_ai_tools() instead
@@ -2142,121 +2623,14 @@ var MindCache = class {
    * Indicates which tools can be used to modify writable keys.
    */
   get_system_prompt() {
-    const lines = [];
-    for (const [key, val] of this.rootMap) {
-      if (key.startsWith("$")) {
-        continue;
-      }
-      const entryMap = val;
-      const attributes = entryMap.get("attributes");
-      const isVisible = attributes?.systemTags?.includes("SystemPrompt") || attributes?.systemTags?.includes("LLMRead");
-      if (!isVisible) {
-        continue;
-      }
-      const value = this.get_value(key);
-      const displayValue = typeof value === "object" ? JSON.stringify(value) : value;
-      const isWritable = attributes?.systemTags?.includes("LLMWrite");
-      const isDocument = attributes?.type === "document";
-      const sanitizedKey = this.sanitizeKeyForTool(key);
-      if (isWritable) {
-        if (isDocument) {
-          lines.push(
-            `${key}: ${displayValue}. Document tools: write_${sanitizedKey}, append_${sanitizedKey}, edit_${sanitizedKey}`
-          );
-        } else {
-          const oldValueHint = displayValue ? ` This tool DOES NOT append \u2014 start your response with the old value (${displayValue})` : "";
-          lines.push(
-            `${key}: ${displayValue}. You can rewrite "${key}" by using the write_${sanitizedKey} tool.${oldValueHint}`
-          );
-        }
-      } else {
-        lines.push(`${key}: ${displayValue}`);
-      }
-    }
-    lines.push(`$date: ${this.get_value("$date")}`);
-    lines.push(`$time: ${this.get_value("$time")}`);
-    return lines.join(", ");
+    return AIToolBuilder.getSystemPrompt(this);
   }
   /**
    * Execute a tool call by name with the given value.
    * Returns the result or null if tool not found.
    */
   executeToolCall(toolName, value) {
-    const match = toolName.match(/^(write|append|insert|edit)_(.+)$/);
-    if (!match) {
-      return null;
-    }
-    const [, action, sanitizedKey] = match;
-    const key = this.findKeyFromSanitizedTool(sanitizedKey);
-    if (!key) {
-      return null;
-    }
-    const entryMap = this.rootMap.get(key);
-    if (!entryMap) {
-      return null;
-    }
-    const attributes = entryMap.get("attributes");
-    const isWritable = attributes?.systemTags?.includes("LLMWrite");
-    if (!isWritable) {
-      return null;
-    }
-    const isDocument = attributes?.type === "document";
-    switch (action) {
-      case "write":
-        if (isDocument) {
-          this._replaceDocumentText(key, value);
-        } else {
-          this.set_value(key, value);
-        }
-        return {
-          result: `Successfully wrote "${value}" to ${key}`,
-          key,
-          value
-        };
-      case "append":
-        if (isDocument) {
-          const yText = this.get_document(key);
-          if (yText) {
-            yText.insert(yText.length, value);
-            return {
-              result: `Successfully appended to ${key}`,
-              key,
-              value
-            };
-          }
-        }
-        return null;
-      case "insert":
-        if (isDocument && typeof value === "object" && value.index !== void 0 && value.text) {
-          this.insert_text(key, value.index, value.text);
-          return {
-            result: `Successfully inserted at position ${value.index} in ${key}`,
-            key,
-            value: value.text
-          };
-        }
-        return null;
-      case "edit":
-        if (isDocument && typeof value === "object" && value.find && value.replace !== void 0) {
-          const yText = this.get_document(key);
-          if (yText) {
-            const text = yText.toString();
-            const idx = text.indexOf(value.find);
-            if (idx !== -1) {
-              yText.delete(idx, value.find.length);
-              yText.insert(idx, value.replace);
-              return {
-                result: `Successfully replaced "${value.find}" with "${value.replace}" in ${key}`,
-                key,
-                value: value.replace
-              };
-            }
-          }
-        }
-        return null;
-      default:
-        return null;
-    }
+    return AIToolBuilder.executeToolCall(this, toolName, value);
   }
   // Internal method stub for legacy compatibility
   _setFromRemote(_key, _value, _attributes) {
@@ -2271,6 +2645,325 @@ var MindCache = class {
 init_CloudAdapter();
 init_CloudAdapter();
 
+// src/cloud/OAuthClient.ts
+var DEFAULT_AUTH_URL = "https://api.mindcache.dev/oauth/authorize";
+var DEFAULT_TOKEN_URL = "https://api.mindcache.dev/oauth/token";
+var DEFAULT_USERINFO_URL = "https://api.mindcache.dev/oauth/userinfo";
+var TOKEN_REFRESH_BUFFER = 5 * 60 * 1e3;
+function generateRandomString(length2) {
+  const array = new Uint8Array(length2);
+  crypto.getRandomValues(array);
+  return Array.from(array).map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, length2);
+}
+function base64UrlEncode(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function generateCodeVerifier() {
+  return generateRandomString(64);
+}
+async function generateCodeChallenge(verifier) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return base64UrlEncode(hash);
+}
+var OAuthClient = class {
+  config;
+  tokens = null;
+  refreshPromise = null;
+  constructor(config) {
+    let redirectUri = config.redirectUri;
+    if (!redirectUri && typeof window !== "undefined") {
+      const url = new URL(window.location.href);
+      url.search = "";
+      url.hash = "";
+      redirectUri = url.toString();
+    }
+    this.config = {
+      clientId: config.clientId,
+      redirectUri: redirectUri || "",
+      scopes: config.scopes || ["read", "write"],
+      authUrl: config.authUrl || DEFAULT_AUTH_URL,
+      tokenUrl: config.tokenUrl || DEFAULT_TOKEN_URL,
+      usePKCE: config.usePKCE !== false,
+      // Default true
+      storagePrefix: config.storagePrefix || "mindcache_oauth"
+    };
+    this.loadTokens();
+  }
+  /**
+     * Check if user is authenticated
+     */
+  isAuthenticated() {
+    return this.tokens !== null && this.tokens.expiresAt > Date.now();
+  }
+  /**
+     * Get stored tokens (if any)
+     */
+  getTokens() {
+    return this.tokens;
+  }
+  /**
+     * Get instance ID for this user+app
+     */
+  getInstanceId() {
+    return this.tokens?.instanceId || null;
+  }
+  /**
+     * Start OAuth authorization flow
+     * Redirects to MindCache authorization page
+     */
+  async authorize(options) {
+    const state = options?.state || generateRandomString(32);
+    this.setStorage("state", state);
+    const url = new URL(this.config.authUrl);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", this.config.clientId);
+    url.searchParams.set("redirect_uri", this.config.redirectUri);
+    url.searchParams.set("scope", this.config.scopes.join(" "));
+    url.searchParams.set("state", state);
+    if (this.config.usePKCE) {
+      const codeVerifier = generateCodeVerifier();
+      const codeChallenge = await generateCodeChallenge(codeVerifier);
+      this.setStorage("code_verifier", codeVerifier);
+      url.searchParams.set("code_challenge", codeChallenge);
+      url.searchParams.set("code_challenge_method", "S256");
+    }
+    if (options?.popup) {
+      const popup = window.open(url.toString(), "mindcache_oauth", "width=500,height=600");
+      if (!popup) {
+        throw new Error("Popup blocked. Please allow popups for this site.");
+      }
+    } else {
+      window.location.href = url.toString();
+    }
+  }
+  /**
+     * Handle OAuth callback
+     * Call this on your redirect URI page
+     *
+     * @returns Tokens if successful
+     */
+  async handleCallback() {
+    if (typeof window === "undefined") {
+      throw new Error("handleCallback must be called in browser");
+    }
+    const url = new URL(window.location.href);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    const error = url.searchParams.get("error");
+    const errorDescription = url.searchParams.get("error_description");
+    if (error) {
+      this.clearStorage();
+      throw new Error(errorDescription || error);
+    }
+    const storedState = this.getStorage("state");
+    if (!state || state !== storedState) {
+      this.clearStorage();
+      throw new Error("Invalid state parameter");
+    }
+    if (!code) {
+      this.clearStorage();
+      throw new Error("No authorization code received");
+    }
+    const body = {
+      grant_type: "authorization_code",
+      code,
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri
+    };
+    if (this.config.usePKCE) {
+      const codeVerifier = this.getStorage("code_verifier");
+      if (!codeVerifier) {
+        throw new Error("Missing code verifier");
+      }
+      body.code_verifier = codeVerifier;
+    }
+    const response = await fetch(this.config.tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const data2 = await response.json().catch(() => ({}));
+      throw new Error(data2.error_description || data2.error || "Token exchange failed");
+    }
+    const data = await response.json();
+    this.tokens = {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      expiresAt: Date.now() + data.expires_in * 1e3,
+      scopes: data.scope?.split(" ") || this.config.scopes,
+      instanceId: data.instance_id
+    };
+    this.saveTokens();
+    url.searchParams.delete("code");
+    url.searchParams.delete("state");
+    window.history.replaceState({}, "", url.toString());
+    this.removeStorage("state");
+    this.removeStorage("code_verifier");
+    return this.tokens;
+  }
+  /**
+     * Get a valid access token
+     * Automatically refreshes if needed
+     */
+  async getAccessToken() {
+    if (!this.tokens) {
+      throw new Error("Not authenticated. Call authorize() first.");
+    }
+    const needsRefresh = this.tokens.expiresAt - Date.now() < TOKEN_REFRESH_BUFFER;
+    if (needsRefresh && this.tokens.refreshToken) {
+      if (!this.refreshPromise) {
+        this.refreshPromise = this.refreshTokens();
+      }
+      return this.refreshPromise;
+    }
+    return this.tokens.accessToken;
+  }
+  /**
+     * Refresh access token
+     */
+  async refreshTokens() {
+    if (!this.tokens?.refreshToken) {
+      throw new Error("No refresh token available");
+    }
+    try {
+      const response = await fetch(this.config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          grant_type: "refresh_token",
+          refresh_token: this.tokens.refreshToken,
+          client_id: this.config.clientId
+        })
+      });
+      if (!response.ok) {
+        this.clearAuth();
+        throw new Error("Session expired. Please sign in again.");
+      }
+      const data = await response.json();
+      this.tokens = {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token || this.tokens.refreshToken,
+        expiresAt: Date.now() + data.expires_in * 1e3,
+        scopes: data.scope?.split(" ") || this.tokens.scopes,
+        instanceId: data.instance_id || this.tokens.instanceId
+      };
+      this.saveTokens();
+      return this.tokens.accessToken;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+  /**
+     * Get user info from MindCache
+     */
+  async getUserInfo() {
+    const token = await this.getAccessToken();
+    const response = await fetch(DEFAULT_USERINFO_URL, {
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    });
+    if (!response.ok) {
+      throw new Error("Failed to get user info");
+    }
+    const data = await response.json();
+    return {
+      id: data.sub,
+      email: data.email,
+      name: data.name,
+      instanceId: data.instance_id
+    };
+  }
+  /**
+     * Logout - revoke tokens and clear storage
+     */
+  async logout() {
+    if (this.tokens?.accessToken) {
+      try {
+        await fetch(this.config.tokenUrl.replace("/token", "/revoke"), {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify({
+            token: this.tokens.accessToken
+          })
+        });
+      } catch {
+      }
+    }
+    this.clearAuth();
+  }
+  /**
+     * Clear authentication state
+     */
+  clearAuth() {
+    this.tokens = null;
+    this.removeStorage("tokens");
+  }
+  /**
+     * Token provider function for MindCache cloud config
+     * Use this with MindCacheCloudOptions.tokenProvider
+     */
+  tokenProvider = async () => {
+    return this.getAccessToken();
+  };
+  // Storage helpers
+  getStorage(key) {
+    if (typeof localStorage === "undefined") {
+      return null;
+    }
+    return localStorage.getItem(`${this.config.storagePrefix}_${key}`);
+  }
+  setStorage(key, value) {
+    if (typeof localStorage === "undefined") {
+      return;
+    }
+    localStorage.setItem(`${this.config.storagePrefix}_${key}`, value);
+  }
+  removeStorage(key) {
+    if (typeof localStorage === "undefined") {
+      return;
+    }
+    localStorage.removeItem(`${this.config.storagePrefix}_${key}`);
+  }
+  clearStorage() {
+    this.removeStorage("state");
+    this.removeStorage("code_verifier");
+    this.removeStorage("tokens");
+  }
+  loadTokens() {
+    const stored = this.getStorage("tokens");
+    if (stored) {
+      try {
+        this.tokens = JSON.parse(stored);
+      } catch {
+        this.tokens = null;
+      }
+    }
+  }
+  saveTokens() {
+    if (this.tokens) {
+      this.setStorage("tokens", JSON.stringify(this.tokens));
+    }
+  }
+};
+function createOAuthClient(config) {
+  return new OAuthClient(config);
+}
+
 // src/local/index.ts
 init_IndexedDBAdapter();
 function useMindCache(options) {
@@ -2313,7 +3006,9 @@ var mindcache = new MindCache();
 
 exports.DEFAULT_KEY_ATTRIBUTES = DEFAULT_KEY_ATTRIBUTES;
 exports.MindCache = MindCache;
+exports.OAuthClient = OAuthClient;
 exports.SystemTagHelpers = SystemTagHelpers;
+exports.createOAuthClient = createOAuthClient;
 exports.mindcache = mindcache;
 exports.useMindCache = useMindCache;
 //# sourceMappingURL=index.js.map