lighthouse 13.5.0-dev.20261008 → 13.5.0-dev.20261009

package/core/gather/gatherers/agentic/ard.js

@@ -4,17 +4,112 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @fileoverview Gatherer that discovers and fetches a site's Agentic Resource Discovery (ARD)
+ * manifest. It follows the discovery mechanisms in ARD §5.1 and also consults the predecessor
+ * `ai-catalog` names so that sites that have not yet migrated are still audited.
+ * @see https://agenticresourcediscovery.org/spec/
+ */
+
 import log from 'lighthouse-logger';
 import LinkHeader from 'http-link-header';
 
 import BaseGatherer from '../../base-gatherer.js';
 import RobotsTxt from '../seo/robots-txt.js';
-import {pageFunctions} from '../../../lib/page-functions.js';
-function getAiCatalogLinkInDOM() {
-  const link = document.querySelector('link[rel~="ai-catalog" i]');
-  return link instanceof HTMLLinkElement ? link.href : null;
+
+/**
+ * Link relations for ARD entry sources. `ai-catalog` is the predecessor relation, which
+ * consumers MAY consult but are not required to (ARD §5.1).
+ */
+const REL_ARD = 'ard';
+const REL_LEGACY = 'ai-catalog';
+
+const WELL_KNOWN_PATH = '/.well-known/ard.json';
+const LEGACY_WELL_KNOWN_PATH = '/.well-known/ai-catalog.json';
+
+const HTTP_OK = 200;
+
+/** @typedef {{ard: string|null, legacy: string|null}} ArdLinks */
+
+/** @typedef {LH.Artifacts['AgentResourceDiscovery']['discoverySignals']} DiscoverySignals */
+
+/**
+ * @typedef FetchResult
+ * @property {number|null} status
+ * @property {string|null} content
+ * @property {Record<string, string>|null} headers
+ * @property {string} [errorMessage]
+ */
+
+/**
+ * A location to try when resolving the manifest. `advertised` locations are ones the site
+ * points at (robots.txt, link tags, Link headers); the well-known paths are probed by
+ * Lighthouse, so a failure there is not the site's fault and is not reported.
+ * @typedef ManifestCandidate
+ * @property {LH.Artifacts.ArdDiscoverySource} source
+ * @property {string|null} url
+ * @property {boolean} advertised
+ */
+
+/** @type {ReadonlyArray<LH.Artifacts.ArdDiscoverySource>} */
+const SOURCE_PRIORITY = [
+  'robotsTxtAgentmap',
+  'htmlLink',
+  'httpHeaderLink',
+  'wellKnown',
+  'legacyHtmlLink',
+  'legacyHttpHeaderLink',
+  'legacyWellKnown',
+];
+
+/** @type {Set<LH.Artifacts.ArdDiscoverySource>} */
+const PROBED_SOURCES = new Set(['wellKnown', 'legacyWellKnown']);
+
+/**
+ * @param {DiscoverySignals} discoverySignals
+ * @return {ManifestCandidate[]}
+ */
+function getManifestCandidates(discoverySignals) {
+  return SOURCE_PRIORITY.map(source => ({
+    source,
+    url: discoverySignals[source],
+    advertised: !PROBED_SOURCES.has(source),
+  }));
+}
+
+/**
+ * Resolves `href` against `baseUrl`, returning null for empty or unparseable values.
+ * @param {string|null|undefined} href
+ * @param {string} baseUrl
+ * @return {string|null}
+ */
+function resolveUrl(href, baseUrl) {
+  if (!href) return null;
+  try {
+    return new URL(href, baseUrl).href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Runs in the page. Returns the `href` of the first `<link>` for each relation, or null.
+ * @param {string} relArd
+ * @param {string} relLegacy
+ * @return {ArdLinks}
+ */
+function getArdLinksInDOM(relArd, relLegacy) {
+  /** @param {string} rel */
+  const getHref = rel => {
+    const link = document.querySelector(`link[rel~="${rel}" i]`);
+    return link instanceof HTMLLinkElement ? link.href : null;
+  };
+  return {ard: getHref(relArd), legacy: getHref(relLegacy)};
 }
 
+/** @type {ArdLinks} */
+const NO_LINKS = {ard: null, legacy: null};
+
 class AgentResourceDiscovery extends BaseGatherer {
   /** @type {LH.Gatherer.GathererMeta<'RobotsTxt'>} */
   meta = {
@@ -23,6 +118,7 @@ class AgentResourceDiscovery extends BaseGatherer {
   };
 
   /**
+   * Returns the absolute URL from the first `Agentmap:` directive in robots.txt, if any.
    * @param {LH.Artifacts['RobotsTxt']|null|undefined} robotsTxt
    * @param {string} finalDisplayedUrl
    * @return {string|null}
@@ -31,93 +127,159 @@ class AgentResourceDiscovery extends BaseGatherer {
     if (!robotsTxt?.content) return null;
     const match = robotsTxt.content.match(/^\s*Agentmap:\s*(\S+)/im);
     if (!match) return null;
-    try {
-      return new URL(match[1], finalDisplayedUrl).href;
-    } catch {
-      return null;
-    }
+    return resolveUrl(match[1], finalDisplayedUrl);
   }
 
   /**
+   * Finds `<link rel="ard">` and `<link rel="ai-catalog">` in the page.
    * @param {LH.Gatherer.Context} context
    * @param {string} finalDisplayedUrl
-   * @return {Promise<string|null>}
+   * @return {Promise<ArdLinks>}
    */
-  static async getHtmlLinkFromDom(context, finalDisplayedUrl) {
+  static async getHtmlLinksFromDom(context, finalDisplayedUrl) {
     try {
-      const href = await context.driver.executionContext.evaluate(getAiCatalogLinkInDOM, {
-        args: [],
+      const links = await context.driver.executionContext.evaluate(getArdLinksInDOM, {
+        args: [REL_ARD, REL_LEGACY],
         useIsolation: true,
-        deps: [pageFunctions.getNodeDetails],
       });
-      if (!href) return null;
-      return new URL(href, finalDisplayedUrl).href;
-    } catch {
-      return null;
+      return {
+        ard: resolveUrl(links?.ard, finalDisplayedUrl),
+        legacy: resolveUrl(links?.legacy, finalDisplayedUrl),
+      };
+    } catch (err) {
+      log.verbose('AgentResourceDiscovery', `Could not read link tags: ${err.message}`);
+      return NO_LINKS;
     }
   }
 
   /**
+   * Finds `rel="ard"` and `rel="ai-catalog"` in the main document's HTTP `Link` header.
    * @param {LH.Gatherer.Context} context
    * @param {string} finalDisplayedUrl
-   * @return {Promise<string|null>}
+   * @return {Promise<ArdLinks>}
    */
-  static async getHttpHeaderLink(context, finalDisplayedUrl) {
-    // Only check in navigation mode
-    if (context.gatherMode !== 'navigation') return null;
+  static async getHttpHeaderLinks(context, finalDisplayedUrl) {
+    if (context.gatherMode !== 'navigation') return NO_LINKS;
 
     try {
       const mainResourceResponse = await context.driver.fetcher.fetchResource(finalDisplayedUrl);
-      const linkHeader = mainResourceResponse.headers?.['link'];
-      if (!linkHeader) return null;
+      const linkHeader = mainResourceResponse.headers?.link;
+      if (!linkHeader) return NO_LINKS;
+
+      const parsed = LinkHeader.parse(linkHeader.replace(/\n/g, ','));
+      /** @param {string} rel */
+      const getUri = rel =>
+        resolveUrl(parsed.refs.find(ref => ref.rel?.toLowerCase() === rel)?.uri, finalDisplayedUrl);
+      return {ard: getUri(REL_ARD), legacy: getUri(REL_LEGACY)};
+    } catch (err) {
+      log.verbose('AgentResourceDiscovery', `Could not read Link header: ${err.message}`);
+      return NO_LINKS;
+    }
+  }
+
+  /**
+   * Fetches a candidate manifest URL. Never throws; network errors are returned as a
+   * null status with an `errorMessage`.
+   * @param {LH.Gatherer.Context} context
+   * @param {string} url
+   * @return {Promise<FetchResult>}
+   */
+  static async fetchManifest(context, url) {
+    try {
+      const {status, content, headers} = await context.driver.fetcher.fetchResource(url);
+      return {status, content, headers: headers || null};
+    } catch (err) {
+      log.error('AgentResourceDiscovery', err);
+      return {status: null, content: null, headers: null, errorMessage: err.message};
+    }
+  }
 
-      const parsed = LinkHeader.parse(linkHeader);
-      const aiCatalogRef = parsed.get('rel', 'ai-catalog')[0];
-      if (!aiCatalogRef?.uri) return null;
+  /**
+   * Tries each candidate in order and returns the first that loads. Advertised candidates
+   * that fail are recorded in `failedSources` and skipped. If nothing loads, the result
+   * describes the first advertised location that failed, or else the `/.well-known/ard.json`
+   * path consumers are required to fetch.
+   * @param {LH.Gatherer.Context} context
+   * @param {ManifestCandidate[]} candidates
+   * @return {Promise<{
+   *   discoverySource: LH.Artifacts.ArdDiscoverySource,
+   *   catalogUrl: string,
+   *   fetchResult: FetchResult,
+   *   failedSources: LH.Artifacts['AgentResourceDiscovery']['failedSources'],
+   * }>}
+   */
+  static async resolveManifest(context, candidates) {
+    /** @type {Array<{source: LH.Artifacts.ArdDiscoverySource, url: string, advertised: boolean, fetchResult: FetchResult}>} */
+    const attempts = [];
+    const failedSources = () => attempts
+      .filter(attempt => attempt.advertised)
+      .map(({source, url, fetchResult}) => ({
+        source,
+        url,
+        status: fetchResult.status,
+        errorMessage: fetchResult.errorMessage,
+      }));
+
+    for (const {source, url, advertised} of candidates) {
+      if (!url || attempts.some(attempt => attempt.url === url)) continue;
 
-      return new URL(aiCatalogRef.uri, finalDisplayedUrl).href;
-    } catch {
-      return null;
+      const fetchResult = await AgentResourceDiscovery.fetchManifest(context, url);
+      if (fetchResult.status === HTTP_OK && fetchResult.content) {
+        return {discoverySource: source, catalogUrl: url, fetchResult,
+          failedSources: failedSources()};
+      }
+      attempts.push({source, url, advertised, fetchResult});
     }
+
+    const fallback = attempts.find(attempt => attempt.advertised) ||
+      attempts.find(attempt => attempt.source === 'wellKnown');
+    if (!fallback) throw new Error('ARD discovery attempted no candidates');
+
+    return {
+      discoverySource: fallback.source,
+      catalogUrl: fallback.url,
+      fetchResult: fallback.fetchResult,
+      failedSources: failedSources(),
+    };
   }
 
   /**
+   * Resolves the manifest following ARD §5.1: explicit ARD signals first, then the
+   * `/.well-known/ard.json` path consumers MUST fetch, and only then the predecessor
+   * `ai-catalog` relation and well-known path, which consumers MAY consult.
    * @param {LH.Gatherer.Context<'RobotsTxt'>} context
    * @return {Promise<LH.Artifacts['AgentResourceDiscovery']>}
    */
   async getArtifact(context) {
     const {finalDisplayedUrl} = context.baseArtifacts.URL;
-    const robotsTxt = context.dependencies.RobotsTxt;
     const robotsTxtAgentmap = AgentResourceDiscovery.getRobotsTxtAgentmap(
-      robotsTxt, finalDisplayedUrl);
-    const [htmlLink, httpHeaderLink] = await Promise.all([
-      AgentResourceDiscovery.getHtmlLinkFromDom(context, finalDisplayedUrl),
-      AgentResourceDiscovery.getHttpHeaderLink(context, finalDisplayedUrl),
+      context.dependencies.RobotsTxt, finalDisplayedUrl);
+    const [htmlLinks, httpHeaderLinks] = await Promise.all([
+      AgentResourceDiscovery.getHtmlLinksFromDom(context, finalDisplayedUrl),
+      AgentResourceDiscovery.getHttpHeaderLinks(context, finalDisplayedUrl),
     ]);
-    const wellKnown = new URL('/.well-known/ai-catalog.json', finalDisplayedUrl).href;
-    const catalogUrl = robotsTxtAgentmap || htmlLink || httpHeaderLink || wellKnown;
-
-    /** @type {string|undefined} */
-    let errorMessage;
-    const fetchResult = await context.driver.fetcher.fetchResource(catalogUrl)
-      .catch(err => {
-        log.error('AgentResourceDiscovery', err);
-        errorMessage = err.message;
-        return {status: null, content: null, headers: null};
-      });
+
+    /** @type {DiscoverySignals} */
+    const discoverySignals = {
+      robotsTxtAgentmap,
+      htmlLink: htmlLinks.ard,
+      httpHeaderLink: httpHeaderLinks.ard,
+      legacyHtmlLink: htmlLinks.legacy,
+      legacyHttpHeaderLink: httpHeaderLinks.legacy,
+      wellKnown: new URL(WELL_KNOWN_PATH, finalDisplayedUrl).href,
+      legacyWellKnown: new URL(LEGACY_WELL_KNOWN_PATH, finalDisplayedUrl).href,
+    };
+
+    const candidates = getManifestCandidates(discoverySignals);
+    const {discoverySource, catalogUrl, fetchResult, failedSources} =
+      await AgentResourceDiscovery.resolveManifest(context, candidates);
 
     return {
-      status: fetchResult.status,
-      content: fetchResult.content,
-      headers: fetchResult.headers || null,
+      ...fetchResult,
       catalogUrl,
-      discoverySignals: {
-        robotsTxtAgentmap,
-        htmlLink,
-        httpHeaderLink,
-        wellKnown,
-      },
-      errorMessage,
+      discoverySource,
+      discoverySignals,
+      failedSources,
     };
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lighthouse",
   "type": "module",
-  "version": "13.5.0-dev.20261008",
+  "version": "13.5.0-dev.20261009",
   "description": "Automated auditing, performance metrics, and best practices for the web.",
   "main": "./core/index.js",
   "bin": {
@@ -38,6 +38,7 @@
     "clean": "rm -r dist proto/scripts/*.json proto/scripts/*_pb2.* proto/scripts/*_pb.* proto/scripts/__pycache__ proto/scripts/*.pyc *.report.html *.report.dom.html *.report.json *.devtoolslog.json *.trace.json shared/localization/locales/*.ctc.json || true",
     "clean-types": "git clean -xfq '*.d.ts' '*.d.cts' -e 'node_modules/' -e 'dist/' -e '.tmp/' -e '**/types/'",
     "lint": "[ \"$CI\" = true ] && eslint --quiet -f codeframe . || eslint .",
+    "zizmor": "uvx zizmor@1.25.2 --gh-token=\"$(gh auth token)\" .github/workflows",
     "smoke": "node -r source-map-support/register cli/test/smokehouse/frontends/smokehouse-bin.js",
     "debug": "node --inspect-brk ./cli/index.js",
     "start": "yarn build-report --standalone && node ./cli/index.js",
@@ -53,14 +54,13 @@
     "test-proto": "yarn compile-proto && yarn build-proto-roundtrip",
     "unit-core": "yarn mocha core",
     "unit-cli": "yarn mocha --testMatch cli/**/*-test.js",
-    "unit-lantern-trace": "INTERNAL_LANTERN_USE_TRACE=1 yarn mocha core/test/computed/metrics core/test/audits",
+    "unit-lantern-trace": "INTERNAL_LANTERN_USE_TRACE=1 yarn mocha core/test/computed/metrics core/test/computed/page-dependency-graph-test.js core/test/computed/tbt-impact-tasks-test.js core/test/audits",
     "unit-report": "yarn mocha --testMatch report/**/*-test.js",
     "unit-treemap": "yarn mocha --testMatch treemap/**/*-test.js",
     "unit-viewer": "yarn mocha --testMatch viewer/**/*-test.js",
     "unit-flow": "bash flow-report/test/run-flow-report-tests.sh",
     "unit": "yarn unit-flow && yarn mocha && yarn unit-lantern-trace",
     "unit:ci": "NODE_OPTIONS=--max-old-space-size=8192 npm run unit",
-    "unit-lantern-trace:ci": "NODE_OPTIONS=--max-old-space-size=8192 npm run unit-lantern-trace",
     "core-unit": "yarn unit-core",
     "cli-unit": "yarn unit-cli",
     "viewer-unit": "yarn unit-viewer",
@@ -71,7 +71,6 @@
     "deploy-treemap": "yarn build-treemap --deploy",
     "deploy-viewer": "yarn build-viewer --deploy",
     "vercel-build": "yarn build-sample-reports && yarn build-viewer && yarn build-treemap",
-    "dogfood-lhci": "./core/scripts/dogfood-lhci.sh",
     "timing-trace": "node core/scripts/generate-timing-trace.js",
     "changelog": "conventional-changelog --config ./build/changelog-generator/index.cjs --infile changelog.md --same-file",
     "type-check": "tsc --build ./tsconfig-all.json",
@@ -111,7 +110,7 @@
     "@jest/fake-timers": "^29.7.0",
     "@testing-library/preact": "^3.1.1",
     "@testing-library/preact-hooks": "^1.1.0",
-    "@types/archiver": "^2.1.2",
+    "@types/archiver": "^8.0.0",
     "@types/chrome": "^0.1.42",
     "@types/configstore": "^6.0.2",
     "@types/cpy": "^5.1.0",
@@ -138,7 +137,7 @@
     "@typescript-eslint/parser": "^8.60.1",
     "acorn": "^8.5.0",
     "angular": "^1.7.4",
-    "archiver": "^7.0.1",
+    "archiver": "^8.0.0",
     "builtin-modules": "^3.3.0",
     "chalk": "^2.4.1",
     "chrome-devtools-frontend": "1.0.1705227",

package/shared/localization/locales/en-US.json

@@ -624,19 +624,28 @@
     "message": "Severity"
   },
   "core/audits/agentic/ard-schema.js | description": {
-    "message": "Valid `ai-catalog.json` manifests are required for autonomous AI agents and registries to discover and verify your resources. [Learn more about the ARD specification](https://agenticresourcediscovery.org/spec/)."
+    "message": "A valid Agentic Resource Discovery (ARD) manifest, served at `/.well-known/ard.json` or linked with `rel=\"ard\"`, lets AI agents and registries discover and verify your resources. [Learn more about the ARD specification](https://agenticresourcediscovery.org/spec/)."
   },
   "core/audits/agentic/ard-schema.js | explanation": {
-    "message": "Catalog file could not be loaded for schema validation."
+    "message": "ARD manifest could not be loaded for schema validation."
   },
   "core/audits/agentic/ard-schema.js | failureTitle": {
-    "message": "`ai-catalog.json` schema is invalid"
+    "message": "ARD manifest is invalid"
   },
   "core/audits/agentic/ard-schema.js | itemSeverityError": {
     "message": "Error"
   },
+  "core/audits/agentic/ard-schema.js | legacyDiscovery": {
+    "message": "Manifest was only found through a legacy location (`/.well-known/ai-catalog.json` or `rel=\"ai-catalog\"`). ARD consumers are not required to check these, so ARD consumers may not discover your resources. Serve the manifest at `/.well-known/ard.json` or link it with `rel=\"ard\"`."
+  },
+  "core/audits/agentic/ard-schema.js | sourceFetchFailed": {
+    "message": "Advertised ARD manifest location could not be loaded."
+  },
+  "core/audits/agentic/ard-schema.js | sourceUnavailable": {
+    "message": "Advertised ARD manifest location could not be loaded (HTTP status {statusCode})."
+  },
   "core/audits/agentic/ard-schema.js | title": {
-    "message": "`ai-catalog.json` schema is valid"
+    "message": "ARD manifest is valid"
   },
   "core/audits/agentic/llms-txt.js | description": {
     "message": "If your llms.txt file does not follow recommendations, large language models may not be able to understand how you want your website to be crawled or used for training. The [llms.txt](https://llmstxt.org/) file should be a Markdown file containing at least one H1 header. [Learn more about the llms.txt audit](https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt)."

package/shared/localization/locales/en-XL.json

@@ -624,19 +624,28 @@
     "message": "Ŝév̂ér̂ít̂ý"
   },
   "core/audits/agentic/ard-schema.js | description": {
-    "message": "V̂ál̂íd̂ `ai-catalog.json` ḿâńîf́êśt̂ś âŕê ŕêq́ûír̂éd̂ f́ôŕ âút̂ón̂óm̂óûś ÂÍ âǵêńt̂ś âńd̂ ŕêǵîśt̂ŕîéŝ t́ô d́îśĉóv̂ér̂ án̂d́ v̂ér̂íf̂ý ŷóûŕ r̂éŝóûŕĉéŝ. [Ĺêár̂ń m̂ór̂é âb́ôút̂ t́ĥé ÂŔD̂ śp̂éĉíf̂íĉát̂íôń](https://agenticresourcediscovery.org/spec/)."
+    "message": "Â v́âĺîd́ Âǵêńt̂íĉ Ŕêśôúr̂ćê D́îśĉóv̂ér̂ý (ÂŔD̂) ḿâńîf́êśt̂, śêŕv̂éd̂ át̂ `/.well-known/ard.json` ór̂ ĺîńk̂éd̂ ẃît́ĥ `rel=\"ard\"`, ĺêt́ŝ ÁÎ áĝén̂t́ŝ án̂d́ r̂éĝíŝt́r̂íêś d̂íŝćôv́êŕ âńd̂ v́êŕîf́ŷ ýôúr̂ ŕêśôúr̂ćêś. [L̂éâŕn̂ ḿôŕê áb̂óût́ t̂h́ê ÁR̂D́ ŝṕêćîf́îćât́îón̂](https://agenticresourcediscovery.org/spec/)."
   },
   "core/audits/agentic/ard-schema.js | explanation": {
-    "message": "Ĉát̂ál̂óĝ f́îĺê ćôúl̂d́ n̂ót̂ b́ê ĺôád̂éd̂ f́ôŕ ŝćĥém̂á v̂ál̂íd̂át̂íôń."
+    "message": "ÂŔD̂ ḿâńîf́êśt̂ ćôúl̂d́ n̂ót̂ b́ê ĺôád̂éd̂ f́ôŕ ŝćĥém̂á v̂ál̂íd̂át̂íôń."
   },
   "core/audits/agentic/ard-schema.js | failureTitle": {
-    "message": "`ai-catalog.json` ŝćĥém̂á îś îńv̂ál̂íd̂"
+    "message": "ÂŔD̂ ḿâńîf́êśt̂ íŝ ín̂v́âĺîd́"
   },
   "core/audits/agentic/ard-schema.js | itemSeverityError": {
     "message": "Êŕr̂ór̂"
   },
+  "core/audits/agentic/ard-schema.js | legacyDiscovery": {
+    "message": "M̂án̂íf̂éŝt́ ŵáŝ ón̂ĺŷ f́ôún̂d́ t̂h́r̂óûǵĥ á l̂éĝáĉý l̂óĉát̂íôń (`/.well-known/ai-catalog.json` ôŕ `rel=\"ai-catalog\"`). ÂŔD̂ ćôńŝúm̂ér̂ś âŕê ńôt́ r̂éq̂úîŕêd́ t̂ó ĉh́êćk̂ t́ĥéŝé, ŝó ÂŔD̂ ćôńŝúm̂ér̂ś m̂áŷ ńôt́ d̂íŝćôv́êŕ ŷóûŕ r̂éŝóûŕĉéŝ. Śêŕv̂é t̂h́ê ḿâńîf́êśt̂ át̂ `/.well-known/ard.json` ór̂ ĺîńk̂ ít̂ ẃît́ĥ `rel=\"ard\"`."
+  },
+  "core/audits/agentic/ard-schema.js | sourceFetchFailed": {
+    "message": "Âd́v̂ér̂t́îśêd́ ÂŔD̂ ḿâńîf́êśt̂ ĺôćât́îón̂ ćôúl̂d́ n̂ót̂ b́ê ĺôád̂éd̂."
+  },
+  "core/audits/agentic/ard-schema.js | sourceUnavailable": {
+    "message": "Âd́v̂ér̂t́îśêd́ ÂŔD̂ ḿâńîf́êśt̂ ĺôćât́îón̂ ćôúl̂d́ n̂ót̂ b́ê ĺôád̂éd̂ (H́T̂T́P̂ śt̂át̂úŝ {statusCode})."
+  },
   "core/audits/agentic/ard-schema.js | title": {
-    "message": "`ai-catalog.json` ŝćĥém̂á îś v̂ál̂íd̂"
+    "message": "ÂŔD̂ ḿâńîf́êśt̂ íŝ v́âĺîd́"
   },
   "core/audits/agentic/llms-txt.js | description": {
     "message": "Îf́ ŷóûŕ l̂ĺm̂ś.t̂x́t̂ f́îĺê d́ôéŝ ńôt́ f̂ól̂ĺôẃ r̂éĉóm̂ḿêńd̂át̂íôńŝ, ĺâŕĝé l̂án̂ǵûáĝé m̂ód̂él̂ś m̂áŷ ńôt́ b̂é âb́l̂é t̂ó ûńd̂ér̂śt̂án̂d́ ĥóŵ ýôú ŵán̂t́ ŷóûŕ ŵéb̂śît́ê t́ô b́ê ćr̂áŵĺêd́ ôŕ ûśêd́ f̂ór̂ t́r̂áîńîńĝ. T́ĥé [l̂ĺm̂ś.t̂x́t̂](https://llmstxt.org/) f́îĺê śĥóûĺd̂ b́ê á M̂ár̂ḱd̂óŵń f̂íl̂é ĉón̂t́âín̂ín̂ǵ ât́ l̂éâśt̂ ón̂é Ĥ1 h́êád̂ér̂. [Ĺêár̂ń m̂ór̂é âb́ôút̂ t́ĥé l̂ĺm̂ś.t̂x́t̂ áûd́ît́](https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt)."

package/third-party/ard/README.md

@@ -5,23 +5,32 @@ This is a JavaScript port of the Agentic Resource Discovery (ARD) Conformance Te
 The original Python script is located in the `ards-project/ard-spec` repository:
 - **Upstream Repository**: https://github.com/ards-project/ard-spec
 - **Source Script**: `conformance/bin/conformance-test`
-- **Schema**: `spec/schemas/ai-catalog.schema.json`
+- **Schema**: `spec/schemas/ard-entry.schema.json` (`$defs/ArdManifest` and `$defs/ArdEntry`)
 - **Pinned Commit SHA**: `b76f235a8f461876ad4f1e77abd0eb0eb302b48d`
+- **Reviewed Upstream Files** (SHA-256 of the upstream content the port was last verified against; maintained by `yarn update:ard-spec --ack-port`, do not edit by hand):
+  - `conformance/bin/conformance-test`: `ac2f3cae1c4ac75261fe45786a117aaad275322c92b74110529ad03a794275b4`
+  - `spec/ard.md`: `6deb2cc58216fb279569d8ff61bd4595ccdf6ceaeef6766a1a1c9f25b6b68a62`
 
 ## Modifications for Lighthouse:
 While the validation rules and test suite maintain 1:1 parity with the reference suite, the following adaptations were made for Lighthouse integration:
-- **Structured Error Return:** `ConformanceTester` stores structured objects (`{ element, message }`) in `errors` and `warnings` instead of formatted ANSI CLI strings.
-- **Precompiled Standalone Validator (`schema-validator.js`):** Uses `build/build-ard-schema.js` (`yarn build-ard-schema`) to precompile `ai-catalog.schema.json` into a pure, standalone JavaScript validator (`schema-validator.js`) ahead of time using `Ajv2020` and `ajv/dist/standalone`. This eliminates runtime dynamic compilation (`new Function()` / `eval()`), preventing Content Security Policy (CSP) `unsafe-eval` violations when running inside Chrome DevTools frontend, avoiding runtime `fs.readFileSync` calls in browser/bundled contexts, and keeping `Ajv` out of the client bundle.
+- **Structured Error Return:** `ConformanceTester` stores structured objects (`{ element, message }`) in `errors`, `warnings` and `infos` instead of formatted ANSI CLI strings. The `[label]` prefix upstream puts on entry messages is reported as `element` instead.
+- **Precompiled Standalone Validator (`schema-validator.js`):** Uses `build/build-ard-schema.js` (`yarn build-ard-schema`) to precompile the `ArdManifest` and `ArdEntry` definitions of `ard-entry.schema.json` into a pure, standalone JavaScript module (`schema-validator.js`) ahead of time using `Ajv2020` and `ajv/dist/standalone`. This eliminates runtime dynamic compilation (`new Function()` / `eval()`), preventing Content Security Policy (CSP) `unsafe-eval` violations when running inside Chrome DevTools frontend, avoiding runtime `fs.readFileSync` calls in browser/bundled contexts, and keeping `Ajv` out of the client bundle.
 - **ESM Format Validation:** Imports `uri` and `date-time` format validators statically from `ajv-formats/dist/formats.js` rather than bundling the full `ajv-formats` dynamic plugin.
+- **Schema Error Messages:** Ajv reports different messages than Python's `jsonschema`. The first error not nested inside a `oneOf`/`anyOf` branch is reported, with `'x' is a required property` phrasing kept for `required` errors.
+- **Non-object Input:** Upstream assumes the manifest root and each entry are JSON objects. The port treats anything else as empty, so it reports errors instead of throwing.
 - **Lighthouse Logger:** Replaced raw `console.log` with `lighthouse-logger`.
 
+Publisher resolution (upstream's `resolve_publisher`, spec §5.1) is implemented by the gatherer in `core/gather/gatherers/agentic/ard.js`, and the resulting legacy-location warning by the `ard-schema` audit. `infos` are not surfaced in the audit.
+
 ## Updating Conformance Script
 
-Upstream schema and conformance test synchronization is checked regularly during dependency upgrades (via `core/scripts/upgrade-deps.sh`) and monitored weekly via CI (`.github/workflows/cron-weekly.yml` with `node core/scripts/update-ard-spec.js --check`).
+`yarn check:ard-spec` (`core/scripts/update-ard-spec.js --check`) compares upstream `main` against what Lighthouse has: the vendored schema must match byte-for-byte, and the hand-ported files must match the **Reviewed Upstream Files** hashes above. It runs weekly in CI (`.github/workflows/cron-weekly.yml`) and during dependency upgrades (`core/scripts/upgrade-deps.sh`). Neither of those can mark upstream changes as handled; only `--ack-port` does.
 
-When upstream changes are detected:
-1. Run `yarn update:ard-spec` to fetch the latest `ai-catalog.schema.json` and bump the pinned commit SHA.
-2. Review the printed diff of `conformance/bin/conformance-test` and adapt `third-party/ard/ard.js` to match any updated validation rules.
-3. Run `yarn build-ard-schema` to regenerate the standalone validator (`schema-validator.js`).
-4. Run `yarn mocha third-party/ard/ard-test.js` to verify test conformance.
+When it reports changes (the `update-ard-port` agent skill walks through this in detail):
+1. Run `yarn update:ard-spec`. This syncs `ard-entry.schema.json` verbatim and prints the upstream `conformance-test` diff. If a hand-ported file changed, it exits 1 **without** bumping the pinned SHA.
+2. Port `conformance/bin/conformance-test` changes into `third-party/ard/ard.js` (keep rules, severities and message text 1:1; see modifications above) and update `third-party/ard/ard-test.js`.
+3. If `spec/ard.md` changed, check §5.1 (Discovery Mechanisms) against `core/gather/gatherers/agentic/ard.js`.
+4. If the schema changed, run `yarn build-ard-schema` to regenerate `schema-validator.js`.
+5. Verify: `yarn mocha third-party/ard/ard-test.js core/test/gather/gatherers/agentic/ard-test.js core/test/audits/agentic/ard-schema-test.js` and `yarn smoke ard ardInvalid`.
+6. Run `yarn update:ard-spec --ack-port` to record the reviewed hashes and bump the pinned SHA. `yarn check:ard-spec` should now pass.