laxy-verify 1.3.0 → 1.3.2

package/README.md

@@ -1,474 +1,486 @@
-# laxy-verify
-
-`laxy-verify` is a deployment blocker gate for frontend apps.
-
-Every verification run includes build, Lighthouse, E2E, multi-viewport, security audit, visual diff, broken links, console error monitoring, and stability coverage regardless of plan. Optional opt-in checks add TypeScript type checking, secret scanning, bundle size analysis, outdated dependency detection, deep accessibility audit, deep SEO audit, and Core Web Vitals budget enforcement.
-
-## Quick start
-
-Run it on a frontend app:
-
-```bash
-cd your-project
-npx laxy-verify .
-```
-
-Generate config plus GitHub Actions workflow:
-
-```bash
-npx laxy-verify --init
-```
-
-That creates:
-
-- `.laxy.yml`
-- `.github/workflows/laxy-verify.yml`
-
-Optional: log in to connect the CLI to your Laxy account:
-
-```bash
-npx laxy-verify login
-npx laxy-verify whoami
-```
-
-For CI, set `LAXY_TOKEN` instead of interactive login:
-
-```yaml
-env:
-  LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
-```
-
-## Why laxy-verify?
-
-Most teams already have some mix of:
-
-- `npm run build`
-- Lighthouse
-- Playwright or smoke checks
-- CI status rules
-
-The gap is not "can these tools exist together?" The gap is "who turns that pile of output into a safe merge or release decision?"
-
-`laxy-verify` gives you:
-
-- one command instead of a custom build plus audit plus smoke-check script stack
-- one result file instead of scattered logs
-- one blocker-first decision instead of "build passed, but do we actually trust this release?"
-- optional account-linked automation on top of the same verification run
-
-This is most useful if you ship frontend apps and want a practical gate before:
-
-- merge
-- client review
-- QA handoff
-- production release
-
-## Why not just LHCI?
-
-|  | laxy-verify | LHCI | Checkly | Percy |
-|--|--|--|--|--|
-| Production build failure detection | Yes | No | No | No |
-| User-flow E2E verification | Yes | No | Manual setup | No |
-| Lighthouse scoring | Yes | Yes | No | No |
-| Visual regression check | Yes | No | No | Yes |
-| Broken link detection | Yes | No | No | No |
-| Console error monitoring | Yes | No | No | No |
-| Cross-browser (Firefox, WebKit) | Yes | No | Yes | No |
-| Release decision (`hold` / `client-ready`) | Yes | No, score only | No | No |
-| TypeScript type check | Yes | No | No | No |
-| Hardcoded secret scanning | Yes | No | No | No |
-| Bundle size analysis | Yes | No | No | No |
-| Outdated dependency check | Yes | No | No | No |
-| Deep WCAG audit (axe-core) | Yes | No | No | No |
-| Deep SEO audit | Yes | No | No | No |
-| Core Web Vitals budget | Yes | No | No | No |
-| Zero-config local start | Yes | No | No | No |
-
-LHCI measures Lighthouse. `laxy-verify` is for deciding whether this frontend is actually safe to ship.
-
-## The failures it is meant to catch
-
-Use `laxy-verify` when you want to catch things like:
-
-- the production build passes locally but fails in CI
-- the app opens, but a key button or form flow is broken
-- desktop looks fine, but a mobile CTA is pushed out of view
-- Lighthouse looks acceptable, but the user-visible path is still not safe to ship
-- a PR needs a clear hold reason instead of a vague "something failed"
-- hardcoded API keys or secrets are about to be pushed to a public repo
-- TypeScript type errors could cause runtime crashes
-- bundle size has silently grown past acceptable limits
-- critical WCAG violations block real users
-- missing SEO meta tags hurt discoverability
-
-## What it actually checks
-
-Every run includes:
-
-- **production build** — runs your actual build command, exit code determines pass/fail
-- **Lighthouse** — 3 runs averaged for stable performance, accessibility, SEO, and best practices scores
-- **E2E scenarios** — Puppeteer-based user flow testing (auto-detected or configured via `.laxy.yml`)
-- **stability pass** — E2E runs a second time to catch flaky behavior
-- **multi-viewport** — Lighthouse at desktop (1350px), tablet (1024px), and mobile (390px)
-- **security audit** — `npm audit` dependency vulnerability scan
-- **visual diff** — pixel-level screenshot comparison against baseline
-- **broken links** — crawls all internal links and validates HTTP responses
-- **console error monitoring** — captures browser JS errors during E2E execution
-- **cross-browser** — Playwright on Firefox and WebKit if `browsers` is configured in `.laxy.yml`
-
-### Opt-in checks
-
-These checks are off by default. Enable them via CLI flags or `.laxy.yml`.
-
-| Flag | What it checks | Blocker or Advisory |
-|------|----------------|---------------------|
-| `--typecheck` | TypeScript type errors via `tsc --noEmit` | **Blocker** (5+ errors → high severity) |
-| `--secret-scan` | Hardcoded secrets: AWS keys, GitHub tokens, Stripe keys, private keys, Bearer tokens, JWTs, generic password/token assignments | **Blocker** (always high severity) |
-| `--bundle-size` | Next.js or Vite bundle size analysis (first-load JS, largest chunk) | Advisory |
-| `--outdated-check` | Outdated dependencies via `npm outdated --json` | Advisory (major behind → warning) |
-| `--a11y-deep` | Deep WCAG audit via axe-core (critical/serious violations) | **Blocker** (critical → high severity) |
-| `--seo-deep` | SEO meta tags, canonical, robots, Open Graph, Twitter Card, JSON-LD | Advisory |
-| `--vitals-budget` | Core Web Vitals budget: LCP ≤ 2500ms, CLS ≤ 0.1, INP ≤ 200ms | Advisory |
-
-Secret scan never exposes actual credential values — findings are masked with `***` in all output formats.
-
-## What you get from one run
-
-- a release decision such as `quick-pass`, `client-ready`, `release-ready`, `hold`, or `investigate`
-- a verification grade: `Gold`, `Silver`, `Bronze`, or `Unverified`
-- `.laxy-result.json` for CI and automation
-- `laxy-verify-report.md` for human review and AI handoff
-
-Grades still exist, but they are not the main point. The main point is whether the run found blockers you should stop on.
-
-## Example workflow
-
-1. Run `npx laxy-verify .` locally before opening or merging a PR.
-2. Fix broken builds, broken flows, and visible regressions.
-3. Commit `.laxy.yml`.
-4. Run `npx laxy-verify --init`.
-5. Let the GitHub Action apply the same gate on every PR.
-
-Full verification with all opt-in checks:
-
-```bash
-npx laxy-verify . --typecheck --secret-scan --bundle-size --outdated-check --a11y-deep --seo-deep --vitals-budget
-```
-
-Or enable them in `.laxy.yml` and just run:
-
-```bash
-npx laxy-verify .
-```
-
-## Example output
-
-```text
-Decision: client-ready
-Grade: Gold
-
-Passed:
-- production build
-- Lighthouse thresholds (Performance 92, Accessibility 97, SEO 90, Best Practices 95)
-- core user flows (5/5 scenarios passed)
-- stability pass (second E2E run passed)
-- desktop, tablet, and mobile viewport checks
-- security audit (no known vulnerabilities)
-- visual diff (no regressions)
-- broken links (0 broken / 12 checked)
-- console errors (0 detected)
-- TypeScript (0 errors)
-- Secret scan (0 findings, 42 files)
-- Bundle size (vite, within thresholds)
-- Outdated deps (0 outdated)
-- WCAG deep (0 critical)
-- SEO deep (0 errors)
-- Core Web Vitals budget (LCP 1200ms, CLS 0.05, INP 80ms)
-
-Artifacts:
-- .laxy-result.json
-- laxy-verify-report.md
-
-  Badge (auto-updates with each run):
-    [![Laxy Verify](https://laxy.app/api/badge/your-repo-id)](https://laxy.app)
-```
-
-For Free accounts, the CLI prints a tip instead:
-
-```text
-  Tip: Pro tracks your last 30 runs so you can see if Performance or Grade is improving.
-       https://laxy.app/pricing
-```
-
-## The decision it helps you make
-
-`laxy-verify` answers a delivery decision, not just a score:
-
-- Would this break for real users right now?
-- What would block a client demo or QA handoff?
-- Is there enough evidence to merge or release with confidence?
-
-All verification checks already run without a paid plan gate.
-
-## Grades
-
-| Grade | Meaning |
-|---|---|
-| Gold | Build passed, E2E passed, Lighthouse passed, and release-level evidence passed |
-| Silver | Build passed and E2E passed |
-| Bronze | Build passed |
-| Unverified | Build failed |
-
-Default Lighthouse thresholds:
-
-- Performance `>= 70`
-- Accessibility `>= 85`
-- SEO `>= 80`
-- Best Practices `>= 80`
-
-## Config
-
-All fields in `.laxy.yml` are optional.
-
-```yaml
-framework: auto
-build_command: ""
-dev_command: ""
-package_manager: auto
-port: 3000
-build_timeout: 300
-dev_timeout: 60
-lighthouse_runs: 3
-fail_on: bronze
-
-thresholds:
-  performance: 70
-  accessibility: 85
-  seo: 80
-  best_practices: 80
-
-crawl: false
-max_crawl_depth: 3
-max_crawl_pages: 10
-browsers:
-  - chromium
-
-# Explicit route list for Lighthouse (optional)
-lighthouse_routes: []
-# Extra routes not discoverable by the crawler (optional)
-extra_routes: []
-# Max crawl-discovered routes to run Lighthouse on (default: 5)
-max_lighthouse_routes: 5
-
-# Visual diff fine-tuning (optional)
-visual_diff:
-  pixelmatch_threshold: 0.1
-  warn_threshold: 30
-  rollback_threshold: 60
-  ignore_selectors: []
-  disable_animations: true
-
-# Opt-in checks (off by default)
-typecheck: false
-secret_scan: false
-secret_scan_ignore_paths: []
-bundle_size: false
-outdated_check: false
-a11y_deep: false
-seo_deep: false
-vitals_budget: false
-```
-
-Useful adjustments:
-
-- raise `fail_on` in CI when you want stricter gates
-- set `build_command` or `dev_command` if auto-detection is not enough
-- increase `lighthouse_runs` for more stable performance evidence
-- point the CLI at the actual app directory in a monorepo
-
-## CLI
-
-```text
-npx laxy-verify [project-dir]
-
-Options:
-  --format console|json
-  --ci
-  --config <path>
-  --fail-on unverified|bronze|silver|gold
-  --skip-lighthouse
-  --plan-override free|pro|team
-  --badge
-  --init
-  --multi-viewport
-  --crawl                Crawl the app to discover routes before E2E
-  --typecheck            Run TypeScript type check (tsc --noEmit)
-  --secret-scan          Scan for hardcoded secrets and credentials
-  --bundle-size          Analyze bundle size (Next.js/Vite)
-  --outdated-check       Check for outdated dependencies
-  --a11y-deep            Deep accessibility audit (axe-core)
-  --seo-deep             Deep SEO audit (meta, OG, JSON-LD)
-  --vitals-budget        Core Web Vitals budget check (LCP, CLS, INP)
-  --share                  Save result and get a shareable URL (Pro)
-  --compare <url>          Compare Lighthouse scores against a reference URL (Pro)
-  --help
-
-Subcommands:
-  login [email]
-  logout
-  whoami
-```
-
-`--plan-override` is only for plan-label and automation testing. Verification coverage stays the same on every plan.
-
-## Pro features
-
-Pro and Team accounts unlock additional capabilities on top of the same verification run:
-
-- **Result saving and sharing** — `--share` saves the run to your dashboard and returns a shareable URL
-- **Environment comparison** — `--compare <url>` runs Lighthouse against a reference URL (e.g. staging or production) and shows score deltas between your local build and the reference
-- **AI failure analysis** — when a run ends in `hold`, Claude analyzes the failure context and returns a root cause summary with top fix suggestions
-- **History trend tracking** — the last 30 runs are stored so you can see whether your grade and performance scores are improving or regressing over time
-- **Dynamic README badge** — after each run, the CLI prints a Markdown badge snippet that links to your live verification status. The badge auto-updates with every run so your README always reflects current grade
-- **Team Slack / Discord alerts** — grade drops and `hold` verdicts fire webhook notifications with score deltas and blocker details
-- **Weekly team report** — automated weekly summary of verification activity across your team's repos
-
-Free accounts see a hint after each run pointing to the history trend feature.
-
-## Secret scan patterns
-
-When `--secret-scan` is enabled, the following patterns are detected:
-
-| Pattern | Example |
-|---------|--------|
-| AWS Access Key | `AKIA...` (20 chars) |
-| AWS Secret Key | `aws_secret_access_key = '...'` |
-| GitHub Token | `ghp_`, `gho_`, `ghs_`, `ghu_` |
-| Slack Token / Webhook | `xoxb-...`, `hooks.slack.com/...` |
-| Private Key Block | `-----BEGIN RSA PRIVATE KEY-----` |
-| Google API Key | `AIza...` |
-| Stripe Key | `sk_live_...`, `pk_live_...` |
-| Twilio / SendGrid / Mailgun | `SK...`, `SG...`, `key-...` |
-| Hardcoded Bearer Token | `Bearer abc123...` |
-| JWT-like Secret | `eyJ...` |
-| Generic Secret Assignment | `password = '...'`, `api_key = '...'` |
-
-False positive filtering:
-
-- `process.env.*`, `import.meta.env.*`, `NEXT_PUBLIC_*`, `VITE_*` references are ignored
-- GitHub Actions template variables (`${{ secrets.* }}`) are ignored
-- `test/`, `tests/`, `__tests__/`, `spec/` directories are excluded
-- Comment lines (`//`, `*`, `<!--`) are excluded — commented-out secrets are not flagged
-- Placeholder/example values are ignored
-- All secret values in findings are **masked with `***`** — never exposed in output
-
-## Test fixture
-
-A sample Vite + React + TypeScript app is included at `fixtures/sample-app/` for testing all verification checks:
-
-```bash
-cd fixtures/sample-app
-npm install
-npm run build
-npx laxy-verify . --typecheck --secret-scan --bundle-size --outdated-check --skip-lighthouse
-```
-
-See `fixtures/sample-app/README.md` for details on what each check finds in the fixture.
-
-## Result files
-
-Every run writes `.laxy-result.json`.
-
-When the run finds something worth reviewing, it also writes `laxy-verify-report.md`.
-
-Typical use:
-
-- `.laxy-result.json` for CI parsing and machine decisions
-- `laxy-verify-report.md` for human review, PR discussion, or AI-assisted fixes
-
-The markdown report is designed to be readable and easy to paste into coding tools.
-
-It includes:
-
-- the main stop-or-ship decision in plain English
-- what passed
-- blockers and warnings
-- exact verification evidence
-- failed scenarios
-- a `Copy For AI` section
-
-## What this is good at
-
-Use `laxy-verify` when you want:
-
-- a merge or release gate for frontend apps
-- one repeatable command for build plus audit plus visible-flow verification
-- a decision that non-authors can understand
-- JSON output for automation without building your own wrapper
-
-## What this is not
-
-`laxy-verify` is not trying to replace:
-
-- your full Playwright suite
-- deep visual QA by designers
-- production observability
-- manual exploratory testing
-
-It is a pre-merge and pre-release verification layer, not your entire quality system.
-
-## Limitations
-
-- monorepos should target the real app subdirectory
-- dev-server-based Lighthouse is not identical to production hosting
-- visual diff and viewport checks increase runtime
-- best stability is on current LTS Node releases
-
-## Requirements
-
-- Node `>=20.18.0 <25`
-- a frontend app with a runnable build flow
-- optional: `playwright` if your project already uses it
-
-## Changelog
-
-### v1.3.0 — Pro history trend, dynamic badge, CLI nudge
-
-- **History trend tracking** — Pro accounts now store the last 30 verification runs. Grade and performance scores accumulate so you can see whether your app is improving or regressing over time
-- **Dynamic README badge** — after each run, Pro accounts see a Markdown badge snippet in the CLI output. The badge auto-updates with every run via the `/api/badge/:id` endpoint
-- **CLI nudge** — Free accounts see a one-line tip after each run pointing to the history trend feature
-- Added `generateDynamicBadgeMarkdown(repoId, apiUrl)` export to the `badge` module
-- Added `share_result` and `history_trend` flags to `EntitlementFeatures` interface
-- 17 test files, 88 unit tests
-
-### v1.2.3 — Bug fix
-
-- Fix E2E and visual diff connection failure on Windows with Node.js 17+: `verifyUrl` now uses `localhost` instead of `127.0.0.1`. On Windows, Vite binds to `::1` (IPv6) which does not accept IPv4 connections.
-
-### v1.2.2 — Opt-in verification checks
-
-Added 7 opt-in checks (off by default, enable via CLI flags or `.laxy.yml`):
-
-- `--typecheck` — TypeScript type error detection via `tsc --noEmit`
-- `--secret-scan` — Hardcoded secret scanning with 11 regex patterns and `***` masking
-- `--bundle-size` — Next.js/Vite bundle size analysis
-- `--outdated-check` — Outdated dependency detection via `npm outdated`
-- `--a11y-deep` — Deep WCAG audit via axe-core + Puppeteer
-- `--seo-deep` — SEO meta/OG/JSON-LD audit
-- `--vitals-budget` — Core Web Vitals budget enforcement (LCP, CLS, INP)
-
-Other changes:
-
-- Secret scan findings are **masked** — real credential values never appear in JSON, markdown, or console output
-- Comment lines excluded from secret scanning to reduce false positives
-- `test/`, `tests/`, `__tests__/`, `spec/` directories excluded from scanning
-- `.laxy.yml` supports `secret_scan_ignore_paths` for custom exclusions
-- Verification report includes all new checks in passes checklist and improvement recommendations
-- Markdown report includes all new checks in the delivery evidence table
-- Added `fixtures/sample-app/` test fixture (Vite + React + TypeScript)
-- 17 test files, 88 unit tests
-
-## Links
-
-- GitHub: https://github.com/SUNgm24/Laxy/tree/main/laxy-verify
-- Issues: https://github.com/SUNgm24/Laxy/issues
+# laxy-verify
+
+`laxy-verify` is a deployment blocker gate for frontend apps.
+
+Every verification run includes build, Lighthouse, E2E, multi-viewport, security audit, visual diff, broken links, console error monitoring, and stability coverage regardless of plan. Optional opt-in checks add TypeScript type checking, secret scanning, bundle size analysis, outdated dependency detection, deep accessibility audit, deep SEO audit, and Core Web Vitals budget enforcement.
+
+## Quick start
+
+Run it on a frontend app:
+
+```bash
+cd your-project
+npx laxy-verify .
+```
+
+Generate config plus GitHub Actions workflow:
+
+```bash
+npx laxy-verify --init
+```
+
+That creates:
+
+- `.laxy.yml`
+- `.github/workflows/laxy-verify.yml`
+
+Optional: log in to connect the CLI to your Laxy account:
+
+```bash
+npx laxy-verify login
+npx laxy-verify whoami
+```
+
+For CI, set `LAXY_TOKEN` instead of interactive login:
+
+```yaml
+env:
+  LAXY_TOKEN: ${{ secrets.LAXY_TOKEN }}
+```
+
+## Why laxy-verify?
+
+Most teams already have some mix of:
+
+- `npm run build`
+- Lighthouse
+- Playwright or smoke checks
+- CI status rules
+
+The gap is not "can these tools exist together?" The gap is "who turns that pile of output into a safe merge or release decision?"
+
+`laxy-verify` gives you:
+
+- one command instead of a custom build plus audit plus smoke-check script stack
+- one result file instead of scattered logs
+- one blocker-first decision instead of "build passed, but do we actually trust this release?"
+- optional account-linked automation on top of the same verification run
+
+This is most useful if you ship frontend apps and want a practical gate before:
+
+- merge
+- client review
+- QA handoff
+- production release
+
+## Why not just LHCI?
+
+|  | laxy-verify | LHCI | Checkly | Percy |
+|--|--|--|--|--|
+| Production build failure detection | Yes | No | No | No |
+| User-flow E2E verification | Yes | No | Manual setup | No |
+| Lighthouse scoring | Yes | Yes | No | No |
+| Visual regression check | Yes | No | No | Yes |
+| Broken link detection | Yes | No | No | No |
+| Console error monitoring | Yes | No | No | No |
+| Cross-browser (Firefox, WebKit) | Yes | No | Yes | No |
+| Release decision (`hold` / `client-ready`) | Yes | No, score only | No | No |
+| TypeScript type check | Yes | No | No | No |
+| Hardcoded secret scanning | Yes | No | No | No |
+| Bundle size analysis | Yes | No | No | No |
+| Outdated dependency check | Yes | No | No | No |
+| Deep WCAG audit (axe-core) | Yes | No | No | No |
+| Deep SEO audit | Yes | No | No | No |
+| Core Web Vitals budget | Yes | No | No | No |
+| Zero-config local start | Yes | No | No | No |
+
+LHCI measures Lighthouse. `laxy-verify` is for deciding whether this frontend is actually safe to ship.
+
+## The failures it is meant to catch
+
+Use `laxy-verify` when you want to catch things like:
+
+- the production build passes locally but fails in CI
+- the app opens, but a key button or form flow is broken
+- desktop looks fine, but a mobile CTA is pushed out of view
+- Lighthouse looks acceptable, but the user-visible path is still not safe to ship
+- a PR needs a clear hold reason instead of a vague "something failed"
+- hardcoded API keys or secrets are about to be pushed to a public repo
+- TypeScript type errors could cause runtime crashes
+- bundle size has silently grown past acceptable limits
+- critical WCAG violations block real users
+- missing SEO meta tags hurt discoverability
+
+## What it actually checks
+
+Every run includes:
+
+- **production build** - runs your actual build command, exit code determines pass/fail
+- **Lighthouse** - 3 runs averaged for stable performance, accessibility, SEO, and best practices scores
+- **E2E scenarios** - Puppeteer-based user flow testing (auto-detected or configured via `.laxy.yml`)
+- **stability pass** - E2E runs a second time to catch flaky behavior
+- **multi-viewport** - Lighthouse at desktop (1350px), tablet (1024px), and mobile (390px)
+- **security audit** - `npm audit` dependency vulnerability scan
+- **visual diff** - pixel-level screenshot comparison against baseline
+- **broken links** - crawls all internal links and validates HTTP responses
+- **console error monitoring** - captures browser JS errors during E2E execution
+- **cross-browser** - Playwright on Firefox and WebKit if `browsers` is configured in `.laxy.yml`
+
+### Opt-in checks
+
+These checks are off by default. Enable them via CLI flags or `.laxy.yml`.
+
+| Flag | What it checks | Blocker or Advisory |
+|------|----------------|---------------------|
+| `--typecheck` | TypeScript type errors via `tsc --noEmit` | **Blocker** (5+ errors -> high severity) |
+| `--secret-scan` | Hardcoded secrets: AWS keys, GitHub tokens, Stripe keys, private keys, Bearer tokens, JWTs, generic password/token assignments | **Blocker** (always high severity) |
+| `--bundle-size` | Next.js or Vite bundle size analysis (first-load JS, largest chunk) | Advisory |
+| `--outdated-check` | Outdated dependencies via `npm outdated --json` | Advisory (major behind -> warning) |
+| `--a11y-deep` | Deep WCAG audit via axe-core (critical/serious violations) | **Blocker** (critical -> high severity) |
+| `--seo-deep` | SEO meta tags, canonical, robots, Open Graph, Twitter Card, JSON-LD | Advisory |
+| `--vitals-budget` | Core Web Vitals budget: LCP <= 2500ms, CLS <= 0.1, INP <= 200ms | Advisory |
+
+Secret scan never exposes actual credential values - findings are masked with `***` in all output formats.
+
+## What you get from one run
+
+- a release decision such as `quick-pass`, `client-ready`, `release-ready`, `hold`, or `investigate`
+- a verification grade: `Gold`, `Silver`, `Bronze`, or `Unverified`
+- `.laxy-result.json` for CI and automation
+- `laxy-verify-report.md` for human review and AI handoff
+
+Grades still exist, but they are not the main point. The main point is whether the run found blockers you should stop on.
+
+## Example workflow
+
+1. Run `npx laxy-verify .` locally before opening or merging a PR.
+2. Fix broken builds, broken flows, and visible regressions.
+3. Commit `.laxy.yml`.
+4. Run `npx laxy-verify --init`.
+5. Let the GitHub Action apply the same gate on every PR.
+
+Full verification with all opt-in checks:
+
+```bash
+npx laxy-verify . --typecheck --secret-scan --bundle-size --outdated-check --a11y-deep --seo-deep --vitals-budget
+```
+
+Or enable them in `.laxy.yml` and just run:
+
+```bash
+npx laxy-verify .
+```
+
+If the default or configured dev port is already occupied, `laxy-verify` automatically starts its temporary verification server on the next available port. Use `--port` only when you want to attach to an already-running server yourself.
+
+## Example output
+
+```text
+Decision: client-ready
+Grade: Gold
+
+Passed:
+- production build
+- Lighthouse thresholds (Performance 92, Accessibility 97, SEO 90, Best Practices 95)
+- core user flows (5/5 scenarios passed)
+- stability pass (second E2E run passed)
+- desktop, tablet, and mobile viewport checks
+- security audit (no known vulnerabilities)
+- visual diff (no regressions)
+- broken links (0 broken / 12 checked)
+- console errors (0 detected)
+- TypeScript (0 errors)
+- Secret scan (0 findings, 42 files)
+- Bundle size (vite, within thresholds)
+- Outdated deps (0 outdated)
+- WCAG deep (0 critical)
+- SEO deep (0 errors)
+- Core Web Vitals budget (LCP 1200ms, CLS 0.05, INP 80ms)
+
+Artifacts:
+- .laxy-result.json
+- laxy-verify-report.md
+
+  Badge (auto-updates with each run):
+    [![Laxy Verify](https://laxy.app/api/badge/your-repo-id)](https://laxy.app)
+```
+
+For Free accounts, the CLI prints a tip instead:
+
+```text
+  Tip: Pro tracks your last 30 runs so you can see if Performance or Grade is improving.
+       https://laxy.app/pricing
+```
+
+## The decision it helps you make
+
+`laxy-verify` answers a delivery decision, not just a score:
+
+- Would this break for real users right now?
+- What would block a client demo or QA handoff?
+- Is there enough evidence to merge or release with confidence?
+
+All verification checks already run without a paid plan gate.
+
+## Grades
+
+| Grade | Meaning |
+|---|---|
+| Gold | Build passed, E2E passed, Lighthouse passed, and release-level evidence passed |
+| Silver | Build passed and E2E passed |
+| Bronze | Build passed |
+| Unverified | Build failed |
+
+Default Lighthouse thresholds:
+
+- Performance `>= 70`
+- Accessibility `>= 85`
+- SEO `>= 80`
+- Best Practices `>= 80`
+
+## Config
+
+All fields in `.laxy.yml` are optional.
+
+```yaml
+framework: auto
+build_command: ""
+dev_command: ""
+package_manager: auto
+port: 3000
+build_timeout: 300
+dev_timeout: 60
+lighthouse_runs: 3
+fail_on: bronze
+
+thresholds:
+  performance: 70
+  accessibility: 85
+  seo: 80
+  best_practices: 80
+
+crawl: false
+max_crawl_depth: 3
+max_crawl_pages: 10
+browsers:
+  - chromium
+
+# Explicit route list for Lighthouse (optional)
+lighthouse_routes: []
+# Extra routes not discoverable by the crawler (optional)
+extra_routes: []
+# Max crawl-discovered routes to run Lighthouse on (default: 5)
+max_lighthouse_routes: 5
+
+# Visual diff fine-tuning (optional)
+visual_diff:
+  pixelmatch_threshold: 0.1
+  warn_threshold: 30
+  rollback_threshold: 60
+  ignore_selectors: []
+  disable_animations: true
+
+# Opt-in checks (off by default)
+typecheck: false
+secret_scan: false
+secret_scan_ignore_paths: []
+bundle_size: false
+outdated_check: false
+a11y_deep: false
+seo_deep: false
+vitals_budget: false
+```
+
+Useful adjustments:
+
+- raise `fail_on` in CI when you want stricter gates
+- set `build_command` or `dev_command` if auto-detection is not enough
+- increase `lighthouse_runs` for more stable performance evidence
+- point the CLI at the actual app directory in a monorepo
+
+## CLI
+
+```text
+npx laxy-verify [project-dir]
+
+Options:
+  --format console|json
+  --ci
+  --config <path>
+  --fail-on unverified|bronze|silver|gold
+  --skip-lighthouse
+  --plan-override free|pro|team
+  --badge
+  --init
+  --multi-viewport
+  --crawl                Crawl the app to discover routes before E2E
+  --typecheck            Run TypeScript type check (tsc --noEmit)
+  --secret-scan          Scan for hardcoded secrets and credentials
+  --bundle-size          Analyze bundle size (Next.js/Vite)
+  --outdated-check       Check for outdated dependencies
+  --a11y-deep            Deep accessibility audit (axe-core)
+  --seo-deep             Deep SEO audit (meta, OG, JSON-LD)
+  --vitals-budget        Core Web Vitals budget check (LCP, CLS, INP)
+  --share                Save result and get a shareable URL (Pro)
+  --compare <url>        Compare Lighthouse scores against a reference URL (Pro)
+  --help
+
+Subcommands:
+  login [email]
+  logout
+  whoami
+```
+
+`--plan-override` is only for plan-label and automation testing. Verification coverage stays the same on every plan.
+
+## Pro features
+
+Pro and Team accounts unlock additional capabilities on top of the same verification run:
+
+- **Result saving and sharing** - `--share` saves the run to your dashboard and returns a shareable URL
+- **Environment comparison** - `--compare <url>` runs Lighthouse against a reference URL (e.g. staging or production) and shows score deltas between your local build and the reference
+- **AI failure analysis** - when a run ends in `hold`, Claude analyzes the failure context and returns a root cause summary with top fix suggestions
+- **History trend tracking** - the last 30 runs are stored so you can see whether your grade and performance scores are improving or regressing over time
+- **Dynamic README badge** - after each run, the CLI prints a Markdown badge snippet that links to your live verification status. The badge auto-updates with every run so your README always reflects current grade
+- **Team Slack / Discord alerts** - grade drops and `hold` verdicts fire webhook notifications with score deltas and blocker details
+- **Weekly team report** - automated weekly summary of verification activity across your team's repos
+
+Free accounts see a hint after each run pointing to the history trend feature.
+
+## Secret scan patterns
+
+When `--secret-scan` is enabled, the following patterns are detected:
+
+| Pattern | Example |
+|---------|--------|
+| AWS Access Key | `AKIA...` (20 chars) |
+| AWS Secret Key | `aws_secret_access_key = '...'` |
+| GitHub Token | `ghp_`, `gho_`, `ghs_`, `ghu_` |
+| Slack Token / Webhook | `xoxb-...`, `hooks.slack.com/...` |
+| Private Key Block | `-----BEGIN RSA PRIVATE KEY-----` |
+| Google API Key | `AIza...` |
+| Stripe Key | `sk_live_...`, `pk_live_...` |
+| Twilio / SendGrid / Mailgun | `SK...`, `SG...`, `key-...` |
+| Hardcoded Bearer Token | `Bearer abc123...` |
+| JWT-like Secret | `eyJ...` |
+| Generic Secret Assignment | `password = '...'`, `api_key = '...'` |
+
+False positive filtering:
+
+- `process.env.*`, `import.meta.env.*`, `NEXT_PUBLIC_*`, `VITE_*` references are ignored
+- GitHub Actions template variables (`${{ secrets.* }}`) are ignored
+- `test/`, `tests/`, `__tests__/`, `spec/` directories are excluded
+- Comment lines (`//`, `*`, `<!--`) are excluded - commented-out secrets are not flagged
+- Placeholder/example values are ignored
+- All secret values in findings are **masked with `***`** - never exposed in output
+
+## Test fixture
+
+A sample Vite + React + TypeScript app is included at `fixtures/sample-app/` for testing all verification checks:
+
+```bash
+cd fixtures/sample-app
+npm install
+npm run build
+npx laxy-verify . --typecheck --secret-scan --bundle-size --outdated-check --skip-lighthouse
+```
+
+See `fixtures/sample-app/README.md` for details on what each check finds in the fixture.
+
+## Result files
+
+Every run writes `.laxy-result.json`.
+
+When the run finds something worth reviewing, it also writes `laxy-verify-report.md`.
+
+Typical use:
+
+- `.laxy-result.json` for CI parsing and machine decisions
+- `laxy-verify-report.md` for human review, PR discussion, or AI-assisted fixes
+
+The markdown report is designed to be readable and easy to paste into coding tools.
+
+It includes:
+
+- the main stop-or-ship decision in plain English
+- what passed
+- blockers and warnings
+- exact verification evidence
+- failed scenarios
+- a `Copy For AI` section
+
+## What this is good at
+
+Use `laxy-verify` when you want:
+
+- a merge or release gate for frontend apps
+- one repeatable command for build plus audit plus visible-flow verification
+- a decision that non-authors can understand
+- JSON output for automation without building your own wrapper
+
+## What this is not
+
+`laxy-verify` is not trying to replace:
+
+- your full Playwright suite
+- deep visual QA by designers
+- production observability
+- manual exploratory testing
+
+It is a pre-merge and pre-release verification layer, not your entire quality system.
+
+## Limitations
+
+- monorepos should target the real app subdirectory
+- dev-server-based Lighthouse is not identical to production hosting
+- visual diff and viewport checks increase runtime
+- best stability is on current LTS Node releases
+
+## Requirements
+
+- Node `>=20.18.0 <25`
+- a frontend app with a runnable build flow
+- optional: `playwright` if your project already uses it
+
+## Changelog
+
+### v1.3.2 - Auto port fallback
+
+- If port `3000` or your configured verification port is already in use, `laxy-verify` now starts its temporary dev server on the next available port automatically
+- `--port` keeps its existing meaning: attach to an already-running server instead of starting a temporary one
+
+### v1.3.1 - Publish fix
+
+- Fix npm package contents so `login`, `logout`, and `whoami` ship with the required `dist/init-analysis.js` runtime dependency
+- Republish the CLI artifact with the README badge, Pro history trend messaging, and Free-plan CLI tip aligned to the shipped code
+
+### v1.3.0 - Pro history trend, dynamic badge, CLI nudge
+
+- **History trend tracking** - Pro accounts now store the last 30 verification runs. Grade and performance scores accumulate so you can see whether your app is improving or regressing over time
+- **Dynamic README badge** - after each run, Pro accounts see a Markdown badge snippet in the CLI output. The badge auto-updates with every run via the `/api/badge/:id` endpoint
+- **CLI nudge** - Free accounts see a one-line tip after each run pointing to the history trend feature
+- Added `generateDynamicBadgeMarkdown(repoId, apiUrl)` export to the `badge` module
+- Added `share_result` and `history_trend` flags to `EntitlementFeatures` interface
+- 17 test files, 88 unit tests
+
+### v1.2.3 - Bug fix
+
+- Fix E2E and visual diff connection failure on Windows with Node.js 17+: `verifyUrl` now uses `localhost` instead of `127.0.0.1`. On Windows, Vite binds to `::1` (IPv6) which does not accept IPv4 connections.
+
+### v1.2.2 - Opt-in verification checks
+
+Added 7 opt-in checks (off by default, enable via CLI flags or `.laxy.yml`):
+
+- `--typecheck` - TypeScript type error detection via `tsc --noEmit`
+- `--secret-scan` - Hardcoded secret scanning with 11 regex patterns and `***` masking
+- `--bundle-size` - Next.js/Vite bundle size analysis
+- `--outdated-check` - Outdated dependency detection via `npm outdated`
+- `--a11y-deep` - Deep WCAG audit via axe-core + Puppeteer
+- `--seo-deep` - SEO meta/OG/JSON-LD audit
+- `--vitals-budget` - Core Web Vitals budget enforcement (LCP, CLS, INP)
+
+Other changes:
+
+- Secret scan findings are **masked** - real credential values never appear in JSON, markdown, or console output
+- Comment lines excluded from secret scanning to reduce false positives
+- `test/`, `tests/`, `__tests__/`, `spec/` directories excluded from scanning
+- `.laxy.yml` supports `secret_scan_ignore_paths` for custom exclusions
+- Verification report includes all new checks in passes checklist and improvement recommendations
+- Markdown report includes all new checks in the delivery evidence table
+- Added `fixtures/sample-app/` test fixture (Vite + React + TypeScript)
+- 17 test files, 88 unit tests
+
+## Links
+
+- GitHub: https://github.com/SUNgm24/Laxy/tree/main/laxy-verify
+- Issues: https://github.com/SUNgm24/Laxy/issues