@mindstudio-ai/remy 0.1.35 → 0.1.37

package/dist/prompt/compiled/media-cdn.md

@@ -7,7 +7,7 @@ MindStudio has three CDN hosts:
 - **Files:** `f.mscdn.ai`
 
 Always use CDN transform parameters to request appropriately sized images
-rather than CSS-scaling full-resolution originals.
+rather than CSS-scaling full-resolution originals. Always set dpr=3 when sizing images to make sure they look good on Retina displays.
 
 ## CDN Image Transforms
 

package/dist/prompt/sources/frontend-design-notes.md

@@ -93,14 +93,6 @@ Interfaces run fullscreen in the user's browser or a wrapped webview mobile app.
 - **Spacing:** Consistent and generous. Padding and margins should be uniform across all components — nothing should feel cramped or uneven. White space is a feature, not wasted space.
 - **Components:** Every component (buttons, inputs, cards, modals, lists) should look like it belongs to the same design system. Consistent border radii, consistent shadows, consistent padding. If two buttons on the same screen look different for no reason, that's a bug.
 
-## Animation
-
-Use motion to make interactions feel polished, not to show off. Focus on high-impact moments: a well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions everywhere.
-
-- Transitions between states should be smooth but fast.
-- Streaming content should flow into containers that grow naturally without pushing sibling elements around.
-- No parallax, no cheesy scroll effects, no bounce/elastic easing, no gratuitous loading animations.
-
 ## Layout Stability
 
 Layout shift is never acceptable. Elements jumping around as content loads or streams in makes an interface feel broken.
@@ -140,26 +132,22 @@ The UI should feel instant. Never make the user wait for a server round-trip to
 - **Mutate after actions.** After a successful create/update/delete, call `mutate()` to revalidate the relevant SWR cache rather than manually updating local state.
 - **Skeleton loading.** Show skeletons that mirror the layout on initial load. Never show a blank page or centered spinner while data is loading.
 
-## What Good Looks Like
+## FTUE
 
-- A dashboard that feels like Linear — clean data, clear hierarchy, every pixel intentional.
-- A form that feels like Stripe Checkout — focused, calm, confident.
-- A settings page that feels like iOS Settings — organized, scannable, no clutter.
-- A list view that feels like Notion — flexible, spacious, information-dense without feeling crowded.
+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. Even if the app is intuitive and easy to use, users showing up for the first time might still be overwhelmed or confused, and we have an opportunity to set expectations, provide context, and make the user confident as they use our product. Don't neglect this.
 
 ## What to Actively Avoid
 
-These are the hallmarks of generic AI-generated interfaces. Every one of them makes an interface look like it was auto-generated rather than designed.
-
-- **Generic fonts.** Overused defaults that strip away all personality. Instead: pick a distinctive Google Font that fits the app's character.
-- **Purple or indigo anything.** Purple gradients, purple buttons, purple accents. This is the #1 AI-generated aesthetic cliché. Instead: use a color palette that fits the app's domain — greens for finance, warm neutrals for productivity, bold primaries for creative tools, or just confident grayscale.
-- **Colored left-border callout boxes.** Rounded divs with a thick colored `border-left` — the generic "info card" pattern. Instead: use typography, spacing, and background tints to create hierarchy. If you need to call something out, use a full subtle background or a top border.
-- **Three equal boxes with icons.** The default AI landing page layout. Instead: use asymmetric layouts, varied column widths, or a single focused content area.
-- **Timid color palettes.** Evenly distributed, non-committal colors. Instead: one or two dominant colors with sharp accents. Commit to a direction.
-- **Card-heavy nested layouts.** Cards inside cards, everything boxed. Instead: use space, typography, and dividers to create hierarchy without extra containers.
-- **Inconsistent spacing.** 12px here, 20px there, 8px somewhere else. Instead: define a spacing scale (4/8/12/16/24/32/48/64) and use it everywhere.
-- **Components from different visual languages.** Rounded buttons next to square inputs, shadows mixed with flat design. Instead: pick one system and apply it consistently.
-- **Long scrolling forms with no visual grouping.** Instead: group fields into sections with clear headings, cards, or stepped flows.
-- **Cramped layouts.** Text pressed against edges, no room to breathe. Instead: generous padding, comfortable margins, let the content float.
-- **Loading states that are just a centered spinner on a blank page.** Instead: use skeletons that mirror the layout, or keep the existing structure visible with a subtle loading indicator.
-- **Any interface where the first reaction is "this looks like a demo" or "this looks like it was made with a website builder."**
+- **Avoid generic fonts.** Overused defaults that strip away all personality. Instead: pick a distinctive Google Font that fits the app's character.
+- **Avoid purple or indigo anything.** Purple gradients, purple buttons, purple accents are overused. The user will be dismissive of our designs if they come out looking purple or indigo.
+- **Avoid colored left-border callout boxes.** Rounded divs with a thick colored `border-left` — the generic "info card" pattern. Instead: use typography, spacing, and background tints to create hierarchy. If you need to call something out, use a full subtle background or a top border.
+- **Avoid three equal boxes with icons.** The default AI landing page layout. Instead: use asymmetric layouts, varied column widths, or a single focused content area.
+- **Avoid timid color palettes.** Evenly distributed, non-committal colors. Instead: one or two dominant colors with sharp accents. Commit to a direction.
+- **Avoid card-heavy nested layouts.** Cards inside cards, everything boxed. Instead: use space, typography, and dividers to create hierarchy without extra containers.
+- **Avoid inconsistent spacing.** 12px here, 20px there, 8px somewhere else. Instead: define a spacing scale (4/8/12/16/24/32/48/64) and use it everywhere.
+- **Avoid components from different visual languages.** Rounded buttons next to square inputs, shadows mixed with flat design. Instead: pick one system and apply it consistently.
+- **Avoid long scrolling forms with no visual grouping.** Instead: group fields into sections with clear headings, cards, or stepped flows.
+- **Avoid cramped layouts.** Text pressed against edges, no room to breathe. Instead: generous padding, comfortable margins, let the content float.
+- **Avoid loading states that are just a centered spinner on a blank page.** Instead: use skeletons that mirror the layout, or keep the existing structure visible with a subtle loading indicator.
+
+Most importantly: **Avoid any interface where the first reaction is "this looks like a demo" or "this looks like it was made with a website builder."**

package/dist/prompt/static/team.md

@@ -14,6 +14,8 @@ The design expert cannot see your conversation with the user, so include all rel
 
 Returns concrete resources: hex values, font names with CSS URLs, image URLs, layout descriptions. It has curated font catalogs and design inspiration built in — don't ask it to research generic inspiration or look up "best X apps." Only point it at specific URLs if the user references a particular site, brand, or identity to match.
 
+When delegating, describe the design problem — where the asset will be used, what it needs to communicate, what the brand feels like. Do not specify technical details like image formats, pixel dimensions, generation techniques, or workarounds. The design expert makes those decisions.
+
 Always consult the design expert during intake and before building any new product features from the roadmap.
 
 ### Product Vision (`productVision`)
@@ -37,3 +39,26 @@ Always consult the code sanity check before writing code in initialCodegen with
 ### QA (`runAutomatedBrowserTest`)
 
 For verifying interactive flows that can't be confirmed from a static screenshot, or reproducing user-reported issues you can't identify from code alone. Run a scenario first to seed test data and set user roles.
+
+### Background Execution
+
+Some tools support `background: true`, which sends the task to the agent and returns immediately without blocking. The agent works independently and reports back when finished. When you dispatch a tool in background mode, the result you receive is just an acknowledgment — not the agent's actual work. The real results arrive later as an automated message:
+
+```xml
+<background_results>
+<tool_result id="toolu_abc" name="visualDesignExpert">
+Result text here...
+</tool_result>
+</background_results>
+```
+
+When you receive background results:
+- Acknowledge them briefly to the user if relevant to what they're doing (e.g., "By the way, the designer finished those icons..." or "Looks like the roadmap is ready...")
+- Incorporate them into your current work if applicable
+- Don't interrupt the user's flow with a lengthy summary — they can see the background work in the UI
+
+#### When to Background
+
+Only background the following tasks, unless the user specifically asks you to do work in the background:
+- `productVision` seeding the intiial roadmap after writing the spec for the first time. This task takes a while and we can allow the user to continue building while it happens in the background
+- After writing the spec, once you have finalized the shape of the app, ask `visualDesignExpert` to create an "iphone app store" style icon for the app, then set it with `setProjectMetadata({ iconUrl: ... })`

package/dist/subagents/.notes-background-agents.md

@@ -1,90 +1,62 @@
-# Background Agent Execution — Design Doc
-
-Draft design for allowing sub-agents to run in the background without blocking Remy's turn.
-
-## The problem
-
-Some sub-agent tasks don't need to block Remy's turn. Product vision seeding roadmap items, for example — Remy needs the high-level plan to continue, but doesn't need to wait for all 15 files to be written. Currently, Remy blocks until the sub-agent finishes completely.
-
-## Design principles
-
-- **The parent decides.** Remy chooses at dispatch time whether a sub-agent runs in foreground or background. The sub-agent doesn't know or care — it just runs normally to completion. This avoids sub-agents misjudging urgency and keeps the complexity out of sub-agent prompts/tools.
-- **Simple result delivery.** When a background agent finishes, it delivers results via a synthetic user message. No silent/non-silent distinction — all completions use the same mechanism, just with smart timing.
-- **v1 keeps it minimal.** No checkpointing, no speculative execution, no resource budgets. Those can come later if needed.
+# Background Agent Execution
 
 ## How it works
 
-### Parent dispatches with background flag
-
-The parent agent's tool call includes a signal that this should run in background. Two options (TBD which is cleaner):
+The parent agent decides at dispatch time whether a sub-agent runs in background by passing `background: true` in the tool input. The sub-agent doesn't know or care — it runs identically to foreground.
 
-1. **Per-tool input field** — `visualDesignExpert({ task: "...", background: true })`
-2. **Runner-level config** — the tool's `execute()` decides based on context and passes `background: true` to `runSubAgent()`
+### Dispatch
 
-Either way, the sub-agent's prompt and tools are identical to foreground. It doesn't know it's backgrounded.
+```
+visualDesignExpert({ task: "...", background: true })
+productVision({ task: "...", background: true })
+```
 
-### Runner split-lifecycle
+### Split lifecycle (runner.ts)
 
-When `background: true` is set on the sub-agent config:
+When `background: true`:
 
-1. Runner resolves the parent's promise immediately with a short acknowledgment (e.g., "Working on design recommendations in background...")
-2. The sub-agent loop continues in a detached async context with its own AbortController (not tied to Remy's turn signal)
-3. Events after the split point are emitted with `background: true` so the frontend can render them differently (collapsed, subtle indicator)
-4. When the sub-agent finishes naturally, the result is handed to the notification queue
+1. The runner creates its own AbortController (detached from the parent turn signal)
+2. The sub-agent's LLM runs normally — streaming, thinking, tool calls
+3. After the first LLM turn that produces text content, the runner **resolves the parent's promise early** with that text + `backgrounded: true`
+4. The sub-agent loop continues in the background — more tool calls, more LLM turns
+5. On completion, `onBackgroundComplete` fires, pushing the result to the notification queue
 
-### Result delivery
+The parent agent gets the initial response immediately and continues its turn. The background agent keeps working.
 
-A single mechanism: synthetic user message, delivered at the right time.
+### Result delivery (headless.ts)
 
-- **If Remy is idle** (between turns) — deliver immediately as an automated message that triggers a new turn
-- **If Remy is mid-turn** — queue the result, deliver immediately after the current turn completes
-- **Multiple completions** — batch into a single message (e.g., "Background work completed:\n\n**Design expert:** ...\n\n**Product vision:** ...")
+A notification queue collects background completions. Delivery:
 
-This means the sub-agent's result always reaches Remy in a natural way — as a user message that kicks off a new turn where Remy can react to it.
+- **If Remy is idle** — deliver immediately as a hidden automated message
+- **If Remy is mid-turn** — queue and flush after `turn_done`
+- **Multiple completions** — batched into one message
 
-### AgentEvent changes
+Format (hidden, XML-tagged):
+```
+@@automated::background_results@@
+<background_results>
+<tool_result id="toolu_abc" name="visualDesignExpert">
+Result text here...
+</tool_result>
+</background_results>
+```
 
-Add optional `background?: boolean` to all event types that have `parentToolId`. The frontend uses this to render background work differently.
+### Events
 
-### History / subAgentMessages
+The `tool_start` event includes `background: true` when a tool is backgrounded. The frontend knows every subsequent event with that `parentToolId` is background work — no need to flag every individual event.
 
-The `subAgentMessages` array on the tool content block gets updated in two phases:
-1. At dispatch time — empty or partial messages attached (the early return acknowledgment)
-2. At background completion — the full message array replaces the partial one, session is saved
+### Process management
 
-A `backgroundStartIndex` on the tool content block marks where the early return happened, so the frontend knows which messages were "live" vs "background."
+Background agents stay in the tool registry after the parent's promise settles. The existing `stop_tool` and `restart_tool` stdin commands work on them. Stopping a background agent via `stop_tool` is how users cancel dangling work.
 
-### Notification queue (headless layer)
+### Which sub-agents support this?
 
-The headless layer maintains a simple queue:
-- Background agents push `{ agentId, name, result, completedAt }` when they finish
-- After each `turn_done`, headless checks the queue and flushes as a single synthetic user message
-- If Remy is idle when a result arrives, headless sends the message immediately
-
-### Process management (headless layer)
-
-The headless layer tracks active background agents:
-- `get_background_agents` action → returns list with id, name, startedAt, status
-- `cancel_background_agent` action → aborts a specific background agent via its AbortController
-- The frontend can show active background work and let users cancel dangling agents
-
-## Which sub-agents would use this?
-
-- **productVision** — return lane summary immediately, write roadmap files in background
 - **designExpert** — return font/color/layout recommendations immediately, generate images in background
+- **productVision** — return initial plan immediately, write roadmap files in background
 - **codeSanityCheck** — NOT a candidate, Remy needs the advice before proceeding
 - **browserAutomation** — NOT a candidate, results inform Remy's next action
 
-## What to build (ordered)
-
-1. Runner split-lifecycle support (`background` flag on SubAgentConfig, detached async continuation)
-2. `background: true` flag on AgentEvent types
-3. Notification queue in headless layer (with idle-vs-busy delivery logic)
-4. Background agent process tracking in headless layer
-5. Wire up parent agent tools (add `background` input field to candidate sub-agent tools)
-6. Update parent agent prompt to teach Remy when to use background dispatch
-
-## Future considerations (not v1)
+## Future considerations
 
 - **Resource budgets** — token/cost ceilings for background agents running unattended
 - **Checkpoint/resume** — serialized state for surviving process restarts

package/dist/subagents/designExpert/prompts/images.md

@@ -1,6 +1,10 @@
 ## Photo and Image Guidelines
 
-When the design calls for imagery, generate actual images and provide their CDN Urls so the developer can use them immediately. Prefer images with strong subjects: people, scenes - dramatic, eye catching, and beautiful.
+Important: All images used in the app might be high resolution and high quality. If serving them via the mindstudio cdn, make sure to specify the ?dpr=3 param for retina displays.
+
+You have a powerful tool for generating high-quality images from any prompt: realistic photos, visalizations, textures, logos, icons and other elements, and more. Use it to create truly custom and beautiful designs. Be liberal with image generation - create multiple variants and choose the best one - AI image generation prompts are finnicky and unpredictable, you don't need to get it right the first generation. You can always edit or regenerate if the analysis seems off.
+
+When the design calls for imagery, generate actual images and provide their CDN URLs so the developer can use them immediately. Prefer images with strong subjects: people, scenes - dramatic, eye catching, and beautiful.
 
 Not every interface needs images. A productivity dashboard, a finance tool, or a data-heavy app is better served by strong typography, color, and layout than by shoehorned photography. Use images when they genuinely add to the experience — landing pages, marketing sites, content-driven apps — not as decoration on every project.
 
@@ -16,7 +20,7 @@ Generated images are production assets, not mockups or concepts — they are hos
 
 ### Image editing
 
-Use `editImages` to transform or build on existing images. Provide one or more source image URLs and a prompt describing the desired result. The source images act as reference material — the model uses them as anchors for style, subject, or composition.
+Use `editImages` to transform or build on existing images. Provide one or more source image URLs and a prompt describing the desired result. The source images act as reference material — the model uses them as anchors for style, subject, or composition. Think about image editing as part of a pipeline for generating a final asset from constituent pieces.
 
 Good use cases for editing:
 - Incorporating a logo or brand mark into a product mockup or scene
@@ -52,6 +56,8 @@ You can produce two kinds of image assets:
 
 **Isolated assets** (with `transparentBackground`) — cutout objects, product shots, icons, illustrated elements on transparent backgrounds. These are composited directly onto layouts, layered over other content, or placed inside cards and feature sections as standalone elements.
 
+Note: when analyzing images generated with `transparentBackground`, the transparent background will appear white to the vision analysis models. Don't mistake this for a white background — the image has an alpha channel and the background is transparent. Trust the generation parameters over what the analysis describes.
+
 Think of yourself as providing visual ingredients — both backgrounds and foreground elements — not finished UI.
 
 ### What makes good photos and images

package/package.json

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