---
title: "Adapter Agent Conformance"
description: "Validate that a framework adapter exposes the same agent-readable documentation contract as the first-party adapters"
canonical_url: "https://docs.farming-labs.dev/docs/guides/adapter-agent-conformance"
markdown_url: "https://docs.farming-labs.dev/docs/guides/adapter-agent-conformance.md"
last_updated: "2018-10-20"
agent:
  tokenBudget: 850
  task: "Add the shared agent-surface conformance suite to a framework adapter."
  outcome: "The adapter passes the same discovery, Markdown, sitemap, robots, skills, MCP, and paginated search contract as first-party adapters."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "The adapter exposes one request handler that can serve the shared docs API and public aliases."
    - "A test fixture contains at least one docs page and can issue Web Request objects to the adapter."
  files:
    - "src/server.ts"
    - "src/agent-conformance.test.ts"
  sideEffects:
    - "Expanding the shared contract can require coordinated public-route changes across every adapter."
  verification:
    - description: "Run the adapter test containing runDocsAgentConformance."
      expect: "The report contains no failed cases and identifies the expected contract version."
  rollback:
    - "Restore the previous adapter handler and remove only the conformance wiring introduced by the change."
  failureModes:
    - symptom: "One public alias fails while the canonical docs API passes."
      resolution: "Forward the alias through the same shared server and preserve its method, headers, status, and response body."
    - symptom: "Static and runtime discovery disagree."
      resolution: "Generate both surfaces from the same resolved config and assert their hashed artifacts in the conformance test."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Add the shared agent-surface conformance suite to a framework adapter.
Outcome: The adapter passes the same discovery, Markdown, sitemap, robots, skills, MCP, and paginated search contract as first-party adapters.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- The adapter exposes one request handler that can serve the shared docs API and public aliases.
- A test fixture contains at least one docs page and can issue Web Request objects to the adapter.

### Files

- `src/server.ts`
- `src/agent-conformance.test.ts`

### Side Effects

- Expanding the shared contract can require coordinated public-route changes across every adapter.

### Verification

- Run the adapter test containing runDocsAgentConformance.
  - Expected: The report contains no failed cases and identifies the expected contract version.

### Rollback

- Restore the previous adapter handler and remove only the conformance wiring introduced by the change.

### Failure Modes

- One public alias fails while the canonical docs API passes. — Recovery: Forward the alias through the same shared server and preserve its method, headers, status, and response body.
- Static and runtime discovery disagree. — Recovery: Generate both surfaces from the same resolved config and assert their hashed artifacts in the conformance test.
<!-- farming-labs:agent-contract:end -->

# Adapter Agent Conformance
URL: /docs/guides/adapter-agent-conformance
LLM index: /llms.txt
Description: Validate that a framework adapter exposes the same agent-readable documentation contract as the first-party adapters
Related: /docs/guides/agent-friendly-docs, /docs/customization/mcp, /docs/customization/llms-txt, /docs/customization/sitemaps, /docs/cli

Every `@farming-labs/docs` adapter should expose the same machine-readable surface. The shared conformance runner turns that expectation into an executable contract.

Use `runDocsAgentConformance` when building or changing a framework adapter. Provide one callback dispatching GET requests to the adapter's public handler and the `mcp` case to its MCP POST handler. Use fixture titles `Introduction` and `Bonjour` for default and localized Markdown. A passing report must contain no failed cases.

## Exact implementation

```ts title="src/agent-conformance.test.ts" framework="custom" runnable
import { runDocsAgentConformance } from "@farming-labs/docs";

export async function verifyAdapter() {
  return runDocsAgentConformance({
    adapter: "nextjs",
    async handle(request) {
      return fetch(request);
    },
  });
}
```

## Covered surfaces

Versioned contract (`DOCS_AGENT_CONTRACT_VERSION` `1.3`) verifies:

- Custom agent discovery, RFC 9727 API catalog GET/HEAD, Agent Skills index/artifact GET/HEAD, config, diagnostics, and feedback schema
- Explicit `.md` aliases and `Accept: text/markdown` negotiation
- Default and localized page content; actionable missing-page recovery
- `llms.txt`, `llms-full.txt`, `AGENTS.md`, `skill.md`
- XML and Markdown sitemaps plus `robots.txt`
- Streamable HTTP MCP initialize request
- Gzip-encoded tar archive delivery of SKILL.md (decompressed via `readAgentSkillDocumentFromTar`)
- SKILL.md frontmatter validated against full spec — unexpected fields like `version` and incorrect `allowed-tools` type are conformance failures
- Cursor-based structured search pagination
- `capabilities.contentChanges` flag and live `GET /api/docs?audience=agent&response=changes` returning valid `docs-content-changes.v1` JSON with `indexGeneration`, `mode`, `resetRequired`, `documentCount`, and array fields; ETag and body-free delivery verified
- HTTP cache validators on every agent-surface response

## Cursor-based structured search

- `GET /api/docs?response=structured&query=<term>&limit=1` returns `hasMore`, `total`, and `nextCursor`.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).