@nebulacomponents/citable 1.17.0 → 1.18.1

package/skill/commands/remediation.md

@@ -0,0 +1,55 @@
+---
+command: /citable remediate --finding <id> [--target <file>] [--write]
+purpose: Apply safe, validated AST code patches for deterministic defects with automated rollback snapshots, structural syntax validation, and confidence gating.
+preconditions: [valid finding from audit run; target source file identified and writeable]
+failure_behaviour: unknown framework -> fail closed; invalid syntax after patch -> rollback and refuse; confidence < 0.7 -> refuse write; semantic microcopy changes -> always refuse automated write (human editorial decision required)
+artifacts_created: [.citable/remediation/snapshots/<snapshot-id>/, unified diff on stdout]
+---
+
+# Closed-Loop Code Remediation & Verification
+
+The remediation suite provides safe, gated code fixes for deterministic technical, schema, and CRO defects discovered during audits. It bridges the gap between audit findings and customer-verified pull requests.
+
+## 1. Safe Patch Application (`citable remediate`)
+
+1. **Framework Detection**: Identifies target source syntax (`jsx`, `tsx`, `vue`, `html`). Fails closed on unknown or ambiguous frameworks.
+2. **Idempotent AST Patching**: Patches are mathematically verified to be idempotent (`applyPatchDetailed`): applying the patch a second time produces an identical AST (a fixed point).
+3. **Structural Validation Gate**: Runs `validatePatchedSource` to confirm that the patch does not break AST structure, introduce syntax errors, or alter unrelated code blocks.
+4. **Confidence Threshold**: Computes an explicit multi-factor confidence score (`computeConfidence`). `--write` is refused if confidence falls below `0.70`.
+5. **Editorial Boundary (Semantic Microcopy Refusal)**: Automated `--write` is strictly refused for semantic copy, CTA wording, or headline changes (e.g. `CRO-012`, `COMP-003`). Microcopy is a human editorial and brand judgment (fact ≠ inference).
+6. **Rollback Snapshot**: Every `--write` automatically snapshots the target file under `.citable/remediation/snapshots/<timestamp>/` with a SHA-256 manifest before making any disk modifications.
+
+## 2. Closed-Loop Verification (`citable verify remediation`)
+
+Running a patch is NOT proof that a defect is resolved:
+
+```bash
+citable verify remediation --run <run-id> --finding <id> [--target <file>] [--apply]
+```
+
+1. **Deterministic Detector Rerun**: Re-executes the exact source detector (`detector_to_rerun`) against the patched target.
+2. **Regression Sweep**: Sweeps for newly introduced critical or high severity defects compared to the baseline run.
+3. **Verification Envelopes**: Emits a checksum-bound before/after verification envelope conforming to `schemas/remediation-verification.schema.json`.
+4. **Verdict Classification**:
+   * `verified`: Target detector no longer reports the defect; zero regressions introduced.
+   * `not_resolved`: Target detector still detects the condition on the patched surface.
+   * `blocked`: Prerequisite dependencies, build tools, or environments unavailable.
+   * `patch_refused`: Confidence below threshold, semantic copy gated, or syntax check failed.
+5. **Outcome Boundary**: Resolution means the detector no longer flags the subject — **it is never an outcome guarantee of rankings, AI citations, or conversion lift**.
+
+## 3. Customer Implementation Kits (`citable kit export`)
+
+Produce an engineer-ready delivery kit for customer development teams:
+
+```bash
+citable kit export --run <run-id> --finding <id> [--target <file>]
+```
+
+Creates a self-contained directory containing:
+* Verbatim finding with evidence lineage.
+* Exact unified diff for code review.
+* Reusable Nebula design system component template (React / Vue / HTML).
+* Rendering-evidence manifest (real captured DOM/visual state; synthetic evidence forbidden).
+* Acceptance test criteria and re-audit verification script.
+* Deployment and rollback instructions.
+* Explicit technical limitations and non-guarantee disclosures.

package/skill/commands/reporting.md

@@ -71,3 +71,31 @@ any observed change to a specific intervention.
    authoritative index guarantees. Divergences are reported as factual observations,
    never fabricated or interpolated.
 
+# Enterprise Search Intelligence Briefing (`citable report search`)
+
+1. Run `citable report search [--target <dir|url>] [--run <id>] [--format md|html|json] [--output <file>]`
+   to generate the 19-pillar Executive Search Intelligence Briefing.
+2. Synthesizes technical crawlability, indexation, Core Web Vitals readiness,
+   AEO answer-extractability, GEO citation frequency, knowledge graph schema
+   architecture, and competitor SERP landscape into an executive document.
+3. Every recommendation binds to a verified finding in the Evidence Register.
+4. Facts and inferences are strictly segregated: deterministic observations are
+   reported in green data panels; strategic hypotheses and inferences are explicitly
+   labeled with confidence ratings.
+5. Refusal boundary: Never promises rankings, algorithmic immunity, or indexing
+   guarantees.
+
+# Enterprise CRO & Customer Journey Briefing (`citable report cro`)
+
+1. Run `citable report cro [--target <dir|url>] [--input <file>] [--format md|html|json] [--output <file>]`
+   to generate the 25-pillar Executive Conversion & Customer Journey Briefing.
+2. Covers end-to-end conversion paths: above-the-fold clarity, message-match
+   scoring, cognitive load, checkout friction, trust and objection analysis, offer
+   architecture, and prioritized A/B experiment blueprints.
+3. Strictly adheres to the **Observation vs Hypothesis vs Causation** taxonomy:
+   - **Observations**: Verbatim DOM defects (e.g. missing autocomplete, undersized touch targets).
+   - **Hypotheses**: Falsifiable experiment statements with measurable primary metrics and guardrails.
+   - **Causation**: Statistical lift attribution requiring concluded, SRM-clean A/B experiments.
+4. Refusal boundary: Revenue lift, conversion percentage improvements, and visual
+   saliency scores are modeled heuristic indices, never observed behavior or guaranteed revenue.
+

package/skill/commands/sow.md

@@ -0,0 +1,95 @@
+---
+command: /citable sow generate [--target <dir|url>] [--run <id>] [--budget <amount>] [--budget-minor <cents>] [--format md|html|json] [--output <path>] [--sample] [--draft]
+purpose: Generate a contractually binding, evidence-traceable enterprise Statement of Work (SOW) from verified audit findings through a formal 7-gate scope admissibility filter and 7-column traceability matrix.
+preconditions: [at least one finalized audit run with verified findings or live target; sample mode required for synthetic demonstrations]
+failure_behaviour: absent or unverified findings in contractual mode -> NoFindingsError; all findings refused -> NoAdmissibleRequirementsError; non-existent run -> RunNotFoundError; negative or sub-cent budget -> BudgetCalculationError; invariant drift -> SowInvariantError
+artifacts_created: [SOW.md, SOW.html, or SOW.json at specified output path]
+---
+
+# Enterprise Statement of Work (SOW) Contract
+
+The `citable sow` command generates enterprise-grade, evidence-backed Statements of Work derived from verified technical SEO, AEO, GEO, schema, and CRO audit findings. It establishes rigid, downward traceability:
+
+```text
+Evidence (observation envelope)
+  ↓
+Observation (deterministic DOM / HTTP probe)
+  ↓
+Finding (verified defect / friction)
+  ↓
+Recommendation (governed remediation)
+  ↓
+SOW Requirement (contractual scope)
+  ↓
+Deliverable (code patch / AST modification)
+  ↓
+Acceptance Test (automated closed-loop detector rerun)
+```
+
+## 1. Operating Premises & Commercial Disclaimers
+
+1. **Fee Binding**: Supplier fees are bound exclusively to verified deliverable acceptance and closed-loop test execution.
+2. **Strict Outcome Disclaimers**: In strict compliance with Citable governance principles, **no search engine crawling, indexation, ranking, AI answer citation, or conversion revenue is guaranteed**.
+3. **No Synthetic Data in Contracts**: Attempting to generate a `CONTRACTUAL` SOW without verified empirical findings immediately fails closed with `NoFindingsError`. Synthetic findings are strictly confined to `--sample` / `--demo`.
+
+## 2. The Scope Admissibility Gate
+
+Audit findings do NOT automatically become contractual obligations. Every candidate finding must pass 7 admissibility gates:
+
+| Gate | Verification Check | Failure Refusal Code | Contractual Handling |
+| :--- | :--- | :--- | :--- |
+| **1. Exclusion Gate** | Check against explicit excluded detectors list | `REFUSE-EXCLUDED` | Track in internal backlog; execute under separate advisory engagement. |
+| **2. Discipline Authorization** | Check if discipline is authorized under contract | `REFUSE-DISCIPLINE-NOT-AUTHORIZED` | Expand authorized disciplines in SOW engagement terms or contract under separate SOW. |
+| **3. Evidence Maturity** | Require deterministic/observed confidence & evidence | `REFUSE-EXPERIMENTAL` / `REFUSE-NO-EVIDENCE` | Run controlled observation probes before considering for contractual obligation. |
+| **4. Scope Boundary** | Verify URL matches authorized host, subdomain, or path | `REFUSE-OUT-OF-SCOPE` | Escalate domain ownership verification or expand contractual executive scope. |
+| **5. Feasibility Gate** | Reject legal, trademark, GDPR, or unfeasible remediation | `REFUSE-UNFEASIBLE-REMEDIATION` | Refer to specialized legal or compliance counsel outside scope. |
+| **6. Materiality Gate** | Require critical/high severity or ICE score >= threshold | `REFUSE-LOW-MATERIALITY` | Log to internal product maintenance backlog; omit from high-value SOW. |
+| **7. Acceptance Gate** | Require automated rerun detector or objective pass/fail test | `REFUSE-UNVERIFIABLE` | Define deterministic verification criteria before adding to scope. |
+| **8. Ownership Clarity** | Resolve accountable owner from finding or role mappings | `REFUSE-OWNER-UNRESOLVED` | Specify delivery_owner on finding or map discipline to accountable role. |
+
+All refused findings are recorded in the SOW's `admissibility_gate.refusal_log` with standard refusal codes and contractual handling guidance.
+
+## 3. The 7-Column Traceability Matrix
+
+Every admitted requirement must satisfy complete 7-column bidirectional traceability:
+
+1. **Finding ID**: Verbatim identifier of the empirical defect (e.g. `F-TECH-001`).
+2. **Recommendation**: Governed, safe remediation instruction.
+3. **SOW Requirement ID**: Contractual clause identifier (`REQ-SOW-001`).
+4. **Deliverable ID**: Accountable work package deliverable (`DELIV-01`).
+5. **Acceptance Test ID**: Automated closed-loop test (`ACC-TEST-001`).
+6. **Responsible Owner**: Named lead dev, architect, or agency practice owner.
+7. **Source Evidence IDs**: Array of cryptographic observation IDs (`['EVD-CWV-001']`).
+
+## 4. Commercial Currency & Minor-Unit Semantics
+
+To eliminate commercial fee drift and rounding leaks, all internal calculations use exact **integer minor units (cents, exponent 2, currency `USD`)**:
+
+* `currency`: Declared as `USD`.
+* `currency_minor_unit_exponent`: Declared as `2`.
+* `commercial_total_fee_minor`: Integer cents (e.g. `$50,000.00` = `5000000` cents).
+* `milestones[].fee_minor`: Integer floor allocation across milestones with remainder pennies distributed deterministically to initial milestones.
+* `commercial_total_fee_usd` / `milestones[].fee_usd`: Derived dollar representation formatted at presentation boundaries (`$33.34`, `$50,000`).
+* Sub-cent fractional budgets (`100.001`) and negative budgets are strictly rejected.
+
+## 5. Generation Modes & Machine-Readable Provenance
+
+Every generated SOW embeds an immutable `generation_provenance` block:
+
+* **`CONTRACTUAL`**: Generated from verified historical run findings or live target; synthetic evidence forbidden.
+* **`DRAFT`**: Generated with preliminary scope or unfinalized commercial terms; requires executive sign-off.
+* **`NON_CONTRACTUAL_SAMPLE`**: Generated with synthetic baseline findings strictly for evaluation/demo (`--sample`).
+
+Provenance tracks:
+* `generator_version`: Exact Citable semver.
+* `generated_at`: ISO 8601 timestamp.
+* `source_type`: `HISTORICAL_RUN`, `LIVE_INSPECTION`, `DIRECT_FINDINGS`, or `SAMPLE_BASELINE`.
+* `source_identifier`: Target URL, run ID, or sample identifier.
+* `source_findings_count`: Integer count of evaluated findings.
+* `findings_integrity_hash`: SHA-256 hash of input findings.
+
+## 6. SOW Verification Command
+
+Run `citable sow validate <sow.json>` to verify:
+1. Strict schema compliance against `schemas/sow.schema.json` (`additionalProperties: false`).
+2. Cross-object invariants via `validateSowInvariants` (fee balancing, work package and deliverable parity, non-empty evidence links).

package/src/analysis/behavioral.js

@@ -0,0 +1,126 @@
+/**
+ * Analyze behavioral interaction evidence across funnels, sessions, cohorts, and interaction signals.
+ */
+export function analyzeBehavioralTelemetry(telemetryData = {}) {
+  const sessions = telemetryData.sessions || telemetryData.metrics || {};
+  const cohorts = telemetryData.cohorts || {};
+  const interactions = telemetryData.interactions || {};
+  const funnelSteps = telemetryData.funnel || [];
+
+  const findings = [];
+  const frictionIndicators = [];
+
+  // 1. Mobile vs Desktop Cohort Divergence
+  const mobileCr = cohorts.mobile?.conversion_rate ?? null;
+  const desktopCr = cohorts.desktop?.conversion_rate ?? null;
+
+  let cohortDivergence = null;
+  if (mobileCr !== null && desktopCr !== null && desktopCr > 0) {
+    const ratio = mobileCr / desktopCr;
+    cohortDivergence = {
+      mobile_cr: mobileCr,
+      desktop_cr: desktopCr,
+      mobile_to_desktop_ratio: Math.round(ratio * 100) / 100,
+    };
+
+    if (ratio < 0.5) {
+      frictionIndicators.push({
+        type: 'mobile_conversion_gap',
+        severity: 'high',
+        evidence: `Mobile conversion rate (${(mobileCr * 100).toFixed(1)}%) is under half of desktop (${(desktopCr * 100).toFixed(1)}%)`,
+        hypothesis: 'Mobile friction (virtual keyboard effort, diminutive tap targets, or slow paint) impedes mobile buyers',
+      });
+    }
+  }
+
+  // 2. Scroll Depth vs CTA Placement
+  const p50Scroll = interactions.scroll_depth_p50_pct ?? interactions.median_scroll_depth ?? null;
+  const ctaPosition = interactions.primary_cta_vertical_pct ?? null;
+
+  if (p50Scroll !== null && ctaPosition !== null) {
+    if (ctaPosition > p50Scroll) {
+      frictionIndicators.push({
+        type: 'buried_cta',
+        severity: 'high',
+        evidence: `Primary CTA is positioned at ${ctaPosition}% page depth, but median user scroll depth is only ${p50Scroll}%`,
+        hypothesis: 'Over 50% of visitors never view the primary conversion CTA before abandoning',
+      });
+    }
+  }
+
+  // 3. Rage Clicks and Dead Clicks
+  const rageClicks = interactions.rage_click_rate_pct ?? interactions.rage_clicks_count ?? 0;
+  const deadClicks = interactions.dead_click_rate_pct ?? interactions.dead_clicks_count ?? 0;
+
+  if (rageClicks > 3 || rageClicks > 50) {
+    frictionIndicators.push({
+      type: 'rage_clicks',
+      severity: 'high',
+      evidence: `Elevated rage click frequency (${rageClicks}) indicates user frustration with unresponsive or broken interactive elements`,
+      hypothesis: 'Interactive components fail to provide immediate visual feedback or fail on tap',
+    });
+  }
+
+  if (deadClicks > 5 || deadClicks > 80) {
+    frictionIndicators.push({
+      type: 'dead_clicks',
+      severity: 'medium',
+      evidence: `High dead click count (${deadClicks}): users attempt to click static elements perceived as interactive`,
+      hypothesis: 'Visual affordances mislead users into clicking non-actionable elements',
+    });
+  }
+
+  // 4. Funnel Drop-off Analysis
+  const funnelDropOffs = [];
+  if (Array.isArray(funnelSteps) && funnelSteps.length >= 2) {
+    for (let i = 0; i < funnelSteps.length - 1; i++) {
+      const curr = funnelSteps[i];
+      const next = funnelSteps[i + 1];
+      const dropOffRate = curr.visitors > 0 ? Math.round(((curr.visitors - next.visitors) / curr.visitors) * 100) : 0;
+      funnelDropOffs.push({
+        from_step: curr.name || `Step ${i + 1}`,
+        to_step: next.name || `Step ${i + 2}`,
+        drop_off_pct: dropOffRate,
+        retained_visitors: next.visitors,
+      });
+
+      if (dropOffRate > 70) {
+        frictionIndicators.push({
+          type: 'steep_funnel_leak',
+          severity: 'critical',
+          evidence: `Severe drop-off between ${curr.name} and ${next.name} (${dropOffRate}% abandon rate)`,
+          hypothesis: `Significant cognitive load, price shock, or friction barrier encountered at ${curr.name}`,
+        });
+      }
+    }
+  }
+
+  // 5. Form Field Abandonment Peak
+  const fieldAbandons = interactions.form_field_abandonment || [];
+  let peakAbandonField = null;
+  if (fieldAbandons.length > 0) {
+    fieldAbandons.sort((a, b) => b.abandon_count - a.abandon_count);
+    peakAbandonField = fieldAbandons[0];
+    frictionIndicators.push({
+      type: 'form_field_bottleneck',
+      severity: 'high',
+      evidence: `Peak form abandonment occurs on field "${peakAbandonField.field_name}" (${peakAbandonField.abandon_count} drop-offs)`,
+      hypothesis: `Field "${peakAbandonField.field_name}" creates high friction or privacy resistance; consider making optional or eliminating`,
+    });
+  }
+
+  return {
+    fact_status: 'observed_behavioral_telemetry',
+    summary: {
+      total_friction_indicators: frictionIndicators.length,
+      critical_indicators: frictionIndicators.filter((i) => i.severity === 'critical').length,
+      high_indicators: frictionIndicators.filter((i) => i.severity === 'high').length,
+      cohort_divergence: cohortDivergence,
+    },
+    funnel_drop_offs: funnelDropOffs,
+    friction_indicators: frictionIndicators,
+    limitations: [
+      'Behavioral signals indicate correlation and user interaction bottlenecks; causal mechanisms must be verified via controlled A/B experiments.',
+    ],
+  };
+}

package/src/analysis/croAudit.js

@@ -0,0 +1,302 @@
+import { parse as parseHtml } from 'node-html-parser';
+import { calculateVisualSaliency } from './saliency.js';
+import { registryPageFor, safePath } from '../detectors/framework.js';
+
+const GENERIC_CTA_RX = /^(?:submit|click\s*here|continue|next|send|ok|go|learn\s*more|more)$/i;
+const VALUE_CTA_RX = /\b(get|start|try|claim|unlock|explore|join|download|access|calculate|book|schedule|request)\b/i;
+const RISK_REVERSAL_RX = /\b(no\s*credit\s*card\s*required|cancel\s*anytime|money-back\s*guarantee|\d+-day\s*guarantee|risk-free|free\s*(?:\d+-day\s*)?trial|no\s*commitment|guaranteed)\b/i;
+const SOCIAL_PROOF_RX = /\b(trusted\s*by|over\s*\d+[\d,]*\s*(?:users|customers|teams|companies)|customer\s*reviews?|what\s*(?:our\s*)?customers\s*say|case\s*studies|testimonials?)\b/i;
+const OBJECTION_RX = /\b(frequently\s*asked\s*questions|faq|common\s*questions|how\s*much|pricing\s*details|cancel\s*policy|security\s*standards)\b/i;
+
+/**
+ * Perform comprehensive CRO audit on a page model
+ */
+export function auditPageCro(page, ctx = {}) {
+  const html = page.html || '';
+  const root = parseHtml(html);
+  const text = (page.text || root.textContent || '').replace(/\s+/g, ' ').trim();
+  const ctas = page.ctas || [];
+  const forms = page.forms || [];
+  const trustBadges = page.trustBadges || [];
+  const headings = page.headings || [];
+
+  // -------------------------------------------------------------
+  // 1. ABOVE-THE-FOLD (ATF) CLARITY & MESSAGE-MATCH (0-100)
+  // -------------------------------------------------------------
+  let atfScore = 0;
+  const atfSignals = [];
+  const atfGaps = [];
+
+  // Scent match: Title to H1 alignment
+  const titleStem = page.title ? page.title.split(/[|—–-]/)[0].trim().toLowerCase() : '';
+  const h1Text = (headings.find((h) => h.level === 1)?.text || '').trim();
+  const h1Lower = h1Text.toLowerCase();
+
+  let scentMatch = false;
+  if (titleStem && h1Lower) {
+    const titleWords = titleStem.split(/\s+/).filter((w) => w.length > 3);
+    const matchedWords = titleWords.filter((w) => h1Lower.includes(w));
+    if (matchedWords.length >= 1 || titleStem.includes(h1Lower) || h1Lower.includes(titleStem)) {
+      scentMatch = true;
+    }
+  }
+
+  if (scentMatch) {
+    atfScore += 30;
+    atfSignals.push(`Strong information scent: Title and primary H1 corroborate core value proposition ("${h1Text.slice(0, 50)}")`);
+  } else if (h1Text) {
+    atfScore += 15;
+    atfGaps.push(`Scent gap: Primary H1 ("${h1Text.slice(0, 40)}") diverges from title tag ("${titleStem.slice(0, 40)}")`);
+  } else {
+    atfGaps.push('Missing H1 headline above the fold to establish page purpose');
+  }
+
+  // Hero CTA presence & conspicuity
+  const heroCtas = ctas.filter((c) => c.inHero);
+  const primaryHeroCta = heroCtas.find((c) => c.isPrimary) || heroCtas[0];
+
+  const saliency = calculateVisualSaliency({
+    ctas: ctas.map((c) => ({ ...c, isPrimary: c.isPrimary })),
+    headings: headings.map((h) => ({ level: h.level || 1, text: h.text })),
+    forms: forms.map((f) => ({ fieldCount: f.fieldCount })),
+  });
+
+  const pci = saliency.primary_cta_conspicuity_index || 0;
+
+  if (primaryHeroCta && pci >= 0.60) {
+    atfScore += 30;
+    atfSignals.push(`Prominent hero CTA with optimal conspicuity (${Math.round(pci * 100)}% PCI score)`);
+  } else if (primaryHeroCta) {
+    atfScore += 20;
+    atfSignals.push(`Hero CTA present ("${primaryHeroCta.text}") but visual conspicuity is diluted (${Math.round(pci * 100)}% PCI score)`);
+  } else {
+    atfGaps.push('No primary CTA visible above the fold in the hero viewport');
+  }
+
+  // Choice overload penalty
+  if (heroCtas.filter((c) => c.isPrimary).length > 1) {
+    atfScore -= 10;
+    atfGaps.push(`Choice overload: ${heroCtas.filter((c) => c.isPrimary).length} competing primary CTAs in hero zone induce decision paralysis`);
+  }
+
+  // Value proposition lead copy (opening 80 words)
+  const firstP = page.paragraphs?.[0] || '';
+  if (firstP.length >= 40 && firstP.length <= 400) {
+    atfScore += 25;
+    atfSignals.push('Concise value proposition paragraph immediately supports hero headline');
+  } else if (firstP.length > 400) {
+    atfScore += 15;
+    atfGaps.push('Opening hero lead text is too verbose (>400 chars); condense into clear benefit bullets');
+  } else {
+    atfGaps.push('Missing explanatory sub-headline or lead benefit description above the fold');
+  }
+
+  // Supporting micro-signals (risk reversal near hero)
+  const heroText = (h1Text + ' ' + firstP + ' ' + (primaryHeroCta?.text || '')).toLowerCase();
+  if (RISK_REVERSAL_RX.test(heroText)) {
+    atfScore += 15;
+    atfSignals.push('Friction-reducing risk reversal (e.g. "No credit card required") placed directly proximate to hero CTA');
+  } else {
+    atfGaps.push('Add an explicit risk-reversal micro-copy badge under hero CTA (e.g. "Free 14-day trial • No credit card required")');
+  }
+
+  atfScore = Math.min(100, Math.max(0, atfScore));
+
+  // -------------------------------------------------------------
+  // 2. UX FRICTION, COGNITIVE LOAD & ABANDONMENT ANALYSIS
+  // -------------------------------------------------------------
+  const frictionIssues = [];
+  let frictionPoints = 0;
+
+  // Form field count & Keystroke Effort Index (KEI)
+  const totalInputs = forms.reduce((sum, f) => sum + (f.fieldCount || 0), 0);
+  const inputsWithAutocomplete = forms.reduce((sum, f) => sum + f.inputs.filter((inp) => Boolean(inp.autocomplete)).length, 0);
+  const manualKeystrokes = totalInputs * 14;
+  const autofillKeystrokes = totalInputs > 0 && inputsWithAutocomplete > 0
+    ? (totalInputs - inputsWithAutocomplete) * 14 + 1
+    : manualKeystrokes;
+  const keystrokeReductionPct = manualKeystrokes > 0
+    ? Math.round(((manualKeystrokes - autofillKeystrokes) / manualKeystrokes) * 100)
+    : 0;
+
+  for (const f of forms) {
+    if (f.fieldCount > 6) {
+      frictionPoints += 20;
+      frictionIssues.push({
+        severity: 'high',
+        type: 'form_length',
+        issue: `Form contains ${f.fieldCount} fields (recommend <= 4 fields for top-of-funnel lead capture)`,
+        remediation: 'Progressive profiling: reduce initial form fields to work email and name; capture details on subsequent step',
+      });
+    }
+
+    const missingAuto = f.inputs.filter((inp) => !inp.autocomplete && ['email', 'tel', 'text', 'name'].includes(inp.type));
+    if (missingAuto.length > 0) {
+      frictionPoints += 10;
+      frictionIssues.push({
+        severity: 'medium',
+        type: 'autocomplete_missing',
+        issue: `${missingAuto.length} input field(s) lack HTML5 autocomplete attributes, increasing mobile entry friction`,
+        remediation: 'Add standard autocomplete attributes (e.g. autocomplete="email", autocomplete="name", autocomplete="tel")',
+      });
+    }
+
+    if (!f.hasSubmit) {
+      frictionPoints += 30;
+      frictionIssues.push({
+        severity: 'critical',
+        type: 'missing_submit',
+        issue: 'Form has no explicit submit button or trigger mechanism',
+        remediation: 'Add an accessible <button type="submit"> element with clear action microcopy',
+      });
+    }
+  }
+
+  // Navigation distraction on conversion surfaces (leaks)
+  const reg = registryPageFor(ctx, page);
+  const isCheckoutOrCapture = ['checkout', 'pricing', 'signup', 'demo', 'cart'].some((t) => (page.url || '').toLowerCase().includes(t));
+  const navLinks = page.navLinksCount || root.querySelectorAll('header nav a, footer a').length;
+
+  if (isCheckoutOrCapture && navLinks > 15) {
+    frictionPoints += 15;
+    frictionIssues.push({
+      severity: 'medium',
+      type: 'funnel_leak',
+      issue: `High-intent conversion page contains ${navLinks} external/header navigation links (funnel leak)`,
+      remediation: 'Enclose conversion funnel: remove non-essential header navigation and social links during checkout/signup',
+    });
+  }
+
+  // Cognitive load index
+  let cognitiveLoad = 'minimal';
+  if (frictionPoints >= 40) cognitiveLoad = 'critical_friction';
+  else if (frictionPoints >= 25) cognitiveLoad = 'high_cognitive_load';
+  else if (frictionPoints >= 10) cognitiveLoad = 'moderate';
+
+  // -------------------------------------------------------------
+  // 3. TRUST, CREDIBILITY, OBJECTIONS & RISK-REVERSAL (0-100)
+  // -------------------------------------------------------------
+  let trustScore = 0;
+  const trustSignals = [];
+  const trustGaps = [];
+
+  // Social proof
+  const hasSocialProof = SOCIAL_PROOF_RX.test(text) || trustBadges.some((b) => /rating|review|g2|capterra|trustpilot/i.test(b.signal || ''));
+  if (hasSocialProof) {
+    trustScore += 25;
+    trustSignals.push('Customer social proof and review signals detected');
+  } else {
+    trustGaps.push('Add customer social proof (client logos, quantitative adoption stats, or verified review quotes)');
+  }
+
+  // Security credentials & badges
+  const hasSecurityBadge = trustBadges.some((b) => /security|ssl|soc-?2|iso|hipaa|pci|verified/i.test(b.signal || '')) ||
+    Boolean(root.querySelector('[class*="security"], [class*="trust"], [class*="badge"]'));
+  if (hasSecurityBadge) {
+    trustScore += 25;
+    trustSignals.push('Security compliance, SSL, or verification badges present');
+  } else {
+    trustGaps.push('Display enterprise security credentials (SOC-2, ISO, HIPAA, or encryption badges) proximate to conversion action');
+  }
+
+  // Risk reversal
+  const hasRiskReversal = RISK_REVERSAL_RX.test(text);
+  if (hasRiskReversal) {
+    trustScore += 25;
+    trustSignals.push('Explicit risk-reversal guarantees present (money-back guarantee, free trial, or cancel anytime)');
+  } else {
+    trustGaps.push('Eliminate buyer perceived risk with explicit guarantees ("Cancel anytime", "30-day money back guarantee")');
+  }
+
+  // Objection handling (FAQ or comparison)
+  const hasObjectionHandling = OBJECTION_RX.test(text) || root.querySelectorAll('details, .faq, #faq').length > 0;
+  if (hasObjectionHandling) {
+    trustScore += 25;
+    trustSignals.push('Pre-purchase objection handling and structured FAQ content detected');
+  } else {
+    trustGaps.push('Include a pre-purchase FAQ addressing common pricing, onboarding, and contract objections');
+  }
+
+  trustScore = Math.min(100, Math.max(0, trustScore));
+
+  // -------------------------------------------------------------
+  // 4. OFFER ARCHITECTURE & CTA HIERARCHY
+  // -------------------------------------------------------------
+  const offerFindings = [];
+  let primaryCtaCount = 0;
+  let genericCtaCount = 0;
+
+  for (const cta of ctas) {
+    if (cta.isPrimary) primaryCtaCount++;
+    if (GENERIC_CTA_RX.test(cta.text)) {
+      genericCtaCount++;
+      offerFindings.push({
+        cta: cta.text,
+        type: 'generic_microcopy',
+        remediation: `Replace low-intent generic copy "${cta.text}" with high-value benefit action copy (e.g. "Get Started Free", "Claim Your Audit")`,
+      });
+    }
+  }
+
+  const ctaHierarchy = {
+    total_ctas: ctas.length,
+    primary_ctas: primaryCtaCount,
+    secondary_ctas: ctas.length - primaryCtaCount,
+    generic_microcopy_count: genericCtaCount,
+    hierarchy_status: primaryCtaCount === 1 ? 'optimal' : primaryCtaCount > 1 ? 'choice_overload' : 'missing_primary',
+  };
+
+  // Express checkout
+  const walletRx = /apple\s*pay|google\s*pay|paypal|one-click/i;
+  const hasExpressPayment = ctas.some((c) => walletRx.test(c.text || '')) ||
+    trustBadges.some((t) => walletRx.test(t.signal || ''));
+
+  // -------------------------------------------------------------
+  // OVERALL CONVERSION READINESS SCORE (0-100)
+  // -------------------------------------------------------------
+  const conversionReadiness = Math.round(
+    (atfScore * 0.35) +
+    (trustScore * 0.30) +
+    (Math.max(0, 100 - frictionPoints) * 0.25) +
+    (ctaHierarchy.hierarchy_status === 'optimal' ? 10 : 5)
+  );
+
+  return {
+    url: page.url,
+    fact_status: 'modeled_cro_evaluation',
+    conversion_readiness_score: conversionReadiness,
+    atf_clarity: {
+      score: atfScore,
+      scent_match: scentMatch,
+      title_stem: titleStem,
+      h1_headline: h1Text,
+      pci_score_pct: Math.round(pci * 100),
+      signals: atfSignals,
+      gaps: atfGaps,
+    },
+    cognitive_load_and_friction: {
+      load_assessment: cognitiveLoad,
+      friction_points: frictionPoints,
+      keystroke_effort: {
+        total_inputs: totalInputs,
+        inputs_with_autocomplete: inputsWithAutocomplete,
+        keystroke_reduction_pct: keystrokeReductionPct,
+      },
+      issues: frictionIssues,
+    },
+    trust_and_credibility: {
+      score: trustScore,
+      signals: trustSignals,
+      gaps: trustGaps,
+      social_proof_detected: hasSocialProof,
+      security_badges_detected: hasSecurityBadge,
+      risk_reversal_detected: hasRiskReversal,
+      objection_handling_detected: hasObjectionHandling,
+    },
+    offer_architecture: {
+      cta_hierarchy: ctaHierarchy,
+      express_checkout_supported: hasExpressPayment,
+      findings: offerFindings,
+    },
+  };
+}