start-vibing 4.3.3 → 4.4.0

package/template/.claude/skills/e2e-audit/e2e/utils/security-helpers.ts

@@ -0,0 +1,114 @@
+import { type Page, expect } from '@playwright/test'
+
+export const XSS_PAYLOADS = [
+	'<script>alert("xss")</script>',
+	'<img src=x onerror=alert("xss")>',
+	'"><script>alert("xss")</script>',
+	"javascript:alert('xss')",
+	'<svg onload=alert("xss")>',
+	"'; DROP TABLE users; --",
+	'{{constructor.constructor("return this")()}}',
+	'${7*7}',
+]
+
+export const REQUIRED_SECURITY_HEADERS = [
+	'x-frame-options',
+	'x-content-type-options',
+	'referrer-policy',
+]
+
+/**
+ * Test XSS payloads against a text input.
+ * Fills each payload and verifies no dialog (alert/confirm/prompt) fires.
+ */
+export async function testXssOnInput(
+	page: Page,
+	inputLocator: ReturnType<Page['getByRole']>,
+) {
+	const dialogFired: string[] = []
+	const handler = (dialog: { message: () => string; dismiss: () => Promise<void> }) => {
+		dialogFired.push(dialog.message())
+		void dialog.dismiss()
+	}
+	page.on('dialog', handler)
+
+	for (const payload of XSS_PAYLOADS) {
+		await inputLocator.clear()
+		await inputLocator.fill(payload)
+		// Trigger potential execution (blur, submit)
+		await inputLocator.press('Tab')
+	}
+
+	page.off('dialog', handler)
+
+	if (dialogFired.length > 0) {
+		throw new Error(
+			`XSS detected! Dialog(s) fired with: ${dialogFired.join(', ')}`,
+		)
+	}
+}
+
+/**
+ * Verify required security headers are present on a response.
+ */
+export async function assertSecurityHeaders(page: Page, url: string) {
+	const response = await page.goto(url)
+	if (!response) throw new Error(`No response for ${url}`)
+
+	const headers = response.headers()
+
+	for (const header of REQUIRED_SECURITY_HEADERS) {
+		expect(
+			headers[header],
+			`Missing security header: ${header}`,
+		).toBeDefined()
+	}
+
+	// X-Content-Type-Options should be nosniff
+	if (headers['x-content-type-options']) {
+		expect(headers['x-content-type-options']).toBe('nosniff')
+	}
+}
+
+/**
+ * Verify that error responses don't contain stack traces.
+ */
+export async function assertNoStackTraceInResponse(page: Page) {
+	const content = await page.content()
+	const stackTraceIndicators = [
+		'at Object.',
+		'at Module.',
+		'at Function.',
+		'node_modules/',
+		'.js:',
+		'webpack-internal',
+		'__next',
+	]
+
+	for (const indicator of stackTraceIndicators) {
+		expect(content).not.toContain(indicator)
+	}
+}
+
+/**
+ * Test RBAC by navigating to a URL and checking if access is denied.
+ */
+export async function assertAccessDenied(
+	page: Page,
+	url: string,
+	expectedRedirect?: string,
+) {
+	await page.goto(url)
+	const currentUrl = page.url()
+
+	if (expectedRedirect) {
+		expect(currentUrl).toContain(expectedRedirect)
+	} else {
+		// Should redirect to /unauthorized or /auth
+		const denied =
+			currentUrl.includes('/unauthorized') ||
+			currentUrl.includes('/auth') ||
+			currentUrl.includes('/login')
+		expect(denied).toBe(true)
+	}
+}

package/template/.claude/skills/e2e-audit/e2e/utils/test-data.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared test data constants for E2E tests.
+ * Keep this minimal — only data used across multiple test files.
+ */
+
+export const ROUTES = {
+	// Dashboard (authenticated)
+	home: '/dashboard/home',
+	knowledge: '/dashboard/knowledge',
+	knowledgeDetail: (id: string) => `/dashboard/knowledge/${id}`,
+	chat: '/dashboard/chat',
+	integrations: '/dashboard/integrations',
+	integrationDetail: (id: string) => `/dashboard/integrations/${id}`,
+	integrationsNew: '/dashboard/integrations/new',
+	integrationsSuccess: '/dashboard/integrations/success',
+	teams: '/dashboard/teams',
+	profile: '/dashboard/profile',
+	admin: '/dashboard/admin',
+	billing: '/dashboard/billing',
+	ontology: '/dashboard/ontology',
+	transcripts: '/dashboard/transcripts',
+	transcriptDetail: (id: string) => `/dashboard/transcripts/${id}`,
+	transcriptDocument: (id: string) => `/dashboard/transcripts/documents/${id}`,
+
+	// Auth
+	root: '/',
+	authDesktop: '/auth/desktop',
+	authError: '/auth/error',
+	logout: '/auth/logout',
+	popupCallback: '/auth/popup-callback',
+	integrationCallbackSuccess: '/auth/integration/callback/success',
+	integrationCallbackError: '/auth/integration/callback/error',
+
+	// Other
+	unauthorized: '/unauthorized',
+	freeTrial: '/freetrial',
+} as const
+
+export const RBAC_ROUTES = {
+	/** Routes accessible only by ADMIN+ */
+	admin: [ROUTES.admin],
+	/** Routes accessible only by OWNER */
+	owner: [ROUTES.billing],
+	/** Routes accessible only by MANAGER+ */
+	manager: [ROUTES.integrationsNew],
+	/** Routes accessible by any authenticated user */
+	member: [
+		ROUTES.home,
+		ROUTES.knowledge,
+		ROUTES.chat,
+		ROUTES.integrations,
+		ROUTES.teams,
+		ROUTES.profile,
+		ROUTES.ontology,
+		ROUTES.transcripts,
+	],
+} as const
+
+export const TIMEOUTS = {
+	navigation: 30_000,
+	action: 10_000,
+	toast: 5_000,
+	animation: 500,
+} as const

package/template/.claude/skills/e2e-audit/runbook.md

@@ -0,0 +1,115 @@
+# E2E Audit Runbook
+
+## Setup
+
+### 1. Install Playwright
+
+```bash
+bun add -D @playwright/test
+bunx playwright install chromium
+```
+
+### 2. Start the dev server
+
+```bash
+bun run dev
+```
+
+### 3. Run tests
+
+```bash
+# All E2E tests
+bun run test:e2e
+
+# With UI mode (visual debugger)
+bunx playwright test --ui
+
+# Specific test file
+bunx playwright test tests/e2e/specs/dashboard-home.spec.ts
+
+# By tag
+bunx playwright test --grep @smoke
+bunx playwright test --grep @security
+bunx playwright test --grep @ux
+```
+
+## Test Organization
+
+```
+tests/e2e/
+├── fixtures/          # Auth + base fixtures
+│   ├── auth.ts        # Per-role authentication setup
+│   ├── base.ts        # Extended test fixture (authenticatedPage)
+│   └── storage/       # Generated auth state files (gitignored)
+├── pages/             # Page Object Models (1 per page)
+├── specs/             # Test specs (1 per page + security/)
+│   └── security/      # Cross-cutting security tests
+└── utils/             # Shared helpers
+    ├── console-collector.ts  # Console message interceptor
+    ├── security-helpers.ts   # XSS, header, RBAC helpers
+    └── test-data.ts          # Routes, timeouts, test constants
+```
+
+## Adding Tests for a New Page
+
+1. **Create Page Object** in `tests/e2e/pages/{page-name}.page.ts`
+2. **Create Test Spec** in `tests/e2e/specs/{page-name}.spec.ts`
+3. **Create Page Spec** in `docs/e2e-audit/page-specs/{page-name}.md`
+4. **Run and fix**: `bunx playwright test tests/e2e/specs/{page-name}.spec.ts`
+5. **Update master audit** in `docs/e2e-audit/reports/master-audit.md`
+
+## Updating Tests After App Changes
+
+1. Run the e2e-audit skill to re-discover elements on changed pages
+2. Compare new page spec with existing
+3. Update POM, test spec, and page spec
+4. Run tests: `bun run test:e2e`
+5. Fix failures
+
+## Auth Setup
+
+Tests use `storageState` for pre-authenticated sessions. The auth fixture at
+`tests/e2e/fixtures/auth.ts` needs real login flows implemented per role.
+
+For local development with OAuth, you may need to:
+1. Use the Cloudflare tunnel (`https://dev.hakutaku.ai`)
+2. Set `BASE_URL=https://dev.hakutaku.ai` when running tests
+3. Or mock auth via direct cookie/session injection
+
+## CI Integration
+
+```yaml
+# Example GitHub Actions step
+- name: E2E Tests
+  run: |
+    bunx playwright install chromium
+    bun run test:e2e
+  env:
+    BASE_URL: http://localhost:3000
+```
+
+## Debugging Failed Tests
+
+```bash
+# View trace from failed test
+bunx playwright show-trace test-results/{test-name}/trace.zip
+
+# Run with headed browser
+bunx playwright test --headed
+
+# Run with slow motion
+bunx playwright test --headed --slow-mo 500
+
+# Debug specific test
+bunx playwright test --debug tests/e2e/specs/dashboard-home.spec.ts
+```
+
+## Tags Reference
+
+| Tag | Purpose | When to run |
+|-----|---------|-------------|
+| `@smoke` | Critical paths | Every PR |
+| `@regression` | Full suite | Main merges |
+| `@security` | Security tests | Weekly + before release |
+| `@a11y` | Accessibility | Weekly |
+| `@ux` | UX/UI validation | After UI changes |

package/template/.claude/skills/super-design/SKILL.md

@@ -8,7 +8,7 @@ description: >
   UX audit (WCAG 2.2 AA, Nielsen heuristics, Baymard, CWV), and synthesized
   overview. Re-audits only what changed since last run. On explicit user request,
   applies surgical fixes with full rollback.
-version: 0.6.3
+version: 0.7.0
 ---
 
 # super-design
@@ -22,17 +22,36 @@ Four-phase pipeline with 6 specialist agents:
    nav, cards, modals, forms, tokens — per competitor × mobile+desktop),
    produces market-analysis.md + component-comparison.md.
 2. **UI/UX audit** (sd-audit) — drives browser via Playwright MCP directly.
-   Five layers:
+   Six layers:
    - Route discovery + static snap (Nielsen + WCAG 2.2 AA + Baymard + CWV)
+   - **Step 1.5 source-first discovery** (0.7.0+) —
+     `discover-surfaces.sh` reads the repo FIRST and emits an authoritative
+     inventory of modals, forms, triggers, internal nav, and Next.js
+     layout/error/loading/not-found/parallel/intercepting routes BEFORE
+     Playwright runs. `extract-project-rules.sh` parses FORBIDDEN tables
+     from CLAUDE.md / AGENTS.md / .cursorrules into audit-applicable
+     rules. Runtime cross-checks surface these as `modal-coverage-gap`,
+     `form-coverage-gap`, and `project-forbidden-<slug>` findings.
    - **Step 2.5 component/modal/flow discovery** (Phase A inventory, B modal
      enumeration, C flow exercising, D state matrix, E form coverage) — this
      is where modal contents, empty/loading/error states, and flow errors
-     get real evidence instead of "checklist hypothetical".
+     get real evidence instead of "checklist hypothetical". Phase B now
+     cross-references `surfaces.json` and files a `modal-coverage-gap`
+     finding for anything declared in source but never opened.
    - **Step 3g design-intelligence scoring** (17-category rubric → DIS 0–100)
      catches implicit best practices checklists miss (cards-in-flex-col,
-     low density, weak CTA hierarchy, vibecode smell).
+     low density, weak CTA hierarchy, vibecode smell). Emits MANDATORY
+     `design-intelligence-craft-summary` finding per page × viewport so
+     overview.md has one holistic verdict row ("admin mobile is 38/100
+     WEAK — holistic redesign scope") per combination, not just discrete
+     per-category findings.
    - **Step 3h mobile-native audit** (21-item Duolingo/Linear/Arc/Cash-App
      checklist) — replaces "responsive-web-on-a-phone" thinking.
+   - **Step 3i project-rule enforcement** (0.7.0+) — consumes
+     `project-rules.json` and fires primary findings keyed to the
+     project's own FORBIDDEN wording (e.g. `project-forbidden-use-cards-on-mobile`)
+     when the rule is violated at runtime. Not a tag, not a severity
+     bump — the project owner's rule IS the rule source.
    - C16 ≤ 4 → **DSC-choice** proposal: sd-synthesis runs
      `scripts/score-typeui.mjs --from-audit <dir>` to derive a 7-axis site
      fingerprint (density/contrast/geometry/color/typography/motion/audience)
@@ -189,6 +208,25 @@ Windows git-bash + Linux.
   `*.fixture.json`, `fixtures/<name>.json`, or `$SUPER_DESIGN_FIXTURES`
   env JSON; falls back to `@fixture-default` with a warning. Consumers
   (hash-pages, sd-audit) MUST strip the suffix before navigating.
+- `discover-surfaces.sh` (0.7.0+) — source-first static scan for
+  modals (`<Dialog|Sheet|Drawer|Modal|Popover|AlertDialog|DropdownMenu|CommandDialog|...>`),
+  forms (`<form>` / `useForm(` / `<Form>`), triggers (`<*Trigger>`),
+  internal navigation (`<Link href>` / `router.push`), and Next.js
+  `layout.tsx` / `error.tsx` / `loading.tsx` / `not-found.tsx` / parallel
+  routes (`@foo/`) / intercepting routes (`(.)foo/`). Emits
+  `$SESSION_DIR/surfaces.json`. sd-audit Step 2.5 Phase B cross-checks
+  runtime observations against this inventory and files
+  `modal-coverage-gap` / `form-coverage-gap` findings for declared
+  components never exercised.
+- `extract-project-rules.sh` (0.7.0+) — parses FORBIDDEN tables from
+  `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `.claude/CLAUDE.md` /
+  `.cursorrules` into an authoritative rule source. Classifies each
+  rule as audit-applicable (mobile / design / ux / perf / a11y) or
+  code-level (skip — belongs to typecheck/lint). Emits
+  `$SESSION_DIR/project-rules.json`. sd-audit Step 3i fires primary
+  findings keyed to the project's own wording (e.g.
+  `project-forbidden-use-cards-on-mobile`) — the project owner's rule
+  IS the rule source, not a tag or severity bump.
 - `build-import-graph.sh` — builds `.super-design/import-graph.json`
   (`{nodes, edges, hash, backend}`) and persists `import_graph_sha` to
   state. Prefers `npx madge --json <roots>`; falls back to a regex

package/template/.claude/skills/super-design/references/audit-methodology.md

@@ -311,13 +311,69 @@ source section cited.
 
 > Source: §3.4.
 
-**`baymard-search-*` — Search (12 rules, §3.6):** placeholders for 12 rules covering autocomplete presence, scope suggestions in autocomplete, search-within-current-category, autodirect on category match, query-term pluralization tolerance, typo tolerance, "no results" with recovery options, recent-searches memory, sort-vs-filter separation, faceted-search state in URL, submit-without-suggestion-selection, voice search on mobile. Rules `baymard-search-01` … `baymard-search-12`. Source: §3.6 bullets + https://baymard.com/ecommerce-design-examples/34-autocomplete-suggestions. Enumerate the exact wording when next Baymard PDF is purchased.
-
-**`baymard-filter-*` — Filter (10 rules, §3.6):** placeholders `baymard-filter-01` … `baymard-filter-10` covering: promote top filters above the product grid; truncate long value lists >10 with styled "More" link; category-specific filters (megapixels, temperature rating); filters for every attribute displayed in list items; expand/collapse icons right-aligned; applied-filter pills visible and individually removable; "clear all" affordance; range sliders with keyboard + numeric input; multi-select affordance obvious; result count live-updated via `aria-live`. Source: §3.6 bullets + https://baymard.com/blog/promoting-product-filters + https://baymard.com/blog/have-filters-for-list-item-info.
-
-**`baymard-bread-*` — Breadcrumbs (6 rules, §3.7):** placeholders `baymard-bread-01` … `baymard-bread-06` covering: present on all non-home pages; implement BOTH hierarchy-based AND history-based (68% of top 50 sub-par, 45% only hierarchy, 23% none); present on mobile (65% mobile fail); no "hidden in more" collapse on desktop without reveal; last crumb non-clickable; structured-data markup (`BreadcrumbList`). Source: §3.7 + https://baymard.com/blog/ecommerce-breadcrumbs.
-
-**`baymard-pdp-*` — PDP / Product Detail (18 rules, §3.8):** placeholders `baymard-pdp-01` … `baymard-pdp-18` covering: single dominant Add-to-Cart (no 3–6 competing colorful buttons); shipping cost/ETA visible on PDP (64% of users look for it); total visible before checkout (24% abandon otherwise); accordion over horizontal tabs (67% of accordion users mis-implement; 28% use worst-performing tabs); UGC visuals present (67% lack them); minimum 3–5 images + zoom + variant-driven imagery; swatches not dropdowns for variants; out-of-stock variants visible-but-disabled (not removed); star ratings above the fold (up to +18% conversion with verified badges); stock urgency without dark patterns; delivery-date estimator; returns policy on PDP; size guide inline (not in a separate page); Q&A / reviews with filtering; cross-sell without shoving below CTA; "notify me" flow for OOS; price history for discount honesty; country/currency switcher persisted. Source: §3.8 + https://baymard.com/research/product-page.
+**`baymard-search-*` — Search (12 rules, §3.6):**
+1. `baymard-search-01` persist search query in the field after submission
+2. `baymard-search-02` autocomplete list capped at 10 items desktop, 4–8 mobile
+3. `baymard-search-03` style category-scope suggestions distinctly within autocomplete
+4. `baymard-search-04` highlight the predictive (un-typed) portion of autocomplete suggestions
+5. `baymard-search-05` copy active autocomplete suggestion into the field on keyboard navigation
+6. `baymard-search-06` support misspellings in autocomplete (spell-tolerant suggestions)
+7. `baymard-search-07` autodirect exact category-match queries to the category page
+8. `baymard-search-08` support synonym and alternate-term searches
+9. `baymard-search-09` support abbreviation and symbol searches
+10. `baymard-search-10` allow "search within" current category on mobile
+11. `baymard-search-11` support non-product queries (return policy, order status, FAQ)
+12. `baymard-search-12` provide 5 proven no-results recovery paths (spelling fix, broaden, contact, etc.)
+
+> Source: §3.6 bullets + https://baymard.com/ecommerce-design-examples/34-autocomplete-suggestions + per-rule URLs in `/docs/research/baymard-public-rules.md` (B-S-01…B-S-12).
+
+**`baymard-filter-*` — Filter (10 rules, §3.6):**
+1. `baymard-filter-01` provide the 5 essential filter types (category, price, rating, brand, user-relevant attribute)
+2. `baymard-filter-02` have filters for every attribute displayed in list items
+3. `baymard-filter-03` display applied filters in a visible overview area, individually removable
+4. `baymard-filter-04` use OR logic within a facet, AND logic across facets
+5. `baymard-filter-05` show product counts per filter value and update them dynamically
+6. `baymard-filter-06` collapse long facet lists to top 4–6 values with a "Show more" link
+7. `baymard-filter-07` explain industry-specific or jargon filter labels
+8. `baymard-filter-08` promote important filters above the product grid / above the fold
+9. `baymard-filter-09` provide 4 essential sort options (featured, price asc/desc, rating, newest)
+10. `baymard-filter-10` persist filter state when user returns from a product detail page
+
+> Source: §3.6 bullets + https://baymard.com/blog/promoting-product-filters + https://baymard.com/blog/have-filters-for-list-item-info + per-rule URLs in `/docs/research/baymard-public-rules.md` (B-F-01…B-F-10).
+
+**`baymard-bread-*` — Breadcrumbs (6 rules, §3.7):**
+1. `baymard-bread-01` provide both hierarchy-based AND history-based breadcrumbs
+2. `baymard-bread-02` include the full category hierarchy in the breadcrumb trail
+3. `baymard-bread-03` suppress homepage and current product page layers from the trail
+4. `baymard-bread-04` make breadcrumbs swipeable on mobile for long paths
+5. `baymard-bread-05` use clear tappability cues on mobile breadcrumbs (size, underline, chevron)
+6. `baymard-bread-06` expose `BreadcrumbList` structured-data markup for SEO and assistive tech
+
+> Rules 01–05 from verified public research (B-B-01…B-B-05). Rule 06 enumerated from §3.7 narrative; supersede when Baymard Premium IDs become available.
+> Source: §3.7 + https://baymard.com/blog/ecommerce-breadcrumbs + per-rule URLs in `/docs/research/baymard-public-rules.md`.
+
+**`baymard-pdp-*` — PDP / Product Detail (18 rules, §3.8):**
+1. `baymard-pdp-01` use button-style size selectors (swatches), not dropdowns
+2. `baymard-pdp-02` provide at least one in-scale product image (size/context reference)
+3. `baymard-pdp-03` show product on a human model for worn or carried items
+4. `baymard-pdp-04` provide sufficient image resolution and zoom on desktop and mobile
+5. `baymard-pdp-05` support both pinch and double-tap zoom gestures on mobile
+6. `baymard-pdp-06` allow guest users to save / wishlist items without account creation
+7. `baymard-pdp-07` display a return-policy link or summary directly on the product page
+8. `baymard-pdp-08` show the lowest shipping-cost estimate (and ETA) on the product page
+9. `baymard-pdp-09` allow carousel navigation across reviewer-submitted images (UGC)
+10. `baymard-pdp-10` respond publicly to negative reviews to demonstrate accountability
+11. `baymard-pdp-11` display price-per-unit for multi-quantity or weight-priced products
+12. `baymard-pdp-12` synchronize product data (price, stock, images) across variation selections
+13. `baymard-pdp-13` include descriptive text or graphics on key product images (annotations)
+14. `baymard-pdp-14` single dominant Add-to-Cart CTA — not 3–6 competing colorful buttons
+15. `baymard-pdp-15` prefer accordion over horizontal tabs for PDP detail sections
+16. `baymard-pdp-16` show out-of-stock variants as visible-but-disabled (never remove from UI)
+17. `baymard-pdp-17` offer a "notify me when back in stock" flow for OOS variants
+18. `baymard-pdp-18` surface size-guide inline on the PDP — not hidden behind a separate page
+
+> Rules 01–13 from verified public research (B-P-01…B-P-13). Rules 14–18 enumerated from §3.8 narrative; supersede when Baymard Premium IDs become available.
+> Source: §3.8 + https://baymard.com/research/product-page + per-rule URLs in `/docs/research/baymard-public-rules.md`.
 
 ### 3.1 Cart abandonment
 **70.19% average abandonment** across 49 studies 2006–2023, range 55–84.27% (https://baymard.com/lists/cart-abandonment-rate). By device: mobile 77.06%, tablet 66.39%, desktop 70.01%. **Reasons** (excluding 43% "just browsing"): extra costs 48%; forced account creation 24%; slow delivery 19%; distrust with CC 18–19%; too long/complicated 17–18%; couldn't see total up front 16%; errors/crashes 13%; returns policy 12%; declined CC 9%; limited payment methods 7%.

package/template/.claude/skills/super-design/scripts/discover-surfaces.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# discover-surfaces.sh — source-first discovery of modals, forms, triggers,
+# internal navigation, and Next.js layout/error/loading/parallel surfaces.
+#
+# Purpose: sd-audit cannot trust runtime-only modal discovery (click every
+# trigger in Playwright). A modal hidden behind a flow step, a feature flag,
+# or an auth gate will be missed. This script reads the SOURCE CODE first
+# and emits an authoritative inventory; Step 2.5 Phase B cross-checks at
+# runtime and emits `modal-coverage-gap` findings for anything declared in
+# source but never opened during the audit.
+#
+# Output: JSON object on stdout with shape:
+# {
+#   "modals":     [{ "component": "CreateUserDialog", "file": "...", "used_in": [...] }],
+#   "forms":      [{ "id": "LoginForm", "file": "...", "fields": [...] }],
+#   "triggers":   [{ "kind": "DialogTrigger", "file": "..." }],
+#   "navigation": [{ "from": "src/...", "to": "/users", "kind": "Link" }],
+#   "layouts":    ["src/app/layout.tsx", "src/app/(app)/layout.tsx"],
+#   "errors":     ["src/app/error.tsx"],
+#   "loading":    ["src/app/loading.tsx"],
+#   "not_found":  ["src/app/not-found.tsx"],
+#   "parallel":   ["src/app/@modal"],
+#   "intercepting": ["src/app/(.)photos"],
+#   "framework":  "next" | "remix" | "sveltekit" | "astro" | "nuxt" | "unknown"
+# }
+#
+# Best-effort grep-based scanner. No AST. False positives are OK —
+# sd-audit treats this as an inventory, not a contract. Missed items
+# are the real failure mode.
+set -euo pipefail
+
+log() { printf '[discover-surfaces] %s\n' "$*" >&2; }
+
+detect_framework() {
+  if   [[ -f next.config.js || -f next.config.ts || -f next.config.mjs ]]; then echo "next"
+  elif [[ -f remix.config.js || -d app/routes ]]; then echo "remix"
+  elif [[ -f svelte.config.js && -d src/routes ]]; then echo "sveltekit"
+  elif [[ -f astro.config.mjs || -f astro.config.ts ]]; then echo "astro"
+  elif [[ -f nuxt.config.ts || -f nuxt.config.js ]]; then echo "nuxt"
+  else echo "unknown"; fi
+}
+
+# Source roots to scan. Frameworks differ; union keeps the scanner simple.
+SCAN_ROOTS=()
+for d in src app src/app src/components components src/pages pages src/features features src/routes app/routes; do
+  [[ -d "$d" ]] && SCAN_ROOTS+=("$d")
+done
+if [[ ${#SCAN_ROOTS[@]} -eq 0 ]]; then
+  log "no known source roots found; emitting empty inventory"
+  jq -n '{modals:[],forms:[],triggers:[],navigation:[],layouts:[],errors:[],loading:[],not_found:[],parallel:[],intercepting:[],framework:"unknown"}'
+  exit 0
+fi
+
+# File extensions we care about.
+EXT_GLOB='\.(tsx|jsx|ts|js|svelte|vue|astro)$'
+
+# --- 1. MODALS --------------------------------------------------------------
+# Match common modal/overlay component usages. We key on JSX opening tags so
+# we catch both <Dialog> and <Dialog.Root>. The component NAME is what
+# the audit logs as the `component` field.
+MODAL_PATTERN='<(Dialog|AlertDialog|Sheet|Drawer|Modal|Popover|HoverCard|Tooltip|CommandDialog|DropdownMenu|ContextMenu|Menubar|NavigationMenu|Select|Combobox|DatePicker|ColorPicker)\b'
+
+modals_json="$(
+  {
+    for root in "${SCAN_ROOTS[@]}"; do
+      grep -rEHn --include='*.tsx' --include='*.jsx' --include='*.ts' --include='*.js' \
+        --include='*.svelte' --include='*.vue' --include='*.astro' \
+        "$MODAL_PATTERN" "$root" 2>/dev/null || true
+    done
+  } | awk -F: '{
+    file=$1; line=$2;
+    # capture component name between < and the next non-word char
+    match($0, /<([A-Z][A-Za-z0-9_]*)/, m);
+    if (m[1] != "") printf "{\"component\":\"%s\",\"file\":\"%s\",\"line\":%s}\n", m[1], file, line;
+  }' | jq -s 'unique_by([.component,.file])'
+)"
+
+# --- 2. FORMS ---------------------------------------------------------------
+# Match react-hook-form useForm() calls, <Form> / <form> elements, and
+# zod schema imports co-located with forms.
+FORM_PATTERN='(useForm\s*\(|<Form[[:space:]>]|<form[[:space:]>])'
+
+forms_json="$(
+  {
+    for root in "${SCAN_ROOTS[@]}"; do
+      grep -rEHln --include='*.tsx' --include='*.jsx' --include='*.ts' --include='*.js' \
+        --include='*.svelte' --include='*.vue' --include='*.astro' \
+        "$FORM_PATTERN" "$root" 2>/dev/null || true
+    done
+  } | sort -u | awk '{ printf "{\"file\":\"%s\"}\n", $0 }' | jq -s '.'
+)"
+
+# --- 3. TRIGGERS ------------------------------------------------------------
+# Explicit *Trigger components (Radix / shadcn convention) tell us the
+# connection between a button and its overlay.
+TRIGGER_PATTERN='<(DialogTrigger|SheetTrigger|DrawerTrigger|PopoverTrigger|DropdownMenuTrigger|AlertDialogTrigger|HoverCardTrigger|TooltipTrigger|SelectTrigger|ComboboxTrigger|ContextMenuTrigger|MenubarTrigger|NavigationMenuTrigger)\b'
+
+triggers_json="$(
+  {
+    for root in "${SCAN_ROOTS[@]}"; do
+      grep -rEHn --include='*.tsx' --include='*.jsx' \
+        "$TRIGGER_PATTERN" "$root" 2>/dev/null || true
+    done
+  } | awk -F: '{
+    file=$1; line=$2;
+    match($0, /<([A-Z][A-Za-z0-9_]*Trigger)/, m);
+    if (m[1] != "") printf "{\"kind\":\"%s\",\"file\":\"%s\",\"line\":%s}\n", m[1], file, line;
+  }' | jq -s '.'
+)"
+
+# --- 4. NAVIGATION ----------------------------------------------------------
+# Internal nav: <Link href=...>, <Link to=...>, router.push("/..."),
+# redirect("/..."), navigate("/..."). We only keep destinations that start
+# with "/" (internal) — external URLs are not audit targets here.
+nav_json="$(
+  {
+    for root in "${SCAN_ROOTS[@]}"; do
+      grep -rEHno --include='*.tsx' --include='*.jsx' --include='*.ts' --include='*.js' \
+        "(href|to)=[\"']/[^\"']*[\"']|(router\.push|redirect|navigate)\(\s*[\"']/[^\"']*[\"']" \
+        "$root" 2>/dev/null || true
+    done
+  } | awk -F: '{
+    file=$1; line=$2; rest=""; for (i=3;i<=NF;i++) rest = rest (i==3?"":":") $i;
+    # extract first "/..." path literal from the match
+    match(rest, /[\"'"'"']\/[^\"'"'"']*[\"'"'"']/, m);
+    if (m[0] != "") {
+      dest=m[0]; gsub(/[\"'"'"']/, "", dest);
+      kind = (rest ~ /push|redirect|navigate/) ? "imperative" : "link";
+      printf "{\"from\":\"%s\",\"to\":\"%s\",\"kind\":\"%s\",\"line\":%s}\n", file, dest, kind, line;
+    }
+  }' | jq -s 'unique_by([.from,.to])'
+)"
+
+# --- 5. NEXT.JS LAYOUT / ERROR / LOADING / NOT-FOUND / PARALLEL -------------
+# Empty arrays for non-Next frameworks.
+FW="$(detect_framework)"
+layouts_json='[]'
+errors_json='[]'
+loading_json='[]'
+notfound_json='[]'
+parallel_json='[]'
+intercepting_json='[]'
+
+if [[ "$FW" == "next" ]]; then
+  # layout.tsx / template.tsx nesting defines wrapper chrome (headers,
+  # sidebars) — sd-audit must audit these at EVERY viewport because a
+  # layout that misbehaves on mobile breaks every child page.
+  layouts_json="$(
+    find app src/app -type f \( -name 'layout.tsx' -o -name 'layout.ts' -o -name 'layout.jsx' -o -name 'layout.js' -o -name 'template.tsx' -o -name 'template.ts' \) 2>/dev/null \
+      | jq -Rn '[inputs]'
+  )"
+  errors_json="$(
+    find app src/app -type f \( -name 'error.tsx' -o -name 'global-error.tsx' \) 2>/dev/null \
+      | jq -Rn '[inputs]'
+  )"
+  loading_json="$(
+    find app src/app -type f -name 'loading.tsx' 2>/dev/null | jq -Rn '[inputs]'
+  )"
+  notfound_json="$(
+    find app src/app -type f -name 'not-found.tsx' 2>/dev/null | jq -Rn '[inputs]'
+  )"
+  # Parallel route slots: directories starting with @
+  parallel_json="$(
+    find app src/app -type d -name '@*' 2>/dev/null | jq -Rn '[inputs]'
+  )"
+  # Intercepting routes: directories starting with (.) / (..) / (...)
+  intercepting_json="$(
+    find app src/app -type d \( -name '(.)*' -o -name '(..)*' -o -name '(...)*' \) 2>/dev/null | jq -Rn '[inputs]'
+  )"
+fi
+
+# --- ASSEMBLE ---------------------------------------------------------------
+jq -n \
+  --argjson modals "$modals_json" \
+  --argjson forms "$forms_json" \
+  --argjson triggers "$triggers_json" \
+  --argjson navigation "$nav_json" \
+  --argjson layouts "$layouts_json" \
+  --argjson errors "$errors_json" \
+  --argjson loading "$loading_json" \
+  --argjson not_found "$notfound_json" \
+  --argjson parallel "$parallel_json" \
+  --argjson intercepting "$intercepting_json" \
+  --arg framework "$FW" \
+  '{
+    framework: $framework,
+    modals: $modals,
+    forms: $forms,
+    triggers: $triggers,
+    navigation: $navigation,
+    layouts: $layouts,
+    errors: $errors,
+    loading: $loading,
+    not_found: $not_found,
+    parallel: $parallel,
+    intercepting: $intercepting
+  }'