@mindstudio-ai/remy 0.1.331 → 0.1.333

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}`);
@@ -4989,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
@@ -5041,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"
     ];
   }
@@ -5895,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
 
@@ -9436,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"
+    ]);
   }
 });
 
@@ -10112,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",
@@ -11311,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,
@@ -11319,7 +11383,8 @@ function writeStats(stats, queue, passiveResults, suggestCompactAt) {
         ...stats,
         suggestCompactAt,
         queue,
-        passiveResults
+        passiveResults,
+        workspaceNotice
       })
     );
   } catch {
@@ -11334,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(
@@ -11550,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";
@@ -11568,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;
@@ -11636,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();
@@ -11682,6 +11885,8 @@ var init_headless = __esm({
           }
         );
         this.passivePen = loadPassiveResults();
+        this.workspaceNotice = loadWorkspaceNotice();
+        void this.checkUpstream();
         this.persistStats();
         if (resumed) {
           this.emit("session_restored", {
@@ -11805,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");
@@ -11821,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
           });
@@ -11868,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)
       //////////////////////////////////////////////////////////////////////////////
@@ -11917,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,
@@ -11937,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,
@@ -12219,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;
         }
       }
@@ -12279,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;
         }
@@ -12287,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);
@@ -12299,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;
@@ -12307,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);
       }
       /**
@@ -12330,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)
           });
@@ -12478,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(
@@ -12530,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
           });
@@ -12542,7 +12795,7 @@ var init_headless = __esm({
               error: err.message
             });
           }
-          log17.warn("Command failed", {
+          log18.warn("Command failed", {
             action: "message",
             requestId,
             error: err.message
@@ -12849,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)
@@ -12858,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 ?? "";
@@ -12867,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);
@@ -12880,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/msfm.md

@@ -113,10 +113,12 @@ A spec starts with YAML frontmatter followed by freeform Markdown. There's no ma
 - `name` (required) — display name for the spec file
 - `description` (optional) — short summary of what this file covers
 - `type` (optional) — defaults to `spec`. Other values: `design/color` (color palette definition), `design/typography` (font and type style definition), `roadmap` (feature roadmap item). The frontend renders these types with specialized editors.
-- `status` (roadmap only) — `done`, `in-progress`, or `not-started`
-- `requires` (roadmap only) — array of slugs for prerequisite roadmap items. Empty array means available now.
+- `status` (roadmap only) — `done`, `in-progress`, or `not-started`. `in-progress` means being built right now, so it is transient: at most one item holds it, and it becomes `done` when the build lands. There is no `blocked` value — blocking is derived from `requires`, and authoring it separately creates a second source of truth that drifts.
+- `requires` (roadmap only) — inline array of **filenames** for prerequisite roadmap items, e.g. `["core-collections.md", "agent-chat.md"]`. Empty array means available now. Filenames, not slugs, so the entries match the names `index.json` uses.
 - `effort` (roadmap only) — `quick`, `small`, `medium`, or `large`
 
+**Don't quote frontmatter values** unless the value contains a `:` and would otherwise be ambiguous. Quotes are stripped when the file is read, so `name: Share & Export` and `name: "Share & Export"` are the same value — the unquoted form is what everything else uses.
+
 ```markdown
 ---
 name: Expense Tracker
@@ -210,6 +212,16 @@ Share haikus as styled image cards on social media or download as prints.
 The card system generates images using the brand's typography and color
 palette, creating shareable assets that feel native to the app's identity.
 
+## What it looks like
+
+- Card composer — pick a haiku, pick a frame
+- Share sheet — one tap to any social app
+- Print export — a high-resolution file for a real print
+
+## Key details
+
+Cards always carry the app's own type and color, never a generic template.
+
 ~~~
 Use generateImage to create styled cards. Card template
 applies brand typography and colors from the spec. Export as PNG via
@@ -217,10 +229,22 @@ CDN transform at 2x resolution. Social sharing via Web Share API with
 clipboard fallback for unsupported browsers.
 ~~~
 
+## Still to build
+
+A frame gallery — seasonal and custom frames — and scheduled sharing.
+
 ## History
 
-- **2026-03-22** — Built card generation using generateImage.
-  Added share button to haiku detail view.
+- **2026-03-22** — Built the composer, share sheet and print export.
+  Frame gallery and scheduling deferred.
 ```
 
-Unbuilt item — same shape with `status: not-started`, a body describing the intended feature, and no History section (History is appended when it's built).
+Unbuilt item — same shape with `status: not-started`, a body describing the intended feature, and no History or Still to build section (both are written when it's built).
+
+Three body sections on roadmap items are read by the frontend, so their shape matters:
+
+- **`## What it looks like`** — one bullet per user-visible surface the item delivers. The roadmap sizes an item from how many surfaces it has, so every item needs this section and every bullet should name one concrete surface.
+- **`## Still to build`** — a sentence or two naming what this item deliberately deferred. Only present when there is something. This is how a `done` item says it landed partially, so name real scope, not vague polish.
+- **`## History`** — one `- **YYYY-MM-DD** — …` entry per build, newest last. Keep entries to a sentence or two about what shipped and what was deferred; they are read in a sidebar, not as a changelog essay.
+
+Write all three as ordinary Markdown — plain `-` bullets and prose. Don't use task-list checkboxes (`- [x]`); the spec editor doesn't round-trip them, so they are erased the first time anyone edits the file.

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