@mindstudio-ai/remy 0.1.0

package/dist/compiled/design.md

@@ -0,0 +1,173 @@
+# Frontend Design Notes
+
+Design standards for web interfaces in MindStudio apps.
+
+## Quality Bar
+
+Every interface must feel like a polished, shipping product — not a
+prototype, not a starter template, not a homework assignment. The standard
+is iOS and Apple's bundled iOS apps, Notion, Stripe. If it wouldn't look
+good on Dribbble, Behance, or Mobbin, it's not done.
+
+MindStudio apps are end-user products. The interface is the product. Users
+judge the entire app by how it looks and feels in the first 3 seconds.
+
+## Be Distinctive
+
+AI-generated interfaces tend to converge on the same generic look: safe
+fonts, timid colors, predictable layouts. Fight this actively. Every
+interface should have character and intentionality — it should look like a
+designer made deliberate choices, not like it was generated from a template.
+
+**Typography must be a conscious choice.** Pick fonts that are beautiful,
+distinctive, and appropriate for the product's personality. Generic system
+fonts and overused defaults make everything look the same. Typography is
+the single fastest way to give an interface identity.
+
+**Commit to a color palette.** One or two dominant colors with sharp accents
+outperform timid, evenly-distributed palettes. Draw inspiration from the
+app's domain — a finance tool might use deep greens and golds; a creative
+tool might use bold, saturated primaries. The palette should feel intentional
+and owned, not randomly selected.
+
+**Backgrounds create atmosphere.** Solid white or solid gray is the safe
+default and the enemy of distinctiveness. Layer subtle gradients, use warm
+or cool tints, add geometric patterns or contextual textures. The background
+sets the mood before the user reads a single word.
+
+**Layouts should surprise.** Avoid the predictable patterns: three equal
+boxes with icons, centered hero with subtitle, generic card grid. Use
+asymmetry, varied column widths, creative negative space, unexpected
+compositions. Study Behance and Mobbin for layout inspiration. Every screen
+should feel considered, not generated.
+
+## App-Like, Not Web-Page-Like
+
+Interfaces run fullscreen in the user's browser or a wrapped webview mobile
+app. They should feel like native apps, not websites.
+
+- **No long scrolling pages.** Use structured layouts: cards, split panes,
+  steppers, tabs, grouped sections that fit the viewport. The interface
+  should feel like a single-purpose tool, not a document.
+- **On mobile**, scrolling may be necessary, but use sticky headers, fixed
+  CTAs, and anchored navigation to keep key actions within reach.
+- Think of every screen as something the user opens, uses, and closes —
+  not something they read.
+
+## Visual Design
+
+- **Typography:** Strong hierarchy — clear distinction between headings,
+  body, labels, and captions. Use weight and size, not just color, to
+  create hierarchy. Choose fonts that elevate the interface and give it
+  personality.
+- **Color:** Clean, vibrant, intentional. Use color to communicate state
+  and guide attention, not to decorate. Commit to a direction — bold and
+  saturated, or muted and editorial — and follow through consistently.
+- **Spacing:** Consistent and generous. Padding and margins should be
+  uniform across all components — nothing should feel cramped or uneven.
+  White space is a feature, not wasted space.
+- **Components:** Every component (buttons, inputs, cards, modals, lists)
+  should look like it belongs to the same design system. Consistent border
+  radii, consistent shadows, consistent padding. If two buttons on the
+  same screen look different for no reason, that's a bug.
+
+## Animation
+
+Use motion to make interactions feel polished, not to show off. Focus on
+high-impact moments: a well-orchestrated page load with staggered reveals
+creates more delight than scattered micro-interactions everywhere.
+
+- Transitions between states should be smooth but fast.
+- Streaming content should flow into containers that grow naturally without
+  pushing sibling elements around.
+- No parallax, no cheesy scroll effects, no bounce/elastic easing, no
+  gratuitous loading animations.
+
+## Layout Stability
+
+Layout shift is never acceptable. Elements jumping around as content loads
+or streams in makes an interface feel broken.
+
+- Reserve space for content that hasn't arrived yet. Use fixed/min-height
+  containers, skeletons, or aspect-ratio boxes.
+- Images must always have explicit dimensions so the browser reserves space
+  before the image loads.
+- Loading-to-loaded transitions should swap content in-place without
+  changing container size.
+- Conditional UI should use opacity/overlay transitions, not insertion into
+  flow that displaces existing content.
+
+## Responsive Design
+
+Every interface must work on both desktop and mobile.
+
+- Use the full viewport. Backgrounds should extend to edges.
+- On desktop, use the space — multi-column layouts, sidebars, spacious
+  cards. Avoid narrow centered columns with empty gutters on a wide screen.
+- On mobile, stack gracefully. Prioritize content and actions.
+- Test at both extremes. A layout that only looks good at one breakpoint
+  is not done.
+
+## Forms
+
+Forms should feel like interactions, not paperwork.
+
+- Group related fields visually. Use cards or sections, not a flat list.
+- Inline validation — show errors as the user types, not after submit.
+  Validation must never introduce layout shift.
+- Loading states after submission. Always indicate that something is
+  happening.
+- Disabled states should be visually distinct but not jarring.
+- Even data entry can be beautiful. Pay attention to alignment, padding,
+  and spacing. Consistency is key.
+
+## What Good Looks Like
+
+- A dashboard that feels like Linear — clean data, clear hierarchy, every
+  pixel intentional.
+- A form that feels like Stripe Checkout — focused, calm, confident.
+- A settings page that feels like iOS Settings — organized, scannable,
+  no clutter.
+- A list view that feels like Notion — flexible, spacious, information-dense
+  without feeling crowded.
+
+## What to Actively Avoid
+
+These are the hallmarks of generic AI-generated interfaces. Every one of
+them makes an interface look like it was auto-generated rather than designed.
+
+- **Generic fonts.** Overused defaults that strip away all personality.
+  Instead: pick a distinctive Google Font that fits the app's character.
+- **Purple or indigo anything.** Purple gradients, purple buttons, purple
+  accents. This is the #1 AI-generated aesthetic cliché. Instead: use
+  a color palette that fits the app's domain — greens for finance, warm
+  neutrals for productivity, bold primaries for creative tools, or just
+  confident grayscale.
+- **Colored left-border callout boxes.** Rounded divs with a thick colored
+  `border-left` — the generic "info card" pattern. Instead: use typography,
+  spacing, and background tints to create hierarchy. If you need to call
+  something out, use a full subtle background or a top border.
+- **Three equal boxes with icons.** The default AI landing page layout.
+  Instead: use asymmetric layouts, varied column widths, or a single
+  focused content area.
+- **Timid color palettes.** Evenly distributed, non-committal colors.
+  Instead: one or two dominant colors with sharp accents. Commit to a
+  direction.
+- **Card-heavy nested layouts.** Cards inside cards, everything boxed.
+  Instead: use space, typography, and dividers to create hierarchy without
+  extra containers.
+- **Inconsistent spacing.** 12px here, 20px there, 8px somewhere else.
+  Instead: define a spacing scale (4/8/12/16/24/32/48/64) and use it
+  everywhere.
+- **Components from different visual languages.** Rounded buttons next to
+  square inputs, shadows mixed with flat design. Instead: pick one system
+  and apply it consistently.
+- **Long scrolling forms with no visual grouping.** Instead: group fields
+  into sections with clear headings, cards, or stepped flows.
+- **Cramped layouts.** Text pressed against edges, no room to breathe.
+  Instead: generous padding, comfortable margins, let the content float.
+- **Loading states that are just a centered spinner on a blank page.**
+  Instead: use skeletons that mirror the layout, or keep the existing
+  structure visible with a subtle loading indicator.
+- **Any interface where the first reaction is "this looks like a demo" or
+  "this looks like it was made with a website builder."**

package/dist/compiled/dev-and-deploy.md

@@ -0,0 +1,69 @@
+# Development & Deployment
+
+## How Development Works
+
+The sandbox uses the same tunnel binary and execution pipeline as local development. Code changes take effect immediately — esbuild transpiles methods per-request, no restart needed. The dev database is a disposable snapshot of production.
+
+### The Dev Inner Loop
+
+1. Edit method code in `dist/methods/src/` — next method invocation uses updated code automatically
+2. Edit frontend code in `dist/interfaces/web/src/` — HMR updates the browser instantly
+3. Add/modify table definitions — schema changes sync to the dev database automatically
+4. Run scenarios to set up specific data states for testing
+
+### Dev Database
+
+The dev session gets its own database — a snapshot of the live database at session start. Your code writes to this snapshot, not to production.
+
+- **Reset to live data** — overwrite the dev database with a fresh copy of production
+- **Truncate** — keep the schema, delete all row data (used by scenarios for a clean canvas)
+- **Schema sync** — add a field to a table interface and it's immediately available in dev
+
+The dev database is disposable. Experiment freely — there's no risk of breaking anything.
+
+### Debugging
+
+`console.log`, `console.warn`, and `console.error` in methods are captured and displayed in the terminal. They don't affect the method's return value. Every method execution is logged with full input, output, duration, and error info.
+
+## What Happens on Deploy
+
+```bash
+git push origin main
+```
+
+The platform builds and deploys automatically:
+
+1. **Parse manifest** — read `mindstudio.json` from the commit
+2. **Compile methods** — esbuild bundles each method into a single JS file
+3. **Compile interfaces** — build web SPA (`npm install && npm run build`), generate configs for API/Discord/Telegram/cron/etc.
+4. **Parse table schemas** — TypeScript AST to column definitions, diff against live database
+5. **Compute effects** — roles diff, cron diff, bot command diffs, table DDL
+6. **Apply** — create/update roles, sync bot commands, apply DDL to a staging database copy, swap the live pointer
+
+### Preview Deployments
+
+Push to a non-default branch for a preview deployment — same build pipeline, but doesn't affect the live app. Useful for testing changes before merging.
+
+### Database Migrations on Deploy
+
+Schema changes are automatic:
+- **New tables** — `CREATE TABLE` applied automatically
+- **New columns** — `ALTER TABLE ADD COLUMN` applied automatically
+- **Dropped columns** — `ALTER TABLE DROP COLUMN` applied automatically when a column is removed from the interface
+- **Dropped tables** — `DROP TABLE` applied automatically when a table file is removed from the manifest
+- **Type changes and renames** — not supported in the automatic migration path
+
+Schema changes are always applied to a clone of the live database, never directly. If DDL fails, the live database is untouched and the release is marked `failed`.
+
+### Rollback
+
+Rollback is a git revert — creates a new commit, triggers a new build. The previous release's database still exists (databases are per-release), so data isn't lost.
+
+### Common Build Failures
+
+- **Method compilation error** — TypeScript/syntax error in a method file. Error message includes file and line.
+- **Web build error** — npm install or build command failed. Check build log stdout/stderr.
+- **Table schema error** — TypeScript file couldn't be parsed. Ensure the table definition uses the `defineTable<T>()` pattern.
+- **Missing manifest fields** — method declared but path doesn't exist, or export doesn't match.
+
+Failed releases don't affect the current live release.

package/dist/compiled/interfaces.md

@@ -0,0 +1,238 @@
+# Interfaces
+
+Interfaces are projections of the backend contract into different modalities. The same methods power all of them. An interface can be as complex and polished as you want, but it's always safe — the backend contract is where anything real happens. The interface can't break business logic or corrupt data.
+
+All external service connections (Discord bot tokens, Telegram bot setup, webhook secrets, email addresses) are configured at the project level by the user through the MindStudio platform. The agent's job is to write the config files and the methods that handle the requests — not to manage API keys, OAuth flows, or service registration.
+
+## Web Interface
+
+A full web application — typically Vite + React, but any framework that produces static output works.
+
+### Project Structure
+
+```
+dist/interfaces/web/
+  web.json           ← interface config
+  package.json
+  vite.config.ts
+  index.html
+  src/
+    App.tsx
+    pages/
+    components/
+```
+
+### Config (`web.json`)
+
+```json
+{
+  "devPort": 5173,
+  "devCommand": "npm run dev"
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `devPort` | `number` | `5173` | Port for the dev server |
+| `devCommand` | `string` | `"npm run dev"` | Command to start the dev server |
+
+### Frontend SDK
+
+```typescript
+import { createClient, platform, auth } from '@mindstudio-ai/interface';
+
+// Typed RPC to backend methods — use the camelCase export function names,
+// NOT the kebab-case method IDs from mindstudio.json. The client maps
+// export names to method IDs automatically.
+const api = createClient<{
+  submitVendorRequest(input: { name: string }): Promise<{ vendorId: string }>;
+  listVendors(): Promise<{ vendors: Vendor[] }>;
+}>();
+
+const { vendorId } = await api.submitVendorRequest({ name: 'Acme' });
+const { vendors } = await api.listVendors();
+
+// File operations
+const { url } = await platform.requestFile({ type: 'image' });
+const cdnUrl = await platform.uploadFile(file);
+
+// Current user (display only)
+auth.userId;
+auth.name;
+auth.email;
+```
+
+The project uses `"jsx": "react-jsx"` (automatic JSX transform) — do not `import React from 'react'`. Only import the specific hooks and types you need (e.g., `import { useState, useEffect } from 'react'`).
+
+On deploy, the platform runs `npm install && npm run build` in the web directory and hosts the output on CDN.
+
+## API Interface
+
+Auto-generated REST endpoints. Every method becomes an API endpoint.
+
+### Config (`interface.json`)
+
+```json
+{
+  "methods": ["submit-vendor-request", "list-vendors", "get-dashboard"]
+}
+```
+
+Omit the `methods` field (or the config entirely) to expose all methods.
+
+### Usage
+
+```bash
+curl -X POST https://api.mindstudio.ai/_internal/v2/apps/{appId}/methods/submit-vendor-request/invoke \
+  -H "Authorization: Bearer sk..." \
+  -H "Content-Type: application/json" \
+  -d '{ "input": { "name": "Acme" } }'
+```
+
+Auth via API key. Returns `{ output, $releaseId, $methodId }`.
+
+### Streaming
+
+```bash
+curl -X POST ... -d '{ "input": {...}, "stream": true }'
+```
+
+Returns SSE: `data: { type: 'token', text }` chunks, then `data: { type: 'done', output }`.
+
+## Discord Bot
+
+Slash commands that invoke methods.
+
+### Config (`interface.json`)
+
+```json
+{
+  "commands": [
+    {
+      "name": "submit-vendor",
+      "description": "Request a new vendor",
+      "method": "submit-vendor-request"
+    }
+  ],
+  "loadingMessage": "Processing your request..."
+}
+```
+
+Commands are synced to Discord on deploy.
+
+## Telegram Bot
+
+Bot commands and message handling.
+
+### Config (`interface.json`)
+
+```json
+{
+  "commands": [
+    {
+      "command": "/submit",
+      "description": "Submit a vendor request",
+      "method": "submit-vendor-request"
+    }
+  ],
+  "defaultMethod": "handle-message"
+}
+```
+
+`defaultMethod` handles free-text messages that don't match a command.
+
+## Cron
+
+Scheduled method execution.
+
+### Config (`interface.json`)
+
+```json
+{
+  "jobs": [
+    {
+      "schedule": "0 9 * * 5",
+      "method": "process-weekly-payments",
+      "description": "Process approved invoices every Friday at 9am"
+    },
+    {
+      "schedule": "*/30 * * * *",
+      "method": "sync-vendor-status",
+      "description": "Sync vendor statuses every 30 minutes"
+    }
+  ]
+}
+```
+
+Standard cron expression format. Jobs are synced to the platform on deploy.
+
+## Webhook
+
+Inbound HTTP endpoints that invoke methods.
+
+### Config (`interface.json`)
+
+```json
+{
+  "endpoints": [
+    {
+      "method": "handle-payment-webhook",
+      "description": "Stripe payment notifications",
+      "secret": "whk_abc123..."
+    }
+  ]
+}
+```
+
+Endpoint URL: `https://api.mindstudio.ai/_internal/v2/webhook/{appId}/{secret}`
+
+Accepts any HTTP method. The method receives `{ method, headers, query, body }` as input.
+
+## Email
+
+Inbound email triggers.
+
+### Config (`interface.json`)
+
+```json
+{
+  "method": "handle-inbound-email"
+}
+```
+
+Register a custom address (e.g., `invoices@mindstudio-hooks.com`) via the platform. Inbound emails invoke the specified method with the email content as input.
+
+## MCP (Model Context Protocol)
+
+Expose methods as AI tools.
+
+### Config (`interface.json`)
+
+```json
+{
+  "methods": ["submit-vendor-request", "list-vendors"]
+}
+```
+
+Each listed method becomes an MCP tool. Method names and descriptions from the manifest are used as tool names and descriptions.
+
+## Manifest Declaration
+
+Each interface is declared in `mindstudio.json`:
+
+```json
+{
+  "interfaces": [
+    { "type": "web", "path": "dist/interfaces/web/web.json" },
+    { "type": "api" },
+    { "type": "cron", "path": "dist/interfaces/cron/interface.json" },
+    { "type": "discord", "path": "dist/interfaces/discord/interface.json" },
+    { "type": "telegram", "path": "dist/interfaces/telegram/interface.json" },
+    { "type": "webhook", "path": "dist/interfaces/webhook/interface.json" },
+    { "type": "email", "path": "dist/interfaces/email/interface.json" },
+    { "type": "mcp", "path": "dist/interfaces/mcp/interface.json" }
+  ]
+}
+```
+
+Some interfaces (like `api`) work without a config file — just declaring the type is enough. Others need a config for command mappings, schedules, etc. Set `"enabled": false` to skip an interface during build.

package/dist/compiled/manifest.md

@@ -0,0 +1,107 @@
+# Manifest Reference
+
+`mindstudio.json` declares everything the platform needs to know about the app. It's read on every deploy to determine what to compile.
+
+## Example
+
+```json
+{
+  "appId": "e452fcf2-06c5-49e8-b4f1-6353563f24b0",
+  "name": "Procure-to-Pay",
+
+  "roles": [
+    { "id": "requester", "name": "Requester", "description": "Can submit vendor requests and purchase orders." },
+    { "id": "approver", "name": "Approver", "description": "Reviews and approves purchase orders." },
+    { "id": "admin", "name": "Administrator", "description": "Full access to all app functions." }
+  ],
+
+  "tables": [
+    { "name": "vendors", "path": "dist/methods/src/tables/vendors.ts", "export": "Vendors" },
+    { "name": "purchase-orders", "path": "dist/methods/src/tables/purchase-orders.ts", "export": "PurchaseOrders" }
+  ],
+
+  "methods": [
+    {
+      "id": "submit-vendor-request",
+      "name": "Submit Vendor Request",
+      "path": "dist/methods/src/submitVendorRequest.ts",
+      "export": "submitVendorRequest"
+    }
+  ],
+
+  "interfaces": [
+    { "type": "web", "path": "dist/interfaces/web/web.json" },
+    { "type": "api" },
+    { "type": "cron", "path": "dist/interfaces/cron/interface.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"]
+    }
+  ]
+}
+```
+
+## Fields
+
+### `appId` (required)
+`string` (UUID). The app's platform identifier. Found in the git remote URL: `https://git.mscdn.ai/{appId}.git`.
+
+### `name` (required)
+`string`. Display name shown in the editor and workspace.
+
+### `roles`
+`Array<{ id, name?, description? }>`. Defaults to `[]`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Kebab-case identifier (used in code: `auth.requireRole('admin')`) |
+| `name` | `string` | No | Display name |
+| `description` | `string` | No | What this role can do |
+
+### `tables`
+`Array<{ name, path, export }>`. Defaults to `[]`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Table name — snake_case, `[a-zA-Z0-9_]` only (must match `db.defineTable('name')`) |
+| `path` | `string` | Yes | Path to the TypeScript file (relative to project root) |
+| `export` | `string` | Yes | Named export from the file (e.g., `Vendors`) |
+
+### `methods` (required, at least one)
+`Array<{ id, name?, path, export }>`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Kebab-case identifier (used in API URLs and frontend method map) |
+| `name` | `string` | No | Display name |
+| `path` | `string` | Yes | Path to the TypeScript file |
+| `export` | `string` | Yes | Named export (the async function) |
+
+### `interfaces`
+`Array<{ type, path?, config?, enabled? }>`. Defaults to `[]`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `string` | Yes | One of: `web`, `api`, `discord`, `telegram`, `cron`, `webhook`, `email`, `mcp` |
+| `path` | `string` | No | Path to the interface config file |
+| `config` | `object` | No | Inline config (alternative to a file) |
+| `enabled` | `boolean` | No | Default `true`. Set `false` to skip during build. |
+
+### `scenarios`
+`Array<{ id, name?, description?, path, export, roles }>`. Defaults to `[]`.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Kebab-case identifier |
+| `name` | `string` | No | Display name |
+| `description` | `string` | No | What state this scenario creates |
+| `path` | `string` | Yes | Path to the TypeScript file |
+| `export` | `string` | Yes | Named export (the async function) |
+| `roles` | `string[]` | Yes | Roles to impersonate after seeding |

package/dist/compiled/media-cdn.md

@@ -0,0 +1,51 @@
+# Images and Media CDN
+
+MindStudio has three CDN hosts:
+
+- **Images:** `i.mscdn.ai`
+- **Videos:** `v.mscdn.ai`
+- **Files:** `f.mscdn.ai`
+
+Always use CDN transform parameters to request appropriately sized images
+rather than CSS-scaling full-resolution originals.
+
+## CDN Image Transforms
+
+Combine freely as query string parameters:
+
+| 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 (fit=crop + face detection) |
+| `fm` | `?fm=webp` | Output format: avif, webp, jpeg, auto |
+| `dpr` | `?dpr=2` | Device pixel ratio (auto-set to 3 when w/h specified) |
+| `q` | `?q=80` | Quality (1-100) |
+| `blur` | `?blur=10` | Blur radius |
+| `sharpen` | `?sharpen=1` | Sharpen amount |
+
+Example: `https://i.mscdn.ai/.../image.png?w=200&h=200&fit=crop&fm=avif`
+
+## Video Thumbnails
+
+Append `/thumbnail.png` or `/thumbnail.jpg` to any video URL:
+
+```
+https://v.mscdn.ai/{orgId}/videos/{videoId}.mp4/thumbnail.png?ts=last&w=400
+```
+
+The `ts` param selects the frame: a number (seconds) or `last`. Image CDN
+resize params also work on video thumbnails.
+
+## Media Metadata
+
+Append `.json` to any CDN URL to get metadata (dimensions, duration, mime
+type, orientation, etc.).
+
+## General Rules
+
+- Always set explicit width/height or aspect-ratio on images to prevent
+  layout shift.
+- Use remote resources (Google Fonts via CDN). Never self-hosted font
+  packages.