@mindstudio-ai/remy 0.1.330 → 0.1.332

package/dist/index.js

@@ -172,6 +172,10 @@ var init_loopGuard = __esm({
 });
 
 // src/api.ts
+function sandboxSessionHeader() {
+  const sessionId = process.env.MINDSTUDIO_SESSION_ID;
+  return sessionId ? { "x-sandbox-session": sessionId } : {};
+}
 async function* streamChat(params) {
   const { baseUrl: baseUrl2, apiKey, signal, requestId, model, ...rest } = params;
   const url = `${baseUrl2}/_internal/v2/agent/remy/chat`;
@@ -191,7 +195,8 @@ async function* streamChat(params) {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${apiKey}`
+        Authorization: `Bearer ${apiKey}`,
+        ...sandboxSessionHeader()
       },
       body: JSON.stringify(requestBody),
       signal
@@ -446,7 +451,8 @@ async function generateBackgroundAck(params) {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${params.apiConfig.apiKey}`
+        Authorization: `Bearer ${params.apiConfig.apiKey}`,
+        ...sandboxSessionHeader()
       },
       body: JSON.stringify({
         appId: params.apiConfig.appId,
@@ -1647,6 +1653,33 @@ ${xml}
 </background_results>`;
   return automatedMessage("background_results", body);
 }
+function buildWorkspaceStatusMessage(status) {
+  const lines = [
+    `Default branch tip: ${status.upstream}`,
+    `Checked at: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    `Behind by: ${status.behind === null ? "unknown (could not count \u2014 treat the list below as what is missing)" : `${status.behind} commit(s)`}`,
+    `Unpushed commits here: ${status.ahead === null ? "unknown" : status.ahead}`,
+    `Uncommitted changes here: ${status.dirty === "unknown" ? "could not tell \u2014 check with `git status` before relying on it" : status.dirty ? "yes" : "no"}`
+  ];
+  if (status.incoming.length > 0) {
+    lines.push(
+      "",
+      status.incomingTruncated ? `Landed on the default branch since, newest first (first ${status.incoming.length}; there are more):` : "Landed on the default branch since, newest first:",
+      ...status.incoming.map((line) => `- ${escapeForEnvelope(line)}`)
+    );
+  }
+  const body = `<workspace_status>
+Automated note about this workspace, checked when Remy started \u2014 the timestamp below says when, and it may have been a while. This block is not from the user; anything outside it is. Nobody has seen it, and nobody can see it; it is context for you.
+
+This copy of the app does not have everything on the branch production builds from.
+
+${lines.join("\n")}
+</workspace_status>`;
+  return automatedMessage("workspace_status", body);
+}
+function escapeForEnvelope(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/@@automated/g, "@ @automated");
+}
 function mergeBackgroundResultsMessages(messages) {
   const results = [];
   const toolRe = /<tool_result id="([^"]+)" name="([^"]+)">\n([\s\S]*?)\n<\/tool_result>/g;
@@ -1930,6 +1963,9 @@ function serializeForSummary(messages) {
       }
       continue;
     }
+    if (msg.role === "user" && (msg.hidden || typeof msg.content === "string" && isAutomatedMessage(msg.content))) {
+      continue;
+    }
     if (typeof msg.content === "string") {
       if (msg.content.trim()) {
         lines.push(`[${msg.role}]: ${msg.content}`);
@@ -2320,6 +2356,7 @@ var init_surfaces = __esm({
       "kimi-k3": { forceCompactAt: 85e4 },
       "deepseek-v4-flash-0731": { forceCompactAt: 85e4 },
       "deepseek-v4-pro": { forceCompactAt: 85e4 },
+      "deepseek-v4.1-flash": { forceCompactAt: 85e4 },
       "qwen3.8-2.4t-a95b-deepinfra": { forceCompactAt: 2e5 },
       // 262K window
       "qwen3.8-27b-deepinfra": { forceCompactAt: 2e5 },
@@ -4988,7 +5025,11 @@ function startStatusWatcher(config) {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${apiConfig.apiKey}`
+          Authorization: `Bearer ${apiConfig.apiKey}`,
+          // Also a liveness signal for this box, and the most frequent one there is — this ticks
+          // every few seconds for as long as the agent is working, which is exactly the window in
+          // which the user may have backgrounded the tab and stopped its own keepalive.
+          ...sandboxSessionHeader()
         },
         body: JSON.stringify({ appId: apiConfig.appId, context }),
         signal
@@ -5040,11 +5081,13 @@ var INTERNAL_PAYLOAD_MARKERS;
 var init_statusWatcher = __esm({
   "src/statusWatcher.ts"() {
     "use strict";
+    init_api();
     INTERNAL_PAYLOAD_MARKERS = [
       "[USER CANCELLED]",
       "[INTERRUPTED]",
       "[INTERRUPTED - PARTIAL OUTPUT RETRIEVED]",
       "<background_results>",
+      "<workspace_status>",
       "<tool_result"
     ];
   }
@@ -5894,7 +5937,7 @@ TypeScript running in a sandboxed environment. Any npm package can be installed.
 - Managed SQLite database with typed schemas and automatic migrations. Define a TypeScript interface, push, and the platform handles diffing and migrating.
 - Built-in app-managed auth. Opt-in via manifest \u2014 developer builds login UI, platform handles verification codes (email-code, sms-code) and cookie sessions. API key auth for programmatic access. No OAuth, no social login (no Apple, Google, Facebook, or GitHub sign-in). Backend methods use auth.requireRole() for access control.
 - Encrypted secrets with separate dev/prod values, injected as process.env. For third-party service credentials not covered by the SDK.
-- Git-native deployment. Push to default branch to deploy.
+- Git-native deployment. Each person with edit access works in their own copy of the app, and everyone publishes to the same default branch, which is what deploys. Pushing any other branch builds a private preview instead. Rollback is a git revert.
 
 ## MindStudio SDK
 
@@ -9435,7 +9478,10 @@ var init_resolve = __esm({
     "use strict";
     init_assets();
     init_sentinel();
-    NON_ACTION_SENTINELS = /* @__PURE__ */ new Set(["background_results"]);
+    NON_ACTION_SENTINELS = /* @__PURE__ */ new Set([
+      "background_results",
+      "workspace_status"
+    ]);
   }
 });
 
@@ -10111,7 +10157,9 @@ async function runTurn(params) {
   for (const entry of keptEntries) {
     appendEntry(entry);
   }
-  const isFirstMessage = state.messages.filter((m) => m.role === "user").length === 1;
+  const isFirstMessage = state.messages.filter(
+    (m) => m.role === "user" && !m.hidden && !(typeof m.content === "string" && isAutomatedMessage(m.content))
+  ).length === 1;
   const STATUS_EXCLUDED_TOOLS = /* @__PURE__ */ new Set([
     "markBuildComplete",
     "setProjectMetadata",
@@ -11310,7 +11358,24 @@ function loadPassiveResults() {
   }
   return [];
 }
-function writeStats(stats, queue, passiveResults, suggestCompactAt) {
+function emptyWorkspaceNotice() {
+  return { pendingNote: null, lastNotedUpstream: null };
+}
+function loadWorkspaceNotice() {
+  try {
+    const stats = JSON.parse(readFileSync2(STATS_FILE, "utf-8"));
+    const notice = stats.workspaceNotice;
+    if (notice && typeof notice === "object") {
+      return {
+        pendingNote: typeof notice.pendingNote === "string" ? notice.pendingNote : null,
+        lastNotedUpstream: typeof notice.lastNotedUpstream === "string" ? notice.lastNotedUpstream : null
+      };
+    }
+  } catch {
+  }
+  return emptyWorkspaceNotice();
+}
+function writeStats(stats, queue, passiveResults, suggestCompactAt, workspaceNotice) {
   try {
     writeFileAtomicSync(
       STATS_FILE,
@@ -11318,7 +11383,8 @@ function writeStats(stats, queue, passiveResults, suggestCompactAt) {
         ...stats,
         suggestCompactAt,
         queue,
-        passiveResults
+        passiveResults,
+        workspaceNotice
       })
     );
   } catch {
@@ -11333,6 +11399,134 @@ var init_stats = __esm({
   }
 });
 
+// src/git/upstreamStatus.ts
+import { execFile as execFile2 } from "child_process";
+function git(args2, timeout = GIT_TIMEOUT_MS) {
+  return new Promise((resolve4) => {
+    const child = execFile2(
+      "git",
+      args2,
+      {
+        cwd: PROJECT_ROOT,
+        encoding: "utf-8",
+        timeout,
+        maxBuffer: MAX_BUFFER_BYTES,
+        // No controlling tty in a box, but an inherited one anywhere else would
+        // let a credential prompt hold the whole timeout open.
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        // execFile's `timeout` sends SIGTERM, which a wedged `git-remote-https`
+        // can ignore. Escalate so the boot path cannot be held by one.
+        killSignal: "SIGKILL"
+      },
+      (err, stdout, stderr) => {
+        resolve4({
+          ok: !err,
+          stdout: (stdout ?? "").trim(),
+          // Kept so a failure can say WHY. For a probe whose entire failure
+          // model is silence, this is the only line that makes it debuggable.
+          error: err ? (stderr || "").trim() || err.message : null
+        });
+      }
+    );
+    child.on("error", () => {
+    });
+  });
+}
+async function readUpstreamStatus() {
+  const inRepo = await git(["rev-parse", "--git-dir"]);
+  if (!inRepo.ok) {
+    return null;
+  }
+  const fetched = await git(
+    ["fetch", "origin", DEFAULT_BRANCH],
+    FETCH_TIMEOUT_MS
+  );
+  if (!fetched.ok) {
+    log17.info(
+      `fetch failed, falling back to the origin/${DEFAULT_BRANCH} on disk: ${fetched.error}`
+    );
+  }
+  const [upstreamRef, headRef] = await Promise.all([
+    git(["rev-parse", `origin/${DEFAULT_BRANCH}`]),
+    git(["rev-parse", "HEAD"])
+  ]);
+  if (!upstreamRef.ok || !headRef.ok) {
+    return null;
+  }
+  const upstream = upstreamRef.stdout;
+  if (upstream === headRef.stdout) {
+    return null;
+  }
+  const incomingResult = await git([
+    "log",
+    `--max-count=${MAX_INCOMING + 1}`,
+    "--format=%an: %s",
+    `HEAD..origin/${DEFAULT_BRANCH}`
+  ]);
+  const incomingLines = incomingResult.ok ? incomingResult.stdout.split("\n").filter((line) => line.length > 0) : [];
+  if (incomingResult.ok && incomingLines.length === 0) {
+    return null;
+  }
+  let behind = null;
+  let ahead = null;
+  const counts = await git([
+    "rev-list",
+    "--left-right",
+    "--count",
+    `origin/${DEFAULT_BRANCH}...HEAD`
+  ]);
+  if (counts.ok) {
+    const [left, right] = counts.stdout.split(/\s+/);
+    behind = Number(left);
+    ahead = Number(right);
+    if (!Number.isFinite(behind) || behind <= 0) {
+      return null;
+    }
+    if (!Number.isFinite(ahead)) {
+      ahead = null;
+    }
+  } else if (!incomingResult.ok) {
+    const contained = await git([
+      "merge-base",
+      "--is-ancestor",
+      `origin/${DEFAULT_BRANCH}`,
+      "HEAD"
+    ]);
+    if (contained.ok) {
+      return null;
+    }
+    log17.info(
+      `behind by an unknown amount: rev-list and log both failed (${counts.error})`
+    );
+  }
+  const status = await git(["status", "--porcelain"]);
+  if (!status.ok) {
+    log17.info(`could not read the working tree state: ${status.error}`);
+  }
+  return {
+    upstream,
+    behind,
+    ahead,
+    dirty: status.ok ? status.stdout.length > 0 : "unknown",
+    incoming: incomingLines.slice(0, MAX_INCOMING),
+    incomingTruncated: incomingLines.length > MAX_INCOMING
+  };
+}
+var log17, DEFAULT_BRANCH, MAX_INCOMING, FETCH_TIMEOUT_MS, GIT_TIMEOUT_MS, MAX_BUFFER_BYTES;
+var init_upstreamStatus = __esm({
+  "src/git/upstreamStatus.ts"() {
+    "use strict";
+    init_projectRoot();
+    init_logger();
+    log17 = createLogger("upstream");
+    DEFAULT_BRANCH = "main";
+    MAX_INCOMING = 20;
+    FETCH_TIMEOUT_MS = 3e4;
+    GIT_TIMEOUT_MS = 1e4;
+    MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+  }
+});
+
 // src/headless/messageQueue.ts
 function holdRestoredUserItems(items) {
   return items.map(
@@ -11549,7 +11743,7 @@ var headless_exports = {};
 __export(headless_exports, {
   HeadlessSession: () => HeadlessSession
 });
-var log17, EXTERNAL_TOOL_TIMEOUT_MS, LONG_RUNNING_TOOLS, LONG_RUNNING_TOOL_TIMEOUT_MS, USER_FACING_TOOLS, HeadlessSession;
+var log18, EXTERNAL_TOOL_TIMEOUT_MS, LONG_RUNNING_TOOLS, LONG_RUNNING_TOOL_TIMEOUT_MS, USER_FACING_TOOLS, HeadlessSession;
 var init_headless = __esm({
   "src/headless/index.ts"() {
     "use strict";
@@ -11567,11 +11761,12 @@ var init_headless = __esm({
     init_attachments();
     init_planFile();
     init_stats();
+    init_upstreamStatus();
     init_tools10();
     init_messageQueue();
     init_resolve();
     init_sentinel();
-    log17 = createLogger("headless");
+    log18 = createLogger("headless");
     EXTERNAL_TOOL_TIMEOUT_MS = 3e5;
     LONG_RUNNING_TOOLS = /* @__PURE__ */ new Set(["runMethod", "testJewel"]);
     LONG_RUNNING_TOOL_TIMEOUT_MS = 18e5;
@@ -11635,6 +11830,15 @@ var init_headless = __esm({
        * Persisted to .remy-stats.json alongside the queue.
        */
       passivePen = [];
+      /**
+       * The workspace-behind note, and the upstream tip it was raised for.
+       *
+       * Rides the same sweep as the passive pen and for the same reason: a
+       * workspace that is behind is worth knowing about before the next piece of
+       * work, and worth nothing at all if nobody is working — so it must never
+       * initiate a turn of its own.
+       */
+      workspaceNotice = emptyWorkspaceNotice();
       // External tool bridge
       pendingTools = /* @__PURE__ */ new Map();
       earlyResults = /* @__PURE__ */ new Map();
@@ -11681,6 +11885,8 @@ var init_headless = __esm({
           }
         );
         this.passivePen = loadPassiveResults();
+        this.workspaceNotice = loadWorkspaceNotice();
+        void this.checkUpstream();
         this.persistStats();
         if (resumed) {
           this.emit("session_restored", {
@@ -11804,7 +12010,7 @@ var init_headless = __esm({
         try {
           this.handleCancel("shutdown");
         } catch (err) {
-          log17.warn("Shutdown cancel failed", { error: err?.message });
+          log18.warn("Shutdown cancel failed", { error: err?.message });
         }
         this.emit("stopping");
         this.emit("stopped");
@@ -11820,7 +12026,7 @@ var init_headless = __esm({
         }
         const line = JSON.stringify(payload) + "\n";
         if (event === "history") {
-          log17.info("Wrote history event to stdout", {
+          log18.info("Wrote history event to stdout", {
             requestId,
             bytes: line.length
           });
@@ -11867,9 +12073,45 @@ var init_headless = __esm({
           this.sessionStats,
           this.queue.snapshot(),
           this.passivePen,
-          suggestCompactAt
+          suggestCompactAt,
+          this.workspaceNotice
         );
       }
+      /**
+       * Park a note if this workspace is missing work that is already in production.
+       *
+       * Once per upstream tip rather than once per boot. Remy restarts for reasons
+       * that have nothing to do with the repo — a pod recycle, a crash, a new
+       * session — and re-raising the same note on each of those turns a useful
+       * signal into nagging. A colleague publishing again moves the tip, which
+       * re-arms it; bringing the workspace current means there is nothing to raise.
+       *
+       * Never throws: this is called unawaited from the boot path, so an unhandled
+       * rejection here would be a crash at the least recoverable moment.
+       */
+      async checkUpstream() {
+        try {
+          const status = await readUpstreamStatus();
+          if (!status || status.upstream === this.workspaceNotice.lastNotedUpstream) {
+            return;
+          }
+          this.workspaceNotice = {
+            pendingNote: buildWorkspaceStatusMessage(status),
+            lastNotedUpstream: status.upstream
+          };
+          this.persistStats();
+          log18.info("workspace behind upstream; note parked for the next turn", {
+            // The upstream sha is the dedupe key, so it is what makes "why did I
+            // not get a note" answerable from the log alone.
+            upstream: status.upstream,
+            behind: status.behind,
+            ahead: status.ahead,
+            dirty: status.dirty
+          });
+        } catch (err) {
+          log18.info(`upstream check failed: ${String(err)}`);
+        }
+      }
       //////////////////////////////////////////////////////////////////////////////
       // Background completions (tool-block mutation; message delivery via queue)
       //////////////////////////////////////////////////////////////////////////////
@@ -11916,7 +12158,7 @@ var init_headless = __esm({
         if (this.sessionStats.lastContextSize <= threshold) {
           return;
         }
-        log17.info("Forced compaction gate triggered", {
+        log18.info("Forced compaction gate triggered", {
           contextSize: this.sessionStats.lastContextSize,
           threshold,
           model: parentModel,
@@ -11936,7 +12178,7 @@ var init_headless = __esm({
       onBackgroundComplete = (toolCallId, name, result, subAgentMessages) => {
         const notify = getToolByName(name)?.backgroundNotify ?? "wake";
         this.pendingBlockUpdates.push({ toolCallId, result, subAgentMessages });
-        log17.info("Background complete", {
+        log18.info("Background complete", {
           toolCallId,
           name,
           notify,
@@ -12218,7 +12460,7 @@ var init_headless = __esm({
           const { documents, images } = await persistAttachments(attachments);
           return buildUploadHeader(documents, images) || void 0;
         } catch (err) {
-          log17.warn("Attachment persistence failed", { error: err.message });
+          log18.warn("Attachment persistence failed", { error: err.message });
           return void 0;
         }
       }
@@ -12278,7 +12520,7 @@ var init_headless = __esm({
         }
         if (batch.length === 0) {
           if (landings > 0) {
-            log17.info("promptUser store landings passed through", { landings });
+            log18.info("promptUser store landings passed through", { landings });
           }
           return raw;
         }
@@ -12286,7 +12528,7 @@ var init_headless = __esm({
         try {
           results = await persistAttachmentList(batch);
         } catch (err) {
-          log17.warn("promptUser upload persistence failed", {
+          log18.warn("promptUser upload persistence failed", {
             error: err.message
           });
           results = batch.map(() => null);
@@ -12298,7 +12540,7 @@ var init_headless = __esm({
               return r.localPath;
             }
             const att = batch[cursor + i];
-            log17.warn("promptUser upload not persisted; falling back to url", {
+            log18.warn("promptUser upload not persisted; falling back to url", {
               filename: att.filename
             });
             return att.url;
@@ -12306,7 +12548,7 @@ var init_headless = __esm({
           cursor += slot.count;
           answers[slot.id] = slot.isArray ? paths : paths[0];
         }
-        log17.info("promptUser uploads persisted", { count: batch.length });
+        log18.info("promptUser uploads persisted", { count: batch.length });
         return JSON.stringify(answers);
       }
       /**
@@ -12329,7 +12571,7 @@ var init_headless = __esm({
       async runSingleTurn(parsed, requestId, fromChain = false, queued = false) {
         const attachments = parsed.attachments;
         if (attachments?.length) {
-          log17.info("Message has attachments", {
+          log18.info("Message has attachments", {
             count: attachments.length,
             urls: attachments.map((a) => a.url)
           });
@@ -12477,6 +12719,18 @@ var init_headless = __esm({
             hidden: true
           });
         }
+        const hasUserWords = entries.some(
+          (entry) => !entry.hidden && !isAutomatedMessage(entry.text)
+        );
+        if (this.workspaceNotice.pendingNote && hasUserWords) {
+          const note = this.workspaceNotice.pendingNote;
+          this.workspaceNotice = {
+            ...this.workspaceNotice,
+            pendingNote: null
+          };
+          this.persistStats();
+          entries.unshift({ text: note, hidden: true });
+        }
         const consumedRids = [];
         const takeSteering = async () => {
           const items = this.queue.removeWhere(
@@ -12529,7 +12783,7 @@ var init_headless = __esm({
               error: "Turn ended unexpectedly"
             });
           }
-          log17.info("Turn complete", {
+          log18.info("Turn complete", {
             requestId,
             durationMs: Date.now() - this.turnStart
           });
@@ -12541,7 +12795,7 @@ var init_headless = __esm({
               error: err.message
             });
           }
-          log17.warn("Command failed", {
+          log18.warn("Command failed", {
             action: "message",
             requestId,
             error: err.message
@@ -12848,7 +13102,7 @@ var init_headless = __esm({
         try {
           parsed = JSON.parse(line);
         } catch (err) {
-          log17.warn("Invalid JSON on stdin", {
+          log18.warn("Invalid JSON on stdin", {
             error: err.message,
             lineLength: line.length,
             preview: line.slice(0, 200)
@@ -12857,7 +13111,7 @@ var init_headless = __esm({
           return;
         }
         const { action, requestId } = parsed;
-        log17.info("Command received", { action, requestId });
+        log18.info("Command received", { action, requestId });
         if (action === "tool_result" && parsed.id) {
           const id = parsed.id;
           const result = parsed.result ?? "";
@@ -12866,7 +13120,7 @@ var init_headless = __esm({
             this.pendingTools.delete(id);
             pending2.resolve(result);
           } else if (!this.running) {
-            log17.info("Late tool_result while idle, dismissing", { id });
+            log18.info("Late tool_result while idle, dismissing", { id });
             this.emit("completed", { success: true }, requestId);
           } else {
             this.earlyResults.set(id, result);
@@ -12879,7 +13133,7 @@ var init_headless = __esm({
             ...typeof parsed.before === "number" ? { before: parsed.before } : {},
             ...typeof parsed.limit === "number" ? { limit: parsed.limit } : {}
           });
-          log17.info("History response", {
+          log18.info("History response", {
             requestId,
             startIndex: page.startIndex,
             endIndex: page.endIndex,

package/dist/prompt/compiled/dev-and-deploy.md

@@ -25,8 +25,17 @@ The dev database is disposable. Experiment freely — there's no risk of breakin
 
 `console.log`, `console.warn`, and `console.error` in methods are captured and displayed in the terminal. They don't affect the method's return value. Every method execution is logged with full input, output, duration, and error info.
 
+## Working Alongside Other People
+
+Most apps are single-owner, but sometimes an app can have several people with edit access, and each of them gets their own workspace: a separate copy of the code, its own dev database, its own conversation with you. Nothing one person does is visible to anyone else until it's pushed, and you can't see into the other workspaces. Everyone's copy tracks the same branch - the one production builds from - and publishing is what advances it. If this copy is missing work the default branch already has, it's likely someone else published while this copy was idle
+
+Whenever any of this reaches the user, talk about the work and the people, not the plumbing. What someone shipped and what it means for what they're about to do is useful. Commit counts, branch names, and phrases like "clean tree" or "fast-forward" are not — almost nobody holds an accurate model of git, including people who use it daily, and reciting repository state at someone is not the same as telling them what happened.
+
 ## What Happens on Deploy
 
+Publishing pushes `main` — the `publishing` skill has the flow. This section is what the platform
+does once that branch moves:
+
 ```bash
 git push origin main
 ```

package/dist/prompt/compiled/platform.md

@@ -92,7 +92,7 @@ const { vendor } = await api.approveVendor({ vendorId: '...' });
 - **Built-in auth.** Opt-in via manifest. Developer builds login UI, platform handles verification codes (email/SMS), cookie sessions, and role enforcement. Backend methods use `auth.requireRole('admin')` for access control.
 - **Multiple interfaces, one codebase.** Web, API, Cron, Webhook, Email, MCP, Agent, Voice — all invoke the same methods. Methods don't know which interface called them.
 - **Sandboxed execution.** Each method invocation runs in its own isolated execution context with npm packages pre-installed.
-- **Git-native deployment.** Push to default branch to deploy. Push to feature branch for preview. Rollback is a git revert.
+- **Git-native deployment.** Push to default branch to deploy. Push to feature branch for preview. Rollback is a git revert. Each person with edit access works in their own copy of the app, and everyone publishes to the same default branch.
 - **Secrets.** Encrypted environment variables with separate dev/prod values. Injected as `process.env` in methods. For third-party service credentials not covered by the SDK.
 
 ## Minimum Viable App

package/dist/prompt/skills/dataSources.md

@@ -82,6 +82,15 @@ People are bad at describing their own data, and the more of it they have the wo
 
 Three rules hold throughout: credentials are app secrets referred to by NAME and never appear in chat or code; nothing that spends is approved or provisioned without the user's explicit yes on the numbers; and dedicated capacity is proposed when a plan asks for it, not before.
 
+### Building an initial app (intake) when a user brings a data source
+
+When a user shows up with a data source from the first message, prefer the following workflow:
+- Get a feel for the data, using the methods discussed above
+- Then, and perhaps most importantly, understand what it is the user is trying to *do* with the data. Are they building a generic RAG chatbot, or something more interesting? What is important to them - grounding, citations, etc? And why?
+- Vectorized data that does nothing isn't very useful - building the app that will consume it to do something compelling is the important bit.
+- If the data smells truly large (e.g., will require async work, meaningful cost to ingest, or dedicated capacity/planning, etc), focus on putting a small sample of the data in a data source and then focus on building and delivering the MVP.
+- After the MVP is built and the user feels good about it, you can help the user bring in the full data source.
+
 ## Loading documents — normally at build time, from the CLI
 
 ```bash
@@ -124,7 +133,7 @@ remy-admin datasources jobs approve <id> --wait
 remy-admin datasources jobs start --source archive --manifest urls.jsonl --limit 200 --approve --wait   # a cheap sample first
 ```
 
-Two gates decide whether a plan can run: the corpus has to fit the source's placement (a shared-pool source over the per-source cap answers `plan_requires_dedicated`; see Dedicated capacity below), and the workspace has to be able to cover the projection (`insufficient_credits`). **Show the user the plan and get an explicit yes before approving** — the plan is the whole point. `--budget <dollars>` pauses the job at a ceiling; `--limit <n>` loads a sample of the corpus to check quality before committing to all of it. Unchanged documents are skipped by content hash, so re-running a job is free. `jobs pause|resume|cancel` are the controls; search works on the partial corpus throughout. One bulk operation per source at a time (`data_source_busy`).
+Two gates decide whether a plan can run: the corpus has to fit the source's placement (a shared-pool source over the per-source cap answers `plan_requires_dedicated`; see Dedicated capacity below), and the workspace has to be able to cover the projection (`insufficient_credits`). **Show the user the plan and get an explicit yes before approving** — the plan is the whole point. `--budget <dollars>` pauses the job at a ceiling; `--limit <n>` loads a sample of the corpus to check quality before committing to all of it. Unchanged documents are skipped by content hash, so re-running a job is free. `jobs pause|resume|cancel` are the controls; search works on the partial corpus throughout. A batch that fails five times stays failed and the job finishes without it; once the cause is fixed, `jobs retry <id>` runs just those batches again and finishes the job. One bulk operation per source at a time (`data_source_busy`); documents stranded by failed batches do not block a move, and `jobs retry` builds them onto wherever the source lives now.
 
 ## Keeping a corpus in sync with an S3 bucket (connectors)
 
@@ -210,7 +219,7 @@ remy-admin datasources remap --source archive --wait
 
 On a job, mapping is its own stage. The mapper turns each object into documents; the platform then ingests those documents in parallel batches of fifty across its workers, whatever one object became. So the size of an object does not set the pace, and a bundle of a thousand records is fine; only the number of objects sets how wide the mapping stage itself runs (three huge files map on three workers, the plan says so as a warning). `jobs status` reads "mapping N of M objects" until that stage is through, then counts documents.
 
-A mapper runs on the platform, so the platform has to build it. Any push builds it, and a branch push is a private preview build, which is all a mapper needs. `map deploy` then makes that build's mapper the source's active one: jobs, syncs and `add()` run it from then on, whether or not the app has ever been published. Publishing activates the mapper the live release declares — which is the one you deployed, since publishing fast-forwards the default branch to your branch. So there is nothing extra to do at publish time, and nothing to merge by hand: publishing is the merge (see the publishing skill). `jobs start` refuses with `mapper_not_deployed` while the dev session declares a mapper that is not yet active, because the job would otherwise load the raw records as documents.
+A mapper runs on the platform, so the platform has to build it. Any push builds it, and a branch push is a private preview build, which is all a mapper needs. `map deploy` then makes that build's mapper the source's active one: jobs, syncs and `add()` run it from then on, whether or not the app has ever been published. Publishing activates the mapper the *live release* declares — so if you deployed a mapper from a branch build, that code still has to reach `main` for the next release to declare it. Getting it there is the publish flow's job, not a separate step you invent (see the publishing skill). `jobs start` refuses with `mapper_not_deployed` while the dev session declares a mapper that is not yet active, because the job would otherwise load the raw records as documents.
 
 `map test --dev` needs the dev session running (`npx mindstudio dev`); it runs the mapper from local source through the tunnel and prints every outcome with markdown previews. The plan of a mapped job records the mapper's outcome mix on its sample; a run whose skip share climbs past twice that pauses with `pauseReason: 'skips'` for a look at the quarantine. `remap` reads the platform's own raw copies — no origin traffic — skips unchanged markdown by hash, and supersedes changed documents, so a metadata tweak on a million-document source costs frames and little else. `externalId` is the identity everything replaces by; choose it deliberately (the record's stable id, never the key of a file that gets rewritten in place).