@buoy-gg/mcp 7.0.20 → 7.0.21

package/dist/{chunk-S5NQ6EUN.mjs → chunk-JQ5GZ4LG.mjs}

@@ -344,7 +344,7 @@ async function waitForBroker(url, attempts = 20) {
 var delay = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // src/version.ts
-var VERSION = "7.0.20" ? "7.0.20" : "0.0.0-dev";
+var VERSION = "7.0.21" ? "7.0.21" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -1254,7 +1254,7 @@ function registerEventsTools(server, sync) {
   server.registerTool(
     "get_events",
     {
-      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
+      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. Check this timeline BEFORE driving the UI to reproduce a bug \u2014 the failure is usually already recorded here. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
       inputSchema: {
         limit: z3.number().optional().describe("Most-recent N events to include. Default 25."),
         sources: z3.array(z3.string()).optional().describe('Only these sources. Coarse names accepted: "network", "redux", "react-query", "storage", "route", "render", "zustand", "jotai". Omit for all.'),
@@ -1649,7 +1649,7 @@ function registerStorageTools(server, sync) {
   server.registerTool(
     "get_storage",
     {
-      description: "Read the app's storage keys across ALL backends: AsyncStorage, MMKV (per instance), and Expo SecureStore. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out. Use for 'what's in storage / read this key'.",
+      description: "Read the app's storage keys across ALL backends: AsyncStorage, MMKV (per instance), and Expo SecureStore. Data wrong or missing after an app restart \u2192 read the persisted values here FIRST \u2014 the bug is usually a stale, missing, or malformed stored value, and reading it beats hunting for it in code. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out.",
       inputSchema: {
         pattern: z8.string().optional().describe("Only keys containing this substring (case-insensitive)."),
         includeValues: z8.boolean().optional().describe("Include each key's value (truncated). Default false (keys only)."),
@@ -1850,7 +1850,7 @@ function registerConsoleTools(server, sync) {
   server.registerTool(
     "get_console",
     {
-      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. Use for 'what's logging / any console errors'. For full args/stack of an entry, fall back to get_snapshot('console').",
+      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. App crashing or erroring \u2192 read this FIRST: it captures crashes and errors including FATAL uncaught JS errors (tagged [FATAL], hooked from RN's global error handler), so a dead app's last words are here, not in the code. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. For full args/stack of an entry, fall back to get_snapshot('console').",
       inputSchema: {
         level: z10.enum(["verbose", "info", "warning", "error"]).optional().describe("Minimum level to include (severity threshold). e.g. 'warning' = warnings + errors. Default all."),
         limit: z10.number().optional().describe("Most-recent N entries. Default 50."),
@@ -2192,7 +2192,7 @@ function registerNetworkTools(server, sync) {
   server.registerTool(
     "get_network_requests",
     {
-      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
+      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. API data wrong or calls failing \u2192 read the actual request+response bodies here instead of guessing from code; capture starts at app launch, so boot-time requests (session bootstrap, first queries) are included. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
       inputSchema: {
         limit: z12.number().optional().describe("Most-recent N requests. Default 25."),
         pattern: z12.string().optional().describe("Only requests whose URL contains this substring (case-insensitive)."),
@@ -3659,6 +3659,8 @@ function runInit(opts = {}) {
     upsertMcpConfig(path3.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
   }
   installSkills(skillSrcDir, cwd, done);
+  appendDebuggingGuide(path3.join(cwd, "CLAUDE.md"), cwd, done);
+  appendDebuggingGuide(path3.join(cwd, "AGENTS.md"), cwd, done);
   log("Buoy MCP installed:");
   for (const line of done) log("  \u2022 " + line);
   log("");
@@ -3805,6 +3807,49 @@ function upsertMcpConfig(file, key, entry, cwd, done) {
   fs3.writeFileSync(file, JSON.stringify(json3, null, 2) + "\n");
   done.push(`${existed ? "updated" : "added"} \`buoy\` in ${rel(file, cwd)}`);
 }
+var GUIDE_HEADING = "# Debugging with Buoy";
+var DEBUGGING_GUIDE = `${GUIDE_HEADING}
+
+This app's runtime is inspectable while it runs: the Buoy MCP tools read live
+state straight from the device. Route by symptom before reading source:
+
+- \`get_events\` \u2014 the universal activity timeline (network, state changes,
+  storage writes, routes, renders). Check it BEFORE driving the UI to
+  reproduce a bug \u2014 the failure is usually already recorded.
+- \`get_network_requests\` \u2014 API data wrong or calls failing \u2192 read the actual
+  request + response bodies instead of guessing from code. Boot-time requests
+  are captured too.
+- \`get_console\` \u2014 crashes and errors, including FATAL uncaught JS errors
+  (tagged \`[FATAL]\`).
+- \`get_storage\` \u2014 data wrong or missing after an app restart \u2192 read the
+  persisted values FIRST.
+- \`get_snapshot\` \u2014 full current state of any one tool when the compact views
+  aren't enough.
+
+Runtime facts beat guesses.
+`;
+function appendDebuggingGuide(file, cwd, done) {
+  let existing = "";
+  if (fs3.existsSync(file)) {
+    try {
+      existing = fs3.readFileSync(file, "utf8");
+    } catch {
+      done.push(`\u26A0 could not read ${rel(file, cwd)} \u2014 skipped the debugging guide`);
+      return;
+    }
+    if (existing.includes(GUIDE_HEADING)) {
+      done.push(`${rel(file, cwd)} already has the "${GUIDE_HEADING}" block`);
+      return;
+    }
+  }
+  const separator = existing === "" ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  try {
+    fs3.writeFileSync(file, existing + separator + DEBUGGING_GUIDE);
+    done.push(`${existing ? "appended" : "created"} "${GUIDE_HEADING}" block in ${rel(file, cwd)}`);
+  } catch {
+    done.push(`\u26A0 could not write ${rel(file, cwd)} \u2014 skipped the debugging guide`);
+  }
+}
 function installSkills(skillSrcDir, cwd, done) {
   if (!fs3.existsSync(skillSrcDir)) {
     done.push("\u26A0 no bundled skills found \u2014 skipped");

package/dist/cli.js

@@ -384,7 +384,7 @@ var import_node_os = __toESM(require("os"));
 var import_node_path = __toESM(require("path"));
 
 // src/version.ts
-var VERSION = "7.0.20" ? "7.0.20" : "0.0.0-dev";
+var VERSION = "7.0.21" ? "7.0.21" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -1290,7 +1290,7 @@ function registerEventsTools(server, sync) {
   server.registerTool(
     "get_events",
     {
-      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
+      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. Check this timeline BEFORE driving the UI to reproduce a bug \u2014 the failure is usually already recorded here. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
       inputSchema: {
         limit: import_zod3.z.number().optional().describe("Most-recent N events to include. Default 25."),
         sources: import_zod3.z.array(import_zod3.z.string()).optional().describe('Only these sources. Coarse names accepted: "network", "redux", "react-query", "storage", "route", "render", "zustand", "jotai". Omit for all.'),
@@ -1455,7 +1455,7 @@ function registerNetworkTools(server, sync) {
   server.registerTool(
     "get_network_requests",
     {
-      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
+      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. API data wrong or calls failing \u2192 read the actual request+response bodies here instead of guessing from code; capture starts at app launch, so boot-time requests (session bootstrap, first queries) are included. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
       inputSchema: {
         limit: import_zod4.z.number().optional().describe("Most-recent N requests. Default 25."),
         pattern: import_zod4.z.string().optional().describe("Only requests whose URL contains this substring (case-insensitive)."),
@@ -2172,7 +2172,7 @@ function registerStorageTools(server, sync) {
   server.registerTool(
     "get_storage",
     {
-      description: "Read the app's storage keys across ALL backends: AsyncStorage, MMKV (per instance), and Expo SecureStore. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out. Use for 'what's in storage / read this key'.",
+      description: "Read the app's storage keys across ALL backends: AsyncStorage, MMKV (per instance), and Expo SecureStore. Data wrong or missing after an app restart \u2192 read the persisted values here FIRST \u2014 the bug is usually a stale, missing, or malformed stored value, and reading it beats hunting for it in code. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out.",
       inputSchema: {
         pattern: import_zod9.z.string().optional().describe("Only keys containing this substring (case-insensitive)."),
         includeValues: import_zod9.z.boolean().optional().describe("Include each key's value (truncated). Default false (keys only)."),
@@ -2373,7 +2373,7 @@ function registerConsoleTools(server, sync) {
   server.registerTool(
     "get_console",
     {
-      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. Use for 'what's logging / any console errors'. For full args/stack of an entry, fall back to get_snapshot('console').",
+      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. App crashing or erroring \u2192 read this FIRST: it captures crashes and errors including FATAL uncaught JS errors (tagged [FATAL], hooked from RN's global error handler), so a dead app's last words are here, not in the code. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. For full args/stack of an entry, fall back to get_snapshot('console').",
       inputSchema: {
         level: import_zod11.z.enum(["verbose", "info", "warning", "error"]).optional().describe("Minimum level to include (severity threshold). e.g. 'warning' = warnings + errors. Default all."),
         limit: import_zod11.z.number().optional().describe("Most-recent N entries. Default 50."),
@@ -3691,6 +3691,8 @@ function runInit(opts = {}) {
     upsertMcpConfig(import_node_path3.default.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
   }
   installSkills(skillSrcDir, cwd, done);
+  appendDebuggingGuide(import_node_path3.default.join(cwd, "CLAUDE.md"), cwd, done);
+  appendDebuggingGuide(import_node_path3.default.join(cwd, "AGENTS.md"), cwd, done);
   log("Buoy MCP installed:");
   for (const line of done) log("  \u2022 " + line);
   log("");
@@ -3837,6 +3839,49 @@ function upsertMcpConfig(file, key, entry, cwd, done) {
   import_node_fs3.default.writeFileSync(file, JSON.stringify(json3, null, 2) + "\n");
   done.push(`${existed ? "updated" : "added"} \`buoy\` in ${rel(file, cwd)}`);
 }
+var GUIDE_HEADING = "# Debugging with Buoy";
+var DEBUGGING_GUIDE = `${GUIDE_HEADING}
+
+This app's runtime is inspectable while it runs: the Buoy MCP tools read live
+state straight from the device. Route by symptom before reading source:
+
+- \`get_events\` \u2014 the universal activity timeline (network, state changes,
+  storage writes, routes, renders). Check it BEFORE driving the UI to
+  reproduce a bug \u2014 the failure is usually already recorded.
+- \`get_network_requests\` \u2014 API data wrong or calls failing \u2192 read the actual
+  request + response bodies instead of guessing from code. Boot-time requests
+  are captured too.
+- \`get_console\` \u2014 crashes and errors, including FATAL uncaught JS errors
+  (tagged \`[FATAL]\`).
+- \`get_storage\` \u2014 data wrong or missing after an app restart \u2192 read the
+  persisted values FIRST.
+- \`get_snapshot\` \u2014 full current state of any one tool when the compact views
+  aren't enough.
+
+Runtime facts beat guesses.
+`;
+function appendDebuggingGuide(file, cwd, done) {
+  let existing = "";
+  if (import_node_fs3.default.existsSync(file)) {
+    try {
+      existing = import_node_fs3.default.readFileSync(file, "utf8");
+    } catch {
+      done.push(`\u26A0 could not read ${rel(file, cwd)} \u2014 skipped the debugging guide`);
+      return;
+    }
+    if (existing.includes(GUIDE_HEADING)) {
+      done.push(`${rel(file, cwd)} already has the "${GUIDE_HEADING}" block`);
+      return;
+    }
+  }
+  const separator = existing === "" ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  try {
+    import_node_fs3.default.writeFileSync(file, existing + separator + DEBUGGING_GUIDE);
+    done.push(`${existing ? "appended" : "created"} "${GUIDE_HEADING}" block in ${rel(file, cwd)}`);
+  } catch {
+    done.push(`\u26A0 could not write ${rel(file, cwd)} \u2014 skipped the debugging guide`);
+  }
+}
 function installSkills(skillSrcDir, cwd, done) {
   if (!import_node_fs3.default.existsSync(skillSrcDir)) {
     done.push("\u26A0 no bundled skills found \u2014 skipped");

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import {
   SyncClient,
   createMcpServer,
   runInit
-} from "./chunk-S5NQ6EUN.mjs";
+} from "./chunk-JQ5GZ4LG.mjs";
 
 // src/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/index.js

@@ -419,7 +419,7 @@ var import_node_os = __toESM(require("os"));
 var import_node_path = __toESM(require("path"));
 
 // src/version.ts
-var VERSION = "7.0.20" ? "7.0.20" : "0.0.0-dev";
+var VERSION = "7.0.21" ? "7.0.21" : "0.0.0-dev";
 var PACKAGE_NAME = "@buoy-gg/mcp";
 
 // src/update/checkForUpdate.ts
@@ -1325,7 +1325,7 @@ function registerEventsTools(server, sync) {
   server.registerTool(
     "get_events",
     {
-      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
+      description: "The UNIVERSAL, token-bounded activity reader for what's happening in the app across ALL Buoy tools. Check this timeline BEFORE driving the UI to reproduce a bug \u2014 the failure is usually already recorded here. The events tool aggregates every source \u2014 network requests, redux/zustand/jotai actions, react-query query/mutation updates, storage writes, route changes, renders \u2014 so filter to one with `sources`: ['network'] lists HTTP requests, ['redux'] dispatched actions, ['react-query'] query updates, ['storage'] writes, ['route'] navigation. Returns a compact one-line summary per event (source \xB7 status \xB7 title \xB7 timing) by DEFAULT \u2014 not the heavy raw payloads \u2014 so it's cheap. Re-call with includeData:true, a bigger limit, or specific sources only when you need detail. PREFER this over get_snapshot (and over reading source code) for any 'what happened' / 'show me the requests/actions' question; get_snapshot is the raw heavy current-state escape hatch.",
       inputSchema: {
         limit: import_zod3.z.number().optional().describe("Most-recent N events to include. Default 25."),
         sources: import_zod3.z.array(import_zod3.z.string()).optional().describe('Only these sources. Coarse names accepted: "network", "redux", "react-query", "storage", "route", "render", "zustand", "jotai". Omit for all.'),
@@ -1490,7 +1490,7 @@ function registerNetworkTools(server, sync) {
   server.registerTool(
     "get_network_requests",
     {
-      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
+      description: "List captured HTTP requests WITH their request ids, plus which ones are pinned/saved. API data wrong or calls failing \u2192 read the actual request+response bodies here instead of guessing from code; capture starts at app launch, so boot-time requests (session bootstrap, first queries) are included. Use this (not get_events) when you need to ACT on a request \u2014 every network action is keyed by the id, and get_events does not emit ids. Compact by default: one line per request (id \xB7 status \xB7 method \xB7 path \xB7 timing \xB7 size). Set flagged:'pinned'|'saved'|'any' to read the developer's KEPT requests \u2014 those are snapshots that outlive Clear, the 500-request cap and app restarts, so treat a pinned request as 'a human flagged this as the problem'. Filter with status:'errors' to go straight to failures, or `pattern` to match a URL substring. includeBodies:true adds truncated request/response payloads (heavier).",
       inputSchema: {
         limit: import_zod4.z.number().optional().describe("Most-recent N requests. Default 25."),
         pattern: import_zod4.z.string().optional().describe("Only requests whose URL contains this substring (case-insensitive)."),
@@ -2207,7 +2207,7 @@ function registerStorageTools(server, sync) {
   server.registerTool(
     "get_storage",
     {
-      description: "Read the app's storage keys across ALL backends: AsyncStorage, MMKV (per instance), and Expo SecureStore. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out. Use for 'what's in storage / read this key'.",
+      description: "Read the app's storage keys across ALL backends: AsyncStorage, MMKV (per instance), and Expo SecureStore. Data wrong or missing after an app restart \u2192 read the persisted values here FIRST \u2014 the bug is usually a stale, missing, or malformed stored value, and reading it beats hunting for it in code. Compact by DEFAULT \u2014 keys only \u2014 so it's token-cheap; pass includeValues:true for the values (truncated), or a `pattern` substring to narrow. Buoy's own internal keys are already filtered out.",
       inputSchema: {
         pattern: import_zod9.z.string().optional().describe("Only keys containing this substring (case-insensitive)."),
         includeValues: import_zod9.z.boolean().optional().describe("Include each key's value (truncated). Default false (keys only)."),
@@ -2408,7 +2408,7 @@ function registerConsoleTools(server, sync) {
   server.registerTool(
     "get_console",
     {
-      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. Use for 'what's logging / any console errors'. For full args/stack of an entry, fall back to get_snapshot('console').",
+      description: "Read the app's captured console logs (console.log/warn/error/\u2026) as a compact tail \u2014 time \xB7 level \xB7 message. App crashing or erroring \u2192 read this FIRST: it captures crashes and errors including FATAL uncaught JS errors (tagged [FATAL], hooked from RN's global error handler), so a dead app's last words are here, not in the code. Token-cheap (uses each entry's pre-rendered message, not raw args). Filter by minimum level (e.g. level:'warning' for warnings+errors) or a message substring. For full args/stack of an entry, fall back to get_snapshot('console').",
       inputSchema: {
         level: import_zod11.z.enum(["verbose", "info", "warning", "error"]).optional().describe("Minimum level to include (severity threshold). e.g. 'warning' = warnings + errors. Default all."),
         limit: import_zod11.z.number().optional().describe("Most-recent N entries. Default 50."),
@@ -3726,6 +3726,8 @@ function runInit(opts = {}) {
     upsertMcpConfig(import_node_path3.default.join(cwd, ".vscode", "mcp.json"), "servers", entry, cwd, done);
   }
   installSkills(skillSrcDir, cwd, done);
+  appendDebuggingGuide(import_node_path3.default.join(cwd, "CLAUDE.md"), cwd, done);
+  appendDebuggingGuide(import_node_path3.default.join(cwd, "AGENTS.md"), cwd, done);
   log("Buoy MCP installed:");
   for (const line of done) log("  \u2022 " + line);
   log("");
@@ -3872,6 +3874,49 @@ function upsertMcpConfig(file, key, entry, cwd, done) {
   import_node_fs3.default.writeFileSync(file, JSON.stringify(json3, null, 2) + "\n");
   done.push(`${existed ? "updated" : "added"} \`buoy\` in ${rel(file, cwd)}`);
 }
+var GUIDE_HEADING = "# Debugging with Buoy";
+var DEBUGGING_GUIDE = `${GUIDE_HEADING}
+
+This app's runtime is inspectable while it runs: the Buoy MCP tools read live
+state straight from the device. Route by symptom before reading source:
+
+- \`get_events\` \u2014 the universal activity timeline (network, state changes,
+  storage writes, routes, renders). Check it BEFORE driving the UI to
+  reproduce a bug \u2014 the failure is usually already recorded.
+- \`get_network_requests\` \u2014 API data wrong or calls failing \u2192 read the actual
+  request + response bodies instead of guessing from code. Boot-time requests
+  are captured too.
+- \`get_console\` \u2014 crashes and errors, including FATAL uncaught JS errors
+  (tagged \`[FATAL]\`).
+- \`get_storage\` \u2014 data wrong or missing after an app restart \u2192 read the
+  persisted values FIRST.
+- \`get_snapshot\` \u2014 full current state of any one tool when the compact views
+  aren't enough.
+
+Runtime facts beat guesses.
+`;
+function appendDebuggingGuide(file, cwd, done) {
+  let existing = "";
+  if (import_node_fs3.default.existsSync(file)) {
+    try {
+      existing = import_node_fs3.default.readFileSync(file, "utf8");
+    } catch {
+      done.push(`\u26A0 could not read ${rel(file, cwd)} \u2014 skipped the debugging guide`);
+      return;
+    }
+    if (existing.includes(GUIDE_HEADING)) {
+      done.push(`${rel(file, cwd)} already has the "${GUIDE_HEADING}" block`);
+      return;
+    }
+  }
+  const separator = existing === "" ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  try {
+    import_node_fs3.default.writeFileSync(file, existing + separator + DEBUGGING_GUIDE);
+    done.push(`${existing ? "appended" : "created"} "${GUIDE_HEADING}" block in ${rel(file, cwd)}`);
+  } catch {
+    done.push(`\u26A0 could not write ${rel(file, cwd)} \u2014 skipped the debugging guide`);
+  }
+}
 function installSkills(skillSrcDir, cwd, done) {
   if (!import_node_fs3.default.existsSync(skillSrcDir)) {
     done.push("\u26A0 no bundled skills found \u2014 skipped");

package/dist/index.mjs

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buoy-gg/mcp",
   "mcpName": "io.github.buoy-gg/mcp",
-  "version": "7.0.20",
+  "version": "7.0.21",
   "description": "MCP server for Buoy devtools — lets any LLM copilot drive Buoy tools (perf-monitor benchmarks, etc.) over the devtool sync protocol",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -31,7 +31,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "socket.io-client": "^4.8.1",
     "zod": "^3.25.0",
-    "@buoy-gg/sync-broker": "^7.0.20"
+    "@buoy-gg/sync-broker": "^7.0.21"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",