@mindstudio-ai/remy 0.1.257 → 0.1.259

package/dist/prompt/skills/agentInterfaces.md

@@ -1,7 +1,7 @@
 ---
 name: Agent Interfaces
-what: Conversational AI as a first-class interface to the app — an LLM with authenticated, per-user access to the app's methods as tools, paired with a streaming chat UI. The platform handles auth, tool dispatch, threads, and streaming, so the work is authorship: who the agent is, which methods it can reach, and how each one is described to it. Any app whose methods do something interesting can be projected into a conversation this way, often as its most compelling surface. This reference covers both halves — writing the agent spec, and building the chat frontend with the SDK's `createAgentChatClient()`.
-when: Before authoring `src/interfaces/agent.md`, compiling `dist/interfaces/agent/`, or building an agent's chat UI. The `<interfaces>` platform doc has the wiring; this is how to author one well.
+what: Conversational AI as a first-class interface to the app — an LLM with authenticated, per-user access to the app's methods as tools, paired with a streaming chat UI. The platform handles auth, tool dispatch, threads, and streaming, so the work is authorship: who the agent is, which methods it can reach, and how each one is described to it. Any app whose methods do something interesting can be projected into a conversation this way, often as its most compelling surface. This reference covers the whole feature — writing the agent spec, compiling it, and building the chat frontend.
+when: Before authoring `src/interfaces/agent.md`, compiling `dist/interfaces/agent/`, or building an agent's chat UI.
 ---
 
 # Building Agent Interfaces
@@ -81,6 +81,8 @@ When building the `dist/interfaces/agent/`, consider the agent spec, as well as
 
 **`agent.json`** — ties it together. Model config from frontmatter, paths to system prompt and tool files, optional `webInterfacePath`.
 
+The exact shape of all three, and of the spec frontmatter they compile from, is in "The wiring" at the end of this document.
+
 ## Chat UI Design
 
 When the agent has a web frontend (via `webInterfacePath`), the chat UI is a page within the web interface.
@@ -203,3 +205,90 @@ The chat UI uses the app's design system — colors, typography, voice from `@br
 
 - Avoid designs that look like dated messaging apps from 2015
 - Avoid robotic empty states ("Hello! I'm your AI assistant. How can I help you today?")
+
+---
+
+# The wiring
+
+## 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.
+
+```yaml
+---
+name: Todo Assistant
+model: {"model": "claude-4-5-haiku", "temperature": 0.5, "maxResponseTokens": 16000}
+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.
+- `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.
+
+## Compiled Output: `dist/interfaces/agent/`
+
+```
+dist/interfaces/agent/
+├── agent.json          ← config the platform reads
+├── system.md           ← compiled system prompt
+└── tools/
+    ├── createTodo.md   ← rich tool description per method
+    ├── listTodos.md
+    └── ...
+```
+
+## Config (`agent.json`)
+
+```json
+{
+  "agent": {
+    "model": "claude-4-5-haiku",
+    "temperature": 0.5,
+    "maxTokens": 16000,
+    "systemPrompt": "system.md",
+    "tools": [
+      { "method": "create-todo", "description": "tools/createTodo.md" },
+      { "method": "list-todos", "description": "tools/listTodos.md" }
+    ],
+    "webInterfacePath": "/chat"
+  }
+}
+```
+
+**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 |
+|-------|-------------|
+| `model` | MindStudio model ID. Comes from the spec frontmatter; look it up with `askMindStudioSdk` rather than guessing |
+| `temperature` | Model temperature |
+| `maxTokens` | Max response tokens (the spec's `maxResponseTokens`) |
+| `systemPrompt` | Relative path to the compiled system prompt markdown file |
+| `tools` | Array of tool entries — `method` references a method `id` from the manifest, `description` is a relative path to a markdown file with rich tool docs (when to use, examples, edge cases, parameter guidance) |
+| `webInterfacePath` | Optional. If the app has a web interface with a chat page, this path tells the IDE where to show the preview. Otherwise the agent is accessed via API. |
+
+Declare it in `mindstudio.json`:
+
+```json
+{ "type": "agent", "path": "dist/interfaces/agent/agent.json" }
+```
+
+## Auth
+
+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.
+

package/dist/prompt/skills/inboundEmail.md

@@ -0,0 +1,116 @@
+---
+name: Inbound Email
+what: The app has its own email address, and mail sent to it runs a method. Every address on the app's subdomain routes to one handler, so `support@`, `receipts@` and `anything@` all arrive without registering anything — branch on the recipient in code. Attachments arrive as CDN URLs the platform has already uploaded, threading headers come through intact so replies land in the same conversation, and a verified custom domain both receives and sends under the app's own brand. "Forward a receipt and the app files it" is a real feature that costs one method.
+when: Before writing an email-handler method, adding an `email` interface, or promising anything about what happens when a user emails the app.
+---
+
+# Inbound Email Interfaces
+
+Inbound email triggers. Each app has **one** email-handler method; the platform routes all inbound
+mail destined for the app — across any of its address tiers — to that method.
+
+The addresses themselves are configured at the project level by the user through the Remy platform.
+Your job is the `interface.json` and the method that handles the mail, not domain registration or MX
+records.
+
+## Address tiers
+
+Three tiers, all delivered to the same handler method. The new tiers are catchall (no localpart
+registration); the legacy tier is specific-localpart and frozen for new apps.
+
+| Tier | Address | How it's set up |
+|---|---|---|
+| Platform subdomain (default) | `*@<custom_subdomain>.madewithremy.com` | Automatic the moment the app has a `custom_subdomain` set. Every address on that subdomain delivers to the handler. |
+| Custom domain | `*@<their-domain>` | The user adds a domain in the dashboard's email-domains settings and points one MX record at `mx.msagent.ai`. Not something the agent provisions. |
+| Legacy `mindstudio-hooks.com` | `<name>@mindstudio-hooks.com` | Existing apps only — frozen for new apps. Don't recommend it; treat as read-only history. |
+
+Because the new tiers are catchall, `to` carries an arbitrary localpart. Methods that need to branch on
+it should read `input.to` (e.g. `if (input.to.startsWith('support@')) ...`). This is what makes
+per-purpose addresses free: you don't register `support@` anywhere, you just check for it.
+
+A verified custom domain (and the app's `madewithremy.com` subdomain) also **sends** outbound mail, not
+just receives — `sendEmail` picks the app's own-brand sender automatically, configured in the
+dashboard's **Email** settings.
+
+## Config (`interface.json`)
+
+The top-level key must match the interface type (`email`):
+
+```json
+{
+  "email": {
+    "method": "handle-inbound-email",
+    "approvedSenders": ["billing@vendor.com", "*@trusted-partner.com"]
+  }
+}
+```
+
+`approvedSenders` is optional. When set, only senders matching an exact address or `*@domain.com`
+wildcard reach the method; everything else is rejected by the platform with `400 invalid_sender` before
+the method runs (silently — the sender isn't bounced). Matching is case-insensitive. The same list
+applies uniformly across all three address tiers.
+
+Declare it in `mindstudio.json`:
+
+```json
+{ "type": "email", "path": "dist/interfaces/email/interface.json" }
+```
+
+## Input shape
+
+```ts
+{
+  to: string;               // full recipient address; localpart is arbitrary on catchall tiers
+  from: string;             // bare sender address, extracted from "Name <a@b>" form
+  fromName: string | null;  // sender display name, or null
+  subject: string;          // 'No Subject' if missing
+  message: string;          // plain-text body, falls back to HTML if text is missing; 'No Body' if neither was sent
+  html: string;             // HTML body, or '' when text-only
+  attachments: string[];    // CDN URLs — already uploaded by the platform
+  messageId: string | null; // this email's Message-ID, angle-bracketed (<id@host>)
+  inReplyTo: string | null; // Message-ID this email is replying to, if any
+  references: string[];     // prior Message-IDs in the thread (angle-bracketed); [] if none
+  replyTo: string | null;   // Reply-To address — reply here, not `from`, when set
+  cc: string[];             // Cc recipient addresses
+  date: string | null;      // original send time, ISO-8601
+}
+```
+
+## Replying in thread
+
+Replies go out through the SDK's `sendEmail` action (its full parameter list is in the SDK actions
+reference in your system prompt). Set `inReplyTo` to the incoming `messageId` and `references` to
+`[...references, messageId]`. Send to `replyTo` when it's set, otherwise `from`.
+
+```typescript
+await mindstudio.sendEmail({
+  to: input.replyTo ?? input.from,
+  subject: `Re: ${input.subject}`,
+  body: reply,
+  inReplyTo: input.messageId ?? undefined,
+  references: input.messageId
+    ? [...input.references, input.messageId]
+    : input.references,
+  cc: input.cc, // reply-all
+});
+```
+
+`sendEmail` returns `{ recipients, cc, bcc, from }` — who it sent to and the sender used. It does
+**not** return the sent message's own `Message-ID`, so thread off *inbound* mail, never off messages
+you sent.
+
+## Attachments and size limits
+
+`attachments[]` is an array of CDN URLs — the platform has already received and uploaded the files.
+Fetch them server-side via the URL when you need the bytes; pass them through as URLs to UI or
+downstream services.
+
+Max inbound message size is 25 MB total (including all attachments). Oversized messages are rejected by
+the platform before the method runs.
+
+## Auth
+
+Methods invoked through this interface run with `auth.roles: ['system']` — the platform is calling, not
+a user session, so there's no user to impersonate. Use `auth.requireRole('system')` to gate methods that
+should only be reachable via email. The auth reference in your system prompt covers the system role in
+full.

package/dist/prompt/skills/mcpInterfaces.md

@@ -1,16 +1,35 @@
 ---
 name: MCP Interfaces
 what: Ships the app as an MCP server, so external AI agents — Claude Desktop, Cursor, anyone's agent — can drive it as a tool surface. The platform hosts the server, handles auth, and derives every tool's input schema from the method contract, so there is no protocol code to write: the work is choosing which methods an outsider should see and describing them well enough for a stranger to use correctly. Cheap to add to an app that already has methods, and it puts the app inside the tools its users already work in.
-when: Before authoring `src/interfaces/mcp.md` or deciding which of the app's methods an external agent gets to see.
+when: Before authoring `src/interfaces/mcp.md`, deciding which of the app's methods an external agent gets to see, or writing the MCP interface config.
 ---
 
-# Building MCP Interfaces
+# MCP Interfaces
 
-Guidance for exposing an app as an MCP server — a tool / resource / prompt surface for *external* AI agents (Claude Desktop, Cursor, anyone's agent). The contract (spec format, compiled output, `interface.json`) is in the `<interfaces>` platform doc in your system prompt; this is how to author one well. Unlike the agent interface, there's no LLM, personality, or UI to design — the entire product is the descriptions and the shape of what you expose.
+Exposing an app as an MCP server — a tool / resource / prompt surface for *external* AI agents (Claude
+Desktop, Cursor, anyone's agent). Unlike the agent interface, which *is* an agent with its own LLM,
+personality and chat UI, MCP has no model of its own: it's the app projected as a server for an outside
+AI to drive.
+
+It supports the full MCP surface:
+
+- **Tools** — methods the agent can call (rich descriptions + machine-readable annotations).
+- **Resources** — read-only app data the agent can pull into context, addressable by URI.
+- **Prompts** — reusable, parameterized prompt templates the server offers.
+- **Instructions** — server-level guidance shown to the calling agent (the toolset's "system prompt").
+
+The platform hosts the server, handles auth, and derives every tool's input schema from the method
+contract. So there's no protocol code to write, and the whole job is authorship plus a config file.
+Authorship first, since that's what decides whether the toolset actually works.
 
 ## The descriptions are the product
 
-The calling agent is a stranger with no knowledge of your app. It decides what to invoke entirely from the names, descriptions, and annotations you ship. Follow the same principles as the agent interface's tool descriptions (load the `agentInterfaces` skill for those — when to use and when not, parameter guidance beyond the schema, what the tool returns) — but write them **self-contained**. An in-app agent tool can lean on the app's framing; an MCP tool can't, because the caller has no context. Spell out what an outsider wouldn't know.
+The calling agent is a stranger with no knowledge of your app. It decides what to invoke entirely from
+the names, descriptions, and annotations you ship. Follow the same principles as the agent interface's
+tool descriptions (load the `agentInterfaces` skill for those — when to use and when not, parameter
+guidance beyond the schema, what the tool returns) — but write them **self-contained**. An in-app agent
+tool can lean on the app's framing; an MCP tool can't, because the caller has no context. Spell out what
+an outsider wouldn't know.
 
 What that looks like in practice — the same method, described twice:
 
@@ -28,46 +47,69 @@ full updated vendor. Editors and admins only; other roles are rejected. For a
 vendor that doesn't exist yet, use `createVendor`.
 ```
 
-The weak one is what a schema already tells the caller. The strong one carries the three things a schema can't: the prerequisite, the partial-update semantics, and the alternative when this isn't the right tool.
+The weak one is what a schema already tells the caller. The strong one carries the three things a schema
+can't: the prerequisite, the partial-update semantics, and the alternative when this isn't the right
+tool.
 
 ## Curate — not every method is a tool
 
-Expose what an outside agent would actually use. Skip internal helpers, admin-only methods, and batch operations. A focused set of well-described tools beats a large set of thin ones. Note role restrictions in the description — gated tools are listed but reject unauthorized calls at runtime, so set expectations rather than surfacing a raw error.
+Expose what an outside agent would actually use. Skip internal helpers, admin-only methods, and batch
+operations. A focused set of well-described tools beats a large set of thin ones. Note role restrictions
+in the description — gated tools are listed but reject unauthorized calls at runtime, so set
+expectations rather than surfacing a raw error.
 
 ## Annotations
 
-Annotations are machine-readable hints clients use to decide whether to auto-call a tool or ask the user first. Set them honestly:
+Annotations are machine-readable hints clients use to decide whether to auto-call a tool or ask the user
+first. Set them honestly:
 
-- `readOnly` — the tool only reads, never mutates. The highest-value hint: clients auto-call reads without prompting, so set it on every pure read.
+- `readOnly` — the tool only reads, never mutates. The highest-value hint: clients auto-call reads
+  without prompting, so set it on every pure read.
 - `destructive` — the tool can delete or overwrite. Clients gate these behind confirmation.
 - `idempotent` — calling twice with the same arguments has the same effect as calling once.
-- `openWorld` — the tool reaches outside the app (external web/services) rather than operating only on app data.
+- `openWorld` — the tool reaches outside the app (external web/services) rather than operating only on
+  app data.
 
-The judgement is per tool, and getting `readOnly` right is what makes a toolset feel responsive rather than nagging:
+The judgement is per tool, and getting `readOnly` right is what makes a toolset feel responsive rather
+than nagging. Abbreviated to just the annotations (a real entry also carries `name`, `title` and
+`description` — the Config section has the full shape):
 
 ```jsonc
-"getVendor":            { "readOnly": true, "idempotent": true }
-"searchVendors":        { "readOnly": true, "idempotent": true }
-"updateVendor":         { "idempotent": true }   // repeatable, but it writes
-"deleteVendor":         { "destructive": true, "idempotent": true }
-"enrichVendorFromWeb":  { "openWorld": true }    // calls out to the internet
+"tools": [
+  { "method": "get-vendor",    "annotations": { "readOnly": true, "idempotent": true } },
+  { "method": "search-vendors", "annotations": { "readOnly": true, "idempotent": true } },
+  { "method": "update-vendor",  "annotations": { "idempotent": true } },                      // repeatable, but it writes
+  { "method": "delete-vendor",  "annotations": { "destructive": true, "idempotent": true } },
+  { "method": "enrich-vendor",  "annotations": { "openWorld": true } }                        // calls out to the internet
+]
 ```
 
-Set them honestly rather than defensively. Marking a read `destructive` to be safe means the caller's user gets a confirmation prompt for looking something up, and they will stop reading the prompts.
+Set them honestly rather than defensively. Marking a read `destructive` to be safe means the caller's
+user gets a confirmation prompt for looking something up, and they will stop reading the prompts.
 
 ## Tools vs. resources
 
-A **tool** is an action the agent *invokes*; a **resource** is data the agent *reads into context*. A read-only method can be either — expose it as a tool if the agent will call it as a step, as a resource if it's reference data the agent should pull in, and as both when both fit.
+A **tool** is an action the agent *invokes*; a **resource** is data the agent *reads into context*. A
+read-only method can be either — expose it as a tool if the agent will call it as a step, as a resource
+if it's reference data the agent should pull in, and as both when both fit.
 
-Resources are method-backed: a read invokes the method. Use a static `uri` for a fixed collection (`app://vendors`) and a `uriTemplate` when the read takes parameters (`app://vendors/{id}`, where `{id}` maps to the method's input). Keep URIs stable and human-legible.
+Resources are method-backed: a read invokes the method. Use a static `uri` for a fixed collection
+(`app://vendors`) and a `uriTemplate` when the read takes parameters (`app://vendors/{id}`, where `{id}`
+maps to the method's input). Keep URIs stable and human-legible.
 
 ## Prompts
 
-Prompts are reusable, parameterized templates the server offers to clients — e.g. a "draft a vendor email" starter. Author the template body with `{{arg}}` placeholders and declare its arguments. Offer a prompt when there's a recurring task worth packaging; skip it if a tool already covers the need.
+Prompts are reusable, parameterized templates the server offers to clients — e.g. a "draft a vendor
+email" starter. Author the template body with `{{arg}}` placeholders and declare its arguments. Offer a
+prompt when there's a recurring task worth packaging; skip it if a tool already covers the need.
 
 ## Server instructions
 
-The spec's intro prose becomes the server `instructions` — toolset-level guidance returned to the calling agent at connect time (its "system prompt"). Put *cross-cutting* guidance here: how the tools fit together, ordering or prerequisites ("read a vendor before updating it"), and norms that apply across the whole toolset. Keep per-tool specifics in the tool descriptions; instructions are for the toolset as a whole.
+The spec's intro prose becomes the server `instructions` — toolset-level guidance returned to the
+calling agent at connect time (its "system prompt"). Put *cross-cutting* guidance here: how the tools
+fit together, ordering or prerequisites ("read a vendor before updating it"), and norms that apply
+across the whole toolset. Keep per-tool specifics in the tool descriptions; instructions are for the
+toolset as a whole.
 
 ```markdown
 This server exposes a procurement app. Vendors are the central record and
@@ -77,4 +119,162 @@ search tool before calling anything that takes one. Search results are capped
 at 50; page with the returned cursor rather than broadening the query.
 ```
 
-That's four sentences doing what no individual tool description could: it explains the shape of the domain, so the calling agent's first move is a reasonable one.
+That's four sentences doing what no individual tool description could: it explains the shape of the
+domain, so the calling agent's first move is a reasonable one.
+
+---
+
+# The wiring
+
+## Spec: `src/interfaces/mcp.md`
+
+Frontmatter declares the server. In the body, the intro prose becomes the server `instructions`, and
+`## Tools`, `## Resources` and `## Prompts` headings declare the rest.
+
+```yaml
+---
+name: Vendor Management
+description: Tools and data for managing vendors and purchase orders.
+type: interface/mcp
+---
+```
+
+```markdown
+This server manages vendors and purchase orders. Read a vendor before updating it; submitted
+requests go through approval before they become active.
+
+## Tools
+
+### Submit a vendor request
+method: submit-vendor-request
+~~~
+Submit a new vendor for approval. Use when the caller wants to add a vendor.
+Do NOT use to modify an existing vendor — that's update-vendor.
+- name: the vendor's legal name
+- contactEmail: billing contact; required for approval routing
+Returns the created vendor's id and its initial "pending" status.
+~~~
+
+### List vendors
+method: list-vendors
+annotations: readOnly
+~~~
+List all vendors, newest first. Read-only.
+~~~
+
+## Resources
+
+- list-vendors → app://vendors — "Vendors" — all vendors (application/json)
+- get-vendor → app://vendors/{id} — "Vendor" — a single vendor by id (application/json)
+
+## Prompts
+
+### draft_vendor_email
+description: Draft an outreach email to a vendor.
+arguments: vendorId (required) — the vendor to contact
+~~~
+Write a warm outreach email to vendor {{vendorId}} introducing our procurement process.
+~~~
+```
+
+Don't hand-author input schemas — the platform derives them.
+
+## Compiled Output: `dist/interfaces/mcp/`
+
+```
+dist/interfaces/mcp/
+├── interface.json      ← config the platform reads
+├── instructions.md     ← server-level guidance (returned in `initialize`)
+├── tools/
+│   ├── submitVendorRequest.md   ← rich description, one per tool
+│   └── listVendors.md
+└── prompts/
+    └── draftVendorEmail.md      ← prompt template body, one per prompt
+```
+
+Resources carry inline metadata only — no per-resource file.
+
+## Config (`interface.json`)
+
+The top-level key must match the interface type (`mcp`):
+
+```json
+{
+  "mcp": {
+    "name": "Vendor Management",
+    "description": "Tools and data for managing vendors and purchase orders.",
+    "instructions": "instructions.md",
+    "tools": [
+      {
+        "method": "submit-vendor-request",
+        "name": "submit_vendor_request",
+        "title": "Submit Vendor Request",
+        "description": "tools/submitVendorRequest.md",
+        "annotations": { "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false }
+      },
+      {
+        "method": "list-vendors",
+        "title": "List Vendors",
+        "description": "tools/listVendors.md",
+        "annotations": { "readOnly": true }
+      }
+    ],
+    "resources": [
+      { "method": "list-vendors", "uri": "app://vendors", "name": "Vendors", "description": "All vendors.", "mimeType": "application/json" },
+      { "method": "get-vendor", "uriTemplate": "app://vendors/{id}", "name": "Vendor", "description": "A single vendor by id.", "mimeType": "application/json" }
+    ],
+    "prompts": [
+      {
+        "name": "draft_vendor_email",
+        "title": "Draft vendor email",
+        "description": "Draft an outreach email to a vendor.",
+        "arguments": [ { "name": "vendorId", "description": "The vendor to contact", "required": true } ],
+        "template": "prompts/draftVendorEmail.md"
+      }
+    ]
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name`, `description` | Server display name + registry metadata (not shown to the calling agent) |
+| `instructions` | Relative path to the server-level guidance returned in `initialize` |
+| `tools[].method` | Method `id` from the manifest (kebab-case) |
+| `tools[].name` | Tool name exposed to clients. Optional — defaults to the method `id`. Must match `[a-zA-Z0-9_-]` and be unique within the server |
+| `tools[].title` | Optional human-friendly display name |
+| `tools[].description` | Relative path to the tool's markdown description |
+| `tools[].annotations` | The client hints from the Annotations section: `readOnly`, `destructive`, `idempotent`, `openWorld` — they map to MCP's `readOnlyHint` etc. |
+| `resources[].method` | The read method invoked when the resource is read |
+| `resources[].uri` / `uriTemplate` | A static URI, or a template whose `{param}` maps to the method's input |
+| `resources[].name`, `description`, `mimeType` | Resource metadata |
+| `prompts[].name`, `title`, `description` | Prompt identity + metadata |
+| `prompts[].arguments` | `[{ name, description?, required? }]` |
+| `prompts[].template` | Relative path to the template body (`{{arg}}` placeholders) |
+
+There is no `inputSchema` field — the platform derives each tool's schema from the method's input
+contract.
+
+Declare it in `mindstudio.json`:
+
+```json
+{ "type": "mcp", "path": "dist/interfaces/mcp/interface.json" }
+```
+
+## Platform Behavior
+
+- The platform hosts the MCP server and exposes it to external clients. Clients connect at
+  `POST https://{app-host}/_/mcp`, where `{app-host}` is any host the app is served on: its
+  `custom_subdomain` host (e.g. `myapp.madewithremy.com`), a custom domain if configured, or the UUID
+  host (`<appId>.madewithremy.com` / `.msagent.ai`).
+- **Auth is optional.** A `Bearer` key resolves to a user with full RBAC, so the method's own
+  `auth.requireRole`/`requireUser` checks apply as they would for that user. With no key, calls run
+  anonymously — no user, no roles. The method is the boundary: gate sensitive tools, and understand that
+  a public (keyless) server effectively exposes only the un-gated ones.
+- Input schemas are derived automatically from each method's input contract.
+- `tools/list` is static; access is enforced per-method at call time (a gated tool is listed but rejects
+  an unauthorized call).
+- A resource read invokes the backing method (template `{param}`s come from the URI) and returns its
+  output as the resource contents.
+- `prompts/get` fills the template with the provided arguments.
+- `instructions` is returned in the `initialize` response.

package/dist/prompt/skills/restApi.md

@@ -0,0 +1,149 @@
+---
+name: REST API
+what: A designed, documented REST surface over the app's methods — named routes, path and query params, resource groupings, and a generated OpenAPI spec. This is distinct from the method endpoints every app already has: those exist automatically and need nothing from you. This is for when the API itself is the product, or when something outside the app has to integrate against stable URLs rather than internal method names.
+when: Before authoring `src/interfaces/api.md` or adding an `api` interface with designed routes. Also load it when a method needs the raw HTTP request (headers, unparsed body).
+---
+
+# REST API Interfaces
+
+REST endpoints for external consumers — other services, mobile apps, integrations. This is separate
+from the web frontend's internal RPC (`@mindstudio-ai/interface` calls `/_/methods` directly and does
+not use the API interface). The API interface lives at `/_/api/` and exposes only the methods you
+choose to route.
+
+Use it for sync endpoints for other services, a public REST API, batch tools — anything where
+something outside the app's own frontend needs to call a method over HTTP.
+
+**For provider webhooks (Stripe, GitHub, Shopify) there are two native paths**, and they are easy to
+confuse. This interface handles them with bearer auth and `input._request.rawBody`. The Webhook
+interface handles them with secret-in-URL routing and a top-level `input.rawBody` — usually the better
+fit for provider callbacks, since providers can't send a bearer token. Load the `webhooks` skill before
+choosing.
+
+## Spec: `src/interfaces/api.md`
+
+The human-readable spec. Frontmatter declares the API name and description; the body maps methods to
+REST routes using MSFM.
+
+```yaml
+---
+name: Vendor Management API
+description: API for managing vendors and purchase orders.
+type: interface/api
+---
+```
+
+Routes are declared as `VERB /path → methodExportName` under resource headings, with annotations for
+params and descriptions:
+
+```markdown
+## Vendors
+
+### List vendors
+GET /vendors → listVendors
+~~~
+Returns all vendors, optionally filtered by status.
+query: status (string, optional) — filter by vendor status
+~~~
+
+### Create vendor
+POST /vendors → submitVendorRequest
+~~~
+Submit a new vendor for approval.
+body: name (string, required) — vendor name
+      contactEmail (string, required) — billing contact
+~~~
+
+### Delete vendor
+DELETE /vendors/:vendorId → deleteVendor
+~~~
+path: vendorId (string, required) — the vendor's unique identifier
+~~~
+```
+
+## Compiled Output: `dist/interfaces/api/api.json`
+
+```json
+{
+  "api": {
+    "name": "Vendor Management API",
+    "description": "API for managing vendors and purchase orders.",
+    "routes": [
+      {
+        "method": "GET",
+        "path": "/vendors",
+        "handler": "list-vendors",
+        "summary": "List vendors",
+        "description": "Returns all vendors, optionally filtered by status.",
+        "tag": "Vendors",
+        "params": {
+          "query": {
+            "status": { "type": "string", "required": false, "description": "Filter by vendor status" }
+          }
+        }
+      },
+      {
+        "method": "POST",
+        "path": "/vendors",
+        "handler": "submit-vendor-request",
+        "summary": "Create vendor",
+        "description": "Submit a new vendor for approval.",
+        "tag": "Vendors",
+        "params": {
+          "body": {
+            "name": { "type": "string", "required": true, "description": "Vendor name" },
+            "contactEmail": { "type": "string", "required": true, "description": "Billing contact" }
+          }
+        }
+      },
+      {
+        "method": "DELETE",
+        "path": "/vendors/:vendorId",
+        "handler": "delete-vendor",
+        "summary": "Delete vendor",
+        "description": "Permanently remove a vendor.",
+        "tag": "Vendors",
+        "params": {
+          "path": {
+            "vendorId": { "type": "string", "required": true, "description": "The vendor's unique identifier" }
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name` | API display name (used in generated OpenAPI spec) |
+| `description` | API description |
+| `routes[].method` | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
+| `routes[].path` | URL path with `:param` placeholders for path params |
+| `routes[].handler` | Method `id` from the manifest (kebab-case) |
+| `routes[].summary` | Short description for the endpoint |
+| `routes[].description` | Longer description |
+| `routes[].tag` | Resource grouping (becomes a tag in OpenAPI) |
+| `routes[].params` | Parameter declarations: `path`, `query`, and/or `body` objects |
+
+Declare it in `mindstudio.json`:
+
+```json
+{ "type": "api", "path": "dist/interfaces/api/api.json" }
+```
+
+## Platform Behavior
+
+Routes are mounted at `/_/api{path}` (e.g. `DELETE /_/api/vendors/abc123`).
+
+- **Path params** are extracted and merged into the method's input: `/:vendorId` → `{ vendorId: "abc123" }`
+- **Query params** are merged into input for GET requests: `?status=approved` → `{ status: "approved" }`
+- **Request body** for POST/PUT/PATCH is the input directly (no `{ input: {...} }` wrapper)
+- **Response** is the method output directly (no `{ output: {...} }` wrapper)
+- **Auth** via `Authorization: Bearer sk_...` — an API key resolves to a user with full RBAC, so the
+  method's own `auth.requireRole`/`requireUser` checks apply exactly as they would for that user
+- **Streaming**: `Accept: text/event-stream` header returns SSE chunks
+- **Raw request context**: Every API method receives `input._request` with `{ method, headers, rawBody }`.
+  `rawBody` is the original unparsed body as a UTF-8 string — needed for signature verification, since
+  providers HMAC the raw payload and a re-serialized body won't match. For most methods you don't need
+  `_request` at all.