@nebulacomponents/citable 1.13.1 → 1.15.0

package/src/crawler/fetch.js

@@ -4,9 +4,11 @@ import net from 'node:net';
 const blockedAddresses = new net.BlockList();
 for (const [network, prefix] of [
   ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
-  ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.168.0.0', 16], ['224.0.0.0', 4],
+  ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24],
+  ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24],
+  ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4],
 ]) blockedAddresses.addSubnet(network, prefix, 'ipv4');
-for (const [network, prefix] of [['::', 128], ['::1', 128], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8]]) {
+for (const [network, prefix] of [['::', 128], ['::1', 128], ['2001:db8::', 32], ['fc00::', 7], ['fe80::', 10], ['ff00::', 8]]) {
   blockedAddresses.addSubnet(network, prefix, 'ipv6');
 }
 
@@ -19,7 +21,7 @@ function isBlockedAddress(address) {
   return blockedAddresses.check(address, family === 4 ? 'ipv4' : 'ipv6');
 }
 
-async function validateDestination(url, lookup) {
+export async function validatePublicUrl(url, { lookup = dns.promises.lookup } = {}) {
   const parsed = new URL(url);
   if (!['http:', 'https:'].includes(parsed.protocol)) throw new Error(`unsupported URL protocol: ${parsed.protocol}`);
   if (parsed.username || parsed.password) throw new Error('URL credentials are not permitted');
@@ -34,6 +36,32 @@ async function validateDestination(url, lookup) {
   return parsed;
 }
 
+/** Enforce the public-network policy for each Playwright request. */
+export async function handlePublicBrowserRoute(route, { lookup = dns.promises.lookup } = {}) {
+  const url = route.request().url();
+  let protocol;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    await route.abort('blockedbyclient');
+    return;
+  }
+  if (['data:', 'blob:', 'about:'].includes(protocol)) {
+    await route.continue();
+    return;
+  }
+  if (!['http:', 'https:'].includes(protocol)) {
+    await route.abort('blockedbyclient');
+    return;
+  }
+  try {
+    await validatePublicUrl(url, { lookup });
+    await route.continue();
+  } catch {
+    await route.abort('blockedbyclient');
+  }
+}
+
 async function readBodyLimited(res, maxBodyBytes) {
   const declared = Number(res.headers.get('content-length'));
   if (Number.isFinite(declared) && declared > maxBodyBytes) {
@@ -66,13 +94,13 @@ export async function fetchUrl(url, {
   maxRetries = 3, retryDelayMs = 1000, maxBodyBytes = 5 * 1024 * 1024,
   fetchImpl = globalThis.fetch, lookup = dns.promises.lookup,
 } = {}) {
-  const requested = await validateDestination(url, lookup);
+  const requested = await validatePublicUrl(url, { lookup });
   const allowedOrigin = requested.origin;
   const chain = [];
   let current = requested.href;
 
   for (let redirects = 0; redirects <= maxRedirects; redirects += 1) {
-    await validateDestination(current, lookup);
+    await validatePublicUrl(current, { lookup });
     let res;
     let lastError;
     for (let attempt = 0; attempt < Math.max(1, maxRetries); attempt += 1) {
@@ -108,7 +136,7 @@ export async function fetchUrl(url, {
       if (redirects === maxRedirects) break;
       const next = new URL(headers.location, current);
       if (next.origin !== allowedOrigin) throw new Error(`redirect leaves audited origin: ${next.href}`);
-      await validateDestination(next.href, lookup);
+      await validatePublicUrl(next.href, { lookup });
       chain.push({ url: current, status: res.status, location: headers.location });
       current = next.href;
       await res.body?.cancel();

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 = [

package/src/extractor/page.js

@@ -57,6 +57,21 @@ export function extractPage({ url, html, status = 200, headers = {}, sourceFile
   }
 
   const body = root.querySelector('body');
+  const rawVisibleText = body ? body.text.replace(/\s+/g, ' ').trim() : '';
+  const structuralRegions = [];
+  const seenRegions = new Set();
+  for (const region of root.querySelectorAll('header,nav,aside,footer,[role=banner],[role=navigation],[role=complementary],[role=contentinfo]')) {
+    if (seenRegions.has(region)) continue;
+    seenRegions.add(region);
+    const text = region.text.replace(/\s+/g, ' ').trim();
+    if (!text) continue;
+    structuralRegions.push({
+      region_type: (region.getAttribute('role') || region.tagName || 'unknown').toLowerCase(),
+      text,
+      html_bytes: Buffer.byteLength(region.outerHTML),
+      token_count: text.split(/\s+/).filter(Boolean).length,
+    });
+  }
   // Strip script/style/nav/footer noise for main-text estimation
   const bodyClone = body ? parse(body.outerHTML) : null;
   if (bodyClone) for (const s of bodyClone.querySelectorAll('script,style,noscript,nav,footer,header[role=banner]')) s.remove();
@@ -115,6 +130,8 @@ export function extractPage({ url, html, status = 200, headers = {}, sourceFile
     images,
     jsonLd,
     text,
+    rawVisibleWordCount: rawVisibleText ? rawVisibleText.split(/\s+/).length : 0,
+    structuralRegions,
     paragraphs,
     wordCount: text ? text.split(/\s+/).length : 0,
     scriptBytes,

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() {