@mindstudio-ai/remy 0.1.0 → 0.1.2

package/README.md

@@ -43,19 +43,19 @@ Remy saves conversation history to `.remy-session.json` in the working directory
 
 ## Tools
 
-Remy's tool set depends on the project state. The sandbox tells remy whether the project has generated code in `dist/` via the `projectHasCode` field on messages.
+Tool availability depends on the project's onboarding state, sent by the sandbox on each message.
 
 ### Always Available
 
 | Tool | Description |
 |------|-------------|
-| `setViewMode` | Switch the IDE view (intake, preview, spec, code, databases, scenarios, logs) |
+| `setProjectOnboardingState` | Advance the onboarding flow (intake → initialSpecAuthoring → initialCodegen → onboardingFinished) |
 | `promptUser` | Ask the user structured questions (form or inline display) |
-| `clearSyncStatus` | Clear sync flags after syncing spec and code |
+| `confirmDestructiveAction` | Confirm a destructive or irreversible action with the user |
 
 ### Spec Tools
 
-Available in all sessions. Used for authoring and editing MSFM specs in `src/`.
+Available in all onboarding states. Used for authoring and editing MSFM specs in `src/`.
 
 | Tool | Description |
 |------|-------------|
@@ -66,7 +66,7 @@ Available in all sessions. Used for authoring and editing MSFM specs in `src/`.
 
 ### Code Tools
 
-Available when the project has generated code (`projectHasCode: true`).
+Available from `initialCodegen` onward.
 
 | Tool | Description |
 |------|-------------|
@@ -78,6 +78,7 @@ Available when the project has generated code (`projectHasCode: true`).
 | `glob` | Find files by pattern |
 | `listDir` | List directory contents |
 | `editsFinished` | Signal that file edits are complete for live preview |
+| `askMindStudioSdk` | Ask the MindStudio SDK assistant about actions, models, connectors, and integrations |
 
 ### LSP Tools (sandbox only)
 
@@ -88,19 +89,22 @@ Available when `--lsp-url` is passed.
 | `lspDiagnostics` | Type errors and warnings for a file, with suggested quick fixes |
 | `restartProcess` | Restart a managed sandbox process (e.g., dev server after npm install) |
 
-### Sync Tools (sync turns only)
+### Post-Onboarding Tools
 
-Available when the sandbox sends a `runCommand: "sync"` message.
+Available only when `onboardingState` is `onboardingFinished`.
 
 | Tool | Description |
 |------|-------------|
+| `clearSyncStatus` | Clear sync flags after syncing spec and code |
 | `presentSyncPlan` | Present a markdown sync plan to the user for approval (streams content) |
+| `presentPublishPlan` | Present a publish changelog for user approval (streams content) |
+| `presentPlan` | Present an implementation plan for user approval (streams content) |
 
 ### Tool Streaming
 
 Tools can opt into streaming via a `streaming` config on the tool definition:
 
-- **Content streaming** (writeSpec, writeFile, presentSyncPlan): Streams `tool_input_delta` events with progressive content as the LLM generates tool arguments. Tools can provide a `transform` function to customize the streamed output (e.g., writeSpec/writeFile compute a progressive diff).
+- **Content streaming** (writeSpec, writeFile, presentSyncPlan, presentPublishPlan, presentPlan): Streams `tool_input_delta` events with progressive content as the LLM generates tool arguments. Tools can provide a `transform` function to customize the streamed output (e.g., writeSpec/writeFile compute a progressive diff).
 - **Input streaming** (promptUser): Streams progressive `tool_start` events with `partial: true` as structured input (like a questions array) builds up.
 - **No streaming** (all other tools): `tool_start` fires once when the complete tool arguments are available.
 
@@ -111,10 +115,10 @@ Streaming is driven by `tool_input_delta` (Anthropic) or `tool_input_args` (Gemi
 ```
 User input
   → Agent loop (src/agent.ts)
-    → POST /_internal/v2/agent/chat (SSE stream)
+    → POST /_internal/v2/agent/remy/chat (SSE stream)
       ← text, thinking, tool_input_delta, tool_input_args, tool_use events
     → Execute tools locally in parallel
-      → External tools (promptUser, setViewMode, etc.) wait for sandbox response
+      → External tools wait for sandbox response
     → Send tool results back
     → Loop until done
     → Save session to .remy-session.json
@@ -136,9 +140,11 @@ src/
   headless.ts            stdin/stdout JSON protocol for sandbox
 
   prompt/
-    index.ts             System prompt builder (mode-aware)
+    index.ts             System prompt builder (onboarding-state-aware)
     actions/             Built-in prompts for runCommand actions
       sync.md
+      publish.md
+      buildFromInitialSpec.md
     static/              Behavioral instruction fragments
       identity.md
       intake.md
@@ -147,7 +153,7 @@ src/
       lsp.md
       projectContext.ts  Reads manifest, spec metadata, file listing at runtime
     compiled/            Platform docs distilled for agent consumption
-    sources/             Raw source docs (fetched + manual)
+    sources/             Prompt source material (hand-maintained)
 
   tools/
     index.ts             Tool registry with streaming config interface
@@ -159,10 +165,13 @@ src/
       writeSpec.ts
       editSpec.ts
       listSpecFiles.ts
-      setViewMode.ts
+      setProjectOnboardingState.ts
       promptUser.ts
+      confirmDestructiveAction.ts
       clearSyncStatus.ts
       presentSyncPlan.ts
+      presentPublishPlan.ts
+      presentPlan.ts
       _helpers.ts        Heading resolution, path validation
     code/                Code tools (file editing, shell, search)
       readFile.ts
@@ -175,6 +184,7 @@ src/
       glob.ts
       listDir.ts
       editsFinished.ts
+      askMindStudioSdk.ts
       lspDiagnostics.ts
       restartProcess.ts
 
@@ -188,12 +198,15 @@ src/
 
 ### External Tools
 
-Some tools are resolved by the sandbox rather than executed locally. Remy emits `tool_start`, then waits for the sandbox to send back a `tool_result` via stdin. This is used for tools that require sandbox/user interaction:
+Some tools are resolved by the sandbox rather than executed locally. Remy emits `tool_start`, then waits for the sandbox to send back a `tool_result` via stdin:
 
 - `promptUser` — renders a form or inline prompt, blocks until user responds
-- `setViewMode` — switches the IDE view mode
+- `setProjectOnboardingState` — advances the onboarding flow
+- `confirmDestructiveAction` — renders a confirmation dialog
 - `clearSyncStatus` — clears sync dirty flags and updates git sync ref
 - `presentSyncPlan` — renders a full-screen markdown plan for user approval
+- `presentPublishPlan` — renders a full-screen changelog for user approval
+- `presentPlan` — renders a full-screen implementation plan for user approval
 
 ### Project Instructions
 
@@ -214,15 +227,15 @@ Send JSON commands, one per line.
 Send a user message to the agent.
 
 ```json
-{"action": "message", "text": "fix the bug in auth.ts", "projectHasCode": true}
+{"action": "message", "text": "fix the bug in auth.ts", "onboardingState": "onboardingFinished"}
 ```
 
 Fields:
 - `text` — the user message (required unless `runCommand` is set)
-- `projectHasCode` — controls tool availability (default: `true`)
+- `onboardingState` — controls tool availability and prompt context. One of: `intake`, `initialSpecAuthoring`, `initialCodegen`, `onboardingFinished` (default: `onboardingFinished`)
 - `viewContext` — `{ mode, openFiles?, activeFile? }` for prompt context
 - `attachments` — array of `{ url, extractedTextUrl? }` for file attachments
-- `runCommand` — triggers a built-in action prompt (e.g., `"sync"`)
+- `runCommand` — triggers a built-in action prompt (`"sync"`, `"publish"`, `"buildFromInitialSpec"`)
 
 When `runCommand` is set, the message text is replaced with a built-in prompt and the user message is marked as `hidden` in conversation history (sent to the LLM but not shown in the UI).
 

package/dist/actions/buildFromInitialSpec.md

@@ -0,0 +1,5 @@
+This is an automated action triggered by the user pressing "Build" in the editor after reviewing the spec.
+
+The user has reviewed the spec and is ready to build. Build everything in one turn: methods, tables, interfaces, manifest updates, and scenarios, using the spec as the master plan.
+
+When code generation is complete, call `setProjectOnboardingState({ state: "onboardingFinished" })`.

package/dist/compiled/design.md

@@ -94,6 +94,10 @@ or streams in makes an interface feel broken.
   before the image loads.
 - Loading-to-loaded transitions should swap content in-place without
   changing container size.
+- Buttons must not change size during loading states. Use a fixed width or
+  `min-width`, and swap the label for a spinner or short text that fits the
+  same space. "Submit" becoming "Submitting..." should not make the button
+  wider and push adjacent elements around.
 - Conditional UI should use opacity/overlay transitions, not insertion into
   flow that displaces existing content.
 

package/dist/compiled/sdk-actions.md

@@ -1,8 +1,8 @@
 # MindStudio Agent SDK
 
-`@mindstudio-ai/agent` provides access to 200+ AI models and 1,000+ actions through a single API key. No separate provider keys needed — MindStudio routes to the correct provider (OpenAI, Anthropic, Google, etc.) server-side.
+`@mindstudio-ai/agent` provides access to 200+ AI models and 1,000+ actions through a single API key. No separate provider keys needed. MindStudio routes to the correct provider (OpenAI, Anthropic, Google, etc.) server-side.
 
-**Full reference:** For complete method signatures, parameters, and output types, read `dist/methods/node_modules/@mindstudio-ai/agent/llms.txt`. This file ships with the package and contains the full API reference for all 170+ actions.
+There is a huge amount of capability here: hundreds of text generation models (OpenAI, Anthropic, Google, Meta, Mistral, and more), dozens of image generation models (FLUX, DALL-E, Stable Diffusion, Ideogram, and more), video generation, text-to-speech, music generation, vision analysis, web scraping, 850+ OAuth connectors, and much more. The tables below are a summary. **Always use the `askMindStudioSdk` tool to look up exact method signatures, model IDs, and config options before writing code that uses the SDK.** The SDK assistant knows every action, every model, every connector, and the user's configured OAuth connections. Don't guess at parameters or model IDs from memory.
 
 ## Usage in Methods
 
@@ -120,7 +120,7 @@ const result = await agent.runFromConnectorRegistry({
 
 ### Model Selection
 
-Override the default model for any AI action:
+Override the default model for any AI action. Each model has its own config options (dimensions, seed, inference steps, etc.) so always use `askMindStudioSdk` to look up the correct config before specifying a model override:
 
 ```typescript
 const { content } = await agent.generateText({
@@ -133,12 +133,6 @@ const { content } = await agent.generateText({
 });
 ```
 
-Browse available models:
-
-```typescript
-const { models } = await agent.listModelsSummaryByType('llm_chat');
-```
-
 ### Batch Execution
 
 Run up to 50 actions in parallel:

package/dist/headless.js

@@ -281,7 +281,7 @@ function resolveIncludes(template) {
   );
   return result.replace(/\n{3,}/g, "\n\n").trim();
 }
-function buildSystemPrompt(projectHasCode, viewContext) {
+function buildSystemPrompt(onboardingState, viewContext) {
   const projectContext = [
     loadProjectInstructions(),
     loadProjectManifest(),
@@ -347,23 +347,32 @@ The current date is ${now}.
   {{compiled/msfm.md}}
 </mindstudio_flavored_markdown_spec_docs>
 
+${isLspConfigured() ? `<typescript_lsp>
+{{static/lsp.md}}
+</typescript_lsp>` : ""}
+
 <project_context>
 ${projectContext}
 </project_context>
 
-${isLspConfigured() ? `<lsp>
-{{static/lsp.md}}
-</lsp>` : ""}
-
 {{static/intake.md}}
 
 {{static/authoring.md}}
 
 {{static/instructions.md}}
 
-<current_authoring_mode>
-${projectHasCode ? "Project has code - keep code and spec in sync." : "Project does not have code yet - focus on writing the spec."}
-</current_authoring_mode>
+<project_onboarding>
+New projects progress through four onboarding states. The user might skip this entirely and jump straight into working on the existing scaffold (which defaults to onboardingFinished), but ideally new projects move through each phase:
+
+- **intake**: Gathering requirements. The project has scaffold code (a "hello world" starter) but it's not the user's app yet. Focus on understanding what they want to build, not on the existing code.
+- **initialSpecAuthoring**: Writing and refining the first spec. The user can see it in the editor as it streams in and can give feedback to iterate on it. This phase covers both the initial draft and any back-and-forth refinement before code generation.
+- **initialCodegen**: First code generation from the spec. The agent is generating methods, tables, interfaces, manifest updates, and scenarios. This can take a while and involves heavy tool use. The user sees a full-screen build progress view.
+- **onboardingFinished**: The project is built and ready. Full development mode with all tools available. From here on, keep spec and code in sync as changes are made.
+
+  <current_project_onboarding_state>
+  ${onboardingState ?? "onboardingFinished"}
+  </current_project_onboarding_state>
+</project_onboarding>
 
 <view_context>
 The user is currently in ${viewContext?.mode ?? "code"} mode.
@@ -376,7 +385,7 @@ ${viewContext?.activeFile ? `Active file: ${viewContext.activeFile}` : ""}
 // src/api.ts
 async function* streamChat(params) {
   const { baseUrl, apiKey, signal, ...body } = params;
-  const url = `${baseUrl}/_internal/v2/agent/chat`;
+  const url = `${baseUrl}/_internal/v2/agent/remy/chat`;
   const startTime = Date.now();
   const messagesWithAttachments = body.messages.filter(
     (m) => m.attachments && m.attachments.length > 0
@@ -625,8 +634,8 @@ import path4 from "path";
 // src/tools/_helpers/diff.ts
 var CONTEXT_LINES = 3;
 function unifiedDiff(filePath, oldText, newText) {
-  const oldLines = oldText.split("\n");
-  const newLines = newText.split("\n");
+  const oldLines = oldText ? oldText.split("\n") : [];
+  const newLines = newText ? newText.split("\n") : [];
   let firstDiff = 0;
   while (firstDiff < oldLines.length && firstDiff < newLines.length && oldLines[firstDiff] === newLines[firstDiff]) {
     firstDiff++;
@@ -877,33 +886,29 @@ async function listRecursive(dir) {
   return results;
 }
 
-// src/tools/spec/setViewMode.ts
-var setViewModeTool = {
+// src/tools/spec/setProjectOnboardingState.ts
+var setProjectOnboardingStateTool = {
   definition: {
-    name: "setViewMode",
-    description: 'Switch the IDE view mode. Use this to navigate the user to the right context. When transitioning from intake to spec, write the first spec file BEFORE calling this \u2014 the user needs something to see when the spec editor opens. Switch to "code" during code generation, then to "preview" when done so the user sees the result.',
+    name: "setProjectOnboardingState",
+    description: "Advance the project onboarding state. Call at natural transition points: before writing the first spec (initialSpecAuthoring), before starting the first code generation (initialCodegen), after the first build succeeds (onboardingFinished). Forward-only progression.",
     inputSchema: {
       type: "object",
       properties: {
-        mode: {
+        state: {
           type: "string",
           enum: [
-            "intake",
-            "preview",
-            "spec",
-            "code",
-            "databases",
-            "scenarios",
-            "logs"
+            "initialSpecAuthoring",
+            "initialCodegen",
+            "onboardingFinished"
           ],
-          description: "The view mode to switch to."
+          description: "The onboarding state to advance to."
         }
       },
-      required: ["mode"]
+      required: ["state"]
     }
   },
   async execute() {
-    return "View mode updated.";
+    return "ok";
   }
 };
 
@@ -935,8 +940,8 @@ var promptUserTool = {
               },
               type: {
                 type: "string",
-                enum: ["select", "text", "confirm", "file", "color"],
-                description: "select: pick from options. text: free-form input. confirm: yes/no. file: file/image upload \u2014 returns CDN URL(s) that can be referenced directly or curled onto disk. color: color picker (returns hex)."
+                enum: ["select", "text", "file", "color"],
+                description: 'select: pick from options (or options + free-form "other"). text: free-form input. file: file/image upload, returns CDN URL(s) that can be referenced directly or curled onto disk. color: color picker (returns hex).'
               },
               helpText: {
                 type: "string",
@@ -1032,8 +1037,6 @@ var promptUserTool = {
           (o) => typeof o === "string" ? o : o.label
         );
         line += q.multiple ? ` (pick one or more: ${opts.join(" / ")})` : ` (${opts.join(" / ")})`;
-      } else if (q.type === "confirm") {
-        line += " (yes / no)";
       } else if (q.type === "file") {
         line += " (upload file)";
       } else if (q.type === "color") {
@@ -1127,6 +1130,35 @@ var presentPlanTool = {
   }
 };
 
+// src/tools/spec/confirmDestructiveAction.ts
+var confirmDestructiveActionTool = {
+  definition: {
+    name: "confirmDestructiveAction",
+    description: "Confirm a destructive or irreversible action with the user. Use for things like deleting data, resetting the database, or discarding draft work. Do not use after presentSyncPlan, presentPublishPlan, or presentPlan (those already include approval). Do not use before onboarding state transitions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: {
+          type: "string",
+          description: "Explanation of what is about to happen and why confirmation is needed."
+        },
+        confirmLabel: {
+          type: "string",
+          description: 'Custom label for the confirm button (e.g., "Delete", "Reset Database"). Defaults to "Confirm".'
+        },
+        dismissLabel: {
+          type: "string",
+          description: 'Custom label for the dismiss button (e.g., "Keep It", "Go Back"). Defaults to "Cancel".'
+        }
+      },
+      required: ["message"]
+    }
+  },
+  async execute() {
+    return "confirmed";
+  }
+};
+
 // src/tools/code/readFile.ts
 import fs9 from "fs/promises";
 var DEFAULT_MAX_LINES2 = 500;
@@ -1723,6 +1755,45 @@ var restartProcessTool = {
   }
 };
 
+// src/tools/code/askMindStudioSdk.ts
+import { exec as exec3 } from "child_process";
+var askMindStudioSdkTool = {
+  definition: {
+    name: "askMindStudioSdk",
+    description: "Ask the MindStudio SDK assistant about actions, AI models, connectors, and integrations. Returns code examples with correct method signatures, model IDs, and config options. Use this instead of guessing SDK usage from memory. Describe what you need, not what API methods you need; the assistant will figure out the right approach. This runs its own LLM call so it has a few seconds of latency; batch related questions into a single query.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Natural language question about the SDK."
+        }
+      },
+      required: ["query"]
+    }
+  },
+  async execute(input) {
+    const query = input.query;
+    return new Promise((resolve) => {
+      exec3(
+        `mindstudio ask ${JSON.stringify(query)}`,
+        { timeout: 6e4, maxBuffer: 512 * 1024 },
+        (err, stdout, stderr) => {
+          if (stdout.trim()) {
+            resolve(stdout.trim());
+            return;
+          }
+          if (err) {
+            resolve(`Error: ${stderr.trim() || err.message}`);
+            return;
+          }
+          resolve("(no response)");
+        }
+      );
+    });
+  }
+};
+
 // src/tools/index.ts
 function getSpecTools() {
   return [readSpecTool, writeSpecTool, editSpecTool, listSpecFilesTool];
@@ -1736,46 +1807,51 @@ function getCodeTools() {
     grepTool,
     globTool,
     listDirTool,
-    editsFinishedTool
+    editsFinishedTool,
+    askMindStudioSdkTool
   ];
   if (isLspConfigured()) {
     tools.push(lspDiagnosticsTool, restartProcessTool);
   }
   return tools;
 }
-function getTools(projectHasCode) {
-  if (projectHasCode) {
-    return [
-      setViewModeTool,
-      promptUserTool,
-      clearSyncStatusTool,
-      presentSyncPlanTool,
-      presentPublishPlanTool,
-      presentPlanTool,
-      ...getSpecTools(),
-      ...getCodeTools()
-    ];
-  }
+function getCommonTools() {
   return [
-    setViewModeTool,
+    setProjectOnboardingStateTool,
     promptUserTool,
+    confirmDestructiveActionTool
+  ];
+}
+function getPostOnboardingTools() {
+  return [
     clearSyncStatusTool,
     presentSyncPlanTool,
     presentPublishPlanTool,
-    ...getSpecTools()
+    presentPlanTool
   ];
 }
-function getToolDefinitions(projectHasCode) {
-  return getTools(projectHasCode).map((t) => t.definition);
+function getTools(onboardingState) {
+  switch (onboardingState) {
+    case "onboardingFinished":
+      return [
+        ...getCommonTools(),
+        ...getPostOnboardingTools(),
+        ...getSpecTools(),
+        ...getCodeTools()
+      ];
+    case "initialCodegen":
+      return [...getCommonTools(), ...getSpecTools(), ...getCodeTools()];
+    default:
+      return [...getCommonTools(), ...getSpecTools()];
+  }
+}
+function getToolDefinitions(onboardingState) {
+  return getTools(onboardingState).map((t) => t.definition);
 }
 function getToolByName(name) {
   const allTools = [
-    setViewModeTool,
-    promptUserTool,
-    clearSyncStatusTool,
-    presentSyncPlanTool,
-    presentPublishPlanTool,
-    presentPlanTool,
+    ...getCommonTools(),
+    ...getPostOnboardingTools(),
     ...getSpecTools(),
     ...getCodeTools()
   ];
@@ -2018,11 +2094,12 @@ function parsePartialJson(jsonString) {
 // src/agent.ts
 var EXTERNAL_TOOLS = /* @__PURE__ */ new Set([
   "promptUser",
-  "setViewMode",
+  "setProjectOnboardingState",
   "clearSyncStatus",
   "presentSyncPlan",
   "presentPublishPlan",
-  "presentPlan"
+  "presentPlan",
+  "confirmDestructiveAction"
 ]);
 function createAgentState() {
   return { messages: [] };
@@ -2035,13 +2112,13 @@ async function runTurn(params) {
     apiConfig,
     system,
     model,
-    projectHasCode,
+    onboardingState,
     signal,
     onEvent,
     resolveExternalTool,
     hidden
   } = params;
-  const tools = getToolDefinitions(projectHasCode);
+  const tools = getToolDefinitions(onboardingState);
   log.info("Turn started", {
     messageLength: userMessage.length,
     toolCount: tools.length,
@@ -2353,7 +2430,8 @@ async function startHeadless(opts = {}) {
   }
   let running = false;
   let currentAbort = null;
-  const externalToolPromises = /* @__PURE__ */ new Map();
+  const pendingTools = /* @__PURE__ */ new Map();
+  const earlyResults = /* @__PURE__ */ new Map();
   function onEvent(e) {
     switch (e.type) {
       case "text":
@@ -2365,22 +2443,14 @@ async function startHeadless(opts = {}) {
       case "tool_input_delta":
         emit("tool_input_delta", { id: e.id, name: e.name, result: e.result });
         break;
-      case "tool_start": {
+      case "tool_start":
         emit("tool_start", {
           id: e.id,
           name: e.name,
           input: e.input,
           ...e.partial && { partial: true }
         });
-        if (!e.partial && !externalToolPromises.has(e.id)) {
-          let resolve;
-          const promise = new Promise((r) => {
-            resolve = r;
-          });
-          externalToolPromises.set(e.id, { promise, resolve });
-        }
         break;
-      }
       case "tool_done":
         emit("tool_done", {
           id: e.id,
@@ -2404,16 +2474,14 @@ async function startHeadless(opts = {}) {
     }
   }
   function resolveExternalTool(id, _name, _input) {
-    const entry = externalToolPromises.get(id);
-    if (entry) {
-      return entry.promise;
+    const early = earlyResults.get(id);
+    if (early !== void 0) {
+      earlyResults.delete(id);
+      return Promise.resolve(early);
     }
-    let resolve;
-    const promise = new Promise((r) => {
-      resolve = r;
+    return new Promise((resolve) => {
+      pendingTools.set(id, { resolve });
     });
-    externalToolPromises.set(id, { promise, resolve });
-    return promise;
   }
   const rl = createInterface({ input: process.stdin });
   rl.on("line", async (line) => {
@@ -2425,10 +2493,12 @@ async function startHeadless(opts = {}) {
       return;
     }
     if (parsed.action === "tool_result" && parsed.id) {
-      const entry = externalToolPromises.get(parsed.id);
-      if (entry) {
-        externalToolPromises.delete(parsed.id);
-        entry.resolve(parsed.result ?? "");
+      const pending = pendingTools.get(parsed.id);
+      if (pending) {
+        pendingTools.delete(parsed.id);
+        pending.resolve(parsed.result ?? "");
+      } else {
+        earlyResults.set(parsed.id, parsed.result ?? "");
       }
       return;
     }
@@ -2447,9 +2517,9 @@ async function startHeadless(opts = {}) {
       if (currentAbort) {
         currentAbort.abort();
       }
-      for (const [id, entry] of externalToolPromises) {
-        entry.resolve("Error: cancelled");
-        externalToolPromises.delete(id);
+      for (const [id, pending] of pendingTools) {
+        pending.resolve("Error: cancelled");
+        pendingTools.delete(id);
       }
       return;
     }
@@ -2472,9 +2542,11 @@ async function startHeadless(opts = {}) {
         userMessage = loadActionPrompt("sync");
       } else if (parsed.runCommand === "publish") {
         userMessage = loadActionPrompt("publish");
+      } else if (parsed.runCommand === "buildFromInitialSpec") {
+        userMessage = loadActionPrompt("buildFromInitialSpec");
       }
-      const projectHasCode = parsed.projectHasCode ?? true;
-      const system = buildSystemPrompt(projectHasCode, parsed.viewContext);
+      const onboardingState = parsed.onboardingState ?? "onboardingFinished";
+      const system = buildSystemPrompt(onboardingState, parsed.viewContext);
       try {
         await runTurn({
           state,
@@ -2483,7 +2555,7 @@ async function startHeadless(opts = {}) {
           apiConfig: config,
           system,
           model: opts.model,
-          projectHasCode,
+          onboardingState,
           signal: currentAbort.signal,
           onEvent,
           resolveExternalTool,

package/dist/index.js

@@ -90,7 +90,7 @@ var init_logger = __esm({
 // src/api.ts
 async function* streamChat(params) {
   const { baseUrl, apiKey, signal, ...body } = params;
-  const url = `${baseUrl}/_internal/v2/agent/chat`;
+  const url = `${baseUrl}/_internal/v2/agent/remy/chat`;
   const startTime = Date.now();
   const messagesWithAttachments = body.messages.filter(
     (m) => m.attachments && m.attachments.length > 0
@@ -351,8 +351,8 @@ var init_readSpec = __esm({
 
 // src/tools/_helpers/diff.ts
 function unifiedDiff(filePath, oldText, newText) {
-  const oldLines = oldText.split("\n");
-  const newLines = newText.split("\n");
+  const oldLines = oldText ? oldText.split("\n") : [];
+  const newLines = newText ? newText.split("\n") : [];
   let firstDiff = 0;
   while (firstDiff < oldLines.length && firstDiff < newLines.length && oldLines[firstDiff] === newLines[firstDiff]) {
     firstDiff++;
@@ -634,37 +634,33 @@ var init_listSpecFiles = __esm({
   }
 });
 
-// src/tools/spec/setViewMode.ts
-var setViewModeTool;
-var init_setViewMode = __esm({
-  "src/tools/spec/setViewMode.ts"() {
+// src/tools/spec/setProjectOnboardingState.ts
+var setProjectOnboardingStateTool;
+var init_setProjectOnboardingState = __esm({
+  "src/tools/spec/setProjectOnboardingState.ts"() {
     "use strict";
-    setViewModeTool = {
+    setProjectOnboardingStateTool = {
       definition: {
-        name: "setViewMode",
-        description: 'Switch the IDE view mode. Use this to navigate the user to the right context. When transitioning from intake to spec, write the first spec file BEFORE calling this \u2014 the user needs something to see when the spec editor opens. Switch to "code" during code generation, then to "preview" when done so the user sees the result.',
+        name: "setProjectOnboardingState",
+        description: "Advance the project onboarding state. Call at natural transition points: before writing the first spec (initialSpecAuthoring), before starting the first code generation (initialCodegen), after the first build succeeds (onboardingFinished). Forward-only progression.",
         inputSchema: {
           type: "object",
           properties: {
-            mode: {
+            state: {
               type: "string",
               enum: [
-                "intake",
-                "preview",
-                "spec",
-                "code",
-                "databases",
-                "scenarios",
-                "logs"
+                "initialSpecAuthoring",
+                "initialCodegen",
+                "onboardingFinished"
               ],
-              description: "The view mode to switch to."
+              description: "The onboarding state to advance to."
             }
           },
-          required: ["mode"]
+          required: ["state"]
         }
       },
       async execute() {
-        return "View mode updated.";
+        return "ok";
       }
     };
   }
@@ -702,8 +698,8 @@ var init_promptUser = __esm({
                   },
                   type: {
                     type: "string",
-                    enum: ["select", "text", "confirm", "file", "color"],
-                    description: "select: pick from options. text: free-form input. confirm: yes/no. file: file/image upload \u2014 returns CDN URL(s) that can be referenced directly or curled onto disk. color: color picker (returns hex)."
+                    enum: ["select", "text", "file", "color"],
+                    description: 'select: pick from options (or options + free-form "other"). text: free-form input. file: file/image upload, returns CDN URL(s) that can be referenced directly or curled onto disk. color: color picker (returns hex).'
                   },
                   helpText: {
                     type: "string",
@@ -799,8 +795,6 @@ var init_promptUser = __esm({
               (o) => typeof o === "string" ? o : o.label
             );
             line += q.multiple ? ` (pick one or more: ${opts.join(" / ")})` : ` (${opts.join(" / ")})`;
-          } else if (q.type === "confirm") {
-            line += " (yes / no)";
           } else if (q.type === "file") {
             line += " (upload file)";
           } else if (q.type === "color") {
@@ -920,6 +914,41 @@ var init_presentPlan = __esm({
   }
 });
 
+// src/tools/spec/confirmDestructiveAction.ts
+var confirmDestructiveActionTool;
+var init_confirmDestructiveAction = __esm({
+  "src/tools/spec/confirmDestructiveAction.ts"() {
+    "use strict";
+    confirmDestructiveActionTool = {
+      definition: {
+        name: "confirmDestructiveAction",
+        description: "Confirm a destructive or irreversible action with the user. Use for things like deleting data, resetting the database, or discarding draft work. Do not use after presentSyncPlan, presentPublishPlan, or presentPlan (those already include approval). Do not use before onboarding state transitions.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            message: {
+              type: "string",
+              description: "Explanation of what is about to happen and why confirmation is needed."
+            },
+            confirmLabel: {
+              type: "string",
+              description: 'Custom label for the confirm button (e.g., "Delete", "Reset Database"). Defaults to "Confirm".'
+            },
+            dismissLabel: {
+              type: "string",
+              description: 'Custom label for the dismiss button (e.g., "Keep It", "Go Back"). Defaults to "Cancel".'
+            }
+          },
+          required: ["message"]
+        }
+      },
+      async execute() {
+        return "confirmed";
+      }
+    };
+  }
+});
+
 // src/tools/code/readFile.ts
 import fs6 from "fs/promises";
 function isBinary(buffer) {
@@ -1626,6 +1655,51 @@ var init_restartProcess = __esm({
   }
 });
 
+// src/tools/code/askMindStudioSdk.ts
+import { exec as exec3 } from "child_process";
+var askMindStudioSdkTool;
+var init_askMindStudioSdk = __esm({
+  "src/tools/code/askMindStudioSdk.ts"() {
+    "use strict";
+    askMindStudioSdkTool = {
+      definition: {
+        name: "askMindStudioSdk",
+        description: "Ask the MindStudio SDK assistant about actions, AI models, connectors, and integrations. Returns code examples with correct method signatures, model IDs, and config options. Use this instead of guessing SDK usage from memory. Describe what you need, not what API methods you need; the assistant will figure out the right approach. This runs its own LLM call so it has a few seconds of latency; batch related questions into a single query.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Natural language question about the SDK."
+            }
+          },
+          required: ["query"]
+        }
+      },
+      async execute(input) {
+        const query = input.query;
+        return new Promise((resolve) => {
+          exec3(
+            `mindstudio ask ${JSON.stringify(query)}`,
+            { timeout: 6e4, maxBuffer: 512 * 1024 },
+            (err, stdout, stderr) => {
+              if (stdout.trim()) {
+                resolve(stdout.trim());
+                return;
+              }
+              if (err) {
+                resolve(`Error: ${stderr.trim() || err.message}`);
+                return;
+              }
+              resolve("(no response)");
+            }
+          );
+        });
+      }
+    };
+  }
+});
+
 // src/tools/index.ts
 function getSpecTools() {
   return [readSpecTool, writeSpecTool, editSpecTool, listSpecFilesTool];
@@ -1639,46 +1713,51 @@ function getCodeTools() {
     grepTool,
     globTool,
     listDirTool,
-    editsFinishedTool
+    editsFinishedTool,
+    askMindStudioSdkTool
   ];
   if (isLspConfigured()) {
     tools.push(lspDiagnosticsTool, restartProcessTool);
   }
   return tools;
 }
-function getTools(projectHasCode) {
-  if (projectHasCode) {
-    return [
-      setViewModeTool,
-      promptUserTool,
-      clearSyncStatusTool,
-      presentSyncPlanTool,
-      presentPublishPlanTool,
-      presentPlanTool,
-      ...getSpecTools(),
-      ...getCodeTools()
-    ];
-  }
+function getCommonTools() {
   return [
-    setViewModeTool,
+    setProjectOnboardingStateTool,
     promptUserTool,
+    confirmDestructiveActionTool
+  ];
+}
+function getPostOnboardingTools() {
+  return [
     clearSyncStatusTool,
     presentSyncPlanTool,
     presentPublishPlanTool,
-    ...getSpecTools()
+    presentPlanTool
   ];
 }
-function getToolDefinitions(projectHasCode) {
-  return getTools(projectHasCode).map((t) => t.definition);
+function getTools(onboardingState) {
+  switch (onboardingState) {
+    case "onboardingFinished":
+      return [
+        ...getCommonTools(),
+        ...getPostOnboardingTools(),
+        ...getSpecTools(),
+        ...getCodeTools()
+      ];
+    case "initialCodegen":
+      return [...getCommonTools(), ...getSpecTools(), ...getCodeTools()];
+    default:
+      return [...getCommonTools(), ...getSpecTools()];
+  }
+}
+function getToolDefinitions(onboardingState) {
+  return getTools(onboardingState).map((t) => t.definition);
 }
 function getToolByName(name) {
   const allTools = [
-    setViewModeTool,
-    promptUserTool,
-    clearSyncStatusTool,
-    presentSyncPlanTool,
-    presentPublishPlanTool,
-    presentPlanTool,
+    ...getCommonTools(),
+    ...getPostOnboardingTools(),
     ...getSpecTools(),
     ...getCodeTools()
   ];
@@ -1698,12 +1777,13 @@ var init_tools = __esm({
     init_writeSpec();
     init_editSpec();
     init_listSpecFiles();
-    init_setViewMode();
+    init_setProjectOnboardingState();
     init_promptUser();
     init_clearSyncStatus();
     init_presentSyncPlan();
     init_presentPublishPlan();
     init_presentPlan();
+    init_confirmDestructiveAction();
     init_readFile();
     init_writeFile();
     init_editFile();
@@ -1715,6 +1795,7 @@ var init_tools = __esm({
     init_lsp();
     init_lspDiagnostics();
     init_restartProcess();
+    init_askMindStudioSdk();
   }
 });
 
@@ -1968,13 +2049,13 @@ async function runTurn(params) {
     apiConfig,
     system,
     model,
-    projectHasCode,
+    onboardingState,
     signal,
     onEvent,
     resolveExternalTool,
     hidden
   } = params;
-  const tools = getToolDefinitions(projectHasCode);
+  const tools = getToolDefinitions(onboardingState);
   log.info("Turn started", {
     messageLength: userMessage.length,
     toolCount: tools.length,
@@ -2264,11 +2345,12 @@ var init_agent = __esm({
     init_parsePartialJson();
     EXTERNAL_TOOLS = /* @__PURE__ */ new Set([
       "promptUser",
-      "setViewMode",
+      "setProjectOnboardingState",
       "clearSyncStatus",
       "presentSyncPlan",
       "presentPublishPlan",
-      "presentPlan"
+      "presentPlan",
+      "confirmDestructiveAction"
     ]);
   }
 });
@@ -2420,7 +2502,7 @@ function resolveIncludes(template) {
   );
   return result.replace(/\n{3,}/g, "\n\n").trim();
 }
-function buildSystemPrompt(projectHasCode, viewContext) {
+function buildSystemPrompt(onboardingState, viewContext) {
   const projectContext = [
     loadProjectInstructions(),
     loadProjectManifest(),
@@ -2486,23 +2568,32 @@ The current date is ${now}.
   {{compiled/msfm.md}}
 </mindstudio_flavored_markdown_spec_docs>
 
+${isLspConfigured() ? `<typescript_lsp>
+{{static/lsp.md}}
+</typescript_lsp>` : ""}
+
 <project_context>
 ${projectContext}
 </project_context>
 
-${isLspConfigured() ? `<lsp>
-{{static/lsp.md}}
-</lsp>` : ""}
-
 {{static/intake.md}}
 
 {{static/authoring.md}}
 
 {{static/instructions.md}}
 
-<current_authoring_mode>
-${projectHasCode ? "Project has code - keep code and spec in sync." : "Project does not have code yet - focus on writing the spec."}
-</current_authoring_mode>
+<project_onboarding>
+New projects progress through four onboarding states. The user might skip this entirely and jump straight into working on the existing scaffold (which defaults to onboardingFinished), but ideally new projects move through each phase:
+
+- **intake**: Gathering requirements. The project has scaffold code (a "hello world" starter) but it's not the user's app yet. Focus on understanding what they want to build, not on the existing code.
+- **initialSpecAuthoring**: Writing and refining the first spec. The user can see it in the editor as it streams in and can give feedback to iterate on it. This phase covers both the initial draft and any back-and-forth refinement before code generation.
+- **initialCodegen**: First code generation from the spec. The agent is generating methods, tables, interfaces, manifest updates, and scenarios. This can take a while and involves heavy tool use. The user sees a full-screen build progress view.
+- **onboardingFinished**: The project is built and ready. Full development mode with all tools available. From here on, keep spec and code in sync as changes are made.
+
+  <current_project_onboarding_state>
+  ${onboardingState ?? "onboardingFinished"}
+  </current_project_onboarding_state>
+</project_onboarding>
 
 <view_context>
 The user is currently in ${viewContext?.mode ?? "code"} mode.
@@ -2609,7 +2700,8 @@ async function startHeadless(opts = {}) {
   }
   let running = false;
   let currentAbort = null;
-  const externalToolPromises = /* @__PURE__ */ new Map();
+  const pendingTools = /* @__PURE__ */ new Map();
+  const earlyResults = /* @__PURE__ */ new Map();
   function onEvent(e) {
     switch (e.type) {
       case "text":
@@ -2621,22 +2713,14 @@ async function startHeadless(opts = {}) {
       case "tool_input_delta":
         emit("tool_input_delta", { id: e.id, name: e.name, result: e.result });
         break;
-      case "tool_start": {
+      case "tool_start":
         emit("tool_start", {
           id: e.id,
           name: e.name,
           input: e.input,
           ...e.partial && { partial: true }
         });
-        if (!e.partial && !externalToolPromises.has(e.id)) {
-          let resolve;
-          const promise = new Promise((r) => {
-            resolve = r;
-          });
-          externalToolPromises.set(e.id, { promise, resolve });
-        }
         break;
-      }
       case "tool_done":
         emit("tool_done", {
           id: e.id,
@@ -2660,16 +2744,14 @@ async function startHeadless(opts = {}) {
     }
   }
   function resolveExternalTool(id, _name, _input) {
-    const entry = externalToolPromises.get(id);
-    if (entry) {
-      return entry.promise;
+    const early = earlyResults.get(id);
+    if (early !== void 0) {
+      earlyResults.delete(id);
+      return Promise.resolve(early);
     }
-    let resolve;
-    const promise = new Promise((r) => {
-      resolve = r;
+    return new Promise((resolve) => {
+      pendingTools.set(id, { resolve });
     });
-    externalToolPromises.set(id, { promise, resolve });
-    return promise;
   }
   const rl = createInterface({ input: process.stdin });
   rl.on("line", async (line) => {
@@ -2681,10 +2763,12 @@ async function startHeadless(opts = {}) {
       return;
     }
     if (parsed.action === "tool_result" && parsed.id) {
-      const entry = externalToolPromises.get(parsed.id);
-      if (entry) {
-        externalToolPromises.delete(parsed.id);
-        entry.resolve(parsed.result ?? "");
+      const pending = pendingTools.get(parsed.id);
+      if (pending) {
+        pendingTools.delete(parsed.id);
+        pending.resolve(parsed.result ?? "");
+      } else {
+        earlyResults.set(parsed.id, parsed.result ?? "");
       }
       return;
     }
@@ -2703,9 +2787,9 @@ async function startHeadless(opts = {}) {
       if (currentAbort) {
         currentAbort.abort();
       }
-      for (const [id, entry] of externalToolPromises) {
-        entry.resolve("Error: cancelled");
-        externalToolPromises.delete(id);
+      for (const [id, pending] of pendingTools) {
+        pending.resolve("Error: cancelled");
+        pendingTools.delete(id);
       }
       return;
     }
@@ -2728,9 +2812,11 @@ async function startHeadless(opts = {}) {
         userMessage = loadActionPrompt("sync");
       } else if (parsed.runCommand === "publish") {
         userMessage = loadActionPrompt("publish");
+      } else if (parsed.runCommand === "buildFromInitialSpec") {
+        userMessage = loadActionPrompt("buildFromInitialSpec");
       }
-      const projectHasCode = parsed.projectHasCode ?? true;
-      const system = buildSystemPrompt(projectHasCode, parsed.viewContext);
+      const onboardingState = parsed.onboardingState ?? "onboardingFinished";
+      const system = buildSystemPrompt(onboardingState, parsed.viewContext);
       try {
         await runTurn({
           state,
@@ -2739,7 +2825,7 @@ async function startHeadless(opts = {}) {
           apiConfig: config,
           system,
           model: opts.model,
-          projectHasCode,
+          onboardingState,
           signal: currentAbort.signal,
           onEvent,
           resolveExternalTool,
@@ -2986,7 +3072,7 @@ function App({ apiConfig, model }) {
           apiConfig,
           system,
           model,
-          projectHasCode: true,
+          onboardingState: "onboardingFinished",
           signal: abort.signal,
           onEvent: (event) => {
             switch (event.type) {

package/dist/static/authoring.md

@@ -33,7 +33,7 @@ After writing the first draft, guide the user through it. Don't just ask "does t
 - When the user asks "is this ready?" — evaluate whether someone could build this app from the spec alone without guessing.
 
 **Building from the spec:**
-When the user is satisfied with the spec, use `promptUser` with a confirm to gate before building code. Once they approve, build everything in one turn — methods, tables, interfaces, manifest updates, and scenarios — using the spec as the master plan. Call `setViewMode({ mode: "code" })` when you start writing code so the user can see files being created. When code generation is complete, call `setViewMode({ mode: "preview" })` so the user sees a full-screen preview of what was built.
+When the user clicks "Build," you will receive a build command. Build everything in one turn: methods, tables, interfaces, manifest updates, and scenarios, using the spec as the master plan. The onboarding state transitions are handled automatically as part of the build command.
 
 **Scenarios are required.** Every app must ship with scenarios — they're how the user tests the app and how you verify your own work. Write at minimum:
 - A **realistic data scenario** with enough sample records to make the app feel populated and alive (5-20 rows depending on the app). Use plausible names, dates, amounts — not "test 1", "test 2".

package/dist/static/instructions.md

@@ -8,7 +8,7 @@
 - The spec is the source of truth. When in doubt, consult the spec before making code changes. When behavior changes, update the spec first.
 - Change only what the task requires. Match existing code style. Keep solutions simple.
 - Read files before editing them. Understand the context before making changes.
-- When the user asks you to make a change, execute it fully — all steps, no pausing for confirmation. Use `promptUser` to gate before major transitions (e.g., building code from a spec). For large changes that touch many files or involve significant design decisions, use `presentPlan` to get user approval first — but only when the scope genuinely warrants it or the user asks to see a plan. Most work should be done autonomously.
+- When the user asks you to make a change, execute it fully — all steps, no pausing for confirmation. Use `confirmDestructiveAction` to gate before destructive or irreversible actions (e.g., deleting data, resetting the database). For large changes that touch many files or involve significant design decisions, use `presentPlan` to get user approval first — but only when the scope genuinely warrants it or the user asks to see a plan. Most work should be done autonomously.
 - After two failed attempts at the same approach, tell the user what's going wrong.
 - Pushing to main branch will trigger a deploy. Use git via bash when the user wants to deploy.
 
@@ -18,4 +18,4 @@
 - Always use full paths relative to the project root when mentioning files (`dist/interfaces/web/src/App.tsx`, not `App.tsx`). Paths will be rendered as clickable links for the user.
 - When summarizing changes, describe what you did in plain language rather than listing a per-file changelog.
 - Use inline `code` formatting only for things the user needs to type or search for.
-- Do not use emojis and avoid overuse of em dashes.
+- Do not use emojis. Avoid em dashes in prose; use periods, commas, colons, or parentheses instead.

package/dist/static/intake.md

@@ -29,8 +29,8 @@ Be upfront about these early if the conversation is heading that way. Better to
 **Guiding the conversation:**
 Keep chat brief. Your goal is to understand the general idea, not to nail every detail — that's what forms and the spec are for.
 
-1. **Brief chat** — Understand what they want to build and why. A few exchanges to get the shape of the idea. If the user comes in with a clear description, you may only need one exchange before moving to forms.
-2. **Structured forms** — Once you have the general idea, use `promptUser` with `type: "form"` to collect details. Forms are easier for users than describing things in chat, especially when they may not have the language for what they want. Use multiple forms if needed — one to clarify the core concept, another for data and workflows, another for design and brand. Each form should build on what you've already learned. Always use `type: "form"` during intake — the form takes over the screen, so don't mix in inline prompts or chat questions between forms.
+1. **Brief chat** — Only when you need to understand the idea or have a conversation. If the user says "hello" or gives a vague description, chat to figure out what they're thinking. But if the user's first message gives you a clear enough idea of what they want to build, acknowledge the idea briefly and move to a form. Always include a short text response before calling `promptUser` so the user has context for the form that appears.
+2. **Structured forms** — Use `promptUser` with `type: "form"` to collect details. If you can express your questions as structured options (select, text, color), use a form instead of asking in chat. Forms are easier for users than describing things in words, especially when they may not have the language for what they want. Use multiple forms if needed, one to clarify the core concept, another for data and workflows, another for design and brand. Each form should build on what you've already learned. Always use `type: "form"` during intake. The form takes over the screen, so don't mix in inline prompts or chat questions between forms.
 3. **Write the spec** — Turn everything into a first draft and get it on screen. The spec is intentionally a starting point, not a finished product. The user will refine it from there.
 
 **What NOT to do:**
@@ -41,4 +41,4 @@ Keep chat brief. Your goal is to understand the general idea, not to nail every
 - Do not try to collect everything through chat. Use forms for structured details — they're less taxing for the user and produce better answers.
 
 **When intake is done:**
-Once you have a clear enough picture — the core data model, the key workflows, who uses it, and which interfaces matter — let them know you're ready to start writing the spec. First, clear the scaffold placeholder by writing an empty `src/app.md` with `writeSpec`. Then call `setViewMode({ mode: "spec" })` so the editor opens. Then start writing the real spec with `writeSpec` — the user will see it stream in live.
+Once you have a clear enough picture (the core data model, the key workflows, who uses it, and which interfaces matter) let them know you're ready to start writing the spec. First, call `setProjectOnboardingState({ state: "initialSpecAuthoring" })` so the editor opens. Then start writing the real spec with `writeSpec`. The user will see it stream in live.

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MindStudio coding agent",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mindstudio-ai/remy"
+  },
   "type": "module",
   "main": "./dist/headless.js",
   "types": "./dist/headless.d.ts",