@mindstudio-ai/remy 0.1.0

package/dist/compiled/methods.md

@@ -0,0 +1,225 @@
+# Methods
+
+A method is a named async function that runs on the platform. It's the universal unit of backend logic — every interface (web, API, Discord, cron, webhook) invokes methods. Methods run in isolated sandboxes. One file per method, one named export.
+
+## Writing a Method
+
+```typescript
+// dist/methods/src/submitVendorRequest.ts
+
+import { db, auth } from '@mindstudio-ai/agent';
+import { Vendors } from './tables/vendors';
+
+export async function submitVendorRequest(input: {
+  name: string;
+  contactEmail: string;
+  taxId: string;
+}) {
+  auth.requireRole('requester');
+
+  const vendor = await Vendors.push({
+    name: input.name,
+    contactEmail: input.contactEmail,
+    taxId: input.taxId,
+    status: 'pending',
+    requestedBy: auth.userId,
+  });
+
+  return { vendorId: vendor.id, status: vendor.status };
+}
+```
+
+### Manifest Entry
+
+```json
+{
+  "id": "submit-vendor-request",
+  "name": "Submit Vendor Request",
+  "path": "dist/methods/src/submitVendorRequest.ts",
+  "export": "submitVendorRequest"
+}
+```
+
+- `id` — kebab-case, used in API URLs (the platform maps these internally)
+- **Important:** the frontend `createClient` uses the camelCase `export` name, not the kebab-case `id`. Call `api.submitVendorRequest()`, not `api['submit-vendor-request']()`.
+- `path` — relative to project root
+- `export` — must match the function name
+
+### Input and Output
+
+Methods receive a single `input` parameter (an object) and return an object. Both are JSON-serializable. If no input is needed, the parameter can be omitted or typed as `{}`.
+
+```typescript
+export async function getDashboard(input: {
+  period?: 'week' | 'month' | 'quarter';
+}) {
+  const period = input.period || 'month';
+  // ...
+  return {
+    pendingApprovals,
+    recentOrders,
+    stats: { totalSpend, vendorCount },
+  };
+}
+```
+
+## Platform Capabilities
+
+The `@mindstudio-ai/agent` SDK provides access to 200+ AI models and 1,000+ actions (email, SMS, web scraping, file uploads, third-party integrations, and more). Inside a method, create an instance and call actions directly. No constructor arguments needed — credentials are picked up automatically from the execution environment:
+
+```typescript
+import { MindStudioAgent } from '@mindstudio-ai/agent';
+
+const agent = new MindStudioAgent();
+
+// AI text generation
+const { content } = await agent.generateText({
+  message: 'Summarize this invoice...',
+});
+
+// AI image generation
+const { imageUrl } = await agent.generateImage({
+  prompt: 'A professional headshot placeholder',
+});
+
+// Send email
+await agent.sendEmail({
+  to: 'user@example.com',
+  subject: 'Your invoice',
+  body: content,
+});
+
+// Upload files
+const { url } = await agent.uploadFile({
+  data: buffer,
+  fileName: 'report.pdf',
+});
+
+// Web scraping
+const { markdown } = await agent.scrapeUrl({
+  url: 'https://example.com',
+});
+
+// Resolve user display info
+const { displayName, email } = await agent.resolveUser({
+  userId,
+});
+```
+
+No separate API keys needed — the platform routes to the correct provider (OpenAI, Anthropic, Google, etc.) automatically.
+
+## Error Handling
+
+Throw errors with messages that make sense to end users — these may surface in the UI:
+
+```typescript
+export async function approveVendor(input: { vendorId: string }) {
+  auth.requireRole('admin', 'grc');
+
+  const vendor = await Vendors.get(input.vendorId);
+  if (!vendor) {
+    throw new Error('Vendor not found.');
+  }
+
+  if (vendor.status !== 'pending') {
+    throw new Error('This vendor has already been reviewed.');
+  }
+
+  // ...
+}
+```
+
+`auth.requireRole()` throws a 403 automatically if the user doesn't have the required role.
+
+## Common Patterns
+
+### CRUD Method
+
+```typescript
+export async function listVendors(input: {
+  status?: string;
+  search?: string;
+}) {
+  const vendors = await Vendors
+    .filter(v => {
+      if (input.status && v.status !== input.status) return false;
+      if (input.search && !v.name.includes(input.search)) return false;
+      return true;
+    })
+    .sortBy(v => v.name);
+
+  return { vendors };
+}
+```
+
+### Role-Gated Operation
+
+```typescript
+export async function deleteVendor(input: { vendorId: string }) {
+  auth.requireRole('admin');
+
+  const vendor = await Vendors.get(input.vendorId);
+  if (!vendor) throw new Error('Vendor not found.');
+
+  await Vendors.remove(input.vendorId);
+  return { success: true };
+}
+```
+
+### Multi-Table Transaction
+
+```typescript
+export async function createPurchaseOrder(input: {
+  vendorId: string;
+  lineItems: Array<{ description: string; amount: number }>;
+}) {
+  auth.requireRole('requester');
+
+  const vendor = await Vendors.get(input.vendorId);
+  if (!vendor || vendor.status !== 'approved') {
+    throw new Error('Vendor must be approved before creating a PO.');
+  }
+
+  const total = input.lineItems.reduce((sum, li) => sum + li.amount, 0);
+
+  const po = await PurchaseOrders.push({
+    vendorId: input.vendorId,
+    requestedBy: auth.userId,
+    lineItems: input.lineItems,
+    totalAmountCents: total,
+    status: 'pending_approval',
+  });
+
+  return { purchaseOrderId: po.id, total };
+}
+```
+
+## Shared Helpers
+
+Code shared between methods goes in `dist/methods/src/common/`. Helpers are not listed in the manifest — they're internal, imported by methods but not directly invocable.
+
+```typescript
+// dist/methods/src/common/getApprovalState.ts
+export function getApprovalState(approvals: Approval[]) {
+  const allApproved = approvals.every(a => a.status === 'approved');
+  const anyRejected = approvals.some(a => a.status === 'rejected');
+  // ...
+}
+```
+
+## Streaming
+
+Methods can stream token-by-token output (useful for AI-generated content):
+
+```typescript
+// Frontend
+const result = await api.generateReport(
+  { month: 'march' },
+  {
+    stream: true,
+    onToken: (text) => setPreview(text),
+  },
+);
+```
+
+The platform handles the SSE transport. The method returns normally — streaming is managed by the SDK and platform, not by your method code.

package/dist/compiled/msfm.md

@@ -0,0 +1,133 @@
+# 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 (`name`, `description`, `version`) followed by freeform Markdown. There's no mandated structure — use headings, prose, tables, lists, whatever makes sense for the domain.
+
+```markdown
+---
+name: Expense Tracker
+version: 1
+---
+
+# Expense Tracker
+
+[High-level description]
+
+~~~
+[Clarifying annotations — roles, key constraints]
+~~~
+
+## [Domain Section]
+
+[Prose describing the workflow]
+
+~~~
+[Edge cases, data representations, business rules]
+~~~
+```

package/dist/compiled/platform.md

@@ -0,0 +1,101 @@
+# 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
+        voice.md                         tone, terminology, error messages
+        visual.md                        colors, typography, components
+        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/` | voice.md (tone, terminology), visual.md (colors, typography), 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/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.