mindcache 2.0.0 → 2.3.0

package/dist/index.mjs

@@ -15,16 +15,17 @@ var CloudAdapter_exports = {};
 __export(CloudAdapter_exports, {
   CloudAdapter: () => CloudAdapter
 });
-var DEFAULT_BASE_URL, RECONNECT_DELAY, MAX_RECONNECT_DELAY, CloudAdapter;
+var RECONNECT_DELAY, MAX_RECONNECT_DELAY, CloudAdapter;
 var init_CloudAdapter = __esm({
   "src/cloud/CloudAdapter.ts"() {
-    DEFAULT_BASE_URL = "wss://api.mindcache.io";
     RECONNECT_DELAY = 1e3;
     MAX_RECONNECT_DELAY = 3e4;
     CloudAdapter = class {
       constructor(config) {
         this.config = config;
-        this.config.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+        if (!config.baseUrl) {
+          throw new Error("MindCache Cloud: baseUrl is required. Please provide the cloud API URL in your configuration.");
+        }
       }
       ws = null;
       queue = [];
@@ -85,6 +86,40 @@ var init_CloudAdapter = __esm({
         }
         this.mindcache = null;
       }
+      /**
+       * Fetch a short-lived WebSocket token from the API using the API key.
+       * This keeps the API key secure by only using it for a single HTTPS request,
+       * then using the short-lived token for the WebSocket connection.
+       *
+       * Supports two key formats:
+       * - API keys: mc_live_xxx or mc_test_xxx → Bearer token
+       * - Delegate keys: del_xxx:sec_xxx → ApiKey format
+       */
+      async fetchTokenWithApiKey() {
+        if (!this.config.apiKey) {
+          throw new Error("API key is required to fetch token");
+        }
+        const httpBaseUrl = this.config.baseUrl.replace("wss://", "https://").replace("ws://", "http://");
+        const isDelegate = this.config.apiKey.startsWith("del_") && this.config.apiKey.includes(":");
+        const authHeader = isDelegate ? `ApiKey ${this.config.apiKey}` : `Bearer ${this.config.apiKey}`;
+        const response = await fetch(`${httpBaseUrl}/api/ws-token`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": authHeader
+          },
+          body: JSON.stringify({
+            instanceId: this.config.instanceId,
+            permission: "write"
+          })
+        });
+        if (!response.ok) {
+          const error = await response.json().catch(() => ({ error: "Failed to get token" }));
+          throw new Error(error.error || `Failed to get WebSocket token: ${response.status}`);
+        }
+        const data = await response.json();
+        return data.token;
+      }
       /**
        * Connect to the cloud service
        */
@@ -94,13 +129,19 @@ var init_CloudAdapter = __esm({
         }
         this._state = "connecting";
         try {
-          if (this.config.tokenProvider && !this.token) {
-            this.token = await this.config.tokenProvider();
+          if (!this.token) {
+            if (this.config.tokenProvider) {
+              this.token = await this.config.tokenProvider();
+            } else if (this.config.apiKey) {
+              this.token = await this.fetchTokenWithApiKey();
+            }
           }
           let url = `${this.config.baseUrl}/sync/${this.config.instanceId}`;
           if (this.token) {
             url += `?token=${encodeURIComponent(this.token)}`;
             this.token = null;
+          } else {
+            throw new Error("MindCache Cloud: No authentication method available. Provide apiKey or tokenProvider.");
           }
           this.ws = new WebSocket(url);
           this.setupWebSocket();
@@ -162,12 +203,6 @@ var init_CloudAdapter = __esm({
           return;
         }
         this.ws.onopen = () => {
-          if (this.config.apiKey) {
-            this.ws.send(JSON.stringify({
-              type: "auth",
-              apiKey: this.config.apiKey
-            }));
-          }
         };
         this.ws.onmessage = (event) => {
           try {
@@ -175,6 +210,7 @@ var init_CloudAdapter = __esm({
             this.handleMessage(msg);
           } catch (error) {
             console.error("MindCache Cloud: Failed to parse message:", error);
+            console.error("Raw message:", typeof event.data === "string" ? event.data.slice(0, 200) : event.data);
           }
         };
         this.ws.onclose = () => {
@@ -182,10 +218,12 @@ var init_CloudAdapter = __esm({
           this.emit("disconnected");
           this.scheduleReconnect();
         };
-        this.ws.onerror = (error) => {
+        this.ws.onerror = () => {
           this._state = "error";
-          this.emit("error", new Error("WebSocket error"));
-          console.error("MindCache Cloud: WebSocket error:", error);
+          const url = `${this.config.baseUrl}/sync/${this.config.instanceId}`;
+          console.error(`MindCache Cloud: WebSocket error connecting to ${url}`);
+          console.error("Check that the instance ID and API key are correct, and that the server is reachable.");
+          this.emit("error", new Error(`WebSocket connection failed to ${url}`));
         };
       }
       handleMessage(msg) {
@@ -262,15 +300,6 @@ var init_CloudAdapter = __esm({
         this.reconnectTimeout = setTimeout(async () => {
           this.reconnectTimeout = null;
           this.reconnectAttempts++;
-          if (this.config.tokenProvider) {
-            try {
-              this.token = await this.config.tokenProvider();
-            } catch (error) {
-              console.error("MindCache Cloud: Failed to get token for reconnect:", error);
-              this.emit("error", error);
-              return;
-            }
-          }
           this.connect();
         }, delay);
       }
@@ -297,11 +326,16 @@ var init_CloudAdapter = __esm({
 
 // src/core/types.ts
 var DEFAULT_KEY_ATTRIBUTES = {
+  type: "text",
+  contentTags: [],
+  systemTags: ["prompt"],
+  // visible by default
+  zIndex: 0,
+  // Legacy - derived from systemTags
   readonly: false,
   visible: true,
   hardcoded: false,
   template: false,
-  type: "text",
   tags: []
 };
 
@@ -318,22 +352,42 @@ var MindCache = class {
   _isLoaded = true;
   // Default true for local mode
   _cloudConfig = null;
+  // Access level for system operations
+  _accessLevel = "user";
+  _initPromise = null;
   constructor(options) {
+    if (options?.accessLevel) {
+      this._accessLevel = options.accessLevel;
+    }
     if (options?.cloud) {
       this._cloudConfig = options.cloud;
       this._isLoaded = false;
       this._connectionState = "disconnected";
-      this._initCloud();
+      this._initPromise = this._initCloud();
     }
   }
+  /**
+   * Get the current access level
+   */
+  get accessLevel() {
+    return this._accessLevel;
+  }
+  /**
+   * Check if this instance has system-level access
+   */
+  get hasSystemAccess() {
+    return this._accessLevel === "system";
+  }
   async _initCloud() {
     if (!this._cloudConfig) {
       return;
     }
     try {
-      const { CloudAdapter: CloudAdapter2 } = await Promise.resolve().then(() => (init_CloudAdapter(), CloudAdapter_exports));
-      const configUrl = this._cloudConfig.baseUrl || "https://api.mindcache.io";
-      const baseUrl = configUrl.replace("https://", "wss://").replace("http://", "ws://");
+      const CloudAdapter2 = await this._getCloudAdapterClass();
+      if (!this._cloudConfig.baseUrl) {
+        throw new Error("MindCache Cloud: baseUrl is required. Please provide the cloud API URL in your configuration.");
+      }
+      const baseUrl = this._cloudConfig.baseUrl.replace("https://", "wss://").replace("http://", "ws://");
       const adapter = new CloudAdapter2({
         instanceId: this._cloudConfig.instanceId,
         projectId: this._cloudConfig.projectId || "default",
@@ -401,12 +455,46 @@ var MindCache = class {
   get isLoaded() {
     return this._isLoaded;
   }
+  /**
+   * Protected method to load CloudAdapter class.
+   * Can be overridden/mocked for testing.
+   */
+  async _getCloudAdapterClass() {
+    const { CloudAdapter: CloudAdapter2 } = await Promise.resolve().then(() => (init_CloudAdapter(), CloudAdapter_exports));
+    return CloudAdapter2;
+  }
   /**
    * Check if this instance is connected to cloud
    */
   get isCloud() {
     return this._cloudConfig !== null;
   }
+  /**
+   * Wait for initial sync to complete (or resolve immediately if already synced/local).
+   * Useful for scripts or linear execution flows.
+   */
+  async waitForSync() {
+    if (this._isLoaded) {
+      return;
+    }
+    if (this._initPromise) {
+      await this._initPromise;
+    }
+    if (this._isLoaded) {
+      return;
+    }
+    return new Promise((resolve) => {
+      if (!this._cloudAdapter) {
+        resolve();
+        return;
+      }
+      const handler = () => {
+        this._cloudAdapter?.off("synced", handler);
+        resolve();
+      };
+      this._cloudAdapter.on("synced", handler);
+    });
+  }
   /**
    * Disconnect from cloud (if connected)
    */
@@ -489,11 +577,16 @@ var MindCache = class {
   get_attributes(key) {
     if (key === "$date" || key === "$time") {
       return {
+        type: "text",
+        contentTags: [],
+        systemTags: ["prompt", "readonly", "protected"],
+        zIndex: 999999,
+        // System keys appear last
+        // Legacy attributes
         readonly: true,
         visible: true,
         hardcoded: true,
         template: false,
-        type: "text",
         tags: []
       };
     }
@@ -506,18 +599,98 @@ var MindCache = class {
       return;
     }
     const existingEntry = this.stm[key];
-    const baseAttributes = existingEntry ? existingEntry.attributes : { ...DEFAULT_KEY_ATTRIBUTES };
+    const wasHardcoded = existingEntry?.attributes.hardcoded || existingEntry?.attributes.systemTags?.includes("protected");
+    const baseAttributes = existingEntry ? {
+      ...existingEntry.attributes,
+      contentTags: [...existingEntry.attributes.contentTags || []],
+      systemTags: [...existingEntry.attributes.systemTags || []],
+      tags: [...existingEntry.attributes.tags || []],
+      zIndex: existingEntry.attributes.zIndex ?? 0
+    } : {
+      ...DEFAULT_KEY_ATTRIBUTES,
+      contentTags: [],
+      // Fresh array
+      systemTags: ["prompt"],
+      // Fresh array with default
+      tags: [],
+      // Fresh array
+      zIndex: 0
+    };
     const finalAttributes = attributes ? { ...baseAttributes, ...attributes } : baseAttributes;
-    if (finalAttributes.hardcoded) {
-      finalAttributes.readonly = true;
-      finalAttributes.template = false;
+    if (attributes) {
+      let systemTags2 = [...finalAttributes.systemTags || []];
+      if ("readonly" in attributes) {
+        if (attributes.readonly && !systemTags2.includes("readonly")) {
+          systemTags2.push("readonly");
+        } else if (!attributes.readonly && !wasHardcoded) {
+          systemTags2 = systemTags2.filter((t) => t !== "readonly");
+        }
+      }
+      if ("visible" in attributes) {
+        if (attributes.visible && !systemTags2.includes("prompt")) {
+          systemTags2.push("prompt");
+        } else if (!attributes.visible) {
+          systemTags2 = systemTags2.filter((t) => t !== "prompt");
+        }
+      }
+      if ("hardcoded" in attributes) {
+        if (attributes.hardcoded && !systemTags2.includes("protected")) {
+          systemTags2.push("protected");
+        } else if (!attributes.hardcoded && !wasHardcoded) {
+          systemTags2 = systemTags2.filter((t) => t !== "protected");
+        }
+        if (wasHardcoded && !systemTags2.includes("protected")) {
+          systemTags2.push("protected");
+        }
+      } else if (wasHardcoded) {
+        if (!systemTags2.includes("protected")) {
+          systemTags2.push("protected");
+        }
+      }
+      if ("template" in attributes) {
+        if (attributes.template && !wasHardcoded && !systemTags2.includes("template")) {
+          systemTags2.push("template");
+        } else if (!attributes.template || wasHardcoded) {
+          systemTags2 = systemTags2.filter((t) => t !== "template");
+        }
+      }
+      finalAttributes.systemTags = systemTags2;
+    } else if (wasHardcoded) {
+      let systemTags2 = [...finalAttributes.systemTags || []];
+      if (!systemTags2.includes("protected")) {
+        systemTags2.push("protected");
+      }
+      if (!systemTags2.includes("readonly")) {
+        systemTags2.push("readonly");
+      }
+      systemTags2 = systemTags2.filter((t) => t !== "template");
+      finalAttributes.systemTags = systemTags2;
     }
+    let systemTags = finalAttributes.systemTags || [];
+    if (wasHardcoded && !systemTags.includes("protected")) {
+      systemTags = [...systemTags, "protected"];
+    }
+    if (systemTags.includes("protected")) {
+      if (!systemTags.includes("readonly")) {
+        systemTags = [...systemTags, "readonly"];
+      }
+      systemTags = systemTags.filter((t) => t !== "template");
+      finalAttributes.systemTags = systemTags;
+    }
+    finalAttributes.readonly = systemTags.includes("readonly");
+    finalAttributes.visible = systemTags.includes("prompt");
+    finalAttributes.hardcoded = wasHardcoded || systemTags.includes("protected");
+    finalAttributes.template = systemTags.includes("template");
+    if (attributes && "tags" in attributes && attributes.tags) {
+      finalAttributes.contentTags = [...attributes.tags];
+    }
+    finalAttributes.tags = [...finalAttributes.contentTags || []];
     this.stm[key] = {
       value,
       attributes: finalAttributes
     };
     if (this.listeners[key]) {
-      this.listeners[key].forEach((listener) => listener());
+      this.listeners[key].forEach((listener) => listener(value));
     }
     this.notifyGlobalListeners();
   }
@@ -528,12 +701,38 @@ var MindCache = class {
       return;
     }
     this._isRemoteUpdate = true;
+    const systemTags = attributes.systemTags || [];
+    if (!attributes.systemTags) {
+      if (attributes.visible !== false) {
+        systemTags.push("prompt");
+      }
+      if (attributes.readonly) {
+        systemTags.push("readonly");
+      }
+      if (attributes.hardcoded) {
+        systemTags.push("protected");
+      }
+      if (attributes.template) {
+        systemTags.push("template");
+      }
+    }
+    const contentTags = attributes.contentTags || attributes.tags || [];
     this.stm[key] = {
       value,
-      attributes
+      attributes: {
+        ...attributes,
+        contentTags,
+        systemTags,
+        zIndex: attributes.zIndex ?? 0,
+        tags: contentTags,
+        readonly: systemTags.includes("readonly"),
+        visible: systemTags.includes("prompt"),
+        hardcoded: systemTags.includes("protected"),
+        template: systemTags.includes("template")
+      }
     };
     if (this.listeners[key]) {
-      this.listeners[key].forEach((listener) => listener());
+      this.listeners[key].forEach((listener) => listener(value));
     }
     this.notifyGlobalListeners();
     this._isRemoteUpdate = false;
@@ -551,7 +750,7 @@ var MindCache = class {
     if (key in this.stm) {
       delete this.stm[key];
       if (this.listeners[key]) {
-        this.listeners[key].forEach((listener) => listener());
+        this.listeners[key].forEach((listener) => listener(void 0));
       }
       this.notifyGlobalListeners();
     }
@@ -573,12 +772,62 @@ var MindCache = class {
     if (!entry) {
       return false;
     }
-    const { hardcoded: _hardcoded, ...allowedAttributes } = attributes;
+    const wasHardcoded = entry.attributes.hardcoded || entry.attributes.systemTags?.includes("protected");
+    const { hardcoded: _hardcoded, systemTags: _systemTags, ...allowedAttributes } = attributes;
+    if (wasHardcoded) {
+      if ("readonly" in allowedAttributes) {
+        delete allowedAttributes.readonly;
+      }
+      if ("template" in allowedAttributes) {
+        delete allowedAttributes.template;
+      }
+    }
     entry.attributes = { ...entry.attributes, ...allowedAttributes };
-    if (entry.attributes.hardcoded) {
+    if ("readonly" in attributes || "visible" in attributes || "template" in attributes) {
+      let newSystemTags = [];
+      if (entry.attributes.readonly) {
+        newSystemTags.push("readonly");
+      }
+      if (entry.attributes.visible) {
+        newSystemTags.push("prompt");
+      }
+      if (entry.attributes.template) {
+        newSystemTags.push("template");
+      }
+      if (wasHardcoded || entry.attributes.hardcoded) {
+        newSystemTags.push("protected");
+      }
+      if (newSystemTags.includes("protected")) {
+        if (!newSystemTags.includes("readonly")) {
+          newSystemTags.push("readonly");
+        }
+        newSystemTags = newSystemTags.filter((t) => t !== "template");
+        entry.attributes.readonly = true;
+        entry.attributes.template = false;
+      }
+      entry.attributes.systemTags = newSystemTags;
+    } else if (wasHardcoded) {
+      let systemTags = [...entry.attributes.systemTags || []];
+      if (!systemTags.includes("protected")) {
+        systemTags.push("protected");
+      }
+      if (!systemTags.includes("readonly")) {
+        systemTags.push("readonly");
+      }
+      systemTags = systemTags.filter((t) => t !== "template");
+      entry.attributes.systemTags = systemTags;
+    }
+    if (wasHardcoded) {
+      entry.attributes.hardcoded = true;
+      if (!entry.attributes.systemTags?.includes("protected")) {
+        entry.attributes.systemTags = [...entry.attributes.systemTags || [], "protected"];
+      }
       entry.attributes.readonly = true;
       entry.attributes.template = false;
     }
+    if ("contentTags" in attributes) {
+      entry.attributes.tags = [...entry.attributes.contentTags || []];
+    }
     this.notifyGlobalListeners();
     return true;
   }
@@ -650,7 +899,7 @@ var MindCache = class {
     if (deleted) {
       this.notifyGlobalListeners();
       if (this.listeners[key]) {
-        this.listeners[key].forEach((listener) => listener());
+        this.listeners[key].forEach((listener) => listener(void 0));
       }
     }
     return deleted;
@@ -659,12 +908,26 @@ var MindCache = class {
     this.stm = {};
     this.notifyGlobalListeners();
   }
+  /**
+   * Get keys sorted by zIndex (ascending), then by key name
+   */
+  getSortedKeys() {
+    return Object.entries(this.stm).sort(([keyA, entryA], [keyB, entryB]) => {
+      const zIndexA = entryA.attributes.zIndex ?? 0;
+      const zIndexB = entryB.attributes.zIndex ?? 0;
+      if (zIndexA !== zIndexB) {
+        return zIndexA - zIndexB;
+      }
+      return keyA.localeCompare(keyB);
+    }).map(([key]) => key);
+  }
   keys() {
-    return [...Object.keys(this.stm), "$date", "$time"];
+    return [...this.getSortedKeys(), "$date", "$time"];
   }
   values() {
     const now = /* @__PURE__ */ new Date();
-    const stmValues = Object.values(this.stm).map((entry) => entry.value);
+    const sortedKeys = this.getSortedKeys();
+    const stmValues = sortedKeys.map((key) => this.stm[key].value);
     return [
       ...stmValues,
       now.toISOString().split("T")[0],
@@ -673,8 +936,9 @@ var MindCache = class {
   }
   entries() {
     const now = /* @__PURE__ */ new Date();
-    const stmEntries = Object.entries(this.stm).map(
-      ([key, entry]) => [key, entry.value]
+    const sortedKeys = this.getSortedKeys();
+    const stmEntries = sortedKeys.map(
+      (key) => [key, this.stm[key].value]
     );
     return [
       ...stmEntries,
@@ -688,8 +952,9 @@ var MindCache = class {
   getAll() {
     const now = /* @__PURE__ */ new Date();
     const result = {};
-    Object.entries(this.stm).forEach(([key, entry]) => {
-      result[key] = entry.value;
+    const sortedKeys = this.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      result[key] = this.stm[key].value;
     });
     result["$date"] = now.toISOString().split("T")[0];
     result["$time"] = now.toTimeString().split(" ")[0];
@@ -703,7 +968,7 @@ var MindCache = class {
           attributes: { ...DEFAULT_KEY_ATTRIBUTES }
         };
         if (this.listeners[key]) {
-          this.listeners[key].forEach((listener) => listener());
+          this.listeners[key].forEach((listener) => listener(this.stm[key]?.value));
         }
       }
     });
@@ -772,7 +1037,9 @@ var MindCache = class {
   getSTM() {
     const now = /* @__PURE__ */ new Date();
     const entries = [];
-    Object.entries(this.stm).forEach(([key, entry]) => {
+    const sortedKeys = this.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      const entry = this.stm[key];
       if (entry.attributes.visible) {
         entries.push([key, this.get_value(key)]);
       }
@@ -787,7 +1054,9 @@ var MindCache = class {
   getSTMForAPI() {
     const now = /* @__PURE__ */ new Date();
     const apiData = [];
-    Object.entries(this.stm).forEach(([key, entry]) => {
+    const sortedKeys = this.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      const entry = this.stm[key];
       if (entry.attributes.visible) {
         const processedValue = entry.attributes.template ? this.get_value(key) : entry.value;
         apiData.push({
@@ -812,7 +1081,9 @@ var MindCache = class {
   }
   getVisibleImages() {
     const imageParts = [];
-    Object.entries(this.stm).forEach(([key, entry]) => {
+    const sortedKeys = this.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      const entry = this.stm[key];
       if (entry.attributes.visible && entry.attributes.type === "image" && entry.attributes.contentType) {
         const dataUrl = this.createDataUrl(entry.value, entry.attributes.contentType);
         imageParts.push({
@@ -838,7 +1109,9 @@ var MindCache = class {
   }
   serialize() {
     const result = {};
-    Object.entries(this.stm).forEach(([key, entry]) => {
+    const sortedKeys = this.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      const entry = this.stm[key];
       if (!entry.attributes.hardcoded) {
         result[key] = {
           value: entry.value,
@@ -853,11 +1126,40 @@ var MindCache = class {
       this.clear();
       Object.entries(data).forEach(([key, entry]) => {
         if (entry && typeof entry === "object" && "value" in entry && "attributes" in entry) {
+          const attrs = entry.attributes;
+          if (attrs.hardcoded === true || attrs.systemTags?.includes("protected")) {
+            return;
+          }
+          let systemTags = attrs.systemTags || [];
+          if (!attrs.systemTags) {
+            systemTags = [];
+            if (attrs.visible !== false) {
+              systemTags.push("prompt");
+            }
+            if (attrs.readonly) {
+              systemTags.push("readonly");
+            }
+            if (attrs.hardcoded) {
+              systemTags.push("protected");
+            }
+            if (attrs.template) {
+              systemTags.push("template");
+            }
+          }
+          const contentTags = attrs.contentTags || attrs.tags || [];
           this.stm[key] = {
             value: entry.value,
             attributes: {
-              ...entry.attributes,
-              tags: entry.attributes.tags || []
+              ...attrs,
+              contentTags,
+              systemTags,
+              zIndex: attrs.zIndex ?? 0,
+              // Sync legacy attributes
+              tags: contentTags,
+              readonly: systemTags.includes("readonly"),
+              visible: systemTags.includes("prompt"),
+              hardcoded: systemTags.includes("protected"),
+              template: systemTags.includes("template")
             }
           };
         }
@@ -868,7 +1170,9 @@ var MindCache = class {
   get_system_prompt() {
     const now = /* @__PURE__ */ new Date();
     const promptLines = [];
-    Object.entries(this.stm).forEach(([key, entry]) => {
+    const sortedKeys = this.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      const entry = this.stm[key];
       if (entry.attributes.visible) {
         if (entry.attributes.type === "image") {
           promptLines.push(`image ${key} available`);
@@ -903,14 +1207,18 @@ var MindCache = class {
       return void 0;
     }
     const sanitizedKey = toolName.replace("write_", "");
-    const allKeys = Object.keys(this.stm);
-    return allKeys.find(
+    const sortedKeys = this.getSortedKeys();
+    return sortedKeys.find(
       (k) => k.replace(/[^a-zA-Z0-9_-]/g, "_") === sanitizedKey
     );
   }
   get_aisdk_tools() {
     const tools = {};
-    const writableKeys = Object.entries(this.stm).filter(([, entry]) => !entry.attributes.readonly).map(([key]) => key);
+    const sortedKeys = this.getSortedKeys();
+    const writableKeys = sortedKeys.filter((key) => {
+      const entry = this.stm[key];
+      return !entry.attributes.readonly;
+    });
     writableKeys.forEach((key) => {
       const sanitizedKey = key.replace(/[^a-zA-Z0-9_-]/g, "_");
       const toolName = `write_${sanitizedKey}`;
@@ -994,6 +1302,12 @@ var MindCache = class {
       value
     };
   }
+  // ============================================
+  // Content Tag Methods (available to all access levels)
+  // ============================================
+  /**
+   * Add a content tag to a key (user-level organization)
+   */
   addTag(key, tag) {
     if (key === "$date" || key === "$time") {
       return false;
@@ -1002,64 +1316,231 @@ var MindCache = class {
     if (!entry) {
       return false;
     }
-    if (!entry.attributes.tags) {
-      entry.attributes.tags = [];
+    if (!entry.attributes.contentTags) {
+      entry.attributes.contentTags = [];
     }
-    if (!entry.attributes.tags.includes(tag)) {
-      entry.attributes.tags.push(tag);
+    if (!entry.attributes.contentTags.includes(tag)) {
+      entry.attributes.contentTags.push(tag);
+      entry.attributes.tags = [...entry.attributes.contentTags];
       this.notifyGlobalListeners();
       return true;
     }
     return false;
   }
+  /**
+   * Remove a content tag from a key
+   */
   removeTag(key, tag) {
     if (key === "$date" || key === "$time") {
       return false;
     }
     const entry = this.stm[key];
-    if (!entry || !entry.attributes.tags) {
+    if (!entry || !entry.attributes.contentTags) {
       return false;
     }
-    const tagIndex = entry.attributes.tags.indexOf(tag);
+    const tagIndex = entry.attributes.contentTags.indexOf(tag);
     if (tagIndex > -1) {
-      entry.attributes.tags.splice(tagIndex, 1);
+      entry.attributes.contentTags.splice(tagIndex, 1);
+      entry.attributes.tags = [...entry.attributes.contentTags];
       this.notifyGlobalListeners();
       return true;
     }
     return false;
   }
+  /**
+   * Get all content tags for a key
+   */
   getTags(key) {
     if (key === "$date" || key === "$time") {
       return [];
     }
     const entry = this.stm[key];
-    return entry?.attributes.tags || [];
+    return entry?.attributes.contentTags || [];
   }
+  /**
+   * Get all unique content tags across all keys
+   */
   getAllTags() {
     const allTags = /* @__PURE__ */ new Set();
     Object.values(this.stm).forEach((entry) => {
-      if (entry.attributes.tags) {
-        entry.attributes.tags.forEach((tag) => allTags.add(tag));
+      if (entry.attributes.contentTags) {
+        entry.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") {
       return false;
     }
     const entry = this.stm[key];
-    return entry?.attributes.tags?.includes(tag) || false;
+    return entry?.attributes.contentTags?.includes(tag) || false;
   }
+  /**
+   * Get all keys with a specific content tag as formatted string
+   */
   getTagged(tag) {
     const entries = [];
-    Object.entries(this.stm).forEach(([key, entry]) => {
-      if (entry.attributes.tags?.includes(tag)) {
+    const sortedKeys = this.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      const entry = this.stm[key];
+      if (entry.attributes.contentTags?.includes(tag)) {
         entries.push([key, this.get_value(key)]);
       }
     });
     return entries.map(([key, value]) => `${key}: ${value}`).join(", ");
   }
+  /**
+   * Get all keys with a specific content tag
+   */
+  getKeysByTag(tag) {
+    const sortedKeys = this.getSortedKeys();
+    return sortedKeys.filter((key) => {
+      const entry = this.stm[key];
+      return entry.attributes.contentTags?.includes(tag);
+    });
+  }
+  // ============================================
+  // System Tag Methods (requires system access level)
+  // ============================================
+  /**
+   * Add a system tag to a key (requires system access)
+   * System tags: 'prompt', 'readonly', 'protected', 'template'
+   */
+  systemAddTag(key, tag) {
+    if (!this.hasSystemAccess) {
+      console.warn("MindCache: systemAddTag requires system access level");
+      return false;
+    }
+    if (key === "$date" || key === "$time") {
+      return false;
+    }
+    const entry = this.stm[key];
+    if (!entry) {
+      return false;
+    }
+    if (!entry.attributes.systemTags) {
+      entry.attributes.systemTags = [];
+    }
+    if (!entry.attributes.systemTags.includes(tag)) {
+      entry.attributes.systemTags.push(tag);
+      this.syncLegacyFromSystemTags(entry);
+      this.notifyGlobalListeners();
+      return true;
+    }
+    return false;
+  }
+  /**
+   * 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") {
+      return false;
+    }
+    const entry = this.stm[key];
+    if (!entry || !entry.attributes.systemTags) {
+      return false;
+    }
+    const isHardcoded = entry.attributes.hardcoded || entry.attributes.systemTags.includes("protected");
+    if (tag === "protected" && isHardcoded) {
+      return false;
+    }
+    const tagIndex = entry.attributes.systemTags.indexOf(tag);
+    if (tagIndex > -1) {
+      entry.attributes.systemTags.splice(tagIndex, 1);
+      this.syncLegacyFromSystemTags(entry);
+      if (isHardcoded) {
+        if (!entry.attributes.systemTags.includes("protected")) {
+          entry.attributes.systemTags.push("protected");
+        }
+        entry.attributes.hardcoded = true;
+        entry.attributes.readonly = true;
+        entry.attributes.template = false;
+      }
+      this.notifyGlobalListeners();
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get all system tags for a key (requires system access)
+   */
+  systemGetTags(key) {
+    if (!this.hasSystemAccess) {
+      console.warn("MindCache: systemGetTags requires system access level");
+      return [];
+    }
+    if (key === "$date" || key === "$time") {
+      return [];
+    }
+    const entry = this.stm[key];
+    return entry?.attributes.systemTags || [];
+  }
+  /**
+   * Check if a key has a specific system tag (requires system access)
+   */
+  systemHasTag(key, tag) {
+    if (!this.hasSystemAccess) {
+      console.warn("MindCache: systemHasTag requires system access level");
+      return false;
+    }
+    if (key === "$date" || key === "$time") {
+      return false;
+    }
+    const entry = this.stm[key];
+    return entry?.attributes.systemTags?.includes(tag) || false;
+  }
+  /**
+   * Set all system tags for a key at once (requires system access)
+   */
+  systemSetTags(key, tags) {
+    if (!this.hasSystemAccess) {
+      console.warn("MindCache: systemSetTags requires system access level");
+      return false;
+    }
+    if (key === "$date" || key === "$time") {
+      return false;
+    }
+    const entry = this.stm[key];
+    if (!entry) {
+      return false;
+    }
+    entry.attributes.systemTags = [...tags];
+    this.syncLegacyFromSystemTags(entry);
+    this.notifyGlobalListeners();
+    return true;
+  }
+  /**
+   * Get all keys with a specific system tag (requires system access)
+   */
+  systemGetKeysByTag(tag) {
+    if (!this.hasSystemAccess) {
+      console.warn("MindCache: systemGetKeysByTag requires system access level");
+      return [];
+    }
+    const sortedKeys = this.getSortedKeys();
+    return sortedKeys.filter((key) => {
+      const entry = this.stm[key];
+      return entry.attributes.systemTags?.includes(tag);
+    });
+  }
+  /**
+   * Helper to sync legacy boolean attributes from system tags
+   */
+  syncLegacyFromSystemTags(entry) {
+    const tags = entry.attributes.systemTags || [];
+    entry.attributes.readonly = tags.includes("readonly");
+    entry.attributes.visible = tags.includes("prompt");
+    entry.attributes.hardcoded = tags.includes("protected");
+    entry.attributes.template = tags.includes("template");
+  }
   toMarkdown() {
     const now = /* @__PURE__ */ new Date();
     const lines = [];
@@ -1073,7 +1554,9 @@ var MindCache = class {
     lines.push("");
     lines.push("## STM Entries");
     lines.push("");
-    Object.entries(this.stm).forEach(([key, entry]) => {
+    const sortedKeys = this.getSortedKeys();
+    sortedKeys.forEach((key) => {
+      const entry = this.stm[key];
       if (entry.attributes.hardcoded) {
         return;
       }
@@ -1083,6 +1566,7 @@ var MindCache = class {
       lines.push(`- **Readonly**: \`${entry.attributes.readonly}\``);
       lines.push(`- **Visible**: \`${entry.attributes.visible}\``);
       lines.push(`- **Template**: \`${entry.attributes.template}\``);
+      lines.push(`- **Z-Index**: \`${entry.attributes.zIndex ?? 0}\``);
       if (entry.attributes.tags && entry.attributes.tags.length > 0) {
         lines.push(`- **Tags**: \`${entry.attributes.tags.join("`, `")}\``);
       }
@@ -1195,11 +1679,9 @@ var MindCache = class {
           currentEntry = {
             value: void 0,
             attributes: {
-              readonly: false,
-              visible: true,
-              hardcoded: false,
-              template: false,
-              type: "text",
+              ...DEFAULT_KEY_ATTRIBUTES,
+              contentTags: [],
+              systemTags: ["prompt"],
               tags: []
             }
           };
@@ -1223,6 +1705,14 @@ var MindCache = class {
           if (currentEntry) {
             currentEntry.attributes.template = value;
           }
+        } else if (trimmed.startsWith("- **Z-Index**: `")) {
+          const zIndexStr = trimmed.match(/`([^`]+)`/)?.[1];
+          if (currentEntry && zIndexStr) {
+            const zIndex = parseInt(zIndexStr, 10);
+            if (!isNaN(zIndex)) {
+              currentEntry.attributes.zIndex = zIndex;
+            }
+          }
         } else if (trimmed.startsWith("- **Tags**: `")) {
           const tagsStr = trimmed.substring(13, trimmed.length - 1);
           if (currentEntry) {
@@ -1279,9 +1769,35 @@ var MindCache = class {
         }
       }
       if (entry.value !== void 0 && entry.attributes) {
+        const attrs = entry.attributes;
+        if (attrs.tags && attrs.tags.length > 0 && (!attrs.contentTags || attrs.contentTags.length === 0)) {
+          attrs.contentTags = [...attrs.tags];
+        }
+        if (!attrs.systemTags || attrs.systemTags.length === 0) {
+          const systemTags = [];
+          if (attrs.visible !== false) {
+            systemTags.push("prompt");
+          }
+          if (attrs.readonly) {
+            systemTags.push("readonly");
+          }
+          if (attrs.hardcoded) {
+            systemTags.push("protected");
+          }
+          if (attrs.template) {
+            systemTags.push("template");
+          }
+          attrs.systemTags = systemTags;
+        }
+        if (!attrs.contentTags) {
+          attrs.contentTags = [];
+        }
+        if (!attrs.tags) {
+          attrs.tags = [...attrs.contentTags];
+        }
         this.stm[key] = {
           value: entry.value,
-          attributes: entry.attributes
+          attributes: attrs
         };
       }
     });