@mindstudio-ai/remy 0.1.256 → 0.1.258

package/dist/prompt/skills/mcpInterfaces.md

@@ -0,0 +1,280 @@
+---
+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`, deciding which of the app's methods an external agent gets to see, or writing the MCP interface config.
+---
+
+# MCP Interfaces
+
+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.
+
+What that looks like in practice — the same method, described twice:
+
+```markdown
+<!-- Weak: restates the schema, assumes the caller knows the app -->
+Updates a vendor. Takes a vendorId and the fields to change.
+```
+
+```markdown
+<!-- Strong: says when to call it, what an outsider can't infer, what comes back -->
+Update an existing vendor's details. Call `listVendors` or `getVendor` first —
+vendorId is the app's internal id, not a name, and there is no lookup by name.
+Only the fields you pass are changed; omitted fields are left alone. Returns the
+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.
+
+## 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.
+
+## Annotations
+
+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.
+- `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.
+
+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
+"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.
+
+## 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.
+
+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.
+
+## 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.
+
+```markdown
+This server exposes a procurement app. Vendors are the central record and
+purchase orders reference them, so a vendor generally has to exist before
+anything else is useful. Ids are internal — resolve a name to an id with a
+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.
+
+---
+
+# 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.

package/dist/prompt/skills/scheduledJobs.md

@@ -0,0 +1,51 @@
+---
+name: Scheduled Jobs
+what: Methods that run on a schedule, declared as cron expressions in an interface config and synced to the platform on deploy. Nothing to host and no scheduler to run — a job is a method plus a schedule line.
+when: Before adding a `cron` interface or writing a method meant to run on a timer.
+---
+
+# Cron Interfaces
+
+Scheduled method execution.
+
+## Config (`interface.json`)
+
+The top-level key must match the interface type (`cron`):
+
+```json
+{
+  "cron": {
+    "jobs": [
+      {
+        "schedule": "0 9 * * 5",
+        "method": "process-weekly-payments",
+        "description": "Process approved invoices every Friday at 9am"
+      },
+      {
+        "schedule": "*/30 * * * *",
+        "method": "sync-vendor-status",
+        "description": "Sync vendor statuses every 30 minutes"
+      }
+    ]
+  }
+}
+```
+
+Standard cron expression format. `method` is the id of a method in `methods[]`. Jobs are synced to the
+platform on deploy.
+
+Declare it in `mindstudio.json`:
+
+```json
+{ "type": "cron", "path": "dist/interfaces/cron/interface.json" }
+```
+
+## 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 on a schedule. The auth reference in your system prompt covers the system role
+in full.
+
+A scheduled job that needs to act on user data acts as the system, not as any user, so it reaches
+everything. Scope what it touches in the method itself rather than relying on role checks to narrow it.

package/dist/prompt/{compiled/task-agents.md → skills/taskAgents.md}

@@ -1,3 +1,9 @@
+---
+name: Task Agents
+what: A full autonomous agent loop callable from any method. Give it a prompt, a set of tools, and an example of the output shape; the platform runs the model until it produces that shape — searching, scraping, generating images, retrying approaches that failed, and calling your app's own methods to read and write data as it goes. Tools can be any of the 1000+ SDK actions and your own methods in any combination, which is what makes it part of the app rather than a detached research bot. This is the difference between a feature that saves what the user typed and one that researches, enriches, and creates on their behalf, and it is one of the most powerful things the platform can do. Consider it whenever a feature would be dramatically more compelling if the app could do real work autonomously.
+when: Before writing any `mindstudio.runTask()` call — background enrichment, research-and-generate, anything where the model decides its own next step.
+---
+
 # Task Agents (`mindstudio.runTask`)
 
 A user types the name of a restaurant into your app, or uploads a photo of a storefront. The API call returns early, and in the background, a task agent searches Google, finds the official website, scrapes the address, gets the official social media accounts, and generates a stylized watercolor postcard of the exterior from images it found online. The user gets back a rich, illustrated card with the canonical name, website, address, and a custom image. A few tool calls (some in parallel), fully autonomous.
@@ -6,7 +12,7 @@ A user types the name of a restaurant into your app, or uploads a photo of a sto
 
 Tools are **SDK actions** (`searchGoogle`, `generateImage`, …) and **your own app's methods** (`{ appMethod: 'saveVendor' }`), in any combination. That second half is what makes a task agent part of your app rather than a detached research bot: it can read your tables to decide what to do next, and write results back itself instead of handing them to you to persist.
 
-This is one of the most powerful pieces of the MindStudio SDK and can make turn apps from amazing into truly magical. Use `askMindStudioSdk` to help construct the perfect agent for a task.
+This is one of the most powerful pieces of the MindStudio SDK, and it can turn an app from amazing into truly magical. Use `askMindStudioSdk` to help construct the right agent for a task — including which model to give it.
 
 ## When to Use
 
@@ -62,7 +68,7 @@ const result = await mindstudio.runTask<{
     photoUrl: 'https://cdn.mindstudio.ai/...',
   },
 
-  model: 'claude-5-sonnet',
+  model: 'claude-5-sonnet',   // ask askMindStudioSdk — don't copy this one blind
   maxTurns: 15,
 });
 
@@ -136,7 +142,7 @@ Keep them short and task-specific. Say when to reach for it and when not to, sin
 
 ## Voice & Tone in Prompts
 
-When a task agent produces user-facing text, the prompt must include a note voice and tone constraints. Make sure to specify no emojis, em dashes, and other "ai-isms" in the prompt, as well as the desired tone and voice of the output.
+When a task agent produces user-facing text, the prompt must state the voice and tone it should write in. Specify the desired voice explicitly, and rule out emojis, em dashes, and other "ai-isms" — the output goes straight to the user, so nothing downstream will catch them.
 
 ## Options
 
@@ -146,14 +152,10 @@ When a task agent produces user-facing text, the prompt must include a note voic
 | `input` | Yes | — | Structured input (passed as user message) |
 | `tools` | Yes | — | SDK action names and/or `{ appMethod, description }` entries, each with optional `defaults` |
 | `structuredOutputExample` | Yes | — | Object or JSON string showing expected output shape. Use realistic example values, not placeholders like `'string'` |
-| `model` | Yes | — | Model ID (must support tool use) |
+| `model` | Yes | — | Model ID (must support tool use). Ask `askMindStudioSdk` for the right one — MindStudio's ids don't match vendor ids, so a plausible-looking guess is usually wrong |
 | `maxTurns` | No | 20 | Max loop iterations (capped at 100) |
 | `onEvent` | No | — | SSE event callback for real-time streaming |
 
-## Models
-
-Use `askMindStudioSdk` for appropriate models given the task and its complexity.
-
 ## Return Value
 
 ```typescript

package/dist/prompt/skills/webhooks.md

@@ -0,0 +1,108 @@
+---
+name: Webhooks
+what: Inbound HTTP endpoints that run a method synchronously, routed by a secret in the URL rather than by an auth header — which is what makes them the right fit for provider callbacks from Stripe, GitHub, Shopify, Slack or Twilio, since those senders can't present a bearer token. Signature verification works natively off the raw request body.
+when: Before adding a `webhook` interface or writing a method that receives a provider callback. Also load it before reaching for any confirmation-token, polling, or proxy workaround for inbound HTTP — those aren't needed here.
+---
+
+# Webhook Interfaces
+
+Inbound HTTP endpoints that invoke a method directly and synchronously — the caller waits for the
+method to finish. Use for receiving webhooks from external services (Stripe, GitHub, Shopify, Slack,
+Twilio). Direct inbound webhooks with signature verification work natively; do **not** build
+confirmation-token or polling workarounds.
+
+The other native path for inbound HTTP is the API interface, which uses bearer auth and exposes the raw
+body at `input._request.rawBody` instead of at the top level. Use that one when the caller can send an
+`Authorization` header and you want a documented REST surface; use this one for provider callbacks.
+Load the `restApi` skill if that's the direction.
+
+Webhook secrets are configured at the project level by the user through the Remy platform. Your job is
+the `interface.json` and the handling method.
+
+## Config (`interface.json`)
+
+The top-level key must match the interface type (`webhook`):
+
+```json
+{
+  "webhook": {
+    "endpoints": [
+      {
+        "method": "handle-payment-webhook",
+        "secret": "whsec_pick_a_long_random_token",
+        "description": "Stripe events"
+      }
+    ]
+  }
+}
+```
+
+- `method` — the id of a method in `methods[]` to invoke.
+- `secret` — a developer-chosen opaque token that is **both the routing key and the access guard**. It
+  is stable across deploys (compilation is a passthrough — redeploying never rotates it), so a URL you
+  register with Stripe/GitHub stays valid. Generate one long random value per endpoint and keep it
+  constant.
+- Declare multiple endpoints if needed; each `secret` maps to one method.
+
+Declare it in `mindstudio.json`:
+
+```json
+{ "type": "webhook", "path": "dist/interfaces/webhook/interface.json" }
+```
+
+## Endpoint URL
+
+Register this with the external service:
+
+```
+https://{app-host}/_/webhook/{secret}
+```
+
+`{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`). All HTTP verbs are accepted.
+
+## Input
+
+The method receives:
+
+```ts
+{
+  method: string;                  // HTTP method
+  headers: Record<string, string>; // request headers
+  query: Record<string, string>;   // query params
+  body: any;                       // parsed JSON / form body
+  rawBody: string;                 // exact raw request bytes (UTF-8), pre-parse
+}
+```
+
+For signature verification **always use `rawBody`, never `body`** — providers (Stripe, GitHub, Shopify,
+Slack) HMAC the raw payload, and a re-serialized `body` will not match:
+
+```typescript
+const event = stripe.webhooks.constructEvent(
+  input.rawBody,
+  input.headers['stripe-signature'],
+  process.env.STRIPE_WEBHOOK_SECRET!,
+);
+```
+
+`rawBody` is populated for `application/json` and `application/x-www-form-urlencoded` bodies (what these
+providers send).
+
+## Response
+
+Whatever the method returns as output is sent back to the caller as JSON; if it returns no output, the
+platform responds `204`. A wrong/unknown secret returns `401`; an app with no live release returns
+`404`.
+
+## 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 a platform trigger. The auth reference in your system prompt covers the
+system role in full.
+
+Note that the URL secret is the only access control on the endpoint itself, which is why it needs to be
+long and random. Signature verification is a second, independent check that the payload really came from
+the provider — do both.

package/dist/prompt/static/authoring.md

@@ -19,7 +19,7 @@ The scaffold starts with these spec files that cover the full picture of the app
 - **`src/interfaces/@brand/voice.md`** — voice and terminology: tone, error messages, word choices
 - **`src/roadmap/`** — feature roadmap. One file per feature (`type: roadmap`). See "Roadmap" below.
 
-These are starting points, not constraints. Create as many spec files as the project needs — the `src/` folder is your workspace and every `.md` file in it becomes compilation context. If the app has substantial content (presentation slides, copy, lesson plans, menu items, quiz questions), put it in its own file (`src/content.md`, `src/slides.md`, `src/menu.md`, etc.) rather than cramming it into `app.md` or `web.md`. If the domain is complex, split `app.md` into multiple files by area (`src/billing.md`, `src/approvals.md`). Add interface specs for other interface types (`api.md`, `webhook.md`, `cron.md`, `agent.md`, etc.) if the app uses them. For external HTTP, the Webhook interface (`webhook.md`) handles inbound provider webhooks (Stripe, GitHub) via secret-in-URL routing, while the API interface (`api.md`) covers bearer-auth sync endpoints, public REST APIs, and batch tools. Organize however serves clarity — the platform reads the entire `src/` folder.
+These are starting points, not constraints. Create as many spec files as the project needs — the `src/` folder is your workspace and every `.md` file in it becomes compilation context. If the app has substantial content (presentation slides, copy, lesson plans, menu items, quiz questions), put it in its own file (`src/content.md`, `src/slides.md`, `src/menu.md`, etc.) rather than cramming it into `app.md` or `web.md`. If the domain is complex, split `app.md` into multiple files by area (`src/billing.md`, `src/approvals.md`). Add interface specs for other interface types (`api.md`, `webhook.md`, `cron.md`, `email.md`, `mcp.md`, `agent.md`) if the app uses them. Each of those has a skill carrying its spec format and config — `restApi`, `webhooks`, `scheduledJobs`, `inboundEmail`, `mcpInterfaces`, `agentInterfaces` — and you should load the relevant one before writing the spec rather than after, since the spec is what the config is compiled from. For external HTTP the choice is between two of them: the Webhook interface handles inbound provider webhooks (Stripe, GitHub) via secret-in-URL routing, while the API interface covers bearer-auth sync endpoints, public REST APIs, and batch tools. Organize however serves clarity — the platform reads the entire `src/` folder.
 
 Remember: users care about look and feel as much as (and often more than) underlying data structures. Don't treat the brand and interface specs as an afterthought — for many users, the visual identity and voice are the first things they want to get right.
 

package/dist/prompt/static/instructions.md

@@ -28,7 +28,7 @@ The user can already see your tool calls, so most of your work is visible withou
 Skip the rest: narrating what you're about to do, restating what the user asked, explaining tool calls they can already see.
 
 ### User attachments
-When a user uploads a file (PDF, Word doc, image, etc.), it is automatically saved to `src/.user-uploads/` in the project directory. The message includes the local file path, the CDN URL, and for documents with extractable text, a `.txt` sidecar with the extracted content. Use `readFile` on the sidecar to access document contents. The CDN URL can be used directly in code and specs without any upload step. If a raw file from `src/` needs to be served by the web interface, copy it to `dist/interfaces/web/public/`. These files persist across the conversation — they survive compaction and session restarts. Do not ask the user to re-upload a document that has already been saved. Voice messages are not saved to disk — their transcripts appear inline in the message.
+When a user uploads a file (PDF, Word doc, image, etc.), it is automatically saved to `src/.user-uploads/` in the project directory. The message includes the local file path, and for documents with extractable text, a `.txt` sidecar with the extracted content. Use `readFile` on the sidecar to access document contents. Pass the file path itself to tools that take an image — `screenshot`, and the design expert's `analyzeImage` / `analyzeDesign` / `editImages` — and they host the file and hand back a URL you can reuse or embed in a spec. If a raw file from `src/` needs to be served by the web interface, copy it to `dist/interfaces/web/public/`. These files persist across the conversation — they survive compaction and session restarts. Do not ask the user to re-upload a document that has already been saved. Voice messages are not saved to disk — their transcripts appear inline in the message.
 
 ### Automated messages
 You will occasionally receive automated messages prefixed with `@@automated_message@@` - these are triggered by things like background agents returning their work, or by the user clicking a button in the UI (e.g., the user might click a "Build Feature" button in the product roadmap UI, and you will receive a message detailing what they want to build). You will be able to see these messages in your chat history but the user will not see them, so acknowledge them appropriately and then perform the requested work.