# Webdev Agent OS v3 — Automated Inspector

The Automated Inspector converts a website into structured browser evidence, a prioritized repair backlog, and suggested values for the Webdev Agent 100-point quality scorecard.

It is designed for local development URLs, staging environments, and deployed websites.

## What it inspects

- Same-origin route discovery and crawl coverage
- HTTP route status and redirect behavior
- Failed scripts, styles, images, fonts, API calls, and other resources
- Browser console errors and uncaught runtime exceptions
- Responsive screenshots at desktop, tablet, and mobile widths
- Horizontal overflow at each requested viewport
- Page titles, descriptions, canonical information, social metadata, and heading structure
- Document language, landmarks, image alternatives, form labels, accessible names, and duplicate IDs
- Navigation timing, paint timing, layout shift, transfer size, resource count, and long tasks
- Common response protections including CSP, HSTS, MIME-sniffing protection, referrer policy, and framing protection
- Optional external-link verification

## Important boundary

Automated inspection is evidence, not final approval.

The system cannot independently determine whether the offer is persuasive, the design is appropriate for the audience, the content is legally accurate, the primary workflow completed correctly, authorization is sound, consent obligations are satisfied, or rollback is operational. Those remain part of the human quality audit and release gate.

## Start the Control Center

```bash
npm run serve
```

Open:

```text
http://127.0.0.1:8080/dashboard/
```

The Node server hosts the Control Center and exposes the local inspector API. Static hosting can display and import reports but cannot launch Chromium or write inspection results.

## Command-line usage

```bash
node scripts/inspect-site.js http://localhost:3000 \
  --output reports/my-project \
  --max-routes 12 \
  --max-depth 3 \
  --screenshot-mode all \
  --viewports desktop,tablet,mobile
```

Optional external-link verification:

```bash
node scripts/inspect-site.js https://example.com --check-external
```

If Chrome or Chromium is not detected automatically:

```bash
CHROME_PATH="C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" npm run inspect -- https://example.com
```

## Generated evidence

Each inspection directory contains:

- `report.html` — visual report with scores, findings, routes, and screenshots
- `report.json` — complete machine-readable inspection evidence
- `report.md` — portable written report
- `backlog.json` — ordered repair tasks with severity and status
- `screenshots/` — responsive visual evidence

## Score mapping

The inspector maps findings into all 11 quality categories. Each category includes a confidence level and a flag showing whether human review is still required.

Evidence-rich automated categories include:

- Responsive quality
- Accessibility heuristics
- Performance
- Technical reliability
- Security headers
- SEO foundations

Lower-confidence categories include:

- Strategy and clarity
- Content and trust
- Visual design
- UX and conversion
- Operations and maintainability

Applying inspector scores to the dashboard does not remove the responsibility to review those categories manually.

## Crawl controls

- `maxRoutes`: 1–50 same-origin routes
- `maxDepth`: 0–5 link levels from the starting URL
- `screenshotMode`: `all`, `homepage`, or `none`
- `viewports`: any combination of `desktop`, `tablet`, and `mobile`
- `navigationTimeoutMs`: per-route browser timeout
- `settleMs`: delay after page load before evidence collection

Query-string tracking parameters are removed during crawl normalization. Mail, telephone, SMS, JavaScript, and data links are not crawled.

## Release behavior

The inspector returns one of three automated states:

- `hold` — a blocker or critical defect was detected
- `conditional-hold` — high-severity defects remain
- `automated-checks-clear` — no high-severity automated defect remains

None of these states equals production approval. The Release Gate still requires workflow verification, manual accessibility review, privacy and security review, operational readiness, rollback, smoke testing, and owner approval.