@nebulacomponents/citable 1.16.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",

package/schemas/cli-output-envelope.schema.json

@@ -0,0 +1,30 @@
+{
+  "$id": "citable://schemas/cli-output-envelope.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CLI JSON output envelope",
+  "description": "Stable envelope for every `citable <command> --json` output. Consumers read `citable_output_schema` for envelope compatibility and read command data from `result`. The envelope version changes only on breaking envelope changes; command payloads evolve backward-compatibly inside result.",
+  "type": "object",
+  "required": ["citable_output_schema", "tool_version", "generated_at", "result"],
+  "properties": {
+    "citable_output_schema": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Envelope contract version. 1.0 is the initial stable contract."
+    },
+    "tool_version": {
+      "type": "string",
+      "description": "Citable package version that produced the output."
+    },
+    "command": {
+      "type": ["string", "null"],
+      "description": "Top-level command that produced this output."
+    },
+    "generated_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp of when the output was generated."
+    },
+    "result": {
+      "description": "Command-specific payload. Structure is defined per command and evolves backward-compatibly within an envelope major version."
+    }
+  }
+}

package/schemas/finding.schema.json

@@ -257,6 +257,75 @@
         }
       }
     },
+    "provenance": {
+      "type": "object",
+      "required": [
+        "detector_version",
+        "tool_version",
+        "evidence_source",
+        "methodology",
+        "revalidation_required"
+      ],
+      "properties": {
+        "detector_version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "tool_version": {
+          "type": "string"
+        },
+        "source_url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "source_file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "evidence_selector": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "evidence_source": {
+          "type": "string",
+          "enum": [
+            "dom_parse",
+            "registry",
+            "registry+dom_parse",
+            "controlled_observation",
+            "configuration"
+          ]
+        },
+        "viewport": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "viewport_note": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "methodology": {
+          "type": "string"
+        },
+        "revalidation_required": {
+          "type": "string",
+          "enum": [
+            "on_next_audit",
+            "human_review_before_action"
+          ]
+        }
+      }
+    },
     "status": {
       "type": "object",
       "required": [

package/schemas/remediation-verification.schema.json

@@ -0,0 +1,98 @@
+{
+  "$id": "citable://schemas/remediation-verification.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Remediation verification record",
+  "description": "Closed-loop evidence that a detector finding was addressed: before-run finding, applied patch, re-run detector result, and verdict. Proves only that the detector no longer reports the same subject; it never proves a conversion or outcome guarantee.",
+  "type": "object",
+  "required": [
+    "verification_id", "timestamp", "status", "tool_version",
+    "source_run_id", "detector_id", "subject", "verdict",
+    "provenance", "limitations"
+  ],
+  "properties": {
+    "verification_id": { "type": "string", "pattern": "^VR-[0-9]{14,20}-[a-z0-9]{2,8}$" },
+    "timestamp": { "type": "string" },
+    "status": { "type": "string", "enum": ["verified", "not_resolved", "blocked", "patch_refused"] },
+    "tool_version": { "type": "string" },
+    "repository_commit": { "type": ["string", "null"] },
+    "source_run_id": { "type": ["string", "null"], "minLength": 1 },
+    "recheck_run_id": { "type": ["string", "null"] },
+    "detector_id": { "type": ["string", "null"] },
+    "subject": {
+      "type": ["object", "null"],
+      "properties": {
+        "type": { "type": "string" },
+        "identifier": { "type": ["string", "null"] }
+      }
+    },
+    "verdict": {
+      "type": "object",
+      "required": ["resolved"],
+      "properties": {
+        "resolved": { "type": "boolean" },
+        "before_finding_ids": { "type": "array", "items": { "type": "string" } },
+        "after_finding_ids": { "type": "array", "items": { "type": "string" } },
+        "new_regressions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["finding_id", "detector_id", "severity", "summary"],
+            "properties": {
+              "finding_id": { "type": "string" },
+              "detector_id": { "type": "string" },
+              "severity": { "type": "string" },
+              "summary": { "type": "string" }
+            }
+          }
+        },
+        "resolution_definition": {
+          "type": "string",
+          "description": "States the exact resolution criterion used; detector absence is not an outcome guarantee."
+        }
+      }
+    },
+    "patch": {
+      "type": ["object", "null"],
+      "properties": {
+        "target_file": { "type": "string" },
+        "framework": { "type": ["string", "null"] },
+        "patcher_class": { "type": ["string", "null"] },
+        "confidence": { "type": ["number", "null"] },
+        "validation_passed": { "type": "boolean" },
+        "applied": { "type": "boolean" },
+        "refusal_reason": { "type": ["string", "null"] },
+        "rollback_snapshot": { "type": ["string", "null"] },
+        "before_sha256": { "type": ["string", "null"] },
+        "after_sha256": { "type": ["string", "null"] }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "required": ["command", "recheck_target", "detectors_run"],
+      "properties": {
+        "command": { "type": "string" },
+        "recheck_target": { "type": ["string", "null"] },
+        "detectors_run": { "type": "array", "items": { "type": "string" } },
+        "detectors_skipped": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "detector_id": { "type": "string" },
+              "reason": { "type": "string" }
+            }
+          }
+        },
+        "recheck_errors": { "type": "array", "items": { "type": "string" } },
+        "recheck_warnings": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "limitations": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "bundle_dir": { "type": ["string", "null"] },
+    "bundle_checksums": { "type": "object" }
+  }
+}

package/schemas/sow.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "citable://schemas/sow.schema.json",
+  "title": "Enterprise Statement of Work (SOW)",
+  "type": "object",
+  "required": [
+    "sow_id",
+    "version",
+    "title",
+    "client",
+    "supplier",
+    "effective_date",
+    "executive_scope",
+    "admissibility_gate",
+    "work_packages",
+    "deliverables",
+    "acceptance_criteria",
+    "traceability_matrix"
+  ],
+  "properties": {
+    "sow_id": { "type": "string" },
+    "version": { "type": "string" },
+    "title": { "type": "string" },
+    "client": {
+      "type": "object",
+      "required": ["name", "contact"],
+      "properties": {
+        "name": { "type": "string" },
+        "contact": { "type": "string" }
+      }
+    },
+    "supplier": {
+      "type": "object",
+      "required": ["name", "contact"],
+      "properties": {
+        "name": { "type": "string" },
+        "contact": { "type": "string" }
+      }
+    },
+    "effective_date": { "type": "string" },
+    "term_days": { "type": "integer" },
+    "executive_scope": {
+      "type": "object",
+      "required": ["business_objective", "in_scope_properties", "in_scope_systems"],
+      "properties": {
+        "business_objective": { "type": "string" },
+        "in_scope_properties": { "type": "array", "items": { "type": "string" } },
+        "in_scope_systems": { "type": "array", "items": { "type": "string" } },
+        "channels": { "type": "array", "items": { "type": "string" } },
+        "geographies": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "admissibility_gate": {
+      "type": "object",
+      "required": ["total_findings_evaluated", "admitted_count", "refused_count"],
+      "properties": {
+        "total_findings_evaluated": { "type": "integer" },
+        "admitted_count": { "type": "integer" },
+        "refused_count": { "type": "integer" },
+        "refusal_log": { "type": "array" }
+      }
+    },
+    "work_packages": { "type": "array" },
+    "deliverables": { "type": "array" },
+    "acceptance_criteria": { "type": "array" },
+    "traceability_matrix": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "finding_id",
+          "recommendation",
+          "sow_requirement_id",
+          "deliverable_id",
+          "acceptance_test_id",
+          "owner",
+          "evidence_id"
+        ],
+        "properties": {
+          "finding_id": { "type": "string" },
+          "recommendation": { "type": "string" },
+          "sow_requirement_id": { "type": "string" },
+          "work_package_id": { "type": "string" },
+          "deliverable_id": { "type": "string" },
+          "acceptance_test_id": { "type": "string" },
+          "owner": { "type": "string" },
+          "evidence_id": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.16.0
+version: 1.18.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -88,7 +88,13 @@ prefer running it over re-deriving its checks by hand:
 citable init                        # initialize .citable/ (non-destructive)
 citable audit [scope] --target <dir|url> [--base-url <url>] [--ref-date YYYY-MM-DD]
 citable plan-audit --target <dir|url> [--base-url <url>]
+citable sweep technical --target <dir|url> # Technical SEO sweep + Core Web Vitals metrics
 citable inspect <page> --target <dir|url>
+citable inspect eeat <page> --target <dir|url> # On-page content analysis & 0-5 E-E-A-T score
+citable inspect readiness <page> --target <dir|url> # Answer-engine readiness (Perplexity, Copilot, ChatGPT)
+citable audit backlinks --input <file>  # Off-page authority assessment & toxic domain identification
+citable prioritize matrix [--run <run-id>] # Impact/Effort/Confidence (ICE) scoring matrix
+citable roadmap [generate|show]         # 30/90/180-day strategic milestone roadmap
 citable map-claims --target <dir|url> [--write]
 citable substantiate [--write]
 citable schema --target <dir|url>
@@ -109,6 +115,8 @@ citable monitor [runA runB] [--webhook <url>] [--min-severity <sev>]  # observat
 citable report dashboard [--last N] [--since <run-id>]  # cross-run evidence trend (Markdown + HTML)
 citable report share-of-voice [--last N] [--since <run-id>]  # competitor citation share (Markdown + HTML)
 citable report consensus [--last N] [--since <run-id>]  # canonical discovery consensus matrix (Markdown + HTML)
+citable report search [--target <dir|url>] [--run <id>] [--format md|html|json] # Enterprise Search Intelligence Briefing (19 pillars, evidence-traceable)
+citable report cro [--target <dir|url>] [--input <file>] [--format md|html|json] # Enterprise CRO & Journey Briefing (25 pillars: observations vs hypotheses vs causation)
 citable metrics import --provider <name> --input <csv|json>
 citable connect status
 citable connect configure --provider <gsc|ga4|wordpress|webflow> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
@@ -138,9 +146,29 @@ citable corpus evaluate --input <acceptance-corpus.json>
 citable corpus publish --input <acceptance-corpus.json> --output <public-corpus.json>
 citable corpus receipt --run <run-id> [--input <execution-context.json>]
 citable corpus compare-receipts <receipt-a.json> <receipt-b.json>
+citable corpus benchmark [--corpus <dir>] [--output <report.json>]  # labeled golden fixtures → per-detector precision/recall gate
 citable artifacts export <run-id> --output <directory>
 citable artifacts verify --input <directory>
 citable artifacts import --input <directory>
+citable inspect cro <page> --target <dir|url>   # CRO readiness: CTAs, forms, payment-wallet vs authentication readiness, modeled saliency indices
+citable cro [--target <dir|url>] [--funnel <id>] # Full CRO intelligence suite: funnel, ATF clarity, trust, cognitive load, ICE matrix, roadmap
+citable cro backlog [--target <dir|url>]         # Prioritized A/B experiment backlog with falsifiable hypotheses & guardrails
+citable cro roadmap [--target <dir|url>]         # 30/90/180-day CRO strategic roadmap tied to measurable conversion outcomes
+citable sweep technical [--target <dir|url>]    # Technical SEO sweep with Core Web Vitals readiness metrics (LCP, INP, CLS)
+citable inspect eeat <page> --target <dir|url>  # On-page E-E-A-T evaluation on a 0-5 rubric scale
+citable inspect readiness <page> --target <dir|url> # Answer-engine readiness across Perplexity, Bing Copilot, ChatGPT
+citable audit backlinks --input <backlinks.json> # Off-page authority assessment and toxic domain identification
+citable prioritize matrix                       # Impact/Effort/Confidence (ICE) scoring matrix for findings & roadmap
+citable roadmap strategic                       # 30/90/180-day strategic milestone horizons with KPI linkages
+citable preview cro <page> [--export <file.html>]  # split-screen before/remediated sandbox (layout-contract checked; accessibility-aware)
+citable remediate --finding <id> [--target <file>] [--write]  # production-safe patch: framework detection, unified diff, static validation, confidence gate, rollback snapshot; semantic copy changes always refuse automated write
+citable verify remediation --run <run-id> --finding <id> [--target <file>] [--apply]  # closed loop: re-run the detector and emit a before/after evidence bundle (schema remediation-verification)
+citable verify page <page> --target <dir|url>   # all detectors scoped to one page; pass = no detector currently reports it, never an outcome guarantee
+citable check experiment <id> [--observed-control N --observed-variant N --days-running N]  # SRM, stopping, power, contamination; lifecycle: planned|running|inconclusive|validated
+citable compatibility   # Node engine, optional adapters, browser, framework, registries, edge size limits
+citable kit export --run <run-id> --finding <id> [--target <file>]  # customer-ready implementation kit (finding, diff, evidence, acceptance tests, deployment, limitations)
+citable sow generate [--target <dir|url>] [--budget <amount>] [--format md|html|json] [--output <path>] # Enterprise SOW from findings with 6-gate admissibility & 7-column traceability
+citable sow validate <sow.json>                  # Validate SOW schema, admissibility gates, and complete traceability matrix
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -194,6 +222,43 @@ monitoring interpretation.
 Use `commands/field-validation.md` for acceptance-corpus authorization,
 sanitization, publication refusal, reproducibility, and evidence boundaries.
 
+## CRO remediation loop (audit → explain → remediate → verify → hand off)
+
+The CRO suite completes the loop. Rules that govern every step:
+
+1. **Safe patches only.** `remediate --write` is gated on framework detection,
+   static structural validation, idempotency, and an explicit confidence
+   threshold. Semantic microcopy replacements are refused for automated write
+   (fact ≠ inference): they require a human editorial decision. Every write
+   creates a rollback snapshot under `.citable/remediation/snapshots/`.
+2. **A written patch is not a verified repair.** Run
+   `verify remediation --run <run-id> --finding <id>`. Resolution means the
+   detector no longer reports the same subject — never a conversion guarantee.
+   The verification bundle is schema-validated
+   (`schemas/remediation-verification.schema.json`).
+3. **Payment wallets ≠ authentication.** Apple Pay/Google Pay/PayPal are
+   payment methods; WebAuthn/passkeys are account authentication. Report them
+   separately (`inspect cro` returns `payment_wallet_readiness` and
+   `authentication_readiness`). Never use "biometric readiness" as a claim.
+4. **Modeled indices are labeled.** Friction Surface Area, CTA Conspicuity
+   Index, and gaze-path ordering are heuristic indices over captured DOM
+   conditions — not observed user behavior and not revenue estimates. Slide
+   decks and kits must keep measured (deterministic findings) and modeled
+   (indices, projections) in separate, labeled categories. No latency,
+   speed, or "percentage eliminated" figure may be stated without a
+   documented measurement methodology.
+5. **Referral fragments are untrusted input.** ScentBeacon-style components
+   may match referrer/`:~:text=` against a fixed allowlist to detect the
+   referral state; raw values are never rendered, persisted, or transmitted.
+   Dynamic claim text must come from registry-bound developer props.
+6. **Experiments carry guardrails.** `check experiment` reports SRM, stopping
+   early, underpowered samples, contamination, and unsupported revenue
+   attribution, and derives one lifecycle of `planned`, `running`,
+   `inconclusive`, or `validated` — never "winner".
+7. **Machine-readable output is a contract.** `--json` wraps every command
+   payload in the `citable_output_schema` 1.0 envelope
+   (`schemas/cli-output-envelope.schema.json`).
+
 ## Command workflows
 
 Detailed per-command workflows live in `commands/`. Follow them; they define

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.',
+    ],
+  };
+}