@mindstudio-ai/remy 0.1.114 → 0.1.116

package/dist/automatedActions/buildFromInitialSpec.md

@@ -4,7 +4,7 @@
 
 This is an automated action triggered by the user pressing "Build" in the editor after reviewing the spec.
 
-The user has reviewed the spec and is ready to build. There are four phases to building: planning, coding, polishing, verifying. Execute each phase in order in a single turn.
+The user has reviewed the spec and is ready to build. There are four phases to building: planning, coding, verifying, polishing. Execute each phase in order in a single turn.
 
 ## Planning
 Think about your approach and then get a quick sanity check from `codeSanityCheck` to make sure you aren't missing anything. 
@@ -14,14 +14,15 @@ If you are building a web frontend, consult `visualDesignExpert` for guidance an
 ## Building
 Then, build everything in one turn: methods, tables, interfaces, manifest updates, and scenarios, using the spec as the master plan. Be sure to delete any unnecessary files from the "Hello World" scaffold that already exist in the project - don't forget to update the page metadata on index.html too.
 
-## Polishing
-When code generation is complete, take a step back and do an explicit polish pass before verifying. Re-read the spec files and the design expert's guidance, then walk through each frontend file looking for design details that got skipped in the initial build: animations, transitions, hover states, micro-interactions, spring physics, entrance reveals, gesture handling, layout issues, and anything else. The initial build prioritizes getting everything connected and functional, but this pass closes the gap between "it works" and "it feels great." In many ways this is the most important part of the initial build, as the user's first experience of the deliverable will set their expectations for every iteration that follows. Don't mess this up.
-
 ## Verifying
 - First, run use `runScenario` to seed test data, then use `runMethod` to confirm important methods work 
 - If the app has a web frontend, check the browser logs to make sure there are no errors rendering it.
-- Ask the `visualDesignExpert` to take a screenshot and verity that the visual design looks correct. Fix any issues it flags - we want the user's first time seeing the finished product to truly wow them.
-- Finally, use `runAutomatedBrowserTest` to smoke-test the main UI flow. The dev database is a disposable snapshot, so don't worry about being destructive. Fix any errors before finishing.
+- Use `runAutomatedBrowserTest` to smoke-test the main UI flow. The dev database is a disposable snapshot, so don't worry about being destructive. Fix any errors before finishing.
 - If there is a scenario that seeds the app with mock data, use it to present the app to the user with initial data seeded, so they can see and play with the real app. Let the user know they can reset the app using a scenario to empty it if they wish. Showing the user something they can play with immediately is important when it comes to landing a strong first impression.
 
+## Polishing
+When code generation is complete, take a step back and do an explicit polish pass before verifying. Re-read the spec files and the design expert's guidance, then walk through each frontend file looking for design details that got skipped in the initial build: animations, transitions, hover states, micro-interactions, spring physics, entrance reveals, gesture handling, layout issues, and anything else. The initial build prioritizes getting everything connected and functional, but this pass closes the gap between "it works" and "it feels great." In many ways this is the most important part of the initial build, as the user's first experience of the deliverable will set their expectations for every iteration that follows. Don't mess this up.
+
+Then, ask the `visualDesignExpert` to take a screenshot and verity that the visual design looks correct. Fix any issues it flags - we want the user's first time seeing the finished product to truly wow them.
+
 When everything is working, use `productVision` to mark the MVP roadmap item as done, then call `setProjectOnboardingState({ state: "onboardingFinished" })`.

package/dist/headless.js

@@ -3162,6 +3162,39 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
 
 // src/subagents/browserAutomation/tools.ts
 var BROWSER_TOOLS = [
+  {
+    clearable: false,
+    name: "setupBrowser",
+    description: "Pre-authenticate the browser and optionally navigate to a starting page. Call this before interacting with authenticated content instead of manually logging in. Auth is optional \u2014 omit to just navigate without authenticating.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        auth: {
+          type: "object",
+          description: "Authentication config. Upserts the user if they don't exist.",
+          properties: {
+            email: {
+              type: "string",
+              description: "User email address."
+            },
+            phone: {
+              type: "string",
+              description: "User phone number."
+            },
+            roles: {
+              type: "array",
+              items: { type: "string" },
+              description: "Roles to set on the user."
+            }
+          }
+        },
+        path: {
+          type: "string",
+          description: 'Navigate to this path after setup (default "/").'
+        }
+      }
+    }
+  },
   {
     clearable: true,
     name: "browserCommand",
@@ -3334,6 +3367,21 @@ var browserAutomationTool = {
         tools: BROWSER_TOOLS,
         externalTools: BROWSER_EXTERNAL_TOOLS,
         executeTool: async (name, _input, _toolCallId, onLog) => {
+          if (name === "setupBrowser") {
+            try {
+              const result2 = await sidecarRequest(
+                "/setup-browser",
+                {
+                  auth: _input.auth,
+                  path: _input.path
+                },
+                { timeout: 15e3 }
+              );
+              return JSON.stringify(result2);
+            } catch (err) {
+              return `Error setting up browser: ${err.message}`;
+            }
+          }
           if (name === "screenshotFullPage") {
             try {
               return await captureAndAnalyzeScreenshot({
@@ -3605,7 +3653,7 @@ var definition5 = {
       },
       instructions: {
         type: "string",
-        description: "If the screenshot you need requires interaction first (dismissing a modal, clicking a tab, filling out a form, navigating a flow), describe the steps to get there. A browser automation agent will follow these instructions before capturing the screenshot. You will always get back a full-height screenshot of the entire page. Do not attempt to scroll or capture specific areas. Only use instructions when you need to trigger stateful changes."
+        description: "If the screenshot you need requires interaction first (dismissing a modal, clicking a tab, filling out a form, navigating a flow, getting through a login/auth checkpoint), describe the steps to get there. A browser automation agent will follow these instructions before capturing the screenshot - it can bypass auth and get right to where it needs to be if you tell it to authenticate as a test user and give it the path/screen to start its test at. You will always get back a full-height screenshot of the entire page. Do not attempt to scroll or capture specific areas. Only use instructions when you need to trigger stateful changes. Never describe what names or values to use when applying the isntructions - the browser automation agent must use its own values for it to work properly."
       }
     }
   }

package/dist/index.js

@@ -2903,6 +2903,39 @@ var init_tools = __esm({
   "src/subagents/browserAutomation/tools.ts"() {
     "use strict";
     BROWSER_TOOLS = [
+      {
+        clearable: false,
+        name: "setupBrowser",
+        description: "Pre-authenticate the browser and optionally navigate to a starting page. Call this before interacting with authenticated content instead of manually logging in. Auth is optional \u2014 omit to just navigate without authenticating.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            auth: {
+              type: "object",
+              description: "Authentication config. Upserts the user if they don't exist.",
+              properties: {
+                email: {
+                  type: "string",
+                  description: "User email address."
+                },
+                phone: {
+                  type: "string",
+                  description: "User phone number."
+                },
+                roles: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Roles to set on the user."
+                }
+              }
+            },
+            path: {
+              type: "string",
+              description: 'Navigate to this path after setup (default "/").'
+            }
+          }
+        }
+      },
       {
         clearable: true,
         name: "browserCommand",
@@ -3138,6 +3171,21 @@ var init_browserAutomation = __esm({
             tools: BROWSER_TOOLS,
             externalTools: BROWSER_EXTERNAL_TOOLS,
             executeTool: async (name, _input, _toolCallId, onLog) => {
+              if (name === "setupBrowser") {
+                try {
+                  const result2 = await sidecarRequest(
+                    "/setup-browser",
+                    {
+                      auth: _input.auth,
+                      path: _input.path
+                    },
+                    { timeout: 15e3 }
+                  );
+                  return JSON.stringify(result2);
+                } catch (err) {
+                  return `Error setting up browser: ${err.message}`;
+                }
+              }
               if (name === "screenshotFullPage") {
                 try {
                   return await captureAndAnalyzeScreenshot({
@@ -3494,7 +3542,7 @@ var init_screenshot3 = __esm({
           },
           instructions: {
             type: "string",
-            description: "If the screenshot you need requires interaction first (dismissing a modal, clicking a tab, filling out a form, navigating a flow), describe the steps to get there. A browser automation agent will follow these instructions before capturing the screenshot. You will always get back a full-height screenshot of the entire page. Do not attempt to scroll or capture specific areas. Only use instructions when you need to trigger stateful changes."
+            description: "If the screenshot you need requires interaction first (dismissing a modal, clicking a tab, filling out a form, navigating a flow, getting through a login/auth checkpoint), describe the steps to get there. A browser automation agent will follow these instructions before capturing the screenshot - it can bypass auth and get right to where it needs to be if you tell it to authenticate as a test user and give it the path/screen to start its test at. You will always get back a full-height screenshot of the entire page. Do not attempt to scroll or capture specific areas. Only use instructions when you need to trigger stateful changes. Never describe what names or values to use when applying the isntructions - the browser automation agent must use its own values for it to work properly."
           }
         }
       }

package/dist/prompt/compiled/auth.md

@@ -86,11 +86,25 @@ interface AppUser {
 
 `auth.getCurrentUser()` returns `AppUser | null`. `null` means unauthenticated.
 
-### State (sync)
+### State
 
 ```typescript
-auth.getCurrentUser()    // AppUser | null
-auth.isAuthenticated()   // boolean
+auth.getCurrentUser()         // AppUser | null
+auth.currentUser              // AppUser | null (sync getter, same as getCurrentUser())
+auth.isAuthenticated()        // boolean
+auth.onAuthStateChanged(cb)   // fires immediately with current user, then on every
+                              // auth transition (verify, confirm, logout).
+                              // 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
@@ -125,6 +139,19 @@ const user = await auth.confirmPhoneChange('+15559876543', '123456');
 await auth.logout();  // clears session
 ```
 
+### 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 |
+
 ### Phone Helpers
 
 ```typescript
@@ -176,31 +203,56 @@ Returns an array of user IDs with the specified role.
 ## 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 [codeSent, setCodeSent] = useState(false);
+  const [error, setError] = useState('');
+
+  // Redirect when authenticated (fires via onAuthStateChanged after verify)
+  useEffect(() => { if (user) navigate('/dashboard'); }, [user]);
 
   const handleSendCode = async () => {
-    const { verificationId } = await auth.sendEmailCode(email);
-    setVerificationId(verificationId);
-    setCodeSent(true);
+    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 () => {
-    await auth.verifyEmailCode(verificationId, code);
-    window.location.href = '/dashboard';
+    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 (!codeSent) {
+  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>
     );
   }
@@ -210,6 +262,8 @@ function LoginPage() {
       <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>
   );
 }
@@ -251,3 +305,23 @@ Roles are declared in the manifest, stored as an array column on the user table,
 ## 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.
+
+## 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.
+
+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!
+
+**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.

package/dist/prompt/compiled/design.md

@@ -47,6 +47,7 @@ Every interface must work on both desktop and mobile. Think about how the app wi
 - On mobile, stack gracefully. Prioritize content and actions.
 - Test at both extremes. A layout that only looks good at one breakpoint is not done.
 - When the app is primarily mobile (e.g., a mobile-first consumer app, a tool designed for on-the-go use), set `"defaultPreviewMode": "mobile"` in `web.json` so the editor previews in a mobile viewport by default.
+- Even for mobile-first apps, make sure to set desktop or larger device breakpoints - nothing looks jankier than opening a mobile-designed site in a desktop browser and seeing a full width bottom tab bar with nav icons stretching 1000px wide. Don't make sloppy, amateur mistakes or omissions like this - the user will notice them and be disappointed.
 
 ## Images
 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.
@@ -88,25 +89,6 @@ The UI should feel instant. Never make the user wait for a server round-trip to
 
 Handle errors gracefully. You don't need to design for every error case, but if remote API requests fail, make sure to show them nicely in a toast or some other appropriate view with a human-friendly label - don't just drop "Error 500 XYZ" inline in a form.
 
-## Auth
-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.
-
-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. MindStudio apps support SMS code verification, email verification, or both, depending on how the app is configured.
-
-### Rules for building auth screens
-
-Consult the `visualDesignExpert` to help you work through authentication at a high level. For most 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). 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.
-
-**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!
-
-**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.
-
-**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 additional guidance.
-
-**Post-login transition:** After successful verification, the transition into the app should feel seamless. 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.
-
 ## FTUE
 
 All interactive apps must be intuitive and easy to use. Form elements must be well-labelled. Complex interfaces should have descriptions or tooltips when helpful. Complex apps benefit from a beautiful simple onboarding modal on first use or a simple click tour. Mobile apps need a beautiful welcome screen sequence that orients the user to the app. Ask the `visualDesignExpert` for advice here. 

package/dist/prompt/compiled/interfaces.md

@@ -75,8 +75,10 @@ const url = await platform.uploadFile(file, {
 controller.abort(); // cancels the upload
 
 // Auth (for apps with auth enabled in manifest)
-auth.getCurrentUser()    // AppUser { id, email, phone, roles, createdAt } | null
-auth.isAuthenticated()   // boolean
+auth.getCurrentUser()               // AppUser { id, email, phone, roles, createdAt } | null
+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 }

package/dist/prompt/static/authoring.md

@@ -12,7 +12,7 @@ After intake, write the spec immediately. Do not ask "ready for me to start?" or
 The scaffold starts with these spec files that cover the full picture of the app:
 
 - **`src/app.md`** — the core application: what it does, how data flows, who's involved, the rules
-- **`src/interfaces/web.md`** — the web interface: layout, screens, interactions, user experience
+- **`src/interfaces/web.md`** — the web interface: layout, screens, interactions, anduser experience, in detail
 - **`src/interfaces/@brand/visual.md`** — aesthetic direction: the overall look, surfaces, spacing, interaction feel
 - **`src/interfaces/@brand/colors.md`** (`type: design/color`) — brand color palette: 3-5 named colors with evocative names and brand-level descriptions. The design system is derived from these.
 - **`src/interfaces/@brand/typography.md`** (`type: design/typography`) — font choices with source URLs and 1-2 anchor styles (Display, Body). Additional styles are derived from these anchors.

package/dist/prompt/static/team.md

@@ -40,7 +40,7 @@ Always consult the code sanity check before writing code in initialCodegen with
 
 For verifying complex stateful interactions: multi-step form submissions, auth flows, real-time updates, flows that require specific data/role setup. This spins up a full chrome browser automation — it's heavyweight and takes minutes to complete a full test. Do not use it for basic rendering or navigation checks. If you can verify something with a screenshot or by reading the code, do that instead. Don't run it constantly after making small changes - save it for meaningful work. Run a scenario first to seed test data and set user roles. The user is able to watch QA work on their screen via a live browser preview - the cursor will move, type, etc - so you can also use this to demo functionality to the user and help them understand how to use their app.
 
-The QA agent can see the screen. Describe what to test, not how — it will figure out what to click, what to check, and what values to use. It always starts its tests logged out/unauthenticated on "/" root. After every test session, the browser is reset to / and any authentication used or created by the tester is cleared and reset.
+The QA agent can see the screen. Describe what to test, not how — it will figure out what to click, what to check, and what values to use. By default, it always starts its tests logged out/unauthenticated on "/" root, but if you want to test a deeper piece of the app it can bypass auth and automatically authenticate itself as any user/role - just tell it to authenticate as the test user and navigate to X to start the test. After every test session, the browser is reset to / and any authentication used or created by the tester is cleared and reset.
 
 Never tell QA what names to use when testing or what values to input - it will use its own judgment.
 

package/dist/subagents/browserAutomation/prompt.md

@@ -2,17 +2,19 @@ You are a browser smoke test agent. You verify that features work end to end by
 
 ## Rules to Remember
 - Don't overthink the tests - the goal is to generally make sure things work as expected, not to provide detailed QA. If something seems mostly okay, note it and move on. Don't continue exploring to try to diagnose specific issues or get specific details unless you are asked to.
-- Fail early: If you encounter a showstopper bug (something doesn't load, something is broken, etc.) do not attempt to diagnose it or work around it. Return early with a report to let the developer fix it, they'll run another test when they're ready.
+- Fail early: If you encounter a showstopper bug (something doesn't load, something is broken, etc.) do not attempt to diagnose it or work around it. We need core common user paths to work - if they don't the app is broken and testing should not continue until it is fixed. Return early with a report to let the developer fix it, they'll run another test when they're ready.
 
 ## Tester Persona
 The user is watching the automation happen on their screen in real-time. When typing into forms or inputs, behave like a realistic user of this specific app. Use the app context (if provided) to understand the audience and tone. Type the way that audience would actually type — not formal, not robotic. The app developer's name is Remy - you must use that and the email remy@mindstudio.ai as the basis for any testing that requires a persona.
 
 ### Auth Testing
-When the app has a login or signup flow, you must use `remy@mindstudio.ai` for email and `+15551234567` for phone number. In the dev environment, verification codes are bypassed for this email address only and any 555-prefixed phone number — enter any 6-digit code (e.g., `123456`) and it will be accepted. If the content you are trying to test is gated behind auth, always use these credentials to login and continue testing.
+When the content you need to test is behind authentication, use the `setupBrowser` tool to automatically pre-authenticate instead of manually navigating login flows. This mints a session cookie, reloads the page with the authenticated state, and optionally navigates to a starting path. Use `remy@mindstudio.ai` as the email. If the test requires a specific role, pass it in the `roles` array.
+
+If you need to test the login/signup flow itself (e.g., verifying the UI, error states, or the verification code input), navigate it manually: use `remy@mindstudio.ai` for email and `+15551234567` for phone. In the dev environment, verification codes are bypassed for this email and any 555-prefixed phone number — enter any 6-digit code (e.g., `123456`).
 
 ## Browser Commands
 
-Your session always starts on the app root / in a logged out/unauthenticated state.
+Your session always starts on the app root / in a logged out/unauthenticated state. Use `setupBrowser` to authenticate before testing protected pages.
 
 ### Snapshot format
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.114",
+  "version": "0.1.116",
   "description": "MindStudio coding agent",
   "repository": {
     "type": "git",