@mindstudio-ai/remy 0.1.8 → 0.1.10

package/dist/prompt/compiled/msfm.md

@@ -0,0 +1,189 @@
+# MSFM — MindStudio-Flavored Markdown
+
+Specs are written in MSFM, a strict superset of Markdown that adds **block annotations** and **inline annotations**. Annotations attach precision to prose so the compiler produces consistent results. A bare spec with no annotations is valid — each annotation makes compilation more deterministic.
+
+## Block Annotations
+
+A tilde-fenced block (`~~~`) that attaches to the content immediately above it:
+
+```markdown
+When requesting a new vendor, there are three areas of review:
+governance, legal, and accounting, with approvals flowing in that order.
+
+~~~
+The spec says "three areas" but lists four names. From the process
+flowchart, it is three sequential stages:
+
+  1. Governance, Risk & Compliance (GRC) — one combined stage
+  2. Legal
+  3. Accounts Payable (AP)
+
+These are sequential. Each stage must complete before the next is
+notified. If any stage rejects, the entire request is rejected.
+~~~
+```
+
+**Rules:**
+- Starts and ends with `~~~` on its own line
+- Attaches to the nearest preceding block element (paragraph, heading, table, list)
+- Multiple annotations can follow the same element (read in order)
+- Can contain any Markdown content (use backtick code fences inside — they coexist with tilde fences)
+
+## Inline Annotations
+
+Attach to a specific word or phrase with `[text]{content}`:
+
+```markdown
+All invoices can be sent to the [Accounts Payable]{The AP team in
+this context refers to the internal accounts payable department, not
+a vendor's AP. Only users with the "ap" or "admin" role can process
+invoices.} team for processing against the PO.
+```
+
+Good for definitions, units, and clarifications:
+
+```markdown
+The PO [amount]{Total across all line items, in USD cents (integer).
+Does not include tax, shipping, or fees.} must not exceed the approved
+budget for the [cost center]{The organizational budget code that this
+purchase is charged to.}.
+```
+
+## Pointers
+
+When an annotation is too large for inline placement, use a pointer — an inline `{#id}` reference that points to a `~~~#id` block:
+
+```markdown
+The AP team pays the vendor according to the [contract payment terms]{#payment-terms}.
+
+~~~#payment-terms
+We do not model payment terms (net 30, net 60, etc.) on the PO or
+vendor. The dueDate on the invoice is the sole payment trigger.
+
+A production implementation would:
+- Store terms on the vendor record (net_30, net_60, due_on_receipt)
+- Auto-calculate dueDate from invoiceDate + terms
+- Support early payment discounts (2/10 net 30)
+
+Default behavior when no terms are specified: due on receipt.
+~~~
+```
+
+Keep the block co-located (right after the paragraph containing the pointer). A single block annotation can be referenced by multiple pointers — useful for concepts like "amounts are in USD cents" that apply in several places.
+
+## Authoring Conventions
+
+**Specs are written in human language for humans.** The prose should describe what the app does the way you'd explain it to a colleague — not in code. No variable names, table names, column types, or function signatures in the prose. Technical details like column types, data representations, and implementation notes belong in annotations, where they serve as precision hints for the compiler without cluttering the readable spec.
+
+Good: "The app remembers every greeting it generates, along with who it was for."
+Bad: "One table: `greetings` with two columns: `name` (string) and `greeting` (string)."
+
+The annotation for the good version might be: `~~~\nOne table. Columns: the person's name (string) and the generated greeting text (string).\n~~~`
+
+**Use inline annotations liberally.** Inline annotations (`[text]{content}`) are the primary annotation tool — use them the way you'd use comments in Google Docs, attached to the specific word or phrase that needs clarification. When the prose says "the user submits a [request]{Must include vendor name, contact email, and tax ID. All fields required.} for review," the annotation is pinned to exactly the word that's ambiguous.
+
+Block annotations (`~~~...~~~`) are for longer notes that don't attach to a single word — implementation notes, edge case lists, multi-line technical details. But most annotations should be inline. A spec where every annotation is a block annotation under a heading is under-annotated — it means the prose itself isn't being examined for ambiguity at the word level.
+
+**Annotations support full markdown.** Use backticks for code and variable names, lists for enumerating options, code blocks for snippets. This keeps the prose clean while giving the compiler precise technical detail:
+
+```markdown
+Each invoice has a [status]{One of: `pending_review`, `approved`, `rejected`, `paid`. Transitions:
+- `pending_review` → `approved` or `rejected` (by AP)
+- `approved` → `paid` (automatic on payment date)
+- `rejected` → `pending_review` (if resubmitted)} that tracks where it is in the review process.
+```
+
+**Annotate ambiguity, not the obvious.** If a statement has only one reasonable interpretation, leave it alone. Annotations resolve genuine ambiguity — places where two engineers might implement different things.
+
+**Pin down edge cases.** The most valuable annotations answer "what happens when...":
+- What happens when a reviewer rejects?
+- What happens when the amount is exactly on the threshold?
+- What happens when no user has the required role?
+- What happens when this is called twice?
+
+**Specify data when it matters.** When "amount" could mean integer cents or decimal dollars, annotate the representation. When "status" could be any string, list the valid values. These are perfect for inline annotations: `The PO [amount]{Total across all line items, in USD cents (integer). Does not include tax, shipping, or fees.} must not exceed the budget.`
+
+**Let the spec breathe.** A spec with more annotation than prose is over-specified. Annotate the hard parts. Trust the compiler on the straightforward parts.
+
+## Spec Structure
+
+A spec starts with YAML frontmatter followed by freeform Markdown. There's no mandated structure — use headings, prose, tables, lists, whatever makes sense for the domain.
+
+**Frontmatter fields:**
+- `name` (required) — display name for the spec file
+- `description` (optional) — short summary of what this file covers
+- `type` (optional) — defaults to `spec`. Other values: `design/color` (color palette definition), `design/typography` (font and type style definition). The frontend renders these types with specialized editors.
+
+```markdown
+---
+name: Expense Tracker
+description: Core application spec
+---
+
+# Expense Tracker
+
+[High-level description]
+
+~~~
+[Clarifying annotations — roles, key constraints]
+~~~
+
+## [Domain Section]
+
+[Prose describing the workflow]
+
+~~~
+[Edge cases, data representations, business rules]
+~~~
+```
+
+Color design spec example (3-5 brand colors with evocative names):
+
+```markdown
+---
+name: Colors
+type: design/color
+---
+
+```colors
+Midnight:
+  value: "#000000"
+  description: Primary background and dark surfaces
+Snow:
+  value: "#F5F5F7"
+  description: Primary text and foreground elements
+Smoke:
+  value: "#86868B"
+  description: Secondary text and supporting content
+```
+```
+
+Typography design spec example (fonts with source URLs, 1-2 anchor styles):
+
+```markdown
+---
+name: Typography
+type: design/typography
+---
+
+```typography
+fonts:
+  Satoshi:
+    src: https://api.fontshare.com/v2/css?f[]=satoshi@400,500,600,700&display=swap
+
+styles:
+  Display:
+    font: Satoshi
+    size: 40px
+    weight: 600
+    letterSpacing: -0.03em
+    lineHeight: 1.1
+    description: Page titles and hero text
+  Body:
+    font: Satoshi
+    size: 16px
+    weight: 400
+    lineHeight: 1.5
+    description: Default reading text
+```
+```

package/dist/prompt/compiled/platform.md

@@ -0,0 +1,103 @@
+# MindStudio Platform
+
+A MindStudio app has three layers: a **spec** (natural language in `src/`), a **backend contract** (methods, tables, roles in `dist/`), and **interfaces** (web, API, bots, cron, etc. — also in `dist/`). The spec is the source of truth; the code is a derivation.
+
+`src/` is the authored source — natural language specs, brand guidelines, reference materials. No code. `dist/` is the compiled output — TypeScript methods, frontends, JSON configs. You can edit `dist/` directly, but `src/` is the reset point. Regenerate `dist/` from `src/` at any time.
+
+## Directory Layout
+
+```
+my-app/
+  mindstudio.json                    ← manifest (declares everything)
+
+  src/                               ← authored source (no code)
+    app.md                             backend spec (MSFM)
+    references/                        supporting material (PDFs, notes, diagrams)
+    interfaces/
+      @brand/                          shared brand identity
+        visual.md                        aesthetic direction, surfaces, spacing
+        colors.md                        brand color palette (type: design/color)
+        typography.md                    fonts and type styles (type: design/typography)
+        voice.md                         tone, terminology, error messages
+        assets/                          logos, icons
+      web.md                           web UI spec
+      api.md                           API conventions
+      cron.md                          scheduled job descriptions
+
+  dist/                              ← compiled output (code + config)
+    methods/                           backend contract
+      src/
+        tables/                          one file per table (TypeScript interfaces)
+        common/                          shared helpers (imported by methods, not methods themselves)
+        *.ts                             one file per method (named async function export)
+      .scenarios/                      seed data scripts (dev only, not deployed)
+      package.json                     backend dependencies
+
+    interfaces/                        interface projections
+      web/                               full project directory (Vite + React)
+        web.json                           dev server config
+        package.json
+        src/
+      api/interface.json                 REST API config
+      discord/interface.json             Discord bot config
+      telegram/interface.json            Telegram bot config
+      cron/interface.json                cron config
+      webhook/interface.json             webhook config
+      email/interface.json               email config
+      mcp/interface.json                 MCP config
+```
+
+## What Goes Where
+
+| What | Where | Notes |
+|------|-------|-------|
+| Method handlers | `dist/methods/src/*.ts` | One file per method, named export |
+| Table definitions | `dist/methods/src/tables/*.ts` | One file per table |
+| Shared helpers | `dist/methods/src/common/*.ts` | Imported by methods, not invokable directly |
+| Scenarios | `dist/methods/.scenarios/*.ts` | Seed data for testing (not deployed) |
+| Backend dependencies | `dist/methods/package.json` | Only declared packages are available at runtime |
+| Web interface | `dist/interfaces/web/` | Full Vite + React project directory |
+| Interface configs | `dist/interfaces/*/interface.json` | One per non-web interface type |
+| Specs | `src/*.md` | Natural language, MSFM format |
+| Brand identity | `src/interfaces/@brand/` | visual.md (aesthetic), colors.md (palette), typography.md (fonts), voice.md (tone), assets/ |
+| Reference material | `src/references/` | Context for the agent, not consumed by platform |
+
+## The Two SDKs
+
+**Backend: `@mindstudio-ai/agent`** — used inside methods. Provides `db` (database), `auth` (access control), and platform capabilities (AI, integrations, connectors). Pre-installed in the sandbox; must also be declared in `dist/methods/package.json`.
+
+```typescript
+import { db, auth } from '@mindstudio-ai/agent';
+```
+
+**Frontend: `@mindstudio-ai/interface`** — used in the web interface. Typed RPC to backend methods.
+
+```typescript
+import { createClient } from '@mindstudio-ai/interface';
+
+const api = createClient<{
+  approveVendor(input: { vendorId: string }): Promise<{ vendor: Vendor }>;
+}>();
+
+const { vendor } = await api.approveVendor({ vendorId: '...' });
+```
+
+## What the Platform Provides
+
+- **Managed databases.** SQLite with typed schemas. Push a schema change and the platform diffs, migrates, and promotes atomically.
+- **Built-in auth.** Define roles in the manifest, call `auth.requireRole('admin')` in methods. Platform handles sessions, tokens, user resolution.
+- **Multiple interfaces, one codebase.** Web, API, Discord, Telegram, Cron, Webhook, Email, MCP — all invoke the same methods. Methods don't know which interface called them.
+- **Sandboxed execution.** Methods run in isolated sandboxes with npm packages pre-installed.
+- **Git-native deployment.** Push to default branch to deploy. Push to feature branch for preview. Rollback is a git revert.
+
+## Minimum Viable App
+
+```
+my-app/
+  mindstudio.json
+  dist/methods/
+    src/hello.ts
+    package.json
+```
+
+One manifest, one method, one package.json. The method is accessible via API key.

package/dist/prompt/compiled/scenarios.md

@@ -0,0 +1,103 @@
+# Scenarios
+
+Scenarios are seed scripts that set up the dev database into a specific state for testing. Instead of manually creating data through the app, run a scenario and get a repeatable starting point. A scenario is just an async function that uses the same `db.push()` calls as methods — no new API to learn.
+
+## Defining Scenarios
+
+In `mindstudio.json`:
+
+```json
+{
+  "scenarios": [
+    {
+      "id": "ap-overdue-invoices",
+      "name": "AP: Overdue Invoices",
+      "description": "AP user with two invoices past due date.",
+      "path": "dist/methods/.scenarios/apOverdueInvoices.ts",
+      "export": "apOverdueInvoices",
+      "roles": ["ap"]
+    },
+    {
+      "id": "empty-requester",
+      "name": "Empty Requester",
+      "description": "Brand new user, no data.",
+      "path": "dist/methods/.scenarios/emptyRequester.ts",
+      "export": "emptyRequester",
+      "roles": ["requester"]
+    }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `id` | Kebab-case identifier |
+| `name` | Display name (shown in dev panel) |
+| `description` | What state this scenario creates |
+| `path` | Path to the TypeScript file |
+| `export` | Named export (the async function) |
+| `roles` | Roles to impersonate after seeding |
+
+## Writing a Scenario
+
+Scenarios live at `dist/methods/.scenarios/` — inside the methods package scope. `@mindstudio-ai/agent` resolves from `dist/methods/node_modules/` and table imports are relative.
+
+```typescript
+// dist/methods/.scenarios/apOverdueInvoices.ts
+
+import { db } from '@mindstudio-ai/agent';
+import { Vendors } from '../src/tables/vendors';
+import { PurchaseOrders } from '../src/tables/purchase-orders';
+import { Invoices } from '../src/tables/invoices';
+
+export async function apOverdueInvoices() {
+  const vendor = await Vendors.push({
+    name: 'Acme Corp',
+    contactEmail: 'billing@acme.com',
+    status: 'approved',
+  });
+
+  const po = await PurchaseOrders.push({
+    vendorId: vendor.id,
+    requestedBy: 'user-requester-1',
+    totalAmountCents: 500000,
+    status: 'active',
+  });
+
+  await Invoices.push([
+    {
+      poId: po.id,
+      invoiceNumber: 'INV-001',
+      amountCents: 150000,
+      dueDate: db.ago(db.days(5)),
+      status: 'pending_review',
+    },
+    {
+      poId: po.id,
+      invoiceNumber: 'INV-002',
+      amountCents: 100000,
+      dueDate: db.ago(db.days(2)),
+      status: 'approved',
+    },
+  ]);
+}
+```
+
+An empty scenario is valid — it exists so you can switch to "clean slate" state:
+
+```typescript
+export async function emptyRequester() {
+  // No data — the truncate clears everything.
+}
+```
+
+Shared setup code can go in `dist/methods/.scenarios/_helpers/`.
+
+## How Scenarios Run
+
+When a scenario runs, the platform:
+1. **Truncates** all tables (deletes all rows, preserves schema)
+2. **Executes** the seed function (your `db.push()` calls populate the clean database)
+3. **Impersonates** the roles from the scenario's `roles` field (the app renders from that user's perspective)
+
+This is deterministic — same scenario always produces the same state.

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

@@ -0,0 +1,146 @@
+# MindStudio Agent SDK
+
+`@mindstudio-ai/agent` provides access to 200+ AI models and 1,000+ actions through a single API key. No separate provider keys needed. MindStudio routes to the correct provider (OpenAI, Anthropic, Google, etc.) server-side.
+
+There is a huge amount of capability here: hundreds of text generation models (OpenAI, Anthropic, Google, Meta, Mistral, and more), dozens of image generation models (FLUX, DALL-E, Stable Diffusion, Ideogram, and more), video generation, text-to-speech, music generation, vision analysis, web scraping, 850+ OAuth connectors, and much more. The tables below are a summary. **Always use the `askMindStudioSdk` tool to look up exact method signatures, model IDs, and config options before writing code that uses the SDK.** The SDK assistant knows every action, every model, every connector, and the user's configured OAuth connections. Don't guess at parameters or model IDs from memory.
+
+## Usage in Methods
+
+Inside a MindStudio app method, create an instance with no arguments — credentials come from the execution environment:
+
+```typescript
+import { MindStudioAgent } from '@mindstudio-ai/agent';
+
+const agent = new MindStudioAgent();
+```
+
+Every action is a method on the agent instance:
+
+```typescript
+const { content } = await agent.generateText({ message: 'Summarize this...' });
+```
+
+Results are returned flat — output fields at the top level alongside metadata:
+
+```typescript
+const result = await agent.generateText({ message: 'Hello' });
+result.content;              // step-specific output
+result.$billingCost;         // cost in credits (if applicable)
+```
+
+## Available Actions
+
+### AI Generation
+
+| Action | What it does | Key input | Key output |
+|--------|-------------|-----------|------------|
+| `generateText` | Text generation with any LLM | `message`, `modelOverride?` | `content` |
+| `generateImage` | Image from text prompt | `prompt`, `modelOverride?` | `imageUrl` |
+| `generateVideo` | Video from text/image | `prompt`, `imageUrl?` | `videoUrl` |
+| `textToSpeech` | Text to spoken audio | `text`, `modelOverride?` | `audioUrl` |
+| `generateMusic` | Music from text description | `prompt` | `audioUrl` |
+| `generateLipsync` | Animate face to match audio | `imageUrl`, `audioUrl` | `videoUrl` |
+| `generateAsset` | HTML/PDF/PNG/video output | `prompt` | `assetUrl` |
+| `generateChart` | Chart from data | `data`, `chartType` | `imageUrl` |
+
+### AI Analysis
+
+| Action | What it does | Key input | Key output |
+|--------|-------------|-----------|------------|
+| `analyzeImage` | Vision model analysis | `prompt`, `imageUrl` | `analysis` |
+| `analyzeVideo` | Video analysis | `prompt`, `videoUrl` | `analysis` |
+| `transcribeAudio` | Audio to text | `audioUrl` | `transcription` |
+| `extractText` | Extract text from documents/images | `url` | `text` |
+| `detectPII` | Find personal data | `text` | `entities` |
+
+### Web & Search
+
+| Action | What it does | Key input | Key output |
+|--------|-------------|-----------|------------|
+| `scrapeUrl` | Extract page content | `url` | `markdown` |
+| `searchGoogle` | Google search | `query` | `results` |
+| `searchGoogleImages` | Image search | `query` | `results` |
+| `searchGoogleNews` | News search | `query` | `results` |
+| `searchPerplexity` | AI-powered search | `query` | `answer` |
+| `httpRequest` | Custom HTTP call | `url`, `method`, `headers?`, `body?` | `response` |
+
+### Communication
+
+| Action | What it does | Key input | Key output |
+|--------|-------------|-----------|------------|
+| `sendEmail` | Send an email | `to`, `subject`, `body` | `messageId` |
+| `sendSMS` | Send a text message | `to`, `message` | `messageId` |
+| `postToSlackChannel` | Post to Slack | `channel`, `message` | — |
+
+### Media Processing
+
+| Action | What it does |
+|--------|-------------|
+| `removeBackgroundFromImage` | Remove image background |
+| `upscaleImage` | Upscale image resolution |
+| `imageFaceSwap` | Swap faces in an image |
+| `imageRemoveWatermark` | Remove watermarks |
+| `mergeVideos` | Concatenate video clips |
+| `trimMedia` | Trim audio/video |
+| `addSubtitlesToVideo` | Auto-generate subtitles |
+| `extractAudioFromVideo` | Extract audio track |
+| `captureThumbnail` | Get video thumbnail |
+
+### Files & Data
+
+| 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 |
+
+### Third-Party Integrations (OAuth Connectors)
+
+850+ additional actions from the MindStudio Connector Registry, covering services like HubSpot, Salesforce, Airtable, Google Workspace, Notion, Coda, and many more. These require OAuth connections set up by the user in MindStudio.
+
+Built-in connector methods include: ActiveCampaign, Airtable, Apollo, Coda, Facebook, Gmail, Google Docs/Sheets/Calendar/Drive, HubSpot, Hunter.io, Instagram, LinkedIn, Notion, X (Twitter), YouTube.
+
+For other services, use `runFromConnectorRegistry`:
+
+```typescript
+// Discover available connectors
+const { connectors } = await agent.listConnectors();
+
+// Get action details
+const action = await agent.getConnectorAction('hubspot', 'create-contact');
+
+// Execute
+const result = await agent.runFromConnectorRegistry({
+  serviceId: 'hubspot',
+  actionId: 'create-contact',
+  input: { email: 'user@example.com', firstName: 'Alice' },
+});
+```
+
+### Model Selection
+
+Override the default model for any AI action. Each model has its own config options (dimensions, seed, inference steps, etc.) so always use `askMindStudioSdk` to look up the correct config before specifying a model override:
+
+```typescript
+const { content } = await agent.generateText({
+  message: 'Hello',
+  modelOverride: {
+    model: 'claude-sonnet-4-6',
+    temperature: 0.7,
+    maxResponseTokens: 1024,
+  },
+});
+```
+
+### Batch Execution
+
+Run up to 50 actions in parallel:
+
+```typescript
+const result = await agent.executeStepBatch([
+  { stepType: 'generateImage', step: { prompt: 'a sunset' } },
+  { stepType: 'textToSpeech', step: { text: 'hello world' } },
+]);
+// result.results[0].output, result.results[1].output
+```