agentgrade-cli 1.0.0

package/lib/probe.mjs

@@ -0,0 +1,1383 @@
+/**
+ * agentgrade probe — core scanning logic
+ *
+ * Pure functions that return structured results. No console output.
+ * Used by cli.mjs (terminal) and server.js (web API).
+ */
+
+import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
+
+// Generate a temp EIP-191 Bearer token for services that require wallet auth before payment
+async function makeEIP191Token(domain) {
+  const key = generatePrivateKey();
+  const account = privateKeyToAccount(key);
+  const ts = Math.floor(Date.now() / 1000);
+  const sig = await account.signMessage({ message: `${domain}:${ts}` });
+  return `${ts}.${sig.slice(2)}`;
+}
+
+function smartParamValue(name) {
+  const n = name.toLowerCase();
+  if (/id$/.test(n)) return '1';
+  if (/uuid|guid/.test(n)) return '00000000-0000-0000-0000-000000000000';
+  if (/domain|hostname|host/.test(n)) return 'example.com';
+  if (/version|ver/.test(n)) return 'v1';
+  if (/email/.test(n)) return 'test@example.com';
+  if (/page|limit|offset|count|num/.test(n)) return '1';
+  return 'test';
+}
+
+const STUB = { string: 'probe', number: 1, boolean: true };
+function stubBody(service) {
+  const fields = service.outputSchema?.input?.bodyFields
+    || service.inputSchema?.properties
+    || service.inputSchema?.body;
+  if (!fields) return {};
+  const body = {};
+  for (const [k, v] of Object.entries(fields)) body[k] = STUB[v.type] ?? 'probe';
+  return body;
+}
+
+function tryParseBase64(str) {
+  try { return JSON.parse(Buffer.from(str, 'base64').toString()); } catch { return null; }
+}
+
+const UA = 'agentgrade/0.2 (+https://agentgrade.com/kb/about-scanning)';
+
+async function fetchSafe(url, opts = {}) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    const headers = { 'User-Agent': UA, ...opts.headers };
+    const res = await fetch(url, { redirect: 'follow', signal: controller.signal, ...opts, headers });
+    clearTimeout(timeout);
+    const ct = res.headers.get('content-type') || '';
+    let text;
+    if (ct.includes('text/event-stream') && res.body) {
+      // SSE: read chunks until we get a data: line, then stop
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = '';
+      try {
+        while (buf.length < 524288) {
+          const { done, value } = await Promise.race([
+            reader.read(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('SSE read timeout')), 3000)),
+          ]);
+          if (done) break;
+          buf += decoder.decode(value, { stream: true });
+          if ((buf.includes('\ndata: ') || buf.startsWith('data: ')) && buf.includes('\n\n')) break;
+        }
+      } catch {} finally { try { reader.cancel(); } catch {} controller.abort(); }
+      text = buf;
+    } else {
+      text = await res.text();
+    }
+    let json;
+    try { json = JSON.parse(text); } catch {}
+    if (!json) { const m = text.match(/^data: (.+)$/m); if (m) try { json = JSON.parse(m[1]); } catch {} }
+    const cfBlocked = res.status === 403 && res.headers.get('cf-mitigated') === 'challenge';
+    const rateLimited = res.status === 429;
+    const retryAfter = rateLimited ? (res.headers.get('retry-after') || null) : null;
+    return { status: res.status, text, json, headers: res.headers, cfBlocked, rateLimited, retryAfter };
+  } catch (e) {
+    return { status: 0, error: e.message };
+  }
+}
+
+async function firstMatch(bases, paths, opts = {}, test = r => r.status === 200) {
+  if (typeof bases === 'string') bases = [bases];
+  const combos = bases.flatMap(b => paths.map(p => ({ base: b, path: p })));
+  const results = await Promise.all(combos.map(c => fetchSafe(`${c.base}${c.path}`, opts).then(r => ({ ...c, r }))));
+  const hits = bases.filter(b => results.some(({ base, r }) => base === b && test(r)));
+  for (const b of bases) {
+    const hit = results.find(({ base, r }) => base === b && test(r));
+    if (hit) return { path: new URL(`${hit.base}${hit.path}`).pathname, r: hit.r, allCfBlocked: false, hitBases: hits };
+  }
+  return results.some(({ r }) => r.cfBlocked) ? { path: null, r: null, allCfBlocked: true, hitBases: [] } : null;
+}
+
+// ─── 402 Probe ──────────────────────────────────────────────────────────────
+
+export async function probe402(url, method = 'POST', body = undefined) {
+  const result = { x402: null, mpp: null, spt: null, l402: null, otherHeaders: [], bodyMentions: [] };
+
+  const opts = {
+    method,
+    headers: { 'Content-Type': 'application/json', 'X-Agent-Id': 'agentgrade' },
+  };
+  if (body && method !== 'GET') opts.body = body;
+
+  const r = await fetchSafe(url, opts);
+  result.status = r.status;
+  result.cfBlocked = r.cfBlocked || false;
+  result.rateLimited = r.rateLimited || false;
+  if (r.rateLimited) { result.retryAfter = r.retryAfter; return result; }
+  if (r.error) { result.error = r.error; return result; }
+
+  if (r.status !== 402) {
+    // Scan body for payment protocol mentions
+    if (r.text) {
+      if (/\bx402\b|Payment-Required/i.test(r.text)) result.bodyMentions.push('x402');
+      if (/\bMPP\b.*payment|payment.*\bMPP\b|machine.payment.protocol|WWW-Authenticate:\s*Payment/i.test(r.text)) result.bodyMentions.push('MPP');
+      if (/\bL402\b|\bLSAT\b|\bmacaroon\b.{0,50}\binvoice\b/i.test(r.text)) result.bodyMentions.push('L402');
+      if (/\bHTTP 402\b|402 payment/i.test(r.text)) result.bodyMentions.push('402 (generic)');
+    }
+    return result;
+  }
+
+  // ── x402 ──
+  const prHeader = r.headers.get('payment-required');
+  if (prHeader) {
+    const parsed = tryParseBase64(prHeader);
+    if (parsed) {
+      const options = parsed.accepts || (Array.isArray(parsed) ? parsed : [parsed]);
+      result.x402 = {
+        version: parsed.x402Version || 1,
+        description: parsed.resource?.description,
+        options: options.map(opt => ({
+          network: opt.network || 'unknown',
+          amount: opt.amount || opt.maxAmountRequired || '?',
+          asset: opt.asset || '?',
+          assetName: opt.extra?.name,
+          payTo: opt.payTo || '?',
+          scheme: opt.scheme,
+          maxTimeoutSeconds: opt.maxTimeoutSeconds,
+        })),
+        extensions: parsed.extensions || null,
+        bazaar: parsed.extensions?.bazaar || null,
+      };
+    } else {
+      result.x402 = { raw: prHeader.slice(0, 200), decodeFailed: true };
+    }
+  }
+
+  // ── MPP ──
+  const wwwAuth = r.headers.get('www-authenticate');
+  if (wwwAuth && /payment/i.test(wwwAuth)) {
+    // Split concatenated WWW-Authenticate headers into individual Payment challenges
+    const challenges = wwwAuth.split(/,?\s*Payment\s+/i).filter(Boolean);
+    const allFields = [];
+    for (const ch of challenges) {
+      const pairs = {};
+      for (const m of ch.matchAll(/(\w+)="([^"]*)"/g)) pairs[m[1]] = m[2];
+      const parts = ch.split(',').map(s => s.trim());
+      for (const part of parts) {
+        const eqIdx = part.indexOf('=');
+        if (eqIdx > 0 && !part.includes('"')) pairs[part.slice(0, eqIdx).trim()] = part.slice(eqIdx + 1).trim();
+      }
+      allFields.push(pairs);
+    }
+    result.mpp = { header: wwwAuth, fields: allFields[0] || {}, challenges: allFields };
+    const stripeCh = allFields.find(p => p.method === 'stripe');
+    if (stripeCh) {
+      let request = null;
+      if (stripeCh.request) {
+        try { request = JSON.parse(Buffer.from(stripeCh.request, 'base64url').toString()); } catch {}
+      }
+      result.spt = {
+        method: 'stripe', intent: stripeCh.intent || null,
+        amount: request?.amount || stripeCh.amount || null,
+        currency: request?.currency || null,
+        decimals: request?.decimals ?? null,
+        realm: stripeCh.realm || null,
+      };
+    }
+  }
+
+  // ── L402 ──
+  if (wwwAuth && /l402|lsat/i.test(wwwAuth)) {
+    result.l402 = {
+      header: wwwAuth.slice(0, 200),
+      macaroon: wwwAuth.match(/macaroon="([^"]*)"/)?.[1] || null,
+      invoice: wwwAuth.match(/invoice="([^"]*)"/)?.[1] || null,
+    };
+  }
+
+  // ── Other payment headers ──
+  if (r.headers) {
+    for (const [k, v] of r.headers.entries()) {
+      if (/payment|invoice|receipt|macaroon|x-mpp|x-402/i.test(k) && k !== 'payment-required' && k !== 'www-authenticate') {
+        result.otherHeaders.push({ name: k, value: v });
+      }
+    }
+  }
+
+  return result;
+}
+
+// ─── Discovery ──────────────────────────────────────────────────────────────
+
+export async function probeDiscovery(origin) {
+  const results = [];
+  const rails = [];
+
+  const wellKnownPaths = [
+    '/.well-known/agentnews.json',
+    '/.well-known/x402.json',
+    '/.well-known/mpp.json',
+    '/.well-known/x402-manifest.json',
+    '/.well-known/pay',
+    '/health',
+    '/openapi.json',
+    '/skill.md',
+    '/llms.txt',
+    '/agents.txt',
+    '/api-docs',
+    '/docs',
+  ];
+
+  for (const path of wellKnownPaths) {
+    const r = await fetchSafe(`${origin}${path}`, { headers: { Accept: 'application/json' } });
+    if (r.status !== 200) continue;
+
+    const entry = { path, status: r.status, hasPayment: false, mentions: [] };
+
+    if (r.json) {
+      const serialized = JSON.stringify(r.json);
+      entry.hasPayment = /settlement_rails|payment|402|mpp|x402|tempo|lightning|l402|usdc|stripe|spt/i.test(serialized);
+      if (r.json.settlement_rails) {
+        const entries = Array.isArray(r.json.settlement_rails)
+          ? r.json.settlement_rails.map(s => [s.method || s.name || '?', s])
+          : Object.entries(r.json.settlement_rails);
+        entry.settlementRails = entries.map(([key, details]) => ({
+          name: details.method || details.name || key,
+          protocol: details.protocol || '?',
+          currency: details.currency || '?',
+          status: details.status || 'available',
+        }));
+        for (const rail of entry.settlementRails) {
+          if (rail.protocol && !rails.includes(rail.protocol)) rails.push(rail.protocol);
+        }
+      }
+      if (r.json.payment_mode) entry.paymentMode = r.json.payment_mode;
+      if (r.json.payment_info) entry.paymentInfo = r.json.payment_info;
+    } else {
+      if (/\bx402\b|Payment-Required/i.test(r.text)) entry.mentions.push('x402');
+      if (/\bMPP\b.*payment|payment.*\bMPP\b|machine.payment.protocol/i.test(r.text)) entry.mentions.push('MPP');
+      if (/\bL402\b|\bLSAT\b/i.test(r.text)) entry.mentions.push('L402');
+      if (/\bUSDC\b/i.test(r.text)) entry.mentions.push('USDC');
+      if (/\blightning\b.*\b(invoice|network|payment)\b/i.test(r.text)) entry.mentions.push('Lightning');
+      if (/\bHTTP 402\b|quota.*exceeded/i.test(r.text)) entry.mentions.push('402 flow');
+    }
+
+    results.push(entry);
+  }
+
+  return { endpoints: results, rails };
+}
+
+// ─── Bazaar Discovery ───────────────────────────────────────────────────────
+
+export async function probeBazaar(origin) {
+  const result = { x402Json: null, x402Probe: null, linkHeader: null, bazaarServices: 0 };
+
+  // /.well-known/x402.json
+  const r1 = await fetchSafe(`${origin}/.well-known/x402.json`, { headers: { Accept: 'application/json' } });
+  if (r1.status === 200 && r1.json) {
+    const raw = r1.json;
+    const rawKeys = Object.keys(raw);
+    // Diagnose expected top-level fields
+    const fieldDiag = (key, label) => {
+      if (key in raw && raw[key]) return { status: 'ok', value: raw[key] };
+      if (key in raw) return { status: 'empty', hint: `"${key}" is present but empty` };
+      // Check for common misspellings / wrong casing
+      const alt = rawKeys.find(k => k.toLowerCase() === key.toLowerCase() || (key === 'name' && k.toLowerCase() === 'provider'));
+      if (alt) return { status: 'misnamed', hint: `found "${alt}" — expected "${key}"`, value: raw[alt] };
+      return { status: 'missing', hint: `add "${key}" to /.well-known/x402.json (${label})` };
+    };
+    result.x402Json = {
+      x402Version: raw.x402Version || 1,
+      name: raw.name,
+      network: raw.network,
+      facilitator: raw.facilitator,
+      payTo: raw.payTo,
+      testnet: raw.testnet || false,
+      rawKeys,
+      fields: {
+        name: fieldDiag('name', 'your service name'),
+        network: fieldDiag('network', 'e.g. base-sepolia or base'),
+        facilitator: fieldDiag('facilitator', 'facilitator URL for payment verification'),
+        payTo: fieldDiag('payTo', 'wallet address to receive payments'),
+      },
+      services: (r1.json.services || []).flatMap(svc => {
+        const bazaar = svc.extensions?.bazaar || null;
+        // Format A (AgentNews): method/path at service level
+        if (svc.method && svc.path) {
+          return [{ method: svc.method, path: svc.path, description: svc.description, amount: svc.humanAmount || svc.amount, bazaar, outputSchema: svc.outputSchema, inputSchema: svc.inputSchema }];
+        }
+        // Format B (CloneRepo/SconeRepo): nested endpoints[]
+        if (svc.endpoints) {
+          return svc.endpoints.map(ep => ({
+            method: ep.method, path: ep.path, description: ep.description || svc.description,
+            amount: svc.payment?.[0]?.amount || svc.amount, bazaar, inputSchema: ep.inputSchema || svc.inputSchema,
+          }));
+        }
+        // Format C: "endpoint" string like "POST /:domain"
+        if (svc.endpoint && typeof svc.endpoint === 'string') {
+          const parts = svc.endpoint.match(/^(GET|POST|PUT|PATCH|DELETE|HEAD)\s+(.+)$/i);
+          if (parts) {
+            return [{ method: parts[1].toUpperCase(), path: parts[2].trim(), description: svc.description || svc.name, amount: svc.price?.amount || svc.amount, bazaar, inputSchema: svc.inputSchema }];
+          }
+        }
+        // Fallback: service with name/description only
+        return [{ method: null, path: null, description: svc.description || svc.name, amount: svc.amount, bazaar }];
+      }),
+      freeEndpoints: r1.json.freeEndpoints || [],
+      // Capture auth info from services (e.g. { type: "EIP-191", domain: "clonerepo.com" })
+      auth: r1.json.services?.[0]?.auth || r1.json.auth || null,
+    };
+    result.bazaarServices += result.x402Json.services.filter(s => s.bazaar?.discoverable).length;
+  }
+
+  // Parse WWW-Authenticate: Payment headers into { mpp, spt } (handles multiple challenges)
+  function parsePaymentAuth(headers) {
+    const wwwAuth = headers?.get('www-authenticate');
+    if (!wwwAuth || !/payment/i.test(wwwAuth)) return null;
+    const challenges = wwwAuth.split(/,?\s*Payment\s+/i).filter(Boolean);
+    const allFields = [];
+    for (const ch of challenges) {
+      const pairs = {};
+      for (const m of ch.matchAll(/(\w+)="([^"]*)"/g)) pairs[m[1]] = m[2];
+      allFields.push(pairs);
+    }
+    const mpp = allFields.length > 0;
+    const stripeCh = allFields.find(p => p.method === 'stripe');
+    let spt = null;
+    if (stripeCh) {
+      let request = null;
+      if (stripeCh.request) try { request = JSON.parse(Buffer.from(stripeCh.request, 'base64url').toString()); } catch {}
+      spt = { method: 'stripe', intent: stripeCh.intent || null, amount: request?.amount || null, currency: request?.currency || null };
+    }
+    return { mpp, spt };
+  }
+
+  // Live 402 probe: try hitting a declared service endpoint to trigger a real 402
+  result.live402 = null;
+  if (result.x402Json) {
+    const targets = result.x402Json.services
+      .filter(s => s.method && s.path)
+      .slice(0, 3);
+    if (targets.length === 0) targets.push({ method: 'POST', path: '/' });
+
+    for (const t of targets) {
+      const probePath = t.path.replace(/:([a-zA-Z_]+)/g, (_, p) => smartParamValue(p)).replace(/\{([^}]+)\}/g, (_, p) => smartParamValue(p));
+      const opts = { method: t.method, headers: { 'Content-Type': 'application/json', 'X-Agent-Id': 'agentgrade-probe' } };
+      if (t.method !== 'GET' && t.method !== 'HEAD') opts.body = JSON.stringify(stubBody(t));
+      const lr = await fetchSafe(`${origin}${probePath}`, opts);
+      if (lr.status === 402) {
+        const prHeader = lr.headers?.get('payment-required');
+        const parsed = prHeader ? tryParseBase64(prHeader) : null;
+        const auth = parsePaymentAuth(lr.headers);
+        result.live402 = {
+          method: t.method, path: t.path, status: 402,
+          version: parsed?.x402Version, options: parsed?.accepts || null,
+          extensions: parsed?.extensions || null,
+          bazaar: parsed?.extensions?.bazaar || null,
+          mpp: auth?.mpp || false, spt: auth?.spt || null,
+        };
+        break;
+      } else if (lr.status === 401 || lr.status === 403) {
+        // If EIP-191 auth is declared, retry with a temp wallet
+        const authInfo = result.x402Json?.auth;
+        if (authInfo?.type === 'EIP-191' && authInfo.domain) {
+          const token = await makeEIP191Token(authInfo.domain);
+          const retryOpts = { ...opts, headers: { ...opts.headers, 'Authorization': `Bearer ${token}` } };
+          const retryR = await fetchSafe(`${origin}${probePath}`, retryOpts);
+          if (retryR.status === 402) {
+            const prHeader = retryR.headers?.get('payment-required');
+            const parsed = prHeader ? tryParseBase64(prHeader) : null;
+            const retryAuth = parsePaymentAuth(retryR.headers);
+            result.live402 = {
+              method: t.method, path: t.path, status: 402,
+              version: parsed?.x402Version, options: parsed?.accepts || null,
+              extensions: parsed?.extensions || null,
+              bazaar: parsed?.extensions?.bazaar || null,
+              mpp: retryAuth?.mpp || false, spt: retryAuth?.spt || null,
+              authUsed: 'EIP-191',
+            };
+            break;
+          }
+        }
+        result.live402 = { method: t.method, path: t.path, status: lr.status, authRequired: true };
+        break;
+      } else if (lr.rateLimited) {
+        result.live402 = { method: t.method, path: t.path, status: 429, rateLimited: true };
+        break;
+      }
+    }
+  }
+
+  // /.well-known/x402-probe
+  const r2 = await fetchSafe(`${origin}/.well-known/x402-probe`, { headers: { Accept: 'application/json' } });
+  if (r2.status === 402) {
+    const prHeader = r2.headers?.get('payment-required');
+    const parsed = prHeader ? tryParseBase64(prHeader) : null;
+    result.x402Probe = {
+      version: parsed?.x402Version,
+      headerBazaar: parsed?.extensions?.bazaar || null,
+      challenges: [],
+    };
+    if (r2.json?.challenges) {
+      result.x402Probe.challenges = r2.json.challenges.map(ch => ({
+        endpoint: ch.endpoint,
+        amount: ch.accepts?.[0]?.amount,
+        assetName: ch.accepts?.[0]?.extra?.name,
+        bazaar: ch.extensions?.bazaar?.discoverable || false,
+      }));
+      result.bazaarServices += result.x402Probe.challenges.filter(c => c.bazaar).length;
+    }
+  }
+
+  // Link header
+  const r3 = await fetchSafe(origin, { method: 'HEAD' });
+  const link = r3.headers?.get('link');
+  if (link && /x402/i.test(link)) {
+    result.linkHeader = link;
+  }
+
+  return result;
+}
+
+// ─── Homepage Scan ──────────────────────────────────────────────────────────
+
+export async function probeHomepage(origin) {
+  const r = await fetchSafe(origin, { headers: { Accept: 'text/html' } });
+  if (!r.text || r.status !== 200) return { protocols: {}, cfBlocked: r.cfBlocked || false };
+
+  const text = r.text;
+  const protocols = {};
+
+  if (/\bx402\b/i.test(text)) protocols.x402 = [];
+  if (/Payment-Required/i.test(text)) (protocols.x402 = protocols.x402 || []).push('Payment-Required header');
+  if (/\bUSDC\b/i.test(text)) (protocols.x402 = protocols.x402 || []).push('USDC');
+  if (/eip155:/i.test(text)) (protocols.x402 = protocols.x402 || []).push('EIP-155 network');
+  if (/eip155:8453|\bBase\s+(chain|mainnet|sepolia)\b/i.test(text)) (protocols.x402 = protocols.x402 || []).push('Base chain');
+
+  if (/\bMPP\b.*payment|payment.*\bMPP\b|machine.payment.protocol/i.test(text)) protocols.MPP = [];
+  if (/WWW-Authenticate:\s*Payment/i.test(text)) (protocols.MPP = protocols.MPP || []).push('WWW-Authenticate: Payment');
+  if (/\bpathUSD\b|\btempo\b.*\bchain\b|\bmppx\b/i.test(text)) (protocols.MPP = protocols.MPP || []).push('Tempo/pathUSD');
+
+  if (/\bL402\b/i.test(text)) protocols.L402 = [];
+  if (/\bLSAT\b/i.test(text)) (protocols.L402 = protocols.L402 || []).push('LSAT');
+  if (/\bmacaroon\b/i.test(text)) (protocols.L402 = protocols.L402 || []).push('macaroon');
+  if (/lightning.{0,50}invoice|invoice.{0,50}lightning/i.test(text)) (protocols.L402 = protocols.L402 || []).push('Lightning invoice');
+
+  if (/\bSPT\b|\bstripe\b.*\bpayment.token\b|\bshared.payment.token/i.test(text)) protocols.SPT = [];
+  if (/method="stripe"|method=["']?stripe/i.test(text)) (protocols.SPT = protocols.SPT || []).push('Stripe method');
+
+  if (/\bHTTP 402\b|402 payment/i.test(text)) protocols['402 flow'] = [];
+  if (/quota.*exceeded|storage.*limit.*exceeded/i.test(text)) (protocols['402 flow'] = protocols['402 flow'] || []).push('quota-based');
+
+  // Check for <link rel="alternate"> pointing to llms.txt
+  const llmsLink = /<link[^>]+rel=["']alternate["'][^>]+href=["'][^"']*llms[^"']*["'][^>]*>/i.test(text)
+    || /<link[^>]+href=["'][^"']*llms[^"']*["'][^>]+rel=["']alternate["'][^>]*>/i.test(text);
+
+  // Check for JSON-LD structured data
+  const jsonLdMatch = text.match(/<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/i);
+  let jsonLd = null;
+  if (jsonLdMatch) {
+    try { const parsed = JSON.parse(jsonLdMatch[1]); jsonLd = { type: parsed['@type'] || (Array.isArray(parsed) ? 'array' : 'object') }; } catch {}
+  }
+
+  // Extract og:image URL
+  const ogImageMatch = text.match(/<meta[^>]+property=["']og:image["'][^>]+content=["']([^"']+)["']/i)
+    || text.match(/<meta[^>]+content=["']([^"']+)["'][^>]+property=["']og:image["']/i);
+  const ogImageUrl = ogImageMatch?.[1] || null;
+  const ogImage = !!ogImageUrl;
+
+  // twitter:image and twitter:card
+  const twitterImage = /<meta[^>]+(?:name|property)=["']twitter:image["'][^>]+content=["'][^"']+["']/i.test(text)
+    || /<meta[^>]+content=["'][^"']+["'][^>]+(?:name|property)=["']twitter:image["']/i.test(text);
+  const twitterCardMatch = text.match(/<meta[^>]+(?:name|property)=["']twitter:card["'][^>]+content=["']([^"']+)["']/i)
+    || text.match(/<meta[^>]+content=["']([^"']+)["'][^>]+(?:name|property)=["']twitter:card["']/i);
+  const twitterCard = twitterCardMatch?.[1] || null;
+
+  // Favicon: SVG and PNG from link tags
+  const faviconSvg = /<link[^>]+type=["']image\/svg\+xml["'][^>]+href=["']([^"']+)["']/i.exec(text)
+    || /<link[^>]+href=["']([^"']+)["'][^>]+type=["']image\/svg\+xml["']/i.exec(text);
+  const faviconPng = /<link[^>]+type=["']image\/png["'][^>]+href=["']([^"']+)["']/i.exec(text)
+    || /<link[^>]+href=["']([^"']+)["'][^>]+type=["']image\/png["']/i.exec(text);
+
+  // Verify reachability of og:image and favicons (parallel)
+  const resolve = (href) => href ? (href.startsWith('http') ? href : `${origin}${href.startsWith('/') ? '' : '/'}${href}`) : null;
+  const [ogReach, svgReach, pngReach, pngFallback] = await Promise.all([
+    ogImageUrl ? fetchSafe(resolve(ogImageUrl), { headers: { Accept: 'image/*' } }) : null,
+    faviconSvg ? fetchSafe(resolve(faviconSvg[1]), { headers: { Accept: 'image/svg+xml' } }) : null,
+    faviconPng ? fetchSafe(resolve(faviconPng[1]), { headers: { Accept: 'image/png' } }) : null,
+    !faviconPng ? fetchSafe(`${origin}/favicon.png`, { headers: { Accept: 'image/png' } }) : null,
+  ]);
+  const ogImageReachable = ogReach?.status === 200;
+  const faviconSvgOk = svgReach?.status === 200;
+  const faviconPngOk = (pngReach?.status === 200) || (pngFallback?.status === 200);
+
+  return {
+    protocols, llmsLink, jsonLd,
+    ogImage, ogImageReachable, twitterImage, twitterCard,
+    faviconSvg: faviconSvgOk, faviconPng: faviconPngOk,
+  };
+}
+
+// ─── Agent Capabilities ─────────────────────────────────────────────────────
+
+export async function probeCapabilities(origin, base) {
+  if (!base || base === origin) return _runProbes(origin, origin);
+
+  // Subpath scan: run full checks independently at both locations, then merge
+  const [atSubpath, atOrigin] = await Promise.all([
+    _runProbes(origin, base),
+    _runProbes(origin, origin),
+  ]);
+
+  // Merge by type: one entry per type, annotate where found
+  const merged = [];
+  const types = [...new Set([...atSubpath, ...atOrigin].map(c => c.type))];
+  for (const type of types) {
+    const subs = atSubpath.filter(c => c.type === type);
+    const origs = atOrigin.filter(c => c.type === type);
+    for (let i = 0; i < Math.max(subs.length, origs.length); i++) {
+      const sub = subs[i], orig = origs[i];
+      if (sub && orig) merged.push({ ...sub, foundAt: 'both' });
+      else if (sub) merged.push({ ...sub, foundAt: 'subpath' });
+      else merged.push({ ...orig, foundAt: 'origin' });
+    }
+  }
+  return merged;
+}
+
+async function _runProbes(origin, base) {
+  const bases = [base];
+  const prefix = base.slice(origin.length);
+
+  async function probeMCP() {
+    const mcpPaths = ['/mcp', '/api/mcp', '/.well-known/mcp.json', '/mcp/docs'];
+    const hit = await firstMatch(bases, mcpPaths, { headers: { Accept: 'application/json' } },
+      r => r.status === 405 || r.status === 406 || (r.status === 200 && (r.json || /mcp|model.context|tool/i.test(r.text))));
+    if (hit?.allCfBlocked) return [{ type: 'MCP', cfBlocked: true }];
+    if (hit) {
+      const { path, r } = hit;
+        const cap = {
+          type: 'MCP', path, verified: false,
+          name: r.json?.name, description: r.json?.description,
+          tools: r.json?.tools?.length, transport: r.json?.transport,
+          detail: r.status === 405 ? 'responds 405 (expects POST/SSE)' : r.status === 406 ? 'responds 406 (Streamable HTTP)' : (!r.json ? 'MCP-related content' : undefined),
+          sseSupported: false, cors: false, protocolVersion: null,
+          streamableHttp: r.status === 406,
+        };
+        const rpcPost = (method, params) => fetchSafe(`${origin}${path}`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
+          body: JSON.stringify({ jsonrpc: '2.0', method, id: 1, params }),
+        });
+        const ir = await rpcPost('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'agentgrade', version: '1.0' } });
+        cap.protocolVersion = ir.json?.result?.protocolVersion || null;
+        cap.name = ir.json?.result?.serverInfo?.name || cap.name;
+        cap.description = ir.json?.result?.serverInfo?.description || cap.description;
+        const tr = await rpcPost('tools/list');
+        const tools = tr.json?.result?.tools;
+        if (tools?.length > 0) {
+          const isPaid = (t) => !!(t._meta?.['agents-x402/paymentRequired'] || t._meta?.paymentRequired);
+          const requiredParams = (t) => (t.inputSchema?.required || []).length;
+          const toolMeta = tools.map(t => ({ name: t.name, paid: isPaid(t), requiredParams: requiredParams(t) }));
+          cap.tools = tools.length;
+          cap.toolNames = toolMeta.map(t => t.name);
+          cap.paidTools = toolMeta.filter(t => t.paid).map(t => t.name);
+          cap.freeTools = toolMeta.filter(t => !t.paid).map(t => t.name);
+          const free = tools.filter(t => !isPaid(t));
+          const candidates = free.length > 0 ? free : tools;
+          const probe = candidates.sort((a, b) => requiredParams(a) - requiredParams(b))[0];
+          const cr = await rpcPost('tools/call', { name: probe.name, arguments: {} });
+          cap.verified = !!(cr.json?.result || cr.json?.error);
+          cap.probeToolUsed = probe.name;
+          cap.probeToolPaid = isPaid(probe);
+        }
+        const [sse, cr2] = await Promise.all([
+          fetchSafe(`${origin}${path}`, { headers: { Accept: 'text/event-stream' } }),
+          fetchSafe(`${origin}${path}`, { method: 'OPTIONS', headers: { Origin: 'https://example.com', 'Access-Control-Request-Method': 'POST' } }),
+        ]);
+        cap.sseSupported = (sse.headers?.get?.('content-type') || '').includes('text/event-stream');
+        cap.cors = !!(cr2.headers?.get?.('access-control-allow-origin'));
+        return [cap];
+    }
+    return [];
+  }
+
+  async function probeClaude() {
+    const claudePaths = ['/.claude-plugin/manifest.json', '/.claude/plugin.json', '/claude.json', '/.well-known/claude.json', '/.well-known/claude-plugin.json'];
+    const hit = await firstMatch(bases, claudePaths, { headers: { Accept: 'application/json' } }, r => r.status === 200 && r.json);
+    if (hit?.allCfBlocked) return [{ type: 'Claude Plugin', cfBlocked: true }];
+    if (hit) {
+      const { path, r } = hit;
+      const toolCount = r.json.tools ? (Array.isArray(r.json.tools) ? r.json.tools.length : Object.keys(r.json.tools).length) : undefined;
+      const rawMcp = r.json.mcp || r.json.mcp_url || r.json.api?.mcp;
+      const mcpUrl = typeof rawMcp === 'string' ? rawMcp : rawMcp?.endpoint || rawMcp?.url;
+      const apiUrl = r.json.api?.url || r.json.openapi;
+      const cap = {
+        type: 'Claude Plugin', path, verified: false,
+        name: r.json.name, description: r.json.description, version: r.json.version,
+        skills: r.json.skills?.length, tools: toolCount,
+        declaredMcp: mcpUrl || null, declaredApi: apiUrl || null,
+      };
+      if (mcpUrl) {
+        const url = mcpUrl.startsWith('http') ? mcpUrl : `${origin}${mcpUrl}`;
+        const mr = await fetchSafe(url, {
+          method: 'POST', headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/list', id: 1 }),
+        });
+        cap.verified = !!(mr.json?.result?.tools);
+      } else if (apiUrl) {
+        const url = apiUrl.startsWith('http') ? apiUrl : `${origin}${apiUrl}`;
+        const ar = await fetchSafe(url, { headers: { Accept: 'application/json' } });
+        cap.verified = ar.status === 200 && !!(ar.json?.openapi || ar.json?.swagger || ar.json?.info);
+      } else {
+        const hasTools = toolCount > 0 && r.json.tools?.some?.(t => t && (t.name || t.description));
+        const hasSkills = r.json.skills?.length > 0 && r.json.skills.some(s => s && (s.name || s.description));
+        cap.verified = !!(r.json.name && r.json.description && (hasTools || hasSkills));
+      }
+      return [cap];
+    }
+    return [];
+  }
+
+  async function probeAIPlugin() {
+    const aiPluginPaths = ['/.well-known/ai-plugin.json', '/ai-plugin.json'];
+    const hit = await firstMatch(origin, aiPluginPaths, { headers: { Accept: 'application/json' } }, r => r.status === 200 && r.json);
+    if (hit?.allCfBlocked) return [{ type: 'AI Plugin', cfBlocked: true }];
+    if (hit) {
+      const { path, r } = hit;
+      const j = r.json;
+      const validApiType = !j.api?.type || j.api.type === 'openapi';
+      const cap = {
+        type: 'AI Plugin', path,
+        name: j.name_for_human, modelName: j.name_for_model,
+        description: j.description_for_human,
+        apiUrl: j.api?.url, apiType: j.api?.type, auth: j.auth?.type,
+        apiSpecReachable: false,
+        verified: !!(j.schema_version && j.name_for_human && j.name_for_model && j.description_for_human && j.api && j.auth && validApiType),
+      };
+      if (cap.apiUrl) {
+        const specUrl = cap.apiUrl.startsWith('http') ? cap.apiUrl : `${origin}${cap.apiUrl}`;
+        const sr = await fetchSafe(specUrl, { headers: { Accept: 'application/json' } });
+        cap.apiSpecReachable = sr.status === 200 && !!(sr.json?.openapi || sr.json?.swagger || sr.json?.info);
+        if (cap.apiSpecReachable && sr.json?.paths) {
+          const getEntries = Object.entries(sr.json.paths).filter(([, m]) => m.get);
+          if (getEntries.length > 0) {
+            const [gPath, gMethods] = getEntries[0];
+            const gr = await fetchSafe(`${origin}${gPath}`, { headers: { Accept: 'application/json' } });
+            const ct = gr.headers?.get?.('content-type') || '';
+            const specProduces = Object.keys(gMethods.get?.responses?.['200']?.content || {});
+            const ctMatches = specProduces.length === 0 || specProduces.some(t => ct.includes(t.split('/')[1]));
+            cap.verified = cap.verified && gr.status && gr.status !== 404 && ctMatches;
+          } else {
+            cap.verified = false;
+          }
+        }
+      }
+      if (cap.verified && !cap.apiSpecReachable) cap.verified = false;
+      return [cap];
+    }
+    return [];
+  }
+
+  async function probeSkills() {
+    const skillPaths = ['/skill.md', '/skills.json', '/.well-known/skills.json'];
+    const hit = await firstMatch(bases, skillPaths, { headers: { Accept: 'application/json' } }, r => r.status === 200);
+    if (hit?.allCfBlocked) return [{ type: 'Skills', cfBlocked: true }];
+    if (hit) {
+      const { path, r } = hit;
+      if (r.json) {
+        const skills = Array.isArray(r.json) ? r.json : [];
+        const wellFormed = skills.every(s => s.name && s.path);
+        let endpointsReachable = 0;
+        let endpointsRespond = 0;
+        for (const sk of skills.slice(0, 3)) {
+          if (!sk.path) continue;
+          const method = (sk.method || 'GET').toUpperCase();
+          const sr = await fetchSafe(`${origin}${sk.path}`, { method, headers: { Accept: 'application/json' } });
+          if (sr.status && sr.status !== 404) endpointsReachable++;
+          if (method !== 'GET' && sr.status && sr.status !== 404) {
+            const vr = await fetchSafe(`${origin}${sk.path}`, {
+              method, headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+              body: '{}',
+            });
+            if (vr.json && (vr.status === 200 || vr.status === 400 || vr.status === 402 || vr.status === 422)) endpointsRespond++;
+          } else if (method === 'GET' && sr.status && sr.status !== 404 && sr.json) {
+            endpointsRespond++;
+          }
+        }
+        return [{
+          type: 'Skills', path, count: skills.length, endpointsReachable,
+          verified: wellFormed && skills.length > 0 && endpointsRespond > 0,
+        }];
+      } else if (r.text.length > 10) {
+        return [{ type: 'Skills', path, bytes: r.text.length, verified: false }];
+      }
+    }
+    return [];
+  }
+
+  async function probeOpenAPI() {
+    const oapiPaths = ['/openapi.json', '/openapi.yaml', '/swagger.json', '/api-docs', '/v1/openapi.json'];
+    const hit = await firstMatch(bases, oapiPaths, { headers: { Accept: 'application/json' } },
+      r => r.status === 200 && r.json && (r.json.openapi || r.json.swagger || r.json.info));
+    if (hit?.allCfBlocked) return [{ type: 'OpenAPI', cfBlocked: true }];
+    if (hit) {
+      const { path, r } = hit;
+      {
+        const declaredPaths = r.json.paths ? Object.keys(r.json.paths) : [];
+        let pathsReachable = 0;
+        let pathsRespond = 0;
+        for (const p of declaredPaths.slice(0, 3)) {
+          const pathDef = r.json.paths[p] || {};
+          const methods = Object.keys(pathDef).filter(m => m !== 'parameters');
+          const method = (methods[0] || 'get').toUpperCase();
+          const sr = await fetchSafe(`${origin}${p}`, { method, headers: { Accept: 'application/json' } });
+          if (sr.status && sr.status !== 404) pathsReachable++;
+          if (sr.json && sr.status >= 200 && sr.status < 300) {
+            const ct = sr.headers?.get?.('content-type') || '';
+            const specProduces = Object.keys(pathDef[methods[0]]?.responses?.['200']?.content || {});
+            const ctOk = specProduces.length === 0 || specProduces.some(t => ct.includes(t.split('/')[1]));
+            if (ctOk) pathsRespond++;
+          }
+        }
+        const paidOps = declaredPaths.filter(p => {
+          const ops = r.json.paths[p] || {};
+          return Object.values(ops).some(op => op?.['x-payment-info']);
+        });
+        return [{
+          type: 'OpenAPI', path,
+          version: r.json.openapi || r.json.swagger,
+          title: r.json.info?.title,
+          paths: declaredPaths.length,
+          pathsReachable,
+          verified: declaredPaths.length > 0 && pathsRespond > 0,
+          xPaymentInfo: paidOps.length > 0 ? { paths: paidOps.length } : null,
+        }];
+      }
+    }
+    return [];
+  }
+
+  async function probeTextFiles() {
+    const results = [];
+    const textOpts = { headers: { Accept: 'text/plain' } };
+    const [llms1, llms2, agentsTxt, robotsTxt] = await Promise.all([
+      fetchSafe(`${base}/llms.txt`, textOpts),
+      fetchSafe(`${base}/llms-full.txt`, textOpts),
+      fetchSafe(`${base}/agents.txt`, textOpts),
+      fetchSafe(`${origin}/robots.txt`, textOpts),
+    ]);
+    if (llms1.cfBlocked) results.push({ type: 'llms.txt', cfBlocked: true });
+    if (agentsTxt.cfBlocked) results.push({ type: 'agents.txt', cfBlocked: true });
+    if (robotsTxt.cfBlocked) results.push({ type: 'robots.txt (agent-aware)', cfBlocked: true });
+    for (const r of [llms1, llms2]) {
+      if (r.status !== 200 || !r.text || r.text.length < 20) continue;
+      const lines = r.text.split('\n').filter(l => l.trim()).length;
+      const firstLine = r.text.split('\n').find(l => l.trim())?.trim().slice(0, 120);
+      const verified = /^#\s+\S/.test(firstLine || '');
+      results.push({ type: 'llms.txt', path: `${prefix}${r === llms1 ? '/llms.txt' : '/llms-full.txt'}`, lines, preview: firstLine, verified });
+    }
+    if (agentsTxt.status === 200 && agentsTxt.text?.length > 10) {
+      results.push({ type: 'agents.txt', path: `${prefix}/agents.txt`, lines: agentsTxt.text.split('\n').filter(l => l.trim()).length });
+    }
+    if (robotsTxt.status === 200 && robotsTxt.text) {
+      const agentMentions = robotsTxt.text.match(/^#.*\b(agents?|AI|GPT|Claude|bots?)\b.*$/gim) || [];
+      const agentUAs = robotsTxt.text.match(/^User-agent:.*\b(GPTBot|ChatGPT|Claude|Anthropic|Google-Extended|Applebot|PerplexityBot)\b.*$/gim) || [];
+      if (agentMentions.length > 0 || agentUAs.length > 0) {
+        // Check if Google-Extended is blocked (Disallow: / after User-agent: Google-Extended)
+        const googleExtBlocked = /User-agent:\s*Google-Extended[\s\S]*?Disallow:\s*\//im.test(robotsTxt.text);
+        results.push({
+          type: 'robots.txt (agent-aware)', path: '/robots.txt',
+          directives: [...agentUAs, ...agentMentions].slice(0, 5).map(l => l.trim()),
+          googleExtBlocked,
+        });
+      }
+    }
+    return results;
+  }
+
+  async function probeIdentity() {
+    const agentDiscovery = [
+      ['/.well-known/webfinger', 'WebFinger', (r) => ({ verified: typeof r.json?.subject === 'string', subject: r.json?.subject })],
+      ['/.well-known/did.json', 'DID Document', (r) => ({ verified: typeof r.json?.id === 'string' && r.json.id.startsWith('did:'), id: r.json?.id })],
+      ['/.well-known/nostr.json', 'Nostr NIP-05', (r) => ({ verified: !!(r.json?.names && typeof r.json.names === 'object' && Object.keys(r.json.names).length > 0) })],
+      ['/.well-known/atproto-did', 'AT Protocol DID', (r) => ({ verified: /^did:(plc|web):/.test(r.text?.trim() || ''), did: r.text?.trim() })],
+      ['/.well-known/apple-app-site-association', 'Apple App Links', null],
+      ['/.well-known/assetlinks.json', 'Android Asset Links', null],
+    ];
+    const responses = await Promise.all(agentDiscovery.map(([path]) => fetchSafe(`${origin}${path}`, { headers: { Accept: 'application/json' } })));
+    const results = [];
+    responses.forEach((r, i) => {
+      const [path, name, validate] = agentDiscovery[i];
+      if (r.cfBlocked) {
+        results.push({ type: name, cfBlocked: true });
+      } else if (r.status === 200 && (r.json || r.text?.length > 5)) {
+        const extra = validate ? validate(r) : {};
+        results.push({ type: name, path, ...extra });
+      }
+    });
+    return results;
+  }
+
+  async function probeContentNegotiation() {
+    const agentUAs = ['ClaudeBot/1.0', 'ChatGPT-User', 'GPTBot/1.0', 'PerplexityBot'];
+    const results = [];
+    // 1. Agent UA → non-HTML response?
+    const uaR = await fetchSafe(`${base}/`, { headers: { 'User-Agent': agentUAs[0], Accept: '*/*' } });
+    if (uaR.cfBlocked) return [{ type: 'Content Negotiation', cfBlocked: true }];
+    const uaCt = (uaR.headers?.get?.('content-type') || '').toLowerCase();
+    const uaNonHtml = uaR.status === 200 && uaCt && !uaCt.includes('text/html') && (uaR.text?.length || 0) > 20;
+    // 2. Accept: application/json → JSON?
+    const jsonR = await fetchSafe(`${base}/`, { headers: { Accept: 'application/json' } });
+    const jsonOk = jsonR.status === 200 && !!jsonR.json && !jsonR.json.error;
+    // 3. Accept: text/plain → text/markdown?
+    const textR = await fetchSafe(`${base}/`, { headers: { Accept: 'text/plain' } });
+    const textCt = (textR.headers?.get?.('content-type') || '').toLowerCase();
+    const textOk = textR.status === 200 && (textCt.includes('text/plain') || textCt.includes('text/markdown')) && (textR.text?.length || 0) > 20;
+
+    if (uaNonHtml || jsonOk || textOk) {
+      results.push({
+        type: 'Content Negotiation', path: `${prefix}/`,
+        agentUA: uaNonHtml ? { contentType: uaCt.split(';')[0].trim() } : null,
+        acceptJson: jsonOk,
+        acceptText: textOk ? { contentType: textCt.split(';')[0].trim() } : null,
+        verified: uaNonHtml || jsonOk || textOk,
+      });
+    }
+    return results;
+  }
+
+  async function probeWebBotAuth() {
+    const r = await fetchSafe(`${origin}/.well-known/http-message-signatures-directory`, { headers: { Accept: 'application/json' } });
+    if (r.cfBlocked) return [{ type: 'Web Bot Auth', cfBlocked: true }];
+    if (r.status !== 200 || !r.json) return [];
+    const members = Array.isArray(r.json.members) ? r.json.members : [];
+    const entities = members.map(m => m.name || m.entity).filter(Boolean);
+    const keyUrls = members.map(m => m.publicKeyUrl || m.keys).filter(Boolean);
+    return [{
+      type: 'Web Bot Auth', path: '/.well-known/http-message-signatures-directory',
+      members: members.length,
+      entities: entities.slice(0, 10),
+      hasKeys: keyUrls.length > 0,
+      verified: members.length > 0 && keyUrls.length > 0,
+    }];
+  }
+
+  const groups = await Promise.all([probeMCP(), probeClaude(), probeAIPlugin(), probeSkills(), probeOpenAPI(), probeTextFiles(), probeIdentity(), probeContentNegotiation(), probeWebBotAuth()]);
+  return groups.flat();
+}
+
+// ─── Consistency Checks ────────────────────────────────────────────────────
+
+export function checkConsistency(capabilities, bazaar, discovery) {
+  const warnings = [];
+
+  // Extract data from capabilities
+  const mcpCap = capabilities.find(c => c.type === 'MCP');
+  const skillsCap = capabilities.find(c => c.type === 'Skills');
+  const oapiCap = capabilities.find(c => c.type === 'OpenAPI');
+
+  // We need the raw data — fetch it in fullScan and pass it here
+  // For now, work with what we have in the capability objects
+  return warnings;
+}
+
+// Deeper consistency check that fetches raw endpoint data
+export async function probeConsistency(origin, capabilities, bazaar, extra = {}) {
+  const warnings = [];
+
+  // Gather raw data from endpoints we know exist
+  let mcpTools = null;
+  const mcpCap = capabilities.find(c => c.type === 'MCP');
+  if (mcpCap) {
+    const r = await fetchSafe(`${origin}${mcpCap.path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
+      body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/list', id: 1 }),
+    });
+    if (r.json?.result?.tools) mcpTools = r.json.result.tools;
+  }
+
+  let skills = null;
+  const skillsCap = capabilities.find(c => c.type === 'Skills');
+  if (skillsCap) {
+    const r = await fetchSafe(`${origin}${skillsCap.path}`, { headers: { Accept: 'application/json' } });
+    if (r.json && Array.isArray(r.json)) skills = r.json;
+  }
+
+  let oapiPaths = null;
+  const oapiCap = capabilities.find(c => c.type === 'OpenAPI');
+  if (oapiCap) {
+    const r = await fetchSafe(`${origin}${oapiCap.path}`, { headers: { Accept: 'application/json' } });
+    if (r.json?.paths) oapiPaths = Object.entries(r.json.paths).flatMap(([p, methods]) =>
+      Object.keys(methods).filter(m => m !== 'parameters').map(m => ({ method: m.toUpperCase(), path: p }))
+    );
+  }
+
+  const x402Services = bazaar?.x402Json?.services || [];
+  const x402Free = bazaar?.x402Json?.freeEndpoints || [];
+
+  // ── MCP vs Skills consistency ──
+  if (mcpTools && skills) {
+    const mcpNames = new Set(mcpTools.map(t => t.name));
+    const skillNames = new Set(skills.map(s => s.name));
+    const inMcpNotSkills = [...mcpNames].filter(n => !skillNames.has(n));
+    const inSkillsNotMcp = [...skillNames].filter(n => !mcpNames.has(n));
+    if (inMcpNotSkills.length > 0) {
+      warnings.push({
+        type: 'mcp_skills_mismatch',
+        severity: 'warn',
+        message: `MCP exposes ${mcpTools.length} tools but skills.json lists ${skills.length}`,
+        detail: `In MCP but not skills.json: ${inMcpNotSkills.join(', ')}`,
+      });
+    }
+    if (inSkillsNotMcp.length > 0) {
+      warnings.push({
+        type: 'skills_mcp_mismatch',
+        severity: 'warn',
+        message: `skills.json lists actions not in MCP`,
+        detail: `In skills.json but not MCP: ${inSkillsNotMcp.join(', ')}`,
+      });
+    }
+  }
+
+  // ── MCP paid tools vs x402 services ──
+  if (mcpTools && x402Services.length > 0) {
+    // Check if MCP paid tools have matching x402 service entries
+    const x402Paths = new Set(x402Services.map(s => s.path));
+    const x402FreePaths = new Set(x402Free.map(e => e.path));
+    // We can't directly map MCP tool names to paths without the skills.json bridge
+    // But if skills.json exists, use it
+    if (skills) {
+      const paidSkills = skills.filter(s => s.auth && s.auth !== 'none');
+      const freeSkills = skills.filter(s => !s.auth || s.auth === 'none');
+      for (const sk of paidSkills) {
+        if (!sk.path) continue;
+        const normalized = sk.path.replace(/:\w+/g, ':id');
+        const inX402 = x402Services.some(s => s.path.replace(/:\w+/g, ':id') === normalized);
+        if (!inX402) {
+          warnings.push({
+            type: 'paid_not_in_x402',
+            severity: 'warn',
+            message: `Paid skill "${sk.name}" (${sk.path}) not listed in x402.json services`,
+            detail: 'Agents won\'t discover this paid endpoint via x402 service catalog',
+          });
+        }
+      }
+      for (const sk of freeSkills) {
+        if (!sk.path) continue;
+        const normalized = sk.path.replace(/:\w+/g, ':id').replace(/\?.*$/, '');
+        const inFree = x402Free.some(e => e.path.replace(/:\w+/g, ':id').replace(/\?.*$/, '') === normalized);
+        if (!inFree && x402Free.length > 0) {
+          warnings.push({
+            type: 'free_not_in_x402',
+            severity: 'info',
+            message: `Free skill "${sk.name}" (${sk.path}) not listed in x402.json freeEndpoints`,
+            detail: 'Consider adding it so agents discover all available actions',
+          });
+        }
+      }
+    }
+  }
+
+  // ── MCP tool count vs OpenAPI path count ──
+  if (mcpTools && oapiPaths) {
+    // Check that MCP tools have corresponding OpenAPI paths
+    if (skills) {
+      for (const sk of skills) {
+        if (!sk.path) continue;
+        const normalized = sk.path.replace(/:\w+/g, '{id}').replace(/\?.*$/, '');
+        const inOapi = oapiPaths.some(p => p.path === normalized && p.method === sk.method);
+        if (!inOapi) {
+          warnings.push({
+            type: 'skill_not_in_openapi',
+            severity: 'info',
+            message: `Skill "${sk.name}" (${sk.method} ${sk.path}) not found in OpenAPI spec`,
+            detail: 'Agents using OpenAPI for discovery won\'t find this endpoint',
+          });
+        }
+      }
+    }
+  }
+
+  // ── x402 payment gating on MCP ──
+  if (mcpCap && x402Services.length > 0) {
+    // Test if MCP gates paid actions — try calling a paid tool without payment
+    const paidTool = mcpTools?.find(t => {
+      if (!skills) return false;
+      const sk = skills.find(s => s.name === t.name);
+      return sk && sk.auth && sk.auth !== 'none';
+    });
+    if (paidTool) {
+      const r = await fetchSafe(`${origin}${mcpCap.path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', 'X-Agent-Id': 'agentgrade-consistency-check' },
+        body: JSON.stringify({
+          jsonrpc: '2.0', method: 'tools/call', id: 99,
+          params: { name: paidTool.name, arguments: { title: '__agentgrade_probe__', url: 'https://example.com' } },
+        }),
+      });
+      if (r.status === 402) {
+        warnings.push({
+          type: 'mcp_402_confirmed',
+          severity: 'pass',
+          message: `MCP correctly gates paid tool "${paidTool.name}" behind 402`,
+          detail: 'Payment required before execution — agents won\'t get free access to paid actions',
+        });
+      } else if (r.status === 200) {
+        warnings.push({
+          type: 'mcp_402_missing',
+          severity: 'error',
+          message: `MCP tool "${paidTool.name}" should require payment but returned 200`,
+          detail: 'Agents can call this paid action for free via MCP. Add payment gating to MCP tool calls.',
+        });
+      }
+    }
+  }
+
+  // ── Skills auth field consistency ──
+  if (skills && x402Services.length === 0 && bazaar?.x402Json === null) {
+    const paidSkills = skills.filter(s => s.auth && s.auth !== 'none');
+    if (paidSkills.length > 0) {
+      warnings.push({
+        type: 'skills_claim_payment_no_x402',
+        severity: 'warn',
+        message: `skills.json claims ${paidSkills.length} paid action(s) but no x402.json found`,
+        detail: 'Publish /.well-known/x402.json so agents can discover payment requirements',
+      });
+    }
+  }
+
+  // ── Homepage claims x402 but scan couldn't confirm it ──
+  const { homepage, probe } = extra;
+  const homepageClaims402 = homepage?.protocols?.x402 || homepage?.protocols?.MPP || homepage?.protocols?.L402;
+  const probeFound402 = probe?.x402 || probe?.mpp || probe?.spt || probe?.l402;
+  const bazaarFound402 = bazaar?.live402?.status === 402 || bazaar?.x402Probe;
+  if (homepageClaims402 && !probeFound402 && !bazaarFound402) {
+    const claimed = Object.keys(homepage.protocols).filter(k => homepage.protocols[k]).join(', ');
+    const hasX402Json = !!bazaar?.x402Json;
+    const probeStatus = probe?.status;
+    if (!hasX402Json) {
+      warnings.push({
+        type: 'homepage_claims_payment_unverifiable',
+        severity: 'warn',
+        message: `Homepage mentions ${claimed} but no live 402 was detected`,
+        detail: `POST to the root returned ${probeStatus || 'unknown'} (not 402), and no /.well-known/x402.json was found. Without a service catalog, the scanner cannot discover which endpoints require payment. Publish /.well-known/x402.json with required fields: x402Version, name, network, facilitator, payTo, and services[]. See https://agentgrade.com/kb/bazaar for the expected format and a minimal passing example.`,
+      });
+    } else {
+      warnings.push({
+        type: 'homepage_claims_payment_no_live_402',
+        severity: 'info',
+        message: `Homepage mentions ${claimed} and x402.json exists, but no live 402 response was observed`,
+        detail: `The declared service endpoints did not return 402 when probed. Check that the paths in x402.json match your actual payment-gated routes.`,
+      });
+    }
+  }
+
+  return warnings;
+}
+
+// ─── Domain Advisory ─────────────────────────────────────────────────────────
+
+const VENTURE_SIGNALS = [
+  /venture\s*os/i, /ventureos/i, /venture-os/i,
+  /domain.*for\s*sale/i, /this\s*domain.*available/i,
+  /buy\s*this\s*domain/i, /make\s*an?\s*offer/i,
+  /parked.*domain/i, /domain\s*parking/i,
+  /hugedomains/i, /dan\.com/i, /sedo\.com/i, /afternic/i, /godaddy\s*auctions/i,
+];
+
+async function checkDomainAdvisory(hostname) {
+  const parts = hostname.split('.');
+  if (parts.length < 2) return null;
+  const tld = parts[parts.length - 1];
+  if (tld === 'com') return null;
+
+  // Check both forms: base.com and basetld.com
+  // e.g. agent.news → check agent.com AND agentnews.com
+  const baseName = parts.slice(0, -1).join('.');
+  const candidates = [`${baseName}.com`];
+  if (parts.length === 2) candidates.push(`${baseName}${tld}.com`);
+
+  for (const comDomain of candidates) {
+    const result = await checkComDomain(comDomain);
+    if (result) return result;
+  }
+  return null;
+}
+
+async function checkComDomain(comDomain) {
+  let r;
+  try {
+    r = await fetchSafe(`https://${comDomain}`, { headers: { Accept: 'text/html, */*' } });
+  } catch { return null; }
+
+  if (!r.text && !r.status) return null;
+
+  const body = (r.text || '').slice(0, 50000);
+  const matched = VENTURE_SIGNALS.filter(re => re.test(body));
+  if (matched.length === 0) return null;
+
+  const isVentureOS = matched.some(re => /venture/i.test(re.source));
+
+  return {
+    comDomain,
+    isVentureOS,
+    signals: matched.map(re => body.match(re)?.[0]).filter(Boolean),
+    message: isVentureOS
+      ? `${comDomain} appears to be held by VentureOS, a portfolio associated with copycat activity. Consider securing the .com before it causes brand confusion.`
+      : `${comDomain} appears to be a parked or for-sale domain. Consider acquiring it to protect your brand.`,
+  };
+}
+
+// ─── Full Scan ──────────────────────────────────────────────────────────────
+
+export async function fullScan(targetUrl, method = 'POST', body = undefined) {
+  const t0 = performance.now();
+  const parsed = new URL(targetUrl);
+  const origin = parsed.origin;
+  const base = origin + parsed.pathname.replace(/\/$/, '');
+  const isRoot = parsed.pathname === '/' || parsed.pathname === '';
+  const subpath = base !== origin ? parsed.pathname.replace(/\/$/, '') : null;
+
+  const timings = {};
+  const timed = (name, fn) => { const s = performance.now(); return fn().then(r => { timings[name] = Math.round(performance.now() - s); return r; }); };
+
+  const [probeResult, discovery, bazaar, rawCapabilities] = await Promise.all([
+    timed('probe402', () => probe402(targetUrl, method, body)),
+    timed('discovery', () => probeDiscovery(origin)),
+    timed('bazaar', () => probeBazaar(origin)),
+    timed('capabilities', () => probeCapabilities(origin, base)),
+  ]);
+  const capabilities = rawCapabilities.filter(c => !c.cfBlocked);
+  const cfBlockedProbes = rawCapabilities.filter(c => c.cfBlocked).map(c => c.type);
+
+  let homepage = null;
+  if (isRoot) {
+    homepage = await timed('homepage', () => probeHomepage(origin));
+  }
+
+  // Subpath discoverability: does the domain root advertise this service?
+  let subpathDiscoverable = null;
+  if (subpath) {
+    const rootR = await fetchSafe(origin, { headers: { Accept: 'application/json, text/html, */*' } });
+    subpathDiscoverable = rootR.text && rootR.text.includes(subpath) ? 'referenced' : 'not_found';
+  }
+
+  // Cross-reference consistency
+  const consistency = await timed('consistency', () => probeConsistency(origin, capabilities, bazaar, { homepage, probe: probeResult }));
+
+  // Build summary
+  const rails = [...discovery.rails];
+  if (probeResult.x402 && !rails.includes('x402')) rails.push('x402');
+  if (probeResult.mpp && !rails.includes('MPP')) rails.push('MPP');
+  if (probeResult.spt && !rails.includes('SPT')) rails.push('SPT');
+  if (probeResult.l402 && !rails.includes('L402')) rails.push('L402');
+
+  // Live 402 confirms x402 — actual payment gating observed
+  if (bazaar.live402?.status === 402 && !rails.includes('x402')) rails.push('x402');
+  if (bazaar.x402Probe && !rails.includes('x402')) rails.push('x402');
+  // x402.json declares support but isn't live confirmation
+  if (bazaar.x402Json && !rails.includes('x402') && !rails.includes('x402 (documented)')) rails.push('x402 (documented)');
+
+  const confirmed = rails.filter(r => !r.includes('(documented)'));
+  const documented = rails.filter(r => r.includes('(documented)'));
+  const capabilityTypes = [...new Set(capabilities.map(c => c.type))];
+  const cfBlocked = probeResult.cfBlocked || homepage?.cfBlocked || false;
+  const rateLimited = probeResult.rateLimited || bazaar.live402?.rateLimited || false;
+  timings.total = Math.round(performance.now() - t0);
+
+  const result = {
+    url: targetUrl,
+    origin,
+    base,
+    subpath,
+    method,
+    probe: probeResult,
+    discovery,
+    bazaar,
+    homepage,
+    capabilities,
+    consistency,
+    subpathDiscoverable,
+    timings,
+    summary: {
+      confirmedRails: confirmed,
+      documentedRails: documented,
+      bazaarServices: bazaar.bazaarServices,
+      capabilities: capabilityTypes,
+      cfBlocked,
+      cfBlockedProbes,
+      rateLimited,
+      subpath,
+      subpathDiscoverable,
+    },
+  };
+  result.score = computeScore(result);
+  result.domainAdvisory = await timed('domainAdvisory', () => checkDomainAdvisory(parsed.hostname));
+  return result;
+}
+
+// ─── Score ───────────────────────────────────────────────────────────────────
+
+export function computeScore(data) {
+  const capMap = {};
+  (data.capabilities || []).forEach(c => { capMap[c.type] = capMap[c.type] || c; });
+  const bz = data.bazaar || {};
+  const disc = (path) => (data.discovery?.endpoints || []).find(e => e.path === path);
+  const hasX402Json = disc('/.well-known/x402.json');
+  const x402Opt = data.probe?.x402?.options?.[0] || bz.live402?.options?.[0];
+  const hasAnyPayment = !!data.probe?.x402 || bz.live402?.status === 402 || !!bz.x402Probe || !!data.probe?.mpp || !!data.probe?.spt || !!data.probe?.l402;
+  const sm = data.summary || {};
+
+  const groups = [
+    { key: 'payments', label: 'Machine Payments', weight: 3, checks: [
+      { label: 'Live 402 response', passed: hasAnyPayment },
+      { label: 'x402', passed: !!data.probe?.x402 || bz.live402?.status === 402 || !!bz.x402Probe, optional: hasAnyPayment },
+      { label: 'MPP', passed: !!data.probe?.mpp || !!bz.live402?.mpp, optional: hasAnyPayment },
+      { label: 'SPT (Stripe)', passed: !!data.probe?.spt || !!bz.live402?.spt, optional: hasAnyPayment },
+      { label: 'L402', passed: !!data.probe?.l402, optional: hasAnyPayment },
+      { label: 'Payment header decodable', passed: (!!data.probe?.x402 && !data.probe.x402.decodeFailed) || !!bz.live402?.version || (data.probe?.mpp?.fields && Object.keys(data.probe.mpp.fields).length > 0) || !!data.probe?.l402 },
+      { label: 'Recipient specified', passed: !!(x402Opt?.payTo && x402Opt.payTo !== '?') || !!bz.x402Json?.payTo || !!data.probe?.mpp?.fields?.recipient },
+      { label: 'Payment terms specified', passed: !!(x402Opt?.amount || data.probe?.mpp?.fields?.amount || data.probe?.l402?.invoice) },
+      { label: 'Discovery published', passed: !!hasX402Json || !!bz.x402Json || !!disc('/.well-known/mpp.json') },
+    ]},
+    { key: 'Bazaar', label: 'Bazaar discovery', weight: 3, checks: [
+      { label: 'Bazaar in live 402 header', passed: !!bz.live402?.bazaar },
+      { label: '/.well-known/x402.json exists', passed: !!bz.x402Json },
+      { label: 'Discoverable service declared', passed: sm.bazaarServices > 0 },
+      { label: 'Provider (name) specified', passed: bz.x402Json?.fields?.name?.status === 'ok' },
+      { label: 'Facilitator specified', passed: bz.x402Json?.fields?.facilitator?.status === 'ok' },
+      { label: 'payTo specified', passed: bz.x402Json?.fields?.payTo?.status === 'ok' },
+    ]},
+    { key: 'MCP', label: 'MCP endpoint', weight: 2, checks: [
+      { label: 'MCP endpoint responds', passed: !!capMap['MCP'] },
+      { label: 'Initialize handshake', passed: !!capMap['MCP']?.protocolVersion },
+      { label: 'Tools listed', passed: capMap['MCP']?.tools > 0 },
+      { label: 'tools/call responds', passed: !!capMap['MCP']?.verified },
+      { label: 'Server name present', passed: !!capMap['MCP']?.name },
+      { label: 'SSE transport', passed: !!capMap['MCP']?.sseSupported, optional: true },
+      { label: 'CORS enabled', passed: !!capMap['MCP']?.cors, optional: true },
+    ]},
+    { key: 'OpenAPI', label: 'OpenAPI spec', weight: 2, checks: [
+      { label: 'OpenAPI spec found', passed: !!capMap['OpenAPI'] },
+      { label: 'Paths defined', passed: capMap['OpenAPI']?.paths > 0 },
+      { label: 'Paths reachable', passed: (capMap['OpenAPI']?.pathsReachable || 0) > 0 },
+      { label: 'Response matches spec', passed: !!capMap['OpenAPI']?.verified },
+      { label: 'Version identified', passed: !!capMap['OpenAPI']?.version },
+      { label: 'Title present', passed: !!capMap['OpenAPI']?.title },
+      { label: 'x-payment-info declared', passed: !!capMap['OpenAPI']?.xPaymentInfo, optional: true },
+    ]},
+    { key: 'llms.txt', label: 'llms.txt', weight: 2, checks: [
+      { label: 'llms.txt found', passed: !!capMap['llms.txt'] },
+      { label: 'Meaningful content', passed: (capMap['llms.txt']?.lines || 0) > 3 },
+    ]},
+    { key: 'Homepage & Meta', label: 'Homepage & Meta', weight: 1, checks: [
+      { label: 'Linked from HTML', passed: !!data.homepage?.llmsLink, optional: true },
+      { label: 'JSON-LD structured data', passed: !!data.homepage?.jsonLd, optional: true },
+      { label: 'og:image declared', passed: !!data.homepage?.ogImage, optional: true },
+      { label: 'og:image reachable', passed: !!data.homepage?.ogImageReachable, optional: true },
+      { label: 'twitter:card set', passed: !!data.homepage?.twitterCard, optional: true },
+      { label: 'Favicon SVG', passed: !!data.homepage?.faviconSvg, optional: true },
+      { label: 'Favicon PNG', passed: !!data.homepage?.faviconPng, optional: true },
+    ]},
+    { key: 'AI Plugin', label: 'AI plugin', weight: 1, checks: [
+      { label: 'ai-plugin.json found', passed: !!capMap['AI Plugin'] },
+      { label: 'name_for_model present', passed: !!capMap['AI Plugin']?.modelName },
+      { label: 'api.type is openapi', passed: !!capMap['AI Plugin'] && (!capMap['AI Plugin'].apiType || capMap['AI Plugin'].apiType === 'openapi') },
+      { label: 'API spec URL present', passed: !!capMap['AI Plugin']?.apiUrl },
+      { label: 'API spec reachable', passed: !!capMap['AI Plugin']?.apiSpecReachable },
+      { label: 'API endpoint responds', passed: !!capMap['AI Plugin']?.verified },
+    ]},
+    { key: 'Claude Plugin', label: 'Claude plugin', weight: 1, checks: [
+      { label: 'Plugin manifest found', passed: !!capMap['Claude Plugin'] },
+      { label: 'Name present', passed: !!capMap['Claude Plugin']?.name },
+      { label: 'Description present', passed: !!capMap['Claude Plugin']?.description },
+      { label: 'Declared endpoint responds', passed: !!capMap['Claude Plugin']?.verified },
+    ]},
+    { key: 'Skills', label: 'Skills manifest', weight: 1, checks: [
+      { label: 'Skills file found', passed: !!capMap['Skills'] },
+      { label: 'Skills defined', passed: (capMap['Skills']?.count || 0) > 0 },
+      { label: 'Skill endpoints reachable', passed: (capMap['Skills']?.endpointsReachable || 0) > 0 },
+    ]},
+    { key: 'agents.txt', label: 'agents.txt', weight: 1, checks: [
+      { label: 'agents.txt found', passed: !!capMap['agents.txt'] },
+    ]},
+    { key: 'robots.txt', label: 'robots.txt directives', weight: 1, checks: [
+      { label: 'robots.txt found with agent directives', passed: !!capMap['robots.txt (agent-aware)'] },
+      { label: 'Google-Extended not blocked', passed: !!capMap['robots.txt (agent-aware)'] && !capMap['robots.txt (agent-aware)'].googleExtBlocked, optional: true },
+    ]},
+    { key: 'Content Negotiation', label: 'Content negotiation', weight: 1, checks: [
+      { label: 'Agent UA gets non-HTML', passed: !!capMap['Content Negotiation']?.agentUA },
+      { label: 'Accept: JSON returns JSON', passed: !!capMap['Content Negotiation']?.acceptJson },
+      { label: 'Accept: text returns text', passed: !!capMap['Content Negotiation']?.acceptText },
+    ]},
+    { key: 'Web Bot Auth', label: 'Bot authentication', weight: 0, checks: [
+      { label: 'Signatures directory published', passed: !!capMap['Web Bot Auth'], optional: true },
+      { label: 'Members declared', passed: (capMap['Web Bot Auth']?.members || 0) > 0, optional: true },
+      { label: 'Public keys available', passed: !!capMap['Web Bot Auth']?.hasKeys, optional: true },
+    ]},
+    { key: 'Identity', label: 'Identity', weight: 0, checks: [
+      { label: 'WebFinger', passed: !!capMap['WebFinger'], optional: true },
+      { label: 'DID Document', passed: !!capMap['DID Document'], optional: true },
+      { label: 'Nostr NIP-05', passed: !!capMap['Nostr NIP-05'], optional: true },
+      { label: 'AT Protocol DID', passed: !!capMap['AT Protocol DID'], optional: true },
+      { label: 'Apple App Links', passed: !!capMap['Apple App Links'], optional: true },
+      { label: 'Android Asset Links', passed: !!capMap['Android Asset Links'], optional: true },
+    ]},
+  ];
+
+  const allChecks = groups.flatMap(g => g.checks.map(ch => ({ ...ch, weight: g.weight })));
+  const scoredChecks = allChecks.filter(ch => ch.passed || !ch.optional);
+  const passedChecks = allChecks.filter(ch => ch.passed).length;
+  const totalChecks = scoredChecks.length;
+  const pct = totalChecks > 0 ? Math.round((passedChecks / totalChecks) * 100) : 0;
+
+  return { passedChecks, totalChecks, pct, groups: groups.map(g => ({ key: g.key, label: g.label, passed: g.checks.filter(c => c.passed).length, total: g.checks.filter(c => c.passed || !c.optional).length })) };
+}
+
+// ─── Scan Delta ──────────────────────────────────────────────────────────────
+
+export function computeDelta(current, previous) {
+  if (!current || !previous) return null;
+  const cr = current.confirmedRails || [], pr = previous.confirmedRails || [];
+  const cc = current.capabilities || [], pc = previous.capabilities || [];
+  const addedRails = cr.filter(r => !pr.includes(r));
+  const removedRails = pr.filter(r => !cr.includes(r));
+  const addedCapabilities = cc.filter(c => !pc.includes(c));
+  const removedCapabilities = pc.filter(c => !cc.includes(c));
+  const bazaarDelta = (current.bazaarServices || 0) - (previous.bazaarServices || 0);
+  return {
+    addedRails, removedRails, addedCapabilities, removedCapabilities, bazaarDelta,
+    changed: addedRails.length + removedRails.length + addedCapabilities.length + removedCapabilities.length > 0 || bazaarDelta !== 0,
+  };
+}
+
+// ─── x402.json Validator ─────────────────────────────────────────────────────
+
+export function validateX402Json(raw) {
+  const errors = [], warnings = [], suggestions = [];
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { valid: false, errors: ['Input must be a JSON object'], warnings, suggestions };
+
+  if (!raw.name) errors.push('Missing required field: "name"');
+  if (!raw.payTo) errors.push('Missing required field: "payTo"');
+  else if (!/^0x[a-fA-F0-9]{40}$/.test(raw.payTo)) warnings.push('"payTo" does not look like a valid Ethereum address');
+  if (!raw.network) errors.push('Missing required field: "network"');
+
+  if (raw.x402Version && raw.x402Version !== 1 && raw.x402Version !== 2) warnings.push(`Unexpected x402Version: ${raw.x402Version}`);
+  if (!raw.x402Version) suggestions.push('Add "x402Version": 2 to declare protocol version');
+
+  if (!raw.services || !Array.isArray(raw.services)) {
+    errors.push('Missing or invalid "services" array');
+  } else {
+    raw.services.forEach((svc, i) => {
+      if (!svc.method && !svc.endpoints) warnings.push(`services[${i}]: missing "method" or "endpoints"`);
+      if (!svc.path && !svc.endpoints) warnings.push(`services[${i}]: missing "path" or "endpoints"`);
+      if (!svc.description) suggestions.push(`services[${i}]: add a "description" for agent discoverability`);
+    });
+  }
+
+  if (!raw.facilitator) suggestions.push('Add "facilitator" for payment verification');
+
+  return { valid: errors.length === 0, errors, warnings, suggestions };
+}