@mindstudio-ai/remy 0.1.276 → 0.1.278

package/dist/headless.js

@@ -681,10 +681,9 @@ The user has approved your implementation plan in .remy-plan.md. You may referen
   }
 }
 
-// src/prompt/skills/catalog.ts
+// src/skillCatalog.ts
 import fs5 from "fs";
 import path3 from "path";
-var SKILLS_DIR = assetPath("prompt", "skills");
 function parseFrontmatter(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (!match) {
@@ -699,16 +698,16 @@ function parseFrontmatter(content) {
   }
   return fields;
 }
-function loadCatalog() {
+function buildSkillCatalog(opts) {
   let files;
   try {
-    files = fs5.readdirSync(SKILLS_DIR).filter((f) => f.endsWith(".md"));
+    files = fs5.readdirSync(opts.dir).filter((f) => f.endsWith(".md"));
   } catch {
-    return [];
+    files = [];
   }
   const skills = [];
   for (const file of files.sort()) {
-    const full = path3.join(SKILLS_DIR, file);
+    const full = path3.join(opts.dir, file);
     const id = file.replace(/\.md$/, "");
     const fields = parseFrontmatter(fs5.readFileSync(full, "utf-8"));
     if (!fields.name || !fields.what || !fields.when) {
@@ -722,38 +721,58 @@ function loadCatalog() {
       path: full
     });
   }
-  return skills;
+  return {
+    skills,
+    ids: skills.map((s) => s.id),
+    get(id) {
+      return skills.find((s) => s.id === id);
+    },
+    readBody(skill) {
+      return fs5.readFileSync(skill.path, "utf-8").replace(/^---[\s\S]*?---\s*/, "").trim();
+    },
+    renderCatalogBlock() {
+      if (skills.length === 0) {
+        return "";
+      }
+      const entries = skills.map(
+        (s) => [
+          `### ${s.name} (\`${s.id}\`)`,
+          s.what,
+          "",
+          `When to load: ${s.when}`,
+          `Reference: ${s.path}`
+        ].join("\n")
+      );
+      return `<${opts.tag}>
+${opts.intro}
+
+${entries.join("\n\n")}
+</${opts.tag}>`;
+    }
+  };
 }
-var SKILLS = loadCatalog();
-var SKILL_IDS = SKILLS.map((s) => s.id);
+
+// src/prompt/skills/_catalog.ts
+var INTRO = `Platform capabilities most apps don't use, so their references are kept out of this prompt rather than competing for your attention on every task \u2014 not because they're marginal.
+
+Read what follows as part of what the platform can do, not as a lookup table. Recognising that one of these fits a feature is your job, and proposing one is fair game \u2014 several of them are the difference between an app that works and an app worth showing off. When a trigger fires, load the reference with loadSkill before writing the code rather than after. Loading is cheap and expected; guessing at one of these APIs is not.
+
+A loaded reference drops out of the conversation once it ages out. Re-read it at the path listed with readFile whenever you need it again.`;
+var catalog = buildSkillCatalog({
+  dir: assetPath("prompt", "skills"),
+  tag: "available_skills",
+  intro: INTRO
+});
+var SKILLS = catalog.skills;
+var SKILL_IDS = catalog.ids;
 function getSkill(id) {
-  return SKILLS.find((s) => s.id === id);
+  return catalog.get(id);
 }
 function readSkillBody(skill) {
-  return fs5.readFileSync(skill.path, "utf-8").replace(/^---[\s\S]*?---\s*/, "").trim();
+  return catalog.readBody(skill);
 }
 function loadSkillsCatalog() {
-  if (SKILLS.length === 0) {
-    return "";
-  }
-  const entries = SKILLS.map(
-    (s) => [
-      `### ${s.name} (\`${s.id}\`)`,
-      s.what,
-      "",
-      `When to load: ${s.when}`,
-      `Reference: ${s.path}`
-    ].join("\n")
-  );
-  return `<available_skills>
-Platform capabilities most apps don't use, so their references are kept out of this prompt rather than competing for your attention on every task \u2014 not because they're marginal.
-
-Read what follows as part of what the platform can do, not as a lookup table. Recognising that one of these fits a feature is your job, and proposing one is fair game \u2014 several of them are the difference between an app that works and an app worth showing off. When a trigger fires, load the reference with loadSkill before writing the code rather than after. Loading is cheap and expected; guessing at one of these APIs is not.
-
-A loaded reference drops out of the conversation once it ages out. Re-read it at the path listed with readFile whenever you need it again.
-
-${entries.join("\n\n")}
-</available_skills>`;
+  return catalog.renderCatalogBlock();
 }
 
 // src/prompt/index.ts
@@ -5452,6 +5471,59 @@ async function execute8(input, _onLog, context) {
   return copyEditorTool.execute(input, context);
 }
 
+// src/subagents/designExpert/tools/loadSkill.ts
+var loadSkill_exports = {};
+__export(loadSkill_exports, {
+  definition: () => definition9,
+  execute: () => execute9
+});
+
+// src/subagents/designExpert/skills/_catalog.ts
+var INTRO2 = `Deep craft references for specific surfaces, kept out of this prompt so they can go far beyond what a resident section could \u2014 full technique recipes, worked examples, quality bars. Recognising that one of these fits the brief is part of your job as much as the design work itself: when a trigger fires, load the reference with loadSkill before designing in that area, not after. The craft in these docs is the difference between a defaulted artifact and a designed one.
+
+A loaded reference drops out of the conversation once it ages out. Re-read it at the path listed with readFile whenever you need it again.`;
+var designSkillCatalog = buildSkillCatalog({
+  dir: assetPath("subagents/designExpert", "skills"),
+  tag: "available_skills",
+  intro: INTRO2
+});
+
+// src/subagents/designExpert/tools/loadSkill.ts
+var definition9 = {
+  name: "loadSkill",
+  description: "Load the full craft reference for a design surface that isn't in your prompt. The available skills and the trigger for each are listed in <available_skills>. Load one before designing in its area, not after \u2014 these are hard-won technique recipes, and the defaulted version of these surfaces is exactly what they exist to prevent. Calling this is cheap and expected \u2014 if you're unsure whether you need it, load it.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      skill: {
+        type: "string",
+        // Omitted when the catalog is empty: an empty enum is a schema no
+        // provider accepts, and failing one tool call beats failing every
+        // request if the docs ever go missing from a build.
+        ...designSkillCatalog.ids.length > 0 ? { enum: designSkillCatalog.ids } : {},
+        description: "The skill id, as listed in <available_skills>."
+      }
+    },
+    required: ["skill"]
+  }
+};
+async function execute9(input) {
+  const id = String(input.skill ?? "");
+  const skill = designSkillCatalog.get(id);
+  if (!skill) {
+    return `Error: unknown skill "${id}". Available: ${designSkillCatalog.ids.join(", ") || "(none)"}`;
+  }
+  try {
+    const body = designSkillCatalog.readBody(skill);
+    return `${body}
+
+---
+This reference lives at ${skill.path}. Re-read it with readFile if you need it again later \u2014 it won't stay in the conversation.`;
+  } catch (err) {
+    return `Error loading skill "${id}": ${err.message}`;
+  }
+}
+
 // src/subagents/designExpert/tools/index.ts
 var tools = {
   searchGoogle: searchGoogle_exports,
@@ -5465,7 +5537,8 @@ var tools = {
   generateImages: generateImages_exports,
   editImages: editImages_exports,
   renderImage: renderImage_exports,
-  polishCopy: polishCopy_exports
+  polishCopy: polishCopy_exports,
+  loadSkill: loadSkill_exports
 };
 var DESIGN_EXPERT_TOOLS = [
   ...COMMON_READ_TOOLS,
@@ -5661,6 +5734,12 @@ function getDesignExpertPrompt(onboardingState, opts) {
     "{{ui_case_studies}}",
     getUiInspirationSample(indices.uiInspiration)
   );
+  const skillsBlock = designSkillCatalog.renderCatalogBlock();
+  if (skillsBlock) {
+    prompt += `
+
+${skillsBlock}`;
+  }
   prompt += "\n\n<!-- cache_breakpoint -->";
   if (specContext) {
     prompt += `

package/dist/index.js

@@ -3015,7 +3015,7 @@ var init_compactConversation = __esm({
   }
 });
 
-// src/prompt/skills/catalog.ts
+// src/skillCatalog.ts
 import fs11 from "fs";
 import path5 from "path";
 function parseFrontmatter(content) {
@@ -3032,16 +3032,16 @@ function parseFrontmatter(content) {
   }
   return fields;
 }
-function loadCatalog() {
+function buildSkillCatalog(opts) {
   let files;
   try {
-    files = fs11.readdirSync(SKILLS_DIR).filter((f) => f.endsWith(".md"));
+    files = fs11.readdirSync(opts.dir).filter((f) => f.endsWith(".md"));
   } catch {
-    return [];
+    files = [];
   }
   const skills = [];
   for (const file of files.sort()) {
-    const full = path5.join(SKILLS_DIR, file);
+    const full = path5.join(opts.dir, file);
     const id = file.replace(/\.md$/, "");
     const fields = parseFrontmatter(fs11.readFileSync(full, "utf-8"));
     if (!fields.name || !fields.what || !fields.when) {
@@ -3055,45 +3055,70 @@ function loadCatalog() {
       path: full
     });
   }
-  return skills;
+  return {
+    skills,
+    ids: skills.map((s) => s.id),
+    get(id) {
+      return skills.find((s) => s.id === id);
+    },
+    readBody(skill) {
+      return fs11.readFileSync(skill.path, "utf-8").replace(/^---[\s\S]*?---\s*/, "").trim();
+    },
+    renderCatalogBlock() {
+      if (skills.length === 0) {
+        return "";
+      }
+      const entries = skills.map(
+        (s) => [
+          `### ${s.name} (\`${s.id}\`)`,
+          s.what,
+          "",
+          `When to load: ${s.when}`,
+          `Reference: ${s.path}`
+        ].join("\n")
+      );
+      return `<${opts.tag}>
+${opts.intro}
+
+${entries.join("\n\n")}
+</${opts.tag}>`;
+    }
+  };
 }
+var init_skillCatalog = __esm({
+  "src/skillCatalog.ts"() {
+    "use strict";
+  }
+});
+
+// src/prompt/skills/_catalog.ts
 function getSkill(id) {
-  return SKILLS.find((s) => s.id === id);
+  return catalog.get(id);
 }
 function readSkillBody(skill) {
-  return fs11.readFileSync(skill.path, "utf-8").replace(/^---[\s\S]*?---\s*/, "").trim();
+  return catalog.readBody(skill);
 }
 function loadSkillsCatalog() {
-  if (SKILLS.length === 0) {
-    return "";
-  }
-  const entries = SKILLS.map(
-    (s) => [
-      `### ${s.name} (\`${s.id}\`)`,
-      s.what,
-      "",
-      `When to load: ${s.when}`,
-      `Reference: ${s.path}`
-    ].join("\n")
-  );
-  return `<available_skills>
-Platform capabilities most apps don't use, so their references are kept out of this prompt rather than competing for your attention on every task \u2014 not because they're marginal.
-
-Read what follows as part of what the platform can do, not as a lookup table. Recognising that one of these fits a feature is your job, and proposing one is fair game \u2014 several of them are the difference between an app that works and an app worth showing off. When a trigger fires, load the reference with loadSkill before writing the code rather than after. Loading is cheap and expected; guessing at one of these APIs is not.
-
-A loaded reference drops out of the conversation once it ages out. Re-read it at the path listed with readFile whenever you need it again.
-
-${entries.join("\n\n")}
-</available_skills>`;
+  return catalog.renderCatalogBlock();
 }
-var SKILLS_DIR, SKILLS, SKILL_IDS;
+var INTRO, catalog, SKILLS, SKILL_IDS;
 var init_catalog = __esm({
-  "src/prompt/skills/catalog.ts"() {
+  "src/prompt/skills/_catalog.ts"() {
     "use strict";
+    init_skillCatalog();
     init_assets();
-    SKILLS_DIR = assetPath("prompt", "skills");
-    SKILLS = loadCatalog();
-    SKILL_IDS = SKILLS.map((s) => s.id);
+    INTRO = `Platform capabilities most apps don't use, so their references are kept out of this prompt rather than competing for your attention on every task \u2014 not because they're marginal.
+
+Read what follows as part of what the platform can do, not as a lookup table. Recognising that one of these fits a feature is your job, and proposing one is fair game \u2014 several of them are the difference between an app that works and an app worth showing off. When a trigger fires, load the reference with loadSkill before writing the code rather than after. Loading is cheap and expected; guessing at one of these APIs is not.
+
+A loaded reference drops out of the conversation once it ages out. Re-read it at the path listed with readFile whenever you need it again.`;
+    catalog = buildSkillCatalog({
+      dir: assetPath("prompt", "skills"),
+      tag: "available_skills",
+      intro: INTRO
+    });
+    SKILLS = catalog.skills;
+    SKILL_IDS = catalog.ids;
   }
 });
 
@@ -6613,6 +6638,72 @@ var init_polishCopy = __esm({
   }
 });
 
+// src/subagents/designExpert/skills/_catalog.ts
+var INTRO2, designSkillCatalog;
+var init_catalog2 = __esm({
+  "src/subagents/designExpert/skills/_catalog.ts"() {
+    "use strict";
+    init_skillCatalog();
+    init_assets();
+    INTRO2 = `Deep craft references for specific surfaces, kept out of this prompt so they can go far beyond what a resident section could \u2014 full technique recipes, worked examples, quality bars. Recognising that one of these fits the brief is part of your job as much as the design work itself: when a trigger fires, load the reference with loadSkill before designing in that area, not after. The craft in these docs is the difference between a defaulted artifact and a designed one.
+
+A loaded reference drops out of the conversation once it ages out. Re-read it at the path listed with readFile whenever you need it again.`;
+    designSkillCatalog = buildSkillCatalog({
+      dir: assetPath("subagents/designExpert", "skills"),
+      tag: "available_skills",
+      intro: INTRO2
+    });
+  }
+});
+
+// src/subagents/designExpert/tools/loadSkill.ts
+var loadSkill_exports = {};
+__export(loadSkill_exports, {
+  definition: () => definition9,
+  execute: () => execute9
+});
+async function execute9(input) {
+  const id = String(input.skill ?? "");
+  const skill = designSkillCatalog.get(id);
+  if (!skill) {
+    return `Error: unknown skill "${id}". Available: ${designSkillCatalog.ids.join(", ") || "(none)"}`;
+  }
+  try {
+    const body = designSkillCatalog.readBody(skill);
+    return `${body}
+
+---
+This reference lives at ${skill.path}. Re-read it with readFile if you need it again later \u2014 it won't stay in the conversation.`;
+  } catch (err) {
+    return `Error loading skill "${id}": ${err.message}`;
+  }
+}
+var definition9;
+var init_loadSkill2 = __esm({
+  "src/subagents/designExpert/tools/loadSkill.ts"() {
+    "use strict";
+    init_catalog2();
+    definition9 = {
+      name: "loadSkill",
+      description: "Load the full craft reference for a design surface that isn't in your prompt. The available skills and the trigger for each are listed in <available_skills>. Load one before designing in its area, not after \u2014 these are hard-won technique recipes, and the defaulted version of these surfaces is exactly what they exist to prevent. Calling this is cheap and expected \u2014 if you're unsure whether you need it, load it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          skill: {
+            type: "string",
+            // Omitted when the catalog is empty: an empty enum is a schema no
+            // provider accepts, and failing one tool call beats failing every
+            // request if the docs ever go missing from a build.
+            ...designSkillCatalog.ids.length > 0 ? { enum: designSkillCatalog.ids } : {},
+            description: "The skill id, as listed in <available_skills>."
+          }
+        },
+        required: ["skill"]
+      }
+    };
+  }
+});
+
 // src/subagents/designExpert/tools/index.ts
 async function executeDesignExpertTool(name, input, context, toolCallId, onLog) {
   const tool = tools[name];
@@ -6636,6 +6727,7 @@ var init_tools4 = __esm({
     init_editImages();
     init_renderImage();
     init_polishCopy();
+    init_loadSkill2();
     init_screenshot2();
     tools = {
       searchGoogle: searchGoogle_exports,
@@ -6649,7 +6741,8 @@ var init_tools4 = __esm({
       generateImages: generateImages_exports,
       editImages: editImages_exports,
       renderImage: renderImage_exports,
-      polishCopy: polishCopy_exports
+      polishCopy: polishCopy_exports,
+      loadSkill: loadSkill_exports
     };
     DESIGN_EXPERT_TOOLS = [
       ...COMMON_READ_TOOLS,
@@ -6918,6 +7011,12 @@ function getDesignExpertPrompt(onboardingState, opts) {
     "{{ui_case_studies}}",
     getUiInspirationSample(indices.uiInspiration)
   );
+  const skillsBlock = designSkillCatalog.renderCatalogBlock();
+  if (skillsBlock) {
+    prompt += `
+
+${skillsBlock}`;
+  }
   prompt += "\n\n<!-- cache_breakpoint -->";
   if (specContext) {
     prompt += `
@@ -6952,6 +7051,7 @@ var init_prompt2 = __esm({
   "src/subagents/designExpert/prompt.ts"() {
     "use strict";
     init_assets();
+    init_catalog2();
     init_context();
     init_orgContext();
     init_sampleCache();

package/dist/prompt/compiled/methods.md

@@ -202,25 +202,23 @@ export async function createPurchaseOrder(input: {
 
 A method can return immediately while kicking off slow work (like `runTask()`) that continues in the background. Don't await the slow call — use `.then()` / `.catch()` to update the record when it completes, and return an early result to the caller. The frontend polls the record's status to track progress. Wrap background chains other than `runTask()` in `mindstudio.waitUntil(...)` so the platform keeps the sandbox alive for them and records an interruption if they're cut short — `runTask()` registers itself automatically.
 
-The example below shows the fire-and-forget shape, not a complete `runTask()` call. Load the `taskAgents` skill before writing one — configuring its tools, validating the output, and handling failures are all there, and none of them are visible here.
+The example below shows the fire-and-forget shape, not a complete `runTask()` call. Load the `taskAgents` skill before writing one — configuring its tools, the `outputSchema` output contract, and handling failures are all there, and none of them are visible here.
 
 ```typescript
 export async function enrichRestaurant(input: { id: string; name: string }) {
   await Restaurants.update(input.id, { status: 'enriching' });
 
   // Fire — don't await
-  mindstudio.runTask<RestaurantData>({
+  mindstudio.runTask({
     prompt: '...',
     input: { name: input.name },
     tools: ['searchGoogle', 'fetchUrl', 'generateImage'],
-    structuredOutputExample: { /* ... */ },
+    outputSchema: { type: 'object', properties: { /* ... */ }, required: [/* ... */] },
     model: 'claude-5-sonnet',
   }).then(async (result) => {
-    if (result.parsedSuccessfully) {
-      await Restaurants.update(input.id, { ...result.output, status: 'complete' });
-    } else {
-      await Restaurants.update(input.id, { status: 'failed' });
-    }
+    // outputSchema means result.output is validated and typed — a task that
+    // can't produce conforming output rejects into the .catch instead.
+    await Restaurants.update(input.id, { ...result.output, status: 'complete' });
   }).catch(async () => {
     await Restaurants.update(input.id, { status: 'failed' });
   });

package/dist/prompt/skills/agentInterfaces.md

@@ -112,13 +112,7 @@ await chat.deleteThread(thread.id);
 await chat.claimThread(thread.id);
 ```
 
-**Client tools** — a tool whose effect happens in the browser (open a sheet, navigate, highlight)
-is declared with `target: "client"` and a `name` + inline `inputSchema` instead of a `method`
-(names must not collide with method ids; the schema is authored — there's no method contract to
-derive it from). The agent's invocation arrives as the `client_tool_call` stream event / the
-`onClientToolCall` callback on `sendMessage`; run the action there. Fire-and-forget on this
-surface: the agent is told the action was displayed and keeps going — the user's next message
-closes the loop.
+**Client tools** — a tool whose effect happens in the browser (open a sheet, navigate, highlight) is declared with `target: "client"` and a `name` + inline `inputSchema` instead of a `method` (names must not collide with method ids; the schema is authored — there's no method contract to derive it from). The agent's invocation arrives as the `client_tool_call` stream event / the `onClientToolCall` callback on `sendMessage`; run the action there. Fire-and-forget on this surface: the agent is told the action was displayed and keeps going — the user's next message closes the loop.
 
 ```js
 await chat.sendMessage(thread.id, text, {
@@ -183,7 +177,7 @@ Images are sent as vision input; documents have their text extracted server-side
 
 ### Layout
 
-Ask `visualDesignExpert` for ideas about how to design the chat UI in a way that is appropriate and unique to the app.
+The chat UI is a first-class design deliverable, not a bolted-on widget. Bring in `visualDesignExpert` for the chat experience as a whole — message design, streaming behavior, tool-activity presentation, the composer, and the empty state, composed as one surface (it has a dedicated craft reference for exactly this) — and implement what it prescribes. The rules below are the floor, not the direction.
 
 User messages visually distinct from assistant messages (right-aligned, different background, or both). Keep it clean — no avatars unless they add meaning. Generous vertical spacing between messages so the conversation breathes. Use clean, beautiful animation where it is additive.
 
@@ -236,8 +230,7 @@ The chat UI uses the app's design system — colors, typography, voice from `@br
 
 ## Spec: `src/interfaces/agent.md`
 
-The human-readable spec. Frontmatter contains structured fields; the prose body is the behavioral spec —
-voice, personality, capabilities, rules — written in MSFM.
+The human-readable spec. Frontmatter contains structured fields; the prose body is the behavioral spec — voice, personality, capabilities, rules — written in MSFM.
 
 ```yaml
 ---
@@ -250,15 +243,10 @@ description: Conversational agent that helps users manage their to-do list.
 Frontmatter fields:
 
 - `name` — agent display name
-- `model` — JSON string with `model` (MindStudio model ID), `temperature`, `maxResponseTokens`, and
-  optional `config` (model-specific settings like `reasoning`, `tools`, etc.). Ask `askMindStudioSdk`
-  for available model IDs and their config options — MindStudio's ids don't match vendor ids, so treat
-  any id in this document's examples as illustrative rather than current. The user's UI has a visual picker for changing it later, so only validate
-  the model when you're setting it; if the value changes afterwards, assume it's correct.
+- `model` — JSON string with `model` (MindStudio model ID), `temperature`, `maxResponseTokens`, and optional `config` (model-specific settings like `reasoning`, `tools`, etc.). Ask `askMindStudioSdk` for available model IDs and their config options — MindStudio's ids don't match vendor ids, so treat any id in this document's examples as illustrative rather than current. The user's UI has a visual picker for changing it later, so only validate the model when you're setting it; if the value changes afterwards, assume it's correct.
 - `description` — one-liner for agent card/listing
 
-The prose body contains sections like Voice & Personality, Capabilities, Behavior — whatever structure
-serves the agent's character. This is compiled into the system prompt and tool descriptions.
+The prose body contains sections like Voice & Personality, Capabilities, Behavior — whatever structure serves the agent's character. This is compiled into the system prompt and tool descriptions.
 
 ## Compiled Output: `dist/interfaces/agent/`
 
@@ -291,9 +279,7 @@ dist/interfaces/agent/
 }
 ```
 
-**The token-limit field is renamed during compilation.** The spec frontmatter calls it
-`maxResponseTokens`; the compiled `agent.json` calls it `maxTokens`. Same value, two names — carry it
-across rather than copying the key.
+**The token-limit field is renamed during compilation.** The spec frontmatter calls it `maxResponseTokens`; the compiled `agent.json` calls it `maxTokens`. Same value, two names — carry it across rather than copying the key.
 
 | Field | Description |
 |-------|-------------|
@@ -313,29 +299,17 @@ Declare it in `mindstudio.json`:
 
 ## Auth
 
-**Every agent config declares an `auth` block.** Agent chat spends the owner's money on every
-message without necessarily touching a backend method, so the platform gates the lobby itself —
-enforced at thread creation and message send:
+**Every agent config declares an `auth` block.** Agent chat spends the owner's money on every message without necessarily touching a backend method, so the platform gates the lobby itself — enforced at thread creation and message send:
 
 ```json
 "auth": { "requireUser": true, "requireRole": ["support-agent", "admin"] }
 ```
 
-- `requireUser: true` — only authenticated app users may chat; `false` — anyone, including
-  anonymous visitors. Most apps want `true`; choose `false` deliberately (a public concierge).
-- `requireRole` (optional) — the user must hold **at least one** of the listed manifest role ids
-  (OR semantics, same as the backend `auth.requireRole(...)`). Omit or leave empty for no role
-  gate. Requires `requireUser: true`. Unknown role ids fail the build.
-- Denials surface to the frontend SDK as `MindStudioInterfaceError` with code `auth_required`
-  (401) or `role_required` (403).
+- `requireUser: true` — only authenticated app users may chat; `false` — anyone, including anonymous visitors. Most apps want `true`; choose `false` deliberately (a public concierge).
+- `requireRole` (optional) — the user must hold **at least one** of the listed manifest role ids (OR semantics, same as the backend `auth.requireRole(...)`). Omit or leave empty for no role gate. Requires `requireUser: true`. Unknown role ids fail the build.
+- Denials surface to the frontend SDK as `MindStudioInterfaceError` with code `auth_required` (401) or `role_required` (403).
 - Dev preview is exempt — the builder is never locked out while testing.
-- Older compiled apps without the block fall back to the manifest's `auth.enabled` (auth-enabled →
-  users only; no auth → public). New configs always declare it explicitly.
-
-Once inside, agent chat runs as the **authenticated user**, not as a system role — tool calls
-carry that user's roles, so a method gated with `auth.requireRole` behaves exactly as it would if
-the user had called it from the web frontend. That's what makes exposing real methods safe; it's
-also why role restrictions belong in the tool descriptions, so the agent can decline gracefully
-instead of surfacing a rejection. Anonymous visitors (when allowed) are scoped by a per-browser
-visitor identity: their threads are private to their browser, and gated methods still reject.
+- Older compiled apps without the block fall back to the manifest's `auth.enabled` (auth-enabled → users only; no auth → public). New configs always declare it explicitly.
+
+Once inside, agent chat runs as the **authenticated user**, not as a system role — tool calls carry that user's roles, so a method gated with `auth.requireRole` behaves exactly as it would if the user had called it from the web frontend. That's what makes exposing real methods safe; it's also why role restrictions belong in the tool descriptions, so the agent can decline gracefully instead of surfacing a rejection. Anonymous visitors (when allowed) are scoped by a per-browser visitor identity: their threads are private to their browser, and gated methods still reject.
 

package/dist/prompt/skills/auth.md

@@ -390,13 +390,7 @@ Roles are declared in the manifest, stored as an array column on the user table,
 
 ## Interface-Level Auth (Agent + Voice)
 
-Agent and voice interfaces additionally declare auth **in their config** (a required `auth` key:
-`{ "requireUser": boolean, "requireRole"?: string[] }`) because those sessions spend money without
-necessarily calling a backend method — the platform gates the lobby itself, before any model or
-media spend. `requireRole` uses the same manifest role ids with OR semantics. Denials reach the
-frontend SDK as `MindStudioInterfaceError` codes `auth_required` (401) and `role_required` (403) —
-route them to the app's login flow. See the `agentInterfaces` / `voiceInterfaces` skills for the
-full contract. Method-level `auth.requireRole(...)` checks still apply to every tool call inside.
+Agent and voice interfaces additionally declare auth **in their config** (a required `auth` key: `{ "requireUser": boolean, "requireRole"?: string[] }`) because those sessions spend money without necessarily calling a backend method — the platform gates the lobby itself, before any model or media spend. `requireRole` uses the same manifest role ids with OR semantics. Denials reach the frontend SDK as `MindStudioInterfaceError` codes `auth_required` (401) and `role_required` (403) — route them to the app's login flow. See the `agentInterfaces` / `voiceInterfaces` skills for the full contract. Method-level `auth.requireRole(...)` checks still apply to every tool call inside.
 
 ## Apps Without Auth