@mindstudio-ai/remy 0.1.8 → 0.1.10

package/dist/static/projectContext.ts

@@ -72,11 +72,14 @@ export function loadSpecFileMetadata(): string {
 
     const entries: string[] = [];
     for (const filePath of files) {
-      const { name, description } = parseFrontmatter(filePath);
+      const { name, description, type } = parseFrontmatter(filePath);
       let line = `- ${filePath}`;
       if (name) {
         line += ` — "${name}"`;
       }
+      if (type) {
+        line += ` (${type})`;
+      }
       if (description) {
         line += ` — ${description}`;
       }
@@ -110,20 +113,22 @@ function walkMdFiles(dir: string): string[] {
 function parseFrontmatter(filePath: string): {
   name: string;
   description: string;
+  type: string;
 } {
   try {
     const content = fs.readFileSync(filePath, 'utf-8');
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match) {
-      return { name: '', description: '' };
+      return { name: '', description: '', type: '' };
     }
 
     const fm = match[1];
     const name = fm.match(/^name:\s*(.+)$/m)?.[1]?.trim() ?? '';
     const description = fm.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? '';
-    return { name, description };
+    const type = fm.match(/^type:\s*(.+)$/m)?.[1]?.trim() ?? '';
+    return { name, description, type };
   } catch {
-    return { name: '', description: '' };
+    return { name: '', description: '', type: '' };
   }
 }
 

package/dist/subagents/browserAutomation/prompt.md

@@ -98,7 +98,8 @@ Check a count with evaluate:
 </rules>
 
 <voice>
-- No emoji, narration, or markdown. 
+- No emoji, narration, or markdown.
 - Your response will be read by another AI agent, so be terse. Execute, observe, report.
 - The main agent reads your final output to decide what to do next.
+- Do not include element refs (ref=eN) in your results. They are session-specific and meaningless to the main agent.
 </voice>

package/dist/subagents/designExpert/.notes.md

@@ -0,0 +1,253 @@
+# Design Research Agent — Design Notes & Decisions
+
+Notes from the initial design of the design research sub-agent (March 2026).
+
+## Purpose
+
+The design research agent is Remy's design consultant. Any design question or decision gets delegated here. It handles both exploratory research ("give me three visual directions for a fintech app") and directed tasks ("the spec says Midnight #000000 and Snow #F5F5F7, what gradient would work for a hero section?"). It returns concrete, actionable output — URLs, hex values, font names with CSS URLs — that Remy can interpret and use however it sees fit.
+
+## Scope
+
+The agent covers five areas:
+
+1. **Typography** — font selection and pairings from curated sources
+2. **Color palettes** — brand color generation from seed colors, domain context, or reference sites; including modern CSS gradients
+3. **Stock photography / placeholder images** — finding relevant imagery via curated stock sites
+4. **Layout & responsive design** — research real products for layout patterns, propose interesting/non-generic compositions, optionally generate wireframe concepts via image generation. This is a major use case — Remy defaults to boring layouts without this.
+5. **Visual reference analysis** — fetch + screenshot sites, analyze them for design insights
+
+Icons and brand SVGs are deferred for now.
+
+## No modes, no structured output format
+
+The agent doesn't have separate "research mode" vs "proposal mode." The task description from Remy carries the context. Sometimes Remy asks for options to present to the user during intake; sometimes it asks for specific answers while building from a spec. The agent handles both naturally.
+
+Output should include concrete resources (URLs, hex values, font names with CSS links) but doesn't need rigid YAML structure. Remy interprets the results.
+
+## Architecture: static docs, runtime-sampled data, and tools
+
+The agent's prompt is assembled from three layers:
+
+### 1. Static documents (baked into prompt)
+
+Guidelines and knowledge that don't change between invocations:
+
+- **Gradient techniques** — what's current/dated, CSS techniques (oklch, color-mix, mesh gradients, grain overlays), reference sites
+- **Animation patterns** — what's current/dated, libraries (Motion as default), performance rules
+- **Color theory** — HSL rotation formulas, oklch color space, color-mix(), tint/shade derivation. No third-party API needed for palette generation.
+- **Design philosophy** — distinctiveness, typography-first thinking, brand-level output, the AI defaults problem
+- **Layout guidance** — what makes layouts interesting (asymmetry, creative whitespace, varied compositions), common anti-patterns to avoid. This is critical because layout is where AI-generated interfaces are weakest.
+- **Visual reference analysis framework** — the consistent analysis structure (mood, color, type, layout, what's distinctive)
+
+### 2. Runtime-sampled JSON arrays (injected at invocation time)
+
+Data arrays that are sampled randomly each time the agent is invoked, to prevent bias and keep results fresh:
+
+**Design inspiration screenshots:**
+- Godly website thumbnails (URLs grabbed from Chrome dev tools, stored as JSON array)
+- Other gallery thumbnails (Awwwards, Figma Community, etc.) as we collect them
+- Just a big array of image URLs; the prompt loader samples ~3-5 per invocation
+- The agent can use `analyzeDesignReference` on these to understand what it's looking at
+
+**Font catalog + pairings:**
+- Fontshare catalog (~100 fonts with metadata: name, slug, category, weights, tags)
+- Fontshare curated pairings (59 heading/body combinations with recommended weights)
+- Open Foundry catalog if we compile it
+- The prompt loader samples ~10-15 fonts per invocation to prevent the agent from always reaching for the same favorites
+- Fonts are provided with CSS URLs: `https://api.fontshare.com/v2/css?f[]={slug}@{weights}&display=swap`
+- The agent should provide a URL to a font and let Remy figure out how to load it. No need for Google Fonts-specific guidance.
+
+**Sampling mechanism:** The prompt loader (in `index.ts` or `prompt.ts`) reads the JSON arrays at startup. Each invocation of the design research tool picks a random subset and injects them into the system prompt before passing it to `runSubAgent`. The agent sees fresh examples every time without managing randomness itself.
+
+### 3. Tools (live, query-dependent)
+
+**`searchGoogle`** — general design research: font recommendations, "best finance app design 2026," real products in the user's domain
+
+**`fetchUrl`** (with optional screenshot) — analyze reference sites, brand sites users share, font specimen pages
+
+**`analyzeImage`** — general-purpose vision analysis. Takes a prompt and an image URL. The agent crafts the prompt based on what it needs to know ("what colors dominate this image?", "describe the typography choices", etc.)
+
+**`analyzeDesignReference`** — specialized wrapper around `analyzeImage` with a pre-built analysis prompt. Takes just an image URL. Returns a consistent analysis: mood/aesthetic, color palette with approximate hex values, typography style, layout composition, and what makes it distinctive. Use this when analyzing screenshots for design inspiration rather than crafting a custom prompt each time.
+
+**Stock photo search** — search Pexels, Unsplash, and Pixabay via MindStudio SDK CLI. No Google Images — too much junk/noise for design work. These are the only sources for stock photography.
+
+**`generateImage`** (via MindStudio SDK) — for generating rough wireframe/layout concepts. TBD on prompt engineering for this.
+
+All tools shell out to the `mindstudio` CLI. No external tool resolution needed.
+
+## Visual reference analysis framework
+
+When analyzing a screenshot or design image, the agent should consistently assess:
+
+1. **Mood/aesthetic** — minimal, bold, editorial, playful, corporate, etc.
+2. **Color** — dominant colors with approximate hex values, palette strategy (monochromatic, complementary, etc.), use of gradients
+3. **Typography** — serif/sans/display, weight, size hierarchy, distinctive choices
+4. **Layout** — composition (symmetric/asymmetric), grid structure, whitespace usage, content density
+5. **What makes it distinctive** — the specific design choices that make this stand out from generic AI-generated interfaces
+
+This framework is baked into the `analyzeDesignReference` tool so analyses are consistent. The general `analyzeImage` tool is available for ad-hoc questions.
+
+## Randomization for inspiration browsing
+
+When searching for design inspiration via tools (not the pre-sampled arrays), the agent tends to see the same top/featured results. Strategies to vary:
+
+- **Varied search queries** — add style adjectives and the current year ("dashboard design minimal dark 2026")
+- **Pagination/offset** — browse page 3 instead of page 1
+- **Domain-specific searches** — search for real products in the user's space, not generic "design inspiration"
+- **Multiple sources per task** — hit 2-3 different sources with different query strategies
+
+For layout and UX patterns, research real products in the user's domain. For aesthetic inspiration, browse design galleries with varied search terms.
+
+## Design philosophy notes
+
+### The AI defaults problem
+
+LLMs converge on statistical medians from training data. For design this means: Inter/DM Sans/Space Grotesk fonts, purple/indigo accents, three-boxes-with-icons layouts, safe neutral palettes. The design research agent exists partly to break this pattern by forcing the model to look at real-world references and curated sources rather than generating from priors. Runtime sampling of fonts and inspiration images further prevents the agent from developing its own biases.
+
+### Color palettes should be UI-functional
+
+"Pretty" palettes from generators (Coolors trending, etc.) are not necessarily good UI palettes. A UI palette needs: a background color, a readable text color on that background, an accent for interactive elements. Deriving palettes from real products or from color theory applied to brand colors produces better results than aesthetic palette generators.
+
+### Typography is the highest-impact decision
+
+Font selection has more impact on perceived quality than any other single design decision. The agent should spend proportionally more effort here — looking at specimens, considering personality match, checking that the font has the weights and styles needed for a complete type hierarchy.
+
+### Brand-level, not implementation-level
+
+The agent's output should be at the brand style guide level: "Midnight #000000 for dark surfaces, Snow #F5F5F7 for text." Not at the CSS variable level: "Background: #000000, BorderFocus: #3A3A3C." The coding agent (Remy) derives implementation details like accessibility contrast adjustments, dark mode palettes, and CSS variables from the brand-level output.
+
+### Layout is where AI is weakest
+
+This is the primary reason the design research agent exists for layout work. Without outside input, Remy will produce the same centered-content, three-column, card-grid layouts every time. The design research agent should push for: asymmetry, varied column widths, creative negative space, unexpected compositions, full-bleed elements, strong visual hierarchy through scale contrast. Analyzing real sites (via the sampled inspiration images and live research) is the best way to inject layout creativity.
+
+## Modern gradients (2026)
+
+### What's current
+
+**Mesh / aurora gradients** — the dominant look. Multiple layered `radial-gradient()`s with `filter: blur()` over dark backgrounds. The Stripe/Linear/Vercel aesthetic. Creates organic, atmospheric backgrounds.
+
+**Grain/noise overlays** — SVG `feTurbulence` filters layered under gradients. Combats color banding on long subtle gradients and adds tactile warmth.
+
+**Glassmorphism (matured)** — subtle `backdrop-filter: blur()` with gradient tints. Used sparingly as an accent, not the whole design language.
+
+**Animated gradient blobs** — hero sections with continuously morphing gradients. CSS `@keyframes` animating `background-position` on oversized gradients for simple cases; WebGL (like Stripe's minigl) for more complex effects.
+
+### CSS techniques that matter
+
+- **`oklch` color space in gradients**: `linear-gradient(to right in oklch, blue, green)` avoids the muddy gray zone that RGB/HSL produce. Perceptually uniform, vibrant transitions. Production-ready in all modern browsers. This is the single biggest upgrade for gradient quality.
+- **`color-mix()`**: `color-mix(in oklch, #3b82f6 70%, white)` for generating tints/shades programmatically. Essential for design systems deriving UI colors from brand colors.
+- **Relative color syntax**: `oklch(from var(--brand) calc(l * 1.25) c h)` derives lighter/darker/desaturated variants from a single token. Powerful for theme layers.
+- **Stacked radial-gradients**: Multiple `radial-gradient()` layers with different positions/sizes to create mesh-like effects without canvas/WebGL.
+- **Conic gradients**: Useful for pie charts, color wheels, angular shading.
+
+### What looks dated
+
+- Simple two-color linear gradients (the 2018 "purple to blue" hero)
+- Instagram-style gradient borders as a primary design element
+- Overly saturated, uniform gradients without texture or depth
+- Flat gradient cards without noise, blur, or layering
+
+### Reference sites
+
+- **Stripe** — WebGL aurora gradient hero, flowing blues/purples/pinks/oranges. The gold standard.
+- **Vercel** — prism/light-refraction effects, animated lines through gradients, grainy textures.
+- **Linear** — dark backgrounds with precise, subtle gradient accents. Minimalist, purposeful.
+
+### Implications for the design research agent
+
+The agent can recommend gradient CSS alongside color palette proposals. Modern gradients are color theory applied through `oklch` — the seed color + HSL rotation math we're already baking in produces the inputs, and the agent can suggest specific gradient techniques (mesh, grain overlay, animated blob) appropriate to the app's aesthetic. The `color-mix()` and relative color syntax are how the coding agent (Remy) derives the implementation — the design research agent just needs to know these exist when making recommendations.
+
+## Modern animations (2026)
+
+### What's current
+
+**CSS scroll-driven animations** — the biggest shift. `animation-timeline: scroll()` and `animation-timeline: view()` tie animations to scroll position purely in CSS, running off the main thread for smooth 60fps. ~85% browser support. Replaces Intersection Observer for entrance animations.
+
+**Scroll-triggered animations** — new in Chrome 145 (2026): time-based animations that trigger at specific scroll offsets, declaratively in CSS. No JS scroll listeners needed.
+
+**View Transitions API** — morphing between page states with cinematic transitions. Page navigations in SPAs, expanding cards to detail views. Growing browser support.
+
+**Spring physics** — natural-feeling motion with spring-based easing rather than cubic-bezier. Motion (Framer Motion) has this built-in.
+
+**Purposeful micro-interactions** — subtle hover/click feedback: scaling, color shifts, depth changes. The philosophy is "guide, confirm, smooth" — not "show off."
+
+### Animation libraries for React
+
+| Library | Size | Best for |
+|---------|------|----------|
+| CSS-native (scroll-timeline, @keyframes) | 0KB | Simple entrances, scroll effects, hover states |
+| Motion (fka Framer Motion) | ~85KB | Complex state-driven animations, layout transitions, spring physics. The React default. |
+| GSAP | ~78KB | Complex sequenced timelines, scroll-driven narratives, raw performance with many simultaneous tweens |
+
+**Motion is the right default for most React app work.** Only reach for GSAP if building complex sequenced timelines.
+
+### Performance rules
+
+- Only animate `transform`, `opacity`, `filter` — these skip layout and paint (GPU-composited).
+- `will-change` sparingly — promotes to GPU layer but overuse causes excessive memory.
+- CSS scroll-driven animations are inherently performant (off main thread).
+- Never animate `width`, `height`, `top`, `left`, `margin`, `padding` — triggers layout recalculation.
+
+### What looks dated
+
+- Parallax scrolling as a primary design pattern
+- Manual `nth-child` stagger delays (use `sibling-index()` + `calc()` now)
+- JS scroll event listeners for scroll animations
+- Heavy animation libraries for simple UI toggles
+- Loading spinners everywhere (skeleton screens preferred)
+- Flashy transitions that don't serve UX purpose
+- Bounce/elastic easing
+
+### Reference sites
+
+- **Apple.com** — scroll-driven storytelling. Information fades in/out, never overwhelming.
+- **Linear.app** — subtle, purposeful micro-interactions. Every motion serves the interface.
+- **Vercel.com** — smooth page transitions, gradient animations, scroll-triggered reveals.
+- **Stripe.com** — gradient animations double as motion design; smooth, continuous, non-distracting.
+
+### Implications for the design research agent
+
+Animation guidance is mostly about restraint — "be purposeful, not decorative." The agent should recommend specific animation patterns appropriate to the app's complexity (a simple CRUD app needs entrance animations and hover states, not scroll-driven narratives). When recommending layouts that involve motion (hero sections, staggered card reveals), the agent should specify the technique (CSS scroll-timeline, Motion spring, etc.) so Remy can implement correctly.
+
+The existing design.md animation section in the main Remy prompt covers the "what not to do" well. The design research agent adds the "what to do" with specific modern techniques.
+
+## Available APIs (no auth required)
+
+| API | URL | What it does |
+|---|---|---|
+| Fontshare | `api.fontshare.com/v2/fonts` | Curated font catalog with metadata |
+| The Color API | `thecolorapi.com` | Color schemes from seed color (analogic, complement, triad, etc.) |
+| Colormind | `colormind.io/api/` | AI-generated 5-color UI palettes, lock known colors |
+| theSVG.org | `thesvg.org/api/` | 4k+ brand logos with hex brand colors, 7 variants |
+| SVGL | `api.svgl.app` | 300+ brand logos with light/dark variants |
+| Iconify | `api.iconify.design` | 275k+ icons from Tabler, Lucide, Phosphor, etc. |
+
+Note: Icons and brand SVG APIs are documented here for future reference but not currently wired up as tools.
+
+## Available via MindStudio SDK (no separate API keys needed)
+
+| Action | What it does |
+|---|---|
+| Pexels search | Stock photos with avg_color field |
+| Unsplash search | High-quality stock photos with color metadata |
+| Pixabay search | 5.6M+ images/videos/vectors |
+| Google search | General web search for design research |
+| Image analysis | Vision model for analyzing screenshots |
+| Image generation | For wireframe/layout concept generation |
+
+Google Images is explicitly excluded — too much noise/junk for design work.
+
+## What's done
+
+- **Font catalog** — 105 fonts (80 Fontshare + 14 Google Fonts + 11 Open Foundry) with 51 curated pairings, compiled in `data/fonts.json`. Runtime-sampled per invocation.
+- **Design inspiration** — 138 Godly screenshots rehosted on MindStudio CDN, pre-analyzed via vision model, compiled in `data/inspiration.json`. Runtime-sampled per invocation. Compilation script at `data/compile-inspiration.sh`.
+- **Runtime sampling** — `prompt.ts` samples 15 fonts + 5 pairings + 5 inspiration images per invocation.
+- **Tools** — 7 tools: searchGoogle, fetchUrl, analyzeImage, analyzeDesignReference, screenshotAndAnalyze, searchStockPhotos, searchProductScreenshots.
+- **Prompt** — split into 6 files in `prompts/`, assembled via template includes. Includes `frontend-design-notes.md` from the main prompt sources via `@src/` prefix.
+
+## What's not done
+
+- **Wireframe generation** — need to figure out good prompts for `generateImage` that produce useful layout wireframe concepts
+- **More inspiration sources** — currently only Godly. Could add Awwwards, Figma Community, or other galleries to the inspiration pool.
+- **Open Foundry fonts without Google Fonts hosting** — 11 fonts marked "(self-host required)" have no CSS URL. Would need to host font files on CDN to make them usable.
+- **Icon integration** — Iconify API and theSVG.org are documented but not wired up as tools yet. Deferred.

package/dist/subagents/designExpert/data/compile-inspiration.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+#
+# Compile inspiration.raw.json → inspiration.json
+#
+# Reads each image URL from inspiration.raw.json, runs analyzeImage via the
+# mindstudio CLI, and writes the compiled output with URL + analysis.
+#
+# Run manually: bash src/subagents/designResearch/data/compile-inspiration.sh
+# Processes images sequentially (one API call at a time).
+# Supports resuming — skips URLs already present in the output file.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RAW_FILE="$SCRIPT_DIR/inspiration.raw.json"
+OUT_FILE="$SCRIPT_DIR/inspiration.json"
+
+PROMPT="Analyze this website/app screenshot as a design reference. Assess: 1) Mood/aesthetic 2) Color palette with approximate hex values and palette strategy 3) Typography style 4) Layout composition (symmetric/asymmetric, grid structure, whitespace usage, content density) 5) What makes it distinctive and interesting vs generic AI-generated interfaces. Be specific and concise."
+
+if [ ! -f "$RAW_FILE" ]; then
+  echo "Error: $RAW_FILE not found"
+  exit 1
+fi
+
+# Initialize output file if it doesn't exist
+if [ ! -f "$OUT_FILE" ]; then
+  echo '{"images":[]}' > "$OUT_FILE"
+fi
+
+TOTAL=$(python3 -c "import json; print(len(json.load(open('$RAW_FILE'))['images']))")
+DONE=$(python3 -c "import json; print(len(json.load(open('$OUT_FILE'))['images']))")
+echo "Compiling inspiration images: $DONE/$TOTAL already done"
+
+# Get URLs that haven't been compiled yet
+URLS=$(python3 -c "
+import json
+raw = set(json.load(open('$RAW_FILE'))['images'])
+done = set(img['url'] for img in json.load(open('$OUT_FILE'))['images'])
+remaining = [u for u in json.load(open('$RAW_FILE'))['images'] if u not in done]
+print('\n'.join(remaining))
+")
+
+if [ -z "$URLS" ]; then
+  echo "All images already compiled."
+  exit 0
+fi
+
+REMAINING=$(echo "$URLS" | wc -l | tr -d ' ')
+echo "Processing $REMAINING remaining images (5 at a time)..."
+BATCH_COUNT=0
+TMPDIR=$(mktemp -d)
+
+# Process a single URL — writes result to a temp file
+process_one() {
+  local url="$1"
+  local idx="$2"
+  local outfile="$TMPDIR/$idx.json"
+
+  ANALYSIS=$(mindstudio analyze-image \
+    --prompt "$PROMPT" \
+    --image-url "$url" \
+    --output-key analysis \
+    --no-meta 2>&1) || true
+
+  if echo "$ANALYSIS" | grep -q '"error"'; then
+    echo "    FAILED — $url"
+    return
+  fi
+
+  python3 -c "
+import json, sys
+json.dump({'url': sys.argv[1], 'analysis': sys.argv[2]}, open(sys.argv[3], 'w'))
+" "$url" "$ANALYSIS" "$outfile"
+
+  echo "    OK — $url"
+}
+
+# Merge all temp files from a batch into the output
+merge_batch() {
+  python3 -c "
+import json, glob, os
+out = '$OUT_FILE'
+tmp = '$TMPDIR'
+with open(out, 'r') as f:
+    data = json.load(f)
+for p in sorted(glob.glob(os.path.join(tmp, '*.json'))):
+    with open(p) as f:
+        data['images'].append(json.load(f))
+    os.remove(p)
+with open(out, 'w') as f:
+    json.dump(data, f, indent=2)
+"
+}
+
+# Process in batches of 5
+BATCH=()
+IDX=0
+while IFS= read -r url; do
+  BATCH+=("$url")
+  IDX=$((IDX + 1))
+  if [ ${#BATCH[@]} -eq 5 ]; then
+    BATCH_COUNT=$((BATCH_COUNT + 5))
+    echo "  Batch $BATCH_COUNT/$REMAINING"
+    for i in "${!BATCH[@]}"; do
+      process_one "${BATCH[$i]}" "$((BATCH_COUNT - 5 + i))" &
+    done
+    wait
+    merge_batch
+    BATCH=()
+  fi
+done <<< "$URLS"
+
+# Process remaining
+if [ ${#BATCH[@]} -gt 0 ]; then
+  BATCH_COUNT=$((BATCH_COUNT + ${#BATCH[@]}))
+  echo "  Batch $BATCH_COUNT/$REMAINING"
+  for i in "${!BATCH[@]}"; do
+    process_one "${BATCH[$i]}" "$((BATCH_COUNT - ${#BATCH[@]} + i))" &
+  done
+  wait
+  merge_batch
+fi
+
+rm -rf "$TMPDIR"
+FINAL=$(python3 -c "import json; print(len(json.load(open('$OUT_FILE'))['images']))")
+echo "Done. $FINAL/$TOTAL images compiled."