@nebulacomponents/citable 1.13.1 → 1.14.0

package/src/installer/index.js

@@ -8,6 +8,7 @@ import {
   PROVIDERS,
   PROVIDER_IDS,
   parseProviderList,
+  providerAgentProfilesDestination,
   providerBundleSkillPath,
   providerDestination,
   providerSkillsDir,
@@ -421,7 +422,7 @@ function toPosix(value) {
 
 function makeInstalledManifest(target, packageInfo, tree) {
   return {
-    name: 'citable',
+    name: target.manifestName || 'citable',
     version: packageInfo.version,
     managedBy: 'citable-cli',
     provider: target.providerId,
@@ -471,7 +472,7 @@ export function inspectInstallation(target, options = {}) {
   } catch (err) {
     return { state: 'corrupt', installed: null, path: destination, problems: [`manifest parse failed: ${err.message}`], symlink, localModifications: 'unknown' };
   }
-  if (manifest.managedBy !== 'citable-cli' || manifest.name !== 'citable') {
+  if (manifest.managedBy !== 'citable-cli' || manifest.name !== (target.manifestName || 'citable')) {
     return { state: 'unmanaged', installed: manifest.version ?? null, path: destination, problems: ['manifest is not managed by citable-cli'], manifest, symlink, localModifications: 'unknown' };
   }
 
@@ -543,6 +544,13 @@ export function createInstallPlan(command, args, options = {}) {
     }
     const status = inspectInstallation(target, { availableTree: bundle.tree, availableVersion: packageInfo.version });
     const action = plannedAction(command, status, args);
+    let profiles = null;
+    try {
+      profiles = prepareAgentProfiles(target, bundle, packageInfo, args, command, options);
+    } catch (err) {
+      results.push(targetResult(target, 'failed', err.message, { exitCode: err.exitCode ?? EXIT_CODES.integrityFailure }));
+      continue;
+    }
     results.push({
       provider: target.providerId,
       providerName: target.provider.displayName,
@@ -558,6 +566,16 @@ export function createInstallPlan(command, args, options = {}) {
       filesToRemove: [],
       collisions: collisionProblems(status, args),
       localModifications: status.localModifications,
+      agentProfiles: profiles ? {
+        path: profiles.target.destination,
+        state: profiles.before.state,
+        action: profiles.action,
+        filesToCreate: ['install', 'replace', 'update', 'repair'].includes(profiles.action)
+          ? Object.keys(profiles.tree.files)
+          : [],
+        collisions: collisionProblems(profiles.before, args),
+        localModifications: profiles.before.localModifications,
+      } : null,
       validation: ['validate package bundle', 'validate provider target', 'validate staged skill', 'validate final installation'],
     });
   }
@@ -674,41 +692,65 @@ function inspectInstallationWithBundle(target, options = {}) {
 function installOrUpdateTarget(target, args, options = {}, command = 'install') {
   let stage = null;
   let backup = null;
+  let installedSkill = false;
   try {
     const packageInfo = loadPackageInfo(options.packageRoot || packageRoot());
     const bundle = validateProviderBundle(target.providerId, options);
     const before = inspectInstallation(target, { availableTree: bundle.tree, availableVersion: packageInfo.version });
     const action = plannedAction(command, before, args);
-    if (action === 'already current') return targetResult(target, 'already current', 'already current', { before });
+    const profiles = prepareAgentProfiles(target, bundle, packageInfo, args, command, options);
+    if (action === 'already current' && (!profiles || profiles.action === 'already current')) {
+      return targetResult(target, 'already current', 'already current', { before, agentProfiles: profiles?.before ?? null });
+    }
     if (action === 'not installed') return targetResult(target, 'skipped', 'not installed', { before });
     if (action === 'refuse') {
       const code = before.state === 'unmanaged' ? EXIT_CODES.installationCollision : EXIT_CODES.integrityFailure;
       return targetResult(target, 'failed', `${before.state}: ${before.problems.join('; ') || 'refusing to overwrite without --force'}`, { before, exitCode: code });
     }
+    if (profiles?.action === 'refuse') {
+      const code = profiles.before.state === 'unmanaged' ? EXIT_CODES.installationCollision : EXIT_CODES.integrityFailure;
+      return targetResult(target, 'failed', `agent profile ${profiles.before.state}: ${profiles.before.problems.join('; ') || 'refusing to overwrite without --force'}`, {
+        before,
+        agentProfiles: profiles.before,
+        exitCode: code,
+      });
+    }
 
     const installPath = target.realDestination || target.destination;
-    const parent = path.dirname(installPath);
-    fs.mkdirSync(parent, { recursive: true });
-    ensureTargetInsideScope(parent, target.scopeRoot);
-    stage = path.join(parent, `.citable-install-${process.pid}-${Date.now()}-${target.providerId}`);
-    backup = path.join(parent, `.citable-backup-${Date.now()}-${target.providerId}`);
-    copyDirSafe(bundle.source, stage);
-    const stagedTree = hashTree(stage, { exclude: ['manifest.json'] });
-    writeJsonFile(path.join(stage, 'manifest.json'), makeInstalledManifest(target, packageInfo, stagedTree));
-    validateStagedSkill(stage, target.providerId);
-
-    if (exists(installPath)) fs.renameSync(installPath, backup);
-    fs.renameSync(stage, installPath);
-    stage = null;
-
-    const after = inspectInstallation(target, { availableTree: stagedTree, availableVersion: packageInfo.version });
-    if (after.state !== 'current') {
-      throw new CitableInstallerError(`final validation failed: ${after.state}`, EXIT_CODES.integrityFailure, { after });
+    let after = before;
+    if (action !== 'already current') {
+      const parent = path.dirname(installPath);
+      fs.mkdirSync(parent, { recursive: true });
+      ensureTargetInsideScope(parent, target.scopeRoot);
+      stage = path.join(parent, `.citable-install-${process.pid}-${Date.now()}-${target.providerId}`);
+      backup = path.join(parent, `.citable-backup-${Date.now()}-${target.providerId}`);
+      copyDirSafe(bundle.source, stage);
+      const stagedTree = hashTree(stage, { exclude: ['manifest.json'] });
+      writeJsonFile(path.join(stage, 'manifest.json'), makeInstalledManifest(target, packageInfo, stagedTree));
+      validateStagedSkill(stage, target.providerId);
+
+      if (exists(installPath)) fs.renameSync(installPath, backup);
+      fs.renameSync(stage, installPath);
+      stage = null;
+      installedSkill = true;
+
+      after = inspectInstallation(target, { availableTree: stagedTree, availableVersion: packageInfo.version });
+      if (after.state !== 'current') {
+        throw new CitableInstallerError(`final validation failed: ${after.state}`, EXIT_CODES.integrityFailure, { after });
+      }
     }
-    return targetResult(target, action === 'update' ? 'updated' : 'installed', `${action} complete`, { before, after, backup: exists(backup) ? backup : null });
+    const profileResult = profiles ? installAgentProfiles(profiles, packageInfo) : null;
+    const resultStatus = action === 'update' || (action === 'already current' && profileResult?.changed) ? 'updated' : 'installed';
+    return targetResult(target, resultStatus, `${action === 'already current' ? 'agent profile install' : action} complete`, {
+      before,
+      after,
+      agentProfiles: profileResult,
+      backup: exists(backup) ? backup : null,
+    });
   } catch (err) {
     if (stage) safeRm(stage);
     const installPath = target.realDestination || target.destination;
+    if (installedSkill && exists(installPath)) safeRm(installPath);
     if (backup && exists(backup) && !exists(installPath)) {
       try {
         fs.renameSync(backup, installPath);
@@ -720,6 +762,80 @@ function installOrUpdateTarget(target, args, options = {}, command = 'install')
   }
 }
 
+function prepareAgentProfiles(target, bundle, packageInfo, args, command, options) {
+  const metadata = bundle.manifest.agentProfiles;
+  if (!metadata || metadata.status !== 'available') return null;
+  const destination = providerAgentProfilesDestination(target.providerId, target.scope, rootsFor(options));
+  if (!destination) throw new CitableInstallerError(`agent profiles are not supported for ${target.provider.displayName}`, EXIT_CODES.unsupportedEnvironment);
+  const source = path.resolve(bundleRoot(options.packageRoot || packageRoot()), metadata.path);
+  const sourceManifest = readJson(path.join(source, 'manifest.json'), `${target.providerId} agent profile manifest`);
+  if (
+    sourceManifest.name !== 'citable-agent-profiles'
+    || sourceManifest.provider !== target.providerId
+    || sourceManifest.managedBy !== 'citable-cli'
+  ) {
+    throw new CitableInstallerError(`agent profile manifest for ${target.provider.displayName} is invalid`, EXIT_CODES.integrityFailure);
+  }
+  const tree = hashTree(source, { exclude: ['manifest.json'] });
+  if (tree.treeHash !== metadata.treeHash || tree.treeHash !== sourceManifest.treeHash) {
+    throw new CitableInstallerError(`agent profile bundle hash mismatch for ${target.provider.displayName}`, EXIT_CODES.integrityFailure);
+  }
+  const profileTarget = {
+    ...target,
+    destination,
+    realDestination: null,
+    manifestName: 'citable-agent-profiles',
+  };
+  const before = inspectInstallation(profileTarget, { availableTree: tree, availableVersion: packageInfo.version });
+  return {
+    target: profileTarget,
+    source,
+    tree,
+    before,
+    action: plannedAction(command, before, args),
+  };
+}
+
+function installAgentProfiles(profiles, packageInfo) {
+  if (profiles.action === 'already current') return { changed: false, before: profiles.before, after: profiles.before };
+  const destination = profiles.target.destination;
+  const parent = path.dirname(destination);
+  let stage = null;
+  let backup = null;
+  try {
+    fs.mkdirSync(parent, { recursive: true });
+    ensureTargetInsideScope(parent, profiles.target.scopeRoot);
+    stage = path.join(parent, `.citable-agent-install-${process.pid}-${Date.now()}`);
+    backup = path.join(parent, `.citable-agent-backup-${Date.now()}`);
+    copyDirSafe(profiles.source, stage);
+    writeJsonFile(path.join(stage, 'manifest.json'), makeInstalledManifest(profiles.target, packageInfo, profiles.tree));
+    validateStagedProfiles(stage, profiles.target.providerId, profiles.tree);
+    if (exists(destination)) fs.renameSync(destination, backup);
+    fs.renameSync(stage, destination);
+    stage = null;
+    const after = inspectInstallation(profiles.target, { availableTree: profiles.tree, availableVersion: packageInfo.version });
+    if (after.state !== 'current') throw new CitableInstallerError(`final agent profile validation failed: ${after.state}`, EXIT_CODES.integrityFailure);
+    return { changed: true, before: profiles.before, after, backup: exists(backup) ? backup : null };
+  } catch (err) {
+    if (stage) safeRm(stage);
+    if (exists(destination)) safeRm(destination);
+    if (backup && exists(backup)) fs.renameSync(backup, destination);
+    throw err;
+  }
+}
+
+function validateStagedProfiles(dir, providerId, tree) {
+  for (const rel of Object.keys(tree.files)) {
+    if (!exists(path.join(dir, rel))) {
+      throw new CitableInstallerError(`staged ${providerId} agent profiles are missing ${rel}`, EXIT_CODES.integrityFailure);
+    }
+  }
+  const manifest = readJson(path.join(dir, 'manifest.json'), 'staged agent profile manifest');
+  if (manifest.managedBy !== 'citable-cli' || manifest.provider !== providerId || manifest.name !== 'citable-agent-profiles') {
+    throw new CitableInstallerError(`staged ${providerId} agent profile manifest is invalid`, EXIT_CODES.integrityFailure);
+  }
+}
+
 function ensureTargetInsideScope(targetPath, scopeRoot) {
   // Use realpathSync when possible to resolve symlinks (e.g. /tmp → /private/tmp on macOS)
   // so that cross-symlink paths compare correctly.
@@ -777,6 +893,7 @@ function uninstallTarget(target, args) {
     if (status.manifest?.managedBy !== 'citable-cli') {
       return targetResult(target, 'failed', `${status.state}: refusing to remove unmanaged content`, { before: status, exitCode: EXIT_CODES.installationCollision });
     }
+    const profileResult = uninstallAgentProfiles(target);
     const destination = target.realDestination || target.destination;
     const relFiles = Object.keys(status.manifest.files || {}).sort((a, b) => b.localeCompare(a));
     for (const rel of relFiles) {
@@ -790,12 +907,39 @@ function uninstallTarget(target, args) {
     } catch {
       // Directory contains user files; preserve it.
     }
-    return targetResult(target, 'removed', 'removed managed files', { before: status, removedFiles: [...relFiles, 'manifest.json'] });
+    return targetResult(target, 'removed', 'removed managed files', {
+      before: status,
+      agentProfiles: profileResult,
+      removedFiles: [...relFiles, 'manifest.json'],
+    });
   } catch (err) {
     return targetResult(target, 'failed', err.message, { exitCode: err.exitCode ?? EXIT_CODES.generalFailure });
   }
 }
 
+function uninstallAgentProfiles(target) {
+  const destination = providerAgentProfilesDestination(target.providerId, target.scope, {
+    projectRoot: target.scope === 'project' ? target.scopeRoot : '',
+    home: target.scope === 'global' ? target.scopeRoot : '',
+  });
+  if (!destination) return null;
+  const profileTarget = { ...target, destination, realDestination: null, manifestName: 'citable-agent-profiles' };
+  const status = inspectInstallation(profileTarget);
+  if (status.state === 'not installed') return { status: 'not installed' };
+  if (status.manifest?.managedBy !== 'citable-cli' || status.manifest?.name !== 'citable-agent-profiles') {
+    return { status: 'preserved', state: status.state, problems: status.problems };
+  }
+  const relFiles = Object.keys(status.manifest.files || {}).sort((a, b) => b.localeCompare(a));
+  for (const rel of relFiles) {
+    assertArchiveEntrySafe(rel);
+    safeUnlink(path.join(destination, rel));
+  }
+  safeUnlink(path.join(destination, 'manifest.json'));
+  pruneEmptyDirs(destination, destination);
+  if (exists(destination) && fs.readdirSync(destination).length === 0) fs.rmdirSync(destination);
+  return { status: 'removed', removedFiles: [...relFiles, 'manifest.json'] };
+}
+
 function safeUnlink(filePath) {
   try {
     fs.unlinkSync(filePath);
@@ -841,13 +985,31 @@ async function inspectCommand(command, args, options = {}) {
   const packageInfo = loadPackageInfo(context.roots.packageRoot);
   const rows = [];
   for (const target of context.targets.filter((target) => !target.duplicateOf)) {
+    let bundle = null;
     let bundleTree = null;
     try {
-      bundleTree = validateProviderBundle(target.providerId, { ...options, packageRoot: context.roots.packageRoot }).tree;
+      bundle = validateProviderBundle(target.providerId, { ...options, packageRoot: context.roots.packageRoot });
+      bundleTree = bundle.tree;
     } catch {
       // Check/list should still report installed state if the package bundle is broken.
     }
     const status = inspectInstallation(target, { availableTree: bundleTree, availableVersion: packageInfo.version });
+    let agentProfiles = null;
+    if (bundle) {
+      try {
+        agentProfiles = prepareAgentProfiles(target, bundle, packageInfo, args, 'install', options)?.before ?? null;
+      } catch (err) {
+        agentProfiles = {
+          state: 'corrupt',
+          installed: null,
+          path: providerAgentProfilesDestination(target.providerId, target.scope, context.roots),
+          localModifications: 'unknown',
+          problems: [err.message],
+        };
+      }
+    }
+    const combinedState = combineInstalledState(status.state, agentProfiles?.state);
+    const profileProblems = (agentProfiles?.problems || []).map((problem) => `agent profiles: ${problem}`);
     rows.push({
       provider: target.providerId,
       providerName: target.provider.displayName,
@@ -855,9 +1017,10 @@ async function inspectCommand(command, args, options = {}) {
       path: target.destination,
       installed: status.installed,
       available: packageInfo.version,
-      state: status.state,
-      localModifications: status.localModifications,
-      problems: status.problems,
+      state: combinedState,
+      localModifications: status.localModifications === 'present' || agentProfiles?.localModifications === 'present' ? 'present' : status.localModifications,
+      problems: [...status.problems, ...profileProblems],
+      agentProfiles,
       symlink: Boolean(status.symlink),
     });
   }
@@ -865,9 +1028,18 @@ async function inspectCommand(command, args, options = {}) {
   return { ok: true, command, providers: rows, exitCode: args.failOnUpdate && hasUpdate ? EXIT_CODES.updateAvailable : EXIT_CODES.success };
 }
 
+function combineInstalledState(skillState, profileState) {
+  if (!profileState || profileState === 'current') return skillState;
+  if (skillState !== 'current') return skillState;
+  if (profileState === 'not installed') return 'partial';
+  if (profileState === 'update available') return 'update available';
+  return profileState;
+}
+
 export async function doctorCommand(args, options = {}) {
   const context = resolveTargets('doctor', args, options);
   const packageInfo = loadPackageInfo(context.roots.packageRoot);
+  const capabilities = await runtimeCapabilities(options);
   const checks = [];
   const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
   checks.push({ level: nodeMajor >= 20 ? 'PASS' : 'FAIL', message: `Node.js ${process.versions.node}` });
@@ -902,7 +1074,81 @@ export async function doctorCommand(args, options = {}) {
   }
 
   const hasFail = checks.some((check) => check.level === 'FAIL');
-  return { ok: !hasFail, command: 'doctor', checks, exitCode: hasFail ? EXIT_CODES.integrityFailure : EXIT_CODES.success };
+  return { ok: !hasFail, command: 'doctor', checks, capabilities, exitCode: hasFail ? EXIT_CODES.integrityFailure : EXIT_CODES.success };
+}
+
+async function optionalDependencyAvailable(name, options = {}) {
+  if (options.capabilityResolver) return Boolean(await options.capabilityResolver(name));
+  try {
+    await import(name);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runtimeCapabilities(options = {}) {
+  const env = options.env || process.env;
+  const dependencyDefinitions = [
+    {
+      id: 'browser_render',
+      requirements: ['playwright'],
+      readyLimitations: ['dependency presence does not establish browser launch readiness'],
+    },
+    {
+      id: 'lighthouse_lab',
+      requirements: ['lighthouse', 'chrome-launcher'],
+      readyLimitations: ['dependency presence does not establish Chrome launch readiness or a successful lab run'],
+    },
+    {
+      id: 'ocr',
+      requirements: ['tesseract.js'],
+      readyLimitations: ['dependency presence does not establish OCR accuracy or source-image availability'],
+    },
+  ];
+  const capabilities = [];
+  for (const definition of dependencyDefinitions) {
+    const availability = await Promise.all(definition.requirements.map(async (name) => ({
+      name,
+      available: await optionalDependencyAvailable(name, options),
+    })));
+    const missing = availability.filter((item) => !item.available).map((item) => item.name);
+    capabilities.push({
+      id: definition.id,
+      state: missing.length ? 'missing_dependency' : 'ready',
+      requirements: definition.requirements,
+      limitations: missing.length
+        ? missing.map((name) => `optional dependency ${name} is not installed`)
+        : definition.readyLimitations,
+    });
+  }
+
+  for (const definition of [
+    {
+      id: 'crux_field',
+      credential: 'CRUX_API_KEY',
+      readyLimitation: 'credential presence does not establish validity, scope, quota, or API availability',
+    },
+    {
+      id: 'gsc_index',
+      credential: 'GSC_ACCESS_TOKEN',
+      readyLimitation: 'credential presence does not establish validity, scope, property access, or API availability',
+    },
+    {
+      id: 'ga4_metrics',
+      credential: 'GA4_ACCESS_TOKEN',
+      readyLimitation: 'credential presence does not establish validity, scope, property access, or API availability',
+    },
+  ]) {
+    const configured = typeof env[definition.credential] === 'string' && env[definition.credential].length > 0;
+    capabilities.push({
+      id: definition.id,
+      state: configured ? 'ready' : 'missing_credential',
+      requirements: [definition.credential],
+      limitations: [configured ? definition.readyLimitation : `${definition.credential} is not configured`],
+    });
+  }
+  return capabilities;
 }
 
 function inspectInstallationWithOptionalBundle(target, packageRootPath, version) {
@@ -1103,7 +1349,15 @@ function renderList(result) {
 }
 
 function renderDoctor(result) {
-  return ['Citable doctor', '', ...result.checks.map((check) => `${check.level.padEnd(5)} ${check.message}`)].join('\n');
+  const lines = ['Citable doctor', '', ...result.checks.map((check) => `${check.level.padEnd(5)} ${check.message}`)];
+  if (result.capabilities?.length) {
+    lines.push('', 'Runtime capabilities');
+    for (const capability of result.capabilities) {
+      lines.push(`  ${capability.id.padEnd(18)} ${capability.state}`);
+      for (const limitation of capability.limitations) lines.push(`    ${limitation}`);
+    }
+  }
+  return lines.join('\n');
 }
 
 export function installerHelp() {

package/src/installer/providers.js

@@ -7,8 +7,10 @@ export const PROVIDERS = Object.freeze({
     aliases: ['claude-code', 'claudecode'],
     projectDir: '.claude',
     projectSkillsDir: '.claude/skills',
+    projectAgentProfilesDir: '.claude/agents',
     globalHints: ['.claude'],
     globalSkillsDir: '.claude/skills',
+    globalAgentProfilesDir: '.claude/agents',
   },
   codex: {
     id: 'codex',
@@ -162,3 +164,12 @@ export function providerBundleSkillPath(providerId) {
   if (!provider) throw new Error(`unknown provider: ${providerId}`);
   return path.join('dist', 'universal', provider.projectSkillsDir, 'citable');
 }
+
+export function providerAgentProfilesDestination(providerId, scope, roots) {
+  const provider = PROVIDERS[providerId];
+  if (!provider) throw new Error(`unknown provider: ${providerId}`);
+  const dir = scope === 'project' ? provider.projectAgentProfilesDir : provider.globalAgentProfilesDir;
+  if (!dir) return null;
+  const root = scope === 'project' ? roots.projectRoot : roots.home;
+  return path.join(root, dir, 'citable');
+}

package/src/observations/browserJourney.js

@@ -1,11 +1,15 @@
 import { envelope, observationRun, readInput } from './common.js';
-import { fetchUrl } from '../crawler/fetch.js';
+import { fetchUrl, handlePublicBrowserRoute, validatePublicUrl } from '../crawler/fetch.js';
 import { sha256 } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { analyzeRenderParity } from './renderParity.js';
 
-async function executeStep(page, step) {
+async function executeStep(page, step, lookup) {
   const locator = step.locator ? page.locator(step.locator).first() : null;
-  if (step.action === 'navigate') await page.goto(step.url, { waitUntil: 'networkidle' });
+  if (step.action === 'navigate') {
+    await validatePublicUrl(step.url, lookup ? { lookup } : {});
+    await page.goto(step.url, { waitUntil: 'networkidle' });
+  }
   else if (step.action === 'click') await locator.click();
   else if (step.action === 'fill') {
     const value = process.env[step.value_env];
@@ -22,7 +26,7 @@ async function executeStep(page, step) {
   else if (step.action === 'scroll') await locator.scrollIntoViewIfNeeded();
 }
 
-async function playwrightCapture(profile, plan, playwright) {
+async function playwrightCapture(profile, plan, playwright, lookup) {
   if (profile.authentication_state !== 'anonymous') throw new Error(`authentication state ${profile.authentication_state} requires a disclosed custom adapter`);
   const browserType = playwright[profile.browser.engine];
   if (!browserType) throw new Error(`Playwright engine ${profile.browser.engine} is unavailable`);
@@ -35,6 +39,7 @@ async function playwrightCapture(profile, plan, playwright) {
       locale: profile.locale,
     });
     try {
+      await context.route('**/*', (route) => handlePublicBrowserRoute(route, lookup ? { lookup } : {}));
       const page = await context.newPage();
       const consoleErrors = [], networkFailures = [], steps = [], stepScreenshots = {};
       page.on('console', (message) => { if (message.type() === 'error') consoleErrors.push(message.text()); });
@@ -43,7 +48,7 @@ async function playwrightCapture(profile, plan, playwright) {
       for (const step of profile.steps) {
         const record = { step_id: step.step_id, action: step.action, status: 'completed', failure: null, screenshot_ref: null };
         try {
-          await executeStep(page, step);
+          await executeStep(page, step, lookup);
           if (step.capture_screenshot) {
             record.screenshot_ref = `journeys/${profile.profile_id}/steps/${step.step_id}.png`;
             stepScreenshots[record.screenshot_ref] = await page.screenshot({ fullPage: true });
@@ -79,6 +84,7 @@ export async function observeBrowserPlan(root, options) {
   const check = validateAgainst('browser-evidence-plan.schema.json', plan);
   if (!check.valid) throw new Error(`browser evidence plan violates contract: ${check.errors.join('; ')}`);
   if (options.target && options.target !== plan.target) throw new Error('browser evidence target differs from the plan target');
+  await validatePublicUrl(plan.target, options.lookup ? { lookup: options.lookup } : {});
   const profileIds = plan.profiles.map((item) => item.profile_id);
   if (new Set(profileIds).size !== profileIds.length) throw new Error('browser evidence plan contains duplicate profile ids');
   const targetOrigin = new URL(plan.target).origin;
@@ -113,7 +119,7 @@ export async function observeBrowserPlan(root, options) {
     try {
       const capture = options.captureJourney
         ? await options.captureJourney(profile, plan)
-        : await playwrightCapture(profile, plan, playwright);
+        : await playwrightCapture(profile, plan, playwright, options.lookup);
       if (!capture || typeof capture.dom !== 'string' || typeof capture.text !== 'string' || typeof capture.browser_version !== 'string' || capture.screenshot == null) {
         throw new Error('browser adapter returned an incomplete capture contract');
       }
@@ -137,6 +143,7 @@ export async function observeBrowserPlan(root, options) {
         artifacts[name] = value;
       }
       const versionMatches = profile.browser.expected_version == null || profile.browser.expected_version === capture.browser_version;
+      const renderParity = analyzeRenderParity(initial.body, capture.dom, plan.semantic_impact_policy || null);
       const data = {
         plan_id: plan.plan_id, target: plan.target, profile_id: profile.profile_id,
         browser: { ...profile.browser, observed_version: capture.browser_version, version_matches_expectation: versionMatches },
@@ -144,9 +151,10 @@ export async function observeBrowserPlan(root, options) {
         consent_state: profile.consent_state, authentication_state: profile.authentication_state,
         final_url: capture.final_url, status: capture.status, dom_hash: sha256(capture.dom), text_hash: sha256(capture.text),
         steps: capture.steps || [], artifact_refs: refs,
+        render_parity: renderParity,
         interpretation_boundary: 'Observed differences do not establish semantic, retrieval, citation, ranking, or business impact.',
       };
-      const limitations = [...plan.limitations, ...profile.limitations];
+      const limitations = [...plan.limitations, ...profile.limitations, ...(plan.semantic_impact_policy?.limitations || [])];
       if (!versionMatches) limitations.push('Observed browser version differs from the planned version.');
       observations.push(envelope('browser_journey', data, { method: 'browser', source: `playwright/${profile.browser.engine}`, raw: capture.dom, limitations }));
     } catch (error) {

package/src/observations/claimDiff.js

@@ -0,0 +1,83 @@
+import { substantiate } from '../commands/substantiate.js';
+import { loadRegistries } from '../registries/index.js';
+
+function keyTerms(text) {
+  return (String(text || '').toLowerCase().match(/[a-z][a-z-]{4,}/g) || []).slice(0, 8);
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function overlapScore(assertionText, claimText) {
+  const terms = keyTerms(assertionText);
+  if (terms.length < 3) return 0;
+  const target = String(claimText || '').toLowerCase();
+  // Whole-word boundaries only — a raw substring test would match "test" inside
+  // "greatest" and misassign a substantiation status to the wrong claim.
+  const present = terms.filter((t) => new RegExp(`\\b${escapeRegExp(t)}\\b`).test(target)).length;
+  return present / terms.length;
+}
+
+function surfaceMatches(citationUrl, surface) {
+  try {
+    const url = new URL(citationUrl);
+    // Path-boundary comparison, not raw substring — a query string or fragment
+    // containing the surface text must not count as a match.
+    return url.pathname === surface || url.pathname.startsWith(surface.endsWith('/') ? surface : `${surface}/`);
+  } catch {
+    return false;
+  }
+}
+
+/** Find the best-matching registry claim for one AI answer assertion (token-overlap heuristic, adapted from CLAIM-008). */
+export function matchClaim(assertionText, claims, citationUrl) {
+  let best = null;
+  let bestScore = 0;
+  for (const c of claims.filter((c) => c.status !== 'retired')) {
+    let score = overlapScore(assertionText, c.claim);
+    if (citationUrl && (c.publication_surfaces || []).some((s) => surfaceMatches(citationUrl, s))) score += 0.1;
+    if (score > bestScore) {
+      bestScore = score;
+      best = c;
+    }
+  }
+  return bestScore >= 0.4 ? best : null;
+}
+
+const OUTCOME_TO_STATUS = {
+  verified: 'confirmed',
+  verified_narrowed: 'confirmed',
+  contradicted: 'contradicted',
+  expired: 'stale',
+};
+
+/**
+ * Diff one answer-engine assertion against the caller's own claim/evidence registry.
+ * Never asserts the AI is wrong — only confirmed/contradicted/stale/unsupported relative
+ * to the caller's own evidence. Never implies a live query happened.
+ */
+export function diffAssertion(assertionText, citationUrl, { claims, assessmentByClaimId }) {
+  if (!assertionText) return null;
+  const matched = matchClaim(assertionText, claims, citationUrl);
+  if (!matched) {
+    return { status: 'unsupported', matched_claim_id: null, reasons: ['no claim in your registry covers this assertion; it could not be checked'] };
+  }
+  const assessment = assessmentByClaimId.get(matched.claim_id);
+  const status = OUTCOME_TO_STATUS[assessment?.outcome] ?? 'unsupported';
+  return { status, matched_claim_id: matched.claim_id, reasons: assessment?.reasons ?? [] };
+}
+
+/**
+ * Precompute the shared claim/evidence lookups once per `observe citations` run.
+ * `problems` surfaces registry schema-validation issues (malformed but parseable
+ * YAML) so the caller can report them as warnings rather than silently diffing
+ * against data that failed its own contract.
+ */
+export function buildClaimDiffContext(root, refDate) {
+  const { registries, problems } = loadRegistries(root);
+  const claims = Array.isArray(registries.claims?.entries) ? registries.claims.entries : [];
+  const { assessments } = substantiate(root, { write: false, refDate });
+  const assessmentByClaimId = new Map(assessments.map((a) => [a.claim_id, a]));
+  return { claims, assessmentByClaimId, problems };
+}

package/src/observations/common.js

@@ -42,6 +42,8 @@ export function summarizeObservations(items) {
   for (const item of items) { byKind[item.kind] = (byKind[item.kind] || 0) + 1; byState[item.state] = (byState[item.state] || 0) + 1; }
   const citations = items.filter((item) => item.kind === 'citation');
   const reviews = items.filter((item) => item.kind === 'citation_review');
+  const claimDiffCounts = { confirmed: 0, contradicted: 0, stale: 0, unsupported: 0, not_checked: 0 };
+  for (const review of reviews) claimDiffCounts[review.data.claim_diff?.status ?? 'not_checked']++;
   const providers = {};
   for (const item of citations) {
     const provider = item.data.provider || 'unknown';
@@ -49,6 +51,17 @@ export function summarizeObservations(items) {
     providers[provider].runs++;
     if (item.data.property_cited) providers[provider].property_cited++;
   }
+  const competitiveSourceMap = new Map();
+  for (const review of reviews.filter((item) => !item.data.first_party)) {
+    let domain;
+    try { domain = new URL(review.data.canonical_url).hostname; } catch { continue; }
+    const current = competitiveSourceMap.get(domain) || { domain, citation_count: 0, declared_profiles: [] };
+    current.citation_count++;
+    if (review.data.source_profile && !current.declared_profiles.some((item) => JSON.stringify(item) === JSON.stringify(review.data.source_profile))) {
+      current.declared_profiles.push(review.data.source_profile);
+    }
+    competitiveSourceMap.set(domain, current);
+  }
   return {
     total: items.length, by_kind: byKind, by_state: byState,
     citation_metrics: citations.length ? {
@@ -56,8 +69,10 @@ export function summarizeObservations(items) {
       citation_presence_rate: citations.filter((x) => x.data.property_cited).length / citations.length,
       supported_citation_rate: reviews.length ? reviews.filter((x) => x.data.support_status === 'supported').length / reviews.length : null,
       review_required: reviews.filter((x) => x.state === 'review_required').length,
+      claim_diff: claimDiffCounts,
       provider_results: providers,
       competitive_domains: [...new Set(reviews.filter((x) => !x.data.first_party).map((x) => { try { return new URL(x.data.canonical_url).hostname; } catch { return null; } }).filter(Boolean))].sort(),
+      competitive_sources: [...competitiveSourceMap.values()].sort((a, b) => a.domain.localeCompare(b.domain)),
     } : null,
   };
 }