beecork 2.8.0 → 2.8.2

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { writeFile as writeFile5, chmod as chmod4 } from "node:fs/promises";
+import { writeFile as writeFile6, chmod as chmod4 } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 
 // src/paths.ts
@@ -187,10 +187,10 @@ async function findShadowingInstalls() {
   const names = process.platform === "win32" ? ["beecork.cmd", "beecork"] : ["beecork"];
   const seenRoots = /* @__PURE__ */ new Set([running]);
   const others = [];
-  for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
+  for (const dir2 of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
     for (const name of names) {
       try {
-        const bin = join(dir, name);
+        const bin = join(dir2, name);
         const root = dirname(dirname(await realpath(bin)));
         if (seenRoots.has(root)) continue;
         seenRoots.add(root);
@@ -241,9 +241,9 @@ async function checkForUpdate(current) {
     void fetchLatest().then(async (latest) => {
       if (!latest) return;
       try {
-        const file = cacheFile();
-        await mkdir(dirname(file), { recursive: true });
-        await writeFile(file, JSON.stringify({ checkedAt: Date.now(), latest }), "utf8");
+        const file2 = cacheFile();
+        await mkdir(dirname(file2), { recursive: true });
+        await writeFile(file2, JSON.stringify({ checkedAt: Date.now(), latest }), "utf8");
       } catch {
       }
     });
@@ -615,7 +615,7 @@ function printBanner(model, version, sources) {
 }
 
 // src/agent.ts
-import { readFile as readFile5 } from "node:fs/promises";
+import { readFile as readFile6 } from "node:fs/promises";
 
 // src/input.ts
 import { emitKeypressEvents } from "node:readline";
@@ -635,10 +635,10 @@ function inputLayout(text, before, promptW, cols2) {
   const curPhysCol = curCol % c;
   return { totalPhys, curPhysRow, curPhysCol };
 }
-function moveVertIndex(buf2, cur2, dir) {
+function moveVertIndex(buf2, cur2, dir2) {
   const lines = buf2.split("\n");
   const { row, col } = rowColOf(buf2.slice(0, cur2));
-  const target = row + dir;
+  const target = row + dir2;
   if (target < 0 || target >= lines.length) return null;
   let idx = 0;
   for (let i = 0; i < target; i++) idx += lines[i].length + 1;
@@ -896,8 +896,8 @@ function readPrompt(opts) {
         if (isPrintableCodePoint(str.codePointAt(0))) insert2(str);
       }
     }
-    function moveVert(dir) {
-      const idx = moveVertIndex(buf2, cur2, dir);
+    function moveVert(dir2) {
+      const idx = moveVertIndex(buf2, cur2, dir2);
       if (idx === null) return;
       cur2 = idx;
       render2();
@@ -1195,11 +1195,11 @@ function createMarkdownStream(write) {
 }
 
 // src/tools.ts
-import { readFile as readFile3, writeFile as writeFile2, appendFile, readdir as readdir2, mkdir as mkdir2, stat, rename, chmod } from "node:fs/promises";
+import { readFile as readFile4, writeFile as writeFile3, appendFile, readdir as readdir2, mkdir as mkdir4, stat, rename, chmod } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { createInterface as createLineReader } from "node:readline";
-import { spawn as spawn3 } from "node:child_process";
-import { join as join3 } from "node:path";
+import { spawn as spawn4 } from "node:child_process";
+import { join as join5 } from "node:path";
 import { lookup as dnsLookup } from "node:dns";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
@@ -1338,10 +1338,10 @@ async function loadSkills() {
     [join2(process.cwd(), ".beecork", "skills"), "project"],
     [bundledDir, "bundled"]
   ];
-  for (const [dir, source] of dirs) {
+  for (const [dir2, source] of dirs) {
     let entries;
     try {
-      entries = await readdir(dir, { withFileTypes: true });
+      entries = await readdir(dir2, { withFileTypes: true });
     } catch {
       continue;
     }
@@ -1354,10 +1354,10 @@ async function loadSkills() {
         continue;
       }
       try {
-        const raw = (await readFile2(join2(dir, e.name), "utf8")).trim();
+        const raw = (await readFile2(join2(dir2, e.name), "utf8")).trim();
         if (!raw) continue;
         const { description, modelInvocable, body } = parseSkill(raw);
-        registry.set(name, { name, content: body, description, modelInvocable, path: join2(dir, e.name), source });
+        registry.set(name, { name, content: body, description, modelInvocable, path: join2(dir2, e.name), source });
       } catch {
       }
     }
@@ -1678,11 +1678,127 @@ function decodeEntities(s) {
   });
 }
 
+// src/skeleton.ts
+import { spawn as spawn3 } from "node:child_process";
+import { mkdir as mkdir2 } from "node:fs/promises";
+import { join as join3, dirname as dirname3 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { homedir as homedir5 } from "node:os";
+var port = () => Number(process.env.BEECORK_SKELETON_PORT) || 8317;
+var skeletonUrl = () => process.env.BEECORK_DEV_SIGNALS_URL || `http://localhost:${port()}`;
+var managedExternally = () => !!process.env.BEECORK_DEV_SIGNALS_URL;
+var skeletonHome = () => process.env.BEECORK_SKELETON_HOME || join3(homedir5(), ".beecork", "skeleton");
+var bridgeScript = () => join3(dirname3(fileURLToPath3(import.meta.url)), "..", "skeleton", "bridge.mjs");
+async function probe(url = skeletonUrl(), timeoutMs = 600) {
+  try {
+    const res = await fetch(`${url}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (res.ok) {
+      const j = await res.json();
+      if (j && j.skeleton === true) return "up";
+    }
+  } catch {
+    return "down";
+  }
+  try {
+    const res = await fetch(`${url}/signals?limit=1`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (res.ok) {
+      const j = await res.json();
+      if (Array.isArray(j && j.signals)) return "up";
+    }
+  } catch {
+  }
+  return "foreign";
+}
+var inFlight = null;
+function ensureBridge() {
+  if (inFlight) return inFlight;
+  inFlight = doEnsure().finally(() => {
+    inFlight = null;
+  });
+  return inFlight;
+}
+async function doEnsure() {
+  if (managedExternally()) return { up: false, reason: "external" };
+  const first = await probe();
+  if (first === "up") return { up: true };
+  if (first === "foreign") return { up: false, reason: "foreign-port" };
+  let pid;
+  try {
+    const home = skeletonHome();
+    await mkdir2(home, { recursive: true });
+    const child = spawn3(process.execPath, [bridgeScript()], {
+      cwd: home,
+      env: { ...process.env, BEECORK_SKELETON_HOME: home, BEECORK_SKELETON_PORT: String(port()) },
+      detached: true,
+      stdio: "ignore"
+      // fire-and-forget; it logs to no one, which is fine
+    });
+    child.on("error", () => {
+    });
+    pid = child.pid;
+    child.unref();
+  } catch {
+    return { up: false, reason: "spawn-failed" };
+  }
+  for (let i = 0; i < 10; i++) {
+    await new Promise((r) => setTimeout(r, 200));
+    if (await probe() === "up") return { up: true, started: true, pid };
+  }
+  return { up: false, started: true, pid, reason: "spawn-failed" };
+}
+
+// src/projectSites.ts
+import { readFile as readFile3, writeFile as writeFile2, mkdir as mkdir3 } from "node:fs/promises";
+import { join as join4 } from "node:path";
+var dir = () => join4(process.cwd(), ".beecork");
+var file = () => join4(dir(), "skeleton.json");
+function toOrigin(input) {
+  const s = String(input || "").trim();
+  if (!s) return "";
+  const withScheme = /^https?:\/\//i.test(s) ? s : "http://" + s;
+  try {
+    const o = new URL(withScheme).origin;
+    return o === "null" ? "" : o;
+  } catch {
+    return "";
+  }
+}
+function isLoopbackOrigin(origin) {
+  const o = toOrigin(origin);
+  if (!o) return false;
+  let host;
+  try {
+    host = new URL(o).hostname;
+  } catch {
+    return false;
+  }
+  host = host.replace(/^\[|\]$/g, "").toLowerCase();
+  return host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0" || host === "::1" || /^127\./.test(host);
+}
+async function loadProjectOrigins() {
+  try {
+    const cfg = JSON.parse(await readFile3(file(), "utf8"));
+    if (!Array.isArray(cfg.origins)) return [];
+    return [...new Set(cfg.origins.map(toOrigin).filter(Boolean))];
+  } catch {
+    return [];
+  }
+}
+async function addProjectOrigin(origin) {
+  const o = toOrigin(origin);
+  if (!o || isLoopbackOrigin(o)) return false;
+  const cur2 = await loadProjectOrigins();
+  if (cur2.includes(o)) return false;
+  await mkdir3(dir(), { recursive: true });
+  await writeFile2(file(), JSON.stringify({ origins: [...cur2, o] }, null, 2) + "\n");
+  return true;
+}
+
 // src/tools.ts
 function runShell(command, opts) {
   return new Promise((resolve2, reject) => {
     const unix2 = process.platform !== "win32";
-    const child = spawn3(command, { shell: true, detached: unix2, stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn4(command, { shell: true, detached: unix2, stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "", stderr = "", outLen = 0, errLen = 0, timedOut = false, aborted = false;
     let settled = false, exitCode = null;
     const kill = () => {
@@ -1749,7 +1865,7 @@ function runShell(command, opts) {
 var fail = (verb, err) => `Error ${verb}: ${err.message}`;
 async function atomicWrite(abs, content) {
   const tmp = `${abs}.beecork-${process.pid}.tmp`;
-  await writeFile2(tmp, content, "utf8");
+  await writeFile3(tmp, content, "utf8");
   try {
     await chmod(tmp, (await stat(abs)).mode);
   } catch {
@@ -1778,8 +1894,8 @@ function lineOffsets(text) {
   for (let i = 0; i < text.length; i++) if (text[i] === "\n") starts.push(i + 1);
   return starts;
 }
-function matchWhitespace(file, oldText, newText) {
-  const fileLines = file.split("\n");
+function matchWhitespace(file2, oldText, newText) {
+  const fileLines = file2.split("\n");
   const oldLines = oldText.split("\n");
   const n = oldLines.length;
   const trim = (l) => l.trim();
@@ -1825,15 +1941,15 @@ function matchWhitespace(file, oldText, newText) {
     if (mode === "strip") return l.startsWith(shift) ? l.slice(shift.length) : l;
     return l;
   }).join("\n");
-  const offs = lineOffsets(file);
+  const offs = lineOffsets(file2);
   const start = offs[s];
-  const end = s + n < offs.length ? offs[s + n] - 1 : file.length;
+  const end = s + n < offs.length ? offs[s + n] - 1 : file2.length;
   return { ok: true, start, end, after: reindented, healedVia: "whitespace" };
 }
-function closestRegion(file, oldText) {
+function closestRegion(file2, oldText) {
   const anchor = oldText.split("\n").map((l) => l.trim()).find((l) => l !== "");
   if (!anchor) return void 0;
-  const fileLines = file.split("\n");
+  const fileLines = file2.split("\n");
   const fmt = (i) => `${String(i + 1).padStart(5)}  ${fileLines[i]}`;
   const exact = [];
   for (let i = 0; i < fileLines.length && exact.length < 3; i++) {
@@ -1854,23 +1970,23 @@ function closestRegion(file, oldText) {
   }
   return best >= 0 && bestScore >= Math.max(2, Math.ceil(words.length / 2)) ? fmt(best) : void 0;
 }
-function resolveEdit(file, oldText, newText) {
+function resolveEdit(file2, oldText, newText) {
   if (oldText === "") return { ok: false, reason: "not_found" };
-  const exact = allIndexOf(file, oldText);
+  const exact = allIndexOf(file2, oldText);
   if (exact.length === 1) return { ok: true, start: exact[0], end: exact[0] + oldText.length, after: newText, healedVia: "exact" };
   if (exact.length > 1) return { ok: false, reason: "ambiguous", count: exact.length };
   const strippedOld = stripReadPrefix(oldText);
   if (strippedOld !== null && strippedOld !== oldText) {
-    const hits = allIndexOf(file, strippedOld);
+    const hits = allIndexOf(file2, strippedOld);
     if (hits.length === 1) {
       const strippedNew = newText.split("\n").map((l) => l.replace(READ_PREFIX, "")).join("\n");
       return { ok: true, start: hits[0], end: hits[0] + strippedOld.length, after: strippedNew, healedVia: "prefix" };
     }
     if (hits.length > 1) return { ok: false, reason: "ambiguous", count: hits.length };
   }
-  const ws = matchWhitespace(file, oldText, newText);
+  const ws = matchWhitespace(file2, oldText, newText);
   if (ws) return ws;
-  return { ok: false, reason: "not_found", closest: closestRegion(file, oldText) };
+  return { ok: false, reason: "not_found", closest: closestRegion(file2, oldText) };
 }
 var todos = [];
 function httpGet(rawUrl, maxBytes, signal) {
@@ -1964,7 +2080,7 @@ async function walkTree(abs, prefix, items, cap) {
     const e = kept[i];
     const last = i === kept.length - 1;
     items.push({ prefix: prefix + (last ? "\u2514\u2500 " : "\u251C\u2500 "), name: e.name + (e.isDirectory() ? "/" : ""), isDir: e.isDirectory() });
-    if (e.isDirectory()) await walkTree(join3(abs, e.name), prefix + (last ? "   " : "\u2502  "), items, cap);
+    if (e.isDirectory()) await walkTree(join5(abs, e.name), prefix + (last ? "   " : "\u2502  "), items, cap);
   }
 }
 function parseRange(args, defLimit) {
@@ -1994,14 +2110,13 @@ async function readLineWindow(abs, offset1, limit) {
   }
   return { lines, startLine: start + 1, hasMore, empty: i === 0 };
 }
-var DEV_SIGNALS_SETUP = `The browser link isn't connected yet (nothing is responding on localhost:8317).
+var EXTENSION_STEPS = `1. Load the extension: Chrome \u2192 chrome://extensions \u2192 turn on "Developer mode" \u2192 "Load unpacked" \u2192 select the beecork-extension/extension folder, and pin the icon.
+2. Click the icon (it auto-connects \u2014 no token to paste), tick "Capture enabled", open the app in a tab, and click "Pair this site".`;
+var DEV_SIGNALS_SETUP = `The browser link isn't connected yet.
 
-This is "Beecork Skeleton" \u2014 a Chrome extension that sends the app's console errors and failed network requests to me, so I can see what the browser sees instead of guessing. One-time, local-only setup (no account, no signup).
+This is "Beecork Skeleton" \u2014 a Chrome extension that streams the app's console errors and failed network requests to me, so I see what the browser sees instead of guessing. beecork runs the local inbox for you automatically; the only one-time step is loading the extension (local-only, no account):
 
-Walk the user through connecting it:
-1. Start the local inbox: run \`node bridge/server.mjs\` in the beecork-extension folder, and leave it running.
-2. Load the extension: Chrome \u2192 chrome://extensions \u2192 turn on "Developer mode" \u2192 "Load unpacked" \u2192 select the beecork-extension/extension folder. Pin the icon.
-3. Click the icon (it auto-connects), tick "Capture enabled", open the app in a tab, and click "Pair this site".
+` + EXTENSION_STEPS + `
 
 Then call read_dev_signals again. Full step-by-step + troubleshooting is in the "browser-signals" skill.`;
 var toolDefs = [
@@ -2098,7 +2213,7 @@ var toolDefs = [
       const MAX = config.searchMaxResults;
       const deadline = Date.now() + config.searchTimeoutMs;
       let truncated = false;
-      async function walk(dir) {
+      async function walk(dir2) {
         if (results.length >= MAX) return;
         if (Date.now() > deadline) {
           truncated = true;
@@ -2106,7 +2221,7 @@ var toolDefs = [
         }
         let entries;
         try {
-          entries = await readdir2(dir, { withFileTypes: true });
+          entries = await readdir2(dir2, { withFileTypes: true });
         } catch {
           return;
         }
@@ -2117,7 +2232,7 @@ var toolDefs = [
             return;
           }
           if (IGNORE.has(e.name)) continue;
-          const full = `${dir}/${e.name}`;
+          const full = `${dir2}/${e.name}`;
           if (e.isDirectory()) {
             await walk(full);
           } else if (e.isFile()) {
@@ -2126,7 +2241,7 @@ var toolDefs = [
             if (info && info.size > config.searchMaxFileBytes) continue;
             let lines;
             try {
-              lines = (await readFile3(full, "utf8")).split("\n");
+              lines = (await readFile4(full, "utf8")).split("\n");
             } catch {
               continue;
             }
@@ -2194,7 +2309,7 @@ var toolDefs = [
     run: async (args) => {
       try {
         const { abs } = resolveInRoot(String(args.path ?? "."));
-        const original = await readFile3(abs, "utf8");
+        const original = await readFile4(abs, "utf8");
         const res = resolveEdit(original, String(args.old_text ?? ""), String(args.new_text ?? ""));
         if (!res.ok) {
           if (res.reason === "ambiguous") {
@@ -2397,21 +2512,21 @@ ${list}`;
     },
     run: async (args) => {
       try {
-        const dir = join3(process.cwd(), ".beecork");
-        await mkdir2(dir, { recursive: true });
-        const file = join3(dir, "memory.md");
+        const dir2 = join5(process.cwd(), ".beecork");
+        await mkdir4(dir2, { recursive: true });
+        const file2 = join5(dir2, "memory.md");
         const fact = String(args.fact).trim();
         if (!fact) return 'Error: remember needs a non-empty "fact".';
         let current = "";
         try {
-          current = await readFile3(file, "utf8");
+          current = await readFile4(file2, "utf8");
         } catch {
         }
         if (current.length + fact.length + 3 > config.memoryMaxChars) {
           return `Error: memory is at its ${config.memoryMaxChars}-char budget. Consolidate first: read .beecork/memory.md, merge duplicate/overlapping lines and drop anything stale or no-longer-true, write_file the shorter version back, then call remember again with this fact.`;
         }
-        if (!current) await writeFile2(file, "# beecork memory\n\n", "utf8");
-        await appendFile(file, `- ${fact}
+        if (!current) await writeFile3(file2, "# beecork memory\n\n", "utf8");
+        await appendFile(file2, `- ${fact}
 `, "utf8");
         return `Remembered: ${fact}`;
       } catch (err) {
@@ -2512,37 +2627,51 @@ ${skill.content}`;
   },
   {
     name: "read_dev_signals",
-    description: "Read the browser's recent console errors and failed network requests for the user's app (localhost or production), captured live by the Beecork Skeleton extension \u2014 so you can SEE what's actually happening instead of guessing. Call this whenever the user reports a bug a browser would surface (blank page, broken button, failed save, a 500, a visual glitch). If it isn't connected yet it returns setup steps to relay to the user. Pull on demand; don't spam it.",
+    description: "Read the browser's recent console errors and failed network requests for the user's app (localhost or production), captured live by the Beecork Skeleton extension \u2014 so you can SEE what's actually happening instead of guessing. Call this whenever the user reports a bug a browser would surface (blank page, broken button, failed save, a 500, a visual glitch). If it isn't connected yet it returns setup steps to relay to the user. Pull on demand; don't spam it. The inbox is SHARED across projects, so pass `origin` (this project's site, e.g. its dev URL or production URL) to see only THIS app's signals \u2014 otherwise you may get other apps' noise too.",
     parameters: {
       type: "object",
       properties: {
         kind: { type: "string", description: 'Filter: "network", "console", "pageError", "log", or "all" (default all).' },
         since_minutes: { type: "number", description: "Only signals from the last N minutes (optional)." },
-        limit: { type: "number", description: "Max signals to return (default 30, max 200)." }
+        limit: { type: "number", description: "Max signals to return (default 30, max 200)." },
+        origin: { type: "string", description: "Scope to one or more sites (comma-separated for several frontends), e.g. http://localhost:8000 or https://app.example.com. Defaults to this project's remembered production site(s) if set; pass localhost explicitly since dev ports aren't remembered." }
       },
       required: []
     },
     run: async (args, signal) => {
-      const base = process.env.BEECORK_DEV_SIGNALS_URL || "http://localhost:8317";
+      const ens = await ensureBridge().catch(() => ({ up: false, reason: "spawn-failed" }));
+      const base = skeletonUrl();
       const kind = args.kind ? String(args.kind) : "";
       const limit = Math.min(Math.max(Number(args.limit) || 30, 1), 200);
       const sinceMin = Number(args.since_minutes) || 0;
-      const params = new URLSearchParams({ limit: String(limit) });
+      const explicit = args.origin ? String(args.origin).split(",").map((s) => toOrigin(s)).filter(Boolean) : [];
+      const scope = explicit.length ? explicit : await loadProjectOrigins();
+      const params = new URLSearchParams({ limit: String(scope.length ? Math.min(200, limit * 4) : limit) });
       if (kind && kind !== "all") params.set("kind", kind);
       if (sinceMin > 0) params.set("since", String(Date.now() - sinceMin * 6e4));
+      if (scope.length) params.set("origin", scope.join(","));
       const timeout = AbortSignal.timeout(Math.min(config.webTimeoutMs, 5e3));
       let data;
       try {
         const res = await fetch(`${base}/signals?${params}`, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
-        if (!res.ok) return `The browser link responded with HTTP ${res.status}. The bridge may be unhealthy \u2014 try restarting it (node bridge/server.mjs).`;
+        if (!res.ok) return `The browser link responded with HTTP ${res.status}. The inbox may be unhealthy \u2014 I'll try to start a fresh one on the next call.`;
         data = await res.json();
       } catch {
+        if (ens.reason === "foreign-port") return `Another program is using the browser-link inbox port, so I couldn't start it. Free that port (or set BEECORK_DEV_SIGNALS_URL to a different inbox) and try again.`;
         return DEV_SIGNALS_SETUP;
       }
       const now = Date.now();
-      const signals = (data.signals ?? []).filter((s) => s && s.kind !== "watch");
+      let signals = (data.signals ?? []).filter((s) => s && s.kind !== "watch");
+      if (scope.length) signals = signals.filter((s) => scope.some((o) => String(s.page || s.url || "").startsWith(o)));
+      signals = signals.slice(-limit);
+      const scopeLabel = scope.length ? ` from ${scope.join(", ")}` : "";
       if (signals.length === 0) {
-        return `The browser link is connected, but no ${kind && kind !== "all" ? `"${kind}" ` : ""}signals were captured${sinceMin ? ` in the last ${sinceMin} min` : ""}. The watched tab just hasn't hit the error yet \u2014 reproduce the issue in the browser (or open the app), then call this again.`;
+        return `The inbox is running${ens.started ? " (I just started it)" : ""}, but no ${kind && kind !== "all" ? `"${kind}" ` : ""}signals${scopeLabel} were captured${sinceMin ? ` in the last ${sinceMin} min` : ""} yet.
+
+If the Beecork Skeleton extension isn't loaded yet, connect it:
+${EXTENSION_STEPS}
+
+Already connected? Reproduce the issue in the browser (or open the app), then call read_dev_signals again.`;
       }
       const ago2 = (ts) => ts ? `${Math.max(0, Math.round((now - ts) / 1e3))}s ago` : "";
       const lines = signals.map((s) => {
@@ -2550,8 +2679,15 @@ ${skill.content}`;
         const text = String(s.text ?? "").replace(/\s+/g, " ").slice(0, 300);
         return `[${s.kind}] ${text}${s.url ? `  @ ${s.url}` : ""}  (${ago2(s.ts)})`;
       });
-      return `${signals.length} browser signal(s), newest last:
-${lines.join("\n")}`;
+      let hint = "";
+      if (!scope.length) {
+        const distinct = [...new Set(signals.map((s) => toOrigin(String(s.page || s.url || ""))).filter(Boolean))];
+        if (distinct.length > 1) hint = `
+
+(These span ${distinct.length} sites: ${distinct.join(", ")}. To see only THIS project's, pass origin:"<its site>" \u2014 or call watch_site once and I'll remember it for this folder.)`;
+      }
+      return `${signals.length} browser signal(s)${scopeLabel}, newest last:
+${lines.join("\n")}${hint}`;
     }
   },
   {
@@ -2566,7 +2702,9 @@ ${lines.join("\n")}`;
       required: ["url"]
     },
     run: async (args, signal) => {
-      const base = process.env.BEECORK_DEV_SIGNALS_URL || "http://localhost:8317";
+      await ensureBridge().catch(() => {
+      });
+      const base = skeletonUrl();
       let origin;
       try {
         origin = new URL(String(args.url ?? "")).origin;
@@ -2586,7 +2724,9 @@ ${lines.join("\n")}`;
       } catch {
         return DEV_SIGNALS_SETUP;
       }
-      return `Requested watching ${origin} for ${minutes} min. If the user has approved that site in the extension, it will start capturing shortly \u2014 have them reproduce the issue in a tab on ${origin} (or open it), then call read_dev_signals. If nothing shows up, the site isn't approved yet: ask the user to open it and click "Pair this site" in the Beecork Skeleton popup.`;
+      const remembered = await addProjectOrigin(origin).catch(() => false);
+      const memo = remembered ? ` I'll remember ${origin} as this project's site, so read_dev_signals here now scopes to it automatically.` : "";
+      return `Requested watching ${origin} for ${minutes} min.${memo} If the user has approved that site in the extension, it will start capturing shortly \u2014 have them reproduce the issue in a tab on ${origin} (or open it), then call read_dev_signals. If nothing shows up, the site isn't approved yet: ask the user to open it and click "Pair this site" in the Beecork Skeleton popup.`;
     }
   }
 ];
@@ -2951,49 +3091,49 @@ ${summary}` }, ...recent];
 }
 
 // src/memory.ts
-import { readFile as readFile4, writeFile as writeFile3, readdir as readdir3, mkdir as mkdir3, chmod as chmod2, rename as rename2, unlink } from "node:fs/promises";
-import { homedir as homedir5 } from "node:os";
-import { join as join4, dirname as dirname3 } from "node:path";
+import { readFile as readFile5, writeFile as writeFile4, readdir as readdir3, mkdir as mkdir5, chmod as chmod2, rename as rename2, unlink } from "node:fs/promises";
+import { homedir as homedir6 } from "node:os";
+import { join as join6, dirname as dirname4 } from "node:path";
 var BEECORK = ".beecork";
 function ancestorDirs() {
-  const home = homedir5();
+  const home = homedir6();
   const dirs = [];
-  let dir = process.cwd();
-  while (dir !== home && dir !== dirname3(dir)) {
-    dirs.push(dir);
-    dir = dirname3(dir);
+  let dir2 = process.cwd();
+  while (dir2 !== home && dir2 !== dirname4(dir2)) {
+    dirs.push(dir2);
+    dir2 = dirname4(dir2);
   }
   return dirs.reverse();
 }
 function corkPaths() {
-  return [join4(homedir5(), BEECORK, "cork.md"), ...ancestorDirs().map((d) => join4(d, "cork.md"))];
+  return [join6(homedir6(), BEECORK, "cork.md"), ...ancestorDirs().map((d) => join6(d, "cork.md"))];
 }
 function beecorkPaths(name) {
-  return [join4(homedir5(), BEECORK, name), ...ancestorDirs().map((d) => join4(d, BEECORK, name))];
+  return [join6(homedir6(), BEECORK, name), ...ancestorDirs().map((d) => join6(d, BEECORK, name))];
 }
 function standardInstructionPaths() {
-  return ancestorDirs().flatMap((d) => [join4(d, "AGENTS.md"), join4(d, "CLAUDE.md")]);
+  return ancestorDirs().flatMap((d) => [join6(d, "AGENTS.md"), join6(d, "CLAUDE.md")]);
 }
 async function loadInstructions() {
-  const home = homedir5();
-  const homeBeecork = join4(home, ".beecork");
+  const home = homedir6();
+  const homeBeecork = join6(home, ".beecork");
   const trusted = [];
   const project = [];
   const sources = [];
   const MAX_FILE = 8e3;
   const MAX_TOTAL = 24e3;
   let total = 0;
-  for (const file of [...corkPaths(), ...standardInstructionPaths(), ...beecorkPaths("memory.md")]) {
+  for (const file2 of [...corkPaths(), ...standardInstructionPaths(), ...beecorkPaths("memory.md")]) {
     try {
-      let content = (await readFile4(file, "utf8")).trim();
+      let content = (await readFile5(file2, "utf8")).trim();
       if (!content) continue;
       if (content.length > MAX_FILE) content = content.slice(0, MAX_FILE) + "\n\u2026(truncated)";
       if (total + content.length > MAX_TOTAL) content = content.slice(0, Math.max(0, MAX_TOTAL - total)) + "\n\u2026(truncated)";
       total += content.length;
-      const block = `## From ${tildify(file)}
+      const block = `## From ${tildify(file2)}
 ${content}`;
-      (file.startsWith(homeBeecork) ? trusted : project).push(block);
-      sources.push(file);
+      (file2.startsWith(homeBeecork) ? trusted : project).push(block);
+      sources.push(file2);
       if (total >= MAX_TOTAL) break;
     } catch {
     }
@@ -3002,7 +3142,7 @@ ${content}`;
 }
 async function readJsonFile(path) {
   try {
-    return JSON.parse(await readFile4(path, "utf8"));
+    return JSON.parse(await readFile5(path, "utf8"));
   } catch (err) {
     if (err.code !== "ENOENT") {
       console.error(color.yellow(`\u26A0 ignoring malformed ${tildify(path)}: ${err.message}`));
@@ -3029,60 +3169,60 @@ async function loadSettings() {
   return { model, reasoningEffort, alwaysAllow, projectAlwaysAllowIgnored };
 }
 function userConfigPath() {
-  return join4(homedir5(), BEECORK, "config.json");
+  return join6(homedir6(), BEECORK, "config.json");
 }
 async function loadUserConfig() {
   return await readJsonFile(userConfigPath()) ?? {};
 }
 async function saveUserConfig(patch) {
-  const file = userConfigPath();
-  await mkdir3(dirname3(file), { recursive: true });
+  const file2 = userConfigPath();
+  await mkdir5(dirname4(file2), { recursive: true });
   const merged = { ...await loadUserConfig(), ...patch };
-  const tmp = `${file}.tmp`;
-  await writeFile3(tmp, JSON.stringify(merged, null, 2), { encoding: "utf8", mode: 384 });
+  const tmp = `${file2}.tmp`;
+  await writeFile4(tmp, JSON.stringify(merged, null, 2), { encoding: "utf8", mode: 384 });
   await chmod2(tmp, 384).catch(() => {
   });
-  await rename2(tmp, file);
+  await rename2(tmp, file2);
 }
 async function saveModelPreference(model) {
   try {
-    const file = join4(homedir5(), BEECORK, "settings.json");
-    await mkdir3(dirname3(file), { recursive: true });
-    const current = await readJsonFile(file) ?? {};
-    await writeFile3(file, JSON.stringify({ ...current, model }, null, 2), "utf8");
+    const file2 = join6(homedir6(), BEECORK, "settings.json");
+    await mkdir5(dirname4(file2), { recursive: true });
+    const current = await readJsonFile(file2) ?? {};
+    await writeFile4(file2, JSON.stringify({ ...current, model }, null, 2), "utf8");
   } catch {
   }
 }
 async function saveReasoningPreference(reasoningEffort) {
   try {
-    const file = join4(homedir5(), BEECORK, "settings.json");
-    await mkdir3(dirname3(file), { recursive: true });
-    const current = await readJsonFile(file) ?? {};
-    await writeFile3(file, JSON.stringify({ ...current, reasoningEffort }, null, 2), "utf8");
+    const file2 = join6(homedir6(), BEECORK, "settings.json");
+    await mkdir5(dirname4(file2), { recursive: true });
+    const current = await readJsonFile(file2) ?? {};
+    await writeFile4(file2, JSON.stringify({ ...current, reasoningEffort }, null, 2), "utf8");
   } catch {
   }
 }
-var sessionsDir = () => join4(process.cwd(), BEECORK, "sessions");
+var sessionsDir = () => join6(process.cwd(), BEECORK, "sessions");
 async function saveSession(messages) {
   try {
-    const dir = sessionsDir();
-    await mkdir3(dir, { recursive: true });
-    const file = join4(dir, `${Date.now()}.json`);
-    const tmp = `${file}.tmp`;
-    await writeFile3(tmp, JSON.stringify(messages), "utf8");
+    const dir2 = sessionsDir();
+    await mkdir5(dir2, { recursive: true });
+    const file2 = join6(dir2, `${Date.now()}.json`);
+    const tmp = `${file2}.tmp`;
+    await writeFile4(tmp, JSON.stringify(messages), "utf8");
     await chmod2(tmp, 384).catch(() => {
     });
-    await rename2(tmp, file);
-    await pruneSessions(dir).catch(() => {
+    await rename2(tmp, file2);
+    await pruneSessions(dir2).catch(() => {
     });
   } catch {
   }
 }
 var MAX_SESSIONS = 50;
-async function pruneSessions(dir) {
-  const files = (await readdir3(dir)).filter((f) => f.endsWith(".json"));
+async function pruneSessions(dir2) {
+  const files = (await readdir3(dir2)).filter((f) => f.endsWith(".json"));
   if (files.length <= MAX_SESSIONS) return;
-  for (const f of files.sort().slice(0, files.length - MAX_SESSIONS)) await unlink(join4(dir, f)).catch(() => {
+  for (const f of files.sort().slice(0, files.length - MAX_SESSIONS)) await unlink(join6(dir2, f)).catch(() => {
   });
 }
 function sanitizeSession(raw) {
@@ -3119,10 +3259,10 @@ function dropIncompleteToolTail(messages) {
   }
   return messages;
 }
-async function readSession(file) {
+async function readSession(file2) {
   try {
-    const path = join4(sessionsDir(), file);
-    const parsed = sanitizeSession(JSON.parse(await readFile4(path, "utf8")));
+    const path = join6(sessionsDir(), file2);
+    const parsed = sanitizeSession(JSON.parse(await readFile5(path, "utf8")));
     await chmod2(path, 384).catch(() => {
     });
     return parsed;
@@ -3158,11 +3298,11 @@ async function listSessions() {
     return [];
   }
 }
-async function loadSession(file) {
-  return await readSession(file) ?? [];
+async function loadSession(file2) {
+  return await readSession(file2) ?? [];
 }
 function projectApprovalsPath() {
-  return join4(homedir5(), BEECORK, "project-approvals.json");
+  return join6(homedir6(), BEECORK, "project-approvals.json");
 }
 async function loadProjectApprovals() {
   const all = await readJsonFile(projectApprovalsPath());
@@ -3171,14 +3311,14 @@ async function loadProjectApprovals() {
 }
 async function addProjectApproval(tool) {
   try {
-    const file = projectApprovalsPath();
-    await mkdir3(dirname3(file), { recursive: true });
-    const all = await readJsonFile(file) ?? {};
+    const file2 = projectApprovalsPath();
+    await mkdir5(dirname4(file2), { recursive: true });
+    const all = await readJsonFile(file2) ?? {};
     const list = new Set(Array.isArray(all[projectRoot]) ? all[projectRoot] : []);
     list.add(tool);
     all[projectRoot] = [...list];
-    await writeFile3(file, JSON.stringify(all, null, 2), "utf8");
-    await chmod2(file, 384).catch(() => {
+    await writeFile4(file2, JSON.stringify(all, null, 2), "utf8");
+    await chmod2(file2, 384).catch(() => {
     });
   } catch {
   }
@@ -3228,7 +3368,7 @@ async function askApproval(ask, call, reason, offerAlways = true) {
     console.log(color.yellow(`   edit ${stripControl(String(args.path ?? ""))}:`));
     console.log(diffPreview(lineDiff(stripControl(String(args.old_text ?? "")), stripControl(String(args.new_text ?? "")))));
   } else if (call.function.name === "write_file") {
-    const existing = (await readFile5(resolveInRoot(String(args.path ?? ".")).abs, "utf8").catch(() => "")).slice(0, 2e5);
+    const existing = (await readFile6(resolveInRoot(String(args.path ?? ".")).abs, "utf8").catch(() => "")).slice(0, 2e5);
     console.log(color.yellow(`   write ${stripControl(String(args.path ?? ""))} ${existing ? "(overwrite)" : "(new file)"}:`));
     console.log(diffPreview(lineDiff(stripControl(existing), stripControl(String(args.content ?? "")))));
   } else {
@@ -3890,7 +4030,7 @@ function stopChrome() {
 var chromeEnabled = () => config.statuslineEnabled && !!process.stdout.isTTY;
 
 // src/commands.ts
-import { writeFile as writeFile4, mkdir as mkdir4, chmod as chmod3 } from "node:fs/promises";
+import { writeFile as writeFile5, mkdir as mkdir6, chmod as chmod3 } from "node:fs/promises";
 async function pick(opts) {
   if (chromeEnabled()) {
     const v = await chromePick(opts.items.map((it) => ({ label: it.label, hint: it.hint, value: it.value })), opts.initial, opts.title);
@@ -4015,15 +4155,15 @@ async function handleCommand(input, messages) {
     replayConversation(restored);
     console.log(color.green(`\u2191 resumed ${restored.length} messages \u2014 the bee has this context now. Continue below.`) + "\n");
   } else if (cmd === "/good" || cmd === "/bad") {
-    const dir = cmd === "/bad" ? "eval/failures" : "eval/good";
+    const dir2 = cmd === "/bad" ? "eval/failures" : "eval/good";
     try {
-      await mkdir4(dir, { recursive: true });
-      const file = `${dir}/${Date.now()}.json`;
-      await writeFile4(file, JSON.stringify({ rating: cmd.slice(1), model: state.model, messages }, null, 2), "utf8");
-      await chmod3(file, 384).catch(() => {
+      await mkdir6(dir2, { recursive: true });
+      const file2 = `${dir2}/${Date.now()}.json`;
+      await writeFile5(file2, JSON.stringify({ rating: cmd.slice(1), model: state.model, messages }, null, 2), "utf8");
+      await chmod3(file2, 384).catch(() => {
       });
       console.log(
-        color.cyan(`saved this conversation \u2192 ${file}`) + (cmd === "/bad" ? " (turn it into an eval task later)" : "") + "\n"
+        color.cyan(`saved this conversation \u2192 ${file2}`) + (cmd === "/bad" ? " (turn it into an eval task later)" : "") + "\n"
       );
     } catch (err) {
       console.log(color.red(`couldn't save: ${err.message}`) + "\n");
@@ -4207,7 +4347,7 @@ ${instr.trusted}`;
     saved = true;
     try {
       if (config.traceFile) {
-        await writeFile5(config.traceFile, JSON.stringify(trace), "utf8");
+        await writeFile6(config.traceFile, JSON.stringify(trace), "utf8");
         await chmod4(config.traceFile, 384).catch(() => {
         });
       } else if (messages.length > 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beecork",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "beecork — a from-scratch CLI coding agent: multi-model (OpenRouter), BYOK, path-confined tools, built part by part.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "main": "dist/index.js",
   "files": [
     "dist/",
-    "skills/"
+    "skills/",
+    "skeleton/"
   ],
   "engines": {
     "node": ">=20.12"

package/skeleton/bridge.mjs

@@ -0,0 +1,181 @@
+// Beecork Skeleton — local inbox (bridge). SHIPPED WITH beecork and auto-started
+// by it (src/skeleton.ts), so the user never runs this by hand. It can still be run
+// directly (`node skeleton/bridge.mjs`) for development.
+//
+// Receives signals POSTed by the extension, keeps a *bounded* rolling window of the
+// most recent ones, and mirrors that window to dev-signals.jsonl (one JSON object per
+// line). Writes are atomic (temp file + rename) so a reader never sees a half file.
+// No dependencies — Node built-ins only.
+//
+// Lifecycle notes (what makes it safe for beecork to own):
+//   - Single instance: a second copy racing for the port exits(0) quietly on EADDRINUSE
+//     instead of crashing — so parallel beecork sessions share ONE inbox.
+//   - Self-tidying: exits itself after IDLE_MS with no traffic and no reads, so an
+//     auto-started bridge can't linger forever after the extension/browser is gone.
+//   - Fixed home: reads/writes under BEECORK_SKELETON_HOME (beecork points this at
+//     ~/.beecork/skeleton) instead of whatever cwd it was launched from.
+
+import http from "node:http";
+import { writeFile, readFile, rename } from "node:fs/promises";
+import { resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+
+const PORT = Number(process.env.BEECORK_SKELETON_PORT) || 8317;
+const HOME = process.env.BEECORK_SKELETON_HOME || process.cwd();
+const FILE = resolve(HOME, "dev-signals.jsonl");
+const TMP = FILE + ".tmp";
+const TOKEN_FILE = resolve(HOME, ".beecork-token");
+const MAX = 1000; // keep at most this many recent signals
+const IDLE_MS = 60 * 60 * 1000; // self-shutdown after an hour with zero activity
+
+// Pairing token: the extension must present this to write. Blocks any other local
+// process or malicious web page from POSTing fake signals to your agent. Generated
+// once and persisted; the extension fetches it via /pair so the user never sees it.
+let TOKEN;
+try {
+  TOKEN = (await readFile(TOKEN_FILE, "utf8")).trim();
+  if (!TOKEN) throw new Error("empty token file");
+} catch {
+  TOKEN = randomBytes(24).toString("hex");
+  await writeFile(TOKEN_FILE, TOKEN + "\n", { mode: 0o600 });
+}
+
+let buffer = []; // rolling in-memory window of recent signal lines; the file mirrors it.
+const watchRequests = new Map(); // origin beecork asked to watch → expiry (ms)
+let lastActivity = Date.now(); // reset on every request; drives idle self-shutdown
+
+// Load any existing signals so a bridge restart keeps recent context.
+try {
+  const prior = await readFile(FILE, "utf8");
+  buffer = prior.split("\n").filter(Boolean).slice(-MAX);
+} catch {
+  /* no file yet — start empty */
+}
+
+// Persist the bounded window atomically. Writes are serialized through one chain so
+// two concurrent ingests can't clobber the temp file mid-write.
+let chain = Promise.resolve();
+function persist() {
+  chain = chain
+    .then(async () => {
+      await writeFile(TMP, buffer.length ? buffer.join("\n") + "\n" : "");
+      await rename(TMP, FILE);
+    })
+    .catch((e) => console.error("[skeleton] persist failed:", e));
+  return chain;
+}
+
+// A web page's fetch carries an http(s) Origin; refuse those so a page you visit can't
+// read your captured app data or drive your extension. beecork's Node fetch has no web
+// origin and passes. No CORS header is set on these routes on purpose.
+const fromWebPage = (req) => /^https?:\/\//i.test(req.headers.origin || "");
+
+const server = http.createServer((req, res) => {
+  lastActivity = Date.now();
+
+  // Liveness + identity marker: lets beecork tell OUR bridge apart from some other
+  // program that happens to hold the port, so it never spawns a duplicate or talks to
+  // a stranger. Non-sensitive, but web-origin-gated like everything else.
+  if (req.method === "GET" && req.url === "/health") {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    return void res
+      .writeHead(200, { "Content-Type": "application/json" })
+      .end(JSON.stringify({ skeleton: true, port: PORT, signals: buffer.length }));
+  }
+
+  // Auto-pairing: hand the token to the extension so the user never touches it.
+  if (req.method === "GET" && req.url === "/pair") {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    return void res.writeHead(200, { "Content-Type": "text/plain" }).end(TOKEN);
+  }
+
+  // A distilled read for the agent: recent signals, filtered. ?kind=&since=<epoch-ms>&limit=
+  if (req.method === "GET" && req.url.startsWith("/signals")) {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    const q = new URL(req.url, "http://localhost").searchParams;
+    const kind = q.get("kind");
+    const since = Number(q.get("since")) || 0;
+    const limit = Math.min(Math.max(Number(q.get("limit")) || 50, 1), 1000);
+    // Scope to one or more origins (comma-separated) so a project sees only its own site's signals.
+    const origins = (q.get("origin") || "").split(",").map((s) => s.trim()).filter(Boolean);
+    let items = buffer.map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+    if (kind && kind !== "all") items = items.filter((s) => s.kind === kind);
+    if (since) items = items.filter((s) => (s.ts || 0) >= since);
+    // Match the TAB the signal came from (s.page) when present, else the request/resource url. Keying
+    // on the tab origin is what makes scoping correct for cross-origin API calls a page makes.
+    if (origins.length) items = items.filter((s) => origins.some((o) => String(s.page || s.url || "").startsWith(o)));
+    items = items.slice(-limit);
+    return void res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify({ signals: items }));
+  }
+
+  // Reverse channel: beecork asks for a site to be watched. The extension honors it
+  // only for sites the user already approved.
+  if (req.method === "POST" && req.url === "/request-watch") {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      try {
+        const { origin: site, ttlMs } = JSON.parse(body || "{}");
+        if (site) watchRequests.set(String(site), Date.now() + (Number(ttlMs) || 10 * 60 * 1000));
+        res.writeHead(200).end("ok");
+      } catch {
+        res.writeHead(400).end("bad json");
+      }
+    });
+    return;
+  }
+  if (req.method === "GET" && req.url.startsWith("/watch-requests")) {
+    if (fromWebPage(req)) return void res.writeHead(403).end("forbidden");
+    const now = Date.now();
+    for (const [site, exp] of watchRequests) if (exp < now) watchRequests.delete(site); // expire
+    return void res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify({ origins: [...watchRequests.keys()] }));
+  }
+
+  // Permissive CORS so the extension's service worker can POST to /ingest.
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+  if (req.method === "OPTIONS") return void res.writeHead(204).end();
+
+  if (req.method === "POST" && req.url === "/ingest") {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", async () => {
+      try {
+        const signal = JSON.parse(body);
+        if (signal.token !== TOKEN) { res.writeHead(401).end("unauthorized"); return; } // token-gated
+        delete signal.token; // never persist the token itself
+        buffer.push(JSON.stringify(signal));
+        if (buffer.length > MAX) buffer.splice(0, buffer.length - MAX); // bound it
+        await persist();
+        console.log(`[skeleton] ${signal.kind}: ${String(signal.text || "").slice(0, 200)}`);
+        res.writeHead(200).end("ok");
+      } catch {
+        res.writeHead(400).end("bad json");
+      }
+    });
+    return;
+  }
+  res.writeHead(404).end();
+});
+
+// Single-instance: if another bridge already holds the port (a parallel beecork
+// session started it), step aside quietly rather than crash.
+server.on("error", (e) => {
+  if (e && e.code === "EADDRINUSE") process.exit(0);
+  console.error("[skeleton]", e);
+  process.exit(1);
+});
+
+// Self-tidying: an auto-started bridge shouldn't outlive its usefulness. When the
+// extension is loaded it polls every ~30s, so this only fires once the browser side
+// is truly gone AND nothing has read for an hour.
+const idle = setInterval(() => {
+  if (Date.now() - lastActivity > IDLE_MS) { server.close(); process.exit(0); }
+}, 5 * 60 * 1000);
+idle.unref(); // don't let the timer alone keep the process alive
+
+server.listen(PORT, "127.0.0.1", () => {
+  console.log(`[skeleton] inbox listening on http://localhost:${PORT} (home: ${HOME})`);
+});

package/skills/browser-signals.md

@@ -21,6 +21,23 @@ the real errors:
 
 Pull it **on demand** while debugging — don't call it in a loop or on every turn.
 
+## Seeing only THIS project's signals (scoping)
+
+The inbox is **shared** across every project that uses beecork, so signals from other apps you
+have open can show up too. Scope to the project you're in:
+
+- Pass **`origin`** — the site(s) this project runs on, e.g.
+  `read_dev_signals({ origin: "http://localhost:8000" })`, or comma-separated for several frontends:
+  `{ origin: "http://localhost:3000,http://localhost:3001" }`. Get it from the project itself (dev
+  script / framework config) or from the user.
+- **Production sites are remembered per folder; localhost is not.** Once you `watch_site` a production
+  URL, beecork saves that origin to `.beecork/skeleton.json` and later `read_dev_signals` calls in that
+  folder auto-scope to it. **localhost is deliberately never remembered** — dev ports get reused across
+  projects (`:8000` might be a different app tomorrow), so a saved localhost binding would mis-attribute
+  another app's signals. Pass the localhost `origin` each session instead (you know it from the project).
+- If you call it unscoped and the feed spans multiple sites, the result lists the origins so you (or the
+  user) can pick this project's.
+
 ## Watching an on-demand / production site
 
 Localhost/dev sites the user approved are watched automatically. A **production** (or
@@ -32,16 +49,18 @@ its own). Then have the user reproduce the issue (or open the site) and call
 
 ## If it says "not connected" — one-time setup
 
-The tool returns setup steps when the bridge isn't running. Relay them to the user:
+**beecork starts the local inbox itself** — the first time you call `read_dev_signals` or
+`watch_site`, beecork auto-starts the bundled bridge (a `127.0.0.1:8317` inbox) in the
+background and shares it across sessions. So there is **no bridge to run by hand**; the only
+one-time step is loading the Chrome extension:
 
-1. **Start the local inbox (bridge):** run `node bridge/server.mjs` in the `beecork-extension`
-   folder and leave it running. It listens on `localhost:8317`.
-2. **Load the extension:** Chrome → `chrome://extensions` → enable **Developer mode** →
+1. **Load the extension:** Chrome → `chrome://extensions` → enable **Developer mode** →
    **Load unpacked** → select the `beecork-extension/extension` folder → pin the icon.
-3. **Connect + approve:** click the icon (it auto-connects — no token to paste), tick
+2. **Connect + approve:** click the icon (it auto-connects — no token to paste), tick
    **Capture enabled**, open the app in a tab, and click **Pair this site**.
 
-Then call `read_dev_signals` again.
+Then call `read_dev_signals` again. (If beecork reports the inbox port is held by another
+program, free port 8317 or set `BEECORK_DEV_SIGNALS_URL` to a different inbox.)
 
 ## Empty result