From b046a4ab53ff333d08de43c855e9ca8baf893501 Mon Sep 17 00:00:00 2001
From: IISweetHeartII <sachi009955@gmail.com>
Date: Thu, 19 Feb 2026 23:45:46 +0900
Subject: [PATCH] feat: implement Phase 1 gatherers, audits, and runner
 pipeline (#38)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add complete Gather → Audit → Score pipeline:

Gatherers (3):
- HttpGatherer: parallel fetch of 6 well-known files
- HtmlGatherer: regex-based extraction of JSON-LD, meta tags, semantic HTML
- ApiGatherer: OpenAPI spec analysis, header/auth/rate-limit detection

Audits (19):
- Discovery: llms-txt, openapi-spec, robots-ai, ai-plugin, schema-org
- API Quality: openapi-valid, response-format, response-examples, content-negotiation
- Structured Data: json-ld, meta-tags, semantic-html
- Auth & Onboarding: self-service-auth, no-captcha
- Error Handling: error-codes, rate-limit-headers, retry-after
- Documentation: machine-readable-docs, sdk-available

Runner: orchestrates two-pass gathering (HTTP first, then derived
HTML+API), executes all audits with error resilience, and feeds
results into the existing scoring engine.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 src/audits/ai-plugin.ts             |  75 ++++++++++++++
 src/audits/content-negotiation.ts   |  68 +++++++++++++
 src/audits/error-codes.ts           |  43 ++++++++
 src/audits/index.ts                 |  31 ++++++
 src/audits/json-ld.ts               |  56 +++++++++++
 src/audits/llms-txt.ts              |  49 +++++++++
 src/audits/machine-readable-docs.ts |  44 ++++++++
 src/audits/meta-tags.ts             |  69 +++++++++++++
 src/audits/no-captcha.ts            |  42 ++++++++
 src/audits/openapi-spec.ts          |  59 +++++++++++
 src/audits/openapi-valid.ts         |  85 ++++++++++++++++
 src/audits/rate-limit-headers.ts    |  49 +++++++++
 src/audits/response-examples.ts     |  49 +++++++++
 src/audits/response-format.ts       |  41 ++++++++
 src/audits/retry-after.ts           |  43 ++++++++
 src/audits/robots-ai.ts             | 124 +++++++++++++++++++++++
 src/audits/schema-org.ts            |  63 ++++++++++++
 src/audits/sdk-available.ts         |  43 ++++++++
 src/audits/self-service-auth.ts     |  42 ++++++++
 src/audits/semantic-html.ts         |  61 +++++++++++
 src/gatherers/api-gatherer.ts       | 150 ++++++++++++++++++++++++++++
 src/gatherers/base-gatherer.ts      |   8 +-
 src/gatherers/html-gatherer.ts      | 124 +++++++++++++++++++++++
 src/gatherers/http-gatherer.ts      | 113 +++++++++++++++++++++
 src/gatherers/index.ts              |   9 ++
 src/index.ts                        |  26 ++++-
 src/runner.ts                       | 110 +++++++++++++++++++-
 27 files changed, 1670 insertions(+), 6 deletions(-)
 create mode 100644 src/audits/ai-plugin.ts
 create mode 100644 src/audits/content-negotiation.ts
 create mode 100644 src/audits/error-codes.ts
 create mode 100644 src/audits/json-ld.ts
 create mode 100644 src/audits/llms-txt.ts
 create mode 100644 src/audits/machine-readable-docs.ts
 create mode 100644 src/audits/meta-tags.ts
 create mode 100644 src/audits/no-captcha.ts
 create mode 100644 src/audits/openapi-spec.ts
 create mode 100644 src/audits/openapi-valid.ts
 create mode 100644 src/audits/rate-limit-headers.ts
 create mode 100644 src/audits/response-examples.ts
 create mode 100644 src/audits/response-format.ts
 create mode 100644 src/audits/retry-after.ts
 create mode 100644 src/audits/robots-ai.ts
 create mode 100644 src/audits/schema-org.ts
 create mode 100644 src/audits/sdk-available.ts
 create mode 100644 src/audits/self-service-auth.ts
 create mode 100644 src/audits/semantic-html.ts
 create mode 100644 src/gatherers/api-gatherer.ts
 create mode 100644 src/gatherers/html-gatherer.ts
 create mode 100644 src/gatherers/http-gatherer.ts

diff --git a/src/audits/ai-plugin.ts b/src/audits/ai-plugin.ts
new file mode 100644
index 0000000..78fbf8f
--- /dev/null
+++ b/src/audits/ai-plugin.ts
@@ -0,0 +1,75 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HttpGatherResult } from '../gatherers/http-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks whether the site exposes an AI plugin manifest at
+ * `/.well-known/ai-plugin.json`.
+ *
+ * The ai-plugin.json manifest is the OpenAI ChatGPT plugin standard
+ * and enables AI platforms to discover and integrate with the site.
+ */
+export class AiPluginAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'ai-plugin',
+    title: 'Site provides an ai-plugin.json manifest',
+    failureTitle: 'Site does not provide an ai-plugin.json manifest',
+    description:
+      'An ai-plugin.json manifest at /.well-known/ai-plugin.json enables AI platforms ' +
+      '(such as ChatGPT plugins) to discover and interact with the site.',
+    requiredGatherers: ['http'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const http = artifacts['http'] as HttpGatherResult;
+    const aiPlugin = http.aiPlugin;
+
+    if (!aiPlugin.found) {
+      return this.fail({
+        type: 'text',
+        summary: 'No /.well-known/ai-plugin.json file was found at the target URL.',
+      });
+    }
+
+    const content = (aiPlugin.content ?? '').trim();
+
+    if (content.length === 0) {
+      return this.fail({
+        type: 'text',
+        summary: 'An ai-plugin.json file was found but it is empty.',
+      });
+    }
+
+    // Validate that it is parseable JSON
+    try {
+      const manifest = JSON.parse(content) as Record<string, unknown>;
+
+      // Basic structural validation: check for expected fields
+      const hasRequiredFields =
+        typeof manifest.schema_version === 'string' &&
+        typeof manifest.name_for_human === 'string' &&
+        typeof manifest.name_for_model === 'string';
+
+      if (!hasRequiredFields) {
+        return this.partial(0.5, {
+          type: 'text',
+          summary:
+            'An ai-plugin.json file was found with valid JSON, but it is missing ' +
+            'expected fields (schema_version, name_for_human, name_for_model).',
+        });
+      }
+
+      return this.pass({
+        type: 'text',
+        summary: `Found a valid ai-plugin.json manifest for "${String(manifest.name_for_human)}".`,
+      });
+    } catch {
+      return this.fail({
+        type: 'text',
+        summary: 'An ai-plugin.json file was found but it contains invalid JSON.',
+      });
+    }
+  }
+}
diff --git a/src/audits/content-negotiation.ts b/src/audits/content-negotiation.ts
new file mode 100644
index 0000000..2c01bcb
--- /dev/null
+++ b/src/audits/content-negotiation.ts
@@ -0,0 +1,68 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HttpGatherResult } from '../gatherers/http-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks whether the site returns proper content-type headers and
+ * supports JSON-based content negotiation.
+ *
+ * Proper content-type headers and accept-header support enable AI agents
+ * to negotiate the most suitable response format.
+ */
+export class ContentNegotiationAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'content-negotiation',
+    title: 'Site supports proper content negotiation',
+    failureTitle: 'Site does not support proper content negotiation',
+    description:
+      'Proper content-type headers and support for JSON content negotiation ' +
+      'enable AI agents to request and receive data in the most suitable format.',
+    requiredGatherers: ['http'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const http = artifacts['http'] as HttpGatherResult;
+    const headers = http.headers;
+
+    const contentType = headers['content-type'] ?? '';
+
+    // Check that a content-type header is present at all
+    if (!contentType) {
+      return this.fail({
+        type: 'text',
+        summary:
+          'The site does not return a content-type header. ' +
+          'AI agents need content-type headers to correctly parse responses.',
+      });
+    }
+
+    // Check for JSON support indicators
+    const hasJsonSupport =
+      contentType.includes('application/json') ||
+      headers['accept']?.includes('application/json') ||
+      // Vary: Accept header indicates the server performs content negotiation
+      (headers['vary'] ?? '').toLowerCase().includes('accept');
+
+    if (hasJsonSupport) {
+      return this.pass({
+        type: 'table',
+        summary: 'The site returns proper content-type headers and supports JSON.',
+        items: [
+          { header: 'content-type', value: contentType },
+          ...(headers['vary'] ? [{ header: 'vary', value: headers['vary'] }] : []),
+        ],
+      });
+    }
+
+    // The site has a content-type header but no JSON support signals
+    return this.fail({
+      type: 'table',
+      summary:
+        'The site returns a content-type header but does not indicate JSON support. ' +
+        'Consider supporting application/json for AI agent consumption.',
+      items: [{ header: 'content-type', value: contentType }],
+    });
+  }
+}
diff --git a/src/audits/error-codes.ts b/src/audits/error-codes.ts
new file mode 100644
index 0000000..7e79892
--- /dev/null
+++ b/src/audits/error-codes.ts
@@ -0,0 +1,43 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks if the API uses structured error codes.
+ * Structured error responses (with code, message, and error fields) help AI agents
+ * programmatically handle failures and implement retry/recovery logic.
+ */
+export class ErrorCodesAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'error-codes',
+    title: 'API uses structured error codes',
+    failureTitle: 'API lacks structured error codes',
+    description:
+      'Structured error codes (e.g., {"error": "...", "code": "...", "message": "..."}) ' +
+      'allow AI agents to programmatically interpret failures and take corrective action ' +
+      'rather than attempting to parse free-text error messages.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    if (api.errorCodeStructured) {
+      return this.pass({
+        type: 'text',
+        summary:
+          'Structured error codes detected in API specification. ' +
+          'Error responses include machine-readable code and message fields.',
+      });
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'No structured error codes found. Define error response schemas with ' +
+        '"error", "code", and "message" fields in your API specification.',
+    });
+  }
+}
diff --git a/src/audits/index.ts b/src/audits/index.ts
index f926d48..1fd7410 100644
--- a/src/audits/index.ts
+++ b/src/audits/index.ts
@@ -1,2 +1,33 @@
 export { BaseAudit } from './base-audit.js';
 export type { AuditMeta } from './base-audit.js';
+
+// Discovery
+export { LlmsTxtAudit } from './llms-txt.js';
+export { OpenapiSpecAudit } from './openapi-spec.js';
+export { RobotsAiAudit } from './robots-ai.js';
+export { AiPluginAudit } from './ai-plugin.js';
+export { SchemaOrgAudit } from './schema-org.js';
+
+// API Quality
+export { OpenapiValidAudit } from './openapi-valid.js';
+export { ResponseFormatAudit } from './response-format.js';
+export { ResponseExamplesAudit } from './response-examples.js';
+export { ContentNegotiationAudit } from './content-negotiation.js';
+
+// Structured Data
+export { JsonLdAudit } from './json-ld.js';
+export { MetaTagsAudit } from './meta-tags.js';
+export { SemanticHtmlAudit } from './semantic-html.js';
+
+// Auth & Onboarding
+export { SelfServiceAuthAudit } from './self-service-auth.js';
+export { NoCaptchaAudit } from './no-captcha.js';
+
+// Error Handling
+export { ErrorCodesAudit } from './error-codes.js';
+export { RateLimitHeadersAudit } from './rate-limit-headers.js';
+export { RetryAfterAudit } from './retry-after.js';
+
+// Documentation
+export { MachineReadableDocsAudit } from './machine-readable-docs.js';
+export { SdkAvailableAudit } from './sdk-available.js';
diff --git a/src/audits/json-ld.ts b/src/audits/json-ld.ts
new file mode 100644
index 0000000..0ac6671
--- /dev/null
+++ b/src/audits/json-ld.ts
@@ -0,0 +1,56 @@
+import type { AuditResult, AuditDetails } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HtmlGatherResult } from '../gatherers/html-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks if the page contains valid JSON-LD structured data.
+ * JSON-LD helps AI agents understand page content and entity relationships.
+ */
+export class JsonLdAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'json-ld',
+    title: 'Page has JSON-LD structured data',
+    failureTitle: 'Page is missing JSON-LD structured data',
+    description:
+      'JSON-LD provides machine-readable structured data that helps AI agents ' +
+      'understand page content, entities, and relationships without parsing HTML.',
+    requiredGatherers: ['html'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const html = artifacts['html'] as HtmlGatherResult;
+    const jsonLdBlocks = html.jsonLd;
+
+    if (jsonLdBlocks.length > 0) {
+      const types = jsonLdBlocks
+        .filter(
+          (block): block is Record<string, unknown> =>
+            typeof block === 'object' && block !== null
+        )
+        .map((block) => block['@type'] as string | undefined)
+        .filter(Boolean);
+
+      const details: AuditDetails = {
+        type: 'table',
+        items: [
+          {
+            blockCount: jsonLdBlocks.length,
+            types: types.join(', ') || 'unknown',
+          },
+        ],
+        summary: `Found ${jsonLdBlocks.length} JSON-LD block(s)`,
+      };
+
+      return this.pass(details);
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'No JSON-LD structured data found. Add <script type="application/ld+json"> ' +
+        'blocks to help AI agents parse your content.',
+    });
+  }
+}
diff --git a/src/audits/llms-txt.ts b/src/audits/llms-txt.ts
new file mode 100644
index 0000000..6eaa40f
--- /dev/null
+++ b/src/audits/llms-txt.ts
@@ -0,0 +1,49 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HttpGatherResult } from '../gatherers/http-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks whether the site exposes a `/llms.txt` file with meaningful content.
+ *
+ * llms.txt is a convention that helps LLM-based agents understand a site's
+ * purpose, API surface, and intended use, improving discoverability.
+ */
+export class LlmsTxtAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'llms-txt',
+    title: 'Site provides an llms.txt file',
+    failureTitle: 'Site does not provide an llms.txt file',
+    description:
+      'An llms.txt file helps AI agents understand the site purpose and available resources. ' +
+      'Providing one improves discoverability by LLM-based tools.',
+    requiredGatherers: ['http'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const http = artifacts['http'] as HttpGatherResult;
+    const llmsTxt = http.llmsTxt;
+
+    if (!llmsTxt.found) {
+      return this.fail({
+        type: 'text',
+        summary: 'No /llms.txt file was found at the target URL.',
+      });
+    }
+
+    const content = (llmsTxt.content ?? '').trim();
+
+    if (content.length === 0) {
+      return this.partial(0.5, {
+        type: 'text',
+        summary: 'An /llms.txt file was found but it is empty.',
+      });
+    }
+
+    return this.pass({
+      type: 'text',
+      summary: `Found /llms.txt with ${content.length} characters of content.`,
+    });
+  }
+}
diff --git a/src/audits/machine-readable-docs.ts b/src/audits/machine-readable-docs.ts
new file mode 100644
index 0000000..0e3ece2
--- /dev/null
+++ b/src/audits/machine-readable-docs.ts
@@ -0,0 +1,44 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks if the site provides machine-readable documentation.
+ * Machine-readable docs (OpenAPI, llms.txt, ai-plugin.json) let AI agents
+ * discover and use APIs without parsing human-readable pages.
+ */
+export class MachineReadableDocsAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'machine-readable-docs',
+    title: 'Site provides machine-readable documentation',
+    failureTitle: 'Site lacks machine-readable documentation',
+    description:
+      'Machine-readable documentation (OpenAPI/Swagger spec, llms.txt, or ai-plugin.json) ' +
+      'enables AI agents to automatically discover API endpoints, understand request/response ' +
+      'schemas, and integrate without manual interpretation of human-written docs.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    if (api.hasMachineReadableDocs) {
+      return this.pass({
+        type: 'text',
+        summary:
+          'Machine-readable documentation found (OpenAPI spec, llms.txt, ' +
+          'and/or ai-plugin.json). AI agents can auto-discover API capabilities.',
+      });
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'No machine-readable documentation found. Provide at least one of: ' +
+        'OpenAPI spec at /openapi.json, llms.txt at /llms.txt, or ' +
+        'ai-plugin.json at /.well-known/ai-plugin.json.',
+    });
+  }
+}
diff --git a/src/audits/meta-tags.ts b/src/audits/meta-tags.ts
new file mode 100644
index 0000000..bb0677b
--- /dev/null
+++ b/src/audits/meta-tags.ts
@@ -0,0 +1,69 @@
+import type { AuditResult, AuditDetails } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HtmlGatherResult } from '../gatherers/html-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+interface TagCheck {
+  tag: string;
+  present: boolean;
+}
+
+/**
+ * Checks for essential meta tags: title, description, og:title, og:description.
+ * These tags help AI agents quickly understand page purpose and content.
+ */
+export class MetaTagsAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'meta-tags',
+    title: 'Page has essential meta tags',
+    failureTitle: 'Page is missing essential meta tags',
+    description:
+      'Essential meta tags (title, description, og:title, og:description) provide ' +
+      'AI agents with quick summaries of page content without full HTML parsing.',
+    requiredGatherers: ['html'],
+    scoreDisplayMode: 'numeric',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const html = artifacts['html'] as HtmlGatherResult;
+    const { metaTags } = html;
+
+    const checks: TagCheck[] = [
+      { tag: 'title', present: metaTags.title !== null && metaTags.title.length > 0 },
+      {
+        tag: 'description',
+        present: metaTags.description !== null && metaTags.description.length > 0,
+      },
+      {
+        tag: 'og:title',
+        present: metaTags.ogTitle !== null && metaTags.ogTitle.length > 0,
+      },
+      {
+        tag: 'og:description',
+        present: metaTags.ogDescription !== null && metaTags.ogDescription.length > 0,
+      },
+    ];
+
+    const foundCount = checks.filter((c) => c.present).length;
+    const score = foundCount / checks.length;
+
+    const details: AuditDetails = {
+      type: 'table',
+      items: checks.map((c) => ({
+        tag: c.tag,
+        status: c.present ? 'found' : 'missing',
+      })),
+      summary: `${foundCount} of ${checks.length} essential meta tags found`,
+    };
+
+    if (score === 1) {
+      return this.pass(details);
+    }
+
+    if (score === 0) {
+      return this.fail(details);
+    }
+
+    return this.partial(score, details);
+  }
+}
diff --git a/src/audits/no-captcha.ts b/src/audits/no-captcha.ts
new file mode 100644
index 0000000..119026a
--- /dev/null
+++ b/src/audits/no-captcha.ts
@@ -0,0 +1,42 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks that the site does NOT require CAPTCHA.
+ * CAPTCHAs are designed to block automated agents and are a major barrier
+ * for AI agent accessibility.
+ */
+export class NoCaptchaAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'no-captcha',
+    title: 'Site does not require CAPTCHA',
+    failureTitle: 'Site requires CAPTCHA, blocking AI agents',
+    description:
+      'CAPTCHAs (reCAPTCHA, hCaptcha, etc.) are designed to block automated access. ' +
+      'Sites that require CAPTCHA prevent AI agents from interacting with them. ' +
+      'Consider alternative bot-mitigation strategies like API keys or rate limiting.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    // Inverted logic: no captcha = pass, captcha detected = fail
+    if (!api.hasCaptcha) {
+      return this.pass({
+        type: 'text',
+        summary: 'No CAPTCHA detected. AI agents can interact with this site.',
+      });
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'CAPTCHA detected (reCAPTCHA, hCaptcha, or similar). This blocks AI agents ' +
+        'from accessing the site. Consider using API keys or rate limiting instead.',
+    });
+  }
+}
diff --git a/src/audits/openapi-spec.ts b/src/audits/openapi-spec.ts
new file mode 100644
index 0000000..74bbbd5
--- /dev/null
+++ b/src/audits/openapi-spec.ts
@@ -0,0 +1,59 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HttpGatherResult } from '../gatherers/http-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks whether the site exposes an OpenAPI specification at `/openapi.json`.
+ *
+ * A valid OpenAPI spec enables AI agents to programmatically discover
+ * and interact with the site's API endpoints.
+ */
+export class OpenapiSpecAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'openapi-spec',
+    title: 'Site provides an OpenAPI specification',
+    failureTitle: 'Site does not provide an OpenAPI specification',
+    description:
+      'An OpenAPI specification allows AI agents to discover and understand ' +
+      'API endpoints programmatically, enabling automated integration.',
+    requiredGatherers: ['http'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const http = artifacts['http'] as HttpGatherResult;
+    const openapiSpec = http.openapiSpec;
+
+    if (!openapiSpec.found) {
+      return this.fail({
+        type: 'text',
+        summary: 'No /openapi.json file was found at the target URL.',
+      });
+    }
+
+    const content = (openapiSpec.content ?? '').trim();
+
+    if (content.length === 0) {
+      return this.partial(0.5, {
+        type: 'text',
+        summary: 'An /openapi.json file was found but it is empty.',
+      });
+    }
+
+    // Validate that it is parseable JSON
+    try {
+      JSON.parse(content);
+    } catch {
+      return this.partial(0.3, {
+        type: 'text',
+        summary: 'An /openapi.json file was found but it contains invalid JSON.',
+      });
+    }
+
+    return this.pass({
+      type: 'text',
+      summary: 'Found a valid JSON file at /openapi.json.',
+    });
+  }
+}
diff --git a/src/audits/openapi-valid.ts b/src/audits/openapi-valid.ts
new file mode 100644
index 0000000..3774b0f
--- /dev/null
+++ b/src/audits/openapi-valid.ts
@@ -0,0 +1,85 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HttpGatherResult } from '../gatherers/http-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Validates the structural completeness of the OpenAPI specification.
+ *
+ * A structurally valid OpenAPI spec must contain a version field
+ * (`openapi` or `swagger`), an `info` object, and a `paths` object.
+ */
+export class OpenapiValidAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'openapi-valid',
+    title: 'OpenAPI specification is structurally valid',
+    failureTitle: 'OpenAPI specification is missing or structurally invalid',
+    description:
+      'A structurally valid OpenAPI specification should contain a version field ' +
+      '(openapi or swagger), an info object, and a paths object with at least one endpoint.',
+    requiredGatherers: ['http'],
+    scoreDisplayMode: 'numeric',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const http = artifacts['http'] as HttpGatherResult;
+    const openapiSpec = http.openapiSpec;
+
+    if (!openapiSpec.found || !openapiSpec.content) {
+      return this.fail({
+        type: 'text',
+        summary: 'No OpenAPI specification was found to validate.',
+      });
+    }
+
+    let spec: Record<string, unknown>;
+    try {
+      spec = JSON.parse(openapiSpec.content) as Record<string, unknown>;
+    } catch {
+      return this.fail({
+        type: 'text',
+        summary: 'The OpenAPI specification contains invalid JSON and cannot be parsed.',
+      });
+    }
+
+    // Check three structural requirements
+    const checks = {
+      hasVersion: typeof spec.openapi === 'string' || typeof spec.swagger === 'string',
+      hasInfo: spec.info !== null && typeof spec.info === 'object',
+      hasPaths: spec.paths !== null && typeof spec.paths === 'object',
+    };
+
+    const passed = Object.values(checks).filter(Boolean).length;
+    const total = Object.keys(checks).length;
+
+    if (passed === total) {
+      const version = (spec.openapi ?? spec.swagger) as string;
+      const pathCount = Object.keys(spec.paths as Record<string, unknown>).length;
+      return this.pass({
+        type: 'table',
+        summary: `OpenAPI spec is structurally valid (version: ${version}, ${pathCount} path(s)).`,
+        items: [
+          { check: 'Version field', result: 'present', value: version },
+          { check: 'Info object', result: 'present' },
+          { check: 'Paths object', result: 'present', value: `${pathCount} path(s)` },
+        ],
+      });
+    }
+
+    const score = passed / total;
+    const missing: string[] = [];
+    if (!checks.hasVersion) missing.push('version (openapi/swagger)');
+    if (!checks.hasInfo) missing.push('info');
+    if (!checks.hasPaths) missing.push('paths');
+
+    return this.partial(score, {
+      type: 'table',
+      summary: `OpenAPI spec is missing ${missing.join(', ')}. Passed ${passed}/${total} checks.`,
+      items: [
+        { check: 'Version field', result: checks.hasVersion ? 'present' : 'missing' },
+        { check: 'Info object', result: checks.hasInfo ? 'present' : 'missing' },
+        { check: 'Paths object', result: checks.hasPaths ? 'present' : 'missing' },
+      ],
+    });
+  }
+}
diff --git a/src/audits/rate-limit-headers.ts b/src/audits/rate-limit-headers.ts
new file mode 100644
index 0000000..45d19b0
--- /dev/null
+++ b/src/audits/rate-limit-headers.ts
@@ -0,0 +1,49 @@
+import type { AuditResult, AuditDetails } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks for rate limiting headers (X-RateLimit-*, RateLimit-*).
+ * Rate limit headers help AI agents self-regulate request frequency
+ * and avoid being blocked.
+ */
+export class RateLimitHeadersAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'rate-limit-headers',
+    title: 'API provides rate limit headers',
+    failureTitle: 'API does not provide rate limit headers',
+    description:
+      'Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, RateLimit-*) ' +
+      'inform AI agents about request quotas so they can throttle themselves and ' +
+      'avoid being blocked by the server.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    if (api.hasRateLimitHeaders) {
+      const headerNames = Object.keys(api.rateLimitHeaders);
+
+      const details: AuditDetails = {
+        type: 'table',
+        items: headerNames.map((name) => ({
+          header: name,
+          value: api.rateLimitHeaders[name],
+        })),
+        summary: `Found ${headerNames.length} rate limit header(s): ${headerNames.join(', ')}`,
+      };
+
+      return this.pass(details);
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'No rate limit headers found. Add X-RateLimit-Limit, X-RateLimit-Remaining, ' +
+        'and X-RateLimit-Reset headers to help AI agents manage request frequency.',
+    });
+  }
+}
diff --git a/src/audits/response-examples.ts b/src/audits/response-examples.ts
new file mode 100644
index 0000000..444ee52
--- /dev/null
+++ b/src/audits/response-examples.ts
@@ -0,0 +1,49 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks whether the OpenAPI specification contains example responses.
+ *
+ * Example responses in the OpenAPI spec help AI agents understand the
+ * expected data shapes, enabling better code generation and integration.
+ */
+export class ResponseExamplesAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'response-examples',
+    title: 'OpenAPI spec contains response examples',
+    failureTitle: 'OpenAPI spec does not contain response examples',
+    description:
+      'Response examples in the OpenAPI specification help AI agents understand ' +
+      'expected data shapes, improving automated code generation and integration accuracy.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    if (!api.hasOpenApi) {
+      return this.fail({
+        type: 'text',
+        summary:
+          'No OpenAPI specification was found, so response examples cannot be evaluated.',
+      });
+    }
+
+    if (api.hasExamples) {
+      return this.pass({
+        type: 'text',
+        summary: 'The OpenAPI specification includes response examples.',
+      });
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'The OpenAPI specification does not include response examples. ' +
+        'Adding "example" or "examples" fields helps AI agents understand expected data shapes.',
+    });
+  }
+}
diff --git a/src/audits/response-format.ts b/src/audits/response-format.ts
new file mode 100644
index 0000000..cafe43c
--- /dev/null
+++ b/src/audits/response-format.ts
@@ -0,0 +1,41 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks whether the API uses a JSON content type in its responses.
+ *
+ * AI agents work best with structured data formats. JSON content types
+ * indicate the API is designed for programmatic consumption.
+ */
+export class ResponseFormatAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'response-format',
+    title: 'API responses use JSON content type',
+    failureTitle: 'API responses do not use JSON content type',
+    description:
+      'APIs that respond with a JSON content type (application/json) are easier ' +
+      'for AI agents to parse and consume programmatically.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    if (api.hasJsonContentType) {
+      return this.pass({
+        type: 'text',
+        summary: 'The API returns responses with a JSON-compatible content type.',
+      });
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'The API does not return a JSON content type header. ' +
+        'AI agents rely on structured JSON responses for reliable parsing.',
+    });
+  }
+}
diff --git a/src/audits/retry-after.ts b/src/audits/retry-after.ts
new file mode 100644
index 0000000..1e9df6c
--- /dev/null
+++ b/src/audits/retry-after.ts
@@ -0,0 +1,43 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks for Retry-After header support.
+ * The Retry-After header tells AI agents exactly when to retry after being
+ * rate-limited, enabling graceful backoff without guesswork.
+ */
+export class RetryAfterAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'retry-after',
+    title: 'API supports Retry-After header',
+    failureTitle: 'API does not support Retry-After header',
+    description:
+      'The Retry-After header (RFC 7231) tells AI agents when to retry after receiving ' +
+      'a 429 or 503 response. Without it, agents must guess retry timing, leading to ' +
+      'either excessive retries or unnecessary delays.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    if (api.hasRetryAfter) {
+      return this.pass({
+        type: 'text',
+        summary:
+          'Retry-After header support detected. AI agents can implement precise ' +
+          'backoff timing when rate-limited.',
+      });
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'No Retry-After header support found. Include a Retry-After header in 429 ' +
+        'and 503 responses so AI agents know exactly when to retry.',
+    });
+  }
+}
diff --git a/src/audits/robots-ai.ts b/src/audits/robots-ai.ts
new file mode 100644
index 0000000..625a3ed
--- /dev/null
+++ b/src/audits/robots-ai.ts
@@ -0,0 +1,124 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HttpGatherResult } from '../gatherers/http-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+const AI_USER_AGENTS = ['GPTBot', 'anthropic', 'Google-Extended', 'CCBot'];
+
+/**
+ * Checks whether robots.txt contains AI-friendly directives.
+ *
+ * Sites that explicitly allow (or at least do not block) common AI user agents
+ * are more discoverable and accessible to AI-powered tools and agents.
+ */
+export class RobotsAiAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'robots-ai',
+    title: 'robots.txt is AI-friendly',
+    failureTitle: 'robots.txt blocks AI agents',
+    description:
+      'A robots.txt file that does not block common AI user agents ' +
+      '(GPTBot, Anthropic, Google-Extended, CCBot) allows AI agents to crawl and index the site.',
+    requiredGatherers: ['http'],
+    scoreDisplayMode: 'numeric',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const http = artifacts['http'] as HttpGatherResult;
+    const robotsTxt = http.robotsTxt;
+
+    if (!robotsTxt.found || !robotsTxt.content) {
+      return this.fail({
+        type: 'text',
+        summary: 'No robots.txt file was found. AI agents cannot determine crawl permissions.',
+      });
+    }
+
+    const content = robotsTxt.content.toLowerCase();
+    const lines = content.split('\n').map((line) => line.trim());
+
+    const blockedAgents: string[] = [];
+    const allowedAgents: string[] = [];
+
+    for (const agent of AI_USER_AGENTS) {
+      if (this.isAgentBlocked(lines, agent.toLowerCase())) {
+        blockedAgents.push(agent);
+      } else {
+        allowedAgents.push(agent);
+      }
+    }
+
+    const totalAgents = AI_USER_AGENTS.length;
+    const allowedCount = allowedAgents.length;
+
+    if (allowedCount === totalAgents) {
+      return this.pass({
+        type: 'table',
+        summary: 'robots.txt does not block any common AI user agents.',
+        items: allowedAgents.map((agent) => ({ agent, status: 'allowed' })),
+      });
+    }
+
+    if (allowedCount === 0) {
+      return this.fail({
+        type: 'table',
+        summary: 'robots.txt blocks all common AI user agents.',
+        items: blockedAgents.map((agent) => ({ agent, status: 'blocked' })),
+      });
+    }
+
+    const score = allowedCount / totalAgents;
+    return this.partial(score, {
+      type: 'table',
+      summary: `robots.txt blocks ${blockedAgents.length} of ${totalAgents} common AI user agents.`,
+      items: [
+        ...blockedAgents.map((agent) => ({ agent, status: 'blocked' })),
+        ...allowedAgents.map((agent) => ({ agent, status: 'allowed' })),
+      ],
+    });
+  }
+
+  /**
+   * Determines if a specific user agent is blocked by the robots.txt rules.
+   *
+   * Checks for agent-specific disallow directives as well as wildcard blocks.
+   */
+  private isAgentBlocked(lines: string[], agent: string): boolean {
+    let inAgentBlock = false;
+    let inWildcardBlock = false;
+    let agentHasDisallow = false;
+    let wildcardDisallowAll = false;
+
+    for (const line of lines) {
+      // Skip comments and empty lines
+      if (line.startsWith('#') || line.length === 0) {
+        continue;
+      }
+
+      if (line.startsWith('user-agent:')) {
+        const ua = line.replace('user-agent:', '').trim();
+        inAgentBlock = ua === agent;
+        inWildcardBlock = ua === '*';
+        continue;
+      }
+
+      if (inAgentBlock && line.startsWith('disallow:')) {
+        const path = line.replace('disallow:', '').trim();
+        if (path === '/' || path === '/*') {
+          agentHasDisallow = true;
+        }
+      }
+
+      if (inWildcardBlock && line.startsWith('disallow:')) {
+        const path = line.replace('disallow:', '').trim();
+        if (path === '/' || path === '/*') {
+          wildcardDisallowAll = true;
+        }
+      }
+    }
+
+    // Agent is blocked if it has a specific disallow or is caught by the wildcard block
+    // (but only if no agent-specific block exists to override)
+    return agentHasDisallow || wildcardDisallowAll;
+  }
+}
diff --git a/src/audits/schema-org.ts b/src/audits/schema-org.ts
new file mode 100644
index 0000000..db60e95
--- /dev/null
+++ b/src/audits/schema-org.ts
@@ -0,0 +1,63 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HtmlGatherResult } from '../gatherers/html-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks whether the page contains JSON-LD Schema.org structured data.
+ *
+ * JSON-LD provides machine-readable metadata that helps AI agents
+ * understand the type, purpose, and context of the page content.
+ */
+export class SchemaOrgAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'schema-org',
+    title: 'Page contains JSON-LD Schema.org structured data',
+    failureTitle: 'Page does not contain JSON-LD Schema.org structured data',
+    description:
+      'JSON-LD structured data (Schema.org) provides machine-readable context about ' +
+      'the page, enabling AI agents to understand its content type and purpose.',
+    requiredGatherers: ['html'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const html = artifacts['html'] as HtmlGatherResult;
+    const jsonLd = html.jsonLd;
+
+    if (!Array.isArray(jsonLd) || jsonLd.length === 0) {
+      return this.fail({
+        type: 'text',
+        summary: 'No JSON-LD structured data was found on the page.',
+      });
+    }
+
+    // Extract @type values from each JSON-LD block for reporting
+    const types: string[] = [];
+    for (const block of jsonLd) {
+      if (block && typeof block === 'object') {
+        const record = block as Record<string, unknown>;
+        const type = record['@type'];
+        if (typeof type === 'string') {
+          types.push(type);
+        } else if (Array.isArray(type)) {
+          for (const t of type) {
+            if (typeof t === 'string') {
+              types.push(t);
+            }
+          }
+        }
+      }
+    }
+
+    const typeSummary =
+      types.length > 0
+        ? ` Types found: ${types.join(', ')}.`
+        : '';
+
+    return this.pass({
+      type: 'text',
+      summary: `Found ${jsonLd.length} JSON-LD block(s) on the page.${typeSummary}`,
+    });
+  }
+}
diff --git a/src/audits/sdk-available.ts b/src/audits/sdk-available.ts
new file mode 100644
index 0000000..a1f94c4
--- /dev/null
+++ b/src/audits/sdk-available.ts
@@ -0,0 +1,43 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks if the site mentions SDK availability.
+ * SDKs (npm packages, pip packages, GitHub libraries) reduce integration friction
+ * for AI agents and their developers.
+ */
+export class SdkAvailableAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'sdk-available',
+    title: 'SDK or client library is available',
+    failureTitle: 'No SDK or client library detected',
+    description:
+      'SDKs and client libraries (npm, pip, GitHub repos) simplify API integration ' +
+      'for AI agents and developers. They provide type-safe interfaces, handle auth, ' +
+      'and reduce the amount of boilerplate code needed to interact with the service.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    if (api.hasSdkLinks) {
+      return this.pass({
+        type: 'text',
+        summary:
+          'SDK or client library references detected (e.g., npm install, pip install, ' +
+          'GitHub links, or developer portal references).',
+      });
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'No SDK or client library references found. Providing SDKs (npm, pip, etc.) ' +
+        'or linking to a GitHub repository lowers the barrier for AI agent integration.',
+    });
+  }
+}
diff --git a/src/audits/self-service-auth.ts b/src/audits/self-service-auth.ts
new file mode 100644
index 0000000..08826c5
--- /dev/null
+++ b/src/audits/self-service-auth.ts
@@ -0,0 +1,42 @@
+import type { AuditResult } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { ApiGatherResult } from '../gatherers/api-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+/**
+ * Checks if the site offers self-service authentication endpoints.
+ * AI agents need programmatic auth (OAuth, API keys, tokens) to access services
+ * without human intervention.
+ */
+export class SelfServiceAuthAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'self-service-auth',
+    title: 'Site provides self-service authentication',
+    failureTitle: 'Site lacks self-service authentication endpoints',
+    description:
+      'Self-service authentication (OAuth, API keys, token endpoints) allows AI agents ' +
+      'to programmatically authenticate without requiring human-in-the-loop setup.',
+    requiredGatherers: ['api'],
+    scoreDisplayMode: 'binary',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const api = artifacts['api'] as ApiGatherResult;
+
+    if (api.hasAuthEndpoint) {
+      return this.pass({
+        type: 'text',
+        summary:
+          'Self-service authentication endpoints detected (e.g., /auth, /oauth, ' +
+          '/api/token, or securitySchemes in OpenAPI spec).',
+      });
+    }
+
+    return this.fail({
+      type: 'text',
+      summary:
+        'No self-service authentication endpoints found. Provide OAuth, API key, ' +
+        'or token-based auth so AI agents can authenticate programmatically.',
+    });
+  }
+}
diff --git a/src/audits/semantic-html.ts b/src/audits/semantic-html.ts
new file mode 100644
index 0000000..a11cf7d
--- /dev/null
+++ b/src/audits/semantic-html.ts
@@ -0,0 +1,61 @@
+import type { AuditResult, AuditDetails } from '../types.js';
+import type { GatherResult } from '../gatherers/base-gatherer.js';
+import type { HtmlGatherResult } from '../gatherers/html-gatherer.js';
+import { BaseAudit, type AuditMeta } from './base-audit.js';
+
+interface ElementCheck {
+  element: string;
+  present: boolean;
+}
+
+/**
+ * Checks for semantic HTML5 elements: nav, main, header, footer, h1.
+ * Semantic markup helps AI agents navigate and understand page structure.
+ */
+export class SemanticHtmlAudit extends BaseAudit {
+  meta: AuditMeta = {
+    id: 'semantic-html',
+    title: 'Page uses semantic HTML elements',
+    failureTitle: 'Page is missing semantic HTML elements',
+    description:
+      'Semantic HTML5 elements (nav, main, header, footer, h1) provide structural ' +
+      'meaning that helps AI agents navigate page content and identify key sections.',
+    requiredGatherers: ['html'],
+    scoreDisplayMode: 'numeric',
+  };
+
+  async audit(artifacts: Record<string, GatherResult>): Promise<AuditResult> {
+    const html = artifacts['html'] as HtmlGatherResult;
+    const { semanticElements } = html;
+
+    const checks: ElementCheck[] = [
+      { element: '<nav>', present: semanticElements.hasNav },
+      { element: '<main>', present: semanticElements.hasMain },
+      { element: '<header>', present: semanticElements.hasHeader },
+      { element: '<footer>', present: semanticElements.hasFooter },
+      { element: '<h1>', present: semanticElements.hasH1 },
+    ];
+
+    const foundCount = checks.filter((c) => c.present).length;
+    const score = foundCount / checks.length;
+
+    const details: AuditDetails = {
+      type: 'table',
+      items: checks.map((c) => ({
+        element: c.element,
+        status: c.present ? 'found' : 'missing',
+      })),
+      summary: `${foundCount} of ${checks.length} semantic elements found`,
+    };
+
+    if (score === 1) {
+      return this.pass(details);
+    }
+
+    if (score === 0) {
+      return this.fail(details);
+    }
+
+    return this.partial(score, details);
+  }
+}
diff --git a/src/gatherers/api-gatherer.ts b/src/gatherers/api-gatherer.ts
new file mode 100644
index 0000000..dbbb69d
--- /dev/null
+++ b/src/gatherers/api-gatherer.ts
@@ -0,0 +1,150 @@
+import type { AXConfig } from '../types.js';
+import { BaseGatherer, type GatherResult } from './base-gatherer.js';
+import type { HttpGatherResult } from './http-gatherer.js';
+
+export interface ApiGatherResult extends GatherResult {
+  hasOpenApi: boolean;
+  openapiVersion: string | null;
+  endpointCount: number;
+  hasJsonContentType: boolean;
+  hasAuthEndpoint: boolean;
+  hasCaptcha: boolean;
+  errorCodeStructured: boolean;
+  hasRateLimitHeaders: boolean;
+  rateLimitHeaders: Record<string, string>;
+  hasRetryAfter: boolean;
+  hasExamples: boolean;
+  hasSdkLinks: boolean;
+  hasMachineReadableDocs: boolean;
+}
+
+/**
+ * Analyzes API-related artifacts from the HTTP gatherer:
+ * OpenAPI spec validity, response headers, auth patterns, etc.
+ */
+export class ApiGatherer extends BaseGatherer {
+  name = 'api';
+
+  async gather(
+    _config: AXConfig,
+    artifacts?: Record<string, GatherResult>
+  ): Promise<ApiGatherResult> {
+    const httpResult = artifacts?.['http'] as HttpGatherResult | undefined;
+    const openapiContent = httpResult?.openapiSpec?.content ?? null;
+    const headers = httpResult?.headers ?? {};
+    const body = httpResult?.body ?? '';
+
+    // Parse OpenAPI spec if found
+    let hasOpenApi = false;
+    let openapiVersion: string | null = null;
+    let endpointCount = 0;
+    let hasExamples = false;
+
+    if (openapiContent) {
+      try {
+        const spec = JSON.parse(openapiContent) as Record<string, unknown>;
+        hasOpenApi = true;
+        openapiVersion =
+          (spec.openapi as string) ?? (spec.swagger as string) ?? null;
+
+        // Count paths
+        const paths = spec.paths as Record<string, unknown> | undefined;
+        if (paths && typeof paths === 'object') {
+          endpointCount = Object.keys(paths).length;
+
+          // Check for examples in any operation
+          const specStr = openapiContent.toLowerCase();
+          hasExamples =
+            specStr.includes('"example"') || specStr.includes('"examples"');
+        }
+      } catch {
+        // Invalid JSON — still mark as found but invalid
+        hasOpenApi = false;
+      }
+    }
+
+    // Check content type
+    const contentType = headers['content-type'] ?? '';
+    const hasJsonContentType =
+      contentType.includes('application/json') ||
+      contentType.includes('text/html');
+
+    // Check for auth endpoints (heuristic)
+    const hasAuthEndpoint =
+      body.includes('/auth') ||
+      body.includes('/login') ||
+      body.includes('/register') ||
+      body.includes('/signup') ||
+      body.includes('/oauth') ||
+      body.includes('/api/token') ||
+      (openapiContent?.includes('/auth') ?? false) ||
+      (openapiContent?.includes('securitySchemes') ?? false);
+
+    // Check for CAPTCHA
+    const bodyLower = body.toLowerCase();
+    const hasCaptcha =
+      bodyLower.includes('recaptcha') ||
+      bodyLower.includes('hcaptcha') ||
+      bodyLower.includes('captcha');
+
+    // Check error structure (heuristic from OpenAPI spec or HTML)
+    const errorCodeStructured =
+      (openapiContent?.includes('"error"') ?? false) ||
+      (openapiContent?.includes('"message"') ?? false) ||
+      (openapiContent?.includes('"code"') ?? false);
+
+    // Rate limit headers
+    const rateLimitHeaders: Record<string, string> = {};
+    const rateLimitKeys = [
+      'x-ratelimit-limit',
+      'x-ratelimit-remaining',
+      'x-ratelimit-reset',
+      'ratelimit-limit',
+      'ratelimit-remaining',
+      'ratelimit-reset',
+      'retry-after',
+    ];
+    for (const key of rateLimitKeys) {
+      const value = headers[key];
+      if (value) {
+        rateLimitHeaders[key] = value;
+      }
+    }
+
+    const hasRateLimitHeaders = Object.keys(rateLimitHeaders).length > 0;
+    const hasRetryAfter =
+      'retry-after' in rateLimitHeaders ||
+      (openapiContent?.toLowerCase().includes('retry-after') ?? false);
+
+    // SDK / documentation links
+    const hasSdkLinks =
+      bodyLower.includes('sdk') ||
+      bodyLower.includes('npm install') ||
+      bodyLower.includes('pip install') ||
+      bodyLower.includes('github.com') ||
+      bodyLower.includes('developer') ||
+      (openapiContent?.toLowerCase().includes('sdk') ?? false);
+
+    // Machine-readable docs
+    const hasMachineReadableDocs =
+      hasOpenApi ||
+      (httpResult?.llmsTxt?.found ?? false) ||
+      (httpResult?.aiPlugin?.found ?? false);
+
+    return {
+      hasOpenApi,
+      openapiVersion,
+      endpointCount,
+      hasJsonContentType,
+      hasAuthEndpoint,
+      hasCaptcha,
+      errorCodeStructured,
+      hasRateLimitHeaders,
+      rateLimitHeaders,
+      hasRetryAfter,
+      hasExamples,
+      hasSdkLinks,
+      hasMachineReadableDocs,
+    };
+  }
+}
diff --git a/src/gatherers/base-gatherer.ts b/src/gatherers/base-gatherer.ts
index 6b5b053..3ef3a47 100644
--- a/src/gatherers/base-gatherer.ts
+++ b/src/gatherers/base-gatherer.ts
@@ -7,9 +7,15 @@ export interface GatherResult {
 /**
  * Base class for all gatherers.
  * Gatherers collect raw data from the target URL that audits will analyze.
+ *
+ * Second-pass gatherers (e.g., HtmlGatherer) receive `artifacts` from
+ * first-pass gatherers so they can parse derived data without re-fetching.
  */
 export abstract class BaseGatherer {
   abstract name: string;
 
-  abstract gather(config: AXConfig): Promise<GatherResult>;
+  abstract gather(
+    config: AXConfig,
+    artifacts?: Record<string, GatherResult>
+  ): Promise<GatherResult>;
 }
diff --git a/src/gatherers/html-gatherer.ts b/src/gatherers/html-gatherer.ts
new file mode 100644
index 0000000..243380f
--- /dev/null
+++ b/src/gatherers/html-gatherer.ts
@@ -0,0 +1,124 @@
+import type { AXConfig } from '../types.js';
+import { BaseGatherer, type GatherResult } from './base-gatherer.js';
+import type { HttpGatherResult } from './http-gatherer.js';
+
+export interface MetaTags {
+  title: string | null;
+  description: string | null;
+  ogTitle: string | null;
+  ogDescription: string | null;
+  ogImage: string | null;
+  canonical: string | null;
+  robots: string | null;
+}
+
+export interface SemanticElements {
+  hasNav: boolean;
+  hasMain: boolean;
+  hasArticle: boolean;
+  hasHeader: boolean;
+  hasFooter: boolean;
+  hasH1: boolean;
+  headingCount: number;
+}
+
+export interface HtmlGatherResult extends GatherResult {
+  html: string;
+  jsonLd: unknown[];
+  metaTags: MetaTags;
+  semanticElements: SemanticElements;
+  links: string[];
+}
+
+// Simple regex-based extraction (no external DOM parser dependency)
+function extractMetaContent(html: string, nameOrProp: string): string | null {
+  // Match name="..." or property="..."
+  const pattern = new RegExp(
+    `<meta[^>]*(?:name|property)=["']${nameOrProp}["'][^>]*content=["']([^"']*)["']`,
+    'i'
+  );
+  const match = html.match(pattern);
+  if (match?.[1] !== undefined) return match[1];
+
+  // Reversed order: content before name
+  const reversed = new RegExp(
+    `<meta[^>]*content=["']([^"']*)["'][^>]*(?:name|property)=["']${nameOrProp}["']`,
+    'i'
+  );
+  const revMatch = html.match(reversed);
+  return revMatch?.[1] !== undefined ? revMatch[1] : null;
+}
+
+function extractTitle(html: string): string | null {
+  const match = html.match(/<title[^>]*>([^<]*)<\/title>/i);
+  return match?.[1] !== undefined ? match[1].trim() : null;
+}
+
+function extractJsonLd(html: string): unknown[] {
+  const results: unknown[] = [];
+  const regex = /<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(html)) !== null) {
+    try {
+      results.push(JSON.parse(match[1] ?? ''));
+    } catch {
+      // Skip malformed JSON-LD
+    }
+  }
+  return results;
+}
+
+function extractLinks(html: string): string[] {
+  const links: string[] = [];
+  const regex = /<a[^>]*href=["']([^"'#][^"']*)["']/gi;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(html)) !== null) {
+    links.push(match[1] ?? '');
+  }
+  return links;
+}
+
+function checkSemanticElements(html: string): SemanticElements {
+  const lower = html.toLowerCase();
+  return {
+    hasNav: /<nav[\s>]/i.test(lower),
+    hasMain: /<main[\s>]/i.test(lower),
+    hasArticle: /<article[\s>]/i.test(lower),
+    hasHeader: /<header[\s>]/i.test(lower),
+    hasFooter: /<footer[\s>]/i.test(lower),
+    hasH1: /<h1[\s>]/i.test(lower),
+    headingCount: (lower.match(/<h[1-6][\s>]/gi) ?? []).length,
+  };
+}
+
+/**
+ * Parses HTML body from the HTTP gatherer to extract metadata,
+ * JSON-LD, semantic structure, and links.
+ */
+export class HtmlGatherer extends BaseGatherer {
+  name = 'html';
+
+  async gather(
+    _config: AXConfig,
+    artifacts?: Record<string, GatherResult>
+  ): Promise<HtmlGatherResult> {
+    const httpResult = artifacts?.['http'] as HttpGatherResult | undefined;
+    const html = httpResult?.body ?? '';
+
+    return {
+      html,
+      jsonLd: extractJsonLd(html),
+      metaTags: {
+        title: extractTitle(html),
+        description: extractMetaContent(html, 'description'),
+        ogTitle: extractMetaContent(html, 'og:title'),
+        ogDescription: extractMetaContent(html, 'og:description'),
+        ogImage: extractMetaContent(html, 'og:image'),
+        canonical: extractMetaContent(html, 'canonical'),
+        robots: extractMetaContent(html, 'robots'),
+      },
+      semanticElements: checkSemanticElements(html),
+      links: extractLinks(html),
+    };
+  }
+}
diff --git a/src/gatherers/http-gatherer.ts b/src/gatherers/http-gatherer.ts
new file mode 100644
index 0000000..3ffd4bf
--- /dev/null
+++ b/src/gatherers/http-gatherer.ts
@@ -0,0 +1,113 @@
+import type { AXConfig } from '../types.js';
+import { BaseGatherer, type GatherResult } from './base-gatherer.js';
+import { DEFAULT_TIMEOUT } from '../config/default.js';
+
+export interface FileProbe {
+  found: boolean;
+  content: string | null;
+  statusCode: number | null;
+}
+
+export interface HttpGatherResult extends GatherResult {
+  url: string;
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+  robotsTxt: FileProbe;
+  llmsTxt: FileProbe;
+  openapiSpec: FileProbe;
+  aiPlugin: FileProbe;
+  sitemapXml: FileProbe;
+  securityTxt: FileProbe;
+}
+
+const MAX_BODY_SIZE = 512_000; // 512KB
+
+async function fetchFile(
+  baseUrl: string,
+  path: string,
+  timeout: number
+): Promise<FileProbe> {
+  try {
+    const url = new URL(path, baseUrl).href;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: { 'User-Agent': 'AX-Score/1.0 (agent-audit)' },
+      redirect: 'follow',
+    });
+
+    clearTimeout(timer);
+
+    if (!res.ok) {
+      return { found: false, content: null, statusCode: res.status };
+    }
+
+    const text = await res.text();
+    return {
+      found: true,
+      content: text.slice(0, MAX_BODY_SIZE),
+      statusCode: res.status,
+    };
+  } catch {
+    return { found: false, content: null, statusCode: null };
+  }
+}
+
+/**
+ * Fetches the target URL and probes well-known files.
+ */
+export class HttpGatherer extends BaseGatherer {
+  name = 'http';
+
+  async gather(config: AXConfig): Promise<HttpGatherResult> {
+    const timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    const baseUrl = config.url;
+
+    // Fetch main page + well-known files in parallel
+    const [main, robotsTxt, llmsTxt, openapiSpec, aiPlugin, sitemapXml, securityTxt] =
+      await Promise.all([
+        fetchFile(baseUrl, '/', timeout),
+        fetchFile(baseUrl, '/robots.txt', timeout),
+        fetchFile(baseUrl, '/llms.txt', timeout),
+        fetchFile(baseUrl, '/openapi.json', timeout),
+        fetchFile(baseUrl, '/.well-known/ai-plugin.json', timeout),
+        fetchFile(baseUrl, '/sitemap.xml', timeout),
+        fetchFile(baseUrl, '/.well-known/security.txt', timeout),
+      ]);
+
+    const headers: Record<string, string> = {};
+    // Re-fetch main page headers (the fetchFile above already did this)
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+      const res = await fetch(baseUrl, {
+        method: 'HEAD',
+        signal: controller.signal,
+        headers: { 'User-Agent': 'AX-Score/1.0 (agent-audit)' },
+        redirect: 'follow',
+      });
+      clearTimeout(timer);
+      res.headers.forEach((value, key) => {
+        headers[key] = value;
+      });
+    } catch {
+      // Fallback: headers remain empty
+    }
+
+    return {
+      url: baseUrl,
+      statusCode: main.statusCode ?? 0,
+      headers,
+      body: main.content ?? '',
+      robotsTxt,
+      llmsTxt,
+      openapiSpec,
+      aiPlugin,
+      sitemapXml,
+      securityTxt,
+    };
+  }
+}
diff --git a/src/gatherers/index.ts b/src/gatherers/index.ts
index 64d8ae3..aa9b618 100644
--- a/src/gatherers/index.ts
+++ b/src/gatherers/index.ts
@@ -1,2 +1,11 @@
 export { BaseGatherer } from './base-gatherer.js';
 export type { GatherResult } from './base-gatherer.js';
+
+export { HttpGatherer } from './http-gatherer.js';
+export type { HttpGatherResult, FileProbe } from './http-gatherer.js';
+
+export { HtmlGatherer } from './html-gatherer.js';
+export type { HtmlGatherResult, MetaTags, SemanticElements } from './html-gatherer.js';
+
+export { ApiGatherer } from './api-gatherer.js';
+export type { ApiGatherResult } from './api-gatherer.js';
diff --git a/src/index.ts b/src/index.ts
index 62a7a88..e50d841 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,6 +1,30 @@
+// Main API
 export { runAudit } from './runner.js';
-export type { AXReport, AXCategory, AuditResult, AXConfig, Recommendation } from './types.js';
+
+// Types
+export type {
+  AXReport,
+  AXCategory,
+  AuditResult,
+  AXConfig,
+  Recommendation,
+  AuditDetails,
+  AuditRef,
+} from './types.js';
+
+// Base classes (for extensibility)
 export { BaseAudit } from './audits/base-audit.js';
 export type { AuditMeta } from './audits/base-audit.js';
+
 export { BaseGatherer } from './gatherers/base-gatherer.js';
 export type { GatherResult } from './gatherers/base-gatherer.js';
+
+// Concrete gatherers
+export { HttpGatherer } from './gatherers/http-gatherer.js';
+export type { HttpGatherResult, FileProbe } from './gatherers/http-gatherer.js';
+
+export { HtmlGatherer } from './gatherers/html-gatherer.js';
+export type { HtmlGatherResult, MetaTags, SemanticElements } from './gatherers/html-gatherer.js';
+
+export { ApiGatherer } from './gatherers/api-gatherer.js';
+export type { ApiGatherResult } from './gatherers/api-gatherer.js';
diff --git a/src/runner.ts b/src/runner.ts
index 0ea53c1..1d6fa54 100644
--- a/src/runner.ts
+++ b/src/runner.ts
@@ -1,4 +1,5 @@
 import type { AXConfig, AXReport, AXCategory, AuditResult } from './types.js';
+import type { GatherResult } from './gatherers/base-gatherer.js';
 import { DEFAULT_CATEGORIES, VERSION } from './config/default.js';
 import {
   calculateCategoryScore,
@@ -6,18 +7,119 @@ import {
   generateRecommendations,
 } from './scoring.js';
 
+// Gatherers
+import { HttpGatherer } from './gatherers/http-gatherer.js';
+import { HtmlGatherer } from './gatherers/html-gatherer.js';
+import { ApiGatherer } from './gatherers/api-gatherer.js';
+
+// Audits — Discovery
+import { LlmsTxtAudit } from './audits/llms-txt.js';
+import { OpenapiSpecAudit } from './audits/openapi-spec.js';
+import { RobotsAiAudit } from './audits/robots-ai.js';
+import { AiPluginAudit } from './audits/ai-plugin.js';
+import { SchemaOrgAudit } from './audits/schema-org.js';
+
+// Audits — API Quality
+import { OpenapiValidAudit } from './audits/openapi-valid.js';
+import { ResponseFormatAudit } from './audits/response-format.js';
+import { ResponseExamplesAudit } from './audits/response-examples.js';
+import { ContentNegotiationAudit } from './audits/content-negotiation.js';
+
+// Audits — Structured Data
+import { JsonLdAudit } from './audits/json-ld.js';
+import { MetaTagsAudit } from './audits/meta-tags.js';
+import { SemanticHtmlAudit } from './audits/semantic-html.js';
+
+// Audits — Auth & Onboarding
+import { SelfServiceAuthAudit } from './audits/self-service-auth.js';
+import { NoCaptchaAudit } from './audits/no-captcha.js';
+
+// Audits — Error Handling
+import { ErrorCodesAudit } from './audits/error-codes.js';
+import { RateLimitHeadersAudit } from './audits/rate-limit-headers.js';
+import { RetryAfterAudit } from './audits/retry-after.js';
+
+// Audits — Documentation
+import { MachineReadableDocsAudit } from './audits/machine-readable-docs.js';
+import { SdkAvailableAudit } from './audits/sdk-available.js';
+
+import type { BaseAudit } from './audits/base-audit.js';
+
+/** All registered audits. Order does not matter — they are mapped by ID. */
+function createAudits(): BaseAudit[] {
+  return [
+    // Discovery
+    new LlmsTxtAudit(),
+    new OpenapiSpecAudit(),
+    new RobotsAiAudit(),
+    new AiPluginAudit(),
+    new SchemaOrgAudit(),
+    // API Quality
+    new OpenapiValidAudit(),
+    new ResponseFormatAudit(),
+    new ResponseExamplesAudit(),
+    new ContentNegotiationAudit(),
+    // Structured Data
+    new JsonLdAudit(),
+    new MetaTagsAudit(),
+    new SemanticHtmlAudit(),
+    // Auth & Onboarding
+    new SelfServiceAuthAudit(),
+    new NoCaptchaAudit(),
+    // Error Handling
+    new ErrorCodesAudit(),
+    new RateLimitHeadersAudit(),
+    new RetryAfterAudit(),
+    // Documentation
+    new MachineReadableDocsAudit(),
+    new SdkAvailableAudit(),
+  ];
+}
+
 /**
  * Run an AX audit against the given URL.
- * Orchestrates the Gather -> Audit -> Score -> Report pipeline.
+ * Orchestrates the Gather → Audit → Score → Report pipeline.
  */
 export async function runAudit(config: AXConfig): Promise<AXReport> {
   const { url } = config;
 
-  // TODO: Phase 1 — Implement gatherers to collect artifacts from URL
-  // TODO: Phase 1 — Run audits against gathered artifacts
-  // For now, return a placeholder report showing the structure
+  // Phase 1: Gather — collect raw artifacts from the target
+  const httpGatherer = new HttpGatherer();
+  const htmlGatherer = new HtmlGatherer();
+  const apiGatherer = new ApiGatherer();
+
+  // First pass: HTTP (network requests)
+  const artifacts: Record<string, GatherResult> = {};
+  artifacts['http'] = await httpGatherer.gather(config);
+
+  // Second pass: HTML + API (derived from HTTP artifacts)
+  artifacts['html'] = await htmlGatherer.gather(config, artifacts);
+  artifacts['api'] = await apiGatherer.gather(config, artifacts);
+
+  // Phase 2: Audit — run all audits against gathered artifacts
+  const allAudits = createAudits();
   const audits: Record<string, AuditResult> = {};
 
+  const auditPromises = allAudits.map(async (auditInstance) => {
+    try {
+      const result = await auditInstance.audit(artifacts);
+      audits[result.id] = result;
+    } catch (err) {
+      // If an audit fails, record it as score 0
+      audits[auditInstance.meta.id] = {
+        id: auditInstance.meta.id,
+        title: auditInstance.meta.failureTitle,
+        description: `Audit error: ${err instanceof Error ? err.message : 'Unknown error'}`,
+        score: 0,
+        weight: 0,
+        scoreDisplayMode: auditInstance.meta.scoreDisplayMode,
+      };
+    }
+  });
+
+  await Promise.all(auditPromises);
+
+  // Phase 3: Score — calculate category and overall scores
   const categories: AXCategory[] = DEFAULT_CATEGORIES.map((cat) => ({
     id: cat.id,
     title: cat.title,