API ReferenceCopy Anchor Link

Complete reference for every option in docs.config.ts. All types are exported from @farming-labs/docs.

defineDocs(config)Copy Anchor Link

The entry point for configuring your docs. Returns a typed config object.

import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  // ...all options below
});

DocsConfigCopy Anchor Link

DocsLocalMcpSearchRuntimeConfigCopy Anchor Link

Runtime shape that describes whether the local MCP server should be treated as the search target. Exported from @farming-labs/docs and @farming-labs/docs/server.

DocsLocalMcpSearchRuntimeInputCopy Anchor Link

Accepted input shape for resolveLocalDocsMcpSearchConfig. A partial form of DocsLocalMcpSearchRuntimeConfig — all fields are optional. Exported from @farming-labs/docs and @farming-labs/docs/server.

DocsSearchRequestResolutionOptionsCopy Anchor Link

Options accepted by the third parameter of resolveSearchRequestConfig. Exported from @farming-labs/docs and @farming-labs/docs/server.

resolveLocalDocsMcpSearchConfigCopy Anchor Link

Public function exported from @farming-labs/docs and @farming-labs/docs/server. Given a McpDocsSearchConfig, an optional DocsLocalMcpSearchRuntimeInput, and an optional request URL, returns a modified search config that uses direct simple search when the configured MCP endpoint resolves to the local server. Returns the original config unchanged for external endpoints.

import { resolveLocalDocsMcpSearchConfig } from "@farming-labs/docs";

const resolved = resolveLocalDocsMcpSearchConfig(
  search,           // McpDocsSearchConfig
  mcp,              // DocsLocalMcpSearchRuntimeInput | null | undefined
  requestUrl,       // string | undefined
);

resolveSearchRequestConfig now accepts an optional third options: DocsSearchRequestResolutionOptions argument. Pass { localMcp: config.mcp } to enable local-MCP detection in custom server adapters. Top-level configuration object passed to defineDocs().

ThemeToggleConfigCopy Anchor Link

DocsMarkdownSection, DocsMarkdownSectionRequest, and DocsMarkdownSectionResultCopy Anchor Link

Three interfaces that power section-addressable markdown reads. All are exported from @farming-labs/docs.

DocsMarkdownSectionCopy Anchor Link

Represents a single heading-delimited section parsed from a markdown document.

DocsMarkdownSectionRequestCopy Anchor Link

Input parameters for a section-addressable markdown request.

DocsMarkdownSectionResultCopy Anchor Link

Result returned by resolveDocsMarkdownSectionRequest.

Related functionsCopy Anchor Link

Three functions are exported from @farming-labs/docs for working with these types:

The constant DOCS_MARKDOWN_SECTION_MAX_BUDGET = 1_000_000 is the hard upper limit accepted for tokenBudget and byteBudget.

DocsMcpPageSectionIndexCopy Anchor Link

DocsMcpPageSectionIndex is the body-free section discovery metadata returned by the list_page_sections MCP tool. It is exported from @farming-labs/docs as a type alias for DocsMarkdownSectionIndex.

DocsMarkdownSectionIndexCopy Anchor Link

The docs-markdown-sections.v1 JSON payload returned by the ?sections endpoint.

DocsMarkdownSectionMetadataCopy Anchor Link

One entry in the sections array of a DocsMarkdownSectionIndex.

DocsMarkdownSectionIndexOptionsCopy Anchor Link

Options accepted by buildDocsMarkdownSectionIndex.

Section-index functionsCopy Anchor Link

Two additional functions are exported from @farming-labs/docs:

The constant DOCS_MARKDOWN_SECTION_INDEX_FORMAT = "docs-markdown-sections.v1" is the fixed format string included in every index response and advertised in /.well-known/agent.json.

DocsConfigMap, DocsConfigMapPointer, and config-map constantsCopy Anchor Link

The config-map endpoint (GET /api/docs?format=config) returns a DocsConfigMap JSON document built from the active docs config. All five framework server adapters handle this request automatically.

ConstantsCopy Anchor Link

DocsConfigMapCopy Anchor Link

The JSON response shape. Contains a format field set to "docs-config-map.v1" and a pointers array of DocsConfigMapPointer entries. Sensitive config values are redacted before serialization.

DocsConfigMapPointerCopy Anchor Link

Response headersCopy Anchor Link

Agent discovery specCopy Anchor Link

The agent discovery spec (GET /.well-known/agent.json) now includes:

{
  "$schema": "https://docs.farming-labs.dev/schema/agent-manifest.v2.json",
  "format": "farming-labs-agent-manifest.v2",
  "version": "2",
  "profile": "full",
  "profiles": {
    "full": "/.well-known/agent.json",
    "compact": "/.well-known/agent.json?profile=compact"
  },
  "api": {
    "config": "/api/docs?format=config"
  },
  "config": {
    "format": "docs-config-map.v1",
    "endpoint": "/api/docs?format=config"
  }
}

Agents that read the discovery spec can use spec.config.endpoint and spec.config.format to fetch and identify the config map without hard-coding the route.

Agents with a small first-hop budget can request ?profile=compact. The compact response is minified and replaces each published skill's companion-file inventory with fileCount; agents can then follow skills.discovery.index only when they need the expanded catalog.

The root $schema and format identify this as the Farming Labs manifest extension. Dynamic manifest responses keep Content-Type: application/json and add:

Link: <https://docs.farming-labs.dev/schema/agent-manifest.v2.json>; rel="describedby"; type="application/schema+json"

This is intentionally distinct from the opt-in A2A v1 Agent Card at /.well-known/agent-card.json.

entry and docsPathCopy Anchor Link

entry is the source route and app folder. In a Next.js app with entry: "docs", the framework expects docs pages under app/docs.

docsPath changes the public route where those pages are exposed. It defaults to the same path as entry, so app/docs/quickstart/page.mdx is served at /docs/quickstart.

For a docs-only deployment or a docs subdomain, set docsPath: "":

import { defineDocs } from "@farming-labs/docs";
import { fumadocs } from "@farming-labs/theme";

export default defineDocs({
  entry: "docs",
  docsPath: "",
  theme: fumadocs(),
});

That keeps the files under app/docs and serves them from the public root:

withDocs({}) reads docsPath from docs.config.tsx. You do not need host-specific rewrites in next.config.ts for a docs-only deployment. Attach the docs deployment to a subdomain like docs.example.com, then root URLs resolve on that subdomain.

Farm.js adapter — withDocs Vite configCopy Anchor Link

When using the @farming-labs/farmjs adapter, withDocs() accepts an optional vite field on the config object passed to it.

Both object and function forms are supported:

import { withDocs } from "@farming-labs/farmjs";

export default withDocs({
  // object form
  vite: {
    plugins: [myPlugin()],
  },
});

import { withDocs } from "@farming-labs/farmjs";

export default withDocs({
  // factory form — receives the resolved config and returns a merged object
  vite: (config) => ({ ...config, plugins: [myPlugin()] }),
});

In both cases the adapter-owned MDX transform is prepended before any plugins you provide, so MDX processing always runs first.

components is merged into the default MDX component map, so you can both add your own components and replace built-ins such as Callout, Tabs, HoverLink, or Prompt. For built-in defaults like theme.ui.components.HoverLink and theme.ui.components.Prompt, see Creating themes. For usage examples and a live demo, see Components.

telemetry and DocsTelemetryConfigCopy Anchor Link

Farming Labs maintainer telemetry for production adoption and coarse agent-optimized feature usage. It is separate from analytics: telemetry is for framework/package insight, while analytics is for project-owned product events.

Telemetry can be disabled with either:

DOCS_TELEMETRY=false
# or
DOCS_TELEMETRY_DISABLED=1

or:

telemetry: false,

Set DOCS_TELEMETRY_INGEST_KEY in both the docs runtime and self-hosted ingestion app when the endpoint should require a shared x-docs-telemetry-key header.

Telemetry may include an anonymous project identity hash, package/framework versions, deployment provider signals, site origin, enabled docs features, and coarse agent-surface events such as llms, markdown, mcp, or skill. It does not collect visitor identities, page views, device fingerprints, search queries, Ask AI questions, feedback comments, copied content, docs source content, cookies, or per-user sessions.

Local development origins are ignored even when telemetry is explicitly enabled. Requests from localhost, *.localhost, IPv4 loopback, and IPv6 loopback or wildcard binding addresses are not sent or stored.

analytics and DocsAnalyticsConfigCopy Anchor Link

Built-in product and usage event stream. Use it for page views, search activity, Ask AI request counts, feedback, page actions, machine-readable markdown reads, agent feedback routes, and MCP usage. See Analytics for the full guide and event list.

analytics: {
  onEvent(event) {
    console.info(event.type, event.properties);
  },
}

observability and DocsObservabilityConfigCopy Anchor Link

Built-in trace event stream for agent runtime debugging. Use it for Ask AI and MCP spans, timing, status, previews, errors, retries, and final handoffs. See Observability for the full guide and trace event list.

observability: {
  console: "debug",
  onEvent(event) {
    console.info(event.type, event.traceId, event.durationMs);
  },
}

OrderingCopy Anchor Link

Controls how pages are sorted in the sidebar. Three strategies are available:

"alphabetical" (default)Copy Anchor Link

Pages are sorted alphabetically by folder name. No extra configuration needed.

ordering: "alphabetical",

"numeric"Copy Anchor Link

Pages are sorted by the order field in frontmatter. Lower numbers appear first. Pages without order are sorted alphabetically after ordered pages.

ordering: "numeric",

Then in your page frontmatter:

---
title: "Installation"
order: 1
---

Slug-based (OrderingItem[])Copy Anchor Link

Pass an array of { slug, children? } objects for explicit control over page order, including nested pages.

ordering: [
  { slug: "installation" },
  { slug: "cli" },
  { slug: "configuration" },
  {
    slug: "themes",
    children: [
      { slug: "default" },
      { slug: "darksharp" },
      { slug: "pixel-border" },
      { slug: "creating-themes" },
    ],
  },
  {
    slug: "customization",
    children: [
      { slug: "colors" },
      { slug: "typography" },
      { slug: "sidebar" },
      { slug: "components" },
      { slug: "ai-chat" },
      { slug: "page-actions" },
    ],
  },
  { slug: "reference" },
],

OrderingItemCopy Anchor Link

Pages not listed in the array appear alphabetically after the listed ones.

DocsNavCopy Anchor Link

Sidebar header configuration.

nav: {
  title: "My Docs",
  url: "/docs",
},

LlmsTxtConfigCopy Anchor Link

Generated llms.txt files for agent-readable docs indexes. The root files are enabled by default; section files are opt-in and only add route handling plus discovery metadata. If a native static file already exists at the same public route, such as public/llms.txt or SvelteKit static/llms.txt, that file takes precedence and the generated output remains the fallback.

export default defineDocs({
  llmsTxt: {
    baseUrl: "https://docs.example.com",
    maxChars: {
      mode: "warn",
      chars: 50_000,
    },
    sections: [
      {
        title: "API",
        description: "Endpoint, SDK, and integration reference pages.",
        match: "/docs/api/**",
        maxChars: {
          mode: "warn",
          chars: 25_000,
        },
      },
    ],
  },
});

Default routes:

• /llms.txt
• /llms-full.txt
• /.well-known/llms.txt
• /.well-known/llms-full.txt

For sections, the route is derived from the first match value. For example, /docs/api/** creates /docs/api/llms.txt and /docs/api/llms-full.txt. Root /llms.txt lists configured sections first and keeps matching pages inside those section files.

LlmsTxtMaxCharsConfigCopy Anchor Link

LlmsTxtSectionConfigCopy Anchor Link

DocsMcpConfigCopy Anchor Link

Built-in MCP server configuration for AI clients, IDE agents, and local MCP tooling.

export default defineDocs({
  entry: "docs",
  mcp: {
    route: "/api/docs/mcp",
    name: "My Docs MCP",
    tools: {
      listDocs: true,
      listPages: true,
      listTasks: true,
      readTask: true,
      getNavigation: true,
      searchDocs: true,
      readPage: true,
      getCodeExamples: true,
      getConfigSchema: true,
      getContext: true,
    },
  },
});

DocsMcpSecurityConfigCopy Anchor Link

Authentication is opt-in. Omitting authenticate keeps HTTP MCP public, while Origin validation and the request-size limit still apply. The stdio transport is unaffected.

export default defineDocs({
  mcp: {
    security: {
      protectedResource: {
        authorizationServers: ["https://auth.example.com"],
        scopesSupported: ["docs:read"],
        requiredScopes: ["docs:read"],
      },
      authenticate: async ({ request, pathname, resource }) => {
        const user = await authenticateRequest(request, { audience: resource });
        return user
          ? { id: user.id, scopes: user.scopes, claims: { pathname, resource } }
          : null;
      },
    },
  },
});

POST bodies are capped before allowedOrigins or authenticate callbacks run. Browser preflight uses the OPTIONS handler and does not run authentication.

DocsMcpProtectedResourceConfigCopy Anchor Link

RFC 9728 protected-resource discovery for OAuth-aware HTTP MCP clients. This object only becomes active when authenticate is also configured. Omitting both keeps HTTP MCP public by default. It does not issue or validate tokens: authenticate remains responsible for signature, issuer, expiry, the exact callback resource audience, and token-derived scope validation. The callback request retains the real incoming URL and query string.

The metadata routes are public and support GET and HEAD:

• /.well-known/oauth-protected-resource/mcp for /mcp
• /.well-known/oauth-protected-resource/.well-known/mcp for /.well-known/mcp
• /.well-known/oauth-protected-resource/api/docs/mcp for the default canonical route; a custom mcp.route produces the matching path instead

When authenticate returns null, protected-resource mode returns 401 with a Bearer WWW-Authenticate challenge containing the metadata URL and required scopes. A valid principal missing a required scope receives 403 with error="insufficient_scope". Returning a Web Response bypasses framework-generated challenges and preserves the custom response. Use HTTPS for hosted MCP and authorization-server URLs; plain HTTP is appropriate only for loopback development. Each alias is a distinct OAuth resource identifier, so token audience validation must accept the exact endpoint used by the client. For Next.js, protected MCP is incompatible with basePath; host it at the origin root or terminate the MCP and RFC 9728 routes at an edge proxy. Inline MCP objects are detected automatically. Pass the live docs config to withDocs(nextConfig, docsConfig) when MCP configuration is imported, spread, or shorthand.

DocsMcpCorsConfigCopy Anchor Link

DocsMcpToolsConfigCopy Anchor Link

Default MCP surface:

• Public HTTP route: /mcp
• Well-known HTTP route: /.well-known/mcp
• Canonical HTTP route: /api/docs/mcp
• stdio command: pnpx @farming-labs/docs mcp
• Built-in tools: list_docs, list_pages, list_tasks, read_task, get_navigation, search_docs, read_page, get_code_examples, get_config_schema, get_context

list_pages and list_docs keep their agent value concise: hasContract, task, outcome, and appliesTo only. Use list_tasks to filter actionable pages by query/framework/version/package, then read_task for the full normalized contract (also available as Markdown through read_page).

Framework notes:

• Next.js: withDocs() auto-generates the default /api/docs/mcp route and public /mcp plus /.well-known/mcp rewrites

FarmDocsAdapterOptionsCopy Anchor Link

Options accepted by the second argument of withDocs(farmConfig, options) in @farming-labs/farmjs.

Production compilation is cached under <Vite cacheDir>/farming-docs/mdx-v1.json, normally node_modules/.vite/farming-docs/mdx-v1.json. Preserve that directory in CI to reuse work between builds. Source, module path, highlighting themes, mode, Node version, and compiler implementation changes invalidate the relevant entries. Missing or unusable caches fall back to compilation. Set buildCache: false to diagnose builds without cache reuse; the lower-level docsMdx() plugin accepts the same option.

import { withDocs } from "@farming-labs/farmjs";

export default withDocs({}, {
  contentRoots: ["../shared-docs"],
});

• TanStack Start / SvelteKit / Astro / Nuxt: use the generated public forwarder for MCP aliases, or add an equivalent framework hook/middleware that forwards to the built-in MCP handler
• Custom routes: set mcp.route in docs.config and update the framework public forwarder so the configured path and the actual endpoint stay aligned

See MCP Server for the route snippets and examples.

createDocsAuthoringMcpServer(options)Copy Anchor Link

Server-only factory for the separate protected authoring MCP. It is not registered by createDocsMcpServer and is never added to public framework routes.

Use runDocsAuthoringMcpStdio() or docs mcp author for local stdio. If a team wraps the factory in HTTP, the transport must require an authoring-specific OAuth scope. Public docs MCP remains read-only.

DocsAgentConfigCopy Anchor Link

agent.okf and DocsOkfConfigCopy Anchor Link

OKF metadata makes provenance and freshness explicit for machine readers. agent.okf: true derives conservative defaults; an object can provide corpus defaults and a staleness policy.

agent: {
  okf: {
    generatedBy: "software:docs-build",
    staleAfterDays: 90,
    verified: [{ by: "human:docs-team", at: "2026-08-01" }],
  },
},

Pages can override these fields with okf frontmatter. docs agent export --public writes the JSON bundle, Markdown frontmatter carries the resolved trust object, local search results expose a trust field, MCP adds get_trust_metadata, and docs doctor --agent reports expired pages.

agent.contentChanges and DocsAgentContentChangesConfigCopy Anchor Link

Body-free runtime document synchronization feed. Enabled by default on server-rendered adapters; always disabled (false) in static bundles produced by docs agent export.

Content-change feed endpointCopy Anchor Link

All five framework adapters handle GET /api/docs?audience=agent&response=changes. The response carries Content-Type: application/json, an ETag derived from the indexGeneration digest, and standard Cache-Control headers. Conditional GET with If-None-Match returns 304 when the index has not changed.

The response format is docs-content-changes.v1:

Query parameters:

The agent discovery manifest gains capabilities.contentChanges: boolean and a top-level contentChanges block describing the endpoint, supported modes, query parameters, and HTTP validators (etag: true, bodyFree: true).

DocsAgentSkillsInput and DocsAgentSkillsConfigCopy Anchor Link

type DocsAgentSkillsInput =
  | string
  | readonly string[]
  | {
      paths: string | readonly string[];
      progressiveDisclosure?: {
        maxSkillLines?: number;
        instructionTokenBudget?: number;
        maxReferenceDepth?: number;
        compatibility?: "when-needed" | "always" | "off";
        checkScripts?: boolean;
      };
    };

Each path is relative to the project root. It may name a SKILL.md, its containing skill directory, or a collection directory whose descendants contain SKILL.md files. A path may reach another project inside the same workspace, but it cannot escape the workspace. Only non-symlink regular files and directories are accepted. Published content is limited to SKILL.md and regular files below references/, scripts/, and assets/.

The project-root skill.md remains the site-level compatibility skill. It is always published alongside agent.skills, using a generated fallback when that root file is absent. Duplicate skill names are rejected.

docs doctor --agent analyzes every configured skill. docs review runs the same analysis when a configured skill, companion file, or docs config changes. Defaults follow the Agent Skills progressive-disclosure guidance: at most 500 lines, an approximately 5,000-token instruction body, and one local Markdown reference hop. The checks also report broken, escaping, or unpublished references; environment-dependent skills without compatibility; and bundled scripts without dependency and validation guidance. Override the thresholds with progressiveDisclosure.

Discovery preserves both client generations:

• /.well-known/agent-skills/index.json is the Agent Skills v0.2 index
• a skill containing only SKILL.md uses /.well-known/agent-skills/<name>/SKILL.md as its indexed skill-md artifact
• a skill with companions uses /.well-known/agent-skills/<name>.tar.gz as a deterministic indexed archive; the SHA-256 digest covers the exact archive bytes
• each safe file is also served at /.well-known/agent-skills/<name>/<path> with its own hash
• /.well-known/skills/index.json, /.well-known/skills/<name>/skill.md, and legacy companion paths support older clients
• Static Agent Bundles emit the same indexes, artifacts, direct files, and hashes
• MCP registers every file at docs://skills/<name>/<path>; text-compatible files use text, and binary files use a base64 blob

DocsAgentA2AConfigCopy Anchor Link

The generated document follows the A2A v1 Agent Card wire shape.

supportedInterfaces must contain at least one { url, protocolBinding?, protocolVersion?, tenant? } entry. Each entry defaults to A2A protocol 1.0 over HTTP+JSON. The core bindings are JSONRPC, GRPC, and HTTP+JSON; a custom binding is an absolute URI. Ordering is meaningful: the first interface is the client's preferred starting point. The deprecated interfaceUrl form cannot be combined with supportedInterfaces; it retains protocol 0.3 as its default so existing services are not silently misadvertised. Set its protocolVersion explicitly for other versions. Core interfaces and all HTTP card/authentication metadata require HTTPS outside loopback development. Custom bindings use a secure binding-appropriate absolute URL such as WSS or MQTTS.

DocsAgentA2ASkill requires id, name, description, and non-empty tags; it can also set examples, capability-specific inputModes and outputModes, and securityRequirements. It does not have a URL in A2A v1. URLs for configured Agent Skill documents and artifacts remain in /.well-known/agent-skills/index.json, its legacy compatibility index, and MCP resources. The preferred supportedInterfaces form requires explicit A2A skills. Published documentation skills are projected only when a2a.skills is omitted from the deprecated shorthand, preserving its previous behavior.

Security schemes use the A2A v1 discriminated wrappers, and each requirement maps a configured scheme name to its scope list. For example:

securitySchemes: {
  bearer: {
    httpAuthSecurityScheme: {
      scheme: "bearer",
      bearerFormat: "JWT",
    },
  },
},
securityRequirements: [
  {
    schemes: {
      bearer: { list: ["docs.read"] },
    },
  },
],

Use exactly one wrapper per named scheme. Requirement objects are alternatives; multiple schemes inside one object are required together. capabilities.extendedAgentCard: true requires at least one declared security scheme and a non-empty applicable security requirement.

When a2a is set, /.well-known/agent-card.json uses the strict v1 shape with supportedInterfaces; it does not emit legacy top-level url, protocolVersion, preferredTransport, or per-skill url fields. Capabilities default to non-streaming with no push notifications, while security metadata is omitted unless configured. When a2a is omitted, the route is not published. Do not point an advertised interface at a docs, Ask AI, or MCP route; those transports do not implement A2A.

DocsAgentEvaluationsConfigCopy Anchor Link

Each task requires id, query, and expect.relevantSources. It can set filters.framework, filters.version, filters.locale, per-task surface, and per-task tokenBudget or topK. Expectations can include allowedSources, forbiddenSources, requiredCitations, minRecallAtK, maxFirstRelevantRank, minUsefulByteRatio, scope, answer, and code-fence matches through examples. filters narrow retrieval; expect.scope asserts the framework, version, or locale of the returned sources without narrowing them first.

DocsAgentEvaluationAnswerProvider is either { provider: "callback", run } or { provider: "http", endpoint, headers?, timeoutMs? }. The callback receives the task id, query, filters, surface, context, retrieved sources, and an abort signal, but never receives the task expectations. The serializable HTTP request omits that callback-only signal. Both providers return { text, citations? }. HTTP auth is opt-in through headers, and header values never appear in reports. Managed external search and HTTP requests require allowNetwork: true, while callbacks remain explicit user code.

DocsAgentGoldenSafetyExpectationCopy Anchor Link

Optional adversarial safety assertions on a golden task. All fields are evaluator-only and must never contain real credentials or private data. Exported as DocsAgentGoldenSafetyExpectation from @farming-labs/docs.

DocsAgentGoldenPromptInjectionExpectation has markers: string[] (canary fragments that must appear in retrieved context) and an optional forbiddenAnswerText?: string[] (fragments the answer must not repeat; defaults to markers).

DocsAgentGoldenAuthenticatedContentExpectation has optional forbiddenSources?: string[] (protected URLs that public retrieval must not expose) and forbiddenText?: string[] (canary fragments that must not appear in context or answers).

DocsAgentGoldenFreshnessExpectation has optional indexGeneration?: string (expected retrieval-index generation digest) and sourceDigests?: Record<string, string> (expected full-document digest keyed by canonical page or section URL).

DocsAgentGoldenQueryVariant has kind: DocsAgentGoldenQueryVariantKind (a string such as "rephrased" or "adversarial").

All five types are exported from @farming-labs/docs and @farming-labs/docs/server.

DocsAgentGoldenExpectedExample.verification accepts "present", "syntax", or "execute". Runnable examples default to syntax verification and explicitly non-runnable examples default to presence. Execution is never inferred: it requires allowNetwork: true, verification: "execute", and an enabled codeBlocks.validate configuration in "report" mode; only an actual PASS receives credit.

Evaluation is offline by default on mcp-context, with no implicit model or network call. The configured-search and ask-ai-context surfaces exercise the real configured retrieval/context paths, and provider failures or timeouts fail instead of falling back to a different surface. Configured-search preserves provider ranking and does not supplement it with local hits. See Golden agent evaluations for a complete example.

DocsReviewConfigCopy Anchor Link

Docs Review configuration for changed docs files, score thresholds, and GitHub Actions behavior.

Omitted review config is enabled by default. Set review: false to opt out of the review command and generated workflow. The generated CI file is a small repository-root wrapper around the hosted reusable workflow at farming-labs/docs/.github/workflows/docs-review-reusable.yml@main.

export default defineDocs({
  entry: "docs",
  review: {
    ci: {
      name: "agent-docs-review",
      mode: "warn",
      annotations: true,
      comment: true,
    },
    score: {
      threshold: 85,
    },
  },
});

DocsReviewCiConfigCopy Anchor Link

DocsReviewRulesConfigCopy Anchor Link

Rule severities accept "off", "suggestion", "warn", or "error".

DocsRobotsConfigCopy Anchor Link

Runtime and generated robots.txt policy for docs and agent-readable routes. Server-rendered apps serve /robots.txt through the shared docs handler when no static file already owns that path; the CLI writes or appends a static file for static export and committed policies.

export default defineDocs({
  robots: {
    enabled: true,
    baseUrl: "https://docs.example.com",
    path: "public/robots.txt",
    ai: "allow",
  },
});

Generated policy covers the docs entry, .md routes, llms.txt, sitemap routes, AGENTS.md, skill.md, MCP aliases, agent discovery routes, and common AI crawler user agents. Existing files are preserved by default; use docs robots generate --append to add or update the managed block, or --force to replace the file.

The agent discovery JSON advertises this surface as robots.enabled, robots.route, and robots.defaultRoute, so agents can find the policy without guessing.

DocsRobotsRuleCopy Anchor Link

See CLI for docs robots generate and Configuration for the high-level setup guide.

DocsSearchConfigCopy Anchor Link

Search is enabled by default. If you do not configure anything, the docs API uses the built-in simple adapter with section-based chunking.

export default defineDocs({
  entry: "docs",
  search: true,
});

GET /api/docs?query=<query> searches the human projection by default. The exact lowercase audience=agent query parameter selects the agent projection:

GET /api/docs?query=installation&audience=agent

The human projection contains shared plus human-only content; the agent projection contains shared plus agent-only content. audience=human, a missing value, and invalid values all resolve to human. This is content projection, not authentication or authorization.

Built-in providers:

• simple — zero-config docs search with section chunking
• typesense — external Typesense collection with optional hybrid mode
• algolia — external Algolia index
• mcp — Streamable HTTP MCP endpoint that exposes a search_docs tool
• custom — your own adapter implementation

SimpleDocsSearchConfigCopy Anchor Link

search: {
  provider: "simple",
  maxResults: 8,
  chunking: {
    strategy: "section",
  },
},

TypesenseDocsSearchConfigCopy Anchor Link

search: {
  provider: "typesense",
  baseUrl: process.env.TYPESENSE_URL!,
  collection: "docs",
  apiKey: process.env.TYPESENSE_SEARCH_API_KEY!,
  adminApiKey: process.env.TYPESENSE_ADMIN_API_KEY,
  mode: "hybrid",
  embeddings: {
    provider: "ollama",
    model: "embeddinggemma",
  },
},

pnpm dlx @farming-labs/docs search sync --typesense

AlgoliaDocsSearchConfigCopy Anchor Link

search: {
  provider: "algolia",
  appId: process.env.ALGOLIA_APP_ID!,
  indexName: "docs",
  searchApiKey: process.env.ALGOLIA_SEARCH_API_KEY!,
  adminApiKey: process.env.ALGOLIA_ADMIN_API_KEY,
},

pnpm dlx @farming-labs/docs search sync --algolia

McpDocsSearchConfigCopy Anchor Link

search: {
  provider: "mcp",
  endpoint: "/mcp",
},

Relative endpoints are resolved against the current docs API request URL. That makes local setups like the Next example easy to test without hardcoding a host.

CustomDocsSearchConfigCopy Anchor Link

import { createCustomSearchAdapter, defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  search: createCustomSearchAdapter({
    name: "my-search",
    async search(query, context) {
      return context.documents
        .filter((doc) =>
          `${doc.title} ${doc.section ?? ""} ${doc.content}`.toLowerCase().includes(query.query.toLowerCase()),
        )
        .slice(0, query.limit ?? 10)
        .map((doc) => ({
          id: doc.id,
          url: doc.url,
          content: doc.section ? `${doc.title} — ${doc.section}` : doc.title,
          description: doc.description,
          type: doc.type,
          section: doc.section,
        }));
    },
  }),
});

DocsSearchAdapterCopy Anchor Link

Custom adapters receive normalized source pages and chunked search documents so you can focus on retrieval and ranking instead of rebuilding the docs scan pipeline. DocsSearchQuery.audience and DocsSearchAdapterContext.audience are both "human" | "agent" and contain the resolved request projection; context.documents is projected to match. Hosted index synchronization always uses the human projection. Custom adapters should apply query.audience while filtering and ranking provider results.

import type { DocsSearchAdapter } from "@farming-labs/docs";

export const adapter: DocsSearchAdapter = {
  name: "my-search",
  async search(query, context) {
    return context.documents.map((doc) => ({
      id: doc.id,
      url: doc.url,
      content: doc.section ? `${doc.title} — ${doc.section}` : doc.title,
      description: doc.description,
      type: doc.type,
      section: doc.section,
    }));
  },
};

DocsSearchChunkingConfigCopy Anchor Link

SearchSyncOptions — additional sync fieldsCopy Anchor Link

These options are available on the search sync CLI command and on the SearchSyncOptions interface:

DocsSearchSourcePage — additional fieldsCopy Anchor Link

Retrieval provenance types and exportsCopy Anchor Link

The following are exported from @farming-labs/docs and @farming-labs/docs/server:

HTTP cache integrity helpersCopy Anchor Link

The following are exported from @farming-labs/docs:

ETag format change: Agent-surface responses now use a strong ETag ("<64-hex-char sha256>") instead of the previous weak form (W/"…"). Clients that cache or compare ETags must update their If-None-Match logic accordingly. Conditional GET and HEAD requests with a matching strong ETag receive 304 Not Modified with the Content-Digest header preserved.

lastModified on discovery responses: DocsStandardsDiscoveryResponseOptions and CreateDocsStandardsResponseOptions both accept a new optional lastModified?: string | Date | null field. When supplied, the response includes a Last-Modified header and supports If-Modified-Since conditional requests.

DocsSearchFacetValueCopy Anchor Link

One selectable search-scope value and the number of matching source pages.

DocsSearchFacetCopy Anchor Link

Bounded values for one search-scope field.

DocsSearchFacetsResponseCopy Anchor Link

Cheap, body-free discovery response for the search scopes available in an index. Returned by GET /api/docs?audience=agent&response=facets with Cache-Control: public, max-age=60.

Two optional query parameters refine the ?response=facets request:

When facet is present, only the named field is computed and returned. Check hasMore in the response to determine whether another page is available, then pass the returned nextCursor value as cursor in the next request to retrieve it.

BuildDocsSearchFacetsOptionsCopy Anchor Link

Options accepted by buildDocsSearchFacets. Exported from @farming-labs/docs.

buildDocsSearchFacetsCopy Anchor Link

Builds a DocsSearchFacetsResponse from source pages without fetching page content. Exported from @farming-labs/docs.

import { buildDocsSearchFacets } from "@farming-labs/docs";

const response = await buildDocsSearchFacets(options);
// response.format === "docs-search-facets.v1"

DocsSearchEmbeddingsConfigCopy Anchor Link

Notes:

• search: false disables search entirely
• Search requires the docs API route; static export hides the UI because there is no server route
• GET /api/docs?query=... remains human by default; only exact audience=agent opts into agent content
• On Next.js, generated routes from withDocs() pass docsConfig directly into createDocsAPI
• MCP-backed search works with relative endpoints like /mcp or /.well-known/mcp and absolute remote endpoints like https://docs.example.com/mcp
• same-origin MCP search_docs routes receive the resolved audience; set forwardAudience: true only when a remote endpoint or custom tool supports the same argument; human-projection requests fall back to local search until then
• If MCP-backed search points at the same relative MCP route, the built-in search_docs tool falls back to simple search internally to avoid recursive loops
• On custom/manual Next routes, import createDocsAPI from @farming-labs/next/api and pass the whole config: createDocsAPI(docsConfig)

ApiReferenceConfigCopy Anchor Link

Generates API reference pages from framework route conventions or a local/remote OpenAPI JSON or YAML document.

Use route scanning when the API lives in the same project and no contract exists. Use specUrl for an existing project-relative file, absolute URL, or request-relative URL.

The native renderer uses the same normalized operation model as Markdown, Ask AI, search, and MCP. It includes operation search and grouping, stable operation permalinks, version switching, parameters, request and response schemas, authentication metadata, copyable cURL examples, and responsive light/dark UI. Each operation also includes a Try it tab that executes requests in the browser and renders status, timing, response headers, and formatted response bodies.

The request console starts from the operation's first server, parameters, media type, and schema examples. Readers can change the server, path/query/header parameters, request body, browser credential mode, and supported bearer, basic, or API-key authentication values before sending. Authentication values stay in memory and are never persisted by Farming Labs. Cookie parameters remain browser-managed; choose Include cookies when the target API relies on them. POST, PUT, PATCH, and DELETE operations require an explicit confirmation before Send request is enabled.

The interactive console is part of the native "farming-labs" renderer. Selecting "scalar" or "fumadocs" preserves that renderer's own request tooling and presentation.

apiReference: {
  enabled: true,
  path: "api-reference",
  routeRoot: "api",
  exclude: ["/api/internal/health", "internal/debug"],
},

apiReference: {
  enabled: true,
  path: "api-reference",
  specUrl: "./openapi.yaml",
  renderer: "farming-labs",
},

Pin an alternate renderer when you want its existing presentation:

apiReference: {
  enabled: true,
  specUrl: "./openapi.yaml",
  renderer: "scalar", // or "fumadocs" in Next.js
},

Pass typed Fumadocs playground and runtime options on Next.js:

import { fumadocsRenderer } from "@farming-labs/next/fumadocs-renderer";
import { authProviders } from "./app/api-reference/auth-providers";

apiReference: {
  enabled: true,
  specUrl: "./openapi.yaml",
  renderer: fumadocsRenderer({
    playground: {
      enabled: true,
      authProviders,
    },
    oauthRedirectUrl: "/api/docs/oauth",
    proxyUrl: "/api/docs/proxy",
    showResponseSchema: true,
    schemaUI: { showExample: true },
  }),
},

The helper accepts Fumadocs createOpenAPIPage() options together with the proxyUrl and disableCache server options. Browser-side providers and callbacks must not contain secrets. Proxy and OAuth URLs must point to application-owned routes.

apiReference: {
  enabled: true,
  path: "api-reference",
  specUrl: "https://petstore3.swagger.io/api/v3/openapi.json",
},

apiReference: {
  enabled: true,
  path: "api-reference",
  versions: {
    v1: { specUrl: "./openapi/v1.yaml", label: "Version 1" },
    v2: {
      specUrl: "./openapi/v2.yaml",
      label: "Version 2",
      overlays: ["./openapi/public.overlay.yaml"],
    },
  },
  defaultVersion: "v2",
},

When specUrl is set, routeRoot and exclude are ignored and the API reference is rendered from the configured document instead. Project-relative sources must remain inside the project root; use an explicit file: URL for a trusted local contract outside it.

versions is mutually exclusive with specUrl and top-level overlays. Every version has a stable /{path}/{version} UI route and GET /api/docs?format=openapi&version={version} schema identity. The unversioned routes use defaultVersion. Discovery, llms.txt, and the API catalog publish all version identities.

Overlay sources support local files, file: URLs, absolute HTTP(S) URLs, and request-relative URLs. Farming Labs supports OpenAPI Overlay 1.0.x and 1.1.x, applies overlays and actions in their declared order, and evaluates targets with RFC 9535 JSONPath before $ref bundling. Invalid overlay documents, invalid or unmatched targets, incompatible updates, and invalid final OpenAPI contracts are reported as source diagnostics. Overlay sources use the same timeout, size, and local containment protections as OpenAPI sources.

$ref supports internal and external URI references with JSON Pointer fragments. External local or remote JSON/YAML documents are fetched once per build and rewritten into the returned OpenAPI document, so downstream renderers and projections receive a self-contained contract. References from project-relative entry documents stay inside the project root. The synchronous builder cannot load HTTP(S) references; use buildApiReferenceOpenApiDocumentAsync() or a framework route for mixed local/remote contracts. Named anchors and $dynamicRef resolution are not supported yet.

Normalized OpenAPI operation modelCopy Anchor Link

Server integrations can import buildNormalizedOpenApiModel and its NormalizedOpenApi* types from @farming-labs/docs/server. The additive API produces stable operation IDs and slugs, method and path selectors, tags, parameters, request bodies, responses, schemas, examples, servers, and the security schemes used by each operation. Farming Labs uses the same model for OpenAPI-backed MCP tools, keeping renderer and agent projections aligned.

DocsOpenApiMcpConfigCopy Anchor Link

An operation can also opt in with x-farming-labs-mcp: true. Security requirements and only the referenced components.securitySchemes are included in the tool metadata. Credentials remain server-owned and are applied after parsed tool parameters.

Every request and redirect is DNS-checked before egress. HTTPS, public-network destinations, bounded response streaming, rate limits, and concurrency limits are enforced by default. Development servers on private networks must opt in explicitly; never enable those exceptions for untrusted OpenAPI documents or model-supplied destinations.

This does not remove the framework route requirement on adapters that do not own the application server. Next.js and Farm.js serve the route through withDocs(). TanStack Start, SvelteKit, Astro, and Nuxt still need their /{path} handler files so the docs app has a route that serves the generated API reference page.

When output: "export" is used in Next.js, the generated API reference route is skipped automatically because it requires a server route handler.

Scanned route conventions:

• Next.js: app/api/**/route.ts and src/app/api/**/route.ts
• TanStack Start: src/routes/api.*.ts and nested route files inside the configured route root
• Farm.js: app/api/**/route.ts and src/app/api/**/route.ts
• SvelteKit: src/routes/api/**/+server.ts or +server.js
• Astro: src/pages/api/**/*.ts or .js
• Nuxt: server/api/**/*.ts or .js

Minimal route handlers for non-Next frameworks:

import { createFileRoute } from "@tanstack/react-router";
import { createTanstackApiReference } from "@farming-labs/tanstack-start/api-reference";
import docsConfig from "../../docs.config";

const handler = createTanstackApiReference(docsConfig);

export const Route = createFileRoute("/api-reference/")({
  server: {
    handlers: {
      GET: handler,
    },
  },
});

Create a second src/routes/api-reference.$.ts file with the same handler and createFileRoute("/api-reference/$").

import { createSvelteApiReference } from "@farming-labs/svelte/api-reference";
import config from "$lib/docs.config";

export const GET = createSvelteApiReference(config);

Create src/routes/api-reference/[...slug]/+server.ts with the same GET export.

import { createAstroApiReference } from "@farming-labs/astro/api-reference";
import config from "../../lib/docs.config";

export const GET = createAstroApiReference(config);

Create src/pages/api-reference/[...slug].ts with the same GET export.

import { defineApiReferenceHandler } from "@farming-labs/nuxt/api-reference";
import config from "~/docs.config";

export default defineApiReferenceHandler(config);

Create server/routes/api-reference/[...slug].ts with the same default export.

ChangelogConfigCopy Anchor Link

Generates changelog listing and entry pages from dated MDX folders inside the docs content tree.

changelog: {
  enabled: true,
  path: "changelogs",
  contentDir: "changelog",
  title: "Changelog",
  description: "Latest product updates and release notes.",
  search: true,
},

With entry: "docs" and the config above, the public pages render at:

• /docs/changelogs
• /docs/changelogs/2026-03-04

When you use withDocs(), the route files are generated automatically. There is no separate __changelog.generated.tsx file to maintain.

ChangelogFrontmatterCopy Anchor Link

Optional frontmatter fields for each changelog entry:

---
title: "OpenAPI mode is now the default"
description: "The docs example now ships with the faster API reference experience."
version: "v0.1.13"
tags: ["api-reference", "next"]
---

GithubConfigCopy Anchor Link

GitHub repository configuration. Enables "Edit on GitHub" links in page footers.

// Simple
github: "https://github.com/my-org/my-docs",

// Monorepo
github: {
  url: "https://github.com/my-org/monorepo",
  branch: "main",
  directory: "apps/docs/docs",
},

The "Edit on GitHub" link only appears when both url and directory are provided.

onCopyClick and CodeBlockCopyDataCopy Anchor Link

Optional callback on DocsConfig. Fired when the user clicks the copy button on a code block — in addition to copying to the clipboard. Use it for analytics, logging, or custom behavior. See Code block copy callback for setup (Next.js / TanStack Start vs SvelteKit / Astro / Nuxt).

CodeBlockCopyDataCopy Anchor Link

Argument passed to onCopyClick(data: CodeBlockCopyData).

import type { CodeBlockCopyData } from "@farming-labs/docs";
import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  onCopyClick(data: CodeBlockCopyData) {
    // data.title, data.content, data.url, data.language
    console.log("Copied:", data.language, data.title ?? "(no title)");
  },
});

feedback, FeedbackConfig, AgentFeedbackConfig, and feedback payloads`Copy Anchor Link

Optional docs page feedback UI. When enabled, a built-in "Good / Bad" prompt is rendered at the end of the page and emits a feedback payload when the user clicks one of the buttons.

FeedbackConfigCopy Anchor Link

DocsFeedbackDataCopy Anchor Link

import type { DocsFeedbackData } from "@farming-labs/docs";
import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  feedback: {
    enabled: true,
    onFeedback(data: DocsFeedbackData) {
      console.log("Feedback:", data.value, data.slug, data.url);
    },
  },
});

This docs site persists feedback through a local Next.js route at website/app/api/feedback/route.ts, backed by the DocsFeedback Prisma model in website/prisma/schema.prisma.

See Page feedback for framework-specific notes. The built-in UI does not require a separate client bridge file.

AgentFeedbackConfigCopy Anchor Link

Optional machine-facing feedback routes for agents, scripts, or evaluation flows.

Notes:

• agent feedback routes are enabled by default; set feedback: false or feedback: { agent: false } to opt out
• feedback.agent does not enable the human footer UI by itself
• the request body always uses { context?, payload }
• without feedback.agent.onFeedback, valid submissions return { ok: true, handled: false }
• submitted feedback is not added to Ask AI prompts or docs search context by the framework
• in Next.js, withDocs() adds the public route rewrites automatically
• Astro, SvelteKit, TanStack Start, and Nuxt expose the same feedback contract through the shared /api/docs?feedback=agent query route
• the shared /api/docs handler is still the source of truth, so ?feedback=agent also works
• agents can discover APIs through GET or HEAD /.well-known/api-catalog (RFC 9727), and can discover integrity-checked skills through GET or HEAD /.well-known/agent-skills/index.json
• agents should discover site identity, locale config, capability flags, search, active markdown routes, Accept: text/markdown, Signature-Agent support, JSON-LD structured data, llms.txt, OpenAPI schema routes, sitemap routes, robots.txt, AGENTS.md, skill.md, skills, MCP, and feedback routes with GET /.well-known/agent.json; GET /.well-known/agent is the public fallback and GET /api/docs/agent/spec is the canonical framework route

DocsAgentFeedbackContextCopy Anchor Link

DocsAgentFeedbackDataCopy Anchor Link

analyzeDocsAgentFeedback() converts recurring failed reports into evidence clusters, golden-task drafts, issue drafts, and a draft docs PR description. readDocsAgentFeedbackFile() accepts JSON arrays/objects and JSON Lines. Both are exported from @farming-labs/docs/server; the CLI wrapper is docs agent feedback --input <path> [--write].

import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  feedback: {
    agent: {
      enabled: true,
      route: "/api/docs/agent/feedback",
      async onFeedback(data) {
        console.log(data.context?.page, data.payload);
      },
    },
  },
});

{
  "context": {
    "page": "/docs/installation",
    "source": "md-route"
  },
  "payload": {
    "task": "install docs in an existing Next.js app",
    "understanding": "partial",
    "outcome": "implemented",
    "confidence": 0.78
  }
}

Quick checks:

curl "http://127.0.0.1:3000/.well-known/agent.json"

curl -I "http://127.0.0.1:3000/.well-known/api-catalog"

curl "http://127.0.0.1:3000/.well-known/agent-skills/index.json"

curl "http://127.0.0.1:3000/AGENTS.md"

curl "http://127.0.0.1:3000/skill.md"

curl "http://127.0.0.1:3000/api/docs/agent/feedback/schema"

curl -X POST "http://127.0.0.1:3000/api/docs/agent/feedback" \
  -H "content-type: application/json" \
  -d '{"payload":{"task":"demo","outcome":"implemented"}}'

ThemeToggleConfigCopy Anchor Link

Light/dark mode toggle in the sidebar.

// Show toggle (default)
themeToggle: true,

// Hide toggle, follow system preference
themeToggle: false,

// Hide toggle, force dark mode
themeToggle: { enabled: false, default: "dark" },

// Show toggle with system option
themeToggle: { mode: "light-dark-system" },

BreadcrumbConfigCopy Anchor Link

Breadcrumb navigation above page content.

breadcrumb: true,              // show (default)
breadcrumb: false,             // hide
breadcrumb: { enabled: false },  // hide

SidebarConfigCopy Anchor Link

Sidebar visibility and customization. See Sidebar for the full guide including custom sidebar components.

Folder landing pages can still override both of those with frontmatter:

---
sidebar:
  folderIndexBehavior: "toggle"
---