Address PR #88 review: rename to browser-to-api, drop lift doc, fix bugs

Renaming and doc cleanup (per shrey150):
- Rename skill from `browser-reverse` to `browser-to-api`. Updates SKILL.md
  frontmatter + heading, package.json, REFERENCE.md heading, the OpenAPI
  doc's `info.description`, and the report.md heading.
- Fix the stale `discover-api-spec` reference in SKILL.md's composition diagram
  (left over from an earlier rename).
- Drop `BODY-CAPTURE-LIFT.md` from the PR; it's a separate proposal.
- Remove the `exec.sendFile()` reference in SKILL.md (browserbase-internal,
  not a generic skill primitive).
- REFERENCE.md restructured to lead with the script/CLI/file-format reference
  rather than an architecture intro. Pipeline diagram dropped.

Bug fixes (per Cursor Bugbot):
- `filter.mjs`: rework precedence so `--include` actually rescues URLs that
  would be hit by a default exclude, matching the documented contract. User
  `--exclude` still wins. Added a unit-style test path.
- `infer.mjs`: skip response-body samples whose CDP status is null. Previously
  they were keyed under `"0"` but `emit.mjs` only iterates `ep.statusCodes`
  (which excludes nulls), silently discarding the body.
- `load.mjs`: fix the comment in `urlQuery()` — code is first-value-wins, not
  last-value-wins.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: derekmeegan

skills/browser-reverse/BODY-CAPTURE-LIFT.md

@@ -1,25 +1,10 @@
-# Browser Reverse — Reference
+# Browser to API — Reference
 
-Technical reference for the discovery pipeline, file formats, and configuration.
-
-## Pipeline
-
-```
-browser-trace run                    discover.mjs
-.o11y/<run>/cdp/network/             ┌─────────┐    ┌────────┐    ┌──────────┐    ┌─────────┐    ┌──────┐
-  requests.jsonl       ──────────▶   │  load   │ ─▶ │ filter │ ─▶ │ normalize│ ─▶ │ infer   │ ─▶ │ emit │
-  responses.jsonl                    └─────────┘    └────────┘    └──────────┘    └─────────┘    └──────┘
-                                       paired         filtered      endpoints       endpoints       openapi
-                                       .jsonl         .jsonl        .jsonl          .with-          .yaml
-                                                                                    schemas         report.md
-                                                                                    .jsonl
-```
-
-Each stage is a discrete script that reads a file and writes a file. `discover.mjs` is the dispatcher; pass `--stage <name>` to run a single stage for debugging.
+Exhaustive reference for every script, flag, file format, and configuration knob the skill exposes.
 
 ## Scripts
 
-All scripts are Node ESM (`type: module`). They depend only on the Node standard library.
+All scripts are Node ESM (`type: module`). They depend only on the Node standard library. `discover.mjs` is the top-level dispatcher; the others are stage scripts the dispatcher calls in order. Run an individual stage with `discover.mjs --stage <name>` for debugging or partial reruns.
 
 ### `discover.mjs --run <path> [flags]`
 

skills/browser-reverse/REFERENCE.md skills/browser-to-api/REFERENCE.mdskills/browser-reverse/REFERENCE.md renamed to skills/browser-to-api/REFERENCE.md

@@ -1,20 +1,20 @@
 ---
-name: browser-reverse
-description: Reverse-engineer a website's HTTP API into a best-effort OpenAPI 3.1 spec by analyzing a `browser-trace` capture. Use when the user wants to discover/extract API endpoints from a browser session, build an OpenAPI doc from network traffic, or document a third-party site's XHR/fetch surface for client integration.
+name: browser-to-api
+description: Turn a website's observable HTTP traffic into a best-effort OpenAPI 3.1 spec by analyzing a `browser-trace` capture. Use when the user wants to discover/extract API endpoints from a browser session, build an OpenAPI doc from network traffic, or document a third-party site's XHR/fetch surface for client integration.
 compatibility: "Requires Node 18+ and a `browser-trace` run directory (`.o11y/<run>/`) produced by the sibling `browser-trace` skill. The scripts use only the Node standard library — no `npm install` step. `jq` is referenced in docs for ad-hoc querying but is not required by the scripts."
 license: MIT
 allowed-tools: Bash, Read, Grep
 ---
 
-# Browser Reverse
+# Browser to API
 
-Replay-driven API reverse-engineering. Consume a `browser-trace` capture, pair its CDP request / response events, templatize observed URLs, infer JSON schemas from samples, and emit an **OpenAPI 3.1** document plus a human-readable coverage report.
+Replay-driven API discovery. Consume a `browser-trace` capture, pair its CDP request / response events, templatize observed URLs, infer JSON schemas from samples, and emit an **OpenAPI 3.1** document plus a human-readable coverage report.
 
 This skill **does not capture traffic**. It is purely offline post-processing on top of `browser-trace`'s `cdp/network/*.jsonl` buckets. The two skills compose:
 
 ```
-browser-trace        →  .o11y/<run>/cdp/network/{requests,responses}.jsonl
-discover-api-spec    →  .o11y/<run>/api-spec/openapi.yaml + report.md
+browser-trace    →  .o11y/<run>/cdp/network/{requests,responses}.jsonl
+browser-to-api   →  .o11y/<run>/api-spec/openapi.yaml + report.md
 ```
 
 ## When to use
@@ -67,7 +67,7 @@ node scripts/discover.mjs --run .o11y/my-site
 
 `discover.mjs` auto-detects `<run>/cdp/network/bodies/`. To use a body capture from elsewhere (e.g. didn't snapshot, want the live `browse network` dir), pass `--bodies <path>` explicitly.
 
-Then deliver the artifacts to the user (`exec.sendFile()` for `openapi.yaml` and `report.md`).
+The two primary deliverables are `openapi.yaml` (machine-readable spec) and `report.md` (human-readable coverage summary).
 
 ## CLI flags
 
@@ -115,7 +115,7 @@ What changes when bodies are present:
 - ✅ Request-body schemas — `postData` from CDP is enough; bodies dir is a nice-to-have for non-`postData` cases.
 - ✅ **Response-body schemas** — fully inferred from real samples. Without bodies you get `{ description, content: <mimeType> }` skeletons.
 
-The report flags every endpoint that has no response-body sample. For a sketch of what it would take to teach `browser-trace` itself to capture response bodies natively (no separate `browse network on` step), see [BODY-CAPTURE-LIFT.md](BODY-CAPTURE-LIFT.md).
+The report flags every endpoint that has no response-body sample.
 
 ## Limitations
 

skills/browser-reverse/SKILL.md skills/browser-to-api/SKILL.mdskills/browser-reverse/SKILL.md renamed to skills/browser-to-api/SKILL.md

@@ -1,5 +1,5 @@
 {
-  "name": "browser-reverse",
+  "name": "browser-to-api",
   "version": "0.1.0",
   "private": true,
   "type": "module"

skills/browser-reverse/package.json skills/browser-to-api/package.jsonskills/browser-reverse/package.json renamed to skills/browser-to-api/package.json

@@ -247,7 +247,7 @@ export function emit(outDir, opts = {}) {
     info: {
       title,
       version: '0.1.0-discovered',
-      description: 'Spec discovered from a browser-trace capture by the browser-reverse skill. Inductive, not contractual — see `report.md` and `x-confidence` extensions for caveats.',
+      description: 'Spec discovered from a browser-trace capture by the browser-to-api skill. Inductive, not contractual — see `report.md` and `x-confidence` extensions for caveats.',
     },
     servers,
     paths,
@@ -290,7 +290,7 @@ export function emit(outDir, opts = {}) {
 
 function buildReport({ kept, dropped, servers, redaction, minSamples }) {
   const lines = [];
-  lines.push('# Browser-reverse: discovered API\n');
+  lines.push('# Discovered API\n');
   lines.push('## Servers\n');
   for (const s of servers) lines.push(`- ${s.url}`);
   if (!servers.length) lines.push('_(none)_');

…lls/browser-reverse/scripts/discover.mjs …ills/browser-to-api/scripts/discover.mjsskills/browser-reverse/scripts/discover.mjs renamed to skills/browser-to-api/scripts/discover.mjs skills/browser-reverse/scripts/discover.mjs renamed to skills/browser-to-api/scripts/discover.mjs

@@ -35,8 +35,13 @@ const DEFAULT_EXCLUDES = [
 
 export function filter(outDir, opts = {}) {
   const { include = [], exclude = [], origins = [] } = opts;
+  // Precedence:
+  //   1. --origins gates everything; non-matching is dropped.
+  //   2. User --exclude always wins (explicit user intent).
+  //   3. Default excludes can be rescued by --include (REFERENCE.md contract).
+  //   4. When --include is set, anything that doesn't match it is dropped.
+  const userExcludeRes = exclude.map(s => new RegExp(s));
   const includeRes = include.map(s => new RegExp(s));
-  const excludeRes = [...DEFAULT_EXCLUDES, ...exclude.map(s => new RegExp(s))];
   const originSet = new Set(origins);
 
   const paired = readJsonl(intermediatePath(outDir, 'paired.jsonl'));
@@ -49,8 +54,13 @@ export function filter(outDir, opts = {}) {
       const matched = [...originSet].some(o => host === o || host.endsWith('.' + o));
       if (!matched) { droppedOrigin++; continue; }
     }
-    if (excludeRes.some(re => re.test(row.url))) { droppedExclude++; continue; }
-    if (includeRes.length && !includeRes.some(re => re.test(row.url))) { droppedInclude++; continue; }
+    if (userExcludeRes.some(re => re.test(row.url))) { droppedExclude++; continue; }
+
+    const matchesInclude = includeRes.length > 0 && includeRes.some(re => re.test(row.url));
+    const matchesDefaultExclude = DEFAULT_EXCLUDES.some(re => re.test(row.url));
+    if (matchesDefaultExclude && !matchesInclude) { droppedExclude++; continue; }
+    if (includeRes.length && !matchesInclude) { droppedInclude++; continue; }
+
     out.push(row);
   }
 

skills/browser-reverse/scripts/emit.mjs skills/browser-to-api/scripts/emit.mjsskills/browser-reverse/scripts/emit.mjs renamed to skills/browser-to-api/scripts/emit.mjs

@@ -55,9 +55,12 @@ export function infer(outDir, opts = {}) {
         if (!pickedReqExample) { pickedReqExample = s.reqBody; pickedReqStatus = s.status; }
       }
       if (s.respBody != null && typeof s.respBody === 'object') {
-        const status = s.status ?? 0;
-        let p = respProtoByStatus.get(status);
-        if (!p) { p = newProto(); respProtoByStatus.set(status, p); }
+        // Skip when we have no status: emit.mjs only renders schemas under
+        // statuses that appear in ep.statusCodes (which excludes nulls), so
+        // a body keyed under "0" would be silently discarded.
+        if (s.status == null) continue;
+        let p = respProtoByStatus.get(s.status);
+        if (!p) { p = newProto(); respProtoByStatus.set(s.status, p); }
         ingest(p, s.respBody);
         if (s.status >= 200 && s.status < 300 && !pickedRespExample) {
           pickedRespExample = s.respBody;