@mindstudio-ai/remy 0.1.252 → 0.1.254

package/dist/headless.js

@@ -914,6 +914,54 @@ ${loadPlanStatus(onboardingState)}
   return resolveIncludes(template);
 }
 
+// src/automatedActions/sentinel.ts
+function sentinel(name) {
+  return `@@automated::${name}@@`;
+}
+function automatedMessage(name, body) {
+  return body ? `${sentinel(name)}
+${body}` : sentinel(name);
+}
+function hasSentinel(text, name) {
+  return text.startsWith(sentinel(name));
+}
+function isAutomatedMessage(text) {
+  return text.startsWith("@@automated::");
+}
+function parseSentinel(text) {
+  const match = text.match(/^@@automated::(\w+)@@(.*)/s);
+  if (!match) {
+    return null;
+  }
+  return { name: match[1], remainder: match[2] };
+}
+function stripSentinelLine(text) {
+  return text.replace(/^@@automated::[^@]*@@[^\n]*\n?/, "");
+}
+function buildBackgroundResultsMessage(results) {
+  const xml = results.map(
+    (r) => `<tool_result id="${r.toolCallId}" name="${r.name}">
+${r.result}
+</tool_result>`
+  ).join("\n\n");
+  const plural = results.length > 1 ? "s" : "";
+  const body = `This is an automated message containing the result${plural} of ${results.length > 1 ? "tool calls" : "a tool call"} that ${results.length > 1 ? "have" : "has"} been working in the background. This is not a direct message from the user.
+<background_results>
+${xml}
+</background_results>`;
+  return automatedMessage("background_results", body);
+}
+function mergeBackgroundResultsMessages(messages) {
+  const results = [];
+  const toolRe = /<tool_result id="([^"]+)" name="([^"]+)">\n([\s\S]*?)\n<\/tool_result>/g;
+  for (const msg of messages) {
+    for (const m of msg.matchAll(toolRe)) {
+      results.push({ toolCallId: m[1], name: m[2], result: m[3] });
+    }
+  }
+  return buildBackgroundResultsMessage(results);
+}
+
 // src/tools/spec/readSpec.ts
 import fs5 from "fs/promises";
 
@@ -3187,54 +3235,6 @@ function startStatusWatcher(config) {
   };
 }
 
-// src/automatedActions/sentinel.ts
-function sentinel(name) {
-  return `@@automated::${name}@@`;
-}
-function automatedMessage(name, body) {
-  return body ? `${sentinel(name)}
-${body}` : sentinel(name);
-}
-function hasSentinel(text, name) {
-  return text.startsWith(sentinel(name));
-}
-function isAutomatedMessage(text) {
-  return text.startsWith("@@automated::");
-}
-function parseSentinel(text) {
-  const match = text.match(/^@@automated::(\w+)@@(.*)/s);
-  if (!match) {
-    return null;
-  }
-  return { name: match[1], remainder: match[2] };
-}
-function stripSentinelLine(text) {
-  return text.replace(/^@@automated::[^@]*@@[^\n]*\n?/, "");
-}
-function buildBackgroundResultsMessage(results) {
-  const xml = results.map(
-    (r) => `<tool_result id="${r.toolCallId}" name="${r.name}">
-${r.result}
-</tool_result>`
-  ).join("\n\n");
-  const plural = results.length > 1 ? "s" : "";
-  const body = `This is an automated message containing the result${plural} of ${results.length > 1 ? "tool calls" : "a tool call"} that ${results.length > 1 ? "have" : "has"} been working in the background. This is not a direct message from the user.
-<background_results>
-${xml}
-</background_results>`;
-  return automatedMessage("background_results", body);
-}
-function mergeBackgroundResultsMessages(messages) {
-  const results = [];
-  const toolRe = /<tool_result id="([^"]+)" name="([^"]+)">\n([\s\S]*?)\n<\/tool_result>/g;
-  for (const msg of messages) {
-    for (const m of msg.matchAll(toolRe)) {
-      results.push({ toolCallId: m[1], name: m[2], result: m[3] });
-    }
-  }
-  return buildBackgroundResultsMessage(results);
-}
-
 // src/subagents/common/cleanMessages.ts
 function findLastSummaryCheckpoint(messages, name) {
   for (let i = messages.length - 1; i >= 0; i--) {
@@ -3290,11 +3290,18 @@ function cleanMessagesForApi(messages) {
       (b) => b.type === "summary" && b.name === "conversation"
     );
     if (summaryBlock && summaryBlock.type === "summary") {
+      const recent = summaryBlock.recent ? `
+
+<recent_messages>
+The last few turns of the summarized conversation, quoted exactly as they were said.
+
+${summaryBlock.recent}
+</recent_messages>` : "";
       prefix.push({
         role: "user",
         content: `<conversation_summary>
 ${summaryBlock.text}
-</conversation_summary>`,
+</conversation_summary>${recent}`,
         hidden: true
       });
     }
@@ -6094,6 +6101,7 @@ var SUBAGENT_SUMMARY_PROMPT = readAsset("compaction", "subagent.md");
 var SUMMARIZABLE_SUBAGENTS = ["visualDesignExpert", "productVision"];
 async function compactConversation(messages, apiConfig, model) {
   const endIndex = findSafeInsertionPoint(messages);
+  const boundary = endIndex > 0 ? messages[endIndex - 1] : null;
   const summaries = [];
   const tasks = [];
   const conversationMessages = getConversationMessagesForSummary(
@@ -6150,6 +6158,7 @@ async function compactConversation(messages, apiConfig, model) {
       "Could not summarize the conversation \u2014 the model did not return a usable summary. History left intact."
     );
   }
+  const recent = collectRecentNarrative(conversationMessages);
   const checkpointMessages = summaries.map((s) => ({
     role: "user",
     hidden: true,
@@ -6158,12 +6167,16 @@ async function compactConversation(messages, apiConfig, model) {
         type: "summary",
         name: s.name,
         text: s.text,
+        ...s.name === "conversation" && recent ? { recent } : {},
         startedAt: Date.now()
       }
     ]
   }));
-  log8.info("Compaction complete", { summaries: summaries.length });
-  return checkpointMessages;
+  log8.info("Compaction complete", {
+    summaries: summaries.length,
+    recentNarrativeChars: recent.length
+  });
+  return { checkpoints: checkpointMessages, boundary };
 }
 function findSafeInsertionPoint(messages, fromIndex = messages.length) {
   let idx = fromIndex;
@@ -6239,6 +6252,58 @@ function getSubAgentMessagesForSummary(messages, subAgentName, endIndex) {
   }
   return collected;
 }
+var RECENT_NARRATIVE_REPLIES = 3;
+var RECENT_NARRATIVE_MAX_CHARS = 2e4;
+function narrativeText(msg) {
+  if (msg.role === "assistant") {
+    if (!Array.isArray(msg.content)) {
+      return null;
+    }
+    const blocks = msg.content;
+    if (blocks.some((b) => b.type === "tool")) {
+      return null;
+    }
+    const text = blocks.filter((b) => b.type === "text").map((b) => b.text).join("").trim();
+    return text || null;
+  }
+  if (msg.role !== "user" || msg.toolCallId || msg.hidden) {
+    return null;
+  }
+  if (typeof msg.content !== "string" || isAutomatedMessage(msg.content)) {
+    return null;
+  }
+  const body = msg.content.trim();
+  if (body) {
+    return body;
+  }
+  return msg.attachments?.find((a) => a.transcript)?.transcript?.trim() || null;
+}
+function collectRecentNarrative(messages) {
+  const quoted = [];
+  let replies = 0;
+  let chars = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    const text = narrativeText(msg);
+    if (!text) {
+      continue;
+    }
+    if (quoted.length > 0) {
+      if (replies >= RECENT_NARRATIVE_REPLIES) {
+        break;
+      }
+      if (chars + text.length > RECENT_NARRATIVE_MAX_CHARS) {
+        break;
+      }
+    }
+    quoted.push(`[${msg.role}]: ${text}`);
+    chars += text.length;
+    if (msg.role === "assistant") {
+      replies++;
+    }
+  }
+  return quoted.reverse().join("\n\n");
+}
 function serializeForSummary(messages) {
   const toolNameById = /* @__PURE__ */ new Map();
   for (const msg of messages) {
@@ -6763,15 +6828,26 @@ function clearSession(state) {
 
 // src/compaction/trigger.ts
 var log10 = createLogger("compaction:trigger");
-var pendingSummaries = [];
+var pending = null;
 var inflightCompaction = null;
 function applyPendingSummaries(state) {
-  const summaries = pendingSummaries.splice(0);
-  if (summaries.length === 0) {
+  const drained = pending;
+  pending = null;
+  if (!drained || drained.checkpoints.length === 0) {
     return;
   }
-  const idx = findSafeInsertionPoint(state.messages);
-  state.messages.splice(idx, 0, ...summaries);
+  let idx;
+  if (!drained.boundary) {
+    idx = 0;
+  } else {
+    const at = state.messages.indexOf(drained.boundary);
+    idx = at === -1 ? 0 : at + 1;
+  }
+  state.messages.splice(idx, 0, ...drained.checkpoints);
+  log10.info("Checkpoint applied", {
+    index: idx,
+    messageCount: state.messages.length
+  });
   saveSession(state);
 }
 var listener = null;
@@ -6782,14 +6858,18 @@ function triggerCompaction(state, apiConfig, opts = {}) {
   if (inflightCompaction) {
     return inflightCompaction;
   }
+  if (pending) {
+    log10.info("Compaction skipped \u2014 a checkpoint is already waiting to apply");
+    return Promise.resolve();
+  }
   const { blocking = false, requestId, model } = opts;
   listener?.({ type: "started", blocking, requestId });
   inflightCompaction = compactConversation(
     state.messages,
     apiConfig,
     resolveModel("conversationSummarizer", state.models, model)
-  ).then((summaries) => {
-    pendingSummaries.push(...summaries);
+  ).then((result) => {
+    pending = result;
     listener?.({ type: "complete", requestId });
     log10.info("Compaction complete");
   }).catch((err) => {
@@ -8963,9 +9043,9 @@ var HeadlessSession = class {
     if (this.currentAbort) {
       this.currentAbort.abort();
     }
-    for (const [id, pending] of this.pendingTools) {
-      clearTimeout(pending.timeout);
-      pending.resolve(USER_CANCELLED_RESULT);
+    for (const [id, pending2] of this.pendingTools) {
+      clearTimeout(pending2.timeout);
+      pending2.resolve(USER_CANCELLED_RESULT);
       this.pendingTools.delete(id);
     }
     return this.queue.removeWhere((item) => item.source !== "user");
@@ -9002,10 +9082,10 @@ var HeadlessSession = class {
     if (action === "tool_result" && parsed.id) {
       const id = parsed.id;
       const result = parsed.result ?? "";
-      const pending = this.pendingTools.get(id);
-      if (pending) {
+      const pending2 = this.pendingTools.get(id);
+      if (pending2) {
         this.pendingTools.delete(id);
-        pending.resolve(result);
+        pending2.resolve(result);
       } else if (!this.running) {
         log15.info("Late tool_result while idle, dismissing", { id });
         this.emit("completed", { success: true }, requestId);

package/dist/index.js

@@ -1599,9 +1599,63 @@ var init_assets = __esm({
   }
 });
 
+// src/automatedActions/sentinel.ts
+function sentinel(name) {
+  return `@@automated::${name}@@`;
+}
+function automatedMessage(name, body) {
+  return body ? `${sentinel(name)}
+${body}` : sentinel(name);
+}
+function hasSentinel(text, name) {
+  return text.startsWith(sentinel(name));
+}
+function isAutomatedMessage(text) {
+  return text.startsWith("@@automated::");
+}
+function parseSentinel(text) {
+  const match = text.match(/^@@automated::(\w+)@@(.*)/s);
+  if (!match) {
+    return null;
+  }
+  return { name: match[1], remainder: match[2] };
+}
+function stripSentinelLine(text) {
+  return text.replace(/^@@automated::[^@]*@@[^\n]*\n?/, "");
+}
+function buildBackgroundResultsMessage(results) {
+  const xml = results.map(
+    (r) => `<tool_result id="${r.toolCallId}" name="${r.name}">
+${r.result}
+</tool_result>`
+  ).join("\n\n");
+  const plural = results.length > 1 ? "s" : "";
+  const body = `This is an automated message containing the result${plural} of ${results.length > 1 ? "tool calls" : "a tool call"} that ${results.length > 1 ? "have" : "has"} been working in the background. This is not a direct message from the user.
+<background_results>
+${xml}
+</background_results>`;
+  return automatedMessage("background_results", body);
+}
+function mergeBackgroundResultsMessages(messages) {
+  const results = [];
+  const toolRe = /<tool_result id="([^"]+)" name="([^"]+)">\n([\s\S]*?)\n<\/tool_result>/g;
+  for (const msg of messages) {
+    for (const m of msg.matchAll(toolRe)) {
+      results.push({ toolCallId: m[1], name: m[2], result: m[3] });
+    }
+  }
+  return buildBackgroundResultsMessage(results);
+}
+var init_sentinel = __esm({
+  "src/automatedActions/sentinel.ts"() {
+    "use strict";
+  }
+});
+
 // src/compaction/index.ts
 async function compactConversation(messages, apiConfig, model) {
   const endIndex = findSafeInsertionPoint(messages);
+  const boundary = endIndex > 0 ? messages[endIndex - 1] : null;
   const summaries = [];
   const tasks = [];
   const conversationMessages = getConversationMessagesForSummary(
@@ -1658,6 +1712,7 @@ async function compactConversation(messages, apiConfig, model) {
       "Could not summarize the conversation \u2014 the model did not return a usable summary. History left intact."
     );
   }
+  const recent = collectRecentNarrative(conversationMessages);
   const checkpointMessages = summaries.map((s) => ({
     role: "user",
     hidden: true,
@@ -1666,12 +1721,16 @@ async function compactConversation(messages, apiConfig, model) {
         type: "summary",
         name: s.name,
         text: s.text,
+        ...s.name === "conversation" && recent ? { recent } : {},
         startedAt: Date.now()
       }
     ]
   }));
-  log2.info("Compaction complete", { summaries: summaries.length });
-  return checkpointMessages;
+  log2.info("Compaction complete", {
+    summaries: summaries.length,
+    recentNarrativeChars: recent.length
+  });
+  return { checkpoints: checkpointMessages, boundary };
 }
 function findSafeInsertionPoint(messages, fromIndex = messages.length) {
   let idx = fromIndex;
@@ -1747,6 +1806,56 @@ function getSubAgentMessagesForSummary(messages, subAgentName, endIndex) {
   }
   return collected;
 }
+function narrativeText(msg) {
+  if (msg.role === "assistant") {
+    if (!Array.isArray(msg.content)) {
+      return null;
+    }
+    const blocks = msg.content;
+    if (blocks.some((b) => b.type === "tool")) {
+      return null;
+    }
+    const text = blocks.filter((b) => b.type === "text").map((b) => b.text).join("").trim();
+    return text || null;
+  }
+  if (msg.role !== "user" || msg.toolCallId || msg.hidden) {
+    return null;
+  }
+  if (typeof msg.content !== "string" || isAutomatedMessage(msg.content)) {
+    return null;
+  }
+  const body = msg.content.trim();
+  if (body) {
+    return body;
+  }
+  return msg.attachments?.find((a) => a.transcript)?.transcript?.trim() || null;
+}
+function collectRecentNarrative(messages) {
+  const quoted = [];
+  let replies = 0;
+  let chars = 0;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    const text = narrativeText(msg);
+    if (!text) {
+      continue;
+    }
+    if (quoted.length > 0) {
+      if (replies >= RECENT_NARRATIVE_REPLIES) {
+        break;
+      }
+      if (chars + text.length > RECENT_NARRATIVE_MAX_CHARS) {
+        break;
+      }
+    }
+    quoted.push(`[${msg.role}]: ${text}`);
+    chars += text.length;
+    if (msg.role === "assistant") {
+      replies++;
+    }
+  }
+  return quoted.reverse().join("\n\n");
+}
 function serializeForSummary(messages) {
   const toolNameById = /* @__PURE__ */ new Map();
   for (const msg of messages) {
@@ -1930,12 +2039,13 @@ Write the summary of the conversation above, following your instructions.`;
   }
   return summaryText.trim();
 }
-var log2, CONVERSATION_SUMMARY_PROMPT, SUBAGENT_SUMMARY_PROMPT, SUMMARIZABLE_SUBAGENTS, CHUNK_CHAR_LIMIT, MIN_SUMMARY_CHARS;
+var log2, CONVERSATION_SUMMARY_PROMPT, SUBAGENT_SUMMARY_PROMPT, SUMMARIZABLE_SUBAGENTS, RECENT_NARRATIVE_REPLIES, RECENT_NARRATIVE_MAX_CHARS, CHUNK_CHAR_LIMIT, MIN_SUMMARY_CHARS;
 var init_compaction = __esm({
   "src/compaction/index.ts"() {
     "use strict";
     init_api();
     init_assets();
+    init_sentinel();
     init_tools8();
     init_logger();
     init_usageLedger();
@@ -1943,6 +2053,8 @@ var init_compaction = __esm({
     CONVERSATION_SUMMARY_PROMPT = readAsset("compaction", "conversation.md");
     SUBAGENT_SUMMARY_PROMPT = readAsset("compaction", "subagent.md");
     SUMMARIZABLE_SUBAGENTS = ["visualDesignExpert", "productVision"];
+    RECENT_NARRATIVE_REPLIES = 3;
+    RECENT_NARRATIVE_MAX_CHARS = 2e4;
     CHUNK_CHAR_LIMIT = 2e5;
     MIN_SUMMARY_CHARS = 400;
   }
@@ -2111,59 +2223,6 @@ var init_surfaces = __esm({
   }
 });
 
-// src/automatedActions/sentinel.ts
-function sentinel(name) {
-  return `@@automated::${name}@@`;
-}
-function automatedMessage(name, body) {
-  return body ? `${sentinel(name)}
-${body}` : sentinel(name);
-}
-function hasSentinel(text, name) {
-  return text.startsWith(sentinel(name));
-}
-function isAutomatedMessage(text) {
-  return text.startsWith("@@automated::");
-}
-function parseSentinel(text) {
-  const match = text.match(/^@@automated::(\w+)@@(.*)/s);
-  if (!match) {
-    return null;
-  }
-  return { name: match[1], remainder: match[2] };
-}
-function stripSentinelLine(text) {
-  return text.replace(/^@@automated::[^@]*@@[^\n]*\n?/, "");
-}
-function buildBackgroundResultsMessage(results) {
-  const xml = results.map(
-    (r) => `<tool_result id="${r.toolCallId}" name="${r.name}">
-${r.result}
-</tool_result>`
-  ).join("\n\n");
-  const plural = results.length > 1 ? "s" : "";
-  const body = `This is an automated message containing the result${plural} of ${results.length > 1 ? "tool calls" : "a tool call"} that ${results.length > 1 ? "have" : "has"} been working in the background. This is not a direct message from the user.
-<background_results>
-${xml}
-</background_results>`;
-  return automatedMessage("background_results", body);
-}
-function mergeBackgroundResultsMessages(messages) {
-  const results = [];
-  const toolRe = /<tool_result id="([^"]+)" name="([^"]+)">\n([\s\S]*?)\n<\/tool_result>/g;
-  for (const msg of messages) {
-    for (const m of msg.matchAll(toolRe)) {
-      results.push({ toolCallId: m[1], name: m[2], result: m[3] });
-    }
-  }
-  return buildBackgroundResultsMessage(results);
-}
-var init_sentinel = __esm({
-  "src/automatedActions/sentinel.ts"() {
-    "use strict";
-  }
-});
-
 // src/subagents/common/cleanMessages.ts
 function findLastSummaryCheckpoint(messages, name) {
   for (let i = messages.length - 1; i >= 0; i--) {
@@ -2219,11 +2278,18 @@ function cleanMessagesForApi(messages) {
       (b) => b.type === "summary" && b.name === "conversation"
     );
     if (summaryBlock && summaryBlock.type === "summary") {
+      const recent = summaryBlock.recent ? `
+
+<recent_messages>
+The last few turns of the summarized conversation, quoted exactly as they were said.
+
+${summaryBlock.recent}
+</recent_messages>` : "";
       prefix.push({
         role: "user",
         content: `<conversation_summary>
 ${summaryBlock.text}
-</conversation_summary>`,
+</conversation_summary>${recent}`,
         hidden: true
       });
     }
@@ -2662,12 +2728,23 @@ var init_session = __esm({
 
 // src/compaction/trigger.ts
 function applyPendingSummaries(state) {
-  const summaries = pendingSummaries.splice(0);
-  if (summaries.length === 0) {
+  const drained = pending;
+  pending = null;
+  if (!drained || drained.checkpoints.length === 0) {
     return;
   }
-  const idx = findSafeInsertionPoint(state.messages);
-  state.messages.splice(idx, 0, ...summaries);
+  let idx;
+  if (!drained.boundary) {
+    idx = 0;
+  } else {
+    const at = state.messages.indexOf(drained.boundary);
+    idx = at === -1 ? 0 : at + 1;
+  }
+  state.messages.splice(idx, 0, ...drained.checkpoints);
+  log4.info("Checkpoint applied", {
+    index: idx,
+    messageCount: state.messages.length
+  });
   saveSession(state);
 }
 function setCompactionListener(l) {
@@ -2677,14 +2754,18 @@ function triggerCompaction(state, apiConfig, opts = {}) {
   if (inflightCompaction) {
     return inflightCompaction;
   }
+  if (pending) {
+    log4.info("Compaction skipped \u2014 a checkpoint is already waiting to apply");
+    return Promise.resolve();
+  }
   const { blocking = false, requestId, model } = opts;
   listener?.({ type: "started", blocking, requestId });
   inflightCompaction = compactConversation(
     state.messages,
     apiConfig,
     resolveModel("conversationSummarizer", state.models, model)
-  ).then((summaries) => {
-    pendingSummaries.push(...summaries);
+  ).then((result) => {
+    pending = result;
     listener?.({ type: "complete", requestId });
     log4.info("Compaction complete");
   }).catch((err) => {
@@ -2697,7 +2778,7 @@ function triggerCompaction(state, apiConfig, opts = {}) {
   });
   return inflightCompaction;
 }
-var log4, pendingSummaries, inflightCompaction, listener;
+var log4, pending, inflightCompaction, listener;
 var init_trigger = __esm({
   "src/compaction/trigger.ts"() {
     "use strict";
@@ -2706,7 +2787,7 @@ var init_trigger = __esm({
     init_surfaces();
     init_session();
     log4 = createLogger("compaction:trigger");
-    pendingSummaries = [];
+    pending = null;
     inflightCompaction = null;
     listener = null;
   }
@@ -9861,9 +9942,9 @@ var init_headless = __esm({
         if (this.currentAbort) {
           this.currentAbort.abort();
         }
-        for (const [id, pending] of this.pendingTools) {
-          clearTimeout(pending.timeout);
-          pending.resolve(USER_CANCELLED_RESULT);
+        for (const [id, pending2] of this.pendingTools) {
+          clearTimeout(pending2.timeout);
+          pending2.resolve(USER_CANCELLED_RESULT);
           this.pendingTools.delete(id);
         }
         return this.queue.removeWhere((item) => item.source !== "user");
@@ -9900,10 +9981,10 @@ var init_headless = __esm({
         if (action === "tool_result" && parsed.id) {
           const id = parsed.id;
           const result = parsed.result ?? "";
-          const pending = this.pendingTools.get(id);
-          if (pending) {
+          const pending2 = this.pendingTools.get(id);
+          if (pending2) {
             this.pendingTools.delete(id);
-            pending.resolve(result);
+            pending2.resolve(result);
           } else if (!this.running) {
             log15.info("Late tool_result while idle, dismissing", { id });
             this.emit("completed", { success: true }, requestId);

package/dist/prompt/compiled/files.md

@@ -1,13 +1,31 @@
 # Files & Storage
 
-Per-app blob storage — the twin of `db` (`db` stores rows; `files` stores files: user uploads,
-generated documents, images, marketing assets). **Private by default.** Files serve on the app's own
-domain.
-
-**File stores are always live — there is no dev copy.** Every `put`/`delete`/overwrite hits
-production storage immediately and irreversibly. And unlike the database, **scenarios never reset file
-stores** — a scenario truncates DB tables but leaves files untouched, so files are not a "clean slate"
-you can re-seed, and orphaned files accumulate across runs. Delete deliberately.
+Per-app blob storage: user uploads, generated documents, images, marketing assets. **Think of a store
+as a CDN-backed bucket the app talks to — not app-defined state like the database.** You declare the
+store; what lands in it is arbitrary durable blobs the app doesn't model — no schema, nothing to
+migrate, no dev/prod sync. **Private by default**, served on the app's own domain. (The API is
+*shaped* like `db` — `defineStore` at module scope, import the handle, like `defineTable` — but the
+mental model is a bucket, not rows.)
+
+## How a store behaves (read before the API)
+
+- **One store, shared across dev and prod — on purpose.** There's no dev copy: a file you upload in
+  the dev editor (a marketing image, a corpus to vectorize) is *already there in prod* at the same
+  stable URL. That continuity is a feature — don't fork buckets per environment.
+- **Creates are safe by default**, because keys default to unique — `put()` mints a UUID (or a
+  content-addressed hash) when you don't pass one, so a dev write and a prod write land at different
+  keys and coexist. A collision only happens when you *choose* a fixed key.
+- **Care goes on the destructive / fixed-key operations**, not on writing in general: `delete(key)`
+  and overwriting a **stable key** (e.g. `config/latest.json`) reach the one live store, so a dev run
+  can clobber what prod serves. A `put()` with a default key can't. (There's intentionally no bulk
+  "clear the store".)
+- **Scenarios don't touch files — and that's correct.** A scenario truncates DB tables to seed test
+  *rows*; files are durable and left alone. A store isn't a "clean slate" you re-seed each run — upload
+  a test file once in dev and it stays. Accumulation is normal for an asset store; don't write
+  `clear()`-style reset helpers.
+- **Need dev and prod to *not* share** something (mutable fixed-key state, or sensitive uploads a
+  developer shouldn't see)? There's no per-store isolation switch — scope the key yourself (e.g.
+  `config/${env}/…`). Rare; the shared default is right almost always.
 
 ## Defining a store
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.252",
+  "version": "0.1.254",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",