@buoy-gg/mcp 7.0.36 → 7.0.38

package/dist/index.mjs

@@ -27,7 +27,7 @@ import {
   registerStorageTools,
   registerZustandTools,
   runInit
-} from "./chunk-QIINQPNK.mjs";
+} from "./chunk-PQOVQPCW.mjs";
 export {
   ALL_DEVICES,
   BROKER_PORT,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@buoy-gg/mcp",
   "mcpName": "io.github.buoy-gg/mcp",
-  "version": "7.0.36",
-  "description": "MCP server for Buoy devtools — lets any LLM copilot drive Buoy tools (perf-monitor benchmarks, etc.) over the devtool sync protocol",
+  "version": "7.0.38",
+  "description": "MCP server exposing supported Buoy inspection and action tools through the device sync protocol. Tool access requires account and Pro setup.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -32,7 +32,8 @@
     "socket.io-client": "^4.8.1",
     "zod": "^3.25.0",
     "ws": "^8.18.0",
-    "@buoy-gg/sync-broker": "^7.0.36"
+    "@buoy-gg/sync-broker": "^7.0.38",
+    "@buoy-gg/license": "^7.0.38"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skill/buoy-optimize/SKILL.md

@@ -1,95 +1,68 @@
 ---
 name: buoy-optimize
-description: Use when the user wants to optimize a laggy/slow screen or find the most performant way to build something render-heavy (lists, animations, LED grids, canvases, maps) in a React Native app — and the Buoy MCP server is connected. Runs a guided, branching performance R&D loop: scaffold param-driven test variants, benchmark them on a real device with the Buoy perf-monitor, analyze trade-offs holistically (never one metric), prune, fork the winners, and cross-pollinate until distilled. Triggers on phrases like "buoy optimize", "optimize this screen", "find the fastest way to render X", "why is this laggy".
+description: Use when the user asks to investigate a slow React Native screen or compare rendering approaches with a connected Buoy MCP server. Measure a baseline and selected variants, check visual behavior, and explain the observed performance trade-offs. Triggers include "buoy optimize", "optimize this screen", "find the fastest way to render X", and "why is this laggy".
 ---
 
-# Buoy Optimize — guided performance R&D
+# Optimize React Native rendering with Buoy
 
-You drive the **Buoy MCP** perf-monitor tools to run a disciplined experiment loop: build many variants of a render-heavy feature, measure each on a real device, and **distill toward the best-looking + most performant + best-balanced** implementation. This is empirical: you propose, you measure, the user verifies it looks right, you analyze trade-offs, then you iterate.
+Use repeatable measurements to investigate the user's workload. Keep a working baseline, compare a small set of plausible changes, and report which devices and conditions the results cover.
 
-## Before you start
-- Confirm a device is connected: call **`list_devices`** — you need at least one device exposing `perf-monitor`. If none, ask the user to open the app with Buoy running.
-- This works on a **real device or simulator**. Measurements are most stable on a simulator or a device on a cooling pad (heat skews runs) — the user's saved benchmark settings already encode their speed/thermal preference; don't re-ask.
+## Check setup and scope
 
-## The non-negotiable principles (read these first)
-1. **Visual correctness is a human gate, every round.** A fast variant that renders wrong is worthless. After every benchmark, have the user open each variant and confirm it looks right *before* you analyze.
-2. **Never declare a winner on one metric.** Read every axis together (UI FPS, JS FPS, CPU, memory, JS/UI jank). The tools deliberately do NOT crown a single 🏆 — they give per-metric leaders + at-risk flags + "balanced" picks. **UI-thread health outranks raw averages:** a cheap run that drops UI frames (low UI FPS / UI jank) is *worse* than a pricier one that holds them. You cannot compare 10% vs 50% CPU in a vacuum.
-3. **Explain trade-offs in plain language; learn across runs.** "A is cheapest but caps the UI thread → jank risk under load; B costs more CPU but caps nothing → safer." Then combine the best tricks from complementary runs into a new candidate.
-4. **A simulator is a baseline, not the verdict.** A variant that wins on a sim is *likely* better on real hardware — but real devices differ (thermal throttling, real GPU/RAM), so results can shift. Always plan to confirm on a real device, and surface that to the user.
+Call `list_devices` and select the intended device. Benchmarking requires a connected app exposing `perf-monitor`, configured account access and Buoy Pro. If a requirement is missing, explain the setup needed. Do not bypass account checks.
 
-## The test ladder (iOS first, real devices confirm)
-Run the **whole loop per tier**, in this order — and tell the user where you are on the ladder:
+Infer the target screen, existing harness, rendering libraries and workload from the project and conversation. Ask only for missing details that would change the experiment: workload size, required visual behavior, target devices, performance limits or a time budget. Continue work already authorized without asking the user to approve each routine prune or iteration.
 
-**iOS simulator → real iOS device → Android simulator → real Android device.**
+Start on the user's target platform and available device. Record whether it is physical hardware or a simulator, the build type and available device information. Keep comparisons on the same setup. Simulator results apply to that environment; confirm relevant candidates on target hardware before making hardware claims. Do not assume one operating system or device class is faster, or require platforms outside the user's scope.
 
-- **iOS always comes first.** iOS is fast and stable — the cleanest baseline to get an approach genuinely solid before anything else.
-- **Then confirm on a real iOS device.** The sim ranking is a strong signal, but **bulk-test the surviving candidates on a real device** to verify the ranking holds and catch device-specific surprises (thermal, GPU, true memory pressure).
-- **Then Android — expect different, usually worse, results.** Android devices are slower, have less RAM, and the same code often needs extra hacks/tricks to match iOS. Re-run the loop on Android (sim → real device); a variant that won on iOS may need Android-specific work or a different approach entirely. Don't assume iOS wins carry over.
-- **Note the current platform** from `list_devices` (`platform: ios | android`) so you know which rung you're on, and **surface the next rung when one is solid** (see Step 10).
+For a specific interaction that causes excess renders, start with `measure_renders` and the relevant `steps`. This may answer the question without a new test route. Compare the same steps after editing with `compareToPrevious: true`. Treat reported render reasons and wasted-render counts as diagnostics to investigate, not proof that a render is unnecessary.
 
-## Step 1 — Kickoff wizard (infer first, ask only the gaps)
-First **state what you can already infer** (target feature from the open file/conversation; whether a test harness exists — scan the repo; render tech from imports; device refresh rate from a perf snapshot). Then ask **only these three** (use multiple-choice; pre-fill your best guess; let "Other" cover the rest):
+## Choose a baseline and candidates
 
-1. **Workload / scale** — what load should each approach hold up at? (e.g. 100 / 1k / 12k items, or a scaling sweep). This sets the benchmark intensity and the baseline.
-2. **Approaches** — do you have specific ideas, or should I propose a set, and how wide? (your list · ~5 focused · ~10–20 wide net, prune hard).
-3. **What "best" means** — balanced/never cap a thread *(recommend)* · smoothness first (hold the refresh rate, UI thread sacred) · lowest CPU/battery · lowest memory — plus any hard limit ("<150MB", "must stay 120fps").
+Use the current implementation with the representative workload as the baseline for a fix. An empty screen can be a separate control for harness overhead; it does not do equivalent work and cannot establish an improvement to the feature.
 
-Then **show the saved benchmark settings, don't ask about speed.** Call **`get_benchmark_settings`** (pass `pages` = baseline + variant count) and read its plain-English line + time estimate back to the user, e.g. *"Using your saved profile: 5s/page, 3 runs each, reload between, ~4 min total."* Then proceed unless they want to change it.
-- One-off speed/runs change for *this* run → pass overrides to `run_benchmark_batch`.
-- "Always / save this" → call **`set_benchmark_settings`** to persist. Never silently overwrite their saved profile.
+When comparing approaches needs a harness, use a route whose parameters select isolated variants. Keep workload, visual output and interactions comparable. Include a way to open each variant for inspection. Follow the project's development-only route and build conventions; `__DEV__` guards alone do not prove a route or dependency is absent from the shipped bundle.
 
-## Step 2 — Scaffold the dev-only test harness
-- One **params-driven test route**: a query param selects which variant renders. **Default / no params = the baseline = nothing (or the minimal current impl) rendered** — the control that tells you the page's own floor.
-- A **dev-only "test pages" hub** (create it if missing), linked from a sensible spot (e.g. the profile/settings screen), listing every test route so the user can open and eyeball each. Add this route's link to it.
-- Gate it all behind `__DEV__` so it never ships.
-- Each variant is real code you build behind a param value. Keep variants isolated so a remount fully resets them (the benchmark bounces between pages to force this).
+Check that the target and bounce routes exist and navigation resets the intended state. A remount does not reset module state or persistent storage. If using `reloadBetweenCases`, confirm that `AutomationResumer` is mounted and that the app can resume the batch after reload.
 
-## Step 3 — Breadth: benchmark the wide net
-Call **`run_benchmark_batch`** with `targetRoute` = the test route and `cases` = baseline + one case per idea (each a `{ name, params }`). It inherits the saved settings; pass overrides only if the user asked. It navigates, records, ranks, and returns you to the origin screen when done.
+Start with a few candidates supported by the observed problem. Add variants when a result suggests a useful next experiment. Keep the original implementation available for comparison.
 
-## Step 4 — Visual gate (mandatory)
-Before trusting any numbers, tell the user: *"Open these → [hub link] + the routes. Which render correctly? Which to disqualify regardless of perf?"* Drop any variant that's visually wrong, no matter how fast.
+## Read settings and run the batch
 
-## Step 5 — Holistic analysis
-Read the `run_benchmark_batch` / `get_batch_report` output: the **Flags** column (⚠️ at-risk axes), **per-metric leaders**, and **Balanced (caps nothing)** list. Then synthesize for the user:
-- Favor the **Balanced** cases. Treat any **⚠️ UI thread / UI jank** flag as close to disqualifying — call it out explicitly with the risk ("drops frames → janky under load").
-- Don't reward a flagged-but-cheap case just because one number is low. Explain the trade-off.
-- Use `compare_reports` for a deep two-way diff (avg + p95) when two candidates are close.
+Call `get_benchmark_settings` with `pages` equal to the total case count, including the baseline, and the selected `deviceId`. Summarize the returned settings and time estimate. The tool reports either a saved device profile or defaults; do not describe defaults as the user's chosen settings.
 
-## Step 6 — Prune
-Drop the clear losers and the visually-wrong ones; keep the promising candidates (e.g. top 5 of 20). Tell the user what you kept and why (per-metric + flags), and confirm.
+Use per-run overrides for a temporary change. Call `set_benchmark_settings` only when the user has asked to persist settings. Explain relevant measurement conditions, including warmup, repeats, cooldown, case order and render instrumentation. Consistent settings help comparisons but do not eliminate measurement noise or thermal effects.
 
-## Step 7 — Depth: fork the survivors (binary-tree refine)
-For each survivor, **give its page its own additional params** — sub-variants exploring ideas *within* that approach (e.g. the Skia variant sprouts Skia-A/B/C). Re-run `run_benchmark_batch` over the sub-variants, visual-gate, analyze, prune. Recurse. New framing each round: *"optimize these survivors without losing visual quality."*
+Call `run_benchmark_batch` with `targetRoute`, `deviceId` and `cases`. Each case has a `name` and optional `params`; the first case is the baseline for deltas. The route must interpret those parameters. The call waits for completion or its wait cap, which can take minutes.
 
-## Step 8 — Cross-pollinate
-When two runs are good in *different* ways (A: great CPU but caps UI thread; B: balanced but pricier), **build a new candidate that combines their best tricks** (A's batching + B's throttling) and benchmark it. Learn from both instead of discarding either.
+Read the returned warnings, failures and partial-result note before comparing rows. A timed-out wait can leave runs saving or automation active; inspect `get_automation_status` before starting another batch. Do not count failed or missing cases as successful tests. Check the current screen afterward instead of assuming navigation restored it.
 
-## Step 9 — Stop (for this tier)
-When gains plateau on the current device, present the distilled candidate **with its trade-offs stated**, not as a bare "winner." Confirm with the user.
+## Check behavior and interpret measurements
 
-## Step 10 — Advance the ladder
-Don't call it "done" — call it "done for this rung," and recommend the next one explicitly:
-- Finished on the **iOS simulator** → *"Solid on the iOS sim. Next: bulk-test the top candidates on a real iOS device to confirm — real hardware can shift the ranking."*
-- Finished on a **real iOS device** → *"Confirmed on a real iPhone. Next: Android (sim, then device). Expect different and usually worse numbers — less RAM, slower GPU — likely needing Android-specific tweaks."*
-- Finished on the **Android simulator** → *"Good on the Android sim. Next: confirm on a real Android device."*
-- Finished on a **real Android device** → fully validated across the ladder; present the final per-platform results and any platform-specific code paths.
+Inspect visual behavior and the relevant interactions using available screenshots, UI tools and project checks. Ask the user when the required appearance is subjective or cannot be checked with available tools. Record unverified behavior explicitly. Exclude a visibly incorrect variant from performance recommendations, while retaining its result as evidence of what was tested.
 
-Carry the iOS winners into Android as the starting set, but re-benchmark everything — never assume an iOS result holds on Android.
+Compare the available UI/JS FPS, CPU, memory and jank measurements together. Check missing values before interpreting a low value or an absent warning. The report's per-metric leaders and `balanced` list are summaries of recorded data. `balanced` means no configured risk flag was triggered; missing measurements can also produce no flag. It does not establish that a case meets every performance requirement.
 
-## Downstream gates (ask only when reached — keep each tiny)
-- **Visual** (every round): which variants render correctly / disqualify.
-- **Prune**: "keep my picks (A, C, D), or adjust?"
-- **Fork**: "for [survivor], what sub-ideas — yours, or I propose ~N?"
-- **Combine**: "A capped the UI thread, B was balanced — try a hybrid?"
-- **Stop**: "gains are plateauing — lock in X, or keep distilling?"
+Use `get_batch_report` with a `batchId` to read a saved batch. Use `compare_reports` with `reportIdA` and `reportIdB` to compare two saved runs; report IDs are different from batch IDs. Inspect available averages, p95 values and render data in the context of the same workload. A lower wasted-render count alone does not prove a fix or an overall speed improvement.
 
-## Tool quick-reference
-- `list_devices` — confirm device + tools.
-- `get_benchmark_settings` / `set_benchmark_settings` — read (plain-English + estimate) / persist the saved profile.
-- `run_benchmark_batch` — the core measurement: case matrix → ranked trade-off report. Inherits saved settings; accepts per-run overrides.
-- `get_batch_report` / `compare_reports` — re-rank a past batch by id / deep two-way diff.
-- `call_action` with `toolId:"route-events"`, `action:"navigate"`, `params:{ path }` — move the app (e.g. to seed an origin or open a variant).
+Explain trade-offs against the user's requirements. For example, a candidate may use less memory while producing more frame drops. Repeat close or noisy comparisons before choosing between them. Do not translate CPU measurements into battery-life claims without separate evidence.
 
-## Keep context lean
-Infer before asking. Defer fork/combine questions until you reach those stages. Don't dump raw per-sample data — work from the ranked report. Summarize each round's decision in a line or two so the user can follow without re-reading tables.
+## Iterate and report
+
+Keep candidates that meet the behavior requirements and offer a useful measured trade-off. Refine a specific hypothesis or combine compatible changes, then rerun the same workload. Stay within the agreed scope and time budget; seek direction when a decision would materially change either.
+
+Stop when the requested issue is resolved with appropriate checks, the agreed budget is reached, or further measurements require unavailable hardware or input. Report the selected implementation, baseline, workload, device/build conditions, settings, observed differences, failures and remaining uncertainty. Distinguish completed checks from proposed follow-up tests. Validation on one device does not establish results for all devices on that platform.
+
+## Tool reference
+
+| Tool | Use |
+| --- | --- |
+| `list_devices` | Select the connected device and inspect its tools. |
+| `measure_renders` | Measure a supported interaction before and after a change. |
+| `get_benchmark_settings` / `set_benchmark_settings` | Read the profile and estimate, or explicitly persist settings. |
+| `run_benchmark_batch` / `get_automation_status` | Run the case matrix and inspect automation status. |
+| `get_batch_report` | Read a saved batch using its `batchId`. |
+| `compare_reports` | Compare saved runs using `reportIdA` and `reportIdB`. |
+| `navigate` | Open a supported app route using `path`. |
+
+Keep summaries focused on the decision and its evidence. Include report IDs so results can be revisited without pasting every sample into the conversation.