@mindstudio-ai/remy 0.1.268 → 0.1.270

package/dist/prompt/compiled/auth.md

@@ -1,437 +1,42 @@
 # 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).
+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, cookie sessions, and role enforcement. Apps without auth config use anonymous guest sessions — the default, and fine for single-user apps, internal utilities, and simple tools.
 
 **Auth is optional.** Many apps don't need it. Only add auth when the app needs to identify users or restrict access.
 
-## Manifest Config
+Four auth methods, combinable per app in the manifest:
 
-```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* above.
-- **`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`.
+- `email-code` — 6-digit code sent via email. The natural default for business/desktop apps.
+- `sms-code` — 6-digit code sent via SMS. The natural default for consumer/mobile apps.
+- `api-key` — programmatic access via `Authorization: Bearer sk_...`; resolves to a user with full RBAC.
+- `remy` — org-delegated "Sign in with Remy" (see below). Internal apps only; org-gated.
 
-## Auth Table
+**Before writing any auth code — the manifest `auth` config, the user table, login/signup UI, frontend `auth.*` calls, API keys — load the `auth` skill.** It has the full contract: config schema, platform-managed columns, the frontend SDK (flows, auth state, error codes, phone/email helpers), delegated sign-in implementation, worked examples, and the auth-screen design rules.
 
-The user table is a regular `defineTable` table. The platform manages the auth-mapped columns; all other columns are the developer's domain.
+## Backend Enforcement
 
 ```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
+import { auth } from '@mindstudio-ai/agent';
 ```
 
-### SMS Code Flow
-
-```typescript
-const { verificationId } = await auth.sendSmsCode('+15551234567');
-const user = await auth.verifySmsCode(verificationId, '123456');
-```
+- **`auth.userId`** — the current user's ID (row ID in the auth table), or `null` for unauthenticated requests. Check for null before using in queries when the method might be called without auth.
+- **`auth.requireRole(...roles)`** — throws 401 if unauthenticated, 403 if the user has none of the listed roles (OR semantics). `auth.hasRole(...roles)` is the non-throwing boolean form. `auth.roles` is the current user's role array.
+- **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.
+- **System role:** when the platform invokes a method on behalf of the app (cron, webhook, email), execution runs with `auth.roles: ['system']` — use `auth.requireRole('system')` to restrict a method to platform triggers. Web frontend, API, and agent calls run as the authenticated user and never get the system role unless explicitly assigned.
 
 ## 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.
+Some apps are owned by an organization that centralizes sign-in. The `<org_context>` block (near the end of this prompt) states the facts; here is how to act on them:
 
-- **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 "Sign in with Remy" is available** — offer delegated sign-in: a "Continue with {Org}" button (exact organization name from the block). For an org-owned app this is usually the primary sign-in — 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 block is absent, or has no delegated-sign-in line** (the common case) — do not build or offer it. It's an enterprise scheme for internal apps only.
+- Delegated users' **roles and email are platform-managed** — enforce with `requireRole`/`hasRole` as usual, but never assign their roles from app code.
 
-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
+## Designing Auth Into the Experience
 
-```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.
+Authentication moments must feel natural and intuitive — never jarring or surprising. For the overwhelming majority of apps, a user should never land on auth at the root of the app on first open: let them explore public resources or meet a landing/introduction moment first (an internal tool can gate at the root, but as a welcome/splash, not an error state). Login and signup are separate moments even when the code is shared — signup should communicate value and build excitement about what the user is joining; login should feel like being welcomed back. The login page is a branding moment: the app's full visual identity, not a generic SaaS template. Consult the `visualDesignExpert` on when and where auth appears in the journey and on the screens themselves; the `auth` skill carries the concrete screen-building rules.
 
 ## 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.
+Real verification codes are sent to real addresses in dev — the only bypasses are `remy@mindstudio.ai` (email) and any `555` phone number, both with fixed code `123456`. There is no other fake code or skip. `runMethod`'s `userId: "testUser"` resolves to a real users-table row for that same identity — **`auth.userId` inside the method is that row's UUID, not the literal string `"testUser"`**, and the row already exists (don't insert it). Full detail, including the "Sign in with Remy" variant, is in the `auth` skill.

package/dist/prompt/compiled/design.md

@@ -53,6 +53,8 @@ Every interface must work on both desktop and mobile. Think about how the app wi
 
 The `designExpert` can create and source amazing, high quality images, graphics, illustrations, and logos to use in the interface - both with and without transparency. This is a huge level for upgrading the premium look, feel, and quality of the app. Use image logos directly instead of plain text wordmarks; use images for empty states, onboarding screens, full-screen loading, and more.
 
+Public CDN images accept resize query params — request the size the layout actually displays (e.g. `?w=400&dpr=2` so it stays crisp on Retina) instead of CSS-scaling a full-res original. The full parameter table is in the `files` skill.
+
 ## Forms
 
 Forms should feel like interactions, not paperwork.
@@ -82,8 +84,8 @@ Buttons should use a small animated spinner during loading, not text labels like
 The UI should feel instant. Never make the user wait for a server round-trip to see the result of their own action. Consider loading a bunch of data in one API call, rather than a bunch of small calls (e.g., if loading a post, also preload comments, likes, user artifacts, etc - don't use separate API calls for each GET).
 
 - **Optimistic updates.** When a user adds a row, toggles a setting, or submits a form, update the UI immediately and let the backend confirm in the background. If the backend fails, revert and show an error.
-- **Use SWR for data fetching** (`useSWR` from the `swr` package). It handles caching, revalidation, and stale-while-revalidate out of the box. Prefer SWR over manual `useEffect` + `useState` fetch patterns.
-- **Mutate after actions.** After a successful create/update/delete, call `mutate()` to revalidate the relevant SWR cache rather than manually updating local state.
+- **Data fetching.** For apps that can load everything on startup, use a Zustand store with a single initial fetch (see the coding instructions) — SWR (`useSWR`) is for server-cache patterns where data is too large or dynamic to hold in memory. Whichever fits, never leave fetches as ad-hoc `useEffect` + `useState` patterns.
+- **Mutate after actions.** After a successful create/update/delete, update the store optimistically (or call `mutate()` to revalidate the relevant cache when using SWR) rather than refetching everything.
 - **Skeleton loading.** Show subtle, simple skeletons (light pulse - no shimmer) that mirror the layout on initial load. Never show a blank page or centered spinner while data is loading.
 
 ### Errors

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

@@ -48,14 +48,7 @@ Every live deploy runs an automated Lighthouse audit of the app. Pull it via `mi
 
 ### 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`.
+Schema changes are automatic — adds and drops of tables/columns are diffed from the table definitions and applied as DDL (type changes and renames are not supported; full rules in the Tables docs). 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
 

package/dist/prompt/compiled/interfaces.md

@@ -61,7 +61,7 @@ const api = createClient<{
 const { vendorId } = await api.submitVendorRequest({ name: 'Acme' });
 const { vendors } = await api.listVendors();
 
-// File upload → client-direct to the app's file store (see Files & Storage).
+// File upload → client-direct to the app's file store (load the `files` skill for the backend side).
 // A backend method mints an upload token; the browser uploads straight to storage.
 const token = await api.getUploadSlot({ filename: file.name, contentType: file.type });
 const { key, url } = await platform.upload(token, file);
@@ -79,11 +79,9 @@ auth.getCurrentUser()               // AppUser { id, email, phone, roles, create
 auth.currentUser                    // same as getCurrentUser() (sync getter)
 auth.isAuthenticated()              // boolean
 auth.onAuthStateChanged(cb)         // fires immediately + on transitions; returns unsubscribe
-auth.sendEmailCode(email)           // → { verificationId }
-auth.verifyEmailCode(verId, code)   // → AppUser (sets session)
-auth.sendSmsCode(phone)             // → { verificationId }
-auth.verifySmsCode(verId, code)     // → AppUser (sets session)
 auth.logout()                       // clears session
+// Verification flows (send/verify email + SMS codes, delegated sign-in, API keys)
+// are in the `auth` skill — load it before building login/signup.
 ```
 
 For apps with an agent interface, the SDK also provides `createAgentChatClient()` for thread management and streaming chat. Load the `agentInterfaces` skill for its usage — thread APIs, streaming callbacks, and attachments are all there.
@@ -154,43 +152,27 @@ Each has its own skill carrying the config shape, the input the method receives,
 
 ## Cron
 
-Scheduled method execution — a method plus a cron expression, synced to the platform on deploy.
-
-**Load the `scheduledJobs` skill** before adding one.
+Scheduled method execution — a method plus a cron expression, synced to the platform on deploy. **Load the `scheduledJobs` skill** before adding one.
 
 ## Webhook
 
-Inbound HTTP endpoints that invoke a method directly and synchronously — the caller waits for the method to finish. Use for receiving webhooks from external services (Stripe, GitHub, Shopify, Slack, Twilio). Direct inbound webhooks with signature verification work natively; do **not** build confirmation-token or polling workarounds.
-
-Routing is by a secret in the URL rather than an auth header, which is what makes it the right fit for provider callbacks — they can't send a bearer token. The API interface is the alternative when the caller can.
-
-**Load the `webhooks` skill** before adding one — the secret semantics, endpoint URL, input shape, and signature verification are all there.
+Inbound HTTP endpoints that invoke a method directly and synchronously. Use for provider callbacks (Stripe, GitHub, Shopify, Slack, Twilio) — signature verification works natively; do **not** build confirmation-token or polling workarounds. Routing is by a secret in the URL rather than an auth header, which is what fits callers that can't send a bearer token; the API interface is the alternative when they can. **Load the `webhooks` skill** before adding one.
 
 ## Email
 
-Inbound email triggers. Each app has one email-handler method; the platform routes all inbound mail destined for the app — across any of its address tiers — to that method. Addresses on the app's subdomain are catchall, so per-purpose addresses (`support@`, `receipts@`) work without registering anything.
-
-**Load the `inboundEmail` skill** before writing the handler — address tiers, `approvedSenders`, the input shape, in-thread replies, and attachments are all there.
+Inbound email triggers: one handler method per app, and the platform routes all inbound mail for the app to it. Addresses on the app's subdomain are catchall, so per-purpose addresses (`support@`, `receipts@`) work without registering anything. **Load the `inboundEmail` skill** before writing the handler.
 
 ## MCP (Model Context Protocol)
 
-Expose the app to *external* AI agents — Claude Desktop, Cursor, other people's agents, anything that speaks MCP. Unlike the agent interface (which *is* an agent — its own LLM, personality, and chat UI), MCP has no model of its own; it's the app projected as an MCP server for an outside AI to drive.
-
-It supports the full MCP surface: tools (methods the agent can call), resources (read-only app data addressable by URI), prompts (parameterized templates), and instructions (server-level guidance for the whole toolset). The platform hosts the server, handles auth, and derives every tool's input schema from the method contract.
-
-**Load the `mcpInterfaces` skill** before authoring `src/interfaces/mcp.md`. Because the consumer is an external agent with no knowledge of your app, the descriptions are the product — the skill carries both how to write them and the full config contract.
+The app projected as an MCP server for *external* AI agents to drive (Claude Desktop, Cursor, other people's agents). Unlike the agent interface — which IS an agent, with its own LLM — MCP has no model of its own. The platform hosts the server, handles auth, and derives tool schemas from method contracts. **Load the `mcpInterfaces` skill** before authoring `src/interfaces/mcp.md` — the consumer knows nothing about your app, so the descriptions are the product.
 
 ## Agent (Conversational Interface)
 
-A conversational interface where an LLM has access to the app's methods as tools. Unlike MCP (which exposes methods for external agents), the agent interface IS the agent — it has its own personality, system prompt, and model config, and orchestrates tool calls against the app's methods internally. Chat runs as the authenticated user, so every tool call carries that user's roles. The config must declare an `auth` block (`{ "requireUser": boolean, "requireRole"?: string[] }`) gating who may chat at all.
-
-**Load the `agentInterfaces` skill** before authoring `src/interfaces/agent.md` or building the chat UI — the spec frontmatter, compiled output, `agent.json`, and the entire frontend surface are all there.
+A conversational interface where the app's own LLM orchestrates its methods as tools — its own personality, system prompt, and model config (the inverse of MCP). Chat runs as the authenticated user, so every tool call carries that user's roles, and the config must declare an `auth` block (`{ "requireUser": boolean, "requireRole"?: string[] }`) gating who may chat at all. **Load the `agentInterfaces` skill** before authoring `src/interfaces/agent.md` or building the chat UI.
 
 ## Voice (Realtime Conversation)
 
-The app's agent as a live voice conversation — the user talks, and the agent answers in sub-second, interruptible speech, calling methods mid-conversation. A sibling of the agent interface, not a mode of it: its own spec, a persona written for the ear rather than the screen, and a smaller toolset where every tool carries a latency class governing how the agent handles the wait out loud. Sessions run as the authenticated user, so tool calls carry that user's roles; the platform handles the realtime media, turn-taking, barge-in, and transcripts. The config must declare an `auth` block (`{ "requireUser": boolean, "requireRole"?: string[] }`) gating who may start a session at all.
-
-**Load the `voiceInterfaces` skill** before authoring `src/interfaces/voice.md` or building the voice UI — the spoken-register rules, latency classes, spec format, `interface.json`, and the `createVoiceClient()` frontend surface are all there.
+The app's agent as a live, interruptible voice conversation — a sibling of the agent interface, not a mode of it, with its own spec and a smaller toolset where every tool carries a latency class. Sessions run as the authenticated user, and the config must declare the same `auth` block gating who may start a session. **Load the `voiceInterfaces` skill** before authoring `src/interfaces/voice.md` or building the voice UI.
 
 ## Manifest Declaration