@seybel/breakhound 1.0.5 → 1.0.7

package/README.md

@@ -16,11 +16,8 @@ breakhound 1.0.0 · 14 pages · 320–1920px
   ✖ /pricing        2 issues · layout changes at 768, 1024   4.1s
   ✔ /about          clean · layout changes at 640, 1024      3.2s
   ✖ /blog/[slug]    1 issue · layout changes at 768          3.8s  as /blog/hello-world
-  ○ /dashboard      Needs a login: it redirected to /login
   ...
 
-  3 issues on 2 pages
-
   ✖ error    320–599px      Page scrolls horizontally (280px wider than the viewport)
               div.pricing-table · /pricing
               → It stays 600px wide no matter the screen size. Replace the fixed width
@@ -30,11 +27,8 @@ breakhound 1.0.0 · 14 pages · 320–1920px
               → Collapse this row into a menu below this width, tighten its spacing, or
                 let it scroll sideways.
 
-  ○ 1 page needs a login. Run npx @seybel/breakhound login once to sign in, then scan again.
-
   Report  .breakhound/report.html  (npx @seybel/breakhound report to open it)
-  Fix it  npx @seybel/breakhound prompt --copy  then paste into your coding agent
-      or  npx @seybel/breakhound mcp install  so your agent can scan, verify and undo by itself
+  Fix it  npx @seybel/breakhound mcp install  so your agent can scan, verify and undo by itself
 ```
 
 ## Quick start
@@ -45,357 +39,49 @@ In your project folder:
 npx @seybel/breakhound
 ```
 
-That's it: no config. npx runs it without installing anything. To type `breakhound` directly instead, install it globally:
-
-```bash
-npm i -g @seybel/breakhound
-```
-
-Or add it to your project with `npm i -D @seybel/breakhound`, so everyone gets the same version, and run it as `npx breakhound` or from an npm script.
-
-If your dev server is already running it's used, otherwise breakhound starts it with your `dev` script and stops it when done. Chromium is downloaded automatically the first time (about 150 MB).
-
-Other ways to run it:
-
-```bash
-npx @seybel/breakhound /pricing /blog          # only these routes
-npx @seybel/breakhound http://localhost:3000   # just this one page
-npx @seybel/breakhound --url https://staging.example.com   # every route, on another server
-```
-
-## Finding routes
-
-| Project | Where routes come from |
-|---|---|
-| Next.js (App and Pages Router) | `app/` and `pages/`, skipping route groups, parallel slots, private folders and API routes |
-| Nuxt | the live Vue router, so module and custom routes count too (falls back to `pages/`) |
-| SvelteKit | `src/routes` |
-| Astro | `src/pages` |
-| Remix, React Router 7 | the route manifest, `app/routes.ts` and `app/routes/` |
-| TanStack Router | `routeTree.gen.ts` and the live router |
-| React Router (code-defined) | the live route tree, including `<Routes>` nested inside pages; falls back to reading your router code |
-| Vue Router (code-defined) | the live router; falls back to reading your router code |
-| Angular | your route definitions, from `src/main.ts` on, with lazily loaded `loadChildren` routes under their path |
-| Anything else | links followed from the home page (up to 50 pages, a few per section) |
-
-**Dynamic routes** like `/blog/[slug]` are scanned once, using a real link found on your pages (routes that share a template share a layout). Routes below one reuse its values: once `/users/jane` is found, `/users/[username]/settings` is scanned as `/users/jane/settings`. If something is still missing, it's listed with a hint naming the parameters. Give them a real value once, by name, and every route that uses them is filled in:
-
-```ts
-params: { username: 'jane', orderId: '1001' }
-```
-
-Or give one route its own URL, which wins over `params`:
-
-```ts
-samples: { '/products/[id]': '/products/42' }
-```
-
-**Pages behind a login** are spotted (they redirect to a sign-in page) and listed instead of scanning the login page over and over. Sign in once:
-
-```bash
-npx @seybel/breakhound login
-```
-
-A browser window opens; log in as you normally would, then press Enter. The session is saved to `.breakhound/auth.json`, which is never committed (see below), and used by later scans. breakhound never sees your password.
-
-Links that would log you out, delete something, or download a file are never followed.
-
-## What it checks
-
-| Check | Finds |
-|---|---|
-| `page-overflow` | Anything that makes the page scroll sideways, or gets cut off at the screen edge (including inside full-width wrappers) |
-| `content-overflow` | Content spilling out of a card, panel or bordered box, sideways or out of the bottom of a fixed-height box |
-| `media-overflow` | Images, video and embeds that don't shrink with their container |
-| `overlap` | Content painted on top of other content |
-| `unexpected-wrap` | Nav rows and button labels breaking onto extra lines |
-| `clipped-text` | Text cut off, or pushed out of sight, by a fixed-size container at narrower widths |
-| `squished-text` | Columns so narrow that words break apart |
-| `distorted-media` | Images stretched or squashed out of proportion |
-| `small-tap-target` | Buttons and links under 24×24px that crowd each other on touch screens (WCAG 2.2) |
-| `tiny-text` | Text under 12px on phones |
-| `oversized-text` | Headings and display text left at their desktop size on phones, wrapping a word or two a line |
-| `edge-gutter` | Text pressed against the edge of a phone screen |
-| `viewport-meta` | A missing responsive viewport tag |
-
-Every issue comes with the exact width ranges where it happens, the element to blame, the numbers behind it, a screenshot, and a likely fix. breakhound also reports the widths where your layout actually changes and flags changes that no media or container query explains.
-
-It's built to be quiet: carousels, off-canvas menus, badges, decorative shapes, ellipsis and line-clamp, and framework dev overlays are all understood and left alone. It also looks inside web components (open shadow roots) and handles right-to-left pages.
-
-### Safari and Firefox
-
-Chromium finds most layout bugs, but Safari and Firefox lay some things out differently (flex gaps, `dvh` units, form controls, font metrics). `--browsers chromium,webkit,firefox` checks the pages again in WebKit (Safari's engine) and Firefox once Chromium is done, one browser at a time so memory stays flat. An issue that shows up in only some of them says so: `(only in WebKit)`. Each extra browser is a one-time download of about 80 to 90 MB, done on first use or ahead of time with `npx @seybel/breakhound install webkit firefox`.
-
-Two differences you'll meet early: Safari gives buttons, inputs and selects an 11px font unless you set one (Chrome and Firefox use about 13px), so unstyled controls show up as tiny text only in WebKit, with `font: inherit` as the fix (that's WebKit on a Mac: Playwright's WebKit on Linux, as in most CI, draws them like Chrome); and Firefox breaks long URLs at their slashes, so a URL that pushes the page wide in Chrome and Safari can wrap fine in Firefox.
-
-### Menus, dialogs, tabs and expandable sections
-
-A lot of what breaks on a phone is hidden until you tap: the mobile menu, a sign-up modal, an FAQ answer, the second tab. After scanning a page as it loads, breakhound opens what it finds there one at a time and sweeps the widths where each can be opened. That covers buttons with `aria-expanded`, `<details>`, popovers, dialogs, tabs (`role="tab"`, as in Radix, shadcn/ui, Headless UI and MUI), Bootstrap toggles, and buttons that are clearly a menu (`hamburger`, `menu-toggle`, an accessible name of "Menu"). Only what breaks while something is open gets reported, with what to open first:
-
-```
-✖ 320–399px  Page scrolls horizontally (80px wider than the viewport), with "Menu" open
-```
-
-It never clicks a link to another page or a button that submits a form, and it opens only one question of an FAQ, since they all share a layout, but every tab, since each shows something different. It opens up to 5 per page. Set `states` to change that, or `--no-states` (or `data-breakhound-ignore="states"` on an element) to leave them closed.
-
-### A second opinion from a vision model (optional)
-
-Rules can't tell when a layout is merely cramped or awkward. `--vision` shows each page at 375, 768 and 1280px to your own vision model (an Anthropic or OpenAI key, or a local Ollama model such as `qwen2.5vl`, set up the same way as `breakhound fix`) and adds what it says looks off. Those come in as info, tied to the element whose text the model quotes, and never fail a run. Verify leaves them out, since an opinion can't be measured again.
-
-## Reports
+No config needed. It works with Next.js, Nuxt, SvelteKit, Astro, Remix, React Router, TanStack Router, Vue, Angular and plain Vite apps, at the root of a monorepo too, and follows links on anything else. Chromium downloads the first time (about 150 MB).
 
-Every run writes to `.breakhound/`:
+To type `breakhound` on its own, install it globally with `npm i -g @seybel/breakhound`, or add it to your project with `npm i -D @seybel/breakhound`.
 
-| File | What it is |
-|---|---|
-| `report.html` | Self-contained report: width map, filters, screenshots, copy buttons. Open it with `breakhound report`. |
-| `summary.md` | One line per issue |
-| `report.md` | Every issue with evidence and screenshots |
-| `prompt.md` | Instructions for a coding agent |
-| `result.json` | The raw result |
-| `report.pdf` | With `--pdf` |
+## What it finds
 
-The folder is for you, not your repo, so it keeps itself out of git: breakhound puts a `.gitignore` inside it that ignores everything there, the way tool caches like `.pytest_cache` do. Nothing to add to your own `.gitignore`, and breakhound never edits it. To commit a report anyway, edit or delete that inner `.gitignore`; breakhound only writes it when it's missing.
+Pages that scroll sideways, content spilling out of its box, media that doesn't shrink, overlapping content, nav rows and labels that wrap, clipped and squished text, text too small or too big for phones, small tap targets, distorted images, text against the screen edge, and a missing viewport tag.
 
-## Chrome extension
+Every issue comes with the exact widths where it happens, the element to blame, the numbers behind it, a screenshot, and a likely fix. It also opens menus, dialogs, tabs and accordions and checks them open, can check Safari's and Firefox's engines too, and is built to stay quiet on carousels, off-canvas menus and other patterns that only look wrong. [All the checks →](https://seybel.github.io/breakhound/guide/checks)
 
-The breakhound extension runs the same checks on the tab you have open, with nothing to install in your project. Get it from the [Chrome Web Store](https://chromewebstore.google.com/detail/ddnmhnjmcokbfabeileblceehjhefkpc); it works on any page Chrome can open, from localhost to production. The quickest way in is to right-click the page and choose **Scan with breakhound**: the breakhound panel opens in Chrome's side panel and starts right away. Clicking the breakhound icon in the toolbar opens it ready to scan, and the same panel is a **breakhound** tab in DevTools. The page grows steadily from 320px to 1920px (or the widths you set) while the timeline fills in live: each run of widths that share a layout, every width where the layout changes, and where something breaks. Then you get:
+## Three ways to use it
 
-- the issues, each with its exact width ranges, the element, the numbers and the likely fix
-- the timeline: the layout bands, the media query widths, the changes no media or container query explains, and a bar for each issue across the widths it covers
+**In the terminal**, as above. Pages behind a login, dynamic routes, staging servers and big apps are all covered in [recipes](https://seybel.github.io/breakhound/guide/recipes).
 
-To check only some screens, pick **Mobile** (320 to 599px), **Tablet** (600 to 1023px) or **Desktop** (1024 to 1920px) next to the widths. Pick a neighbour as well to check both, so Mobile and Tablet is 320 to 1023px; **All** goes back to every width. They only fill in the two width fields, so you can still type any range you like, and a smaller range scans faster.
+**In Chrome**, with the [breakhound extension](https://chromewebstore.google.com/detail/ddnmhnjmcokbfabeileblceehjhefkpc): right-click any page, from localhost to production, and choose **Scan with breakhound**. A timeline fills in live as the page grows from 320px to 1920px. [More →](https://seybel.github.io/breakhound/guide/extension)
 
-Drag across the timeline to resize the page live, click anywhere on it to jump to a width, or use the arrow keys to nudge a pixel at a time. Widths wider than the tab are zoomed out to fit, like DevTools' device mode, so a 1920px layout is shown whole, and the page refits when you drag DevTools bigger or smaller. If you press Cancel on Chrome's debugging bar, the tab goes back to its own width and breakhound's outlines disappear. Click an issue to see the page at the width where it's worst, with the element outlined. **Select in Elements** jumps to the element, and **Copy prompt** gives your coding agent the same instructions `breakhound prompt` would. (Select in Elements is only in the DevTools tab, since only DevTools has an Elements panel.) It finds what the CLI finds on the same page, since both run the same code.
-
-While it scans or shows a width, Chrome displays a bar saying breakhound started debugging this browser: that is how an extension resizes a tab. The bar goes away afterwards, and the tab goes back to its own width and scroll position. **Reload first** reloads the page before scanning, so breakhound can wait for the page's own resize handlers exactly, as the CLI does. Leave it off to scan the page as you have it.
-
-**Whole site** scans every page of the site, starting from the one you're on. breakhound finds the pages the way the CLI does: from the app's live router when it has one (Vue, React Router, Nuxt, Remix, TanStack), otherwise by following links from the page you're on and the home page (never a logout, delete or file link, and a few pages per section, since blog posts share a layout), up to 25 pages. It loads each one in the same tab, scans it, and comes back to where you were. Chrome stops drawing a tab that's out of view, so if you switch away while it runs, the scan pauses and carries on by itself when you come back. Your own login applies, so pages behind it are scanned too. Each page gets a chip with its issue count; an issue shared by several pages is counted once, and **Copy prompt** lists it once with every page it's on. Showing an issue from another page takes the tab there first.
-
-**Send to agent** hands the issues to the coding agent working on that app, so it can fix them and check each fix in your browser. See [From the browser](#from-the-browser) below.
-
-Routes only your project's files list (Next.js, SvelteKit and Astro route folders) need the CLI, as do menus opened, other browsers, screenshots and reports.
-
-
-## Fix it with your coding agent
-
-breakhound doesn't edit your code: your own agent does, and breakhound checks its work. Nothing leaves your machine and it costs nothing.
-
-### Over MCP (recommended)
+**With your coding agent.** breakhound doesn't edit your code: your agent does, and breakhound checks its work at every width.
 
 ```bash
 npx @seybel/breakhound mcp install
 ```
 
-It finds Claude Code, Cursor, VS Code, Antigravity, Windsurf and Codex, shows what it will add to their MCP settings, and asks first. Then ask your agent to fix the responsive issues. It can:
-
-| Tool | What it does |
-|---|---|
-| `scan` | Find every route and its issues. This becomes the baseline |
-| `list_routes`, `list_issues` | What was found |
-| `get_issue` | Widths, element, source file and line, measurements, likely fix and a screenshot |
-| `verify` | Scan again and compare with the baseline: fixed, still there, and **new** |
-| `checkpoint` | Commit the fix for some routes as its own git commit |
-| `undo` | Revert the fixes for some routes, or the whole session |
-
-`verify` is the point: agents often fix 812px and break 1280px, or fix one page and break another that shares a component. New issues show up there, at any width, on any page that was scanned.
-
-The dev server stays up between calls, so each verify only takes as long as the scan. In Claude Code, `/mcp__breakhound__fix` asks for the whole loop in one go.
-
-### From the browser
-
-Scanned a page in the breakhound extension? Click **Send to agent** and the issues go to the agent working on that app, with nothing to copy and paste. Then ask it to "fix the breakhound issues".
-
-- It goes to the project, not to one agent: Claude Code and Cursor open on the same app both see it.
-- breakhound picks the project serving the page, the way the CLI recognises your dev server (or from `baseUrl` in your config). When it can't tell, for a staging site say, it asks which project.
-- When the agent verifies a fix, the panel scans those pages again **in your browser**: same login, same browser, so the comparison is exact. Keep the panel open while it works; a chip in the toolbar shows the agent is connected. If the panel is closed, verify says so, and the agent asks you to open it.
-
-It works through the MCP server, so it needs `npx @seybel/breakhound mcp install` once (the panel shows the command if your agent isn't connected yet). `breakhound mcp` listens on 127.0.0.1 only, on a port from 47821, and answers only the breakhound extension. It only ever writes the scan you sent into `.breakhound/`; it never reads or sends your files.
-
-### With a prompt
-
-```bash
-npx @seybel/breakhound prompt --copy
-```
-
-Paste it into any agent. It lists each unique issue once with the widths, the element, the evidence and the likely fix, and tells the agent to run `npx @seybel/breakhound verify` until nothing is left.
-
-### With your own model
-
-No agent at hand? `breakhound fix` works through the last scan's issues itself, using your own API key or a model running on your machine:
-
-```bash
-ANTHROPIC_API_KEY=... npx @seybel/breakhound fix          # or OPENAI_API_KEY=... with --model <name>
-npx @seybel/breakhound fix --provider ollama --model qwen2.5-coder   # free and local, with Ollama
-```
-
-For each issue it shows the model the issue and the files most likely behind it (where the element is written, then the files that mention its classes), applies the edits it suggests, and checks the pages again. A fix that clears the issue without breaking anything else, at any width, becomes its own commit, which `breakhound undo` can take back. One that doesn't is put back, and the model gets one more try with the reason. Files with uncommitted changes are never touched. It needs a git repository, and only the code around each issue is sent to the model you chose.
-
-### Verify, checkpoint, undo
-
-The same loop works from the command line:
-
-```bash
-npx @seybel/breakhound verify /pricing      # compare with the last full scan
-npx @seybel/breakhound checkpoint /pricing -m "Let the pricing table shrink"
-npx @seybel/breakhound undo /pricing        # revert just that fix
-npx @seybel/breakhound undo --session       # revert every fix since the scan
-npx @seybel/breakhound undo                 # list the fixes you can undo
-```
-
-Checkpoints are ordinary commits with a `Breakhound-Route:` trailer, and undo makes a new commit that reverts them: history is never rewritten. breakhound never commits changes you had before the scan (it stops and says so), and undo refuses to run over uncommitted work.
-
-### Point the agent at the right line
-
-In development, breakhound reads where elements come from out of React's and Vue's dev info, which usually gives the component and its file. For the exact line of every element, add the plugin (development only, production builds are untouched):
-
-```ts
-// vite.config.ts (React, Vue, Svelte, Preact, Solid; Nuxt: under `vite.plugins`)
-import breakhound from '@seybel/breakhound/vite';
-export default defineConfig({ plugins: [breakhound(), react()] });
-```
-
-```js
-// next.config.mjs (Turbopack and webpack)
-import { withBreakhound } from '@seybel/breakhound/next';
-export default withBreakhound({ /* your config */ });
-```
-
-```js
-// webpack.config.js
-const { BreakhoundPlugin } = require('@seybel/breakhound/webpack');
-module.exports = { plugins: [new BreakhoundPlugin()] };
-```
-
-Each HTML element gets a `data-bh-src="src/components/Nav.tsx:42:7"` attribute on the dev server, and reports and prompts show `Source: src/components/Nav.tsx:42`.
-
-## Configuration
-
-Optional. `npx @seybel/breakhound init` creates one. If breakhound is in your dev dependencies you get `breakhound.config.ts` (or `.mjs` without TypeScript), fully typed:
-
-```ts
-import { defineConfig } from '@seybel/breakhound';
-
-export default defineConfig({
-  exclude: ['/admin/**'],                       // or include: ['/blog/**']
-  samples: { '/products/[id]': '/products/42' },
-  widths: { min: 320, max: 1920 },
-  ignore: ['.intercom-launcher', { selector: '.map', detectors: ['overlap'] }],
-  detectors: { 'tiny-text': false, 'edge-gutter': 'info' },
-  failOn: 'error',
-});
-```
-
-Running breakhound through `npx` without installing it, you get `breakhound.config.json` instead. A TypeScript file importing a package that isn't installed would break your project's own type check (and builds that run it, like `next build`). The JSON file points at breakhound's schema, so your editor still suggests and explains every option:
-
-```json
-{
-  "$schema": "https://cdn.jsdelivr.net/npm/@seybel/breakhound/dist/schema.json",
-  "exclude": ["/admin/**"]
-}
-```
-
-`.js`, `.cjs` and `.mts` configs work too. The types ship for both `import` and `require`.
-
-| Option | What it does |
-|---|---|
-| `baseUrl` | Scan this server instead of finding or starting the dev server |
-| `routes` | Scan exactly these routes instead of discovering them |
-| `include`, `exclude` | Route globs: `*` is one segment, `**` any number |
-| `samples` | A real URL for a dynamic route |
-| `params` | Real values for dynamic route parameters by name, for every route that uses them |
-| `maxRoutes` | Most routes per run (default 100) |
-| `server` | How to start the app: `{ command: 'npm run preview', port: 4173, timeout: 120 }` |
-| `widths` | `{ min, max, step }` in CSS pixels |
-| `ignore`, `detectors` | Leave elements out, turn checks off or change their severity |
-| `failOn` | Exit 1 at `error`, `warning`, `info` or `none` |
-| `vision` | `true` to add a vision model's opinion, or `{ model, provider, widths }` |
-| `fix` | The model `breakhound fix` uses: `{ provider: 'ollama', model: 'qwen2.5-coder' }` |
-| `browsers` | Engines to check in: `["chromium", "webkit", "firefox"]` (default Chromium only) |
-| `states` | Most menus, dialogs, tabs and expandable sections to open per page (default 5), or `false` |
-| `concurrency` | Browser tabs to use at once (default half your CPU cores, up to 4) |
-| `memoryLimit` | Most memory the dev server and browser may use together, e.g. `"6GB"`, `"50%"` or `"off"` (default 60% of your memory) |
-
-You can also mark elements in your markup:
-
-```html
-<div data-breakhound-ignore>...</div>                      <!-- every check -->
-<div data-breakhound-ignore="overlap small-tap-target">...</div>
-```
+That sets it up for Claude Code, Cursor, VS Code, Antigravity, Windsurf and Codex. Then ask your agent to fix the responsive issues: it can scan, verify that each fix didn't break another width or page, commit each fix on its own, and undo it. No MCP? `npx @seybel/breakhound prompt --copy` gives you instructions to paste into any agent. [More →](https://seybel.github.io/breakhound/guide/agents)
 
-## CLI
-
-Run these with `npx @seybel/breakhound`, or as `breakhound` after `npm i -g @seybel/breakhound`. Installed in a project, it's `npx breakhound` or an npm script.
-
-```
-breakhound                     Find your app and scan every route
-breakhound /pricing /blog      Scan only these routes of your app
-breakhound <url or file ...>   Scan just these pages
-breakhound login [route]       Log in once in a browser window; later scans reuse the session
-breakhound report              Open the last HTML report
-breakhound prompt              Print the fix prompt (--copy to copy it, --all to include info)
-breakhound init                Create a config file
-breakhound install [browsers]  Download Chromium, or webkit and firefox (--with-deps adds Linux libraries)
-
-breakhound verify [routes]     Scan again and compare with the last full scan (--all to count info)
-breakhound checkpoint <routes> Commit the current changes as the fix for these routes (-m message)
-breakhound undo [routes]       Revert the fixes for these routes (--session for all)
-breakhound mcp install         Add the MCP server to your agents (--client, --yes)
-breakhound mcp                 Run the MCP server (your agent starts it)
-
---url <url>             Where your app runs (skips finding the dev server)
---include <glob>        Only scan matching routes (repeatable)
---exclude <glob>        Skip matching routes (repeatable)
---max-routes <n>        Most routes to scan (default 100)
---min <px> --max <px>   Width range (default 320 to 1920)
---fail-on <level>       Exit 1 at error, warning, info or none (default error)
---pdf                   Also write report.pdf
---no-screenshots        Skip screenshots
---no-states             Don't open menus, dialogs, tabs and expandable sections
---browsers <list>       Also check other engines, e.g. chromium,webkit,firefox
---vision                Also ask your own vision model what looks off (info only)
---concurrency <n>       Browser tabs to use at once
---memory-limit <size>   Memory the dev server and browser may use, e.g. 6GB, 50% or off
---out <dir>             Report folder (default .breakhound)
---open                  Open the report when done
--q, --quiet             Only print errors
-```
-
-While it runs, breakhound watches the memory of the dev server it started (and everything that server runs) and of its browser, along with how much memory your system has left. If they grow past `memoryLimit`, or the system runs out of memory, it shuts them down at once and tells you what used the memory and what to try. It only ever stops processes it started itself.
-
-Exit codes: `0` clean, `1` issues at or above `--fail-on`, `2` a page couldn't be checked (it failed to load, answered with an HTTP error, or rendered nothing). Pages behind a login and dynamic routes without a URL are reported but don't fail the run.
-
-## CI
-
-On GitHub Actions, after installing your dependencies:
+## In CI
 
 ```yaml
 - uses: Seybel/breakhound@v1
   with:
     fail-on: error
-    # url: ${{ steps.deploy.outputs.preview-url }}   # or scan a preview deployment
 ```
 
-It starts your dev server (or scans `url`), turns each issue into an annotation, adds the summary to the job page, and uploads the report as an artifact.
+It starts your dev server (or scans a preview deployment), turns each issue into an annotation, and uploads the report as an artifact. [More →](https://seybel.github.io/breakhound/guide/ci)
 
-Anywhere else, `npx @seybel/breakhound install --with-deps && npx @seybel/breakhound` does the same job; `CI=true` keeps it from opening windows or asking questions.
+## Docs
 
-## Development
-
-```bash
-npm install
-npx playwright install chromium
-npm test            # accuracy suite in real Chromium, plus unit tests
-npm run typecheck
-npm run lint
-npm run build       # builds the publishable package in packages/cli/dist
-npm run build:extension   # builds the DevTools panel in packages/extension/dist
-npm run dev -- http://localhost:3000
-```
+- [Getting started](https://seybel.github.io/breakhound/guide/getting-started) and [your first scan](https://seybel.github.io/breakhound/guide/first-scan)
+- [Recipes](https://seybel.github.io/breakhound/guide/recipes) for common jobs
+- [Configuration](https://seybel.github.io/breakhound/reference/config) and the [CLI](https://seybel.github.io/breakhound/reference/cli)
 
-`fixtures/pages` is the accuracy benchmark: pages with planted bugs (marked with `data-bh-expect`) and pages full of tricky-but-fine patterns that must stay clean. Every detector change has to keep it at 100%.
+## Contributing
 
-Found a false positive, or a bug breakhound missed? That's the most useful thing to report: see [CONTRIBUTING.md](https://github.com/Seybel/breakhound/blob/main/CONTRIBUTING.md). How it all works is in [docs/DESIGN.md](https://github.com/Seybel/breakhound/blob/main/docs/DESIGN.md).
+Found a false positive, or a bug breakhound missed? That's the most useful thing to report. See [CONTRIBUTING.md](https://github.com/Seybel/breakhound/blob/main/CONTRIBUTING.md) for that and for working on the code.
 
 ## License
 

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { existsSync as existsSync16 } from "fs";
-import { join as join18, resolve as resolve7 } from "path";
+import { join as join19, resolve as resolve7 } from "path";
 import { parseArgs, styleText as styleText9 } from "util";
 
 // ../engine/src/index.ts
@@ -2107,11 +2107,12 @@ async function printPdf(html, file) {
 
 // src/auth.ts
 import { existsSync as existsSync7, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname4, join as join8 } from "path";
+import { dirname as dirname4, join as join9 } from "path";
 import { createInterface } from "readline";
 import { styleText as styleText3 } from "util";
 
 // src/app.ts
+import { join as join7 } from "path";
 import { styleText } from "util";
 
 // ../routes/src/ast.ts
@@ -2917,8 +2918,8 @@ function staticRoutes(project) {
 }
 
 // ../routes/src/project.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname2, join as join5 } from "path";
+import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname2, join as join5, relative as relative3 } from "path";
 var FRAMEWORKS = {
   next: { name: "Next.js", routing: "files" },
   nuxt: { name: "Nuxt", routing: "code" },
@@ -3052,11 +3053,69 @@ function normalizeBasePath(path) {
   if (!trimmed) return "";
   return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
 }
+var RUNS_PACKAGES = /\b(turbo|nx|lerna|moon)\b|\bpnpm\b.*\s(-r|--recursive|--filter|-F)\b|\b(npm|yarn|bun)\b.*\s(--workspaces?|-w|--filter|workspaces?)\b/;
+function workspaceDirs(root, pkg) {
+  const globs = Array.isArray(pkg.workspaces) ? [...pkg.workspaces] : [...pkg.workspaces?.packages ?? []];
+  const pnpm = join5(root, "pnpm-workspace.yaml");
+  if (existsSync4(pnpm)) {
+    let inPackages = false;
+    for (const line of readFileSync5(pnpm, "utf8").split(/\r?\n/)) {
+      if (/^packages\s*:/.test(line)) inPackages = true;
+      else if (/^\S/.test(line)) inPackages = false;
+      else if (inPackages) {
+        const item = line.match(/^\s*-\s*['"]?([^'"#]+?)['"]?\s*(?:#.*)?$/)?.[1];
+        if (item) globs.push(item);
+      }
+    }
+  }
+  const expand = (dir, parts, depth = 0) => {
+    const [part, ...rest2] = parts;
+    if (part === void 0) return [dir];
+    if (part === "." || part === "") return expand(dir, rest2, depth);
+    if (!part.includes("*"))
+      return existsSync4(join5(dir, part)) ? expand(join5(dir, part), rest2, depth) : [];
+    let subdirs;
+    try {
+      subdirs = readdirSync2(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && d.name !== "node_modules" && !d.name.startsWith(".")).map((d) => d.name);
+    } catch {
+      return [];
+    }
+    if (part === "**") {
+      return [
+        ...expand(dir, rest2, depth),
+        ...depth < 3 ? subdirs.flatMap((d) => expand(join5(dir, d), parts, depth + 1)) : []
+      ];
+    }
+    const match = new RegExp(
+      `^${part.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`
+    );
+    return subdirs.filter((d) => match.test(d)).flatMap((d) => expand(join5(dir, d), rest2, depth));
+  };
+  const of = (globs2) => globs2.flatMap((g) => expand(root, g.replace(/\/+$/, "").split("/")));
+  const left = new Set(of(globs.filter((g) => g.startsWith("!")).map((g) => g.slice(1))));
+  return [...new Set(of(globs.filter((g) => !g.startsWith("!"))))].filter((d) => !left.has(d));
+}
+function workspaceApps(root, pkg) {
+  return workspaceDirs(root, pkg).filter((dir) => {
+    const app = readJson(join5(dir, "package.json"));
+    if (!app) return false;
+    const framework = detectFramework({ ...app.dependencies, ...app.devDependencies });
+    const script = pickDevScript(app.scripts ?? {});
+    return framework.id !== "unknown" && !!script && DEV_SERVER.test(script.command);
+  });
+}
 function detectProject(cwd) {
   const pkg = readJson(join5(cwd, "package.json"));
   if (!pkg) return null;
   const deps = { ...pkg.dependencies, ...pkg.devDependencies };
   const framework = detectFramework(deps);
+  const own = pickDevScript(pkg.scripts ?? {});
+  const isApp = framework.id !== "unknown" && !!own && !RUNS_PACKAGES.test(own.command);
+  const apps = isApp ? [] : workspaceApps(cwd, pkg);
+  if (apps.length === 1) {
+    const app = detectProject(apps[0]);
+    if (app) return { ...app, workspace: relative3(cwd, apps[0]) };
+  }
   const devScript = pickDevScript(pkg.scripts ?? {});
   const defaultPort = DEFAULT_PORT[framework.id];
   const configured = [...new Set(configuredPorts(cwd, devScript?.command))];
@@ -3068,7 +3127,8 @@ function detectProject(cwd) {
     devScript,
     ports: [...new Set(ports)],
     configuredPorts: configured,
-    basePath: detectBasePath(cwd)
+    basePath: detectBasePath(cwd),
+    ...apps.length > 1 ? { apps: apps.map((a) => relative3(cwd, a)) } : {}
   };
 }
 
@@ -3266,14 +3326,14 @@ var RouteQueue = class {
 function readRuntimeRoutes() {
   const w = window;
   const paths = /* @__PURE__ */ new Set();
-  const join19 = (base, path) => path.startsWith("/") ? path : `${base.replace(/\/?\*$/, "").replace(/\/+$/, "")}/${path}`;
+  const join20 = (base, path) => path.startsWith("/") ? path : `${base.replace(/\/?\*$/, "").replace(/\/+$/, "")}/${path}`;
   const manifest = w.__reactRouterManifest?.routes ?? w.__remixManifest?.routes;
   if (manifest && typeof manifest === "object") {
     const fullPath = (id, depth = 0) => {
       const r = manifest[id];
       if (!r || depth > 50) return "";
       const parent = r.parentId ? fullPath(r.parentId, depth + 1) : "";
-      return r.path ? join19(parent, r.path) : parent;
+      return r.path ? join20(parent, r.path) : parent;
     };
     for (const id of Object.keys(manifest)) {
       const r = manifest[id];
@@ -3320,7 +3380,7 @@ function readRuntimeRoutes() {
         if (e?.props?.children && !e.props.path) walkElements(e.props.children, base);
         continue;
       }
-      const full = typeof e.props.path === "string" ? join19(base, e.props.path) : base;
+      const full = typeof e.props.path === "string" ? join20(base, e.props.path) : base;
       if (typeof e.props.path === "string") paths.add(full);
       else if (e.props.index) paths.add(indexPath2(base));
       walkElements(e.props.children, full);
@@ -3330,7 +3390,7 @@ function readRuntimeRoutes() {
     if (!Array.isArray(routes) || depth > 30) return;
     for (const r of routes) {
       if (!r || typeof r !== "object") continue;
-      const full = typeof r.path === "string" ? join19(base, r.path) : base;
+      const full = typeof r.path === "string" ? join20(base, r.path) : base;
       if (typeof r.path === "string") paths.add(full);
       else if (r.index) paths.add(indexPath2(base));
       walkObjects(r.children, full, depth + 1);
@@ -3342,7 +3402,7 @@ function readRuntimeRoutes() {
       if (Array.isArray(matches) && matches.length) {
         let base = "";
         for (const m of matches)
-          if (typeof m.route?.path === "string") base = join19(base, m.route.path);
+          if (typeof m.route?.path === "string") base = join20(base, m.route.path);
         return base;
       }
     }
@@ -3371,7 +3431,7 @@ function readRuntimeRoutes() {
         if (Array.isArray(matches)) {
           let base = "";
           for (const m of matches) {
-            if (typeof m?.route?.path === "string") base = join19(base, m.route.path);
+            if (typeof m?.route?.path === "string") base = join20(base, m.route.path);
             if (Array.isArray(m?.route?.children)) {
               kind ??= "react-router";
               walkObjects(m.route.children, base);
@@ -3555,7 +3615,7 @@ async function startServer(project, options = {}) {
   }
   const timeoutMs = options.timeoutMs ?? 12e4;
   const child = spawn(command, {
-    cwd: project.root,
+    cwd: options.cwd ?? project.root,
     shell: true,
     detached: process.platform !== "win32",
     stdio: ["ignore", "pipe", "pipe"],
@@ -3592,6 +3652,13 @@ async function startServer(project, options = {}) {
   let failingSince = null;
   while (Date.now() < deadline) {
     if (child.exitCode !== null) {
+      const printed2 = printedUrl;
+      const page = printed2 ? await probe(`${printed2}/`, 5e3) : null;
+      if (printed2 && page && page.status < 500 && looksLikeProject(project, page, true)) {
+        process.removeListener("exit", cleanup);
+        return { url: printed2, alreadyRunning: true, stop: async () => {
+        } };
+      }
       throw new Error(
         `The dev server (${command}) stopped before it was ready:
 ${output.slice(-15).join("\n")}`
@@ -3946,9 +4013,34 @@ async function resolveServer(cwd, config, quiet) {
       "No package.json here, so there is no app to find. Run breakhound in your project folder, or pass a URL: npx @seybel/breakhound http://localhost:3000"
     );
   }
-  if (config.server?.port) {
-    project.ports = [config.server.port, ...project.ports.filter((p) => p !== config.server?.port)];
-    project.configuredPorts = [config.server.port, ...project.configuredPorts];
+  const withPort = (p) => {
+    const port = config.server?.port;
+    if (!port) return p;
+    p.ports = [port, ...p.ports.filter((q) => q !== port)];
+    p.configuredPorts = [port, ...p.configuredPorts];
+    return p;
+  };
+  withPort(project);
+  if (project.workspace) log(quiet, styleText("dim", `Using the app in ${project.workspace}`));
+  if (project.apps && !config.server?.command) {
+    const found = await Promise.all(
+      project.apps.map(async (dir2) => {
+        const found2 = detectProject(join7(cwd, dir2));
+        const app2 = found2 && withPort(found2);
+        const running3 = app2 ? await findRunningServer(app2) : null;
+        return app2 && running3 ? { dir: dir2, app: app2, running: running3 } : null;
+      })
+    );
+    const live = found.filter((f) => f !== null);
+    if (live.length !== 1 || !live[0]) {
+      throw new Error(
+        `This is a monorepo with ${project.apps.length} apps (${project.apps.join(", ")}). Run breakhound in the one to scan, e.g. cd ${project.apps[0]} && npx @seybel/breakhound, or start its dev server first.`
+      );
+    }
+    const { dir, app, running: running2 } = live[0];
+    const baseUrl2 = withBasePath(running2.url, app.basePath);
+    log(quiet, `${styleText("green", "\u2714")} ${app.framework.name} in ${dir} running at ${baseUrl2}`);
+    return { project: { ...app, workspace: dir }, baseUrl: baseUrl2, server: null };
   }
   const running = config.server?.command ? null : await findRunningServer(project);
   if (running) {
@@ -3961,7 +4053,8 @@ async function resolveServer(cwd, config, quiet) {
   log(quiet, styleText("dim", `Starting ${name ?? "the app"} with ${label}...`));
   let pid;
   const started = await startServer(project, {
-    ...command ? { command } : {},
+    // A command from the config runs where breakhound was run, like the user would run it.
+    ...command ? { command, cwd } : {},
     ...config.server?.port ? { port: config.server.port } : {},
     ...config.server?.timeout ? { timeoutMs: config.server.timeout * 1e3 } : {},
     onSpawn: (id) => {
@@ -3972,6 +4065,12 @@ async function resolveServer(cwd, config, quiet) {
     guard.untrackServer(pid);
     throw error;
   });
+  if (started.alreadyRunning) {
+    guard.untrackServer(pid);
+    const baseUrl2 = withBasePath(started.url, project.basePath);
+    log(quiet, `${styleText("green", "\u2714")} ${name ?? "App"} already running at ${baseUrl2}`);
+    return { project, baseUrl: baseUrl2, server: null };
+  }
   const server2 = {
     ...started,
     stop: async () => {
@@ -4058,7 +4157,7 @@ async function planRoutes(app, config, scanner, explicit) {
 import { spawnSync as spawnSync3 } from "child_process";
 import { existsSync as existsSync6, readFileSync as readFileSync8 } from "fs";
 import { createRequire as createRequire2 } from "module";
-import { dirname as dirname3, join as join7 } from "path";
+import { dirname as dirname3, join as join8 } from "path";
 import { styleText as styleText2 } from "util";
 var DOWNLOAD_MB = { chromium: 150, webkit: 80, firefox: 90 };
 function installed(name) {
@@ -4086,7 +4185,7 @@ function playwrightCli() {
   const manifest = require2.resolve("playwright/package.json");
   const { bin } = JSON.parse(readFileSync8(manifest, "utf8"));
   const file = typeof bin === "string" ? bin : bin?.playwright ?? "cli.js";
-  return join7(dirname3(manifest), file);
+  return join8(dirname3(manifest), file);
 }
 function installBrowsers(names, withDeps) {
   const cli = playwrightCli();
@@ -4117,7 +4216,7 @@ async function runLogin(cwd, config, options = {}) {
   };
   ensureBrowsers();
   const app = await resolveServer(cwd, config, options.quiet ?? false);
-  const file = join8(cwd, AUTH_FILE);
+  const file = join9(cwd, AUTH_FILE);
   const browser = await launch(Boolean(automate));
   try {
     const context = await browser.newContext({
@@ -4243,7 +4342,7 @@ function copyToClipboard(text2) {
 
 // src/config.ts
 import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
-import { join as join9, resolve as resolve2 } from "path";
+import { join as join10, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var CONFIG_FILES = [
   "breakhound.config.ts",
@@ -4261,7 +4360,7 @@ function selfModule() {
   return "@seybel/breakhound";
 }
 async function loadConfig(cwd, explicit) {
-  const file = explicit ? resolve2(cwd, explicit) : CONFIG_FILES.map((f) => join9(cwd, f)).find((f) => existsSync8(f));
+  const file = explicit ? resolve2(cwd, explicit) : CONFIG_FILES.map((f) => join10(cwd, f)).find((f) => existsSync8(f));
   if (!file) return { config: {}, file: null, warnings: [] };
   if (!existsSync8(file)) throw new Error(`Config file not found: ${file}`);
   let config;
@@ -4444,14 +4543,14 @@ function normalizeIgnore(ignore) {
 // src/fix.ts
 import { execFileSync } from "child_process";
 import { existsSync as existsSync12, readFileSync as readFileSync14, statSync as statSync3, writeFileSync as writeFileSync6 } from "fs";
-import { join as join13, normalize as normalize2 } from "path";
+import { join as join14, normalize as normalize2 } from "path";
 import { styleText as styleText6 } from "util";
 
 // src/session.ts
 import { spawnSync as spawnSync5 } from "child_process";
 import { randomBytes } from "crypto";
 import { existsSync as existsSync9, readFileSync as readFileSync11, realpathSync, writeFileSync as writeFileSync3 } from "fs";
-import { join as join10, relative as relative3, resolve as resolve3, sep as sep2 } from "path";
+import { join as join11, relative as relative4, resolve as resolve3, sep as sep2 } from "path";
 var SESSION_FILE = "session.json";
 function git(cwd, args, input) {
   const run2 = spawnSync5("git", args, {
@@ -4484,7 +4583,7 @@ function fromRoot(root, cwd, path) {
     base = realpathSync(cwd);
   } catch {
   }
-  return relative3(root, resolve3(base, path)).split(sep2).join("/");
+  return relative4(root, resolve3(base, path)).split(sep2).join("/");
 }
 function changedFiles(cwd, outDir = ".breakhound") {
   const root = gitRoot(cwd);
@@ -4503,7 +4602,7 @@ function changedFiles(cwd, outDir = ".breakhound") {
   return files.filter((f) => f !== skip && !f.startsWith(`${skip}/`));
 }
 function sessionPath(cwd, outDir) {
-  return join10(resolve3(cwd, outDir), SESSION_FILE);
+  return join11(resolve3(cwd, outDir), SESSION_FILE);
 }
 function readSession(cwd, outDir = ".breakhound") {
   const file = sessionPath(cwd, outDir);
@@ -4710,11 +4809,11 @@ function undo(cwd, req) {
 
 // src/verify.ts
 import { existsSync as existsSync11, readFileSync as readFileSync13, writeFileSync as writeFileSync5 } from "fs";
-import { join as join12, resolve as resolve5 } from "path";
+import { join as join13, resolve as resolve5 } from "path";
 
 // src/scan.ts
-import { existsSync as existsSync10, readdirSync as readdirSync2, readFileSync as readFileSync12, rmSync, statSync as statSync2, writeFileSync as writeFileSync4 } from "fs";
-import { isAbsolute, join as join11, relative as relative5, resolve as resolve4, sep as sep3 } from "path";
+import { existsSync as existsSync10, readdirSync as readdirSync3, readFileSync as readFileSync12, rmSync, statSync as statSync2, writeFileSync as writeFileSync4 } from "fs";
+import { isAbsolute, join as join12, relative as relative6, resolve as resolve4, sep as sep3 } from "path";
 import { fileURLToPath as fileURLToPath3, pathToFileURL } from "url";
 import { styleText as styleText5 } from "util";
 
@@ -4872,7 +4971,7 @@ ${SETUP}`
 }
 
 // src/print.ts
-import { relative as relative4 } from "path";
+import { relative as relative5 } from "path";
 import { styleText as styleText4 } from "util";
 var BADGE = {
   error: styleText4("red", "\u2716 error  "),
@@ -4949,7 +5048,7 @@ function printIssues(result) {
 }
 function printFooter(paths, result, cwd) {
   const rel = (p) => {
-    const r = relative4(cwd, p);
+    const r = relative5(cwd, p);
     return r.startsWith("..") ? p : r;
   };
   console.log("");
@@ -5134,7 +5233,7 @@ function routeOf(url, cwd) {
   const u = new URL(url);
   if (u.protocol === "file:") {
     const path = fileURLToPath3(u);
-    const rel = relative5(cwd, path);
+    const rel = relative6(cwd, path);
     return rel.startsWith("..") ? path : rel;
   }
   return `${u.pathname}${u.search}` || "/";
@@ -5142,9 +5241,9 @@ function routeOf(url, cwd) {
 var SCREENSHOT_FILE = /^[0-9a-f]{10}\.png$/;
 function clearScreenshots(dir) {
   if (!existsSync10(dir)) return;
-  for (const name of readdirSync2(dir)) {
-    if (SCREENSHOT_FILE.test(name)) rmSync(join11(dir, name), { force: true });
-    else if (BROWSER_NAMES.includes(name)) clearScreenshots(join11(dir, name));
+  for (const name of readdirSync3(dir)) {
+    if (SCREENSHOT_FILE.test(name)) rmSync(join12(dir, name), { force: true });
+    else if (BROWSER_NAMES.includes(name)) clearScreenshots(join12(dir, name));
   }
 }
 function resolveTargets(targets, config, cwd) {
@@ -5170,25 +5269,26 @@ function projectPath(file, root, basePath = "") {
   if (isAbsolute(path)) candidates.push(path);
   if (path.startsWith("/")) {
     const inApp = basePath && path.startsWith(`${basePath}/`) ? path.slice(basePath.length) : path;
-    candidates.push(join11(root, inApp));
+    candidates.push(join12(root, inApp));
   } else {
-    candidates.push(join11(root, path));
+    candidates.push(join12(root, path));
   }
   for (const candidate of candidates) {
-    const rel = relative5(root, candidate);
+    const rel = relative6(root, candidate);
     if (!rel.startsWith("..") && !isAbsolute(rel) && isFile(candidate))
       return rel.split(sep3).join("/");
   }
   return null;
 }
-function relativeSources(routes, root, basePath) {
+function relativeSources(routes, root, basePath, workspace = "") {
+  const prefix = workspace ? `${workspace.split(sep3).join("/")}/` : "";
   for (const route of routes) {
     for (const issue of route.issues) {
       for (const element of [issue.element, issue.related]) {
         const source = element?.source;
         if (!element || !source) continue;
         const file = projectPath(source.file, root, basePath);
-        element.source = file ? { ...source, file } : null;
+        element.source = file ? { ...source, file: `${prefix}${file}` } : null;
       }
     }
   }
@@ -5245,11 +5345,11 @@ async function scan(req) {
   const pageMode = jobs ? jobs.every((j) => !j.url.startsWith("http")) : req.targets.length > 0 && req.targets.every((t) => isPageTarget(t, cwd));
   const pageTargets = jobs && pageMode ? jobs : pageMode ? resolveTargets(req.targets, config, cwd) : [];
   const outDir = resolve4(cwd, config.outDir ?? ".breakhound");
-  const screenshotDir = join11(outDir, "screenshots");
+  const screenshotDir = join12(outDir, "screenshots");
   const browsers = config.browsers?.length ? config.browsers : ["chromium"];
   const [firstBrowser = "chromium", ...otherBrowsers] = browsers;
   ensureBrowsers(browsers);
-  const authFile = join11(cwd, AUTH_FILE);
+  const authFile = join12(cwd, AUTH_FILE);
   const auth = existsSync10(authFile) ? { storageState: authFile } : {};
   const scanner = new Scanner({ ...auth, browser: firstBrowser });
   const startedAt = /* @__PURE__ */ new Date();
@@ -5369,7 +5469,7 @@ async function scan(req) {
           const result2 = await other.scanPage(route.url, {
             ...baseOptions,
             route: route.route,
-            ...baseOptions.screenshotDir ? { screenshotDir: join11(baseOptions.screenshotDir, browser) } : {}
+            ...baseOptions.screenshotDir ? { screenshotDir: join12(baseOptions.screenshotDir, browser) } : {}
           });
           for (const i of result2.issues)
             if (i.screenshot) i.screenshot = `${browser}/${i.screenshot}`;
@@ -5440,7 +5540,12 @@ async function scan(req) {
     if (!req.app) await app?.server?.stop();
   }
   applySeverity(routes, config);
-  relativeSources(routes, app?.project?.root ?? cwd, app?.project?.basePath ?? "");
+  relativeSources(
+    routes,
+    app?.project?.root ?? cwd,
+    app?.project?.basePath ?? "",
+    app?.project?.workspace
+  );
   const firstUrl = pageTargets[0]?.url;
   const baseUrl = app?.baseUrl ?? config.baseUrl ?? (firstUrl?.startsWith("http") ? new URL(firstUrl).origin : null);
   const framework = app?.project?.framework;
@@ -5458,7 +5563,7 @@ async function scan(req) {
   const kept = req.app ? app : null;
   if (req.write === false) return { result, reports: null, app: kept };
   const reports = await saveReports(result, config, cwd);
-  const baselineFile = join11(outDir, BASELINE_FILE);
+  const baselineFile = join12(outDir, BASELINE_FILE);
   const earlier = !pageMode && req.targets.length > 0 && existsSync10(baselineFile) ? JSON.parse(readFileSync12(baselineFile, "utf8")) : null;
   const baseline = earlier && !earlier.from ? mergeScans(earlier, result) : result;
   writeFileSync4(baselineFile, `${JSON.stringify(baseline, null, 2)}
@@ -5479,7 +5584,7 @@ async function saveExtensionScan(sent, config, cwd) {
     issues: r.issues.filter((i) => off[i.detector] !== false)
   }));
   applySeverity(routes, config);
-  relativeSources(routes, project?.root ?? cwd, project?.basePath ?? "");
+  relativeSources(routes, project?.root ?? cwd, project?.basePath ?? "", project?.workspace);
   const framework = project?.framework;
   const result = createScanResult(routes, {
     version: sent.tool.version,
@@ -5493,9 +5598,9 @@ async function saveExtensionScan(sent, config, cwd) {
     from: "extension"
   });
   const outDir = resolve4(cwd, config.outDir ?? ".breakhound");
-  clearScreenshots(join11(outDir, "screenshots"));
+  clearScreenshots(join12(outDir, "screenshots"));
   await saveReports(result, config, cwd);
-  writeFileSync4(join11(outDir, BASELINE_FILE), `${JSON.stringify(result, null, 2)}
+  writeFileSync4(join12(outDir, BASELINE_FILE), `${JSON.stringify(result, null, 2)}
 `);
   touchSession(cwd, config.outDir ?? ".breakhound");
   return result;
@@ -5503,14 +5608,14 @@ async function saveExtensionScan(sent, config, cwd) {
 function saveReports(result, config, cwd) {
   const outDir = resolve4(cwd, config.outDir ?? ".breakhound");
   return writeReports(result, outDir, {
-    screenshotDir: join11(outDir, "screenshots"),
+    screenshotDir: join12(outDir, "screenshots"),
     pdf: config.pdf ?? false,
     verifyCommand: "npx @seybel/breakhound verify"
   });
 }
 function readLastResult(cwd, outDir = ".breakhound") {
   const dir = resolve4(cwd, outDir);
-  const file = join11(dir, "result.json");
+  const file = join12(dir, "result.json");
   if (!existsSync10(file)) throw new Error("No scan yet. Run breakhound first.");
   return { result: JSON.parse(readFileSync12(file, "utf8")), dir };
 }
@@ -5537,7 +5642,7 @@ function mergeScans(earlier, now) {
 function readBaseline(cwd, outDir = ".breakhound") {
   const dir = resolve5(cwd, outDir);
   for (const name of [BASELINE_FILE, "result.json"]) {
-    const file = join12(dir, name);
+    const file = join13(dir, name);
     if (existsSync11(file)) return JSON.parse(readFileSync13(file, "utf8"));
   }
   throw new Error("Nothing to verify against yet. Run breakhound first to scan the app.");
@@ -5676,7 +5781,7 @@ async function finishVerify(req, baseline, result) {
   const outcome = { baselineAt: baseline.startedAt, ...diff, current, reports };
   const dir = resolve5(req.cwd, req.config.outDir ?? ".breakhound");
   const { current: _, reports: __, ...saved } = outcome;
-  writeFileSync5(join12(dir, "verify.json"), `${JSON.stringify(saved, null, 2)}
+  writeFileSync5(join13(dir, "verify.json"), `${JSON.stringify(saved, null, 2)}
 `);
   return outcome;
 }
@@ -5794,12 +5899,12 @@ function pickFiles(cwd, issue, tracked = trackedFiles(cwd)) {
   const terms = searchTerms(issue);
   const scores = /* @__PURE__ */ new Map();
   for (const source of [issue.element.source, issue.related?.source]) {
-    if (source?.file && existsSync12(join13(cwd, source.file))) {
+    if (source?.file && existsSync12(join14(cwd, source.file))) {
       scores.set(source.file, (scores.get(source.file) ?? 0) + 100);
     }
   }
   for (const file of tracked) {
-    const full = join13(cwd, file);
+    const full = join14(cwd, file);
     try {
       if (statSync3(full).size > MAX_SCAN_BYTES) continue;
       const content = readFileSync14(full, "utf8");
@@ -5808,7 +5913,7 @@ function pickFiles(cwd, issue, tracked = trackedFiles(cwd)) {
     } catch {
     }
   }
-  return [...scores.entries()].sort((a, b) => b[1] - a[1]).slice(0, MAX_FILES3).map(([path]) => ({ path, content: excerpt(readFileSync14(join13(cwd, path), "utf8"), terms) }));
+  return [...scores.entries()].sort((a, b) => b[1] - a[1]).slice(0, MAX_FILES3).map(([path]) => ({ path, content: excerpt(readFileSync14(join14(cwd, path), "utf8"), terms) }));
 }
 function parseEdits(reply) {
   const edits = [];
@@ -5855,7 +5960,7 @@ function applyEdits(cwd, edits, allowed) {
   const originals = /* @__PURE__ */ new Map();
   for (const edit of edits) {
     if (!allowed.has(edit.file)) return { error: `${edit.file} wasn't one of the files given.` };
-    const current = next.get(edit.file) ?? readFileSync14(join13(cwd, edit.file), "utf8");
+    const current = next.get(edit.file) ?? readFileSync14(join14(cwd, edit.file), "utf8");
     if (!originals.has(edit.file)) originals.set(edit.file, current);
     const at = locate(current, edit.search);
     if (at === "many") {
@@ -5867,11 +5972,11 @@ function applyEdits(cwd, edits, allowed) {
       return { error: `The search text for ${edit.file} isn't in the file. Copy it exactly.` };
     next.set(edit.file, current.slice(0, at.start) + edit.replace + current.slice(at.end));
   }
-  for (const [file, content] of next) writeFileSync6(join13(cwd, file), content);
+  for (const [file, content] of next) writeFileSync6(join14(cwd, file), content);
   return { originals };
 }
 function restore2(cwd, originals) {
-  for (const [file, content] of originals) writeFileSync6(join13(cwd, file), content);
+  for (const [file, content] of originals) writeFileSync6(join14(cwd, file), content);
 }
 function promptFor(group, text2, files, feedback) {
   const parts = [text2, "", "Files:", ""];
@@ -6012,7 +6117,7 @@ async function fix(req) {
 
 // src/init.ts
 import { existsSync as existsSync13, readFileSync as readFileSync15, writeFileSync as writeFileSync7 } from "fs";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 import { styleText as styleText7 } from "util";
 var TEMPLATE = (baseUrl, typed) => `${typed ? "import { defineConfig } from '@seybel/breakhound';\n\nexport default defineConfig({" : "/** @type {import('@seybel/breakhound').BreakhoundConfig} */\nexport default {"}
   // breakhound finds your dev server, or starts it, by itself. Set this to
@@ -6049,7 +6154,7 @@ var JSON_TEMPLATE = `${JSON.stringify(
 `;
 function isInstalled(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync15(join14(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync15(join15(cwd, "package.json"), "utf8"));
     return Boolean(pkg.dependencies?.breakhound || pkg.devDependencies?.breakhound);
   } catch {
     return false;
@@ -6057,7 +6162,7 @@ function isInstalled(cwd) {
 }
 function guessBaseUrl(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync15(join14(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync15(join15(cwd, "package.json"), "utf8"));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     const dev = pkg.scripts?.dev ?? "";
     const port = dev.match(/(?:--port|-p)[ =](\d{2,5})/)?.[1];
@@ -6072,15 +6177,15 @@ function guessBaseUrl(cwd) {
   return "http://localhost:3000";
 }
 function runInit(cwd) {
-  const existing = ["ts", "mts", "js", "mjs", "cjs", "json"].map((ext) => `breakhound.config.${ext}`).find((f) => existsSync13(join14(cwd, f)));
+  const existing = ["ts", "mts", "js", "mjs", "cjs", "json"].map((ext) => `breakhound.config.${ext}`).find((f) => existsSync13(join15(cwd, f)));
   if (existing) {
     console.log(`${existing} already exists. Nothing to do.`);
     return;
   }
   const installed2 = isInstalled(cwd);
-  const typed = existsSync13(join14(cwd, "tsconfig.json"));
+  const typed = existsSync13(join15(cwd, "tsconfig.json"));
   const file = !installed2 ? "breakhound.config.json" : typed ? "breakhound.config.ts" : "breakhound.config.mjs";
-  writeFileSync7(join14(cwd, file), installed2 ? TEMPLATE(guessBaseUrl(cwd), typed) : JSON_TEMPLATE);
+  writeFileSync7(join15(cwd, file), installed2 ? TEMPLATE(guessBaseUrl(cwd), typed) : JSON_TEMPLATE);
   console.log(`${styleText7("green", "\u2714")} Created ${file}`);
   if (!installed2) {
     console.log(
@@ -6097,7 +6202,7 @@ Now run ${styleText7("bold", "npx @seybel/breakhound")}.`);
 
 // src/mcp.ts
 import { existsSync as existsSync14, readFileSync as readFileSync17 } from "fs";
-import { join as join16, resolve as resolve6 } from "path";
+import { join as join17, resolve as resolve6 } from "path";
 import { createInterface as createInterface2 } from "readline";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
@@ -6105,7 +6210,7 @@ import { fileURLToPath as fileURLToPath4 } from "url";
 import { randomUUID } from "crypto";
 import { readFileSync as readFileSync16 } from "fs";
 import { createServer } from "http";
-import { basename, join as join15 } from "path";
+import { basename, join as join16 } from "path";
 var EXTENSION_IDS = ["ddnmhnjmcokbfabeileblceehjhefkpc"];
 var POLL_MS = 25e3;
 var PICKUP_MS = 2e4;
@@ -6130,7 +6235,7 @@ function allowedOrigins() {
 }
 function projectName(root) {
   try {
-    const name = JSON.parse(readFileSync16(join15(root, "package.json"), "utf8")).name;
+    const name = JSON.parse(readFileSync16(join16(root, "package.json"), "utf8")).name;
     if (typeof name === "string" && name) return name;
   } catch {
   }
@@ -6550,7 +6655,7 @@ function createTools() {
             true
           );
         const out = { content: [{ type: "text", text: found.text }] };
-        const shot = found.issue.screenshot && join16(dir, "screenshots", found.issue.screenshot);
+        const shot = found.issue.screenshot && join17(dir, "screenshots", found.issue.screenshot);
         if (shot && existsSync14(shot)) {
           out.content.push({
             type: "image",
@@ -6683,7 +6788,7 @@ Run verify to see the issues back.`
   ];
 }
 function fixedDetails(ctx, routes) {
-  const file = join16(resolve6(ctx.root, ctx.config.outDir ?? ".breakhound"), "verify.json");
+  const file = join17(resolve6(ctx.root, ctx.config.outDir ?? ".breakhound"), "verify.json");
   if (!existsSync14(file)) return [];
   try {
     const v = JSON.parse(readFileSync17(file, "utf8"));
@@ -6754,7 +6859,7 @@ async function runMcpServer(version, io = { input: process.stdin, output: proces
       "package.json",
       "breakhound.config.json",
       "breakhound.config.ts"
-    ].some((f) => existsSync14(join16(cwd, f)));
+    ].some((f) => existsSync14(join17(cwd, f)));
     if (!looksLikeProject2 && clientCanListRoots) {
       try {
         const res = await request("roots/list");
@@ -6901,7 +7006,7 @@ async function runMcpServer(version, io = { input: process.stdin, output: proces
 import { spawnSync as spawnSync6 } from "child_process";
 import { existsSync as existsSync15, mkdirSync as mkdirSync3, readFileSync as readFileSync18, writeFileSync as writeFileSync8 } from "fs";
 import { homedir } from "os";
-import { dirname as dirname5, join as join17, relative as relative6 } from "path";
+import { dirname as dirname5, join as join18, relative as relative7 } from "path";
 import { createInterface as createInterface3 } from "readline/promises";
 import { styleText as styleText8 } from "util";
 var SERVER_NAME = "breakhound";
@@ -6967,12 +7072,12 @@ function onPath(command) {
 function allClients(cwd, home = homedir()) {
   const { command, args } = serverCommand();
   return [
-    jsonClient("claude", "Claude Code", join17(cwd, ".mcp.json"), "mcpServers", { command, args }),
-    jsonClient("cursor", "Cursor", join17(cwd, ".cursor", "mcp.json"), "mcpServers", {
+    jsonClient("claude", "Claude Code", join18(cwd, ".mcp.json"), "mcpServers", { command, args }),
+    jsonClient("cursor", "Cursor", join18(cwd, ".cursor", "mcp.json"), "mcpServers", {
       command,
       args
     }),
-    jsonClient("vscode", "VS Code", join17(cwd, ".vscode", "mcp.json"), "servers", {
+    jsonClient("vscode", "VS Code", join18(cwd, ".vscode", "mcp.json"), "servers", {
       type: "stdio",
       command,
       args,
@@ -6984,7 +7089,7 @@ function allClients(cwd, home = homedir()) {
     jsonClient(
       "antigravity",
       "Antigravity",
-      join17(cwd, ".agents", "mcp_config.json"),
+      join18(cwd, ".agents", "mcp_config.json"),
       "mcpServers",
       {
         command,
@@ -6994,26 +7099,26 @@ function allClients(cwd, home = homedir()) {
     jsonClient(
       "windsurf",
       "Windsurf",
-      join17(home, ".codeium", "windsurf", "mcp_config.json"),
+      join18(home, ".codeium", "windsurf", "mcp_config.json"),
       "mcpServers",
       { command, args }
     ),
-    codexClient(join17(home, ".codex", "config.toml"))
+    codexClient(join18(home, ".codex", "config.toml"))
   ];
 }
 function detectClients(cwd, home = homedir()) {
   const found = {
-    claude: existsSync15(join17(cwd, ".mcp.json")) || existsSync15(join17(cwd, ".claude")) || existsSync15(join17(cwd, "CLAUDE.md")) || existsSync15(join17(home, ".claude")) || onPath("claude"),
-    cursor: existsSync15(join17(cwd, ".cursor")) || existsSync15(join17(home, ".cursor")),
-    vscode: existsSync15(join17(cwd, ".vscode")) || onPath("code"),
-    antigravity: existsSync15(join17(cwd, ".agents", "mcp_config.json")) || existsSync15(join17(home, ".gemini", "config", "mcp_config.json")) || existsSync15(join17(home, ".gemini", "antigravity")) || onPath("antigravity"),
-    windsurf: existsSync15(join17(home, ".codeium", "windsurf")),
-    codex: existsSync15(join17(home, ".codex"))
+    claude: existsSync15(join18(cwd, ".mcp.json")) || existsSync15(join18(cwd, ".claude")) || existsSync15(join18(cwd, "CLAUDE.md")) || existsSync15(join18(home, ".claude")) || onPath("claude"),
+    cursor: existsSync15(join18(cwd, ".cursor")) || existsSync15(join18(home, ".cursor")),
+    vscode: existsSync15(join18(cwd, ".vscode")) || onPath("code"),
+    antigravity: existsSync15(join18(cwd, ".agents", "mcp_config.json")) || existsSync15(join18(home, ".gemini", "config", "mcp_config.json")) || existsSync15(join18(home, ".gemini", "antigravity")) || onPath("antigravity"),
+    windsurf: existsSync15(join18(home, ".codeium", "windsurf")),
+    codex: existsSync15(join18(home, ".codex"))
   };
   return allClients(cwd, home).filter((c) => found[c.id]);
 }
 function show(path, cwd) {
-  const rel = relative6(cwd, path);
+  const rel = relative7(cwd, path);
   return rel.startsWith("..") ? path.replace(homedir(), "~") : rel;
 }
 async function installMcp(cwd, options = {}) {
@@ -7279,7 +7384,7 @@ async function main(argv) {
   }
   const outDir = values.out ?? fileConfig.outDir ?? ".breakhound";
   if (command === "report") {
-    const file = join18(resolve7(cwd, outDir), "report.html");
+    const file = join19(resolve7(cwd, outDir), "report.html");
     if (!existsSync16(file)) throw new Error("No report yet. Run breakhound first.");
     openInDefaultApp(file);
     console.log(file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seybel/breakhound",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Find where your layout breaks across every viewport width, then hand the fix to your coding agent.",
   "keywords": [
     "responsive",
@@ -11,7 +11,7 @@
     "playwright",
     "mcp"
   ],
-  "homepage": "https://github.com/Seybel/breakhound#readme",
+  "homepage": "https://seybel.github.io/breakhound/",
   "bugs": {
     "url": "https://github.com/Seybel/breakhound/issues"
   },