@nebulacomponents/citable 1.14.0 → 1.15.1

package/src/commands/reportShareOfVoice.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  calculateShareOfVoice,
+  extractDomain,
+  loadCitationRuns,
+  renderShareOfVoiceHtml,
+  renderShareOfVoiceMarkdown,
+} from '../reporting/shareOfVoice.js';
+import { loadRegistries } from '../registries/index.js';
+
+/**
+ * `citable report share-of-voice` — compute first-party and competitor citation share
+ * across recorded observation runs. Never invents competitor citations; unevidenced
+ * prompts and competitors are reported plainly.
+ */
+export function reportShareOfVoice(root, { since, last } = {}) {
+  if (last != null && (!Number.isInteger(last) || last < 1)) {
+    throw new Error('--last must be a positive integer');
+  }
+
+  const { registries } = loadRegistries(root);
+  const competitors = registries.competitors?.entries || [];
+
+  const firstPartyDomains = new Set();
+  if (registries.config?.site?.base_url) {
+    const d = extractDomain(registries.config.site.base_url);
+    if (d) firstPartyDomains.add(d);
+  }
+  if (registries.pages?.entries) {
+    for (const p of registries.pages.entries) {
+      if (p.url) {
+        const d = extractDomain(p.url);
+        if (d) firstPartyDomains.add(d);
+      }
+    }
+  }
+
+  const { included, skipped } = loadCitationRuns(root, { since, last });
+  const data = calculateShareOfVoice(included, competitors, firstPartyDomains);
+
+  const dir = path.join(root, '.citable', 'reports');
+  const pathMd = path.join(dir, 'share-of-voice.md');
+  const pathHtml = path.join(dir, 'share-of-voice.html');
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(pathMd, renderShareOfVoiceMarkdown(data, skipped));
+  fs.writeFileSync(pathHtml, renderShareOfVoiceHtml(data, skipped));
+
+  return {
+    dir,
+    included: included.length,
+    skipped: skipped.length,
+    competitors_evaluated: competitors.length,
+    prompts_evaluated: data.prompts.length,
+    total_citations: data.total_citations_recorded,
+    path_md: pathMd,
+    path_html: pathHtml,
+  };
+}

package/src/connectors/http.js

@@ -1,15 +1,18 @@
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
 
-export async function providerRequest(url, { token, fetchImpl = globalThis.fetch, method = 'GET', body, attempts = 3 } = {}) {
+export async function providerRequest(url, { token, fetchImpl = globalThis.fetch, method = 'GET', body, headers = {}, attempts = 3, rawResponse = false } = {}) {
   if (!token) throw Object.assign(new Error('authorization is not configured'), { connectorState: 'not_configured' });
   let response;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     response = await fetchImpl(url, {
       method,
-      headers: { authorization: `Bearer ${token}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
+      headers: { authorization: `Bearer ${token}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}), ...headers },
       body: body ? JSON.stringify(body) : undefined,
     });
-    if (response.ok) return response.json();
+    if (response.ok) {
+      if (rawResponse) return response;
+      return response.json();
+    }
     const detail = (await response.text()).slice(0, 300);
     if (!RETRYABLE.has(response.status) || attempt === attempts) {
       const states = { 401: 'authorization_expired', 403: 'permission_denied', 429: 'quota_limited' };

package/src/connectors/index.js

@@ -1,7 +1,9 @@
 import { gscConnector } from './gsc.js';
 import { ga4Connector } from './ga4.js';
+import { wordpressConnector } from './wordpress.js';
+import { webflowConnector } from './webflow.js';
 
-const CONNECTORS = new Map([gscConnector, ga4Connector].map((connector) => [connector.provider, connector]));
+const CONNECTORS = new Map([gscConnector, ga4Connector, wordpressConnector, webflowConnector].map((connector) => [connector.provider, connector]));
 
 export function getConnector(provider) {
   const connector = CONNECTORS.get(String(provider).toLowerCase());

package/src/connectors/webflow.js

@@ -0,0 +1,224 @@
+import { providerRequest } from './http.js';
+import { sha256, nowIso } from '../shared/io.js';
+
+const BASE = 'https://api.webflow.com/v2';
+
+const METRICS = {
+  pages: { unit: 'count', value_type: 'integer' },
+  collections: { unit: 'count', value_type: 'integer' },
+  items: { unit: 'count', value_type: 'integer' },
+};
+
+function computeWebflowPayloadHash(payload) {
+  const canonical = {
+    target_id: String(payload.target_id || payload.id),
+    site_id: String(payload.site_id || ''),
+    title: String(payload.title || ''),
+    slug: String(payload.slug || ''),
+    meta_title: String(payload.meta_title || ''),
+    meta_description: String(payload.meta_description || ''),
+    open_graph_title: String(payload.open_graph_title || ''),
+    open_graph_description: String(payload.open_graph_description || ''),
+    body: String(payload.body || ''),
+  };
+  return sha256(JSON.stringify(canonical));
+}
+
+export const webflowConnector = {
+  provider: 'webflow',
+  defaultCredentialEnv: 'WEBFLOW_API_TOKEN',
+  readOnlyScopes: ['sites:read', 'pages:read', 'cms:read'],
+  writeScopes: ['pages:write', 'cms:write'],
+
+  describeMetrics() {
+    return METRICS;
+  },
+
+  async discoverProperties(context) {
+    const result = await providerRequest(`${BASE}/sites`, context);
+    const sites = result.sites || [];
+    return sites.map((site) => ({
+      property_id: site.id,
+      display_name: site.displayName || site.id,
+      custom_domains: (site.customDomains || []).map((d) => d.url || d.host || d),
+      time_zone: site.timeZone || null,
+      created_on: site.createdOn || null,
+      permission: 'administrator',
+    }));
+  },
+
+  async validateConnection(connection, context) {
+    const site = await providerRequest(`${BASE}/sites/${encodeURIComponent(connection.property_id)}`, context);
+    const valid = Boolean(site && site.id === connection.property_id);
+    return {
+      valid,
+      site_id: site?.id || connection.property_id,
+      display_name: site?.displayName || null,
+      last_published: site?.lastPublished || null,
+    };
+  },
+
+  async sync(connection, metrics, { startDate, endDate, ...context }) {
+    const siteId = connection.property_id;
+    const rows = [];
+    const metricNames = new Set(metrics.map((m) => m.external_name));
+
+    if (metricNames.has('pages')) {
+      const pageResult = await providerRequest(`${BASE}/sites/${encodeURIComponent(siteId)}/pages`, context);
+      const pages = pageResult.pages || [];
+      const pageMetric = metrics.find((m) => m.external_name === 'pages');
+      rows.push({
+        metric: pageMetric,
+        value: pages.length,
+        dimensions: { date: endDate },
+        observed_at: `${endDate}T00:00:00.000Z`,
+      });
+    }
+
+    if (metricNames.has('collections') || metricNames.has('items')) {
+      const collectionsResult = await providerRequest(`${BASE}/sites/${encodeURIComponent(siteId)}/collections`, context);
+      const collections = collectionsResult.collections || [];
+
+      if (metricNames.has('collections')) {
+        const colMetric = metrics.find((m) => m.external_name === 'collections');
+        rows.push({
+          metric: colMetric,
+          value: collections.length,
+          dimensions: { date: endDate },
+          observed_at: `${endDate}T00:00:00.000Z`,
+        });
+      }
+
+      if (metricNames.has('items')) {
+        let totalItems = 0;
+        for (const col of collections) {
+          const itemsResult = await providerRequest(`${BASE}/collections/${encodeURIComponent(col.id)}/items?limit=100`, context);
+          totalItems += (itemsResult.items || []).length;
+        }
+        const itemMetric = metrics.find((m) => m.external_name === 'items');
+        rows.push({
+          metric: itemMetric,
+          value: totalItems,
+          dimensions: { date: endDate },
+          observed_at: `${endDate}T00:00:00.000Z`,
+        });
+      }
+    }
+
+    return {
+      rows,
+      cursor: endDate,
+      limitations: [
+        'Webflow API enforces rate limits of 60 requests per minute.',
+        'Staged CMS changes require site publish to appear on live domains.',
+      ],
+    };
+  },
+
+  /**
+   * Read Webflow page or collection item content and SEO metadata with hash integrity.
+   */
+  async readContent(connection, targetId, context) {
+    if (!targetId) throw new Error('Webflow readContent requires targetId');
+    const page = await providerRequest(`${BASE}/pages/${encodeURIComponent(targetId)}`, context);
+
+    const payload = {
+      target_id: String(page.id),
+      site_id: page.siteId || connection.property_id,
+      title: page.title || '',
+      slug: page.slug || '',
+      meta_title: page.seo?.title || page.title || '',
+      meta_description: page.seo?.description || '',
+      open_graph_title: page.openGraph?.title || null,
+      open_graph_description: page.openGraph?.description || null,
+      body: page.body || '',
+      draft: Boolean(page.draft),
+      archived: Boolean(page.archived),
+      published: Boolean(page.published),
+    };
+
+    const contentHash = computeWebflowPayloadHash(payload);
+    return { ...payload, content_hash: contentHash };
+  },
+
+  /**
+   * Apply reviewed, hash-locked remediation to a Webflow page.
+   */
+  async applyRemediation(connection, remediation, context = {}) {
+    if (!remediation.reviewer) {
+      throw new Error('CMS remediation requires a named human reviewer per governance rules');
+    }
+    if (!remediation.expected_hash) {
+      throw new Error('CMS remediation requires expected_hash for hash-locking');
+    }
+    if (!remediation.target_id) {
+      throw new Error('CMS remediation requires target_id');
+    }
+
+    const current = await this.readContent(connection, remediation.target_id, context);
+    if (current.content_hash !== remediation.expected_hash) {
+      throw new Error(`stale remediation refused for Webflow ${remediation.target_id}: content hash changed (${current.content_hash} !== ${remediation.expected_hash})`);
+    }
+
+    const updates = remediation.updates || {};
+    const candidatePayload = {
+      ...current,
+      title: updates.title !== undefined ? updates.title : current.title,
+      slug: updates.slug !== undefined ? updates.slug : current.slug,
+      meta_title: updates.meta_title !== undefined ? updates.meta_title : current.meta_title,
+      meta_description: updates.meta_description !== undefined ? updates.meta_description : current.meta_description,
+      open_graph_title: updates.open_graph_title !== undefined ? updates.open_graph_title : current.open_graph_title,
+      open_graph_description: updates.open_graph_description !== undefined ? updates.open_graph_description : current.open_graph_description,
+      body: updates.body !== undefined ? updates.body : current.body,
+    };
+    const simulatedHash = computeWebflowPayloadHash(candidatePayload);
+
+    // Dry-run mode by default
+    if (!context.write) {
+      return {
+        status: 'proposed',
+        dry_run: true,
+        target_id: remediation.target_id,
+        before_hash: current.content_hash,
+        after_hash: simulatedHash,
+        updates,
+        reviewer: remediation.reviewer,
+      };
+    }
+
+    // Live update via PATCH
+    const body = {};
+    if (updates.title !== undefined) body.title = updates.title;
+    if (updates.slug !== undefined) body.slug = updates.slug;
+    if (updates.body !== undefined) body.body = updates.body;
+    if (updates.meta_title !== undefined || updates.meta_description !== undefined) {
+      body.seo = {
+        title: updates.meta_title !== undefined ? updates.meta_title : current.meta_title,
+        description: updates.meta_description !== undefined ? updates.meta_description : current.meta_description,
+      };
+    }
+    if (updates.open_graph_title !== undefined || updates.open_graph_description !== undefined) {
+      body.openGraph = {
+        title: updates.open_graph_title !== undefined ? updates.open_graph_title : current.open_graph_title,
+        description: updates.open_graph_description !== undefined ? updates.open_graph_description : current.open_graph_description,
+      };
+    }
+
+    await providerRequest(`${BASE}/pages/${encodeURIComponent(remediation.target_id)}`, {
+      ...context,
+      method: 'PATCH',
+      body,
+    });
+
+    const updated = await this.readContent(connection, remediation.target_id, context);
+    return {
+      status: 'applied',
+      dry_run: false,
+      target_id: remediation.target_id,
+      before_hash: current.content_hash,
+      after_hash: updated.content_hash,
+      updated_at: nowIso(),
+      reviewer: remediation.reviewer,
+    };
+  },
+};

package/src/connectors/wordpress.js

@@ -0,0 +1,226 @@
+import { providerRequest } from './http.js';
+import { sha256, nowIso } from '../shared/io.js';
+
+const METRICS = {
+  published_posts: { unit: 'count', value_type: 'integer' },
+  published_pages: { unit: 'count', value_type: 'integer' },
+};
+
+function normalizeBaseUrl(propertyId) {
+  if (!propertyId) throw new Error('WordPress property_id must be the base site or API URL');
+  return String(propertyId).replace(/\/+$/, '');
+}
+
+function computeCmsPayloadHash(payload) {
+  const canonical = {
+    target_id: String(payload.target_id || payload.id),
+    title: String(payload.title || ''),
+    content: String(payload.content || ''),
+    excerpt: String(payload.excerpt || ''),
+    slug: String(payload.slug || ''),
+    status: String(payload.status || 'publish'),
+    meta: payload.meta || {},
+    schema_data: payload.schema_data || null,
+  };
+  return sha256(JSON.stringify(canonical));
+}
+
+export const wordpressConnector = {
+  provider: 'wordpress',
+  defaultCredentialEnv: 'WORDPRESS_AUTH_TOKEN',
+  readOnlyScopes: [
+    'https://api.wordpress.org/auth/posts.readonly',
+    'https://api.wordpress.org/auth/pages.readonly',
+  ],
+  writeScopes: [
+    'https://api.wordpress.org/auth/posts.edit',
+    'https://api.wordpress.org/auth/pages.edit',
+  ],
+
+  describeMetrics() {
+    return METRICS;
+  },
+
+  async discoverProperties(context) {
+    const targetUrl = context.property_id || context.siteUrl || context.url;
+    if (!targetUrl) {
+      return [{
+        property_id: 'https://example.test',
+        display_name: 'WordPress Site (configure with site URL)',
+        permission: 'administrator',
+      }];
+    }
+    const base = normalizeBaseUrl(targetUrl);
+    const siteInfo = await providerRequest(`${base}/wp-json`, context);
+    return [{
+      property_id: siteInfo.url || base,
+      display_name: siteInfo.name || base,
+      description: siteInfo.description || null,
+      home: siteInfo.home || null,
+      permission: 'administrator',
+    }];
+  },
+
+  async validateConnection(connection, context) {
+    const base = normalizeBaseUrl(connection.property_id);
+    const user = await providerRequest(`${base}/wp-json/wp/v2/users/me?context=edit`, context);
+    const valid = Boolean(user && (user.id || user.name));
+    return {
+      valid,
+      user: user?.name || null,
+      roles: user?.roles || [],
+      capabilities: user?.capabilities || {},
+    };
+  },
+
+  async sync(connection, metrics, { startDate, endDate, ...context }) {
+    const base = normalizeBaseUrl(connection.property_id);
+    const rows = [];
+    const metricNames = new Set(metrics.map((m) => m.external_name));
+
+    if (metricNames.has('published_posts')) {
+      const posts = await providerRequest(`${base}/wp-json/wp/v2/posts?per_page=100&status=publish`, context);
+      const postMetric = metrics.find((m) => m.external_name === 'published_posts');
+      rows.push({
+        metric: postMetric,
+        value: Array.isArray(posts) ? posts.length : 0,
+        dimensions: { date: endDate },
+        observed_at: `${endDate}T00:00:00.000Z`,
+      });
+    }
+
+    if (metricNames.has('published_pages')) {
+      const pages = await providerRequest(`${base}/wp-json/wp/v2/pages?per_page=100&status=publish`, context);
+      const pageMetric = metrics.find((m) => m.external_name === 'published_pages');
+      rows.push({
+        metric: pageMetric,
+        value: Array.isArray(pages) ? pages.length : 0,
+        dimensions: { date: endDate },
+        observed_at: `${endDate}T00:00:00.000Z`,
+      });
+    }
+
+    return {
+      rows,
+      cursor: endDate,
+      limitations: [
+        'WordPress REST API collection is bounded to accessible posts and pages.',
+        'Custom post types outside standard posts and pages require dedicated endpoint parameters.',
+      ],
+    };
+  },
+
+  /**
+   * Read CMS page/post content, metadata, and structured data with hash integrity.
+   */
+  async readContent(connection, targetId, context) {
+    if (!targetId) throw new Error('WordPress readContent requires targetId');
+    const base = normalizeBaseUrl(connection.property_id);
+    let item;
+    try {
+      item = await providerRequest(`${base}/wp-json/wp/v2/pages/${encodeURIComponent(targetId)}?context=edit`, context);
+    } catch {
+      // Fall back to posts if not a page
+      item = await providerRequest(`${base}/wp-json/wp/v2/posts/${encodeURIComponent(targetId)}?context=edit`, context);
+    }
+
+    const payload = {
+      target_id: String(item.id),
+      type: item.type || 'page',
+      url: item.link || '',
+      slug: item.slug || '',
+      status: item.status || 'publish',
+      title: item.title?.raw ?? item.title?.rendered ?? '',
+      content: item.content?.raw ?? item.content?.rendered ?? '',
+      excerpt: item.excerpt?.raw ?? item.excerpt?.rendered ?? '',
+      meta: item.meta || {},
+      schema_data: item.meta?.schema_data || null,
+      yoast_title: item.meta?._yoast_wpseo_title || null,
+      yoast_metadesc: item.meta?._yoast_wpseo_metadesc || null,
+      modified_gmt: item.modified_gmt || null,
+    };
+
+    const contentHash = computeCmsPayloadHash(payload);
+    return { ...payload, content_hash: contentHash };
+  },
+
+  /**
+   * Apply reviewed, hash-locked remediation to WordPress page or post.
+   */
+  async applyRemediation(connection, remediation, context = {}) {
+    if (!remediation.reviewer) {
+      throw new Error('CMS remediation requires a named human reviewer per governance rules');
+    }
+    if (!remediation.expected_hash) {
+      throw new Error('CMS remediation requires expected_hash for hash-locking');
+    }
+    if (!remediation.target_id) {
+      throw new Error('CMS remediation requires target_id');
+    }
+
+    const current = await this.readContent(connection, remediation.target_id, context);
+    if (current.content_hash !== remediation.expected_hash) {
+      throw new Error(`stale remediation refused for WordPress ${remediation.target_id}: content hash changed (${current.content_hash} !== ${remediation.expected_hash})`);
+    }
+
+    const updates = remediation.updates || {};
+    const candidatePayload = {
+      ...current,
+      title: updates.title !== undefined ? updates.title : current.title,
+      content: updates.content !== undefined ? updates.content : current.content,
+      excerpt: updates.excerpt !== undefined ? updates.excerpt : current.excerpt,
+      slug: updates.slug !== undefined ? updates.slug : current.slug,
+      status: updates.status !== undefined ? updates.status : current.status,
+      meta: updates.meta !== undefined ? updates.meta : current.meta,
+      schema_data: updates.schema_data !== undefined ? updates.schema_data : current.schema_data,
+    };
+    const simulatedHash = computeCmsPayloadHash(candidatePayload);
+
+    // Dry-run mode by default
+    if (!context.write) {
+      return {
+        status: 'proposed',
+        dry_run: true,
+        target_id: remediation.target_id,
+        before_hash: current.content_hash,
+        after_hash: simulatedHash,
+        updates,
+        reviewer: remediation.reviewer,
+      };
+    }
+
+    // Live update
+    const base = normalizeBaseUrl(connection.property_id);
+    const endpoint = current.type === 'post' ? 'posts' : 'pages';
+    const body = {};
+    if (updates.title !== undefined) body.title = updates.title;
+    if (updates.content !== undefined) body.content = updates.content;
+    if (updates.excerpt !== undefined) body.excerpt = updates.excerpt;
+    if (updates.slug !== undefined) body.slug = updates.slug;
+    if (updates.status !== undefined) body.status = updates.status;
+    if (updates.meta !== undefined || updates.schema_data !== undefined) {
+      body.meta = {
+        ...(current.meta || {}),
+        ...(updates.meta || {}),
+        ...(updates.schema_data !== undefined ? { schema_data: updates.schema_data } : {}),
+      };
+    }
+
+    await providerRequest(`${base}/wp-json/wp/v2/${endpoint}/${encodeURIComponent(remediation.target_id)}`, {
+      ...context,
+      method: 'POST',
+      body,
+    });
+
+    const updated = await this.readContent(connection, remediation.target_id, context);
+    return {
+      status: 'applied',
+      dry_run: false,
+      target_id: remediation.target_id,
+      before_hash: current.content_hash,
+      after_hash: updated.content_hash,
+      updated_at: nowIso(),
+      reviewer: remediation.reviewer,
+    };
+  },
+};

package/src/detectors/geoReco.js

@@ -1,4 +1,5 @@
 import { defineDetector, indexTargets, registryPageFor, sitePageFor, pageSubject, entrySubject } from './framework.js';
+import { classifyAnswerStance } from '../observations/stance.js';
 
 const D = [];
 
@@ -223,6 +224,106 @@ D.push(defineDetector({
   },
 }));
 
+D.push(defineDetector({
+  id: 'GEO-007', name: 'Unfavorable or distorted entity stance in recorded generative answers', namespace: 'GEO',
+  description: 'Recorded generative engine answers express an unfavorable, negative, or critically distorted stance toward a registered entity.',
+  discipline: ['geo', 'aeo'], severity: 'high', deterministic: false, requires: ['registries'],
+  finding_type: 'evidence_backed_semantic_finding',
+  impact: { representation: 'high', reputational: 'high', conversion: 'medium' },
+  applicable_requirement: 'GEO §6: accurate synthesis and entity representation; Rubric: narrative accuracy (§4 & §5)',
+  false_positive_conditions: ['Legitimate negative comparison where a product does not support a feature by design'],
+  remediation: 'Review the recorded answers against the narrative-accuracy rubric, identify whether the negative characterization reflects true product limitations or factual inaccuracies/outdated information, and publish authoritative corroborating evidence or file model corrections.',
+  unsafe_shortcuts: ['publishing fabricated positive reviews', 'manipulating third-party review sites', 'crawler prompt injection (GEO-001)'],
+  verification: 'Follow-up generative engine observations demonstrate neutral or favorable stance with no narrative-accuracy violations.',
+  review_required: true,
+  check(ctx) {
+    const entities = (ctx.registries?.entities?.entries || []).filter((e) => e.status !== 'retired');
+    if (!entities.length) return [];
+    const hits = [];
+
+    // 1. Check promptResults
+    for (const pr of ctx.promptResults || []) {
+      for (const e of entities) {
+        const names = [e.canonical_name, ...(e.aliases || [])].map((n) => n.toLowerCase());
+        const text = `${pr.prompt_text || ''} ${pr.answer_text || ''}`.toLowerCase();
+        const mentioned = names.some((n) => text.includes(n));
+        if (!mentioned) continue;
+
+        const classification = classifyAnswerStance(pr.answer_text || '', e, { reviewer: pr.evaluator });
+        const isNegativeSentiment = pr.sentiment === 'negative' || pr.recommendation_status === 'not_recommended';
+        if (classification.stance === 'unfavorable' || isNegativeSentiment) {
+          hits.push({
+            subject: entrySubject('entities', e.entity_id),
+            summary: `Generative engine ${pr.engine || 'unknown'} expresses unfavorable stance toward entity "${e.canonical_name}"`,
+            evidence: [
+              `engine: ${pr.engine || 'unknown'}`,
+              `prompt: ${pr.prompt_text || pr.prompt_id || 'unknown'}`,
+              `stance: unfavorable`,
+              `markers: ${classification.unfavorable_markers?.join(', ') || 'recorded negative sentiment'}`,
+              `excerpt: "${(classification.evidence_passages?.[0] || pr.answer_text || '').slice(0, 160)}"`,
+              `reviewer: ${pr.evaluator || 'unreviewed (semantic review required)'}`,
+            ],
+            confidence: pr.evaluator ? 'confirmed' : 'medium',
+            finding_type: 'evidence_backed_semantic_finding',
+          });
+        }
+      }
+    }
+
+    // 2. Check observations (stance or citation)
+    for (const obs of ctx.observations || []) {
+      if (obs.kind === 'stance' && obs.data?.stance === 'unfavorable') {
+        const e = entities.find((ent) => ent.entity_id === obs.data.entity_id);
+        if (e) {
+          hits.push({
+            subject: entrySubject('entities', e.entity_id),
+            summary: `Generative engine ${obs.data.engine || 'unknown'} expresses unfavorable stance toward entity "${e.canonical_name}"`,
+            evidence: [
+              `engine: ${obs.data.engine || 'unknown'}`,
+              `prompt: ${obs.data.prompt_text || obs.data.prompt_id || 'unknown'}`,
+              `stance: unfavorable`,
+              `markers: ${(obs.data.unfavorable_markers || []).join(', ') || 'unfavorable markers'}`,
+              `excerpt: "${(obs.data.evidence_passages?.[0] || '').slice(0, 160)}"`,
+              `reviewer: ${obs.data.reviewer || 'unreviewed (semantic review required)'}`,
+            ],
+            confidence: obs.data.reviewer ? 'confirmed' : 'medium',
+            finding_type: 'evidence_backed_semantic_finding',
+          });
+        }
+      } else if (obs.kind === 'citation' && obs.data?.answer_text) {
+        for (const e of entities) {
+          const classification = classifyAnswerStance(obs.data.answer_text, e);
+          if (classification.mentioned && classification.stance === 'unfavorable') {
+            hits.push({
+              subject: entrySubject('entities', e.entity_id),
+              summary: `Generative engine ${obs.data.provider || 'unknown'} expresses unfavorable stance toward entity "${e.canonical_name}"`,
+              evidence: [
+                `engine: ${obs.data.provider || 'unknown'}`,
+                `prompt: ${obs.data.prompt_text || obs.data.prompt_id || 'unknown'}`,
+                `stance: unfavorable`,
+                `markers: ${(classification.unfavorable_markers || []).join(', ')}`,
+                `excerpt: "${(classification.evidence_passages?.[0] || obs.data.answer_text).slice(0, 160)}"`,
+                `reviewer: unreviewed (semantic review required)`,
+              ],
+              confidence: 'medium',
+              finding_type: 'evidence_backed_semantic_finding',
+            });
+          }
+        }
+      }
+    }
+
+    // Deduplicate by entity and summary
+    const seen = new Set();
+    return hits.filter((h) => {
+      const k = `${h.subject.identifier}|${h.summary}`;
+      if (seen.has(k)) return false;
+      seen.add(k);
+      return true;
+    });
+  },
+}));
+
 /* ---------------- RECO: recommendation eligibility ---------------- */
 
 const RECO_CHECKS = [