@mindstudio-ai/remy 0.1.289 → 0.1.291

package/dist/headless.js

@@ -2496,7 +2496,7 @@ var bashTool = {
 };
 
 // src/tools/code/grep.ts
-import { exec } from "child_process";
+import { execFile } from "child_process";
 var DEFAULT_MAX = 50;
 function clampContext(v) {
   const n = Math.floor(Number(v));
@@ -2570,57 +2570,87 @@ var grepTool = {
       1,
       Math.floor(Number(input.maxResults) || DEFAULT_MAX)
     );
-    const globFlag = input.glob ? ` --glob '${input.glob}'` : "";
-    const escaped = input.pattern.replace(/'/g, "'\\''");
     const mode = input.outputMode === "count" || input.outputMode === "filesWithMatches" ? input.outputMode : "content";
-    const ci = input.caseInsensitive ? " -i" : "";
-    let ctx = "";
+    const ctx = [];
     if (mode === "content") {
       if (input.context != null) {
         const c = clampContext(input.context);
         if (c > 0) {
-          ctx = ` -C ${c}`;
+          ctx.push("-C", String(c));
         }
       } else {
         const b = input.contextBefore != null ? clampContext(input.contextBefore) : 0;
         const a = input.contextAfter != null ? clampContext(input.contextAfter) : 0;
         if (b > 0) {
-          ctx += ` -B ${b}`;
+          ctx.push("-B", String(b));
         }
         if (a > 0) {
-          ctx += ` -A ${a}`;
+          ctx.push("-A", String(a));
         }
       }
     }
+    const ci = input.caseInsensitive ? ["-i"] : [];
     let rgFlags;
     let grepFlags;
     if (mode === "count") {
-      rgFlags = `--count${ci}`;
-      grepFlags = `-rc${ci}`;
+      rgFlags = ["--count", ...ci];
+      grepFlags = ["-rc", ...ci];
     } else if (mode === "filesWithMatches") {
-      rgFlags = `-l${ci}`;
-      grepFlags = `-rl${ci}`;
+      rgFlags = ["-l", ...ci];
+      grepFlags = ["-rl", ...ci];
     } else {
-      rgFlags = `-n --no-heading${ci}${ctx} --max-count=${max}`;
-      grepFlags = `-rn${ci}${ctx} --max-count=${max}`;
-    }
-    const rgCmd = `rg ${rgFlags}${globFlag} '${escaped}' ${searchPath}`;
-    const grepCmd = `grep ${grepFlags} '${escaped}' ${searchPath} --include='*.ts' --include='*.tsx' --include='*.js' --include='*.json' --include='*.md'`;
-    return new Promise((resolve4) => {
-      exec(rgCmd, { maxBuffer: 512 * 1024 }, (err, stdout) => {
-        if (stdout?.trim()) {
-          resolve4(formatResults(stdout, max, mode));
-          return;
+      rgFlags = ["-n", "--no-heading", ...ci, ...ctx, `--max-count=${max}`];
+      grepFlags = ["-rn", ...ci, ...ctx, `--max-count=${max}`];
+    }
+    const rgArgs = [
+      ...rgFlags,
+      ...input.glob ? ["--glob", input.glob] : [],
+      "--",
+      input.pattern,
+      searchPath
+    ];
+    const grepArgs = [
+      ...grepFlags,
+      "--exclude-dir=node_modules",
+      "--exclude-dir=.git",
+      "--include=*.ts",
+      "--include=*.tsx",
+      "--include=*.js",
+      "--include=*.json",
+      "--include=*.md",
+      "--",
+      input.pattern,
+      searchPath
+    ];
+    const run = (cmd, cmdArgs) => new Promise((resolve4) => {
+      const child = execFile(
+        cmd,
+        cmdArgs,
+        { maxBuffer: 512 * 1024, timeout: 3e4 },
+        (err, stdout) => {
+          resolve4({
+            stdout: stdout ?? "",
+            timedOut: err?.killed === true
+          });
         }
-        exec(grepCmd, { maxBuffer: 512 * 1024 }, (_err, grepStdout) => {
-          if (grepStdout?.trim()) {
-            resolve4(formatResults(grepStdout, max, mode));
-          } else {
-            resolve4("No matches found.");
-          }
-        });
-      });
+      );
+      child.stdin?.end();
     });
+    const rg = await run("rg", rgArgs);
+    if (rg.stdout.trim()) {
+      return formatResults(rg.stdout, max, mode);
+    }
+    if (rg.timedOut) {
+      return `Error: search timed out after 30s in ${searchPath} \u2014 narrow the path or pattern.`;
+    }
+    const grep = await run("grep", grepArgs);
+    if (grep.stdout.trim()) {
+      return formatResults(grep.stdout, max, mode);
+    }
+    if (grep.timedOut) {
+      return `Error: search timed out after 30s in ${searchPath} \u2014 narrow the path or pattern.`;
+    }
+    return "No matches found.";
   }
 };
 
@@ -3176,6 +3206,13 @@ var SCREENSHOT_ANALYSIS_PROMPT = `Describe everything visible on screen from top
 var ANALYSIS_RESPONSE_FORMAT = `Respond only with your analysis as Markdown and absolutely no other text. Do not use emojis - use unicode if you need symbols.`;
 function buildScreenshotAnalysisPrompt(opts) {
   let p = opts?.prompt || SCREENSHOT_ANALYSIS_PROMPT;
+  if (opts?.additionalQuestions) {
+    p += `
+
+After the analysis above, also answer the following specific questions about the screenshot:
+
+${opts.additionalQuestions}`;
+  }
   if (opts?.styleMap) {
     p += `
 
@@ -4583,7 +4620,8 @@ async function runBrowserAutomation(task, context, opts) {
                 step: {
                   imageUrl: s.result.url,
                   prompt: buildScreenshotAnalysisPrompt({
-                    styleMap: s.result.styleMap
+                    styleMap: s.result.styleMap,
+                    additionalQuestions: opts?.analysisPrompt
                   }),
                   visionModelOverride: visionOverride
                 }
@@ -4598,7 +4636,13 @@ async function runBrowserAutomation(task, context, opts) {
                   if (i >= analyses.length) {
                     return;
                   }
-                  step.result.analysis = analyses[i]?.output?.analysis || analyses[i]?.output || "";
+                  const analysis = analyses[i]?.output?.analysis || analyses[i]?.output || "";
+                  step.result.analysis = analysis;
+                  const kind = step.command === "screenshotFullPage" ? "fullPage" : "viewport";
+                  const harvested = lastCapture[kind];
+                  if (harvested && typeof analysis === "string" && analysis && harvested.url === step.result.url) {
+                    harvested.analysis = analysis;
+                  }
                 });
               } catch {
                 log8.debug("Failed to parse batch analysis result", {
@@ -4618,7 +4662,7 @@ async function runBrowserAutomation(task, context, opts) {
     const preferred = opts?.capture === "viewport" ? lastCapture.viewport ?? lastCapture.fullPage : lastCapture.fullPage ?? lastCapture.viewport;
     return {
       text: result.text,
-      ...preferred?.url ? { screenshot: { url: preferred.url, styleMap: preferred.styleMap } } : {}
+      ...preferred?.url ? { screenshot: preferred } : {}
     };
   } finally {
     release();
@@ -4666,7 +4710,7 @@ var screenshotDefinition = {
       },
       prompt: {
         type: "string",
-        description: "Optional question about the screenshot. If omitted, returns a general description of what's visible."
+        description: "Optional specific questions about the screenshot, answered alongside the general description of what's visible. If omitted, returns just the general description."
       },
       imageUrl: {
         type: "string",
@@ -4714,15 +4758,25 @@ async function executeScreenshot(input, onLog, context) {
       const shotKind = fullPage ? "full-page" : "viewport";
       const task = input.path ? `Navigate to "${input.path}", then: ${input.instructions}. After completing these steps, take a ${shotKind} screenshot.` : `${input.instructions}. After completing these steps, take a ${shotKind} screenshot.`;
       const result = await runBrowserAutomation(task, context, {
-        capture: fullPage ? "fullPage" : "viewport"
+        capture: fullPage ? "fullPage" : "viewport",
+        analysisPrompt: input.prompt
       });
       if (!result.screenshot) {
         return result.text;
       }
+      const { url, styleMap, analysis } = result.screenshot;
+      if (analysis) {
+        onLog?.(JSON.stringify({ url, analysis }));
+        return JSON.stringify({
+          url,
+          analysis,
+          ...styleMap ? { styleMap } : {}
+        });
+      }
       return await streamScreenshotAnalysis({
-        image: result.screenshot.url,
+        image: url,
         prompt: input.prompt,
-        styleMap: result.screenshot.styleMap,
+        styleMap,
         onLog,
         model,
         apiConfig: context?.apiConfig
@@ -5595,7 +5649,7 @@ var WIREFRAMES_DIR = "src/.wireframes";
 var UPLOAD_TIMEOUT_MS2 = 3e4;
 var definition10 = {
   name: "createWireframe",
-  description: "Create (or revise) a wireframe from self-contained HTML+CSS. Call this while working to generate a sharable wireframe asset: the result returns the exact markdown reference line to paste into your response and into specs (like generateImages returns the image URL). Calling again with the same slug overwrites the wireframe in place, so a revision keeps its path and existing references stay current.",
+  description: "Generate a wireframe from self-contained HTML+CSS you author and write it to disk as a design artifact. This is how a wireframe comes to exist \u2014 the way generateImages is how an image comes to exist \u2014 and the developer builds from the file it creates. The result also hands back the reference line that embeds the wireframe in your response and in specs; paste it wherever the wireframe belongs and it renders as a live preview. Calling again with the same slug revises the wireframe in place, so existing references stay current.",
   inputSchema: {
     type: "object",
     properties: {
@@ -5605,7 +5659,7 @@ var definition10 = {
       },
       slug: {
         type: "string",
-        description: 'Filename stem, lowercase kebab-case (e.g. "feed-post-card"). The wireframe lives at src/.wireframes/{slug}.html. Re-use a slug to revise that wireframe in place.'
+        description: 'Filename stem, lowercase kebab-case (e.g. "feed-post-card"). Re-use a slug to revise that wireframe in place.'
       },
       description: {
         type: "string",
@@ -7542,6 +7596,7 @@ function clearSession(state) {
     log11.warn("Session archive on clear failed", { error: err.message });
   }
   state.messages = [];
+  state.models = void 0;
   try {
     if (fs21.existsSync(SESSION_FILE)) {
       fs21.unlinkSync(SESSION_FILE);
@@ -10190,7 +10245,10 @@ var HeadlessSession = class {
   //////////////////////////////////////////////////////////////////////////////
   handleClear() {
     clearSession(this.state);
-    return {};
+    return {
+      modelSurfaces: getEffectiveModelSurfaces(),
+      allowedModelsByType: ALLOWED_MODELS_BY_TYPE
+    };
   }
   /** Change per-agent model picks without clearing history. Takes effect on
    * the next turn — the model is resolved live, per LLM call, from

package/dist/index.js

@@ -2825,6 +2825,7 @@ function clearSession(state) {
     log3.warn("Session archive on clear failed", { error: err.message });
   }
   state.messages = [];
+  state.models = void 0;
   try {
     if (fs10.existsSync(SESSION_FILE)) {
       fs10.unlinkSync(SESSION_FILE);
@@ -3593,7 +3594,7 @@ var init_bash = __esm({
 });
 
 // src/tools/code/grep.ts
-import { exec } from "child_process";
+import { execFile } from "child_process";
 function clampContext(v) {
   const n = Math.floor(Number(v));
   return Number.isFinite(n) ? Math.min(100, Math.max(0, n)) : 0;
@@ -3671,57 +3672,87 @@ var init_grep = __esm({
           1,
           Math.floor(Number(input.maxResults) || DEFAULT_MAX)
         );
-        const globFlag = input.glob ? ` --glob '${input.glob}'` : "";
-        const escaped = input.pattern.replace(/'/g, "'\\''");
         const mode = input.outputMode === "count" || input.outputMode === "filesWithMatches" ? input.outputMode : "content";
-        const ci = input.caseInsensitive ? " -i" : "";
-        let ctx = "";
+        const ctx = [];
         if (mode === "content") {
           if (input.context != null) {
             const c = clampContext(input.context);
             if (c > 0) {
-              ctx = ` -C ${c}`;
+              ctx.push("-C", String(c));
             }
           } else {
             const b = input.contextBefore != null ? clampContext(input.contextBefore) : 0;
             const a = input.contextAfter != null ? clampContext(input.contextAfter) : 0;
             if (b > 0) {
-              ctx += ` -B ${b}`;
+              ctx.push("-B", String(b));
             }
             if (a > 0) {
-              ctx += ` -A ${a}`;
+              ctx.push("-A", String(a));
             }
           }
         }
+        const ci = input.caseInsensitive ? ["-i"] : [];
         let rgFlags;
         let grepFlags;
         if (mode === "count") {
-          rgFlags = `--count${ci}`;
-          grepFlags = `-rc${ci}`;
+          rgFlags = ["--count", ...ci];
+          grepFlags = ["-rc", ...ci];
         } else if (mode === "filesWithMatches") {
-          rgFlags = `-l${ci}`;
-          grepFlags = `-rl${ci}`;
+          rgFlags = ["-l", ...ci];
+          grepFlags = ["-rl", ...ci];
         } else {
-          rgFlags = `-n --no-heading${ci}${ctx} --max-count=${max}`;
-          grepFlags = `-rn${ci}${ctx} --max-count=${max}`;
-        }
-        const rgCmd = `rg ${rgFlags}${globFlag} '${escaped}' ${searchPath}`;
-        const grepCmd = `grep ${grepFlags} '${escaped}' ${searchPath} --include='*.ts' --include='*.tsx' --include='*.js' --include='*.json' --include='*.md'`;
-        return new Promise((resolve4) => {
-          exec(rgCmd, { maxBuffer: 512 * 1024 }, (err, stdout) => {
-            if (stdout?.trim()) {
-              resolve4(formatResults(stdout, max, mode));
-              return;
+          rgFlags = ["-n", "--no-heading", ...ci, ...ctx, `--max-count=${max}`];
+          grepFlags = ["-rn", ...ci, ...ctx, `--max-count=${max}`];
+        }
+        const rgArgs = [
+          ...rgFlags,
+          ...input.glob ? ["--glob", input.glob] : [],
+          "--",
+          input.pattern,
+          searchPath
+        ];
+        const grepArgs = [
+          ...grepFlags,
+          "--exclude-dir=node_modules",
+          "--exclude-dir=.git",
+          "--include=*.ts",
+          "--include=*.tsx",
+          "--include=*.js",
+          "--include=*.json",
+          "--include=*.md",
+          "--",
+          input.pattern,
+          searchPath
+        ];
+        const run = (cmd, cmdArgs) => new Promise((resolve4) => {
+          const child = execFile(
+            cmd,
+            cmdArgs,
+            { maxBuffer: 512 * 1024, timeout: 3e4 },
+            (err, stdout) => {
+              resolve4({
+                stdout: stdout ?? "",
+                timedOut: err?.killed === true
+              });
             }
-            exec(grepCmd, { maxBuffer: 512 * 1024 }, (_err, grepStdout) => {
-              if (grepStdout?.trim()) {
-                resolve4(formatResults(grepStdout, max, mode));
-              } else {
-                resolve4("No matches found.");
-              }
-            });
-          });
+          );
+          child.stdin?.end();
         });
+        const rg = await run("rg", rgArgs);
+        if (rg.stdout.trim()) {
+          return formatResults(rg.stdout, max, mode);
+        }
+        if (rg.timedOut) {
+          return `Error: search timed out after 30s in ${searchPath} \u2014 narrow the path or pattern.`;
+        }
+        const grep = await run("grep", grepArgs);
+        if (grep.stdout.trim()) {
+          return formatResults(grep.stdout, max, mode);
+        }
+        if (grep.timedOut) {
+          return `Error: search timed out after 30s in ${searchPath} \u2014 narrow the path or pattern.`;
+        }
+        return "No matches found.";
       }
     };
   }
@@ -4360,6 +4391,13 @@ var init_analyzeImage = __esm({
 // src/tools/_helpers/screenshot.ts
 function buildScreenshotAnalysisPrompt(opts) {
   let p = opts?.prompt || SCREENSHOT_ANALYSIS_PROMPT;
+  if (opts?.additionalQuestions) {
+    p += `
+
+After the analysis above, also answer the following specific questions about the screenshot:
+
+${opts.additionalQuestions}`;
+  }
   if (opts?.styleMap) {
     p += `
 
@@ -5620,7 +5658,8 @@ async function runBrowserAutomation(task, context, opts) {
                 step: {
                   imageUrl: s.result.url,
                   prompt: buildScreenshotAnalysisPrompt({
-                    styleMap: s.result.styleMap
+                    styleMap: s.result.styleMap,
+                    additionalQuestions: opts?.analysisPrompt
                   }),
                   visionModelOverride: visionOverride
                 }
@@ -5635,7 +5674,13 @@ async function runBrowserAutomation(task, context, opts) {
                   if (i >= analyses.length) {
                     return;
                   }
-                  step.result.analysis = analyses[i]?.output?.analysis || analyses[i]?.output || "";
+                  const analysis = analyses[i]?.output?.analysis || analyses[i]?.output || "";
+                  step.result.analysis = analysis;
+                  const kind = step.command === "screenshotFullPage" ? "fullPage" : "viewport";
+                  const harvested = lastCapture[kind];
+                  if (harvested && typeof analysis === "string" && analysis && harvested.url === step.result.url) {
+                    harvested.analysis = analysis;
+                  }
                 });
               } catch {
                 log9.debug("Failed to parse batch analysis result", {
@@ -5655,7 +5700,7 @@ async function runBrowserAutomation(task, context, opts) {
     const preferred = opts?.capture === "viewport" ? lastCapture.viewport ?? lastCapture.fullPage : lastCapture.fullPage ?? lastCapture.viewport;
     return {
       text: result.text,
-      ...preferred?.url ? { screenshot: { url: preferred.url, styleMap: preferred.styleMap } } : {}
+      ...preferred?.url ? { screenshot: preferred } : {}
     };
   } finally {
     release();
@@ -5728,15 +5773,25 @@ async function executeScreenshot(input, onLog, context) {
       const shotKind = fullPage ? "full-page" : "viewport";
       const task = input.path ? `Navigate to "${input.path}", then: ${input.instructions}. After completing these steps, take a ${shotKind} screenshot.` : `${input.instructions}. After completing these steps, take a ${shotKind} screenshot.`;
       const result = await runBrowserAutomation(task, context, {
-        capture: fullPage ? "fullPage" : "viewport"
+        capture: fullPage ? "fullPage" : "viewport",
+        analysisPrompt: input.prompt
       });
       if (!result.screenshot) {
         return result.text;
       }
+      const { url, styleMap, analysis } = result.screenshot;
+      if (analysis) {
+        onLog?.(JSON.stringify({ url, analysis }));
+        return JSON.stringify({
+          url,
+          analysis,
+          ...styleMap ? { styleMap } : {}
+        });
+      }
       return await streamScreenshotAnalysis({
-        image: result.screenshot.url,
+        image: url,
         prompt: input.prompt,
-        styleMap: result.screenshot.styleMap,
+        styleMap,
         onLog,
         model,
         apiConfig: context?.apiConfig
@@ -5782,7 +5837,7 @@ var init_screenshot2 = __esm({
           },
           prompt: {
             type: "string",
-            description: "Optional question about the screenshot. If omitted, returns a general description of what's visible."
+            description: "Optional specific questions about the screenshot, answered alongside the general description of what's visible. If omitted, returns just the general description."
           },
           imageUrl: {
             type: "string",
@@ -6896,7 +6951,7 @@ var init_createWireframe = __esm({
     UPLOAD_TIMEOUT_MS2 = 3e4;
     definition10 = {
       name: "createWireframe",
-      description: "Create (or revise) a wireframe from self-contained HTML+CSS. Call this while working to generate a sharable wireframe asset: the result returns the exact markdown reference line to paste into your response and into specs (like generateImages returns the image URL). Calling again with the same slug overwrites the wireframe in place, so a revision keeps its path and existing references stay current.",
+      description: "Generate a wireframe from self-contained HTML+CSS you author and write it to disk as a design artifact. This is how a wireframe comes to exist \u2014 the way generateImages is how an image comes to exist \u2014 and the developer builds from the file it creates. The result also hands back the reference line that embeds the wireframe in your response and in specs; paste it wherever the wireframe belongs and it renders as a live preview. Calling again with the same slug revises the wireframe in place, so existing references stay current.",
       inputSchema: {
         type: "object",
         properties: {
@@ -6906,7 +6961,7 @@ var init_createWireframe = __esm({
           },
           slug: {
             type: "string",
-            description: 'Filename stem, lowercase kebab-case (e.g. "feed-post-card"). The wireframe lives at src/.wireframes/{slug}.html. Re-use a slug to revise that wireframe in place.'
+            description: 'Filename stem, lowercase kebab-case (e.g. "feed-post-card"). Re-use a slug to revise that wireframe in place.'
           },
           description: {
             type: "string",
@@ -11172,7 +11227,10 @@ var init_headless = __esm({
       //////////////////////////////////////////////////////////////////////////////
       handleClear() {
         clearSession(this.state);
-        return {};
+        return {
+          modelSurfaces: getEffectiveModelSurfaces(),
+          allowedModelsByType: ALLOWED_MODELS_BY_TYPE
+        };
       }
       /** Change per-agent model picks without clearing history. Takes effect on
        * the next turn — the model is resolved live, per LLM call, from

package/dist/prompt/compiled/interfaces.md

@@ -120,6 +120,8 @@ analytics.track('vendor_submitted', { vendorType: 'restaurant' });
 analytics.track('checkout_completed', { itemCount: 3, total: 47.99 });
 ```
 
+- **Apps can also READ their own analytics from backend methods** — the agent SDK's `analytics` namespace (lifetime per-page metrics, live visitor count, traffic sources, event stats), so an admin view can show real traffic next to the app's own data. Consult `askMindStudioSdk` for the query API when building one.
+
 Analytics is **cookie-banner-free by design**: per-app scoping, IP discarded after geo lookup, country-level only, query strings server-scrubbed except for a UTM whitelist (`utm_*`, `ref`, `source`, `gclid`, `fbclid`, `msclkid`), no fingerprinting, no third-party scripts. If a user asks about GDPR cookie consent for analytics, you can explain why it is not needed.
 
 Disabling telemetry is a per-app dashboard setting (platform toggle, not code). Point users there if they ask.

package/dist/prompt/compiled/jewels.md

@@ -1,3 +1,3 @@
 # Jewels
 
-A "jewel" is an optional AI companion for a single app method (`foo.jewel.ts` beside `foo.ts`): it proposes the method call a human would otherwise make, the method's manifest `autonomy` setting decides what happens to each proposal: recorded silently (`shadow`), queued for human review (`approve`), or committed (`auto`), and every proposal is then graded against what really happened. Jewels are never part of an initial build, and most apps will never need them. By default, build AI features as plain method code - if the user wants to add jewels later on, conversion is easy and additive. Before doing any work with or thinking around jewels, load the `jewels` skill.
+A "jewel" is an optional AI companion for a single app method (`foo.jewel.ts` beside `foo.ts`): it proposes the method call a human would otherwise make, the method's manifest `autonomy` setting decides what happens to each proposal: recorded silently (`shadow`), queued for human review (`approve`), or committed (`auto`), and every proposal is then graded against what really happened. Jewels are never part of an initial build, and most apps will never need them. By default, build AI features as plain method code - if the user wants to add jewels later on, conversion is easy. Before doing any work with or thinking around jewels, load the `jewels` skill.

package/dist/prompt/compiled/tables.md

@@ -167,14 +167,55 @@ const results = await Vendors
 // Aggregates — all return Query objects (batchable)
 const count = await Vendors.count();
 const any = await Vendors.some(v => v.status === 'pending');
-const cheapest = await Vendors.min(v => v.totalCents);
-const grouped = await Vendors.groupBy(v => v.status);
+const cheapest = await Vendors.min(v => v.totalCents);   // full ROW with min value
+const grouped = await Vendors.groupBy(v => v.status);    // Map of FULL rows — fetches everything
 
 // These two return Promises directly (not batchable)
 const all = await Vendors.every(v => v.status !== 'rejected');
 const empty = await Vendors.isEmpty();
 ```
 
+### Aggregation
+
+`count()`, `sum()`, `avg()`, `countDistinct()`, and `aggregate()` compile to SQL aggregates (`COUNT`/`TOTAL`/`AVG`/`GROUP BY`) — no rows are fetched, so they stay cheap at any table size. Use them for every summary over a table that can grow; never page a whole table into memory to compute totals.
+
+```typescript
+// Scalar aggregates — accessors, like sortBy/min/max
+const revenue = await Orders.filter(o => o.status === 'paid').sum(o => o.amountCents);
+const avgScore = await Answers.avg(a => a.score);            // number | null (null on empty set)
+const respondents = await Answers.countDistinct(a => a.responseId);
+
+// Grouped aggregation — STRING column names, one plain object per group
+const top = await Answers
+  .filter((a, $) => a.surveyId === $.surveyId, { surveyId }) // bindings: lifts closure var so filter compiles to SQL
+  .aggregate({
+    by: ['questionId', 'dimension'],
+    select: {
+      n: { count: true },
+      total: { sum: 'score' },
+      avgScore: { avg: 'score' },
+      respondents: { countDistinct: 'responseId' },
+    },
+    orderBy: 'total', desc: true, limit: 20,
+  });
+// Array<{ questionId, dimension, n: number, total: number, avgScore: number | null, respondents: number }>
+```
+
+Select terms: `{ count: true }`, `{ sum: 'col' }`, `{ avg: 'col' }`, `{ min: 'col' }`, `{ max: 'col' }`, `{ countDistinct: 'col' }`. Omit `by` for several aggregates over the whole filtered set (returns a single object). Empty set: `count`/`countDistinct` → 0, `sum` → 0, `avg`/`min`/`max` → null. `groupBy()` fetches full rows — reach for it only when you need the rows themselves, not a summary.
+
+### Raw SQL Escape Hatch
+
+`db.sql()` runs read-only raw SQL against the app's own database — for joins, subqueries, and window functions the typed API can't express. Last resort: prefer the typed API (including `aggregate()`) whenever it can express the query.
+
+```typescript
+const rows = await db.sql<{ questionId: string; n: number }>(
+  'SELECT questionId, COUNT(*) AS n FROM answers WHERE surveyId = ? GROUP BY questionId',
+  [surveyId],
+);
+```
+
+`SELECT`/`WITH` only — writes throw; use Table methods for writes. Positional `?` bind params. Lazy and batchable via `db.batch()`. Raw rows come back close to how SQLite stores them and may not exactly match the typed API's representations.
+
 ### Updating Records
 
 ```typescript
@@ -342,7 +383,7 @@ const [_, newOrder, pending] = await db.batch(
 
 **Always batch instead of sequential awaits.** A loop with `await Table.update()` inside makes N separate HTTP calls. Mapping to mutations and passing them to `db.batch()` makes one.
 
-**Note:** Almost all read methods return batchable `Query` objects — including `get()`, `findOne()`, `count()`, `some()`, `min()`, `max()`, and `groupBy()`. The exceptions are `every()` and `isEmpty()`, which return Promises directly and cannot be batched.
+**Note:** Almost all read methods return batchable `Query` objects — including `get()`, `findOne()`, `count()`, `sum()`, `avg()`, `countDistinct()`, `aggregate()`, `some()`, `min()`, `max()`, and `groupBy()` — and `db.sql()` results batch too. The exceptions are `every()` and `isEmpty()`, which return Promises directly and cannot be batched.
 
 ## Migrations
 

package/dist/prompt/skills/jewels.md

@@ -30,7 +30,7 @@ One jewel per judgment. If a jewel would need to take two actions, the methods a
 
 Never include a jewel in an initial build, and don't bring them up while an app is young. Most users will never want one; a few will care a lot. The default posture:
 
-- **Build AI features plainly.** A drafting feature is a method that calls a model and returns text, with no jewel machinery anywhere. Converting it to a jewel later is additive (a `.jewel.ts` beside the method, an `autonomy` line in the manifest); nothing about the plain version is thrown away.
+- **Build AI features plainly.** A drafting feature is a method that calls a model and returns text, with no jewel machinery anywhere. Converting it later is cheap. At shadow it's purely additive (a `.jewel.ts` beside the method, an `autonomy` line in the manifest). At approve, the jewel takes over as the sole producer: it proposes what the plain feature used to write, surfaced in the same place the human already saw it, and the plain generation is retired — one generator, always. A jewel graded against human edits of some other AI's draft is measuring model against model.
 - **Jewels enter when the user asks** about automating a judgment the app already handles, or picks an automation item off the roadmap. Once an app is solid and a judgment verb sees real use, a benefit-phrased automation item may belong on the roadmap; that is the only proactive channel.
 - **When the user engages, have the conversation first**: what it does in their terms, what the levels mean, what evidence looks like. Then start with exactly one verb.
 
@@ -77,7 +77,7 @@ interface JewelPairRecord {
 
 The executor never throws: a shadow run must never break anything. Your code failing inside `subject` or `propose` becomes the record's `error`; `grade` failing softens to verdict `skip`.
 
-Shadowing runs only on the deployed app. Dev traffic never fires jewels; dev invocations are synthetic and would pollute the pair ledger.
+Shadowing runs only on the deployed app — dev invocations are synthetic and would pollute the pair ledger. The arrival flow is different: `jewels.propose` on approve/auto methods runs for real in dev sessions (the jewel executes from local source, queue items are scoped to the dev session, auto commits apply against the dev database) so the app's hot path is testable end-to-end, but none of it is recorded — no pairs, no grading, no training data.
 
 ## Usage
 
@@ -203,7 +203,7 @@ grade: async ({ proposed, actual }) => {
 
 Four levels: `manual` (no jewel ever; a policy statement), `shadow` (runs silently on every human invocation, pairs recorded, nothing visible), `approve` (jewel drafts, a human accepts, edits, or rejects; the edit is the richest training signal there is), `auto` (the jewel acts under its own identity).
 
-**Auto is the only level you earn with evidence. Shadow and approve are both safe starting points; pick by what the product is.** When the proposals themselves are the product (drafts for review), start at approve; it's often the permanent home. When the evidence is the product (an auto-bound verb), start at shadow. Raising to auto is a reviewed manifest diff justified by agreement numbers.
+**Auto is the only level you earn with evidence. Shadow and approve are both safe starting points; pick by what the product is.** When the proposals themselves are the product (drafts for review), start at approve; it's often the permanent home. When the evidence is the product (an auto-bound verb), start at shadow. The levels differ in what exists, not in presentation: at approve the human sees and edits the proposal before it takes effect; at shadow nothing ever surfaces. Raising to auto is a reviewed manifest diff justified by agreement numbers.
 
 **Choose approve by the verb's risk shape, not by default.** Reversible state-machine verbs (routing, classification; a mistake is a two-click correction) go shadow → auto with a `sampleRate` canary and skip approve, because a review queue on a high-agreement classifier adds work without adding safety. Approve belongs on irreversible or outward-facing verbs (send, publish, charge, refund): `sampleRate` is population-level risk control, and those verbs need per-instance gating, which is what approve is.
 
@@ -229,7 +229,7 @@ from the platform's small menu; `qwen3.5-4b` is the default, with `qwen3.5-9b` a
 `gpt-oss-20b` as larger alternatives, and the default is the right choice unless a
 report shows it falling short), `windowDays` (how many days of ledger history to train
 on; default all history), `epochs` (1-10, default 3), `rank` (LoRA rank, 4-64, default
-16), `learningRate` (default 5e-5). It requires `jewel`, and it rides the release:
+16), `learningRate` (default 1e-4). It requires `jewel`, and it rides the release:
 changing a knob is a commit + deploy before the next training run.
 
 Once a method has accumulated graded pairs, train from the prod CLI:
@@ -238,14 +238,20 @@ a run id and the dataset report; a run takes minutes to tens of minutes, so neve
 `--wait` (that flag is for humans at a terminal — it would block your whole loop).
 Start the run, tell the user it's training, keep working on other things, and check in
 with `mindstudio-prod jewels run <runId>` between tasks — the `progress` field shows
-the live phase and training percent, and `status` goes `complete` or `failed` with the
+the live phase and training percent, the run's `log` narrates the whole story as
+timestamped status events (queued, GPU acquired, training, grading — loss points are
+compacted to a count in CLI output), and `status` goes `complete` or `failed` with the
 full report. The dataset report says whether the ledger is trainable (pairs without an
 attached `trace` don't count), and a run produces a downloadable LoRA adapter plus a
 held-out agreement report: how often the trained model matched your team's decisions
 on pairs it never saw. The adapter and report land in the app's own file store
 (`models/` in the Files dashboard), so the user can download them there. The
-agreement number is `report.grading.agreement` — scored by the jewel's own grade
-function, the same grader as the pairs dashboard; there is no other agreement field.
+agreement number is `report.selected.agreement` when present, else
+`report.grading.agreement` — scored by the jewel's own grade function, the same grader
+as the pairs dashboard. A run trains multiple checkpoint candidates (per-epoch
+snapshots, plus a DPO pass over the team's corrections when enough have accumulated)
+and the platform promotes whichever scores highest on that grader — `report.selected`
+names the serving checkpoint; this is automatic, never something you configure.
 A completed run without a `grading` block just hasn't been graded yet
 (`mindstudio-prod jewels grade <runId>` fills it). A completed run registers the
 app's tuned model as a real model id — `tuned/{appId}/{methodId}`, one stable id per
@@ -253,9 +259,19 @@ method that retraining advances in place — and the latest complete run per met
 automatically served on the platform's GPU pool, so that id works like any other
 model the moment training finishes. There is no special invoke tool: to sanity-check
 or demo a tuned model, make an ordinary generate-text call with that model id (the
-pool serves it with the exact template posture it was trained under). Promotion (the
-app actually switching a jewel onto its tuned model) is still a deliberate later
-step; do not wire a tuned model into app code unprompted.
+pool serves it with the exact template posture it was trained under). **Promotion**
+(switching a jewel onto its own tuned model) is a one-line change: swap the `model`
+id inside the jewel's existing `runTask` call to the tuned line — the git commit is
+the promotion record, and reverting it is the rollback. Tool-using jewels promote
+too: the tuned model was trained on the jewel's full transcripts, tool calls
+included, and the training report's `toolEval` block shows how faithfully it makes
+the teacher's tool decisions (qwen bases only — gpt-oss can't drive tools yet, and
+the platform rejects that combination with a clear error). One hard rule: never
+restructure the propose path to a generate-text call to do it — that silently loses
+`outputSchema` validation AND the task `traceId`, so the jewel's new pairs stop
+being trainable and the learning loop dies. `runTask` with the tuned id keeps both.
+Promotion is still a deliberate step; do not wire a tuned model into app code
+unprompted.
 
 ## Arrival Triggers (`mindstudio.jewels.propose`)
 
@@ -288,7 +304,7 @@ Rules that matter:
 
 ## Native Approval Flows (`jewels.queue`)
 
-For `approve`-mode methods, the review inbox belongs in the app, next to the work. Three pieces:
+For `approve`-mode methods, the queue is data, not a screen: proposals surface wherever the human already makes this decision. When the app has an editor for the decision, the pending proposal pre-fills it and the human's normal confirm action resolves it; a dedicated inbox is only for decisions with no existing surface. Three pieces:
 
 ```typescript
 // 1. Backend list method, gated with the APP'S reviewer role.
@@ -297,7 +313,7 @@ export async function listPendingDrafts() {
   return mindstudio.jewels.queue.list({ methodId: 'send-message' });
 }
 
-// 2. Frontend inbox UI renders items: subject, proposed input, reasoning.
+// 2. Frontend surfaces items where the decision already lives (pre-fill the existing editor); render subject, proposed input, reasoning.
 
 // 3. Backend resolve method: approve applies, dismiss records.
 export async function reviewDraft(input: {

package/dist/prompt/static/coding.md

@@ -82,7 +82,7 @@ You have access to the `mindstudio` CLI, which exposes every SDK action as a com
 ### Production App Management
 You have access to `mindstudio-prod`, a CLI for managing the user's production app. Use it via your bash tool. All output is JSON. Run `mindstudio-prod --help` or `mindstudio-prod <command> --help` to discover usage and available options.
 
-Available commands: `requests` (server logs, errors, latency), `crashes` (frontend browser errors), `analytics` (traffic, referrers, live counters), `releases`, `diagnostics` (Lighthouse audit), `domains`, `users` (list, set roles), `db` (query production sql), `data` (live db operations like lift-from-dev), `methods` (list, invoke), `secrets`, `files` (CDN files), `datasources` (document corpora), `prerender` (crawler snapshots), `voice` (phone numbers, call logs, voice policy), `issues` (externally-reported bugs).
+Available commands: `requests` (server logs, errors, latency), `crashes` (frontend browser errors), `analytics` (traffic queries — lifetime metrics, sources, live counters), `releases`, `diagnostics` (Lighthouse audit), `domains`, `users` (list, set roles), `db` (query production sql), `data` (live db operations like lift-from-dev), `methods` (list, invoke), `secrets`, `files` (CDN files), `datasources` (document corpora), `prerender` (crawler snapshots), `voice` (phone numbers, call logs, voice policy), `issues` (externally-reported bugs).
 
 Two rules: buying a `voice` phone number bills $1/month — never buy without the user's explicit confirmation. `issues` is for externally-reported bugs only — read from it and resolve items when the user asks; never use it to track work you are doing with the user.
 

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

@@ -16,7 +16,7 @@ Think about the ways you can truly elevate the design. Use image generation to c
 - After you've taken a screenshot, use analyze image to ask different questions about it - don't re-screenshot the page unnecessarily.
 - Match the image engine to the job: `renderImage` (a browser rendering HTML you author) for token-exact graphics — share cards, wordmarks, flat icon tiles; `generateImages` (an image model) for organic, photographic, and illustrated work. Don't ask the image model to hit exact hex codes or typography, and don't hand-write SVG path data — compose HTML/CSS and render it.
 - When you write user-facing copy (headlines, captions, labels, body text), hand it to `polishCopy` before finalizing. It tightens prose so it reads like a person wrote it rather than a machine, without changing what it says. Cheap and fast — use it on any copy that will ship.
-- Build wireframes with `createWireframe` during your working phase as you work out a layout, component, or interaction. Creating wireframes is how you create interactive assets to share back to the user, like how you generate images. The result returns the exact `![name](src/.wireframes/{slug}.html)` reference line; paste it into your response where the wireframe belongs. It renders as a live preview, and the developer reads the file for the exact markup. Same slug = revise in place; new slug = new wireframe.
+- Build wireframes with `createWireframe` during your working phase as you work out a layout, component, or interaction. The tool generates the wireframe as a real asset, the way `generateImages` generates images: it writes the file the developer builds from, and its result hands back the reference line that embeds the wireframe in your response. Paste that line where the wireframe belongs and it renders as a live preview. Same slug = revise in place; new slug = new wireframe.
 
 ## Voice
 - No emoji, no filler.

package/dist/subagents/designExpert/prompts/ui-patterns.md

@@ -25,7 +25,7 @@ Some surfaces are deep enough to carry their own craft reference in <available_s
 
 ### Wireframes
 
-Wireframes are design artifacts you build while you work, in the same phase as screenshots and image generation. As you work out a layout, a card anatomy, an interaction, or a motion pattern, build it with `createWireframe`: a `name`, a kebab-case `slug`, a one-line `description`, and self-contained HTML+CSS. Sketching in HTML is how you think through spatial decisions, so by the time you write your direction, the wireframes that anchor it already exist. The tool result returns the exact markdown reference line (`![Feed Post Card](src/.wireframes/feed-post-card.html)`) — when you write your response, paste that line wherever the wireframe belongs, with your notes in the surrounding prose. The reference renders as a live visual preview, and the developer reads the file itself for the exact markup and CSS.
+Wireframes are design artifacts you build while you work, in the same phase as screenshots and image generation. As you work out a layout, a card anatomy, an interaction, or a motion pattern, build it with `createWireframe`: a `name`, a kebab-case `slug`, a one-line `description`, and self-contained HTML+CSS. Sketching in HTML is how you think through spatial decisions, so by the time you write your direction, the wireframes that anchor it already exist as files — the developer reads them for the exact markup and CSS. Each call's result hands back the markdown reference line that embeds that wireframe; when you write your response, paste it wherever the wireframe belongs, with your notes in the surrounding prose, and it renders as a live visual preview.
 
 Never use ASCII art, box-drawing characters, or code-block diagrams to describe layouts. Always use a wireframe instead, even if it's just grey rectangles with labels. A 20-line wireframe with placeholder boxes communicates proportions, spacing, and hierarchy better than any text diagram. For abstract layouts, use skeleton-style placeholders (grey boxes, rounded rects) rather than mocking up real content.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.289",
+  "version": "0.1.291",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",