@mindstudio-ai/remy 0.1.255 → 0.1.257

package/dist/prompt/compiled/files.md

@@ -85,9 +85,23 @@ const { key, url } = await platform.upload(token, file, { onProgress: (f) => set
 
 ## Public assets + image resizing
 
-Public files are world-readable, on the app's domain, and **images resize via query params**
-(`?w=&h=&fit=&crop=&fm=&dpr=&q=&blur=&sharpen=` — same vocabulary as the image CDN; set `dpr=2/3` for
-retina). Request the size you need rather than CSS-scaling a full-res original.
+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 |
+|-------|---------|--------|
+| `w` | `?w=400` | Max width in pixels |
+| `h` | `?h=300` | Max height in pixels |
+| `fit` | `?fit=crop` | Resize mode: `scale-down`, `contain`, `cover`, `crop`, `pad` |
+| `crop` | `?crop=face` | Face-aware crop (with `fit=crop`) |
+| `fm` | `?fm=webp` | Output format: `avif`, `webp`, `jpeg`, `auto` |
+| `dpr` | `?dpr=2` | Device pixel ratio |
+| `q` | `?q=80` | Quality (1–100) |
+| `blur` | `?blur=10` | Blur radius |
+| `sharpen` | `?sharpen=1` | Sharpen amount |
+
+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' })`).

package/dist/prompt/compiled/interfaces.md

@@ -59,19 +59,16 @@ const api = createClient<{
 const { vendorId } = await api.submitVendorRequest({ name: 'Acme' });
 const { vendors } = await api.listVendors();
 
-// File upload (returns CDN URL)
-const url = await platform.uploadFile(file);
+// File upload → client-direct to the app's file store (see Files & Storage).
+// A backend method mints an upload token; the browser uploads straight to storage.
+const token = await api.getUploadSlot({ filename: file.name, contentType: file.type });
+const { key, url } = await platform.upload(token, file);
 
-// With progress tracking
-const url = await platform.uploadFile(file, {
-  onProgress: (fraction) => setProgress(fraction), // 0 to 1
-});
-
-// With abort support
+// With progress + abort
 const controller = new AbortController();
-const url = await platform.uploadFile(file, {
+const { url } = await platform.upload(token, file, {
   signal: controller.signal,
-  onProgress: (f) => setProgress(f),
+  onProgress: (fraction) => setProgress(fraction), // 0 to 1
 });
 controller.abort(); // cancels the upload
 
@@ -419,7 +416,7 @@ 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 like the API interface (optional — keyed or anonymous), and derives every tool's input schema from the method contract. Because the consumer is an external agent with no knowledge of your app, **the descriptions are the product** — see "Building MCP Interfaces" for how to write them.
+The platform hosts the server, handles auth like the API interface (optional — keyed or anonymous), and derives every tool's input schema from the method contract. Because the consumer is an external agent with no knowledge of your app, **the descriptions are the product** — load the `mcpInterfaces` skill for how to write them.
 
 ### Spec: `src/interfaces/mcp.md`
 
@@ -566,6 +563,8 @@ There is no `inputSchema` field — the platform derives each tool's schema from
 
 A conversational interface where an LLM has access to the app's methods as tools. Unlike MCP (which exposes methods for external agents), the agent interface IS the agent — it has its own personality, system prompt, and model config, and orchestrates tool calls against the app's methods internally.
 
+This section is the wiring. Load the `agentInterfaces` skill before authoring the spec body or building the chat UI — what belongs in the agent's system prompt, how to write its tool descriptions, and the `createAgentChatClient()` frontend API are all there.
+
 ### 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.

package/dist/prompt/compiled/methods.md

@@ -97,11 +97,8 @@ await mindstudio.sendEmail({
   cc: input.cc, // reply-all
 });
 
-// Upload files
-const { url } = await mindstudio.uploadFile({
-  data: buffer,
-  fileName: 'report.pdf',
-});
+// Store a file → returns a stable URL (define the store at module scope; see Files & Storage)
+const { url } = await Reports.put(buffer, { contentType: 'application/pdf', filename: 'report.pdf' });
 
 // Web scraping
 const { markdown } = await mindstudio.scrapeUrl({
@@ -221,6 +218,8 @@ export async function createPurchaseOrder(input: {
 
 A method can return immediately while kicking off slow work (like `runTask()`) that continues in the background. Don't await the slow call — use `.then()` / `.catch()` to update the record when it completes, and return an early result to the caller. The frontend polls the record's status to track progress.
 
+The example below shows the fire-and-forget shape, not a complete `runTask()` call. Load the `taskAgents` skill before writing one — configuring its tools, validating the output, and handling failures are all there, and none of them are visible here.
+
 ```typescript
 export async function enrichRestaurant(input: { id: string; name: string }) {
   await Restaurants.update(input.id, { status: 'enriching' });

package/dist/prompt/compiled/scenarios.md

@@ -104,6 +104,22 @@ This is deterministic — same scenario always produces the same state.
 
 Scenarios are useful for seeding initial app state after build for testing, as well as to give the user a first impression of an app that is already filled with data and looks and feels usable. The user can choose to run further scenarios after initial build by clicking the Scenarios tab and selecting a scenario to run.
 
+## 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.
+
+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.
+
 ## Scenario Data
 
 Align scenario data to the vibe of the app - construct data that feels like it fits.

package/dist/prompt/compiled/sdk-actions.md

@@ -83,7 +83,6 @@ result.$billingCost;         // cost in credits (if applicable)
 
 | Action | What it does |
 |--------|-------------|
-| `uploadFile` | Upload a file to CDN |
 | `downloadVideo` | Download a video URL |
 | `getMediaMetadata` | Get dimensions, duration, etc. |
 | `convertPdfToImages` | PDF pages to PNG images |
@@ -154,4 +153,4 @@ Consider the ways in which AI can be incorporated into backend methods to solve
 
 ### Task Agents
 
-For multi-step tasks where the model needs to autonomously compose actions (research + scrape + generate, enrichment pipelines, content creation), use `runTask()` instead of chaining actions manually. It runs an agent loop and returns structured JSON. Its tools can include SDK actions as well as your app's own methods, so the agent can read your data to decide what to do next and write results back itself. See the task agents reference for full details.
+For multi-step tasks where the model needs to autonomously compose actions (research + scrape + generate, enrichment pipelines, content creation), use `runTask()` instead of chaining actions manually. It runs an agent loop and returns structured JSON. Its tools can include SDK actions as well as your app's own methods, so the agent can read your data to decide what to do next and write results back itself. Load the `taskAgents` skill before writing one — it is the full reference.

package/dist/prompt/{compiled/agent-interfaces.md → skills/agentInterfaces.md}

@@ -1,3 +1,9 @@
+---
+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.
+---
+
 # Building Agent Interfaces
 
 Guidance for designing conversational AI agents and their frontends. An agent interface pairs an LLM (with per-user-scoped/authenticated access to app methods as tools, handled by platform automatically) with a chat UI. The developer authors the agent's character in MSFM (`src/interfaces/agent.md`); you compile it into a system prompt and tool descriptions (`dist/interfaces/agent/`).
@@ -10,21 +16,32 @@ A good system prompt establishes who the agent is — personality, tone, judgmen
 
 Short and opinionated beats long and comprehensive. "Sounds like a sharp, organized friend — brief by default" gives the model more to work with than a page of behavioral rules. Define constraints through character, not checklists. Let the model's judgment work.
 
-#### System Prompt Specifics
-Always include a note like "## Tool Usage
-- When multiple tool calls are independent, make them all in a single turn. Searching for three different products, or fetching two reference sites: batch them instead of doing one per turn." to help the model know it can run tools in parallel
-- The user's name and current role(s) at the time of message, if any, will be automatically appended to the end of every system prompt at runtime like:
+Three things every compiled system prompt should carry, on top of the character:
+
+**Parallel tool use.** The model won't batch independent calls unless told it can. Include a section like:
 
+```markdown
+## Tool Usage
+
+When multiple tool calls are independent, make them all in a single turn.
+Searching for three different products, or fetching two reference sites:
+batch them instead of doing one per turn.
 ```
+
+**Markdown and house style.** Unless the user says otherwise, tell the agent it can use markdown (the chat UI renders it) and to avoid em dashes and emojis.
+
+**The current user is appended for you.** At runtime the platform appends the user's name and roles to the end of every system prompt, so don't write your own placeholder for it:
+
+```markdown
 ## Current User
+
 Name: Jane Smith
 Roles: editor
 ```
-- Unless the user specifies otherwise, always include a note that the agent can use markdown in responses (since the chat UI renders it) and should avoid using em dashes and emojis in its responses.
 
 ### Tool descriptions are the most important artifact
 
-The system prompt says *who* the agent is. The tool descriptions say *what it can do*. A great tool description means the agent uses the tool correctly without explicit instruction. Do not be overly precise or micromanage. Your goal with tool descriptions is to provide context and faming- trust that the model is intelligent enough to fill in the gaps.. Each `tools/*.md` file should cover:
+The system prompt says *who* the agent is. The tool descriptions say *what it can do*. A great tool description means the agent uses the tool correctly without explicit instruction. Do not be overly precise or micromanage. Your goal with tool descriptions is to provide context and framing — trust that the model is intelligent enough to fill in the gaps. Each `tools/*.md` file should cover:
 
 - **When to use** this tool (and when NOT to — e.g. "NOT for marking complete, use toggle-todo")
 - **Parameter guidance** beyond the schema — what makes a good value, when to include optional fields, what to skip
@@ -116,10 +133,12 @@ response.abort();
 
 **Attachments:**
 
-Send images or documents alongside a message. Upload via `platform.uploadFile()` first, then pass CDN URLs as the 4th argument:
+Send images or documents alongside a message. Upload to the app's file store first (see Files & Storage), then pass the returned URLs as the 4th argument:
 
 ```ts
-const url = await platform.uploadFile(file);
+// backend method mints a token; the browser uploads straight to storage
+const token = await api.getUploadSlot({ filename: file.name, contentType: file.type });
+const { url } = await platform.upload(token, file);
 
 chat.sendMessage(threadId, "What's in this document?", {
   onText: (delta) => setText((prev) => prev + delta),
@@ -128,7 +147,7 @@ chat.sendMessage(threadId, "What's in this document?", {
 });
 ```
 
-Images (`i.mscdn.ai`) are sent as vision input. Documents (`f.mscdn.ai`) have text extracted server-side and included in context. Attachments are preserved in thread history.
+Images are sent as vision input; documents have their text extracted server-side and included in context. Attachments are preserved in thread history.
 
 **Key points:**
 - `onText` and `onThinking` receive deltas (append to state, don't replace)
@@ -174,7 +193,7 @@ The first screen should invite conversation. A greeting from the agent, a few su
 
 ### Mobile
 
-Chat is inherently mobile-friendly — lean into it. Pay attention to viewport sizing on mobile as the virtual keyboard changes the available height. 
+Chat is inherently mobile-friendly — lean into it. Pay attention to viewport sizing on mobile as the virtual keyboard changes the available height.
 
 ### Respect the brand
 

package/dist/prompt/skills/dataSources.md

@@ -0,0 +1,131 @@
+---
+name: Data Sources
+what: A managed retrieval system for document corpora, not a bolt-on keyword search. Documents are chunked and embedded, candidate hits are re-scored by a reranking model, semantic search runs alongside exact keyword matching so part numbers and error codes still land, images inside documents are described by a vision model and made searchable, and every hit returns a citation that links to its source page. Chunking and embedding settings are versioned — a rebuilt corpus can be compared against the live one and promoted without downtime. All of that applies to unstructured documents queried by meaning, and to nothing else.
+when: Only for unstructured documents queried by meaning — "find the clause about early termination". Structured data belongs in `db`: if the question can be expressed as a filter, it is not a search problem, and a `WHERE` clause is faster, cheaper and exact. Load before defining or querying a data source.
+---
+
+# 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.
+
+**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.
+
+## 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.
+- **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 a metadata filter instead.
+
+## Defining and searching
+
+```typescript
+import { dataSources } from '@mindstudio-ai/agent';
+export const Policies = dataSources.defineDataSource('policies');   // lowercase [a-z0-9_-], ≤64
+
+const { results } = await Policies.search('what are the payment terms?', { topK: 5 });
+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.
+
+**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`, `rerank`, `hybrid`.
+
+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.
+
+**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
+
+```bash
+mindstudio-prod datasources add --source policies --wait docs/*.pdf
+mindstudio-prod datasources search --source policies "what are the payment terms?"   # sanity-check
+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.
+
+**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:
+
+```typescript
+await Policies.add(buffer, { filename: 'policy.pdf', contentType: 'application/pdf' });
+const docs = await Policies.documents();   // 'processing' | 'done' | 'error'
+await Policies.remove(documentId);
+```
+
+Formats: pdf, docx, pptx, xlsx, odt, rtf, epub, images, txt, md, json, csv, tsv, log, html.
+
+## 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.
+
+## Tuning — two kinds of setting
+
+| Kind | Settings | Cost |
+|---|---|---|
+| **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.
+
+`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:
+
+```bash
+mindstudio-prod datasources revectorize --source policies --max-chars 900 --wait
+mindstudio-prod datasources search --source policies --candidate "payment terms"   # compare
+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.
+
+For anything deeper on the SDK, ask `askMindStudioSdk` rather than guessing at an API.

package/dist/prompt/skills/mcpInterfaces.md

@@ -0,0 +1,80 @@
+---
+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.
+---
+
+# Building 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.
+
+## 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:
+
+```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
+```
+
+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.

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/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.

package/dist/subagents/browserAutomation/prompt.md

@@ -43,6 +43,7 @@ Note: the snapshot concatenates inline text and strips whitespace. If you need t
 - `navigate`: Navigate to a new URL within the app. Waits for the new page to load before continuing with subsequent steps. Use this instead of evaluate with `window.location.href` when you need to navigate and then continue interacting with the new page. Steps after navigate execute on the new page automatically.
 - `evaluate`: Run arbitrary JavaScript in the page and return the result.
 - `styles`: Read computed CSS styles from page elements. Pass a `properties` array with camelCase CSS property names (e.g., `["backgroundColor", "borderRadius", "fontSize"]`). Omit `properties` for a default set covering colors, typography, spacing, borders, shadows, dimensions, and layout. Uses the same targeting as click/type (ref, text, role, label, selector). Omit the target to get styles for all elements from the last snapshot.
+- `screenshotFullPage`: Take a screenshot of the whole page, top to bottom. Returns CDN url with full text analysis and dimensions. Use for overall composition or content past the fold.
 - `screenshotViewport`: Take a screenshot of the visible viewport. Returns CDN url with full text analysis and dimensions. To capture a specific section, set `scrollToSelector` (a CSS selector) — or `scrollY` (an absolute offset) — on this same step; it scrolls the target into view and captures it atomically, so you do NOT need a separate scroll step. Do not use if you can get what you need with other tools - only use when you need to visually see the viewport.
 - `setViewport`: Switch the browser between desktop and mobile rendering. Set `mode` to `"desktop"` or `"mobile"`. Mobile emulates a phone (390-wide, touch, device pixel ratio 2); desktop is the standard wide viewport. This reloads the page so media queries, responsive layouts, and `matchMedia` re-evaluate — the reload clears in-page state, so switch before you set up the state you want to inspect. The mode persists across navigations within a run. Each run starts in the app's default mode, so only use this when you need to check the other one.
 
@@ -161,7 +162,7 @@ Check a count with evaluate:
 
 ### Final Screenshot
 How you take the final screenshot depends on what the task asked for:
-- **Whole page** → use the standalone `screenshotFullPage` tool. It takes a full-height screenshot of the current page and returns the URL plus a full-text description.
+- **Whole page** → use a `browserCommand` batch ending in a `screenshotFullPage` step. Returns the URL plus a full-text description.
 - **A specific section / viewport** → use a `browserCommand` batch ending in a `screenshotViewport` step with `scrollToSelector` set to the section (e.g. `{ "command": "screenshotViewport", "scrollToSelector": "#pricing" }`). This scrolls the section into view and captures it in one atomic step. Do this rather than a separate scroll step followed by a capture — capturing the viewport is only reliable when the scroll and the shot are in the same step.
 
 <rules>

package/dist/subagents/designExpert/prompts/images.md

@@ -20,7 +20,7 @@ Generated images are production assets, not mockups or concepts — they are hos
 
 ### Image editing
 
-Use `editImages` to transform or build on existing images. Provide one or more source image URLs and a prompt describing the desired result. The source images act as reference material — the model uses them as anchors for style, subject, or composition. Think about image editing as part of a pipeline for generating a final asset from constituent pieces.
+Use `editImages` to transform or build on existing images. Provide one or more source images — a URL, or the path of an image file on disk such as a logo the user uploaded — and a prompt describing the desired result. The source images act as reference material — the model uses them as anchors for style, subject, or composition. Think about image editing as part of a pipeline for generating a final asset from constituent pieces.
 
 Good use cases for editing:
 - Incorporating a logo or brand mark into a product mockup or scene

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.255",
+  "version": "0.1.257",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch",
+    "dev": "tsup --watch src",
     "typecheck": "tsc --noEmit",
     "lint:fix": "prettier --write ./src",
     "local-update": "npm run build && npm link",