ugly-app 0.1.484 → 0.1.485

package/dist/cli/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.1.484";
+export declare const CLI_VERSION = "0.1.485";
 //# sourceMappingURL=version.d.ts.map

package/dist/cli/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.484";
+export const CLI_VERSION = "0.1.485";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-app",
-  "version": "0.1.484",
+  "version": "0.1.485",
   "type": "module",
   "main": "./dist/server/index.js",
   "exports": {

package/src/cli/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.484";
+export const CLI_VERSION = "0.1.485";

package/templates/.claude/skills/bot-swarm/SKILL.md

@@ -181,11 +181,50 @@ This starts Docker, MongoDB, and the server but **without** tsx watch, tsc --wat
 
 **Use the shipped driver — do NOT write your own.** The template includes a pre-validated Playwright driver at `bots/feedback/run-bot.mjs` that handles everything mechanical: launching headless Chromium, setting the bot auth cookie, screenshotting + element-mapping each page, and submitting via `npx ugly-app feedback:submit`. Earlier cycles wasted 20+ minutes mid-run rebuilding this from scratch and debugging the playwright spawn — the bundled script is the contract. Don't rewrite it.
 
+The driver has three modes; in this step we use `--capture` then `--submit` so the persona can **actually see the page** before authoring findings:
+
+```bash
+node bots/feedback/run-bot.mjs <slug> --capture  # crawl + screenshots only
+node bots/feedback/run-bot.mjs <slug> --submit   # post findings.json (no Playwright)
+```
+
 Dispatch ALL active personas as **parallel subagents** (`delegate_parallel`). Each subagent does:
 
-1. Read `bots/feedback/active/{slug}/persona.md` and `memory.md` to get into character.
+1. **READ persona.** Open `bots/feedback/active/{slug}/persona.md` and `memory.md` to get into character.
 
-2. **Author the persona's findings.** Look at the screenshots + element maps from the previous cycle if any (`bots/journal/cycles/screenshots/{slug}/*.png` and `*.element-map.json`). Decide what 1–5 observations this persona would make. Write them to `bots/feedback/active/{slug}/findings.json`:
+   Optionally override which routes the persona crawls by writing `bots/feedback/active/{slug}/pages.json` (default: `["/"]`):
+
+   ```json
+   ["/", "/inbox", "/settings"]
+   ```
+
+2. **CAPTURE current state.** Run the driver in capture-only mode:
+
+   ```bash
+   node bots/feedback/run-bot.mjs {slug} --capture
+   ```
+
+   This writes fresh PNGs + element maps to `bots/journal/cycles/screenshots/{slug}/<page>.png` and `<page>.element-map.json` reflecting the CURRENT site. No feedback is submitted yet.
+
+3. **LOOK at each page.** For each PNG under `bots/journal/cycles/screenshots/{slug}/`, inspect it using vision — the persona **must actually see** the page before writing findings:
+
+   - If `analyze_image` is available (ugly-studio coding-agent):
+
+     ```
+     analyze_image(
+       path="bots/journal/cycles/screenshots/{slug}/<page>.png",
+       query="<persona-specific question about layout, contrast,
+              copy, mobile fit, image rendering, overlap, etc.>"
+     )
+     ```
+
+     Run multiple targeted queries per image — `analyze_image` is bounded (Haiku) and each call is cheap. Vague one-shots like "describe everything" waste tokens; specific questions like "is the hero CTA legible against the background" / "list any overlapping text in the masthead" / "what does the empty-library state actually look like" produce usable answers.
+
+   - If running under claude-code CLI or any vision-capable model: Read the PNG path with the Read tool — the model sees it inline.
+
+   - Cross-reference with the matching `<page>.element-map.json` to resolve specific `dataId` / source-file references when you find something worth reporting.
+
+4. **AUTHOR findings.json.** Write 1–5 findings to `bots/feedback/active/{slug}/findings.json`:
 
    ```json
    [
@@ -195,23 +234,17 @@ Dispatch ALL active personas as **parallel subagents** (`delegate_parallel`). Ea
    ]
    ```
 
-   Optionally, override which routes the persona crawls by writing `bots/feedback/active/{slug}/pages.json` (default: `["/"]`):
+   Each `message` must reference something the persona actually saw — layout reality, contrast, copy, image rendering, overlap, broken animation. Vague feature wishes that could have been written without looking at the page are wasted feedback; rewrite them with a visual hook ("when I see X on /capture, Y is wrong because…").
 
-   ```json
-   ["/", "/inbox", "/settings"]
-   ```
-
-3. **Run the driver.** This launches Chromium, screenshots each route into `bots/journal/cycles/screenshots/{slug}/<page>.png`, captures the element map, and submits one feedback per finding via the framework's `submitFeedbackBot` endpoint:
+5. **SUBMIT findings.** Run the driver in submit-only mode:
 
    ```bash
-   node bots/feedback/run-bot.mjs {slug}
+   node bots/feedback/run-bot.mjs {slug} --submit
    ```
 
-4. Update `bots/feedback/active/{slug}/memory.md` with what you submitted, what changed since last cycle, and how the persona's view of the site is evolving.
-
-**Be ambitious.** Don't just report cosmetic nits — request new features, suggest adding entire pages, propose redesigns, ask for search/filter/sort, animations, dark mode, better navigation, new data models. Think like a demanding product manager, not a passive observer.
+   This posts one feedback row per finding via `submitFeedbackBot` (data-proxy `db.captureFeedback`) with the captured screenshot + element map attached as `context.screenshotPath` / `context.elementMap`.
 
-8. Update `bots/feedback/active/{slug}/memory.md`:
+6. **Update memory.** Edit `bots/feedback/active/{slug}/memory.md`:
 
    ```markdown
    ## Cycle [YYYY-MM-DD]
@@ -224,6 +257,8 @@ Dispatch ALL active personas as **parallel subagents** (`delegate_parallel`). Ea
    [compress entries older than 3 cycles into History block when > ~4000 tokens]
    ```
 
+**Be ambitious.** Don't just report cosmetic nits — request new features, suggest adding entire pages, propose redesigns, ask for search/filter/sort, animations, dark mode, better navigation, new data models. Think like a demanding product manager, not a passive observer.
+
 **Timeout**: 20 minutes per bot. Failed bots do not block others.
 Record which bots succeeded and which failed/timed out.
 
@@ -248,6 +283,8 @@ Run sequentially in one session. No questions. Make autonomous decisions.
      npx ugly-app feedback:resolve --id "<feedbackReportId>" --status resolved --resolution "captured for processing"
      ```
 
+   - **Do NOT muzzle this CLI with `2>/dev/null > /dev/null`.** If a resolve call fails, you need to see it. A silent failure here leaves feedback at `status: new`, so the next cycle re-processes the same items as duplicates and the persona memory diverges from reality. If you batch resolves in a loop, treat any non-zero exit as a cycle-breaking error: surface it, stop the loop, and do not claim `Maintain: success`.
+
 3. Invoke `/fix-feedback local` — run completely unattended:
    - Do not ask which environment. Use `local`.
 

package/templates/.claude/skills/fix-feedback/SKILL.md

@@ -36,6 +36,28 @@ The only valid reason to decline feedback is if it contradicts a Critical Rule i
 
 If you're unsure how to implement something, read the existing code, read the ugly-app API reference, and figure it out. Do not skip it. Do not defer it. Do not say "this would require significant refactoring" — just do the refactoring.
 
+## Using screenshots
+
+Bot-submitted feedback (and any feedback from the studio's bug-report flow) includes `context.screenshotPath` — an absolute path to the PNG the user/persona saw when they wrote the feedback. **Look at it before proposing a fix.** The written message alone is insufficient context for layout, contrast, spacing, image-rendering, or overlap work — the user is reacting to what they SAW.
+
+- If `analyze_image` is available (ugly-studio coding-agent):
+
+  ```
+  analyze_image(
+    path=context.screenshotPath,
+    query="describe the area the user is reacting to; list any visible
+           defects in layout, contrast, copy, or image rendering"
+  )
+  ```
+
+  Run multiple targeted queries when the feedback is non-trivial — one for the affected region, one to OCR any visible text the user references, one for colors/contrast if the complaint is design-related. `analyze_image` is Haiku-cheap; vague one-shots waste tokens.
+
+- If the active model is vision-capable (Claude Code CLI, Claude/GPT/Gemini framework models): `Read(context.screenshotPath)` inlines the image directly.
+
+Cross-reference what you see with `context.elementMap` (next section) to translate visual descriptions into source-file references.
+
+**Do NOT propose a visual fix without inspecting the screenshot.** Element maps describe DOM state; the screenshot is the only record of what the user perceived.
+
 ## Using element maps
 
 Feedback may include an `elementMap` field — a JSON snapshot of every interactive element on the page with:

package/templates/bots/feedback/run-bot.mjs

@@ -1,23 +1,29 @@
 #!/usr/bin/env node
 /**
  * Pre-validated feedback-bot driver. The bot-swarm skill calls this
- * once per persona during Step 2 (Feedback Bots).
+ * once or twice per persona during Step 2 (Feedback Bots).
  *
  * Usage:
- *   node bots/feedback/run-bot.mjs <persona-slug>
+ *   node bots/feedback/run-bot.mjs <persona-slug>            # legacy: capture + submit in one pass
+ *   node bots/feedback/run-bot.mjs <persona-slug> --capture  # crawl + screenshots only (no submit)
+ *   node bots/feedback/run-bot.mjs <persona-slug> --submit   # submit findings.json (no Playwright)
+ *
+ * The two-phase form exists so the persona subagent can LOOK at the
+ * just-captured screenshots (Read on PNG, or `analyze_image`) before
+ * authoring findings.json. The single-pass form is the original
+ * crawl+submit flow and is kept for callers that don't need vision.
  *
  * Reads `bots/feedback/active/<slug>/.env` for `BOT_TOKEN`, launches a
  * headless Chromium, browses the local dev server (`BASE_URL`,
  * default http://localhost:5400), captures a screenshot per page +
- * an element map, and submits a `feedback` entry per finding via
+ * an element map, and submits one `feedback` entry per finding via
  * `npx ugly-app feedback:submit`.
  *
  * Why this is shipped instead of asked-of-the-model: every prior
  * cycle the manager re-invented this script and burned 20+ min
  * iterating on the playwright spawn, the screenshot path layout,
  * and the feedback-submit args. A known-good template short-circuits
- * that loop. Edit the `analyze` callback to change what each persona
- * looks at, but leave the I/O scaffolding alone.
+ * that loop. Don't rewrite the I/O scaffolding.
  *
  * Output:
  *   - bots/journal/cycles/screenshots/<slug>/<page>.png
@@ -35,7 +41,19 @@ const execFileP = promisify(execFile);
 
 const SLUG = process.argv[2];
 if (!SLUG) {
-  console.error('Usage: node bots/feedback/run-bot.mjs <persona-slug>');
+  console.error(
+    'Usage: node bots/feedback/run-bot.mjs <persona-slug> [--capture|--submit]',
+  );
+  process.exit(2);
+}
+
+const MODE_FLAG = process.argv[3];
+let MODE; // 'capture' | 'submit' | 'both'
+if (!MODE_FLAG) MODE = 'both';
+else if (MODE_FLAG === '--capture') MODE = 'capture';
+else if (MODE_FLAG === '--submit') MODE = 'submit';
+else {
+  console.error(`[${SLUG}] unknown mode flag "${MODE_FLAG}" — use --capture or --submit`);
   process.exit(2);
 }
 
@@ -162,49 +180,34 @@ async function submitFeedback({ type, message, url, screenshot, elementMap }) {
   }
 }
 
-// --- Main crawl ------------------------------------------------------
-fs.mkdirSync(SCREENSHOTS_DIR, { recursive: true });
-
-const browser = await chromium.launch({ headless: true });
-const ctx = await browser.newContext();
-// Cookie-based bot auth: the framework's authReq handler accepts
-// `Authorization: Bearer ...` headers. Set the token as a cookie too
-// so the SPA's same-origin fetches inherit it without each persona
-// having to wire it through manually.
-await ctx.addCookies([
-  {
-    name: 'ugly_auth',
-    value: BOT_TOKEN,
-    url: BASE_URL,
-  },
-]);
-
-const page = await ctx.newPage();
-
-for (const route of pages) {
+// --- Per-route helpers ----------------------------------------------
+function routeFilenames(route) {
   const slugForFile = route === '/' ? 'home' : route.replace(/[^a-z0-9]+/gi, '-');
-  const screenshotPath = path.join(SCREENSHOTS_DIR, `${slugForFile}.png`);
-  const elementMapPath = path.join(SCREENSHOTS_DIR, `${slugForFile}.element-map.json`);
-  const url = `${BASE_URL}${route}`;
+  return {
+    slugForFile,
+    screenshotPath: path.join(SCREENSHOTS_DIR, `${slugForFile}.png`),
+    elementMapPath: path.join(SCREENSHOTS_DIR, `${slugForFile}.element-map.json`),
+    url: `${BASE_URL}${route}`,
+  };
+}
 
+async function captureRoute(page, route) {
+  const { screenshotPath, elementMapPath, url } = routeFilenames(route);
   try {
     await page.goto(url, { waitUntil: 'networkidle', timeout: 15_000 });
   } catch (err) {
     console.error(`[${SLUG}] failed to load ${url}: ${err.message}`);
-    continue;
+    return false;
   }
-
   await page.screenshot({ path: screenshotPath, fullPage: true });
   const elementMap = await captureElementMap(page);
   fs.writeFileSync(elementMapPath, JSON.stringify(elementMap, null, 2));
+  return true;
+}
 
-  // --- Hand-off to the persona's analysis ----------------------------
-  // Override `analyze` per persona by writing
-  // `bots/feedback/active/<slug>/findings.json` with an array of
-  // `{ type, message }` objects that the persona drafted from
-  // looking at the screenshot + element map. Default behavior:
-  // submit a single placeholder so the journal isn't empty even if
-  // the persona's findings.json wasn't generated.
+function loadFindings(route) {
+  // The persona authors findings.json between `--capture` and `--submit`.
+  // If absent or empty we emit a placeholder so the journal isn't empty.
   const findingsPath = path.join(BOT_DIR, 'findings.json');
   let findings = [];
   if (fs.existsSync(findingsPath)) {
@@ -223,17 +226,58 @@ for (const route of pages) {
       },
     ];
   }
+  return findings;
+}
 
+async function submitForRoute(route) {
+  const { screenshotPath, elementMapPath, url } = routeFilenames(route);
+  // The screenshot/element-map are attached only if the capture phase
+  // actually produced them (e.g. when running `--submit` after
+  // `--capture`, or in `both` mode).
+  const hasScreenshot = fs.existsSync(screenshotPath);
+  const hasElementMap = fs.existsSync(elementMapPath);
+  const findings = loadFindings(route);
   for (const f of findings) {
     await submitFeedback({
       type: f.type ?? 'feature',
       message: `${personaText.slice(0, 200)}\n\n${f.message}`,
       url,
-      screenshot: screenshotPath,
-      elementMap: elementMapPath,
+      screenshot: hasScreenshot ? screenshotPath : undefined,
+      elementMap: hasElementMap ? elementMapPath : undefined,
     });
   }
 }
 
-await browser.close();
-console.log(`[${SLUG}] done — ${pages.length} pages crawled.`);
+// --- Main ------------------------------------------------------------
+fs.mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+
+if (MODE === 'capture' || MODE === 'both') {
+  const browser = await chromium.launch({ headless: true });
+  const ctx = await browser.newContext();
+  // Cookie-based bot auth: the framework's authReq handler accepts
+  // `Authorization: Bearer ...` headers. Set the token as a cookie too
+  // so the SPA's same-origin fetches inherit it without each persona
+  // having to wire it through manually.
+  await ctx.addCookies([
+    {
+      name: 'ugly_auth',
+      value: BOT_TOKEN,
+      url: BASE_URL,
+    },
+  ]);
+  const page = await ctx.newPage();
+  for (const route of pages) {
+    const ok = await captureRoute(page, route);
+    if (ok && MODE === 'both') {
+      await submitForRoute(route);
+    }
+  }
+  await browser.close();
+  console.log(`[${SLUG}] ${MODE === 'both' ? 'done' : 'captured'} — ${pages.length} pages.`);
+} else {
+  // MODE === 'submit' — no Playwright needed, just post the findings.
+  for (const route of pages) {
+    await submitForRoute(route);
+  }
+  console.log(`[${SLUG}] submitted findings for ${pages.length} routes.`);
+}