@mindstudio-ai/remy 0.1.276 → 0.1.277

package/dist/prompt/skills/dataSources.md

@@ -6,33 +6,20 @@ when: Only for unstructured documents queried by meaning — "find the clause ab
 
 # Data Sources (Search Over Documents)
 
-Per-app searchable document corpora: upload documents, ask in plain language, get back the passages
-that answer it with a citation to the source.
+Per-app searchable document corpora: upload documents, ask in plain language, get back the passages that answer it with a citation to the source.
 
-**Most apps should not use one — check this before reaching for it.** Structured data (rows with
-fields you filter on) belongs in `db`; a `WHERE` clause is faster, cheaper and exact. A data source
-earns its cost only for **unstructured documents queried by meaning**. "Find the clause about early
-termination" is a data source. "Find contracts signed after March" is a `db` query. If the question
-can be expressed as a filter, it is not a search problem.
+**Most apps should not use one — check this before reaching for it.** Structured data (rows with fields you filter on) belongs in `db`; a `WHERE` clause is faster, cheaper and exact. A data source earns its cost only for **unstructured documents queried by meaning**. "Find the clause about early termination" is a data source. "Find contracts signed after March" is a `db` query. If the question can be expressed as a filter, it is not a search problem.
 
-Don't use one when: the data is structured (`db`), you only need to store files (`files` — nobody is
-searching the contents), the requirement is exact lookup by identifier, or the corpus is a handful of
-short docs that fit in a prompt.
+Don't use one when: the data is structured (`db`), you only need to store files (`files` — nobody is searching the contents), the requirement is exact lookup by identifier, or the corpus is a handful of short docs that fit in a prompt.
 
 ## Behaviour (read before the API)
 
-- **One corpus shared across dev and prod** — like a file store, not a table. No dev copy, no
-  per-release isolation. A document added while building is already live.
+- **One corpus shared across dev and prod** — like a file store, not a table. No dev copy, no per-release isolation. A document added while building is already live.
 - **Scenarios never reset a data source.** Don't write `clear()`-style reset helpers.
 - **Re-adding the same bytes is free** — content-addressed, so ingest scripts are safe to re-run.
 - **Ingest is async.** `add()` returns once queued; poll `documents()`, or use `--wait` from the CLI.
 - **Reprocessing costs real money**, so changing how a corpus is built is always explicit.
-- **Limits apply**: 25 data sources per app, 5,000 documents per source, 10,000 chunks per
-  document, 300 searches/minute. Well clear of normal use — but **source names must be fixed, not
-  computed per user or per request**, since referencing one creates it. Partition inside a source
-  with document metadata instead: tag at add time
-  (`add(bytes, { filename, metadata: { userId } })`), narrow at search time
-  (`search(q, { filter: { metadata: { userId } } })`).
+- **Limits apply**: 25 data sources per app, 5,000 documents per source, 10,000 chunks per document, 300 searches/minute. Well clear of normal use — but **source names must be fixed, not computed per user or per request**, since referencing one creates it. Partition inside a source with document metadata instead: tag at add time (`add(bytes, { filename, metadata: { userId } })`), narrow at search time (`search(q, { filter: { metadata: { userId } } })`).
 
 ## Defining and searching
 
@@ -44,43 +31,21 @@ const { results } = await Policies.search('what are the payment terms?', { topK:
 const context = results.map((r) => r.text).join('\n\n');
 ```
 
-Hits are `{ score, text, citation }` with
-`citation: { documentId, filename, pageNumber, chunkIndex, headingPath, boundingBox?, url }`, plus
-`retrievalRank`/`retrievalScore` — the position before reranking, so you can show what reranking did.
+Hits are `{ score, text, citation }` with `citation: { documentId, filename, pageNumber, chunkIndex, headingPath, boundingBox?, url }`, plus `retrievalRank`/`retrievalScore` — the position before reranking, so you can show what reranking did.
 
-**Always render the citation.** `citation.url` is a stable on-domain link — put it in an `<a href>`
-beside the answer. Retrieval is approximate; a user who can click through can judge for themselves.
-An answer with no citation is an assertion.
+**Always render the citation.** `citation.url` is a stable on-domain link — put it in an `<a href>` beside the answer. Retrieval is approximate; a user who can click through can judge for themselves. An answer with no citation is an assertion.
 
-Created on first use, so searching a source the build hasn't populated returns no results rather than
-throwing. `search` options: `topK` (default 5, max 50), `scoreThreshold`, `filter`, `mode`,
-`maxPerDocument`, `highlight`, `rerank`, `hybrid`.
+Created on first use, so searching a source the build hasn't populated returns no results rather than throwing. `search` options: `topK` (default 5, max 50), `scoreThreshold`, `filter`, `mode`, `maxPerDocument`, `highlight`, `rerank`, `hybrid`.
 
-**Filtering** narrows a search before ranking, and every condition only narrows:
-`filter: { metadata: { department: 'legal', year: [2025, 2026] }, filename, documentIds,
-pages: { min?, max? }, contains: 'all these words', phrase: 'exact adjacent sequence' }`.
-Metadata is tagged at add time (scalars only, ≤16 keys); re-adding the same bytes with different
-metadata updates the tags in place, free. Filters are the right tool for scoping retrieval
-(per-user, per-category); they are NOT a substitute for a `db` query over structured data.
+**Filtering** narrows a search before ranking, and every condition only narrows: `filter: { metadata: { department: 'legal', year: [2025, 2026] }, filename, documentIds, pages: { min?, max? }, contains: 'all these words', phrase: 'exact adjacent sequence' }`. Metadata is tagged at add time (scalars only, ≤16 keys); re-adding the same bytes with different metadata updates the tags in place, free. Filters are the right tool for scoping retrieval (per-user, per-category); they are NOT a substitute for a `db` query over structured data.
 
-**Modes**: `mode: 'hybrid'` (default) fuses semantic and keyword retrieval; `'semantic'` is the
-embedding alone; `'lexical'` is keyword-only with **no query embedding** — cheapest and fastest,
-right when the query is an identifier (an error code, a SKU, a name) rather than a meaning.
-`maxPerDocument: 2` stops one document monopolizing the results when the answer should draw on
-several. `highlight: true` adds `matches` (`{start, end}` offsets into `text`) for rendering
-highlighted excerpts.
+**Modes**: `mode: 'hybrid'` (default) fuses semantic and keyword retrieval; `'semantic'` is the embedding alone; `'lexical'` is keyword-only with **no query embedding** — cheapest and fastest, right when the query is an identifier (an error code, a SKU, a name) rather than a meaning. `maxPerDocument: 2` stops one document monopolizing the results when the answer should draw on several. `highlight: true` adds `matches` (`{start, end}` offsets into `text`) for rendering highlighted excerpts.
 
-Search is deterministic for a fixed corpus and configuration, so eval sets and regression checks are
-meaningful — key them on `(documentId, chunkIndex)` rather than on chunk text.
+Search is deterministic for a fixed corpus and configuration, so eval sets and regression checks are meaningful — key them on `(documentId, chunkIndex)` rather than on chunk text.
 
-**Debugging retrieval.** Two opt-in options, neither of which changes the results or their order:
-`explain: true` adds `explain.{dense, lexical, matchedVia}` (which half of hybrid found each hit;
-costs two extra round trips), and `expand: 1` adds `neighbors.{before, after}` for surrounding
-context. When a document never comes back at all, `Policies.stats()` reports the config actually in
-effect and `Policies.chunks(documentId)` shows exactly how it was split.
+**Debugging retrieval.** Two opt-in options, neither of which changes the results or their order: `explain: true` adds `explain.{dense, lexical, matchedVia}` (which half of hybrid found each hit; costs two extra round trips), and `expand: 1` adds `neighbors.{before, after}` for surrounding context. When a document never comes back at all, `Policies.stats()` reports the config actually in effect and `Policies.chunks(documentId)` shows exactly how it was split.
 
-**Configuration is not declared in code** — chunking and embedding settings live on the corpus and are
-set with the CLI, so code and reality can't drift.
+**Configuration is not declared in code** — chunking and embedding settings live on the corpus and are set with the CLI, so code and reality can't drift.
 
 ## Loading documents — normally at build time, from the CLI
 
@@ -92,12 +57,9 @@ mindstudio-prod datasources search --source policies --filter department=legal -
 mindstudio-prod datasources delete --source policies   # whole source; --source is required, never defaulted
 ```
 
-`--wait` blocks until processing finishes and exits non-zero on failure. Also `datasources list`,
-`status` (per-document state + ingest errors), `rm --document <id>`. `--help` for flags.
+`--wait` blocks until processing finishes and exits non-zero on failure. Also `datasources list`, `status` (per-document state + ingest errors), `rm --document <id>`. `--help` for flags.
 
-**Seeding a test corpus:** scenarios don't touch data sources, so load fixtures with the same command
-in a setup script — `datasources add --source <slug> --wait fixtures/*.pdf`. Re-running is free, so
-it needs no guard.
+**Seeding a test corpus:** scenarios don't touch data sources, so load fixtures with the same command in a setup script — `datasources add --source <slug> --wait fixtures/*.pdf`. Re-running is free, so it needs no guard.
 
 Use the SDK's `add()` only when *users* upload documents that must become searchable:
 
@@ -115,9 +77,7 @@ Formats: pdf, docx, pptx, xlsx, odt, rtf, epub, images, txt, md, json, csv, tsv,
 
 ## Answering from results
 
-Retrieve → join passages as context → have a model answer *from that context* → render citations.
-Never paste raw chunks at the user; they're fragments. For agentic flows, give the model `search` as a
-tool so it can query repeatedly and refine, rather than retrieving once up front.
+Retrieve → join passages as context → have a model answer *from that context* → render citations. Never paste raw chunks at the user; they're fragments. For agentic flows, give the model `search` as a tool so it can query repeatedly and refine, rather than retrieving once up front.
 
 ## Tuning — two kinds of setting
 
@@ -126,21 +86,16 @@ tool so it can query repeatedly and refine, rather than retrieving once up front
 | **Free** (ranking) | `--rerank`, `--rerank-model`, `--hybrid`, `--top-k` | none, next search |
 | **Rebuild** (how docs become vectors) | `--max-chars`, `--min-chars`, `--drop-blocks`, `--contextual`, `--describe-images`, `--embedding-model`, `--extraction-model` | every document reprocessed |
 
-Images inside documents are described by a vision model and the description substituted into the
-searchable text (`--describe-images`, on by default) — without it a chart contributes nothing to
-search at all. Documents with no images cost nothing.
+Images inside documents are described by a vision model and the description substituted into the searchable text (`--describe-images`, on by default) — without it a chart contributes nothing to search at all. Documents with no images cost nothing.
 
-`rerank` and `hybrid` default on and are usually right — reranking is the biggest quality lever, and
-hybrid is what finds part numbers, error codes and proper nouns a semantic model never learned. Both
-are also per-query (`search(q, { rerank: false })`) for a latency-sensitive path.
+`rerank` and `hybrid` default on and are usually right — reranking is the biggest quality lever, and hybrid is what finds part numbers, error codes and proper nouns a semantic model never learned. Both are also per-query (`search(q, { rerank: false })`) for a latency-sensitive path.
 
 ```bash
 mindstudio-prod datasources config --source policies              # show
 mindstudio-prod datasources config --source policies --top-k 8    # free, immediate
 ```
 
-**A rebuild-class change on a populated corpus is rejected** — you're told what it would invalidate
-and what it costs. To make it, build a new version alongside the live one:
+**A rebuild-class change on a populated corpus is rejected** — you're told what it would invalidate and what it costs. To make it, build a new version alongside the live one:
 
 ```bash
 mindstudio-prod datasources revectorize --source policies --max-chars 900 --wait
@@ -148,7 +103,6 @@ mindstudio-prod datasources search --source policies --candidate "payment terms"
 mindstudio-prod datasources promote --source policies                              # go live
 ```
 
-Search serves the current version throughout, so nothing degrades while the new one builds.
-`datasources drop` discards an unwanted candidate.
+Search serves the current version throughout, so nothing degrades while the new one builds. `datasources drop` discards an unwanted candidate.
 
 For anything deeper on the SDK, ask `askMindStudioSdk` rather than guessing at an API.

package/dist/prompt/skills/files.md

@@ -6,37 +6,19 @@ when: Before defining a file store or writing any upload, download, share-link,
 
 # Files & Storage
 
-Per-app blob storage: user uploads, generated documents, images, marketing assets. **Think of a store
-as a CDN-backed bucket the app talks to — not app-defined state like the database.** You declare the
-store; what lands in it is arbitrary durable blobs the app doesn't model — no schema, nothing to
-migrate, no dev/prod sync. **Private by default**, served on the app's own domain. (The API is
-*shaped* like `db` — `defineStore` at module scope, import the handle, like `defineTable` — but the
-mental model is a bucket, not rows.)
+Per-app blob storage: user uploads, generated documents, images, marketing assets. **Think of a store as a CDN-backed bucket the app talks to — not app-defined state like the database.** You declare the store; what lands in it is arbitrary durable blobs the app doesn't model — no schema, nothing to migrate, no dev/prod sync. **Private by default**, served on the app's own domain. (The API is *shaped* like `db` — `defineStore` at module scope, import the handle, like `defineTable` — but the mental model is a bucket, not rows.)
 
 ## How a store behaves (read before the API)
 
-- **One store, shared across dev and prod — on purpose.** There's no dev copy: a file you upload in
-  the dev editor (a marketing image, a corpus to vectorize) is *already there in prod* at the same
-  stable URL. That continuity is a feature — don't fork buckets per environment.
-- **Creates are safe by default**, because keys default to unique — `put()` mints a UUID (or a
-  content-addressed hash) when you don't pass one, so a dev write and a prod write land at different
-  keys and coexist. A collision only happens when you *choose* a fixed key.
-- **Care goes on the destructive / fixed-key operations**, not on writing in general: `delete(key)`
-  and overwriting a **stable key** (e.g. `config/latest.json`) reach the one live store, so a dev run
-  can clobber what prod serves. A `put()` with a default key can't. (There's intentionally no bulk
-  "clear the store".)
-- **Scenarios don't touch files — and that's correct.** A scenario truncates DB tables to seed test
-  *rows*; files are durable and left alone. A store isn't a "clean slate" you re-seed each run — upload
-  a test file once in dev and it stays. Accumulation is normal for an asset store; don't write
-  `clear()`-style reset helpers.
-- **Need dev and prod to *not* share** something (mutable fixed-key state, or sensitive uploads a
-  developer shouldn't see)? There's no per-store isolation switch — scope the key yourself (e.g.
-  `config/${env}/…`). Rare; the shared default is right almost always.
+- **One store, shared across dev and prod — on purpose.** There's no dev copy: a file you upload in the dev editor (a marketing image, a corpus to vectorize) is *already there in prod* at the same stable URL. That continuity is a feature — don't fork buckets per environment.
+- **Creates are safe by default**, because keys default to unique — `put()` mints a UUID (or a content-addressed hash) when you don't pass one, so a dev write and a prod write land at different keys and coexist. A collision only happens when you *choose* a fixed key.
+- **Care goes on the destructive / fixed-key operations**, not on writing in general: `delete(key)` and overwriting a **stable key** (e.g. `config/latest.json`) reach the one live store, so a dev run can clobber what prod serves. A `put()` with a default key can't. (There's intentionally no bulk "clear the store".)
+- **Scenarios don't touch files — and that's correct.** A scenario truncates DB tables to seed test *rows*; files are durable and left alone. A store isn't a "clean slate" you re-seed each run — upload a test file once in dev and it stays. Accumulation is normal for an asset store; don't write `clear()`-style reset helpers.
+- **Need dev and prod to *not* share** something (mutable fixed-key state, or sensitive uploads a developer shouldn't see)? There's no per-store isolation switch — scope the key yourself (e.g. `config/${env}/…`). Rare; the shared default is right almost always.
 
 ## Defining a store
 
-Like `db.defineTable`, define at module scope and import into methods. Access is pinned at define
-time.
+Like `db.defineTable`, define at module scope and import into methods. Access is pinned at define time.
 
 ```typescript
 import { files } from '@mindstudio-ai/agent';
@@ -63,13 +45,9 @@ const { files, cursor } = await Uploads.list({ prefix: 'reports/', limit: 100 })
 await Uploads.delete(key);
 ```
 
-- `put(content, { key?, contentType?, filename?, contentAddressed? })` → `StoredFile`
-  (`{ key, url, size?, contentType?, updatedAt?, shareUrl() }`). Omit `key` → UUID;
-  `contentAddressed: true` → a `<sha256>.<ext>` key (immutable/idempotent, for baked-in public assets).
-- **`file.url`** is a plain relative string — don't await it. To display a user *their own* file, hand
-  them `file.url`; don't `get()` the bytes and stream them yourself.
-- **`await file.shareUrl({ expiresIn })`** → an absolute signed link that works with **no session**
-  (email / cross-site embed). Private stores only; default 24h.
+- `put(content, { key?, contentType?, filename?, contentAddressed? })` → `StoredFile` (`{ key, url, size?, contentType?, updatedAt?, shareUrl() }`). Omit `key` → UUID; `contentAddressed: true` → a `<sha256>.<ext>` key (immutable/idempotent, for baked-in public assets).
+- **`file.url`** is a plain relative string — don't await it. To display a user *their own* file, hand them `file.url`; don't `get()` the bytes and stream them yourself.
+- **`await file.shareUrl({ expiresIn })`** → an absolute signed link that works with **no session** (email / cross-site embed). Private stores only; default 24h.
 
 ## User uploads (client-direct — bytes never go through the backend)
 
@@ -91,9 +69,7 @@ const { key, url } = await platform.upload(token, file, { onProgress: (f) => set
 
 ## Public assets + image resizing
 
-Public files are world-readable, served on the app's own domain, and **images resize via query
-params** — request the size you need rather than CSS-scaling a full-res original. Always set `dpr=2`
-or `3` when sizing so images stay crisp on Retina displays.
+Public files are world-readable, served on the app's own domain, and **images resize via query params** — request the size you need rather than CSS-scaling a full-res original. Always set `dpr=2` or `3` when sizing so images stay crisp on Retina displays.
 
 | Param | Example | Effect |
 |-------|---------|--------|
@@ -109,13 +85,11 @@ or `3` when sizing so images stay crisp on Retina displays.
 
 Combine freely: `…/hero.jpg?w=200&h=200&fit=crop&fm=avif`.
 
-Lightweight-config pattern: a public store + a stable `key` is a file the frontend can `fetch` with no
-DB hit and the backend can overwrite (`Config.put(json, { key: 'config/latest.json' })`).
+Lightweight-config pattern: a public store + a stable `key` is a file the frontend can `fetch` with no DB hit and the backend can overwrite (`Config.put(json, { key: 'config/latest.json' })`).
 
 ## Build-time / marketing assets
 
-Need an image on the site (hero, logo, OG image)? **Never commit binaries to the repo** — it bloats
-git. Upload once and embed the returned URL:
+Need an image on the site (hero, logo, OG image)? **Never commit binaries to the repo** — it bloats git. Upload once and embed the returned URL:
 
 ```bash
 mindstudio-prod files put --public ./hero.jpg   # → { url, key } — content-addressed, immutable
@@ -124,8 +98,7 @@ Write that URL into your JSX/HTML. Also: `files list`, `files rm --store … --k
 
 ## Generated assets
 
-MindStudio SDK Actions that produce a file (`generateImage`, `generateVideo`, `generateSpeech`, `generatePdf`,
-`upscaleImage`, …) can optionally write straight into a store — pass the handle as `store` in the options object:
+MindStudio SDK Actions that produce a file (`generateImage`, `generateVideo`, `generateSpeech`, `generatePdf`, `upscaleImage`, …) can optionally write straight into a store — pass the handle as `store` in the options object:
 
 ```typescript
 const { imageUrl } = await mindstudio.generateImage({ prompt }, { store: Assets });
@@ -135,10 +108,7 @@ If omitted, files are written to the default global, public MindStudio CDN.
 
 ## When public vs private
 
-- **Private (default):** user uploads, generated docs, anything not world-readable. Reads are authed
-  (the app session) or a short-lived `shareUrl`.
-- **Public:** marketing images, resizable media, config the frontend reads. Deliberate `access:
-  'public'`.
+- **Private (default):** user uploads, generated docs, anything not world-readable. Reads are authed (the app session) or a short-lived `shareUrl`.
+- **Public:** marketing images, resizable media, config the frontend reads. Deliberate `access: 'public'`.
 
-Per-user access is the app's job — key files per user (`{userId}/…`) and hand each user only their own
-URLs; the platform authorizes at the app level, not per file.
+Per-user access is the app's job — key files per user (`{userId}/…`) and hand each user only their own URLs; the platform authorizes at the app level, not per file.

package/dist/prompt/skills/inboundEmail.md

@@ -6,17 +6,13 @@ when: Before writing an email-handler method, adding an `email` interface, or pr
 
 # 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.
+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.
+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.
+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 |
 |---|---|---|
@@ -24,13 +20,9 @@ registration); the legacy tier is specific-localpart and frozen for new apps.
 | 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.
+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.
+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`)
 
@@ -45,10 +37,7 @@ The top-level key must match the interface type (`email`):
 }
 ```
 
-`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.
+`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`:
 
@@ -78,9 +67,7 @@ Declare it in `mindstudio.json`:
 
 ## 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`.
+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({
@@ -95,22 +82,14 @@ await mindstudio.sendEmail({
 });
 ```
 
-`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.
+`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.
+`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.
+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.
+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

@@ -6,10 +6,7 @@ when: Before authoring `src/interfaces/mcp.md`, deciding which of the app's meth
 
 # 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.
+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:
 
@@ -18,18 +15,11 @@ It supports the full MCP surface:
 - **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 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:
 
@@ -47,32 +37,22 @@ 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. Abbreviated to just the annotations (a real entry also carries `name`, `title` and
-`description` — the Config section has the full shape):
+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": [
@@ -84,32 +64,21 @@ than nagging. Abbreviated to just the annotations (a real entry also carries `na
 ]
 ```
 
-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
@@ -119,8 +88,7 @@ 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.
 
 ---
 
@@ -128,8 +96,7 @@ domain, so the calling agent's first move is a reasonable one.
 
 ## 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.
+Frontmatter declares the server. In the body, the intro prose becomes the server `instructions`, and `## Tools`, `## Resources` and `## Prompts` headings declare the rest.
 
 ```yaml
 ---
@@ -252,8 +219,7 @@ The top-level key must match the interface type (`mcp`):
 | `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.
+There is no `inputSchema` field — the platform derives each tool's schema from the method's input contract.
 
 Declare it in `mindstudio.json`:
 
@@ -263,18 +229,10 @@ Declare it in `mindstudio.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(...)`/`hasRole(...)` 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.
+- 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(...)`/`hasRole(...)` 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.
+- `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

@@ -6,24 +6,15 @@ when: Before authoring `src/interfaces/api.md` or adding an `api` interface with
 
 # 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.
+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.
+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.
+**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.
+The human-readable spec. Frontmatter declares the API name and description; the body maps methods to REST routes using MSFM.
 
 ```yaml
 ---
@@ -33,8 +24,7 @@ type: interface/api
 ---
 ```
 
-Routes are declared as `VERB /path → methodExportName` under resource headings, with annotations for
-params and descriptions:
+Routes are declared as `VERB /path → methodExportName` under resource headings, with annotations for params and descriptions:
 
 ```markdown
 ## Vendors
@@ -140,10 +130,6 @@ Routes are mounted at `/_/api{path}` (e.g. `DELETE /_/api/vendors/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(...)`/`hasRole(...)` checks apply exactly as they would for that user
+- **Auth** via `Authorization: Bearer sk_...` — an API key resolves to a user with full RBAC, so the method's own `auth.requireRole(...)`/`hasRole(...)` 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.
+- **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/scenarios.md

@@ -112,19 +112,15 @@ Scenarios are useful for seeding initial app state after build for testing, as w
 
 ## What scenarios don't touch
 
-**Scenarios seed database tables and nothing else.** They do not touch file stores or data sources —
-deliberately: both are durable and shared across dev and prod, with no per-release copy to reset, so
-there is nothing to truncate.
+**Scenarios seed database tables and nothing else.** They do not touch file stores or data sources — deliberately: both are durable and shared across dev and prod, with no per-release copy to reset, so there is nothing to truncate.
 
-Don't try to seed documents into a data source from a scenario, and don't write `clear()`-style reset
-helpers for one. Load a test corpus once from the CLI instead:
+Don't try to seed documents into a data source from a scenario, and don't write `clear()`-style reset helpers for one. Load a test corpus once from the CLI instead:
 
 ```bash
 mindstudio-prod datasources add --source policies --wait fixtures/*.pdf
 ```
 
-Re-running it is free (documents are content-addressed), so it's safe to keep in a setup script
-beside your scenarios.
+Re-running it is free (documents are content-addressed), so it's safe to keep in a setup script beside your scenarios.
 
 ## Scenario Data
 

package/dist/prompt/skills/scheduledJobs.md

@@ -31,8 +31,7 @@ The top-level key must match the interface type (`cron`):
 }
 ```
 
-Standard cron expression format. `method` is the id of a method in `methods[]`. Jobs are synced to the
-platform on deploy.
+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`:
 
@@ -42,10 +41,6 @@ Declare it in `mindstudio.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.
+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.
+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.