@mindstudio-ai/remy 0.1.269 → 0.1.270

package/dist/prompt/compiled/methods.md

@@ -91,7 +91,7 @@ await mindstudio.sendEmail({
 // a handler. It has the full input shape and the threading rules; getting the headers
 // wrong sends a reply that starts a new conversation instead of continuing one.
 
-// Store a file → returns a stable URL (define the store at module scope; see Files & Storage)
+// Store a file → returns a stable URL (define the store at module scope; load the `files` skill)
 const { url } = await Reports.put(buffer, { contentType: 'application/pdf', filename: 'report.pdf' });
 
 // Web scraping
@@ -168,17 +168,7 @@ Building the query progressively (one `.filter` per optional input) is the canon
 
 ### 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.');
-
-  const { deleted } = await Vendors.remove(input.vendorId);
-  return { deleted };
-}
-```
+Same shape as any method, with `auth.requireRole('admin')` (or the relevant role) as the first line — it throws for callers without the role, so nothing below it runs unauthorized.
 
 ### Multi-Table Transaction
 
@@ -319,30 +309,6 @@ input._request: {
 
 `rawBody` preserves the exact bytes the client sent — whitespace, key ordering, encoding. Use it for signature verification.
 
-**There are two inbound HTTP interfaces and they expose the raw body differently.** This one is the API interface, at `input._request.rawBody`. The Webhook interface puts it at top-level `input.rawBody` and routes by a secret in the URL instead of a bearer token, which usually suits provider callbacks better since a provider can't send one. Load the `webhooks` skill before choosing — the example below is the API-interface shape and won't work unchanged in a webhook handler.
-
-```typescript
-export async function stripeWebhook(input: {
-  type: string;
-  data: any;
-  _request: { headers: Record<string, string>; rawBody: string };
-}) {
-  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
-
-  const event = stripe.webhooks.constructEvent(
-    input._request.rawBody,
-    input._request.headers['stripe-signature'],
-    process.env.STRIPE_WEBHOOK_SECRET!,
-  );
-
-  switch (event.type) {
-    case 'payment_intent.succeeded':
-      // ...
-      break;
-  }
-
-  return { received: true };
-}
-```
+**There are two inbound HTTP interfaces and they expose the raw body differently.** The API interface puts it at `input._request.rawBody`; the Webhook interface puts it at top-level `input.rawBody` and routes by a secret in the URL instead of a bearer token, which usually suits provider callbacks better since a provider can't send one. Load the `webhooks` skill before writing a signature-verifying handler (e.g. Stripe's `constructEvent` over the raw bytes) — the input shape depends on which interface you chose.
 
 For most methods, you don't need `_request` — the parsed path params, query params, and body fields are already on `input` directly.

package/dist/prompt/compiled/msfm.md

@@ -223,19 +223,4 @@ clipboard fallback for unsupported browsers.
   Added share button to haiku detail view.
 ```
 
-Unbuilt item:
-
-```markdown
----
-name: Daily Prompt Engine
-type: roadmap
-status: not-started
-description: A new writing prompt every day, tuned to the user's style and interests.
-requires: []
-effort: small
----
-
-Generate a personalized daily writing prompt based on the user's past haikus,
-preferred themes, and seasonal context. Surface it as a gentle nudge on the
-home screen, not a notification.
-```
+Unbuilt item — same shape with `status: not-started`, a body describing the intended feature, and no History section (History is appended when it's built).

package/dist/prompt/compiled/platform.md

@@ -12,7 +12,7 @@ my-app/
 
   src/                               ← authored source (no code)
     app.md                             backend spec (MSFM)
-    references/                        supporting material (PDFs, notes, diagrams)
+    references/                        supporting material (PDFs, notes, diagrams) — context for the agent, not consumed by the platform
     interfaces/
       @brand/                          shared brand identity
         visual.md                        aesthetic direction, surfaces, spacing
@@ -34,7 +34,7 @@ my-app/
         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
+      package.json                     backend dependencies — only declared packages are available at runtime
 
     interfaces/                        interface projections
       web/                               full project directory (Vite + React)
@@ -60,21 +60,11 @@ my-app/
         tools/                             tool descriptions (one .md per method)
 ```
 
-## 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/ |
-| Roadmap | `src/roadmap/*.md` | Feature roadmap items (type: roadmap). One file per feature with status, dependencies, and history. |
-| Reference material | `src/references/` | Context for the agent, not consumed by platform |
+## Platform Limits
+
+Two things the platform cannot do — be upfront when a request heads this way:
+- Native mobile apps (iOS/Android). Mobile-responsive web apps are fine.
+- Real-time multiplayer with persistent connections (no WebSocket support). Turn-based or async multiplayer works great.
 
 ## The Two SDKs
 

package/dist/prompt/skills/auth.md

@@ -0,0 +1,443 @@
+---
+name: Auth & User Accounts
+what: Apps manage their own users — opt-in via manifest config over a developer-owned user table, with the platform handling verification codes, cookie sessions, and role sync. Covers email/SMS code login (the platform sends real 6-digit codes; the developer builds the UI), per-user API keys that resolve to full RBAC over Bearer auth, org-delegated "Sign in with Remy" for internal apps (redirect/popup handshake, platform-managed identity), the full frontend SDK (auth state and onAuthStateChanged, flows, email/phone changes, phone and email helpers, error codes), backend enforcement (requireRole/hasRole/userId, the system role), auth-screen design rules, and the dev test bypasses.
+when: Before writing ANY auth code — the manifest `auth` config, the user table, login/signup UI, frontend `auth.*` calls, API keys, delegated sign-in — and before testing or debugging auth flows.
+---
+
+# Auth
+
+Remy apps can have and manage their own users. Auth is opt-in: configure it in the manifest, define a user table, and build your own login UI. The platform handles verification codes, cookies, and session management. Apps without auth config use anonymous guest sessions (current default behavior).
+
+**Auth is optional.** Many apps don't need it. Only add auth when the app needs to identify users or restrict access.
+
+## Manifest Config
+
+```json
+{
+  "auth": {
+    "enabled": true,
+    "methods": ["email-code", "sms-code"],
+    "table": {
+      "name": "users",
+      "columns": {
+        "email": "email",
+        "phone": "phone",
+        "roles": "roles",
+        "apiKey": "apiKey"
+      }
+    }
+  },
+  "roles": [
+    { "id": "vendor", "name": "Vendor" },
+    { "id": "buyer", "name": "Buyer" },
+    { "id": "admin", "name": "Admin" }
+  ]
+}
+```
+
+- **`auth.enabled`** — opt-in. No auth config = anonymous guest sessions.
+- **`auth.methods`** — which verification methods the app supports. At least one required.
+  - `email-code` — 6-digit code sent via email
+  - `sms-code` — 6-digit code sent via SMS
+  - `api-key` — programmatic access via `Authorization: Bearer sk_...` header. Resolves to a user with full RBAC.
+  - `remy` — platform-delegated sign-in ("Sign in with Remy"). The platform resolves who the user is; roles and verification are platform-managed. Only usable when the app's owning organization has it enabled — the `<org_context>` block signals availability. See *Organization-Managed Sign-In* below.
+- **`auth.table.name`** — name of the `defineTable` table that holds user records.
+- **`auth.table.columns`** — maps platform-managed fields to column names in the developer's table.
+  - `email` — required if `email-code` is in methods
+  - `phone` — required if `sms-code` is in methods
+  - `roles` — optional. Maps to a JSON array column for role assignments.
+  - `apiKey` — optional. Required if `api-key` is in methods. Platform stores masked value (`sk_...xxxx`) for display; one key per user.
+- **`roles`** — declares valid roles for the app. Same as before: `id`, `name`, optional `description`.
+
+## Auth Table
+
+The user table is a regular `defineTable` table. The platform manages the auth-mapped columns; all other columns are the developer's domain.
+
+```typescript
+import { db } from '@mindstudio-ai/agent';
+
+export const Users = db.defineTable<{
+  // Mapped to auth — platform keeps these in sync
+  email: string;
+  phone?: string;
+  roles: string[];
+  apiKey?: string;       // masked value (sk_...xxxx), read-only from code
+  // Developer's own fields
+  displayName: string;
+  plan: 'free' | 'pro';
+  avatarUrl?: string;
+}>('users');
+```
+
+### Platform-Managed Column Behavior
+
+- **`email` / `phone` / `apiKey`** — read-only from code. Writing via `update()` or `push()` throws a `MindStudioError`. Use the auth API to change a user's email or phone, and `auth.createApiKey()` / `auth.revokeApiKey()` for API keys.
+- **`roles`** — read/write from both code and the dashboard. `Users.update(userId, { roles: ['admin'] })` works and syncs to the platform. Dashboard role changes sync back to the table.
+- All other columns are fully the developer's. When auth creates a user row, only the managed columns (email/phone, roles) are populated. All user-defined columns start as null until the user completes onboarding — type them as optional and guard against null.
+
+## Frontend Auth (Interface SDK)
+
+The developer builds their own login/signup UI. The SDK provides methods that handle the verification flow and session management.
+
+```typescript
+import { auth } from '@mindstudio-ai/interface';
+```
+
+### User Shape
+
+```typescript
+interface AppUser {
+  id: string;
+  email: string | null;
+  phone: string | null;
+  roles: string[];
+  apiKey: string | null;    // masked value (sk_...xxxx), null if no key
+  provider?: 'remy' | null; // 'remy' = delegated sign-in (platform-managed); null/absent = app-verified
+  createdAt: string;
+}
+```
+
+`auth.getCurrentUser()` returns `AppUser | null`. `null` means unauthenticated.
+
+### State
+
+```typescript
+auth.getCurrentUser()         // AppUser | null
+auth.currentUser              // AppUser | null (sync getter, same as getCurrentUser())
+auth.isAuthenticated()        // boolean
+auth.authStatus               // 'authenticating' | 'authenticated' | 'unauthenticated' (sync getter)
+auth.onAuthStateChanged(cb)   // fires immediately with current user, then on every transition —
+                              // verify/confirm/logout AND each authStatus change (a Sign in with Remy
+                              // handshake starting or settling). During 'authenticating' it may fire
+                              // null; that's expected — read authStatus to tell it apart from
+                              // logged-out. Returns an unsubscribe function.
+```
+
+Use `onAuthStateChanged` in React instead of reading `currentUser` once at render time:
+
+```typescript
+function useAuth() {
+  const [user, setUser] = useState<AppUser | null>(null);
+  useEffect(() => auth.onAuthStateChanged(setUser), []);
+  return user;
+}
+```
+
+### Email Code Flow
+
+```typescript
+const { verificationId } = await auth.sendEmailCode('user@example.com');
+// User enters the 6-digit code from their email
+const user = await auth.verifyEmailCode(verificationId, '123456');
+// user is now authenticated — auth.getCurrentUser() returns the AppUser
+```
+
+### SMS Code Flow
+
+```typescript
+const { verificationId } = await auth.sendSmsCode('+15551234567');
+const user = await auth.verifySmsCode(verificationId, '123456');
+```
+
+## Organization-Managed Sign-In ("Sign in with Remy")
+
+Some apps are owned by an organization that centralizes sign-in. When that applies to the current app, the system prompt includes an `<org_context>` block (near the end); for org-managed sign-in it states the organization name and whether delegated sign-in is available. Sign in with Remy is a way to make authentication seamless for internal apps - it should not be used for public-facing applications. The app owner will need to add users to their workspace's team on the Remy platform and those users will need Remy accounts for it to work.
+
+- **When it says "Sign in with Remy" is available** — offer delegated sign-in: a **"Continue with {Org}"** button wired to the `remy` method (see *Sign in with Remy (delegated)* below). Use the exact organization name from the block for the label. For an org-owned app this is usually the primary sign-in — the members already have platform identities, so a verification-code form is redundant.
+- **When it says the organization requires delegated sign-in** — `remy` is the *only* human method: do not add `email-code` or `sms-code`. Those are blocked at the platform edge for the org's apps, so building them yields a login that can't work.
+
+When the `<org_context>` block is absent, or present without a delegated-sign-in line — the common case — do not build it or offer to build it. This is an auth scheme for enterprises building internal apps only, and it requires a Remy enterprise plan to use. When enabled, the platform decides who the user is (like "Sign in with Google"); the app just starts the flow and reads the result.
+
+```typescript
+// "Continue with {Org}" button — must be triggered by a user gesture (click).
+<button onClick={() => auth.signInWithRemy()}>Continue with Acme</button>
+
+// On return from the handshake (or when opened from the Remy dashboard), the app
+// cold-loads with sign-in still completing. Track authStatus and render a
+// "Completing sign-in…" state — NOT the login screen — while it's 'authenticating'.
+const [user, setUser] = useState(auth.currentUser);
+const [status, setStatus] = useState(auth.authStatus);
+useEffect(() => auth.onAuthStateChanged(() => {
+  setUser(auth.currentUser);
+  setStatus(auth.authStatus);
+}), []);
+useEffect(() => { auth.handleRemyRedirect().catch(() => {}); }, []); // no-op if nothing to redeem
+// status === 'authenticating' → <CompletingSignIn/>;  user → app;  else → login
+```
+
+- `auth.signInWithRemy(options?)` → `Promise<AppUser | null>`. Auto-detects context: a top-level app redirects to the platform and back — **the page navigates away, so the promise never settles; don't await it to gate UI**. An app embedded in a cross-origin iframe (the dev IDE preview) uses a popup and the promise resolves with the user (or `null` if the popup is closed). Options: `redirectUri` (default current URL), `state` (CSRF, auto-generated), `mode: 'auto' | 'popup' | 'redirect'` (default `'auto'` — leave it). Because of the redirect case, **drive UI off `onAuthStateChanged`, not the return value.**
+- `auth.handleRemyRedirect()` → `Promise<AppUser | null>`. Call once on load. Handles both the "Continue with {Org}" return and being opened from the Remy dashboard; on success it updates the session in-place (fires `onAuthStateChanged`) and cleans the URL.
+- **Render the completing state, not the login screen, on return.** A redirect return (or dashboard launch) cold-loads with `auth.authStatus === 'authenticating'` — set *before first paint* and held until the exchange settles. Gate the UI on `authStatus`: `'authenticating'` → a brief "Completing sign-in…" state; a user → the app; `'unauthenticated'` → the login screen. Don't infer this from the URL `?code` (it's stripped when redemption starts) or treat the initial `null` user as logged-out — that flashes the login screen over a successful sign-in.
+- Delegated users have `provider: 'remy'`. Their **roles and email are platform-managed** (like `email`/`phone` for code users) — enforce access with `requireRole`/`hasRole` on the backend as usual, but don't assign roles from app code; the platform owns them.
+
+### Email/Phone Changes (must be authenticated)
+
+```typescript
+await auth.requestEmailChange('newemail@example.com');
+const user = await auth.confirmEmailChange('newemail@example.com', '123456');
+
+await auth.requestPhoneChange('+15559876543');
+const user = await auth.confirmPhoneChange('+15559876543', '123456');
+```
+
+### Logout
+
+```typescript
+await auth.logout();  // clears session
+```
+
+### API Keys
+
+For apps with `api-key` in their auth methods. API keys resolve to a user with the same `auth.userId`, `auth.roles`, and `requireRole()` enforcement as a cookie session.
+
+```typescript
+// Generate a key for the current user (must be logged in)
+const { key } = await auth.createApiKey();
+// key = "sk_..." — show once, not stored. user.apiKey updates to masked value.
+
+// Revoke current user's key
+await auth.revokeApiKey();
+// user.apiKey becomes null
+```
+
+Both methods fire `onAuthStateChanged` since they modify the user object. One key per user — creating a new key replaces the old one.
+
+Consumers use the key as a Bearer token: `Authorization: Bearer sk_...`. The platform resolves it to the user, populates the auth context, and executes the method normally. Invalid or revoked key: 401.
+
+### Error Codes
+
+All auth methods throw on failure with a `code` property:
+
+| Code | HTTP | Meaning |
+|------|------|---------|
+| `rate_limited` | 429 | Too many requests |
+| `invalid_code` | 400 | Wrong verification code |
+| `verification_expired` | 400 | Code has expired |
+| `max_attempts_exceeded` | 400 | Too many failed attempts |
+| `not_authenticated` | 401 | No active session |
+| `invalid_session` | 401 | Session expired or invalid |
+| `not_supported` | 400 | Feature not enabled for this app (e.g. API keys without `api-key` in methods) |
+| `invalid_state` | 400 | Sign in with Remy: returned CSRF state didn't match (stale/replayed redirect) |
+| `popup_blocked` | — | Sign in with Remy (embedded): popup was blocked — prompt to allow popups and retry |
+| `signin_timeout` | — | Sign in with Remy (embedded): popup didn't complete in time |
+| `auth_required` | 401 | Agent/voice interface requires an authenticated user (interface `auth` block) |
+| `role_required` | 403 | Agent/voice interface requires a role the user doesn't hold |
+
+### Phone Helpers
+
+```typescript
+auth.phone.countries          // ~180 countries with { code, dialCode, name, flag }
+                              // Key selects by country code (US, CA, BB), not dial code — multiple countries share +1
+auth.phone.detectCountry()    // guess from timezone, e.g. 'US'
+auth.phone.toE164('5551234567', 'US')  // '+15551234567'
+auth.phone.format('+15551234567')      // '+1 (555) 123-4567'
+auth.phone.isValid('+15551234567')     // true
+```
+
+### Email Helpers
+
+```typescript
+auth.email.isValid('user@example.com')  // true
+```
+
+## Backend Auth (Agent SDK)
+
+```typescript
+import { auth } from '@mindstudio-ai/agent';
+```
+
+### `auth.requireRole(...roles)`
+
+Throws 401 (unauthenticated) if there is no current user. Throws 403 (forbidden) if the current user doesn't have **any** of the specified roles.
+
+```typescript
+auth.requireRole('admin');
+auth.requireRole('admin', 'approver');  // any of these
+```
+
+**Require login: check `auth.userId`. Roles are RBAC** — only declare roles that map to real business distinctions (vendor/buyer/admin), and only check them when behavior should differ. Newly verified users have `roles: []` until your code assigns them.
+
+### `auth.hasRole(...roles)`
+
+Returns `boolean`. Same logic as `requireRole` but doesn't throw.
+
+### `auth.userId`
+
+The current user's ID (the row ID in the auth table), or `null` for unauthenticated requests. Check for null before using in database queries when the method might be called without auth.
+
+### `auth.roles`
+
+Array of role IDs assigned to the current user.
+
+### `auth.getUsersByRole(role)`
+
+Returns an array of user IDs with the specified role.
+
+### System Role (Platform Triggers)
+
+When the platform invokes a method on behalf of the app (cron, webhook, email), the execution runs as a system user with `auth.roles: ['system']`. Use `auth.requireRole('system')` to restrict methods to platform triggers only:
+
+```typescript
+export async function regenerateCache(input: {}) {
+  auth.requireRole('system');
+  // Only cron, webhooks, and users with 'system' role can reach this
+}
+```
+
+Web frontend calls (`/_/methods`), API interface calls (`/_/api`), and agent chat all run as the authenticated user — they don't get the system role unless the user has been explicitly assigned it. You can assign `system` to app users via the dashboard or SDK if they need to manually trigger these methods.
+
+## Login Page Example
+
+```tsx
+import { useState, useEffect } from 'react';
+import { auth } from '@mindstudio-ai/interface';
+import { useLocation } from 'wouter';
+
+function useAuth() {
+  const [user, setUser] = useState<AppUser | null>(null);
+  useEffect(() => auth.onAuthStateChanged(setUser), []);
+  return user;
+}
+
+function LoginPage() {
+  const user = useAuth();
+  const [, navigate] = useLocation();
+  const [email, setEmail] = useState('');
+  const [code, setCode] = useState('');
+  const [verificationId, setVerificationId] = useState('');
+  const [error, setError] = useState('');
+
+  // Redirect when authenticated (fires via onAuthStateChanged after verify)
+  useEffect(() => { if (user) navigate('/dashboard'); }, [user]);
+
+  const handleSendCode = async () => {
+    try {
+      const { verificationId } = await auth.sendEmailCode(email);
+      setVerificationId(verificationId);
+      setError('');
+    } catch (err: any) {
+      setError(err.code === 'rate_limited' ? 'Too many attempts. Try again later.' : err.message);
+    }
+  };
+
+  const handleVerify = async () => {
+    try {
+      await auth.verifyEmailCode(verificationId, code);
+      // onAuthStateChanged fires, useAuth updates, redirect happens
+    } catch (err: any) {
+      if (err.code === 'invalid_code') setError('Wrong code. Try again.');
+      else if (err.code === 'verification_expired') setError('Code expired. Request a new one.');
+      else if (err.code === 'max_attempts_exceeded') setError('Too many attempts. Request a new code.');
+      else setError(err.message);
+    }
+  };
+
+  if (!verificationId) {
+    return (
+      <div>
+        <h1>Sign in</h1>
+        <input placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} />
+        <button onClick={handleSendCode}>Send code</button>
+        {error && <p>{error}</p>}
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <p>Enter the code we sent to {email}</p>
+      <input placeholder="123456" value={code} onChange={e => setCode(e.target.value)} />
+      <button onClick={handleVerify}>Verify</button>
+      <button onClick={() => setVerificationId('')}>Resend</button>
+      {error && <p>{error}</p>}
+    </div>
+  );
+}
+```
+
+## Backend Method Example
+
+```typescript
+import { auth } from '@mindstudio-ai/agent';
+import { Users } from './tables/users';
+
+export async function getDashboard() {
+  const user = auth.userId ? await Users.get(auth.userId) : null;
+
+  if (auth.hasRole('admin')) {
+    const allUsers = await Users.toArray();
+    return { user, allUsers, isAdmin: true };
+  }
+
+  return { user, isAdmin: false };
+}
+
+export async function promoteToAdmin(input: { userId: string }) {
+  auth.requireRole('admin');
+  await Users.update(input.userId, { roles: ['admin'] });
+}
+```
+
+## Roles
+
+Roles are declared in the manifest, stored as an array column on the user table, and enforced in backend methods. The platform manages role data across the user table and the dashboard.
+
+- Declare roles in `mindstudio.json` with `id` and `name`
+- The mapped `roles` column holds a JSON array of role ID strings: `["vendor", "admin"]`
+- Writable from code: `Users.update(userId, { roles: ['admin'] })` — platform syncs automatically
+- Writable from dashboard: Remy dashboard shows app users and their roles
+- Backend enforcement: `auth.requireRole('admin')` works as before
+
+## Interface-Level Auth (Agent + Voice)
+
+Agent and voice interfaces additionally declare auth **in their config** (a required `auth` key:
+`{ "requireUser": boolean, "requireRole"?: string[] }`) because those sessions spend money without
+necessarily calling a backend method — the platform gates the lobby itself, before any model or
+media spend. `requireRole` uses the same manifest role ids with OR semantics. Denials reach the
+frontend SDK as `MindStudioInterfaceError` codes `auth_required` (401) and `role_required` (403) —
+route them to the app's login flow. See the `agentInterfaces` / `voiceInterfaces` skills for the
+full contract. Method-level `auth.requireRole(...)` checks still apply to every tool call inside.
+
+## Apps Without Auth
+
+Apps without `auth` in the manifest use anonymous guest sessions. No login, no user identity, no roles. This is the default and works fine for single-user apps, internal tools, and simple utilities. (Agent/voice interfaces on such apps declare `"auth": { "requireUser": false }` explicitly — anonymous callers are scoped by a per-browser visitor identity.)
+
+## Important: Designing Auth in Web Interfaces
+
+The most imporant user experience consideration with auth is that authentication moments must feel natural and intuitive - they should not feel jarring or surprising. Take care to integrate them into the entire experience when building.
+
+For the overwhelming majority of apps, a user should never land on auth at the root of an app when opening it for the first time (except in cases where the app is, e.g., an internal tool or some other protected experience - and even then it should feel more like a welcome/splash screen than an error state). Users should be able to explore public resources, or at least encounter some kind of landing/introduction moment, before they get hit with a signup/login screen. Make auth feel like a natural moment in the user's journey.
+
+Login and signup screens set the tone for the user's entire experience with the app and are important to get right - they should feel like exciting entry points into the next level of the user journy. A janky login form with misaligned inputs and no feedback dminishes excitement and undermines trust before the user even gets in.
+
+Login and signup are separate moments - even if the underlying code is the same for both. A new user signing up should feel like they are creating a new account. A user logging in should feel like they are being welcomed back. Auth is always a pain for users, even when it's as frictionless as this, so take care to use Sign Up screens as moments to communicate value and help the user get excited about what they are joining.
+
+Consult the `visualDesignExpert` to help you work through authentication at a high level, including when and where to show auth, and the design of specific screens.
+
+### Rules for Building Auth Screens
+**Auth modes:** Think about which mode(s) makes the most sense for the type of app you are building. Consumer apps likely to be used on mobile should probably tend toward SMS auth as the default - business apps used on desktop make more sense to use email verification - or allow both, there's no harm in giving the user choice!
+
+**"Continue with {Org}" (delegated):** When the `<org_context>` block says delegated sign-in is available, a single "Continue with {Org}" button is the primary path — often the *only* one — and there's no verification-code step to design at all (the platform handles it). Give the button real weight in the branded login moment rather than treating it as a secondary option, and use the exact organization name. If the org also allows code methods, delegated goes first with the code form beneath. On return from the handshake (and on dashboard launch), render a brief "Completing sign-in…" state driven by `auth.authStatus === 'authenticating'` — never the login form — so a successful sign-in doesn't flash the logged-out screen.
+
+**Verification code input:** The 6-digit code entry is the critical moment. Prefer to design it as individual digit boxes (not a single text input), with auto-advance between digits, a beautiful animation and auto-submit on paste, and clear visual feedback. The boxes should be large enough to tap easily on mobile. Show a subtle animation on successful verification. Error states should be inline and immediate, not a separate alert. Make sure there is no layout shift when loading in the success/error states - loading spinners must never pop in below the input and shift the content, for example.
+
+**The send/resend flow:** After the user enters their email or phone and taps "Send code," show clear confirmation that the code was sent ("Check your email" with the address displayed). Include a resend option with a cooldown timer (e.g., "Resend in 30s"). The transition from "enter email/phone" to "enter code" should feel smooth, not like a page reload. Always make sure the user can cancel and exit the flow (e.g., they had a typo in their email, or remembered they used a different email to sign up).
+
+**The overall login page:** This is a branding moment. Use the app's full visual identity — colors, typography, any logos, hero imagery, or illustration. A centered card on a branded background is a classic pattern. Don't make it look like a generic SaaS login template. The login page must feel like it belongs to this specific app. Consult the `visualDesignExpert` for guidance on how to really make this shine.
+
+**Post-login transition:** After successful verification, the transition into the app should feel seamless and instant. Avoid a blank loading screen — if data needs to load, show the app shell with skeleton states. Always make sure the user has a way of logging out.
+
+## Testing Auth in Development
+
+Auth works the same in dev/preview as in production — real verification codes are sent to real email addresses and phone numbers. There are two test bypasses:
+
+- **Email:** `remy@mindstudio.ai` — verification code is always `123456`
+- **Phone:** any `555` number (e.g. `+15551234567`) — verification code is always `123456`
+
+All other emails and phone numbers receive real codes. There is no dev-mode bypass, no fake code, and no way to skip verification. When testing auth flows in the preview, use one of the test bypasses above or a real email/phone.
+
+The `runMethod` tool's `userId: "testUser"` shortcut resolves to this same dev-bypass identity. The platform find-or-creates a real users-table row for it on first call and caches the row's UUID for the rest of the dev session. **`auth.userId` inside the method is that UUID — not the literal string `"testUser"`.** The user row already exists, so don't try to insert it. If you need the UUID to seed app-specific rows that reference it (profiles, preferences, foreign keys), read it from any method response or query the users table directly: `SELECT id FROM users WHERE email = 'remy@mindstudio.ai'` (or `phone = '+15555555555'` for SMS-auth apps).
+
+For **"Sign in with Remy"** apps (`auth.methods` is `["remy"]`, with no `email-code`/`sms-code`), `testUser` — and `setupBrowser` — resolve to **the developer's own delegated Remy identity**, not the `remy@mindstudio.ai` code-bypass user. `auth.userId` is still that user's real UUID, but the `remy@mindstudio.ai` email lookup above does not apply — read the UUID from a method response instead.
+
+Browser automation tools (screenshots, automated browser tests) handle their own auth sessions. Scenarios seed database data but do not create browser auth sessions.

package/dist/prompt/{compiled → skills}/files.md

@@ -1,3 +1,9 @@
+---
+name: Files, Storage & CDN
+what: Per-app blob storage the database doesn't model — user uploads, generated documents, marketing images. Stores are private by default (reads authed by the app session, or short-lived signed share links) or deliberately public — public files are CDN-served on the app's own domain and images resize on the fly via query params (width, height, crop, format, dpr), so the frontend requests the size it displays instead of CSS-scaling originals. User uploads go client-direct: the backend mints a token and the browser uploads straight to storage, bytes never pass through a method. SDK actions that produce files (generateImage, generatePdf, …) can write straight into a store, and the CLI uploads build-time assets (heroes, logos, OG images) so binaries never land in git. One store is shared across dev and prod on purpose.
+when: Before defining a file store or writing any upload, download, share-link, or image-serving code — user uploads, generated documents, marketing assets, config blobs, anything durable the app stores outside the database.
+---
+
 # Files & Storage
 
 Per-app blob storage: user uploads, generated documents, images, marketing assets. **Think of a store

package/dist/prompt/{compiled → skills}/scenarios.md

@@ -1,3 +1,9 @@
+---
+name: Scenarios
+what: Seed scripts that reset the dev database to a specific state — the platform truncates all tables, runs an async function of plain `db.push()` calls, then impersonates a role, so the same scenario always produces the same state. They're how the user tests the app from each role's perspective and how a freshly built app makes its first impression already populated with data that fits its vibe. Declared in the manifest, written at `dist/methods/.scenarios/`.
+when: Before writing or editing a scenario — including the initial build, where scenarios are required. Covers file placement and imports, truncate semantics, what scenarios must not touch (file stores, data sources), and seeding realistic data and bespoke images.
+---
+
 # 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.

package/dist/prompt/{compiled → skills}/secrets.md

@@ -1,3 +1,9 @@
+---
+name: Secrets & Environment Variables
+what: Encrypted per-app secrets injected into backend method execution as `process.env`, with separate dev and prod values resolved automatically by execution context — test keys in the sandbox, live keys in releases, same code. Only for third-party services the MindStudio SDK doesn't already cover (a Stripe key, a webhook signing secret, a direct external API): the SDK handles auth, billing, and key management for AI models and platform integrations itself, so most apps never need one. Backend-only — secrets never reach frontends or interfaces.
+when: Before wiring a credential for an external service the SDK doesn't provide — never for AI model keys or platform-provided integrations (use the SDK), and never in frontend code.
+---
+
 # Secrets & Environment Variables
 
 Apps can store encrypted secrets (API keys, database URLs, tokens) that get injected into method execution as `process.env` variables. Secrets have separate dev and prod values — dev values are used in the editor sandbox, prod values are used in deployed releases.

package/dist/prompt/skills/voiceInterfaces.md

@@ -385,15 +385,21 @@ How answering works:
   in-call verification flow. The agent can serve whatever anonymous callers are allowed, and
   offers verification when the caller wants something account-bound.
 - **Verification uses the app's own auth methods** (`sms-code` / `email-code` from the
-  manifest), existing accounts only — there is no sign-up over the phone:
-  - SMS: a code is texted to the number the caller is calling from, if an account has that
-    number on file. No other number is possible by design.
-  - Email: the caller says their address; the platform matches it against the app's users
-    (transcription-tolerant — no letter-by-letter spelling ceremony) and emails the account's
-    stored address a code.
-  - The flow never confirms or denies that an account exists — a code is "sent if an account
-    matches", always phrased that neutrally. The persona should offer verification naturally
-    when it unlocks something, never as a robotic gate.
+  manifest):
+  - SMS: a code is texted to the phone number on the call (no other number is possible by
+    design), and confirming it signs the caller in — **creating their account if they're new**,
+    the same find-or-create policy `sms-code` has on web (enabling the method is what enables
+    sign-up; there is no separate toggle on either surface). After a first-time caller verifies,
+    the session-context method re-fires with the fresh identity — that's the hook for seeding a
+    new account with data.
+  - Email: existing accounts only — the caller says their address; the platform matches it
+    against the app's users (transcription-tolerant — no letter-by-letter spelling ceremony) and
+    emails the account's stored address a code. There is no sign-up by email over the phone: a
+    call can't reliably capture a verbatim never-seen address, so new callers sign up by text
+    instead.
+  - The email flow never confirms or denies that an account exists — a code is "sent if an
+    account matches", always phrased that neutrally. The persona should offer verification
+    naturally when it unlocks something, never as a robotic gate.
 - **Verified mid-call, upgraded mid-call**: once the code checks out, the session becomes that
   user's — Current User block, roles on every tool call — without redialing.