agentlinkops 0.6.1 → 0.6.3

package/src/citations/contract.js

@@ -13,6 +13,7 @@ import { z } from 'zod';
 import { validatePublicUrl } from '../verifier/url.js';
 
 export const CITATIONS_VERSION = 1;
+export const CITATION_PANEL_VERSION = 2;
 
 // Outcome tiers, weakest to strongest. `unknown` is NOT the bottom of a scale: it is
 // excluded from every denominator, exactly as a blocked fetch is never a lost link.
@@ -55,11 +56,11 @@ export const CITATION_LIMITS = Object.freeze({
 });
 
 const httpsUrl = z.string().refine((value) => {
-  try { return validatePublicUrl(value); } catch { return false; }
+  try { return new URL(value).protocol === 'https:' && validatePublicUrl(value).valid; } catch { return false; }
 }, { message: 'a public https URL is required' });
 
 export const citationTargetSchema = z.object({
-  domain: z.string().min(3).optional(),
+  domain: z.string().min(3).refine(value => !/[/?#@:]/.test(value) && validatePublicUrl(`https://${value}/`).valid, { message: 'a public hostname is required' }).optional(),
   url: httpsUrl.optional(),
   scope: z.enum(CITATION_TARGET_SCOPES).default('domain'),
   brand: z.string().min(1),
@@ -71,6 +72,9 @@ export const citationTargetSchema = z.object({
 export const citationPromptSchema = z.object({
   id: z.string().min(1).max(80).optional(),
   text: z.string().min(1).max(2000),
+  intent_cluster: z.string().min(1).max(100).optional(),
+  branded: z.boolean().default(false),
+  provenance: z.object({ source: z.enum(['gsc', 'paa', 'autocomplete', 'manual']), reference: z.string().min(1).max(1000), observed_at: z.iso.datetime({ offset: true }), basis: z.literal('user_supplied') }).optional(),
 });
 
 export const citationEngineSpecSchema = z.object({
@@ -79,10 +83,23 @@ export const citationEngineSpecSchema = z.object({
   engine: z.string().min(2).max(40),
   via: z.enum(['api', 'browser']).default('api'),
   model: z.string().min(1).max(80).optional(),
+  country: z.string().regex(/^[A-Z]{2}$/).optional(),
 });
 
-export const citationPanelSchema = z.object({
-  schema_version: z.literal(CITATIONS_VERSION),
+export function migrateCitationPanel(raw) {
+  if (!raw || typeof raw !== 'object' || ![1, 2].includes(raw.schema_version)) return raw;
+  const targets = Array.isArray(raw.targets) ? [...raw.targets] : raw.targets;
+  if (Array.isArray(targets) && Array.isArray(raw.competitors)) {
+    for (const competitor of raw.competitors) {
+      if (competitor && typeof competitor.domain === 'string' && !targets.some(target => target?.scope !== 'url' && target?.domain?.toLowerCase() === competitor.domain.toLowerCase())) {
+        targets.push({ ...competitor, scope: 'domain' });
+      }
+    }
+  }
+  return { ...raw, schema_version: CITATION_PANEL_VERSION, targets, country: raw.country ?? (raw.locale ?? 'en-US').split('-').at(-1) };
+}
+export const citationPanelSchema = z.preprocess(migrateCitationPanel, z.object({
+  schema_version: z.literal(CITATION_PANEL_VERSION),
   targets: z.array(citationTargetSchema).min(1).max(50),
   prompts: z.array(citationPromptSchema).min(1).max(500),
   engines: z.array(citationEngineSpecSchema).min(1).max(4),
@@ -100,9 +117,19 @@ export const citationPanelSchema = z.object({
     aliases: z.array(z.string().min(1).max(100)).max(12).default([]),
   })).max(10).default([]),
   // Locale pinning: surfaces vary answers by geography. Default en-US.
-  locale: z.string().min(2).max(10).default('en-US'),
+  locale: z.string().regex(/^[a-z]{2,3}-[A-Z]{2}$/).default('en-US'),
+  country: z.string().regex(/^[A-Z]{2}$/).default('US'),
   note: z.string().max(500).optional(),
-});
+}));
+
+export function panelLocaleContext(panel, spec) {
+  return { locale: panel.locale ?? 'en-US', country: spec.country ?? panel.country ?? 'US',
+    mode: spec.engine === 'mock' ? 'fixture' : spec.engine === 'google-aio' ? 'supplier-location' : 'single-locale-unverified' };
+}
+export function localizedPromptId(promptId, context) {
+  // Preserve legacy en-US/US cell identities; other contexts get distinct baselines.
+  return context.locale === 'en-US' && context.country === 'US' ? promptId : `${promptId}@${context.locale}:${context.country}`;
+}
 
 // The engine identity names HOW a surface was reached, because the same engine two
 // ways is two different measurements and is never averaged (limelitgeo/open's rule).
@@ -110,6 +137,7 @@ export function engineIdentity(spec) {
   const provider = spec.via === 'browser' ? 'web-own-browser' : spec.engine === 'mock' ? 'builtin' : 'api';
   const parts = [spec.engine, provider];
   if (spec.model) parts.push(spec.model);
+  if (spec.country && spec.country !== 'US') parts.push(`country:${spec.country}`);
   return parts.join(':');
 }
 
@@ -135,7 +163,17 @@ export const evidenceEnvelopeSchema = z.object({
   screenshot_file: z.string().max(120).optional(),
   prompt: z.string().min(1),
   engine_identity: z.string().min(1),
+  locale_context: z.object({ locale: z.string(), country: z.string(), mode: z.enum(['fixture', 'supplier-location', 'single-locale-unverified']) }).optional(),
   provider_model_version: z.string().min(1),
+  browser_context: z.object({ surface: z.literal('web'), authentication: z.enum(['saved-session', 'anonymous']), account_tier: z.literal('unknown') }).optional(),
+  // Adapter provenance is request/response metadata, never supplier credentials.
+  provenance: z.object({
+    query: z.string().max(700), location_code: z.number().int().positive(), language_code: z.string().max(20),
+    device: z.enum(['desktop','mobile']), endpoint: z.string().url(), depth: z.number().int().positive(),
+    load_async_ai_overview: z.boolean(), task_id: z.string().nullable().optional(), checked_at: z.string().nullable().optional(),
+    check_url: z.string().nullable().optional(), provider_query: z.string().nullable().optional(), provider_device: z.string().nullable().optional(),
+  }).optional(),
+  failure: z.object({ code: z.string().max(100), message: z.string().max(2000) }).optional(),
   answer: z.string(),
   citations: z.array(z.object({ url: httpsUrl, title: z.string().max(500).optional() })).max(200),
   fan_out: z.array(z.string().max(500)).max(100).default([]),
@@ -153,6 +191,8 @@ export const observationRowSchema = z.object({
   cell_id: z.string().min(1),
   run_index: z.number().int().nonnegative(),
   outcome: z.enum(CITATION_OUTCOMES),
+  brand_mentioned: z.boolean().nullable().optional(),
+  target_cited: z.boolean().nullable().optional(),
   cited_urls: z.array(z.string().max(2048)).max(50).default([]),
   verify: z.enum(['unverified', 'reachable', 'unreachable', 'unknown']).default('unverified'),
   evidence_sha256: z.string().length(64),
@@ -172,10 +212,16 @@ export const epochRowSchema = z.object({
   n: z.number().int().nonnegative(),
   unknowns: z.number().int().nonnegative(),
   mentioned: z.number().int().nonnegative(),
-  rate: z.number().min(0).max(1),
-  ci_low: z.number().min(0).max(1),
-  ci_high: z.number().min(0).max(1),
+  rate: z.number().min(0).max(1).nullable(),
+  ci_low: z.number().min(0).max(1).nullable(),
+  ci_high: z.number().min(0).max(1).nullable(),
   classification: z.enum(EPOCH_CLASSIFICATIONS),
+  statistics: z.object({
+    scope: z.literal('fixed-epoch-supplemental'),
+    confidence_sequence: z.record(z.string(), z.unknown()).nullable(),
+    epoch_comparison: z.record(z.string(), z.unknown()).nullable(),
+    changepoint: z.record(z.string(), z.unknown()),
+  }).optional(),
   baseline: z.object({
     epoch_id: z.string().min(1),
     rate: z.number().min(0).max(1),

package/src/citations/inventory.js

@@ -0,0 +1,106 @@
+import { readFile, readdir, lstat, realpath } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { citationPanelSchema, evidenceEnvelopeSchema, targetKey } from './contract.js';
+import { panelEpochs } from './report.js';
+import { analyzeRetainedAnswer } from './match.js';
+import { parseOpportunityRecord, opportunityRecordId, ELIGIBILITY_GATES } from '../../shared/opportunity-record.js';
+const hash = value => createHash('sha256').update(value).digest('hex');
+
+export async function freezeCitationInventory({ dir, panel: input, epochId }) {
+  const panel = citationPanelSchema.parse(input);
+  const epochs = await panelEpochs({ dir, panel });
+  const cells = epochId ? epochs.find(rows => rows[0]?.epoch_id === epochId) : epochs[0];
+  if (!cells) throw new Error('No matching panel epoch to freeze');
+  epochId = cells[0].epoch_id;
+  if (!/^[A-Za-z0-9_.-]+$/.test(epochId) || ['.', '..'].includes(epochId)) throw new Error('Invalid epoch reference');
+  const root = await realpath(resolve(dir)); const evidenceDir = join(root, 'citations/evidence', epochId);
+  let files = [];
+  try {
+    if (!(await lstat(evidenceDir)).isDirectory() || !(await realpath(evidenceDir)).startsWith(root + '/')) throw new Error('Unsafe evidence directory');
+    files = await readdir(evidenceDir);
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const observations = []; const identities = new Set(); let invalid = 0;
+  for (const file of files.sort()) {
+    if (!/^[a-f0-9]{64}\.json$/.test(file)) continue;
+    const path = join(evidenceDir, file);
+    if (!(await lstat(path)).isFile()) { invalid++; continue; }
+    let envelope, text;
+    try { text = await readFile(path, 'utf8'); envelope = evidenceEnvelopeSchema.parse(JSON.parse(text)); }
+    catch { invalid++; continue; }
+    if (envelope.epoch_id !== epochId || !cells.some(cell => cell.cell_id === envelope.cell_id)) continue;
+    const identity = `${envelope.cell_id}|${envelope.run_index}`;
+    if (identities.has(identity)) throw new Error('Duplicate observation identity in retained evidence'); identities.add(identity);
+    const [, promptId, key] = envelope.cell_id.split('|');
+    const target = panel.targets.find(target => targetKey(target) === key);
+    if (!target) continue;
+    const prompt = panel.prompts.find(prompt => { const id = prompt.id ?? hash(prompt.text).slice(0, 10); return id === promptId || promptId?.startsWith(`${id}@`); });
+    const analysis = envelope.engine_identity.startsWith('google-aio:') && !envelope.provenance ? { mentioned: null, cited: null, outcome: 'unknown' } : analyzeRetainedAnswer(target, envelope);
+    observations.push({ cell_id: envelope.cell_id, run_index: envelope.run_index, engine_identity: envelope.engine_identity,
+      prompt_id: promptId, prompt: envelope.prompt, headline_eligible: !prompt?.branded, prompt_provenance: prompt?.provenance ?? null,
+      intent_cluster: prompt?.intent_cluster ?? null, target: key, observed_at: envelope.at,
+      provider_model_version: envelope.provider_model_version, locale_context: envelope.locale_context ?? null,
+      mentioned: analysis.mentioned, cited: analysis.cited, outcome: analysis.outcome,
+      citations: analysis.outcome === 'unknown' ? [] : envelope.citations,
+      evidence_sha256: hash(text), fixture: envelope.engine_identity.startsWith('mock:') });
+  }
+  const expected = cells.reduce((count, cell) => count + (cell.n ?? 0) + (cell.unknowns ?? 0), 0);
+  const payload = { schema_version: 1, kind: 'frozen_citation_inventory', epoch_id: epochId, frozen_at: new Date().toISOString(),
+    scope: 'Only the retained observations in this fixed panel epoch; missing rows do not prove absence.',
+    absence_claim: 'not_supported', panel: { ...panel, mockFixtures: undefined }, cells,
+    spent_estimate_usd: Math.max(0, ...cells.map(cell => cell.spent_estimate_usd ?? 0)),
+    missing_envelopes: Math.max(0, expected - observations.length), invalid_envelopes: invalid, observations };
+  return { ...payload, inventory_sha256: hash(JSON.stringify(payload)) };
+}
+
+function validateInventory(inventory) {
+  if (inventory?.kind !== 'frozen_citation_inventory') throw new Error('A frozen citation inventory is required');
+  const { inventory_sha256, ...payload } = inventory;
+  if (hash(JSON.stringify(payload)) !== inventory_sha256) throw new Error('Frozen inventory checksum does not match');
+}
+
+export function citationGap(inventory) {
+  validateInventory(inventory);
+  return { inventory_sha256: inventory.inventory_sha256, absence_claim: 'not_supported',
+    scope: 'Citation and mention counts describe this dataset only, separately by engine, prompt and target.',
+    cells: inventory.cells.map(cell => {
+      const rows = inventory.observations.filter(row => row.cell_id === cell.cell_id);
+      const known = rows.filter(row => row.outcome !== 'unknown');
+      const cited = known.filter(row => row.cited).length;
+      return { cell_id: cell.cell_id, n: known.length, cited, mentioned: known.filter(row => row.mentioned).length,
+        unknowns: rows.length - known.length, missing_envelopes: Math.max(0, (cell.n ?? 0) + (cell.unknowns ?? 0) - rows.length),
+        headline_eligible: rows.length > 0 && rows.every(row => row.headline_eligible),
+        finding: !known.length ? 'unknown' : cited ? 'cited_in_this_dataset' : 'not_cited_in_these_known_samples' };
+    }),
+    mentioned_not_cited: inventory.observations.filter(row => row.mentioned === true && row.cited === false).map(row => ({ cell_id: row.cell_id, prompt: row.prompt, evidence_sha256: row.evidence_sha256 })) };
+}
+
+export async function exportCitationSources(inventory, { niche, consentRef, excludedInputsAttested = false } = {}) {
+  if (!consentRef || !excludedInputsAttested) throw new Error('Library export requires a written consent reference and an explicit excluded-inputs attestation');
+  validateInventory(inventory);
+  const records = new Map();
+  for (const row of inventory.observations) {
+    if (row.outcome === 'unknown' || !row.headline_eligible) continue;
+    // Private named-brand questions are not public opportunity-library fields.
+    if (inventory.panel.targets.some(target => [target.brand, ...(target.aliases ?? []), target.domain].filter(Boolean).some(value => row.prompt.toLowerCase().includes(value.toLowerCase())))) continue;
+    for (const citation of row.citations) {
+      const host = new URL(citation.url).hostname; const subject = { host, page_url: citation.url, route_url: null, surface: 'ai_citation' };
+      const id = await opportunityRecordId(niche?.id, subject);
+      if (records.has(id)) continue;
+      const at = row.observed_at;
+      const record = { schema_version: 1, record_id: id, status: 'held', niche, opportunity_type: 'ai_citation_source', type_basis: 'observed', subject,
+        observed: { rel_tokens: null, indexing: 'unknown', cost_basis: 'unknown', audience_statement: null, cited_destinations: [],
+          ai_citation: { query: row.prompt, model: row.provider_model_version ?? 'unknown', observed_at: at } },
+        contact_route: { class: 'unknown', deliverability: 'not_checked', observed_at: null },
+        eligibility: { gates: ELIGIBILITY_GATES.map(gate => ({ gate, verdict: 'not_satisfied', because: row.fixture ? 'fixture_not_live_evidence' : 'public_page_and_rights_review_pending', observed_at: null })) },
+        verification: { route_state: 'unverified', listing_state: 'not_checked', last_verified_at: null, next_due_at: null, window_days: 90, unknown_streak: 0, reason: 'page_verification_pending' },
+        provenance: { source_class: 'consented_project_lane', run_id: inventory.epoch_id, seed_reason: row.fixture ? 'fixture_only' : 'retained_assistant_citation', consent_ref: consentRef, first_seen_at: at, last_seen_at: at },
+        rights: { basis: 'owned_observation_of_public_page', redistributable: false, excluded_inputs_attested: true, takedown_route: 'withdraw_on_request' },
+        evidence: [{ observed_at: at, observer: 'assistant_query', outcome: row.fixture ? 'unknown' : 'present', reason: row.fixture ? 'fixture_only' : null, page_url: citation.url, http_status: null, sha256: row.evidence_sha256,
+          complete: !row.fixture, run_id: inventory.epoch_id, checker_version: 'citation-inventory-v1', rel_tokens: null, anchor: null }],
+        dates: { created_at: at, updated_at: at, last_observed_at: at }, withdrawal: null };
+      records.set(id, parseOpportunityRecord(record));
+    }
+  }
+  return [...records.values()];
+}

package/src/citations/login.js

@@ -0,0 +1,122 @@
+// `agentlinkops citation login ENGINE` — one-time session persistence.
+// Opens a visible browser window (or an Xvfb virtual display on headless
+// Linux), navigates to the engine's URL, waits for the person to log in,
+// then saves the storageState (cookies + localStorage) as a JSON file the
+// engine adapter reads on every subsequent run.
+//
+// The saved session belongs to the person: it never leaves their machine,
+// it's never synced to the hosted service, and `citation logout ENGINE`
+// removes it. This is the CLI-own-browser posture — the user's account,
+// their risk, their data.
+import { mkdir, writeFile, rm, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readFile } from 'node:fs/promises';
+
+const SESSIONS_DIR = join(homedir(), '.agentlinkops', 'citations', 'sessions');
+
+const ENGINE_URLS = Object.freeze({
+  chatgpt: 'https://chatgpt.com/',
+  grok: 'https://grok.com/',
+  copilot: 'https://copilot.microsoft.com/',
+  perplexity: 'https://www.perplexity.ai/',
+  gemini: 'https://gemini.google.com/',
+  claude: 'https://claude.ai/',
+  bing: 'https://www.bing.com/',
+});
+
+export async function loginEngine({ engineName, timeoutMs = 180_000, runtime = {} }) {
+  const url = ENGINE_URLS[engineName];
+  if (!url) {
+    throw new Error(`unknown engine for login: ${engineName} (known: ${Object.keys(ENGINE_URLS).join(', ')})`);
+  }
+
+  // Lazy import playwright-core so the CLI still works without browser tooling.
+  const { firefox } = runtime.playwright ?? await import('playwright-core');
+  const { resolveCamoufoxLaunchOptions } = runtime.camoufox ?? await import('./browser/gen/lib/browser/camoufox.js');
+  const { ensureDisplay, detectDisplay } = runtime.display ?? await import('./browser/gen/lib/browser/display.js');
+
+  // On headless Linux, create a virtual display so the browser renders visibly
+  // for X11 forwarding over ssh. On macOS, the browser opens directly.
+  let displayHandle = null;
+  let display;
+  let browser;
+  try {
+  if ((runtime.platform ?? process.platform) === 'linux' && !detectDisplay()) {
+    displayHandle = await ensureDisplay({ allowExistingDisplay: false });
+    display = displayHandle.display;
+  }
+
+  const options = await resolveCamoufoxLaunchOptions({
+    provider: engineName,
+    display,
+    headlessMode: 'headful', // login requires a visible browser
+  });
+
+  browser = await firefox.launch({ ...options, executablePath: options.executablePath });
+  const context = await browser.newContext({ locale: 'en-US', timezoneId: 'America/New_York' });
+  const page = await context.newPage();
+
+  (runtime.log ?? console.log)(`Opening ${url} — log in; the session saves after login is detected or the timeout expires.`);
+  await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+
+  // Wait for login: poll for a logged-in indicator or timeout.
+  const deadline = Date.now() + timeoutMs;
+  let loggedIn = false;
+  while (Date.now() < deadline && !loggedIn) {
+    await page.waitForTimeout(5000);
+    loggedIn = await page.evaluate(() => {
+      // Generic login indicators: cookie-based session markers
+      const cookies = document.cookie;
+      if (/session|auth|token|login/i.test(cookies)) return true;
+      // Surface-specific: the login button disappeared
+      const loginBtn = document.querySelector('button[data-testid*="login"], a[href*="login"], button[aria-label*="Log in"]');
+      if (!loginBtn) return document.querySelectorAll('textarea, [contenteditable="true"]').length > 0;
+      return false;
+    }).catch(() => false);
+  }
+
+  // Save the storageState regardless: even a partial session may work
+  // (anonymous surfaces don't need login, and the adapter handles both).
+  const state = await context.storageState();
+  const sessionDir = runtime.sessionDir ?? SESSIONS_DIR;
+  await mkdir(sessionDir, { recursive: true, mode: 0o700 });
+  const sessionPath = join(sessionDir, `${engineName}.json`);
+  await writeFile(sessionPath, JSON.stringify(state, null, 2), { mode: 0o600 });
+  await chmod(sessionPath, 0o600);
+
+  return {
+    engine: engineName,
+    sessionPath,
+    loggedIn: loggedIn || 'saved-partial-state',
+    cookies: state.cookies?.length ?? 0,
+    origins: state.origins?.length ?? 0,
+  };
+  } finally {
+    let timer;
+    try { await Promise.race([browser?.close().catch(() => {}), new Promise(resolve => { timer = setTimeout(resolve, runtime.cleanupTimeoutMs ?? 5000); })]); }
+    finally { clearTimeout(timer); await displayHandle?.cleanup?.(); }
+  }
+}
+
+export async function logoutEngine({ engineName }) {
+  if (!Object.hasOwn(ENGINE_URLS, engineName)) throw new Error('unknown engine for logout');
+  const sessionPath = join(SESSIONS_DIR, `${engineName}.json`);
+  try {
+    await rm(sessionPath);
+    return { engine: engineName, removed: true };
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return { engine: engineName, removed: false, note: 'no session file found' };
+  }
+}
+
+export async function listSessions() {
+  try {
+    const { readdir } = await import('node:fs/promises');
+    const files = await readdir(SESSIONS_DIR);
+    return files.filter((f) => f.endsWith('.json')).map((f) => f.replace('.json', ''));
+  } catch {
+    return [];
+  }
+}

package/src/citations/match.js

@@ -118,3 +118,15 @@ export function classifyOutcome(target, run, verifyFetch) {
 }
 
 export { CITATION_OUTCOMES, outcomeRank };
+
+// Re-analyze retained answers without new provider requests or mutating evidence.
+// Mention and citation are independent facts: an answer may satisfy both.
+export function analyzeRetainedAnswer(target, evidence) {
+  if (!evidence || evidence.failure || evidence.unknown || typeof evidence.answer !== 'string') {
+    return { mentioned: null, cited: null, citedUrls: [], outcome: 'unknown' };
+  }
+  const citedUrls = matchCitations(target, evidence.citations ?? []);
+  const mentioned = matchMention(target, evidence.answer);
+  return { mentioned, cited: citedUrls.length > 0, citedUrls,
+    outcome: citedUrls.length ? 'cited' : mentioned ? 'mentioned' : 'not_cited' };
+}

package/src/citations/panel-builder.js

@@ -1,44 +1,49 @@
-// Guided panel authoring: turn a domain + optional brand into a ready-to-run
-// panel with sensible defaults. The buyer who doesn't want to write JSON
-// gets a starting point they can edit.
-export function buildStarterPanel({ domain, brand, aliases = [], engines = [
-  { engine: 'chatgpt', via: 'browser' },
-  { engine: 'duck', model: 'claude-haiku-4-5' },
-  { engine: 'google-aio' },
-], samples = 10, maxUsd = 1.0, competitors = [] } = {}) {
+// Suggested prompts are editable starting points, never measured search demand.
+import { citationPanelSchema, CITATION_PANEL_VERSION } from './contract.js';
+import { validatePublicUrl } from '../verifier/url.js';
+
+function domainName(value) {
+  if (typeof value !== 'string' || /[\s/?#@:]/.test(value)) throw new Error('domain must be a hostname without a path');
+  const url = new URL(`https://${value}/`);
+  if (!validatePublicUrl(url.href).valid) throw new Error('domain must be a public hostname');
+  return url.hostname.toLowerCase().replace(/^www\./, '');
+}
+export function buildStarterPanel({ domain, brand, topic, aliases = [], engines = [{ engine: 'mock' }],
+  samples = 10, maxUsd = 1, competitors = [], prompts, locale = 'en-US', country } = {}) {
   if (!domain || !brand) throw new Error('domain and brand are required');
-  const prompts = defaultPrompts(domain);
-  const targets = [
-    { domain, scope: 'domain', brand, aliases },
-    ...competitors.map((c) => ({ domain: c.domain, scope: 'domain', brand: c.brand, aliases: c.aliases ?? [] })),
-  ];
-  return {
-    schema_version: 1,
-    note: `Citation watch for ${brand}`,
-    targets,
-    prompts,
-    engines,
-    samples,
-    maxUsd,
-    competitors: competitors.map((c) => ({ domain: c.domain, brand: c.brand, aliases: c.aliases ?? [] })),
-    locale: 'en-US',
-  };
+  const targets = [{ domain: domainName(domain), scope: 'domain', brand, aliases }];
+  const normalizedCompetitors = competitors.map(c => ({ ...c, domain: domainName(c.domain), aliases: c.aliases ?? [] }));
+  return citationPanelSchema.parse({
+    schema_version: CITATION_PANEL_VERSION, note: `Editable prompt suggestions for ${brand}; verify audience relevance before running.`,
+    targets, competitors: normalizedCompetitors, prompts: prompts ?? defaultPrompts(topic || brand),
+    engines, samples, maxUsd, locale, country: country ?? locale.split('-').at(-1),
+  });
 }
-
-// Ten sensible starting prompts: category, how-to, comparison, tool-seeking.
-// Replace with GSC-derived panels (DP-0032) once search data is wired.
-function defaultPrompts(domain) {
-  const base = domain.split('.')[0];
+function defaultPrompts(topic) {
   return [
-    { id: 'category', text: `what is ${base}` },
-    { id: 'best-tools', text: `best ${base} tools` },
-    { id: 'how-to', text: `how to use ${base}` },
-    { id: 'comparison', text: `${base} vs alternatives` },
-    { id: 'open-source', text: `open source ${base}` },
-    { id: 'pricing', text: `${base} pricing` },
-    { id: 'reviews', text: `${base} reviews` },
-    { id: 'tutorial', text: `${base} tutorial` },
-    { id: 'alternatives', text: `${base} alternatives free` },
-    { id: 'for-beginners', text: `${base} for beginners` },
+    { id: 'definition', text: `What is ${topic}?` },
+    { id: 'options', text: `Which ${topic} tools should I compare?` },
+    { id: 'workflow', text: `How can I get started with ${topic}?` },
+    { id: 'alternatives', text: `What alternatives to ${topic} should I consider?` },
+    { id: 'evidence', text: `What evidence should I check when choosing ${topic}?` },
   ];
 }
+
+// The input is the user's retained research, never a claim that this command queried a source.
+export function selectResearchPrompts(records, { limit = 50 } = {}) {
+  if (!Array.isArray(records) || !records.length || records.length > 5000) throw new Error('Research must contain 1–5000 prompt records');
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error('Prompt limit must be 1–500');
+  const seen = new Set(); const groups = new Map();
+  for (const record of records) {
+    if (!record || typeof record.text !== 'string' || !record.intent_cluster || !record.provenance) throw new Error('Each researched prompt needs text, intent_cluster and provenance');
+    const text = record.text.trim().replace(/\s+/g, ' '); const key = text.toLowerCase();
+    if (seen.has(key)) continue; seen.add(key);
+    const prompt = { text, intent_cluster: record.intent_cluster, branded: record.branded === true, provenance: { ...record.provenance, basis: 'user_supplied' } };
+    const group = groups.get(record.intent_cluster) ?? []; group.push(prompt); groups.set(record.intent_cluster, group);
+  }
+  const selected = [];
+  while (selected.length < limit && [...groups.values()].some(group => group.length)) {
+    for (const group of groups.values()) if (group.length && selected.length < limit) selected.push(group.shift());
+  }
+  return selected.map((prompt, index) => ({ id: `research-${index + 1}`, ...prompt }));
+}