weftens 0.0.1 → 0.1.1

package/agent-cores/seo-content/test/strategy.test.mjs

@@ -0,0 +1,108 @@
+// Strategy-engine tests — run with `node --test`. Every assertion pins a SPECIFIC
+// seeded issue in the fixture. If these pass, the engine is doing real arithmetic
+// and threshold logic, not echoing a prompt.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { parseRecords } from '../src/parse.mjs';
+import { buildStrategy, expectedCtr, classifyIntent } from '../src/strategy.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const csv = readFileSync(join(__dirname, 'fixtures', 'gsc-sample.csv'), 'utf8');
+const records = parseRecords(csv);
+const result = buildStrategy(records);
+
+const q = (list, query) => list.find((x) => x.query === query);
+
+test('striking-distance detects the two page-two keywords (pos 11-20)', () => {
+  const queries = result.strikingDistance.map((r) => r.query).sort();
+  assert.deepEqual(queries, ['best crm for solar installers', 'crm for real estate agents']);
+  for (const r of result.strikingDistance) {
+    assert.ok(r.position >= 11 && r.position <= 20);
+    assert.equal(r.lever, 'improve-rank');
+  }
+});
+
+test('striking-distance click math is real: 2000 impr x CTR@pos5 - 20 now', () => {
+  const rec = q(result.strikingDistance, 'crm for real estate agents');
+  // expectedCtr(5) = 0.061 -> 2000*0.061 = 122 ; gain = 122 - 20 = 102
+  assert.equal(rec.projectedCtr, 0.061);
+  assert.equal(rec.projectedClicks, 122);
+  assert.equal(rec.opportunityClicks, 102);
+  assert.match(rec.math, /2000 impr/);
+});
+
+test('high-impression/low-CTR flags "free crm" with the title/meta lever', () => {
+  const rec = q(result.lowCtrOpportunities, 'free crm');
+  assert.ok(rec, 'free crm surfaced as a low-CTR opportunity');
+  assert.equal(rec.lever, 'improve-ctr');
+  // pos4 expected CTR 0.08 -> 5000*0.08 = 400 ; gain = 400 - 50 = 350
+  assert.equal(rec.projectedClicks, 400);
+  assert.equal(rec.opportunityClicks, 350);
+});
+
+test('a healthy page-one keyword is NOT flagged as low-CTR', () => {
+  // "best crm software" pos3, 11% CTR is above 70% of expected(3)=0.11
+  assert.equal(q(result.lowCtrOpportunities, 'best crm software'), undefined);
+});
+
+test('cannibalization: "crm pricing" splits across two URLs', () => {
+  const rec = q(result.cannibalization, 'crm pricing');
+  assert.ok(rec, 'cannibalization detected');
+  assert.equal(rec.urlCount, 2);
+  assert.equal(rec.primaryUrl, 'https://acme.example/pricing');
+  assert.deepEqual(rec.competingUrls, ['https://acme.example/plans']);
+  // 300 of 1100 impressions land off the primary URL -> ~0.273, above the 0.2 warn line
+  assert.equal(rec.splitShare, 0.273);
+  assert.equal(rec.severity, 'warn');
+  assert.equal(rec.confidence, 'verified-in-data');
+});
+
+test('a single-URL query is not reported as cannibalization', () => {
+  assert.equal(q(result.cannibalization, 'free crm'), undefined);
+});
+
+test('opportunity list is ranked by modeled click gain, descending', () => {
+  const gains = result.opportunities.map((o) => o.opportunityClicks);
+  for (let i = 1; i < gains.length; i += 1) {
+    assert.ok(gains[i - 1] >= gains[i], 'sorted descending by opportunityClicks');
+  }
+  assert.ok(result.totalOpportunityClicks > 0);
+});
+
+test('intent classification is lexical and deterministic', () => {
+  assert.equal(classifyIntent('buy crm software online'), 'act');
+  assert.equal(classifyIntent('best crm software'), 'compare');
+  assert.equal(classifyIntent('how to use a crm'), 'learn');
+  assert.equal(classifyIntent('enterprise crm platform'), 'unknown');
+});
+
+test('expectedCtr curve is monotonic down and interpolates fractional positions', () => {
+  assert.ok(expectedCtr(1) > expectedCtr(5));
+  assert.ok(expectedCtr(5) > expectedCtr(10));
+  assert.ok(expectedCtr(10) > expectedCtr(20));
+  const mid = expectedCtr(1.5);
+  assert.ok(mid < expectedCtr(1) && mid > expectedCtr(2), 'pos 1.5 lies between pos 1 and 2');
+});
+
+test('topic clustering groups the crm queries under a shared token', () => {
+  const crm = result.clusters.find((c) => c.topic === 'crm');
+  assert.ok(crm, 'a "crm" cluster exists');
+  assert.ok(crm.size >= 5);
+  assert.ok(crm.impressions > 0);
+});
+
+test('same input -> byte-identical output (deterministic)', () => {
+  const a = JSON.stringify(buildStrategy(parseRecords(csv)));
+  const b = JSON.stringify(buildStrategy(parseRecords(csv)));
+  assert.equal(a, b);
+});
+
+test('the templated read reports real counts, no fabricated prose', () => {
+  assert.match(result.summary, /10 queries analyzed/);
+  assert.match(result.summary, /striking-distance/);
+  assert.match(result.summary, /cannibalization/);
+});

package/agent-cores/seo-technical/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/seo-technical",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Technical-SEO auditor. Deterministic: fetch a URL, compute crawl/index/render findings. No LLM in the core.",
+  "bin": {
+    "seo-technical": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "audit": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/agent-cores/seo-technical/src/audit.mjs

@@ -0,0 +1,233 @@
+// Deterministic technical-SEO audit. No LLM. Given a fetched page (and optionally
+// its robots.txt and sitemap.xml), compute checkable findings grouped by root cause.
+//
+// Input is data, not a prompt. Every finding carries evidence a developer can act on.
+
+const SEVERITY_ORDER = { fail: 0, warn: 1, info: 2, pass: 3 };
+
+// --- tiny, dependency-free HTML extractors (adequate for the specific tags we check) ---
+
+function firstMatch(re, s) {
+  const m = re.exec(s);
+  return m ? m[1] : null;
+}
+
+function allMatches(re, s) {
+  const out = [];
+  let m;
+  while ((m = re.exec(s)) !== null) out.push(m);
+  return out;
+}
+
+function getAttr(tag, name) {
+  const m = new RegExp(`${name}\\s*=\\s*["']([^"']*)["']`, 'i').exec(tag);
+  return m ? m[1] : null;
+}
+
+function metaContent(html, nameOrProp, value) {
+  // find <meta ... name="robots" ... content="...">
+  const tags = allMatches(/<meta\b[^>]*>/gi, html).map((m) => m[0]);
+  for (const tag of tags) {
+    const key = getAttr(tag, nameOrProp);
+    if (key && key.toLowerCase() === value.toLowerCase()) return getAttr(tag, 'content');
+  }
+  return null;
+}
+
+export function auditPage(input) {
+  const {
+    url = null,
+    finalUrl = url,
+    status = null,
+    redirectChain = [],
+    html = '',
+    robotsTxt = null,
+    sitemapXml = null,
+  } = input;
+
+  const findings = [];
+  const add = (f) => findings.push(f);
+
+  // --- HTTP status & redirects ---
+  if (status === null) {
+    add({ id: 'http-status', category: 'crawl', severity: 'info', message: 'No HTTP status provided (offline audit).' });
+  } else if (status >= 200 && status < 300) {
+    add({ id: 'http-status', category: 'crawl', severity: 'pass', message: `HTTP ${status}.`, evidence: String(status) });
+  } else if (status >= 300 && status < 400) {
+    add({ id: 'http-status', category: 'crawl', severity: 'warn', message: `HTTP ${status} redirect at the requested URL.`, evidence: String(status) });
+  } else {
+    add({ id: 'http-status', category: 'crawl', severity: 'fail', message: `HTTP ${status} — page not served.`, evidence: String(status) });
+  }
+
+  if (redirectChain.length > 1) {
+    add({
+      id: 'redirect-chain',
+      category: 'crawl',
+      severity: redirectChain.length > 2 ? 'warn' : 'info',
+      message: `${redirectChain.length}-hop redirect chain wastes crawl budget and link equity.`,
+      evidence: redirectChain.join(' -> '),
+    });
+  }
+
+  if (finalUrl && finalUrl.startsWith('http://')) {
+    add({ id: 'https', category: 'crawl', severity: 'fail', message: 'Final URL is not HTTPS.', evidence: finalUrl });
+  } else if (finalUrl && finalUrl.startsWith('https://')) {
+    add({ id: 'https', category: 'crawl', severity: 'pass', message: 'Served over HTTPS.', evidence: finalUrl });
+  }
+
+  // --- Indexability: meta robots ---
+  const robotsMeta = metaContent(html, 'name', 'robots');
+  if (robotsMeta && /noindex/i.test(robotsMeta)) {
+    add({ id: 'meta-robots', category: 'index', severity: 'fail', message: 'Page is set to noindex — it will not rank.', evidence: robotsMeta });
+  } else if (robotsMeta) {
+    add({ id: 'meta-robots', category: 'index', severity: 'info', message: `meta robots: ${robotsMeta}.`, evidence: robotsMeta });
+  }
+
+  // --- Canonical ---
+  const canonicalTag = allMatches(/<link\b[^>]*>/gi, html).map((m) => m[0]).find((t) => /rel\s*=\s*["']canonical["']/i.test(t));
+  if (!canonicalTag) {
+    add({ id: 'canonical', category: 'index', severity: 'warn', message: 'No canonical link — duplicate-content risk across URL variants.' });
+  } else {
+    const href = getAttr(canonicalTag, 'href');
+    const selfRef = finalUrl && href && (href === finalUrl || href.replace(/\/$/, '') === finalUrl.replace(/\/$/, ''));
+    add({
+      id: 'canonical',
+      category: 'index',
+      severity: selfRef || !finalUrl ? 'pass' : 'info',
+      message: selfRef ? 'Self-referential canonical.' : `Canonical points elsewhere: ${href}.`,
+      evidence: href,
+    });
+  }
+
+  // --- Title ---
+  const title = firstMatch(/<title[^>]*>([\s\S]*?)<\/title>/i, html);
+  if (!title || !title.trim()) {
+    add({ id: 'title', category: 'content-signals', severity: 'fail', message: 'Missing <title>.' });
+  } else {
+    const len = title.trim().length;
+    const sev = len < 10 || len > 65 ? 'warn' : 'pass';
+    add({ id: 'title', category: 'content-signals', severity: sev, message: `Title ${len} chars${sev === 'warn' ? ' (aim 10–65)' : ''}.`, evidence: title.trim() });
+  }
+
+  // --- Meta description ---
+  const desc = metaContent(html, 'name', 'description');
+  if (!desc) {
+    add({ id: 'meta-description', category: 'content-signals', severity: 'warn', message: 'No meta description.' });
+  } else {
+    const len = desc.length;
+    const sev = len < 50 || len > 160 ? 'warn' : 'pass';
+    add({ id: 'meta-description', category: 'content-signals', severity: sev, message: `Meta description ${len} chars${sev === 'warn' ? ' (aim 50–160)' : ''}.`, evidence: desc });
+  }
+
+  // --- Viewport (mobile) ---
+  const viewport = metaContent(html, 'name', 'viewport');
+  add(viewport
+    ? { id: 'viewport', category: 'render', severity: 'pass', message: 'Mobile viewport declared.', evidence: viewport }
+    : { id: 'viewport', category: 'render', severity: 'warn', message: 'No viewport meta — mobile rendering degraded.' });
+
+  // --- H1 ---
+  const h1s = allMatches(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi, html);
+  if (h1s.length === 0) {
+    add({ id: 'h1', category: 'content-signals', severity: 'warn', message: 'No <h1>.' });
+  } else if (h1s.length > 1) {
+    add({ id: 'h1', category: 'content-signals', severity: 'info', message: `${h1s.length} <h1> elements (usually one is intended).` });
+  } else {
+    add({ id: 'h1', category: 'content-signals', severity: 'pass', message: 'Exactly one <h1>.', evidence: h1s[0][1].replace(/<[^>]+>/g, '').trim().slice(0, 120) });
+  }
+
+  // --- JSON-LD structured data (grounds AI-answer / rich-result eligibility) ---
+  const ldScripts = allMatches(/<script\b[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi, html);
+  if (ldScripts.length === 0) {
+    add({ id: 'jsonld', category: 'structured-data', severity: 'warn', message: 'No JSON-LD structured data — weaker grounding for rich results and AI answers.' });
+  } else {
+    const types = [];
+    let broken = 0;
+    for (const m of ldScripts) {
+      try {
+        const parsed = JSON.parse(m[1].trim());
+        const collect = (o) => {
+          if (Array.isArray(o)) return o.forEach(collect);
+          if (o && typeof o === 'object' && o['@type']) types.push(...[].concat(o['@type']));
+        };
+        collect(parsed);
+      } catch {
+        broken += 1;
+      }
+    }
+    if (broken > 0) add({ id: 'jsonld-invalid', category: 'structured-data', severity: 'fail', message: `${broken} of ${ldScripts.length} JSON-LD blocks fail to parse — invalid to every consumer.` });
+    if (types.length) add({ id: 'jsonld', category: 'structured-data', severity: 'pass', message: `JSON-LD present: ${[...new Set(types)].join(', ')}.`, evidence: [...new Set(types)].join(', ') });
+  }
+
+  // --- hreflang ---
+  const hreflangs = allMatches(/<link\b[^>]*>/gi, html).map((m) => m[0]).filter((t) => /hreflang\s*=/i.test(t));
+  if (hreflangs.length) add({ id: 'hreflang', category: 'index', severity: 'info', message: `${hreflangs.length} hreflang alternates declared.` });
+
+  // --- Image alt coverage ---
+  const imgs = allMatches(/<img\b[^>]*>/gi, html).map((m) => m[0]);
+  if (imgs.length) {
+    const withAlt = imgs.filter((t) => getAttr(t, 'alt') !== null).length;
+    const pct = Math.round((withAlt / imgs.length) * 100);
+    add({ id: 'img-alt', category: 'content-signals', severity: pct < 80 ? 'warn' : 'pass', message: `${withAlt}/${imgs.length} images have alt (${pct}%).`, evidence: `${pct}%` });
+  }
+
+  // --- robots.txt ---
+  if (robotsTxt !== null) {
+    const blocksAll = /User-agent:\s*\*[\s\S]*?Disallow:\s*\/\s*($|\n)/i.test(robotsTxt);
+    add(blocksAll
+      ? { id: 'robots-txt', category: 'crawl', severity: 'fail', message: 'robots.txt disallows all crawling (Disallow: /).' }
+      : { id: 'robots-txt', category: 'crawl', severity: 'pass', message: 'robots.txt does not block the whole site.' });
+    const sitemapDirective = firstMatch(/Sitemap:\s*(\S+)/i, robotsTxt);
+    add(sitemapDirective
+      ? { id: 'robots-sitemap', category: 'crawl', severity: 'pass', message: 'robots.txt advertises a sitemap.', evidence: sitemapDirective }
+      : { id: 'robots-sitemap', category: 'crawl', severity: 'info', message: 'robots.txt has no Sitemap: directive.' });
+  }
+
+  // --- sitemap.xml ---
+  if (sitemapXml !== null) {
+    const urlCount = allMatches(/<loc>\s*([\s\S]*?)\s*<\/loc>/gi, sitemapXml).length;
+    add(urlCount > 0
+      ? { id: 'sitemap', category: 'crawl', severity: 'pass', message: `sitemap.xml lists ${urlCount} URLs.`, evidence: String(urlCount) }
+      : { id: 'sitemap', category: 'crawl', severity: 'warn', message: 'sitemap.xml reachable but lists no <loc> URLs.' });
+  }
+
+  return summarize({ url, finalUrl, status, findings });
+}
+
+function summarize({ url, finalUrl, status, findings }) {
+  const counts = { fail: 0, warn: 0, info: 0, pass: 0 };
+  for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
+
+  const byCategory = {};
+  for (const f of findings) (byCategory[f.category] ||= []).push(f);
+
+  const ranked = [...findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+  const actionable = ranked.filter((f) => f.severity === 'fail' || f.severity === 'warn');
+
+  // Deterministic 0–100 health score: full credit minus weighted penalties.
+  const graded = findings.filter((f) => f.severity !== 'info');
+  const penalty = counts.fail * 3 + counts.warn * 1;
+  const max = graded.length * 3 || 1;
+  const score = Math.max(0, Math.round(100 * (1 - penalty / max)));
+
+  return {
+    url,
+    finalUrl,
+    status,
+    score,
+    counts,
+    diagnosis: buildDiagnosis(actionable, counts),
+    priorityFixes: actionable.slice(0, 10),
+    byCategory,
+    findings: ranked,
+    ignoreList: findings.filter((f) => f.severity === 'pass').map((f) => f.id),
+  };
+}
+
+function buildDiagnosis(actionable, counts) {
+  if (actionable.length === 0) return 'No crawl, index, or render blockers found in the checked set.';
+  const top = actionable[0];
+  const parts = [];
+  if (counts.fail) parts.push(`${counts.fail} blocking issue${counts.fail > 1 ? 's' : ''}`);
+  if (counts.warn) parts.push(`${counts.warn} warning${counts.warn > 1 ? 's' : ''}`);
+  return `${parts.join(' and ')}; start with: ${top.message}`;
+}

package/agent-cores/seo-technical/src/cli.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Real CLI. Two modes:
+//   seo-technical <url>                 live fetch + audit
+//   seo-technical --html <file> [--url] offline audit of a saved page
+// Output: JSON findings on stdout (machine-readable), diagnosis on stderr.
+
+import { readFileSync } from 'node:fs';
+import { auditPage } from './audit.mjs';
+import { fetchPage } from './fetch.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--html') args.html = argv[++i];
+    else if (a === '--url') args.url = argv[++i];
+    else if (a === '--pretty') args.pretty = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  let result;
+
+  if (args.html) {
+    const html = readFileSync(args.html, 'utf8');
+    result = auditPage({ url: args.url ?? null, finalUrl: args.url ?? null, html });
+  } else {
+    const url = args.url ?? args._[0];
+    if (!url) {
+      console.error('Usage: seo-technical <url>   |   seo-technical --html <file> [--url <url>]');
+      process.exitCode = 1;
+      return;
+    }
+    const page = await fetchPage(url);
+    result = auditPage(page);
+  }
+
+  console.error(`seo-technical: ${result.finalUrl ?? result.url ?? '(offline)'} — score ${result.score}/100 — ${result.diagnosis}`);
+  console.log(JSON.stringify(result, null, args.pretty ? 2 : 0));
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});

package/agent-cores/seo-technical/src/fetch.mjs

@@ -0,0 +1,51 @@
+// Live fetch layer. Retrieves a page plus its robots.txt and sitemap.xml so the
+// deterministic audit has real bytes to check. Node 20+ global fetch; no deps.
+
+function originOf(u) {
+  const url = new URL(u);
+  return `${url.protocol}//${url.host}`;
+}
+
+async function tryText(u) {
+  try {
+    const res = await fetch(u, { redirect: 'follow', headers: { 'user-agent': 'agent-cores-seo-technical/0.1 (+audit)' } });
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}
+
+// Manually follow redirects so we can report the chain (fetch collapses it).
+export async function fetchPage(startUrl, { maxHops = 5 } = {}) {
+  const chain = [];
+  let current = startUrl;
+  let res = null;
+  for (let i = 0; i < maxHops; i += 1) {
+    chain.push(current);
+    res = await fetch(current, { redirect: 'manual', headers: { 'user-agent': 'agent-cores-seo-technical/0.1 (+audit)' } });
+    if (res.status >= 300 && res.status < 400) {
+      const loc = res.headers.get('location');
+      if (!loc) break;
+      current = new URL(loc, current).toString();
+      continue;
+    }
+    break;
+  }
+  const html = res ? await res.text() : '';
+  const origin = originOf(current);
+  const [robotsTxt, sitemapXml] = await Promise.all([
+    tryText(`${origin}/robots.txt`),
+    tryText(`${origin}/sitemap.xml`),
+  ]);
+  return {
+    url: startUrl,
+    finalUrl: current,
+    status: res ? res.status : null,
+    redirectChain: chain,
+    headers: res ? Object.fromEntries(res.headers.entries()) : {},
+    html,
+    robotsTxt,
+    sitemapXml,
+  };
+}

package/agent-cores/seo-technical/test/audit.test.mjs

@@ -0,0 +1,73 @@
+// Offline tests — run with `node --test`, zero install. Asserts the auditor detects
+// real, specific problems in a known fixture. If these pass, the core is doing real
+// deterministic work, not echoing a prompt.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { auditPage } from '../src/audit.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const html = readFileSync(join(__dirname, 'fixtures', 'sample.html'), 'utf8');
+
+const byId = (r, id) => r.findings.find((f) => f.id === id);
+
+test('flags noindex as a blocking failure', () => {
+  const r = auditPage({ url: 'https://example.com/', finalUrl: 'https://example.com/', status: 200, html });
+  const f = byId(r, 'meta-robots');
+  assert.ok(f, 'meta-robots finding exists');
+  assert.equal(f.severity, 'fail');
+});
+
+test('detects invalid JSON-LD but still reports the valid block’s types', () => {
+  const r = auditPage({ html });
+  const invalid = byId(r, 'jsonld-invalid');
+  assert.ok(invalid && invalid.severity === 'fail', 'broken JSON-LD flagged as fail');
+  const ok = byId(r, 'jsonld');
+  assert.ok(ok && /Apartment/.test(ok.evidence), 'valid @type surfaced');
+});
+
+test('warns on missing canonical and short meta description', () => {
+  const r = auditPage({ html });
+  assert.equal(byId(r, 'canonical').severity, 'warn');
+  assert.equal(byId(r, 'meta-description').severity, 'warn');
+});
+
+test('passes a good title and single h1', () => {
+  const r = auditPage({ html });
+  assert.equal(byId(r, 'title').severity, 'pass');
+  assert.equal(byId(r, 'h1').severity, 'pass');
+});
+
+test('computes image alt coverage (1 of 2 = 50%)', () => {
+  const r = auditPage({ html });
+  const f = byId(r, 'img-alt');
+  assert.equal(f.severity, 'warn');
+  assert.equal(f.evidence, '50%');
+});
+
+test('robots.txt Disallow: / is a hard failure; sitemap URLs are counted', () => {
+  const r = auditPage({
+    html,
+    robotsTxt: 'User-agent: *\nDisallow: /\nSitemap: https://example.com/sitemap.xml',
+    sitemapXml: '<urlset><url><loc>https://example.com/</loc></url><url><loc>https://example.com/a</loc></url></urlset>',
+  });
+  assert.equal(byId(r, 'robots-txt').severity, 'fail');
+  assert.equal(byId(r, 'sitemap').evidence, '2');
+});
+
+test('score is deterministic and penalizes failures', () => {
+  const r1 = auditPage({ status: 200, finalUrl: 'https://example.com/', html });
+  const r2 = auditPage({ status: 200, finalUrl: 'https://example.com/', html });
+  assert.equal(r1.score, r2.score, 'same input -> same score');
+  assert.ok(r1.score < 100, 'fixture has issues, so score is below 100');
+  assert.ok(r1.score >= 0);
+});
+
+test('diagnosis names the top actionable issue', () => {
+  const r = auditPage({ status: 200, html });
+  assert.match(r.diagnosis, /issue|warning/);
+  assert.ok(r.priorityFixes.length > 0);
+});

package/agent-cores/seo-technical/test/fixtures/sample.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Visconti at Westshore — Apartments in Tampa</title>
+  <meta name="description" content="Too short.">
+  <meta name="robots" content="noindex, follow">
+  <script type="application/ld+json">
+    { "@context": "https://schema.org", "@type": "Apartment", "name": "Visconti at Westshore" }
+  </script>
+  <script type="application/ld+json">
+    { "@type": "LocalBusiness", "name": "broken", }
+  </script>
+</head>
+<body>
+  <h1>Visconti at Westshore</h1>
+  <img src="/a.jpg" alt="Pool">
+  <img src="/b.jpg">
+  <p>Content.</p>
+</body>
+</html>

package/agent-cores/supply-verify/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-cores/supply-verify",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Ad-spend verification engine. Deterministic: parse placement/log-level data, compute MFA/IVT/low-viewability waste and an evidenced exclusion list. No LLM in the core.",
+  "bin": {
+    "supply-verify": "src/cli.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "verify": "node src/cli.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/agent-cores/supply-verify/src/cli.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Real CLI. Reads a placement / log-level report (CSV or JSON) from a file path
+// and prints the deterministic waste report.
+//   supply-verify <file>              audit a CSV or JSON placement report
+//   supply-verify <file> --pretty     pretty-print the JSON
+//   supply-verify <file> --json|--csv force the input format
+// Output: JSON result on stdout (machine-readable); one-line summary on stderr.
+
+import { readFileSync } from 'node:fs';
+import { verifySupply } from './verify.mjs';
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--pretty') args.pretty = true;
+    else if (a === '--json') args.format = 'json';
+    else if (a === '--csv') args.format = 'csv';
+    else if (a === '--needs-data') args.includeNeedsData = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const file = args._[0];
+  if (!file) {
+    console.error('Usage: supply-verify <placements.csv|.json> [--pretty] [--json|--csv] [--needs-data]');
+    process.exitCode = 1;
+    return;
+  }
+  const text = readFileSync(file, 'utf8');
+  const result = verifySupply(text, { format: args.format, includeNeedsData: args.includeNeedsData });
+  console.error(`supply-verify: ${result.summary.placements} placements — $${result.summary.reclaimableSpend} reclaimable — ${result.summary.diagnosis}`);
+  console.log(JSON.stringify(result, null, args.pretty ? 2 : 0));
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+}