# Documentation

> An AI-native documentation framework for Next.js, TanStack Start, SvelteKit, Astro, and Nuxt.

## CLI

URL: https://docs.farming-labs.dev/docs/cli

Scaffold, upgrade, export static Agent Bundles, compact agent docs, validate code blocks, generate sitemaps and robots.txt, sync search, and run MCP

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:ff98ba0ac661af3e
settingsHash=fnv1a64:e50e89e221226fc3
outputHash=fnv1a64:c95a0dd048e26147
generatedAt=2026-08-20T10:20:45.204Z
-->
URL: /docs/cli
LLM index: /llms.txt
Description: Scaffold, upgrade, export static Agent Bundles, compact agent docs, validate code blocks, generate sitemaps and robots.txt, sync search, and run MCP
Related: /docs/configuration, /docs/guides/agent-friendly-docs, /docs/customization/sitemaps, /docs/customization/llms-txt

# CLI

## CLI task

Task: Plan and validate fenced MDX code blocks with the Farming Labs docs CLI.

Expected result: The validation plan identifies runnable examples before any execution occurs, and
the follow-up validation reports each configured example without executing unrelated prose.

Applies to Next.js, TanStack Start, SvelteKit, Astro, and Nuxt projects using
`@farming-labs/docs` version `>=0.2.60`.

Prerequisites:

- Run commands from the docs project root with its package manager available.
- Install project dependencies before invoking the local `docs` binary.
- Review the plan before allowing configured runners to execute examples.

```bash title="terminal"
pnpm exec docs codeblocks validate --plan
pnpm exec docs codeblocks validate
pnpm exec docs codeblocks validate --json
```

Verification: confirm the plan lists the expected fenced examples and that validation exits without
an unhealthy or unverified command. Recovery: correct the reported file, line, command, or runner
configuration, then rerun `--plan` before executing validation again.

## Workflow selection

- Use `init` for a new docs app or to add docs to an existing supported app.
- Preview package changes with `upgrade --dry-run` before upgrading.
- Use `agent compact --stale` for generated page context and `agent export --check` for bundles.
- Use `doctor --agent` for site-wide readiness, `doctor --api` for OpenAPI contract and projection
  diagnostics, and `review --ci` for changed documentation.
- Use `openapi diff <baseline> <current>` to reject breaking API changes; add `--json` for CI.
- Use `openapi sdk <source> --output <path>` to generate a typed client; use `--check` in CI.
- Use `mcp` for local stdio clients; hosted clients should connect to the configured HTTP route.

For a published release use `pnpm dlx @farming-labs/docs <command>`; use `pnpm exec docs <command>` only after installing dependencies. For non-interactive scaffold: `init --template <framework> --name <dir>`; omit `--name` to be prompted. Plain `init` asks whether to modify the current app or create a fresh project.

After a mutating command run `pnpm exec docs doctor --agent`; expected result is a loaded `docs.config.ts`, `docs.config.tsx`, or `src/lib/docs.config.ts` with no hard failure. After changing `apiReference`, also run `pnpm exec docs doctor --api`; it validates local or remote JSON/YAML sources, references, versions, overlays, renderer compatibility, and generated operation projections without executing operations. Before publishing a contract, run `pnpm exec docs openapi diff <baseline> <current>`; it loads local or remote JSON/YAML sources and exits non-zero on breaking changes by default. Generate a deterministic client with `pnpm exec docs openapi sdk <source> --output <path>` and verify committed output with `--check`. For SvelteKit or Astro append `--config src/lib/docs.config.ts`. Prefer `--dry-run` for previews and `--check` for generated outputs.

If `pnpm` cannot find `docs`, install dependencies or use `pnpm dlx`. If the wrong config loads, return to project root or pass `--config <path>`; do not copy flags between unrelated subcommands.

**Main commands:**
- `init` — create a new docs app or add docs to an existing app
- `upgrade` — bump docs packages
- `agent export` — materialize complete machine-readable surface for static hosting
- `agent compact` — generate sibling `agent.md` files from resolved docs pages
- `agents generate` — write root and static `AGENTS.md` instructions
- `skills scaffold` — compile structured page `agent` contracts into an installable Agent Skill
- `doctor` — audit agent readiness, reader quality, or OpenAPI contract health
- `openapi diff` — compare OpenAPI contracts and gate breaking changes
- `openapi sdk` — generate a typed TypeScript fetch client from an OpenAPI contract
- `review` — review docs changes locally or in GitHub Actions
- `codeblocks validate` — plan and validate runnable MDX code fences
- `mcp` — run the built-in docs MCP server over stdio
- `search sync` — push docs content into Typesense or Algolia
- `sitemap generate` — write `sitemap.xml`, `sitemap.md`, and `docs/sitemap.md`
- `robots generate` — write or append an agent-friendly `robots.txt`

## Quick Start

### From scratch

```bash title="terminal"
pnpm dlx @farming-labs/docs init --template next --name my-docs
pnpm dlx @farming-labs/docs init --template tanstack-start --name my-docs
pnpm dlx @farming-labs/docs init --template nuxt --name my-docs
pnpm dlx @farming-labs/docs init --template sveltekit --name my-docs
pnpm dlx @farming-labs/docs init --template astro --name my-docs
```

### Existing project

```bash title="terminal"
pnpm dlx @farming-labs/docs init
```

The CLI: detects framework from `package.json`, asks for theme, entry path (default `docs`), aliases, global CSS, optional i18n, generates files, installs `@farming-labs/*` packages, optionally adds Docs Cloud support.

### Upgrade

```bash title="terminal"
pnpm dlx @farming-labs/docs upgrade
```

Pass `--framework` if detection is ambiguous.

### MCP server locally

```bash title="terminal"
pnpx @farming-labs/docs mcp
pnpm exec docs mcp --config src/lib/docs.config.ts
```

HTTP MCP route (start Next example first):
```txt
http://127.0.0.1:3000/mcp
http://127.0.0.1:3000/.well-known/mcp
```

### Search sync

```bash title="terminal"
pnpm dlx @farming-labs/docs search sync --typesense
```

Loads environment files and uploads configured docs.


---

## Analytics

URL: https://docs.farming-labs.dev/docs/cloud/analytics

How connected Docs Cloud projects store runtime analytics events

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:7034d577d38a7462
settingsHash=fnv1a64:72be2461542d7a95
outputHash=fnv1a64:71082a9b0c66a490
generatedAt=2026-08-20T10:20:45.215Z
-->
# Analytics

## Analytics task

Task: Connect a docs runtime to Docs Cloud analytics without exposing user-authored inputs by default.

Expected result: Runtime events are attributed to the intended Docs Cloud project and appear in its analytics dashboard.

## Analytics prerequisites

- A Docs Cloud workspace has an imported project or custom analytics project.
- The dashboard-provided project ID is available for the runtime environment.
- Consent and retention policies are defined before enabling includeInputs.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Analytics verification

- Run pnpm dlx @farming-labs/docs cloud check --analytics --no-network. Expected: The analytics runtime, Cloud setting, and project environment checks pass.
- Trigger a test page view and confirm the event is attributed to the expected project in Docs Cloud.
- Failure: Events do not appear in the dashboard.
- Recovery: Copy the project ID from Docs Cloud again and use the framework-specific public or server environment variable documented on this page.
- Rollback: Disable cloud.analytics or set the documented analytics-enabled environment flag to false.

## Analytics agent guidance

Use this page when the user asks about this topic: Docs Cloud analytics, project identity, managed Cloud analytics delivery, event storage, dashboard analytics, includeInputs privacy, and customer onEvent callbacks.
Keep answers technical and avoid exposing internal transport details as public setup steps. If the user asks how to deploy a hosted preview, point to /docs/cloud/deploy. If the user asks about runtime event options outside Cloud, point to /docs/customization/analytics.


---

## Deploy

URL: https://docs.farming-labs.dev/docs/cloud/deploy

Deploy a Docs Cloud preview from docs.config.ts, docs.json, and a project API key

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:21f42c17384037d9
settingsHash=fnv1a64:063b4c9a14696a17
outputHash=fnv1a64:c156b3ca29676945
generatedAt=2026-08-20T10:20:45.224Z
-->
# Deploy

## Deploy task

Task: Configure a repository and deploy a hosted Docs Cloud preview.

Expected result: Docs Cloud accepts the synchronized contract and returns a preview deployment URL.

Exact implementation:

```bash title="terminal"
pnpm dlx @farming-labs/docs deploy --json
```
## Deploy prerequisites

- The workspace has Docs Cloud access and a connected project.
- DOCS_CLOUD_API_KEY is available through the shell, .env.local, or CI secrets.
- The cloud deploy setting is enabled in docs.config.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Deploy verification

- Run pnpm dlx @farming-labs/docs cloud check --deploy. Expected: Config, docs.json freshness, API key, deploy scopes, and hosted API checks pass.
- Confirm the JSON deploy response includes the expected project and preview URL.
- Failure: The CLI reports a missing or invalid API key.
- Recovery: Set the environment variable named by cloud.apiKey.env and never put the raw value in committed config.
- Rollback: Restore the previous docs.json and docs.config cloud block from version control.

## Deploy agent guidance

Use this page when the user asks about this topic: Docs Cloud deploys, hosted preview docs, Docs Cloud API keys, docs.config.ts cloud config, docs.json sync, publish modes, and deploy troubleshooting.
Keep answers technical and grounded in the commands and config on this page. Never suggest committing raw API key values to docs.config.ts, docs.json, or source control.
If the request is about hosted analytics, project identity, or event storage, point to /docs/cloud/analytics. If the request is about the docs.json contract itself, point to /docs/guides/docs-json.


---

## Docs Cloud

URL: https://docs.farming-labs.dev/docs/cloud

Overview of Docs Cloud projects, deploys, analytics, and the docs.json contract

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:ea4599fe0d071f98
settingsHash=fnv1a64:54aabfe997b31e1c
outputHash=fnv1a64:3bbb07e4687e854e
generatedAt=2026-08-20T10:20:45.233Z
-->
# Docs Cloud

## Docs Cloud Sync repository contract task

Task: Connect a Farming Labs docs project to the Docs Cloud repository contract.

Expected result: docs.config and docs.json agree, secrets remain outside source control, and Cloud checks can inspect the project.

Exact implementation:

```bash title="terminal"
pnpm dlx @farming-labs/docs cloud sync
```
## Docs Cloud Sync repository prerequisites

- The repository already contains a working Farming Labs docs project.
- The team has Docs Cloud access and knows which project should own the integration.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Docs Cloud Sync repository verification

- Run pnpm dlx @farming-labs/docs cloud check --no-network. Expected: The local config loads and docs.json is current with no raw API key value.
- Failure: docs.json is stale after editing docs.config.
- Recovery: Run cloud sync again and review the generated diff before committing it.
- Rollback: Restore the previous docs.config and docs.json from version control.

## Docs Cloud agent guidance

Use this page when the user asks about this topic: Docs Cloud overview, Cloud project shape, Docs Cloud API keys, docs.config.ts cloud config, docs.json, hosted deploys, analytics, and publish defaults.
Keep answers grounded in the pages linked from this overview. Never suggest committing raw API key values to docs.config.ts, docs.json, or source control.
If the request is about hosted preview deploys, point to /docs/cloud/deploy. If the request is about hosted analytics, project identity, or event storage, point to /docs/cloud/analytics.
If the request is about the docs.json contract itself, point to /docs/guides/docs-json. If the request is about every config option, point to /docs/configuration.
## Docs Cloud Sync repository contract command

Run `pnpm dlx @farming-labs/docs cloud sync` to generate the `docs.json` repository contract. Commit `docs.json`, but keep the raw Docs Cloud API key outside source control.

```bash title="terminal"
pnpm dlx @farming-labs/docs cloud sync
```

## Docs Cloud sync prerequisites

Before Cloud sync, confirm the repository has a working docs config and that the Docs Cloud API key is available only through the configured environment variable.

## Docs Cloud sync verification

After Cloud sync, review the generated `docs.json`, run `pnpm dlx @farming-labs/docs cloud check --no-network`, and confirm no raw key was written to source control.


---

## Configuration

URL: https://docs.farming-labs.dev/docs/configuration

Everything lives in docs.config.ts

# Configuration

You are an agent helping someone configure `@farming-labs/docs`.

Use this machine-oriented page when the user needs implementation guidance for `docs.config.ts` or `docs.config.tsx`, especially when they are asking what field to set, what defaults apply, or how a feature behaves across frameworks.

## Priorities

1. Keep the answer grounded in the actual `defineDocs()` surface.
2. Preserve exact option names:
   - `entry`
   - `theme`
   - `components`
   - `pageActions`
   - `agent`

| `contentChanges`   | `/api/docs?audience=agent&response=changes` | Body-free content synchronization feed (`docs-content-changes.v1`) |
   - `codeBlocks`
   - `search`
   - `ai`
   - `mcp`
   - `llmsTxt`
   - `sitemap`
   - `robots`
   - `apiReference`
   - `staticExport`
   - `i18n`
   - `metadata`
   - `og`
3. If the config contains JSX, prefer `docs.config.tsx`.
4. If the user only needs machine-readable page content, prefer `.md` routes or MCP `read_page` over scraping HTML.
5. For Next.js docs routes, mention `Signature-Agent` when the user wants agents to read canonical URLs as markdown.

## Guidance

- When the user wants to add a custom MDX component, point them to `components` in `defineDocs()`.
- When they want to change default props for a built-in component like `HoverLink`, point them to `theme.ui.components`.
- When they want AI-facing behavior, distinguish between:
  - `ai` for Ask AI / chat

  - `agent.contentChanges` for the body-free runtime document synchronization feed (`GET /api/docs?audience=agent&response=changes`)

  - `agent.compact` for defaults used by `docs agent compact`
  - `agent.evaluations` for golden tasks that measure retrieval, context, answers, examples, and
    budgets in `docs doctor` and `docs review`
  - `codeBlocks.validate` for planning and validating fenced MDX code blocks
  - `mcp` for the built-in MCP server, including default tools like `list_docs`, `search_docs`,
    `read_page`, `get_code_examples`, `get_config_schema`, and `get_context`
  - `llmsTxt` for crawler-friendly site summaries
  - `sitemap` for XML and Markdown maps with canonical URLs and freshness dates
  - `robots` plus `docs robots generate` for a static crawler and AI-agent access policy
  - markdown routes for page-level machine-readable content
- When they ask about generated API docs, use `apiReference`. Set `specUrl` to a project-relative
  JSON/YAML file or URL when a contract exists; otherwise use framework route scanning. The native
  `"farming-labs"` renderer is the cross-framework default and uses the normalized operation model
  for search, versions, schemas, responses, auth metadata, and cURL. Scalar remains available on
  every framework and Fumadocs on Next.js. On Next.js, use `fumadocsRenderer()` from
  `@farming-labs/next/fumadocs-renderer` to pass typed `playground`, `oauthRedirectUrl`, `proxyUrl`,
  schema UI, and other upstream renderer options. Browser-side providers must not contain secrets.
  Contracts may use Swagger 2.0 or OpenAPI 3.0–3.2;
  bounded internal/external `$ref` documents are bundled per build and project-relative files stay
  inside the project root. Use URL-safe `versions` with one `defaultVersion`, or ordered Overlay
  1.0/1.1 sources applied before reference resolution; invalid sources and targets are reported.

### Executable evaluation fixture

Use this deterministic runnable block when agent evaluations need to verify the configured
code-block runner without credentials or external services:

```js title="codeblocks-smoke.js" runnable
const metadata = { framework: "nextjs", runnable: true };

if (!metadata.runnable) {
  throw new Error("Expected runnable metadata");
}

console.log("metadata ok");
```

- When the user asks about runtime document synchronization or incremental content updates, point to `agent.contentChanges`. Enabled by default on server-rendered adapters; always `false` in static bundles produced by `docs agent export`. The endpoint is `GET /api/docs?audience=agent&response=changes` and returns a `docs-content-changes.v1` payload with `indexGeneration`, `mode` (`snapshot`, `delta`, or `reset`), `resetRequired`, `documentCount`, and `added`/`modified`/`removed` arrays. Supply `since=<indexGeneration>` from a previous response to receive a delta. ETag and `If-None-Match` conditional requests are supported.

- When they ask about static hosting, mention `staticExport: true`. Note that setting `staticExport: true` also signals to the diagnostics endpoint (`GET /api/docs?format=diagnostics`) that server-side features such as search and AI are unavailable, so diagnostics tooling can skip those checks.
- When they need to edit `docs.config.ts` through MCP, prefer `get_config_schema` before suggesting
  config changes.
- When they need compact retrieval through MCP, prefer `get_context` with an explicit token budget;
  use `read_page.section` when they already know the exact heading.
- Golden evaluations default to the local `mcp-context` surface. There is no implicit model,
  network request, or command execution. `configured-search` measures the actual `search` provider,
  and `ask-ai-context` measures the production Ask AI retrieval/context assembly path.
- Non-simple search providers and the built-in HTTP answer provider require
  `agent.evaluations.allowNetwork: true`. Provider failures fail the task instead of falling back to
  local search. `searchTimeoutMs` defaults to 30 seconds per retrieval attempt; transient timeouts,
  fetch failures, rate limits, and server errors are retried twice with bounded backoff. Optional
  HTTP authentication belongs in `answer.headers`; header values are never included in reports.
- An answer provider is opt-in. Use `{ provider: "callback", run }` for explicit user code or
  `{ provider: "http", endpoint, headers?, timeoutMs? }` for the managed HTTP contract. Add
  `expect.answer` only when answer text and answer citations should be scored; context citations are
  reported as context evidence, not mislabeled as model-answer citations.
- `filters` constrain retrieval. Use `expect.scope` to assert returned framework, version, or locale
  without pre-filtering away a wrong result.
- Expected examples support `verification: "present" | "syntax" | "execute"`. Runnable examples
  default to syntax, non-runnable examples default to presence, and execution requires an explicit
  execute expectation, `allowNetwork: true`, and enabled `codeBlocks.validate` report mode. Skips
  never count as passes.
- When they ask about reading time, note that `readingTime` is opt-in (`enabled: true` required).
  The `includeCode` field inside `ReadingTimeConfig` defaults to `false`, which means fenced and
  inline code blocks are stripped before counting words so the label reflects human prose length.
  Recommend `includeCode: true` only for code-heavy guides where examples make up a large part of
  the page and should count toward the estimate. Do not recommend setting it globally when prose
  length is the primary signal the team cares about.
- When the user asks which routes are available to agents, include `GET /api/docs?format=diagnostics` alongside `GET /api/docs?format=config`. The agent discovery spec (served at `/.well-known/agent.json`) now includes a `diagnostics` key pointing to `/api/docs?format=diagnostics`. That endpoint returns a `DocsDiagnostics` payload (format: `"docs-diagnostics.v1"`) describing enabled features and any configuration issues. All five framework adapters handle this route automatically — no additional setup is required.
- Include `GET`/`HEAD /.well-known/api-catalog` for RFC 9727 API discovery and
  `GET`/`HEAD /.well-known/agent-skills/index.json` for SHA-256 Agent Skills discovery. These are
  additive to the existing Farming Labs manifest and require no config flag.
- Identify the Farming Labs manifest by
  `$schema: "https://docs.farming-labs.dev/schema/agent-manifest.v1.json"` and
  `format: "farming-labs-agent-manifest.v1"`. Dynamic responses link the Draft 2020-12 schema with
  `rel="describedby"`. Do not confuse it with the separate, opt-in A2A Agent Card at
  `/.well-known/agent-card.json`.

## Agent discovery spec routes

The discovery spec exposed at `/.well-known/agent.json` and `/.well-known/agent` includes the following API route keys:

| Key                | Default route                           | Description                                                     |
| ------------------ | --------------------------------------- | --------------------------------------------------------------- |
| `config`           | `/api/docs?format=config`               | Machine-readable config map (`docs-config-map.v1`)              |
| `diagnostics`      | `/api/docs?format=diagnostics`          | Feature status and configuration issues (`docs-diagnostics.v1`) |
| `apiCatalog`       | `/.well-known/api-catalog`              | RFC 9727 JSON Linkset                                           |
| `agentSkillsIndex` | `/.well-known/agent-skills/index.json` | Hashed Agent Skills discovery index                             |

Agents that previously read only `config` should also check `diagnostics` to detect misconfigured or disabled features before attempting to use them.
The API catalog is intentionally absent when `staticExport: true` or `llmsTxt.apiCatalog: false`;
Agent Skills discovery remains available in both cases.

## Framework notes

- Next.js uses `withDocs()` and can expose page-level `.md`, `Accept: text/markdown`, and `Signature-Agent` markdown routes automatically.
- Farm.js serves docs and API-reference routes through `withDocs()`.
- TanStack Start, SvelteKit, Astro, and Nuxt use the shared docs API markdown mode through their framework-specific docs route setup.
- Do not switch frameworks unless the user explicitly asks to migrate.

## Follow-up pages

- Use [/docs/installation](/docs/installation) when the user is still wiring the framework into an app or has not created the docs route yet.
- Use [/docs/cli](/docs/cli) when they want scaffolding, upgrades, code block validation, sitemap generation, robots generation, search sync, or MCP commands instead of manual setup.
- Use [/docs/reference](/docs/reference) when they need the full typed `defineDocs()` surface or nested option details, including the `DocsDiagnostics` types and constants.
- Use [/docs/customization](/docs/customization) when the question moves from config into layout, sidebar, colors, or page-level polish.
- Use [/docs/themes](/docs/themes) when they are choosing a preset theme or building their own.
- Use [/docs/customization/components](/docs/customization/components) when the question is really about `components` or `theme.ui.components`.
- Use [/docs/customization/agent-primitive](/docs/customization/agent-primitive) when the user wants `.md` routes, hidden `<Agent>` content, or sibling `agent.md` overrides.
- Use [/docs/customization/mcp](/docs/customization/mcp) when they want machine-readable access through the built-in MCP server.
- Use [/docs/customization/llms-txt](/docs/customization/llms-txt) when they need crawler-friendly summaries for AI systems.
- Use [/docs/customization/sitemaps](/docs/customization/sitemaps) when they need `sitemap.xml`, `sitemap.md`, `/docs/sitemap.md`, static export files, or `lastmod` behavior.
- Use [/docs/customization/ai-chat](/docs/customization/ai-chat) when they are configuring Ask AI or retrieval-backed chat.
- Use [/docs/customization/page-actions](/docs/customization/page-actions) when they want Copy Markdown or Open in LLM actions.
- Use [/docs/token-efficiency](/docs/token-efficiency) when they care about retrieval quality, context size, or agent cost.

## Suggested exploration order

1. Confirm the runtime and config file path first.
2. Verify `entry`, `contentDir`, `nav`, and `theme` before discussing advanced features.
3. Move to `search`, `ai`, `mcp`, `pageActions`, `llmsTxt`, `sitemap`, or `robots` only after the base project shape is correct.
4. Use customization and theme pages once routing and content structure are stable.
5. Use markdown routes, sitemaps, `robots.txt`, `agent.compact`, MCP, and token-efficiency docs when the user is optimizing for agents or machine-readable access.

## Output style

- Prefer short, exact config examples.
- Preserve the user's framework if they already gave one.
- Do not invent config keys that are not part of `defineDocs()`.


---

## Contributing

URL: https://docs.farming-labs.dev/docs/contributing

How to contribute to @farming-labs/docs

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:b5dc93bd0362d4de
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:0ba4aa7e16e15e72
generatedAt=2026-08-20T10:20:45.259Z
-->
# Contributing

## Contributing task

Task: Prepare a focused, tested contribution to the Farming Labs docs monorepo.

Expected result: The change follows repository conventions, includes proportional tests or docs, and is ready for pull-request review.

Exact implementation:

```bash title="terminal"
   pnpm --dir website dev
   ```
## Contributing prerequisites

- Read the repository AGENTS.md and the skill that matches the affected subsystem.
- Install the pinned pnpm workspace dependencies and identify the smallest affected package set.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs, @farming-labs/next, @farming-labs/tanstack-start, @farming-labs/svelte, @farming-labs/astro, @farming-labs/nuxt.

## Contributing verification

- Run formatting, lint, type checking, and the smallest relevant test suite required by the changed packages. Expected: Every required check exits successfully and the worktree contains only intentional changes.
- Failure: A package-specific test passes but another adapter regresses.
- Recovery: Run the shared conformance tests and the affected adapter type checks before requesting review.
- Rollback: Revert only the contribution's files and restore generated artifacts from their source templates.

## Contributing agent guidance

Start by reading the repository `AGENTS.md` and the matching file under
`skills/farming-labs/*/SKILL.md`, then branch from `main` with a focused `fix/`, `feat/`, or `chore/`
name. Install the pinned workspace dependencies from the repository root and keep edits inside the
smallest affected package, example, or `website/app/docs/` page set.

For a documentation preview, run `pnpm --dir website dev` and open the changed route. Core or
theme work may also require `pnpm build`; adapter agent-surface changes must run the shared
conformance test described at `/docs/guides/adapter-agent-conformance`. The expected handoff is a
clean, intentional diff with formatting, type checks, and the smallest relevant tests passing.

If a package test passes but another adapter regresses, run the shared conformance tests and the
affected adapter type check before review. If formatting touches unrelated files, remove those
mechanical changes instead of including them in the pull request.


---

## Agent Primitive

URL: https://docs.farming-labs.dev/docs/customization/agent-primitive

Author human- and agent-specific page context, generated AGENTS.md instructions, and machine-readable route discovery.

# Agent Primitive

You are reading the machine-oriented override for `/docs/customization/agent-primitive`.

Use this page when you need the page-level authoring contract for agent-facing docs in
`@farming-labs/docs`.

## Audience Controls

1. `Agent`
   - Embed `<Agent>...</Agent>` inside `page.mdx`
   - Hidden in the normal docs UI
   - Included in agent-projected output when there is no sibling `agent.md`

2. `Human`
   - Embed `<Human>...</Human>` inside `page.mdx`
   - Included in rendered HTML and public search
   - Removed from agent-projected output

3. `Audience`
   - Use `<Audience only="agent">...</Audience>` as the explicit form of `Agent`
   - Use `<Audience only="human">...</Audience>` as the explicit form of `Human`
   - Only static `"agent"` and `"human"` values are supported; `docs review` reports dynamic values and spread props
   - Invalid or missing values remain shared rather than being silently deleted

4. `agent.md`
   - Place a sibling `agent.md` beside `page.mdx`
   - Becomes the full machine-readable output for that page
   - Preferred by MCP `read_page("/docs/customization/agent-primitive")`

Content without an audience wrapper is shared. `Agent` remains an optional shorthand and does not
support `only="human"`; use `Human` or `Audience` for human-only content.

## Projection Contract

Use the human projection for rendered docs HTML and public docs search. Use the agent projection
for Markdown routes and API responses, Ask AI retrieval/context, MCP, `llms-full.txt`, and static
agent exports. The compact `llms.txt` file contains discovery metadata and links to agent-projected
Markdown rather than page bodies. Sitemaps contain route metadata rather than page bodies, so
audience blocks do not appear in them.

Audience filtering is content shaping, not authentication or authorization. Do not put secrets or
private data in any audience block or `agent.md`; machine-readable routes and source files can be
public.

## When To Choose Which

- Choose `Agent` when the human page should stay canonical and only needs extra machine context
- Choose `Human` when a visual explanation or UI note should not consume agent context
- Choose `Audience` when one explicit component is easier to scan than two shorthands
- Choose `agent.md` when agents need a shorter, stricter, or more operational document

## Automation

If the team wants to generate or refresh page-level `agent.md` files automatically, use
`docs agent compact`.

- it resolves the same page-level machine document with this order: `agent.md`, the agent
  projection of audience-aware page markdown, then shared page markdown
- it writes sibling `agent.md` files that become the new `.md`, docs API, and MCP source
- it is useful when authors start with `<Agent>` blocks and later want a shorter, fully
  machine-focused document

Example:

```bash
pnpm exec docs agent compact customization/agent-primitive
pnpm exec docs agent compact --all
```

## Validation

- Human page: `/docs/customization/agent-primitive`
- Markdown route: `/docs/customization/agent-primitive.md`
- Canonical markdown request: `/docs/customization/agent-primitive` with `Signature-Agent`
- API route: `/api/docs?format=markdown&path=customization/agent-primitive`
- MCP read target: `/docs/customization/agent-primitive`

After adding or changing page-level audience controls, see [the CLI docs](/docs/cli) and the `Doctor`
section for the audit workflow. Use it to confirm the machine-facing layer is actually discoverable
and to watch the explicit audience coverage improve as more routes gain audience blocks or sibling
`agent.md` files.

## Let Agents Discover The Spec

Use `GET` or `HEAD /.well-known/api-catalog` for RFC 9727 API discovery. Use `GET` or
`HEAD /.well-known/agent-skills/index.json` for Agent Skills discovery; each entry points to the
exact `SKILL.md` bytes covered by its `sha256:` digest.

Fetch `GET /.well-known/agent.json` before choosing how to read or report on the docs. If that is
unavailable, fall back to `GET /.well-known/agent` and then `GET /api/docs/agent/spec`.

This is the Farming Labs documentation-discovery extension. Verify
`$schema: "https://docs.farming-labs.dev/schema/agent-manifest.v1.json"` and
`format: "farming-labs-agent-manifest.v1"` before consuming it. Dynamic responses also associate
the Draft 2020-12 schema with `Link: <...>; rel="describedby"; type="application/schema+json"`.
Do not parse this document as A2A; an explicitly configured A2A service uses the separate,
opt-in `/.well-known/agent-card.json` route.

The spec is generated from `docs.config` and includes:

- site title, description, docs entry, and base URL
- configured locales and the `lang`/`locale` query parameters
- capability flags for the API catalog, Agent Skills discovery, markdown, structured data, MCP,
  search, feedback, `AGENTS.md`, skills, `llms.txt`, and sitemap
- shared docs API route
- search endpoint and query parameter
- markdown route patterns, `Accept: text/markdown`, and `Signature-Agent` support
- JSON-LD structured data schema and fields
- `llms.txt` and `llms-full.txt` routes
- `sitemap.xml`, `sitemap.md`, `/docs/sitemap.md`, and `/.well-known/sitemap.md` routes when enabled
- `AGENTS.md` route, well-known alias, API format, compatibility aliases, and root file convention
- `skill.md` route, well-known alias, API format, and root file convention
- RFC 9727 catalog and Agent Skills index/artifact routes
- Skills CLI install command and recommended skill metadata
- MCP enabled state, endpoint, server name, version, and tool toggles
- agent feedback enabled state, schema route, and submit route

Use the returned routes instead of hard-coding defaults when the project customizes MCP or feedback.

## Bootstrap Prompt Pattern

Add this block to the docs landing page or another route that agents are likely to read first:

```mdx
<Agent>
You are reading this docs site as an implementation agent.

Before implementing from these docs, fetch `/.well-known/agent.json` from the same origin. If that
is unavailable, fall back to `/.well-known/agent`, then `/api/docs/agent/spec`. Use that JSON as the
source of truth for the docs entry path, markdown route pattern, search endpoint, MCP endpoint,
`llms.txt` routes, `sitemap.xml` / `sitemap.md` / `/docs/sitemap.md` routes, `AGENTS.md`, `skill.md`, skills install command, locale
handling, and feedback endpoints.

Recommended bootstrap flow:

1. Fetch `/.well-known/agent.json`, then fall back to `/.well-known/agent` and `/api/docs/agent/spec`.
2. Read `spec.skills.route` or `spec.skills.wellKnown` when a concise site skill is useful.
3. Use `spec.markdown.pagePattern`, `spec.markdown.acceptHeader`, or `spec.markdown.signatureAgentHeader` to read relevant docs pages as markdown.
4. Use `spec.search.endpoint` when you need to find the right page first.
5. Use `spec.sitemap.markdown.route` for the semantic docs map and `spec.sitemap.xml.route` for canonical freshness when sitemap is enabled.
6. Fetch `spec.robots.route` when you need to confirm crawler and AI-agent access policy.
7. Use `spec.mcp.wellKnownEndpoint`, `spec.mcp.publicEndpoint`, or `spec.mcp.endpoint` when MCP is enabled and your environment supports MCP.
8. If `spec.feedback.enabled` is true, fetch `spec.feedback.schema` before submitting to `spec.feedback.submit`.

Do not scrape the HTML page when markdown, search, sitemap, robots, MCP, or `llms.txt` routes are
available in the spec.
</Agent>
```

## Feedback Contract

Agent feedback is enabled by default unless the site opts out. Use these default endpoints:

- schema: `/api/docs/agent/feedback/schema`
- submit: `/api/docs/agent/feedback`

The shared docs API also accepts the same feature through query parameters:

- schema: `/api/docs?feedback=agent&schema=1`
- submit: `/api/docs?feedback=agent`

Fetch the schema endpoint first and use the returned schema as the source of truth for the body you
submit. Do not assume the payload fields are fixed, because the site can customize
`feedback.agent.schema`.

For the default schema, the body looks like:

```json
{
  "context": {
    "page": "/docs/customization/agent-primitive",
    "source": "md-route"
  },
  "payload": {
    "task": "understand page-level agent docs",
    "outcome": "implemented"
  }
}
```

If the project customizes `feedback.agent.route` or `feedback.agent.schemaRoute`, use those
configured paths instead of the defaults.

## Skills

This repo also ships reusable Agent Skills for broader workflows that are larger than one page.
The hosted site serves `/AGENTS.md`, `/.well-known/AGENTS.md`, and `/api/docs?format=agents` as
coding-agent instructions. If a root `AGENTS.md` or `AGENT.md` exists beside `docs.config.ts`, that
file is served. Otherwise the framework generates a fallback from config.

The hosted site serves `/skill.md`, `/.well-known/skill.md`, and `/api/docs?format=skill` as a
concise route discovery skill. If a root `skill.md` exists beside `docs.config.ts`, that file is
served. Otherwise the framework generates a fallback from config.

Install them with:

```bash
npx skills add farming-labs/docs
```

Use the page-level audience controls in this doc when the context belongs to a single route.
Use a skill when the task spans multiple pages or product areas such as:

- setup and installation
- CLI onboarding
- docs configuration
- page actions
- theme creation

Relevant skills in this repo include `getting-started`, `cli`, `configuration`, `page-actions`,
`ask-ai`, and `creating-themes`.

## Authoring Reminder

Do not duplicate whole pages into `<Agent>` blocks. Keep `Agent` additive and concise. Use `Human`
for UI-only explanation, and leave content unwrapped when it serves both audiences.
Use `agent.md` when the machine-readable page needs to diverge substantially.


---

## Ask AI

URL: https://docs.farming-labs.dev/docs/customization/ai-chat

Add a RAG-powered AI chat to your documentation

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:90a70f0c0a38a3ce
settingsHash=fnv1a64:7a85fb928fd52635
outputHash=fnv1a64:ded084b41bf41852
generatedAt=2026-08-20T10:20:45.282Z
-->
# Ask AI

## Ask AI task

Task: Enable Ask AI with an explicit provider, retrieval path, and secret-handling model.

Expected result: A docs question returns a grounded streamed answer with citations from the configured documentation corpus.

## Ask AI prerequisites

- A working docs runtime and searchable content are already available.
- The selected provider credentials are stored in environment variables rather than committed config.
- Decide whether the browser may call the provider directly or must use a same-origin server proxy.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Ask AI verification

- Ask a question answered by one known page. Expected: The response streams successfully, cites the expected page, and does not expose provider credentials to the browser.
- Failure: The answer is plausible but cites no documentation.
- Recovery: Verify the search provider, maxResults, MCP endpoint when useMcp is enabled, and the selected page's machine-readable content.
- Rollback: Set ai.enabled to false and remove provider credentials and any custom chat route added for the integration.

## Ask AI agent guidance

Configure top-level `ai` in `docs.config.ts` or `docs.config.tsx`, and keep provider credentials in
environment variables. Next.js reads `OPENAI_API_KEY` directly; TanStack Start, SvelteKit, and Astro
pass the server-only value through `src/lib/docs.server.ts`, while Nuxt reads it through Nitro.

Set `ai.useMcp: true` only when Ask AI should retrieve with `search_docs` from `mcp.route` (default
`/api/docs/mcp`). Success means a question answered by a known page streams and cites that page. If
the answer has no citation, check the search provider, `ai.maxResults`, MCP endpoint, and the page's
machine-readable content. Move credential-bearing requests behind the same-origin docs API when the
browser reports authentication or CORS errors; `staticExport: true` intentionally hides Ask AI.


---

## Analytics

URL: https://docs.farming-labs.dev/docs/customization/analytics

Track product and usage events from docs, search, AI, feedback, agent, and MCP routes

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:1d7dae95f1156a3b
settingsHash=fnv1a64:72be2461542d7a95
outputHash=fnv1a64:8dfc9629f7835ae0
generatedAt=2026-08-20T10:20:45.290Z
-->
# Analytics

## Analytics task

Task: Analytics

Expected result: Track product and usage events from docs, search, AI, feedback, agent, and MCP routes

## Analytics verification



## Analytics agent guidance

Top-level `analytics` records product usage, not step-level agent traces. `analytics: true` writes
events with the `[@farming-labs/docs:analytics]` prefix; `analytics.onEvent` forwards normalized
`DocsAnalyticsEvent` objects to a custom destination.

Leave `analytics.includeInputs` false unless the project has consent and a retention policy; paths,
counts, status, durations, and model IDs remain available without raw queries or questions. Verify
the integration by triggering a page, search, Ask AI, Markdown, or MCP action and checking its exact
event type and `source`. Retrieval, model, or tool spans inside one request belong to
`observability` instead.


---

## Colors

URL: https://docs.farming-labs.dev/docs/customization/colors

Override any color token from config

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:868072b335139257
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:3ef315ed2e252ae5
generatedAt=2026-08-20T10:20:45.296Z
-->
# Colors

## Colors task

Task: Colors

Expected result: Override any color token from config

## Colors verification



## Colors agent guidance

Theme color overrides live under `theme(...).ui.colors` in `docs.config.ts` or `docs.config.tsx`;
only the required keys belong there, without replacing the preset CSS for one token. Each value must
be a valid CSS color and maps to its documented `--color-fd-*` variable, such as `primary` to
`--color-fd-primary`.

Verify that the target variable changes while omitted tokens still come from the preset in light and
dark mode. If an override produces the wrong theme behavior, omitting that key restores the preset
default; the replacement value can be valid hex, rgb, hsl, or oklch.


---

## Components

URL: https://docs.farming-labs.dev/docs/customization/components

Override built-in or add custom MDX components

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:5c3143c5a326a02e
settingsHash=fnv1a64:063b4c9a14696a17
outputHash=fnv1a64:359366d4cee9d620
generatedAt=2026-08-20T10:20:45.310Z
-->
# Components

## Components task

Task: Register a custom MDX component or override a built-in component without breaking page rendering.

Expected result: The component is available in MDX, receives the intended props, and renders in the configured docs theme.

Exact implementation:

```tsx title="docs.config.tsx"
import { defineDocs } from "@farming-labs/docs";
import { pixelBorder } from "@farming-labs/theme/pixel-border";
import { InfoCard } from "./components/info-card";

export default defineDocs({
  // ...theme, nav, etc.
  components: {
    InfoCard,
  },
});
```
## Components prerequisites

- The project has a working docs.config file and an existing docs page for verification.
- Use docs.config.tsx when registration includes JSX.
- Confirm whether the requirement needs a config component override or a theme default-prop override.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Components verification

- Build the docs app and render an MDX page that uses the component. Expected: The build succeeds, the component renders once with the documented props, and existing built-ins still work.
- Failure: MDX reports that the custom component is undefined.
- Recovery: Export the component, register the exact case-sensitive name in docs.config.tsx, and restart the dev server.
- Rollback: Remove the component registration and restore the previous built-in or theme defaults.

## Components agent guidance

For Next.js or TanStack Start, create the React component and register its exact case-sensitive name
under top-level `components` in `docs.config.ts[x]`; MDX can then use that name without an import.
Astro, SvelteKit, and Nuxt use their adapter-native component registration instead. Use
`theme.ui.components` only to change default props for a built-in; a top-level entry such as
`components.HoverLink` replaces that component across the React-rendered docs pages.

Build the docs app and render one MDX page with the documented props while confirming existing
built-ins still work. If MDX reports an undefined component, check its export and registration name
and restart the dev server. If JSX makes the config fail to parse, rename `docs.config.ts` to
`docs.config.tsx`. Remove a built-in override to restore the previous component; when removing a
custom component, remove its MDX usages too.


---

## llms.txt

URL: https://docs.farming-labs.dev/docs/customization/llms-txt

Auto-generate llms.txt and llms-full.txt for LLM-friendly documentation

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:575801915b4e04d5
settingsHash=fnv1a64:3fa80ff29bd1598e
outputHash=fnv1a64:34ab5873e4b3807d
generatedAt=2026-08-20T10:20:45.323Z
-->
# llms.txt

## llms.txt task

Task: llms.txt

Expected result: Auto-generate llms.txt and llms-full.txt for LLM-friendly documentation

## llms.txt verification



## llms.txt agent guidance

`llmsTxt` is enabled by default. Verify `/llms.txt`, `/llms-full.txt`, their `/.well-known/` aliases,
and the `format=llms` or `format=llms-full` docs API responses before adding route files.
`llmsTxt.baseUrl` corrects the generated origin, `llmsTxt.sections` divides a large corpus, and
`llmsTxt.maxChars` limits compact output.

Static deployment uses `pnpm exec docs agent export --public`; committed output is checked with
`pnpm exec docs agent export --check`. A native `public/llms.txt` (or SvelteKit `static/llms.txt`)
intentionally wins over generated fallback content, so that file is the first place to inspect or
delete when runtime configuration appears to have no effect.


---

## MCP Server

URL: https://docs.farming-labs.dev/docs/customization/mcp

Expose your docs as MCP tools and resources over stdio, /mcp, or /.well-known/mcp

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:3e985393450bab74
settingsHash=fnv1a64:4d5874ba9e62babc
outputHash=fnv1a64:7878d01f4b26d792
generatedAt=2026-07-30T09:43:36.464Z
-->
# MCP Server

## MCP Server task

Task: Expose the docs MCP server over stdio or Streamable HTTP with optional explicit authentication.

Expected result: An MCP client initializes successfully and can discover, search, and read the configured documentation resources.

## MCP Server prerequisites

- The docs API and framework public forwarder are already wired.
- Choose stdio for local use or Streamable HTTP for a shared endpoint.
- Keep HTTP public by default and add security.authenticate only when the deployment requires access control.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## MCP Server verification

- Run pnpm exec docs doctor --agent. Expected: MCP access and discovery/config/schema consistency pass.
- Initialize an MCP client and call list_docs followed by read_page for a known route. Expected: The initialize request succeeds and both tools return structured content for the configured docs corpus.
- Failure: The client receives 404 from /mcp or /.well-known/mcp.
- Recovery: Align mcp.route with the framework public forwarder and keep the documented aliases pointing at the canonical handler.
- Rollback: Set mcp.enabled to false, remove client configuration, and restore custom route or authentication wiring.

## MCP Server agent guidance

MCP is enabled and public by default: `/mcp` and `/.well-known/mcp` forward to the canonical
`/api/docs/mcp` handler. Add `mcp.security.authenticate` only for private docs; return a principal to
continue or `null` for `401`. Add `mcp.security.protectedResource.authorizationServers` and scopes
only when OAuth-aware clients need RFC 9728 discovery.

Run `pnpm exec docs doctor --agent`, then initialize a client and call `list_docs` followed by
`read_page` for a known route. A `404` can mean MCP is disabled, static export omitted the server
route, or the canonical handler and public forwarder are missing or disagree; use doctor output to
distinguish them. Repeated `401` responses mean the callback is not returning a valid principal;
`403` with `insufficient_scope` means the principal lacks a configured required scope. Local-only
clients can avoid HTTP routing with `pnpm exec docs mcp`.

The public docs MCP never contains write tools. For an operator-controlled authoring session, run
`pnpm exec docs mcp author --branch-prefix docs/`. It restricts reads and writes to documentation
files under `contentDir`, requires a current SHA-256 before overwriting, and exposes branch,
preview, doctor, diff, and feedback-analysis tools. Draft-PR publishing is not registered unless the
operator also passes `--allow-publish`; keep that server on local stdio or behind a separate
authoring-scoped OAuth transport.


---

## Observability

URL: https://docs.farming-labs.dev/docs/customization/observability

Trace Ask AI and MCP runs with span IDs, timing, status, previews, errors, and callbacks

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:9d3948c775786cbd
settingsHash=fnv1a64:72be2461542d7a95
outputHash=fnv1a64:5a926dd8952106a9
generatedAt=2026-08-20T10:20:45.332Z
-->
# Observability

## Observability task

Task: Observability

Expected result: Trace Ask AI and MCP runs with span IDs, timing, status, previews, errors, and callbacks

## Observability verification



## Observability agent guidance

Top-level `observability` covers steps inside Ask AI and MCP runs. `observability: true` writes the
`[@farming-labs/docs:observability]` stream; its console mode shows local traces, while
`observability.onEvent` forwards `DocsObservabilityEvent` objects.

Verify one trace contains a shared `traceId`, child `spanId` values, status, and `durationMs`, with
Ask AI lifecycle events or `tool.call`/`tool.result` for MCP. Built-in previews exclude raw user
text; separate raw `input` fields are omitted unless `includeInputs` is enabled. If only `page_view`,
`search_query`, `api_ai_request`, or `mcp_tool` appears, inspect `analytics.onEvent`; those are usage
events rather than runtime spans.


---

## OG Images

URL: https://docs.farming-labs.dev/docs/customization/og-images

Dynamic and static Open Graph images for docs — how they work, what context is passed, and how the docs website generates them

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:6fa5aff3470aecd8
settingsHash=fnv1a64:1b5212557ba75927
outputHash=fnv1a64:7df800a8c45ebe93
generatedAt=2026-08-20T10:20:45.344Z
-->
# OG Images

## OG Images task

Task: Configure and verify static or dynamic Open Graph images for docs pages.

Expected result: Every tested docs page resolves an absolute OG image URL whose response is a valid social preview image.

Exact implementation:

```tsx title="api/og/route.ts"
import { ImageResponse } from "next/og";
import { NextRequest } from "next/server";

export const runtime = "edge";

export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);
  const title = searchParams.get("title") ?? "@farming-labs/docs";
  const description = searchParams.get("description") ?? "";

  return new ImageResponse(
    (
      <div
        style={{
          width: "100%",
          height: "100%",
          display: "flex",
          flexDirection: "column",
          justifyContent: "space-between",
          backgroundColor: "#000000",
          padding: "50px 80px",
          // ... fonts, branding, borders
        }}
      >
        {/* Branding strip */}
        <span style={{ fontFamily: "monospace", color: "rgba(255,255,255,0.4)" }}>
          @farming-labs/docs
        </span>

        {/* Page context: title and description from frontmatter */}
        <div>
          <h1 style={{ fontSize: 68, fontWeight: 700, color: "#fff" }}>
            {title}
          </h1>
          {description && (
            <p style={{ fontSize: 22, color: "rgba(255,255,255,0.4)" }}>
              {description}
            </p>
          )}
        </div>

        {/* Footer: site label + CTA */}
        <div style={{ display: "flex", justifyContent: "space-between" }}>
          <span>documentation · docs.farming-labs.com</span>
          <span>get started →</span>
        </div>
      </div>
    ),
    { width: 1200, height: 630 }
  );
}
```
## OG Images prerequisites

- The docs site has an absolute public base URL available to metadata generation.
- Choose dynamic generation for page-aware images or commit a static image for a fixed preview.
- Applies to framework nextjs; version >=0.2.60; package @farming-labs/docs, @farming-labs/next.

## OG Images verification

- Fetch the generated metadata and its og:image URL for a representative docs page. Expected: The URL is absolute and the image request returns HTTP 200 with an image content type.
- Failure: Social previews use a relative or unreachable image URL.
- Recovery: Configure an absolute sitemap, llms.txt, robots, AI docs, or site base URL and retest generated metadata.
- Rollback: Restore the previous og configuration and remove the dynamic route or static image introduced by the change.

## OG Images agent guidance

For Next.js dynamic previews, set `og.enabled`, `og.type: "dynamic"`, and `og.endpoint` in
`docs.config.ts`, then implement `GET` in `app/api/og/route.tsx` when the response contains JSX.
Read the `title` and `description` query parameters and return a 1200x630 image. For a reliable
per-page override, set explicit `openGraph` and `twitter` frontmatter.

Fetch a representative page's absolute `og:image` URL and require HTTP 200 with an image content
type. If a dynamic image is stale, hard-refresh or add a cache-busting query. If rendering throws,
limit the route to fonts, layout, and CSS supported by `ImageResponse`; restore the previous `og`
config and remove the new route or static image to roll back.


---

## Page Actions

URL: https://docs.farming-labs.dev/docs/customization/page-actions

Add copy, LLM, MCP connection, and Agent Skills actions to docs pages

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:f58201f70663f345
settingsHash=fnv1a64:72be2461542d7a95
outputHash=fnv1a64:64fef2cb27439f75
generatedAt=2026-08-20T10:20:45.354Z
-->
# Page Actions

## Page Actions task

Task: Configure Copy Markdown and Open in LLM actions for docs pages.

Expected result: The selected actions appear in the intended position and produce canonical Markdown or provider URLs for the current page.

## Page Actions prerequisites

- Machine-readable Markdown routes work for the docs entry.
- Configure github.url before using provider templates that require a GitHub source URL.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Page Actions verification

- Open a docs page, copy Markdown, and exercise each configured external provider action. Expected: Copied text matches the configured format and every provider URL contains the canonical current-page target.
- Failure: Copy Markdown returns HTML or an empty response.
- Recovery: Verify the page .md route and shared docs API Markdown format before changing the button.
- Rollback: Disable pageActions or restore the previous provider, alignment, and copy settings.

## Page Actions agent guidance

Edit top-level `pageActions` in `docs.config.ts` or `docs.config.tsx`. Enable
`copyMarkdown` for clipboard output and `openDocs` for provider links; prefer
`openDocs.target: "markdown"` so the prompt receives the current machine-readable page. Configure
top-level `github` before using the `github` target or `{githubUrl}` template value.

First verify the page's `.md` route, then copy Markdown and open every configured provider from that
page. If copying returns HTML or an empty body, repair the Markdown route rather than the button. If
a provider URL contains an unresolved token, use only the documented template placeholders and
check the required `github.url`. To remove both actions, delete `pageActions` or set both
`copyMarkdown: false` and `openDocs: false`.


---

## Customization

URL: https://docs.farming-labs.dev/docs/customization

Colors, typography, sidebar, components, analytics, telemetry, observability, agent primitives, robots.txt, OG images, AI chat, and page actions

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:e24affa1d337935b
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:14aaecb13600c381
generatedAt=2026-08-20T10:20:45.362Z
-->
# Customization

## Customization task

Task: Customization

Expected result: Colors, typography, sidebar, components, analytics, telemetry, observability, agent primitives, robots.txt, OG images, AI chat, and page actions

## Customization verification



## Customization agent guidance

Treat this page as a configuration router. Visual tokens and built-in default props belong under
`theme.ui`, replacement MDX components use top-level `components`, and runtime features use
top-level `ai`, `analytics`, `telemetry`, `observability`, `mcp`, `llmsTxt`, `sitemap`, and
`pageActions` in `docs.config.ts`.

The linked feature page is the source of truth because each option has different defaults and
verification steps. A layout or CSS file is unnecessary for an option documented as config-only. A
committed crawl policy comes from `pnpm exec docs robots generate`; audience-specific page content
follows the Agent Primitive workflow.


---

## Sidebar

URL: https://docs.farming-labs.dev/docs/customization/sidebar

Title, icons, collapsible groups, and styling

# Sidebar

Use this page when the user asks about sidebar titles, icons, collapsible groups, ordering, or styling.

Keep answers grounded in the documented `sidebar`, `nav`, `icons`, `order`, and folder structure options. If the request moves beyond sidebar behavior, point to the closest related configuration or customization docs instead of inventing config.


---

## Sitemaps

URL: https://docs.farming-labs.dev/docs/customization/sitemaps

Generate sitemap.xml, sitemap.md, and docs/sitemap.md for crawlers, agents, and static exports

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:c75827353d89371c
settingsHash=fnv1a64:0a67cd1f3384201a
outputHash=fnv1a64:3255515be7b4e3ee
generatedAt=2026-08-20T10:20:45.376Z
-->
# Sitemaps

## Sitemaps task

Task: Generate and verify XML and Markdown sitemaps for runtime and static docs deployments.

Expected result: Canonical sitemap routes or generated files list the expected docs pages with valid links and configured freshness metadata.

Exact implementation:

```bash title="terminal"
pnpm exec docs sitemap generate
pnpm exec docs robots generate
```
## Sitemaps prerequisites

- The docs content tree and public base URL are configured.
- Decide whether the deployment serves runtime routes or needs generated public files.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Sitemaps verification

- Run pnpm exec docs sitemap generate --check. Expected: Generated sitemap artifacts match the current docs tree.
- Fetch sitemap.xml, sitemap.md, /docs/sitemap.md, and /.well-known/sitemap.md from a running site. Expected: Each route returns the configured format and links to known canonical docs pages.
- Failure: The check reports stale generated files.
- Recovery: Regenerate from the same docs config and commit the manifest and public output together.
- Rollback: Restore the previous sitemap config and regenerate or remove only the sitemap artifacts it owned.

## Sitemaps agent guidance

Use this page when the task is to customize or troubleshoot generated sitemaps. Runtime sitemap
routes are enabled by default; use `sitemap: false` only when a project must opt out.

Default public routes:
- `/sitemap.xml`
- `/sitemap.md`
- `/docs/sitemap.md`
- `/.well-known/sitemap.md`

Static export command:
- `pnpm exec docs sitemap generate`

Pair with `pnpm exec docs robots generate` when the static host should also publish an explicit
crawler and AI-agent access policy at `/robots.txt`.

The command writes `.farming-labs/sitemap-manifest.json` plus public sitemap files unless
`--manifest-only` is used. Lastmod dates come from `git log -1` for each page source path first,
then filesystem mtime as a fallback. Preloaded adapters also use the manifest as the stable source
for JSON-LD `dateModified`.


---

## Telemetry

URL: https://docs.farming-labs.dev/docs/customization/telemetry

Production maintainer telemetry for @farming-labs/docs adoption and agent-surface usage

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:27054689be801ecc
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:aad652137c192ee9
generatedAt=2026-08-20T10:20:45.382Z
-->
# Telemetry

## Telemetry task

Task: Telemetry

Expected result: Production maintainer telemetry for @farming-labs/docs adoption and agent-surface usage

## Telemetry verification



## Telemetry agent guidance

Use this page when the user asks about this topic: Farming Labs maintainer telemetry, production
package adoption, opt-out configuration, DOCS_TELEMETRY, and coarse agent-surface usage. Keep this
separate from project-owned analytics.


---

## Typography

URL: https://docs.farming-labs.dev/docs/customization/typography

Fonts, heading sizes, weights, and spacing

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:d09604014837a203
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:65b300952ebb86ca
generatedAt=2026-08-20T10:20:45.388Z
-->
# Typography

## Typography task

Task: Typography

Expected result: Fonts, heading sizes, weights, and spacing

## Typography verification



## Typography agent guidance

Font families live at `theme.ui.typography.font.style.sans` and `.mono`; `h1` through `h4`, `body`,
and `small` accept the documented `size`, `weight`, `lineHeight`, and `letterSpacing` fields in
`docs.config.ts` or `docs.config.tsx`.

For Next.js Google Fonts, CSS variables originate in `app/layout.tsx`; their generated variable
classes belong on `<body>`, and the typography config references those exact names. Verify the
computed sans and mono families on the rendered page. If the fallback font remains, check that the
body class includes both font variables and that the config spelling matches before changing type
sizes or weights.


---

## Adapter Agent Conformance

URL: https://docs.farming-labs.dev/docs/guides/adapter-agent-conformance

Validate that a framework adapter exposes the same agent-readable documentation contract as the first-party adapters

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:452409f4999cf5d1
settingsHash=fnv1a64:1b5212557ba75927
outputHash=fnv1a64:a83cd1b06f2d79ce
generatedAt=2026-08-20T10:20:45.398Z
-->
# 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`.


---

## How to Write Agent-Friendly Docs

URL: https://docs.farming-labs.dev/docs/guides/agent-friendly-docs

A practical playbook for writing documentation that reads well for humans while still giving agents enough structure to implement, verify, and recover

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:d065d00a89874ed0
settingsHash=fnv1a64:4d5874ba9e62babc
outputHash=fnv1a64:61659a4471a71139
generatedAt=2026-08-20T10:20:45.416Z
-->
# How to Write Agent-Friendly Docs

## How to Write Agent-Friendly Docs task

Task: Turn an implementation-heavy docs page into a measurable agent-ready task contract.

Expected result: The page is retrievable for its target task, cites canonical sources, declares applicability, includes executable evidence, and stays within its context budget.

## How to Write Agent-Friendly Docs prerequisites

- Start with accurate human-facing documentation and a concrete user task.
- Identify the framework, package version, required files, commands, side effects, and likely failure modes.
- Keep secrets and authorization-only content out of all audience projections.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## How to Write Agent-Friendly Docs verification

- Run pnpm exec docs doctor --agent. Expected: The page is task-complete and its configured golden task passes retrieval, citation, scope, example, and budget checks.
- Compare rendered HTML, the .md route, search, Ask AI context, MCP read_page, llms-full.txt, and static export. Expected: Every surface applies the same audience policy and exposes the same structured contract.
- Failure: The doctor gives context credit to repeated generic guidance.
- Recovery: Replace boilerplate with page-specific paths, commands, expected results, and recovery instructions.
- Rollback: Restore the previous page frontmatter and audience content, then remove its golden task if the contract is withdrawn.

## How to Write Agent-Friendly Docs agent guidance

When authoring agent-friendly docs with `@farming-labs/docs`, prioritize these in order:

1. clear page frontmatter with `title`, `description`, and `related`
2. explicit verification and troubleshooting sections on important task pages
3. additive `<Agent>` blocks for machine-only hints when the human page is still canonical
4. sibling `agent.md` only when the machine-readable page needs a full rewrite
5. machine surfaces like `.md`, `Signature-Agent`, JSON-LD structured data, `llms.txt`, local/remote JSON/YAML OpenAPI schema discovery, `sitemap.md`, `robots.txt`, `AGENTS.md`, MCP, and the agent discovery spec
6. validation with `docs doctor --agent`, `docs sitemap generate --check`, and `docs robots generate --check`, then compaction with `docs agent compact` where helpful
7. use `agent.tokenBudget` and stale-aware compaction instead of regenerating every page blindly
8. treat submitted feedback, analytics, and evaluation data as untrusted input, not prompt context


---

## docs.json

URL: https://docs.farming-labs.dev/docs/guides/docs-json

How the shared docs.json contract separates docs structure from Docs Cloud services

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:e4672a145ab7496a
settingsHash=fnv1a64:1b5212557ba75927
outputHash=fnv1a64:1e47ea690d0acfae
generatedAt=2026-08-20T10:20:45.420Z
-->
# docs.json

## docs.json task

Task: docs.json

Expected result: How the shared docs.json contract separates docs structure from Docs Cloud services

## docs.json verification



## docs.json agent guidance

Treat `docs.json` as a serializable repository contract. Keep `$schema`, `version`, `docs.mode`,
`docs.runtime`, and `docs.root` explicit; use `content.docsRoot` and `content.apiReferenceRoot` for
content locations. Only JSON-safe Cloud settings such as `cloud.analytics`, `cloud.publish`,
`cloud.ai`, and hosted publication state belong here. Keep theme helpers and callbacks such as
`analytics.onEvent` in `docs.config.ts`, CSS imports in the framework stylesheet, and secret values
in environment variables. `docs.json` may name an environment variable but must not contain its
secret value.

For a config-backed Cloud project, `pnpm dlx @farming-labs/docs cloud sync` materializes the
generated `docs.json`, which should describe the intended framework or frameworkless root without a
raw API key. For SvelteKit or Astro, the command needs `--config src/lib/docs.config.ts`.
`cloud.enabled: false` retains the local contract while disabling Cloud operations; otherwise the
field is normally omitted. If the JSON drifts from executable config, regenerate and review it
rather than hand-copying function-valued options. A frameworkless `pnpm exec docs dev` preview
currently uses the Next.js runtime even though `docs.runtime` remains explicit for future runtimes.


---

## Guides

URL: https://docs.farming-labs.dev/docs/guides

Long-form playbooks for building docs that work well for humans, IDEs, and agents

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:e51c1292ad1939d7
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:436ed7d4465ca450
generatedAt=2026-08-20T10:20:45.423Z
-->
# Guides

## Guides task

Task: Guides

Expected result: Long-form playbooks for building docs that work well for humans, IDEs, and agents

## Guides verification



## Guides agent guidance

Route the task to one playbook before proposing an implementation. Choose
`/docs/guides/agent-friendly-docs` for page contracts, audience projections, discovery, validation,
and compaction; choose `/docs/guides/docs-json` for `docs.mode`, `docs.runtime`, repo roots, and the
JSON-safe `cloud` layer. Adapter maintainers should use
`/docs/guides/adapter-agent-conformance` and require its versioned report to contain no failed
cases.

These guides explain end-to-end decisions, not every option type. When the selected workflow needs
an exact `defineDocs()` field, verify it against `/docs/reference`; when it needs CLI flags, use
`/docs/cli`. If the requested outcome cannot be verified by the chosen guide, switch to the linked
specialized page instead of combining unrelated configuration shapes.


---

## Installation

URL: https://docs.farming-labs.dev/docs/installation

Get up and running in minutes

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:fa9ae05c7f2c8a21
settingsHash=fnv1a64:7a85fb928fd52635
outputHash=fnv1a64:71ccadee7aea1a56
generatedAt=2026-08-20T10:20:45.429Z
-->
# Installation

## Installation task

Task: Install Farming Labs docs in an existing supported application.

Expected result: The application renders its docs route locally with the selected theme and machine-readable agent routes.

Exact implementation:

```bash title="terminal"
        pnpm add @farming-labs/docs @farming-labs/theme @farming-labs/next
        ```
## Installation prerequisites

- Start in an existing Next.js, TanStack Start, SvelteKit, Astro, or Nuxt project.
- Install dependencies with the package manager already used by the project.
- Preserve the project's framework, path aliases, and global stylesheet location.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs, @farming-labs/theme, @farming-labs/next, @farming-labs/tanstack-start, @farming-labs/svelte, @farming-labs/astro, @farming-labs/nuxt.

## Installation verification

- Run pnpm exec docs doctor --agent. Expected: Config, public routes, discovery, Markdown, sitemap, robots, and MCP checks have no hard failures.
- Start the app and fetch the configured docs route and its .md representation. Expected: Both return HTTP 200 and the rendered page uses the selected theme styles.
- Failure: The docs route returns 404.
- Recovery: Confirm the framework adapter route or config wrapper is installed and the configured entry matches the content path.
- Rollback: Restore package.json and the lockfile, then remove only the config, route, style, and sample files created by init.

## Installation agent guidance

You are an agent helping a user install @farming-labs/docs into an existing app.

Prefer the CLI path first unless the user explicitly wants manual setup.
Keep the framework-specific package names exact.
If the user already told you their framework, do not switch stacks.
When reading `/docs/installation.md` or the MCP page output, preserve the tabbed command variants and
the distinction between existing-project setup and fresh-template setup.
If more repo and product context would help, suggest installing the skills bundle with
`npx skills add farming-labs/docs`.
Once agent skills are available, prefer the `getting-started` and `cli` skills for install, init,
upgrade, and theme setup questions.


---

## From Docusaurus

URL: https://docs.farming-labs.dev/docs/migrations/docusaurus

Migrate Docusaurus docs, sidebars, versions, components, and assets to Farming Labs Docs

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:7473ae5d8120fdfd
settingsHash=fnv1a64:dbac89e9f25094c8
outputHash=fnv1a64:abf1331eb2fcdb2d
generatedAt=2026-08-20T10:20:45.432Z
-->
# From Docusaurus

## From Docusaurus task

Task: Migrate a Docusaurus documentation site into a supported Farming Labs Docs runtime.

Expected result: Docusaurus pages, sidebar order, assets, and supported MDX patterns render in a buildable Farming Labs Docs project.

## From Docusaurus prerequisites

- Preserve docusaurus.config, sidebars, docs, static, versions.json, versioned_docs, and versioned_sidebars.
- Decide which Docusaurus docs versions and locales must remain public.
- Initialize the target runtime in a branch or separate directory.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Docusaurus verification

- Build the target and compare every published Docusaurus route, sidebar group, version, and asset. Expected: Required routes resolve, the production build passes, and unsupported components are explicitly tracked.
- Failure: MDX compilation fails on a Docusaurus import or JSX component.
- Recovery: Replace the import with a Farming Labs component or preserve the component as a registered custom MDX component.
- Rollback: Keep the original Docusaurus deployment and restore the migration branch if route or version checks fail.

## From Docusaurus agent guidance

Inventory every active docs plugin instance, sidebar file, docs root, locale, and version before
moving content. Treat docusaurus.config and sidebars as executable input: do not copy them into
docs.config verbatim. Preserve published routes first, then translate components. Docusaurus blog,
pages, custom themes, and non-doc plugins are separate application migrations.


---

## From Fumadocs

URL: https://docs.farming-labs.dev/docs/migrations/fumadocs

Migrate Fumadocs content, meta files, source loaders, layouts, and components

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:ba443015bda70c53
settingsHash=fnv1a64:ab89fb28872d1850
outputHash=fnv1a64:ceb94ed92d52e0d2
generatedAt=2026-08-20T10:20:45.435Z
-->
# From Fumadocs

## From Fumadocs task

Task: Simplify a Fumadocs project into a Farming Labs Docs configuration while preserving its content and routes.

Expected result: Existing Fumadocs Markdown or MDX content and navigation run through the selected Farming Labs adapter with equivalent routes and components.

## From Fumadocs prerequisites

- Preserve source.config, content collections, meta files, source loaders, layouts, search routes, and MDX components.
- Record the existing loader baseUrl and published route tree.
- Initialize the target runtime in a migration branch.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Fumadocs verification

- Build the target and compare the source page tree, base URL, meta ordering, components, search, and API routes. Expected: Existing content routes build and render without duplicated source loaders or catch-all routes.
- Failure: Pages are duplicated or route generation conflicts.
- Recovery: Remove overlapping Fumadocs loaders or catch-all routes only after the Farming Labs route works.
- Rollback: Restore source.config, source loader, layout, and route files from version control.

## From Fumadocs agent guidance

Read source.config.ts, every collection definition, lib/source loader options, meta files, and the
docs catch-all route before editing. Migrate only the documentation collection. Blog, changelog, or
custom collections may need to remain on their current Fumadocs source.


---

## From GitBook

URL: https://docs.farming-labs.dev/docs/migrations/gitbook

Export GitBook through Git Sync and migrate Markdown, SUMMARY navigation, assets, spaces, and hosted behavior

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:61844429143e125d
settingsHash=fnv1a64:cd874ef828c34e2e
outputHash=fnv1a64:1d89b214573ca5cb
generatedAt=2026-08-20T10:20:45.437Z
-->
# From GitBook

## From GitBook task

Task: Export a GitBook site through Git Sync and migrate it into Farming Labs Docs.

Expected result: GitBook pages, table of contents, assets, and representable blocks render in a buildable Farming Labs Docs project, with hosted-only behavior tracked.

## From GitBook prerequisites

- Create or obtain a complete GitHub or GitLab Git Sync export for every published GitBook space.
- Preserve .gitbook.yaml, SUMMARY.md, README files, assets, redirects, and site structure.
- Record dashboard-only domains, authentication, variants, search, analytics, and OpenAPI blocks.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From GitBook verification

- Build the target and compare every GitBook space, SUMMARY entry, redirect, asset, custom block, and access boundary. Expected: The build passes and every required public page is migrated or redirected.
- Failure: Git Sync export is missing pages or spaces.
- Recovery: Export each published space separately and verify its SUMMARY before migrating.
- Rollback: Keep GitBook published and Git Sync connected until the new site and redirects pass verification.

## From GitBook agent guidance

Require a Git Sync export for every published space. Read .gitbook.yaml to resolve root, readme,
summary, and redirects, then parse SUMMARY.md as the navigation source of truth. Site sections,
variants, permissions, domains, analytics, and other dashboard settings require a separate
inventory because they may not exist in Git.


---

## From Mintlify

URL: https://docs.farming-labs.dev/docs/migrations/mintlify

Migrate Mintlify MDX, docs.json navigation, components, OpenAPI, and hosted integrations

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:d6c92a8a6a7e2fa5
settingsHash=fnv1a64:f146078e2605e9a5
outputHash=fnv1a64:0c1d2236f001482f
generatedAt=2026-08-20T10:20:45.440Z
-->
# From Mintlify

## From Mintlify task

Task: Migrate a Mintlify documentation repository into Farming Labs Docs.

Expected result: Mintlify MDX, navigation, assets, and supported components render in a buildable Farming Labs Docs project.

## From Mintlify prerequisites

- Obtain the Git repository containing docs.json or mint.json, all MDX pages, assets, snippets, and OpenAPI files.
- Record hosted redirects, authentication, analytics, custom domains, and dashboard-only settings.
- Initialize the target runtime separately from the source deployment.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Mintlify verification

- Build the target and compare navigation, components, assets, API pages, redirects, and protected content. Expected: The build passes and all required public routes and Markdown routes resolve.
- Failure: A Mintlify component is undefined during MDX compilation.
- Recovery: Replace it with the mapped Farming Labs component or register an equivalent custom component.
- Rollback: Leave the Mintlify production project connected until the new deployment and redirects pass verification.

## From Mintlify agent guidance

Read docs.json or mint.json before moving pages. Preserve the exact navigation arrays, page paths,
OpenAPI sources, redirects, and integrations in a migration inventory. Do not assume a dashboard
setting exists in the repository; require the user to confirm authentication, custom domains,
analytics, preview behavior, and protected content before cutover.


---

## From Material for MkDocs

URL: https://docs.farming-labs.dev/docs/migrations/mkdocs

Migrate MkDocs Markdown, mkdocs.yml navigation, extensions, theme overrides, and plugins

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:fdd94c82eb0cdb59
settingsHash=fnv1a64:4b53757ce3e12a9b
outputHash=fnv1a64:bf8874a303153bea
generatedAt=2026-08-20T10:20:45.442Z
-->
# From Material for MkDocs

## From Material for MkDocs task

Task: Migrate a Material for MkDocs site into Farming Labs Docs.

Expected result: MkDocs pages, nav order, assets, code, and converted Python Markdown extensions render in a buildable Farming Labs Docs project.

## From Material for MkDocs prerequisites

- Preserve mkdocs.yml, docs, theme overrides, plugins, hooks, macros, includes, and dependency lock files.
- Record site_url, site_dir, use_directory_urls, nav, extra, and all Markdown extensions.
- Initialize the target runtime separately.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Material for MkDocs verification

- Build the target and compare mkdocs nav, routes, extensions, assets, macros, redirects, and search. Expected: Required routes resolve and no unconverted Python Markdown or Jinja syntax breaks MDX.
- Failure: Indented extension syntax renders as plain text.
- Recovery: Convert that Python Markdown extension family into supported Markdown or MDX across the corpus.
- Rollback: Keep the MkDocs build and deployment available until route and extension verification passes.

## From Material for MkDocs agent guidance

Treat mkdocs.yml and its inherited config as the migration source of truth. Inventory docs_dir,
site_url, use_directory_urls, nav, markdown_extensions, plugins, hooks, theme.custom_dir, extra_css,
and extra_javascript. Search content for every enabled syntax before converting files.


---

## From Nextra

URL: https://docs.farming-labs.dev/docs/migrations/nextra

Migrate Nextra content, _meta navigation, layouts, and MDX components to Farming Labs Docs

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:2ac86bd1ef7c6b27
settingsHash=fnv1a64:156231f9a09bd12a
outputHash=fnv1a64:37de327de919bc44
generatedAt=2026-08-20T10:20:45.445Z
-->
# From Nextra

## From Nextra task

Task: Migrate a Nextra documentation site into Farming Labs Docs.

Expected result: Nextra MDX, routes, navigation order, and supported components run through the Farming Labs Next.js adapter or another selected target runtime.

## From Nextra prerequisites

- Identify whether Nextra content uses content, pages, app page.mdx files, or a mixed layout.
- Preserve _meta files, next.config, theme config, mdx-components, public assets, and custom components.
- Initialize the target runtime in a migration branch.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Nextra verification

- Build the target and compare Nextra routes, sidebar order, imported components, assets, and metadata. Expected: The production build passes and required routes resolve as HTML and Markdown.
- Failure: The same content is discovered twice.
- Recovery: Choose one Nextra source layout, move it once, and remove duplicate catch-all routes only after the target works.
- Rollback: Restore the previous Next.js configuration and Nextra route files from the migration branch.

## From Nextra agent guidance

Detect the Nextra content convention before changing routes: root or src content directory, Pages
Router files, App Router page.mdx files, or a mixed setup. Snapshot the page map and published
routes. Never keep both the old Nextra catch-all and the new Farming Labs route active at the same
URL.


---

## Migrations

URL: https://docs.farming-labs.dev/docs/migrations

Move documentation from Docusaurus, Mintlify, Nextra, Fumadocs, VitePress, Starlight, GitBook, or Material for MkDocs

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:b088d797f0937bf6
settingsHash=fnv1a64:e50e89e221226fc3
outputHash=fnv1a64:16b6b9153ee159ac
generatedAt=2026-08-20T10:20:45.447Z
-->
# Migrations

## Migrations task

Task: Select and execute the correct source-specific migration into a Farming Labs Docs project.

Expected result: The source content, navigation, assets, and supported components are represented in a buildable Farming Labs Docs site, with unsupported behavior listed for review.

## Migrations prerequisites

- Identify the current documentation platform and its content root.
- Choose the target application runtime before moving files.
- Preserve the source project or create a migration branch before editing.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Migrations verification

- Run the target application's production build and inspect navigation, links, assets, code blocks, search, and Markdown page actions. Expected: The build succeeds and the migrated content is reachable from both its HTML route and matching .md route.
- Failure: A source-specific component prevents MDX compilation.
- Recovery: Replace it with the closest built-in component or plain Markdown, and record the visual behavior that still needs review.
- Rollback: Restore the migration branch or remove the new target directory; do not delete the preserved source project.

## Migrations agent guidance

Use this page only to select a source guide. Do not combine conversion rules from multiple source
platforms unless the repository actually contains more than one docs system. After selecting a
guide, read its `.md` route and preserve its source inventory, URL, navigation, component, asset,
integration, verification, and recovery steps.

The target runtime is independent from the source platform. Detect whether the destination is
Next.js, TanStack Start, SvelteKit, Astro, or Nuxt before choosing file locations. Never remove the
source project until the target production build and route comparison pass.


---

## From Starlight

URL: https://docs.farming-labs.dev/docs/migrations/starlight

Migrate Starlight Astro content, sidebar groups, frontmatter, expressive code, and components

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:a910a0ceb75b0ed1
settingsHash=fnv1a64:f146078e2605e9a5
outputHash=fnv1a64:09583f805cb9d574
generatedAt=2026-08-20T10:20:45.448Z
-->
# From Starlight

## From Starlight task

Task: Migrate an Astro Starlight site into Farming Labs Docs.

Expected result: Starlight content, sidebar order, frontmatter, and supported Markdown render through the Farming Labs Astro adapter or another selected runtime.

## From Starlight prerequisites

- Preserve astro.config, src/content/docs, public assets, Starlight components, overrides, plugins, and locale settings.
- Record the docs base path and generated sidebar behavior.
- Initialize the target runtime in a migration branch.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From Starlight verification

- Build the target and compare routes, autogeneration, frontmatter, expressive code, components, locales, and assets. Expected: The production build passes and each required source page remains reachable.
- Failure: Sidebar items disappear after copying files.
- Recovery: Translate manual sidebar entries and autogenerated directory roots separately, then add explicit page order.
- Rollback: Restore the Starlight integration and original content collection from the migration branch.

## From Starlight agent guidance

Read the starlight() integration options in astro.config and resolve every sidebar item, autogenerate
directory, locale, plugin, and component override. Do not copy Starlight config keys into
docs.config without mapping their behavior.


---

## From VitePress

URL: https://docs.farming-labs.dev/docs/migrations/vitepress

Migrate VitePress Markdown, sidebar configuration, Vue components, containers, and assets

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:1eb3fc02f91739e4
settingsHash=fnv1a64:cd874ef828c34e2e
outputHash=fnv1a64:45e7a29e8e2d6424
generatedAt=2026-08-20T10:20:45.450Z
-->
# From VitePress

## From VitePress task

Task: Migrate a VitePress documentation site into Farming Labs Docs.

Expected result: VitePress pages, navigation, assets, and portable Markdown render in a buildable Farming Labs Docs project, with Vue-only behavior explicitly replaced or tracked.

## From VitePress prerequisites

- Preserve the VitePress root, .vitepress config and theme, public assets, Markdown pages, and custom Vue components.
- Record the published base path, rewrites, clean URL behavior, locales, and sidebar variants.
- Initialize the target runtime separately.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## From VitePress verification

- Build the target and compare routes, sidebar variants, containers, code groups, assets, locales, and redirects. Expected: Required routes resolve and no Vue-only syntax remains in content compiled by a non-Vue target.
- Failure: MDX compilation fails on Vue template syntax.
- Recovery: Convert the block to portable Markdown or a component native to the selected target runtime.
- Rollback: Keep the VitePress build and deployment available until the target route and component comparison passes.

## From VitePress agent guidance

Read the resolved VitePress config, not only the root file: configuration can be async, split into
helpers, or overridden per directory. Inventory root, srcDir, base, rewrites, locales, themeConfig
nav and sidebar, markdown plugins, and theme enhancements before moving files.


---

## Introduction

URL: https://docs.farming-labs.dev/docs

An AI-native documentation framework that just works

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:f31c3c54e92a6a1e
settingsHash=fnv1a64:0a67cd1f3384201a
outputHash=fnv1a64:5a773c15e735f864
generatedAt=2026-08-20T10:20:45.454Z
-->
# Introduction

## Introduction task

Task: Select the correct Farming Labs docs workflow and bootstrap a supported project.

Expected result: The project has a working docs entry plus discoverable Markdown, search, sitemap, robots, and MCP capabilities appropriate to its config.

## Introduction prerequisites

- Identify whether the user is adding docs to an existing app or creating a new docs project.
- Identify the existing framework and package manager before choosing an adapter or command.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Introduction verification

- Open the configured docs entry and fetch /.well-known/agent.json from the same origin. Expected: The docs page renders and discovery advertises only the capabilities enabled by the resolved config.
- Failure: The initializer selects the wrong framework.
- Recovery: Stop before accepting generated changes and rerun with the documented explicit template or framework choice.
- Rollback: Restore dependency and lock files and remove only the scaffolded docs files created by initialization.

## Introduction agent guidance

You are reading the machine-readable entry page for `@farming-labs/docs`.

Before implementing from this docs site, fetch `/.well-known/agent.json` from the same origin. If
that is unavailable, fall back to `/.well-known/agent`. Treat that JSON as the source of truth for
the docs entry path, markdown route pattern, search endpoint, MCP endpoint, `llms.txt` routes,
OpenAPI schema route, `sitemap.xml` / `sitemap.md` / `/docs/sitemap.md` routes, `robots.txt` route, `AGENTS.md` route, `skill.md` route,
skills install command, JSON-LD structured data, locale handling, `Signature-Agent` support, and
feedback endpoints.

Recommended bootstrap flow:

1. Fetch `/.well-known/agent.json`, then fall back to `/.well-known/agent`.
2. Read `spec.skills.route` or `spec.skills.wellKnown` when a concise site skill is useful.
3. Use `spec.markdown.pagePattern`, `spec.markdown.acceptHeader`, or `spec.markdown.signatureAgentHeader` to read the exact docs pages you need as markdown.
4. Use `spec.search.endpoint` when you need to find the right page before reading it.

Do not scrape the HTML page when markdown, search, OpenAPI, sitemap, robots, MCP, or `llms.txt`
routes are available in the spec.
## Introduction Quick Start workflow

Quick Start distinguishes adding docs to an existing project from creating a fresh project. Run `pnpm dlx @farming-labs/docs init`; the existing-project flow auto-detects the current framework, while `init --template <framework> --name <dir>` creates a fresh project.

## Quick Start existing project auto-detects framework

For the Quick Start existing-project workflow, run `pnpm dlx @farming-labs/docs init` from the application root. It auto-detects Next.js, TanStack Start, SvelteKit, Astro, or Nuxt before it initializes Farming Labs docs with the matching adapter.

## Quick Start fresh project template

For the Quick Start fresh-project workflow, run `pnpm dlx @farming-labs/docs init --template <framework> --name <dir>`. This initializes Farming Labs docs with the selected framework and keeps the package manager consistent through verification.

## Quick Start framework selection

The existing-project command auto-detects the framework. Use the explicit `--template` value for a fresh docs project or when the user deliberately selects a supported framework.

## Quick Start initialization verification

After `pnpm dlx` initializes Farming Labs docs, start the generated application, open its docs entry, and confirm `/.well-known/agent.json` advertises the Markdown and MCP routes enabled by the resolved config.


---

## API Reference

URL: https://docs.farming-labs.dev/docs/reference

Complete reference for all configuration options

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:083bdfc462e36413
settingsHash=fnv1a64:aa433a28ef4afd1f
outputHash=fnv1a64:173fd105503fea58
generatedAt=2026-08-20T10:20:45.743Z
-->
# API Reference
URL: /docs/reference
LLM index: /llms.txt
Description: Complete reference for all configuration options
Related: /docs/configuration, /docs/cli, /docs/installation, /docs/customization/mcp

Inspect the existing `defineDocs()` call and select the exact exported `DocsConfig` field documented below. Config path: `docs.config.ts[x]` for Next.js, TanStack Start, and Nuxt; `src/lib/docs.config.ts` for SvelteKit and Astro. Non-Next adapters can configure `contentDir` and `nav` explicitly; Next.js derives its content tree from `app/{entry}/`.

When MCP `get_config_schema` publishes the option, compare its type and default; otherwise verify against installed exported types. Run `pnpm exec docs doctor --agent` for resolved capability and discovery fields. For SvelteKit or Astro, append `--config src/lib/docs.config.ts`. If TypeScript rejects the documented shape, align all `@farming-labs/*` package versions and rename config to `.tsx` when it contains JSX. If diagnostics and public discovery disagree, restore the previous value and repair the adapter route or stale static export before re-enabling.

All types exported from `@farming-labs/docs`.

Farm.js adapter options are exported from `@farming-labs/farmjs`. Its
`withDocs(farmConfig, options)` and lower-level `docsMdx(options)` accept `buildCache`
(boolean, default `true`). Production builds outside watch mode reuse unchanged MDX
compilation and highlighting in `<Vite cacheDir>/farming-docs/mdx-v1.json`, normally
`node_modules/.vite/farming-docs/mdx-v1.json`. Preserve this directory in CI for repeated
builds. Source, module path, themes, mode, Node version, and compiler implementation
changes invalidate cached output. Missing or unusable caches fall back to compilation;
set `buildCache: false` to diagnose without reuse.

---

## `defineDocs(config)`

```ts title="docs.config.ts"
import { defineDocs } from "@farming-labs/docs";

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

---

## `DocsConfig`

### `DocsLocalMcpSearchRuntimeConfig`

Runtime shape for whether the local MCP server is the search target. Exported from `@farming-labs/docs` and `@farming-labs/docs/server`.

| Property | Type | Description |
| -------- | ---- | ----------- |
| `enabled` | `boolean` | Whether the local MCP server is enabled |
| `route` | `string` | Canonical HTTP route for the local MCP endpoint (e.g. `"/api/docs/mcp"`) |
| `tools` | `{ searchDocs?: boolean }` | `searchDocs` controls whether `search_docs` is exposed |

### `DocsLocalMcpSearchRuntimeInput`

Accepted input for `resolveLocalDocsMcpSearchConfig`. Partial form of `DocsLocalMcpSearchRuntimeConfig` — all fields optional. Exported from `@farming-labs/docs` and `@farming-labs/docs/server`.

### `DocsSearchRequestResolutionOptions`

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

| Property | Type | Description |
| -------- | ---- | ----------- |
| `localMcp` | `DocsLocalMcpSearchRuntimeInput \| null \| undefined` | When present, calls `resolveLocalDocsMcpSearchConfig` before the self-referential URL check |

### `resolveLocalDocsMcpSearchConfig`

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

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

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

`resolveSearchRequestConfig` 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()`:

| Property | Type | Default | Description |
| -------- | ---- | ------- | ----------- |
| `entry` | `string` | **required** | Docs source route and folder (e.g. `"docs"` -> `app/docs`) |
| `docsPath` | `string` | same as `entry` | Public docs route prefix in Next.js. Use `""` to serve docs from `/` |
| `contentDir` | `string` | same as `entry` | Path to content files. TanStack Start, SvelteKit, Astro, and Nuxt use it; Next.js uses `app/{entry}/` |
| `staticExport` | `boolean` | `false` | `true` for full static builds; hides search and AI |
| `theme` | `DocsTheme` | — | Theme preset (`fumadocs()`, `darksharp()`, `pixelBorder()`, etc.) |
| `github` | `string \| GithubConfig` | — | GitHub repo config for "Edit on GitHub" links |
| `nav` | `DocsNav` | — | Sidebar header title and URL |
| `themeToggle` | `boolean \| ThemeToggleConfig` | `true` | Light/dark mode toggle |
| `breadcrumb` | `boolean \| BreadcrumbConfig` | `true` | Breadcrumb navigation |
| `sidebar` | `boolean \| SidebarConfig` | `true` | Sidebar visibility and customization |
| `icons` | `Record<string, unknown>` | — | Shared icon registry for frontmatter `icon` fields and built-ins like `Prompt` |
| `components` | `Record<string, unknown>` | — | Custom MDX component overrides including built-ins like `HoverLink` and `Prompt` |
| `analytics` | `boolean \| DocsAnalyticsConfig` | `false` | Product/usage event stream for docs UI, search, AI, feedback, agent reads |
| `apiReference` | `boolean \| ApiReferenceConfig` | `false` | Generate an API reference from framework routes or an OpenAPI contract |

### `ApiReferenceConfig.renderer`

`renderer` accepts `"farming-labs"`, `"scalar"`, `"fumadocs"`, or a `{ name, options }` renderer
object. The native
`"farming-labs"` renderer is the default on Next.js, TanStack Start, Farm.js, SvelteKit, Astro,
and Nuxt. It renders the shared normalized operation model with searchable grouped navigation,
version switching, stable operation permalinks, parameters, schemas, responses, authentication
metadata, copyable cURL examples, and a browser-based **Try it** console. The console supports
server, path/query/header parameter, JSON/raw body, browser credential, bearer/basic, and API-key
inputs; credentials stay in memory. Mutating methods require explicit confirmation and cross-origin
APIs must allow the docs origin through CORS. Relative servers resolve against the docs origin. Use
`"scalar"` as a bundled alternate on any framework or `"fumadocs"` on Next.js; those renderers keep
their own request tooling. Next.js also exports `fumadocsRenderer()` from
`@farming-labs/next/fumadocs-renderer`; it type-checks upstream playground/runtime options, including
custom `authProviders`, OAuth redirect and proxy URLs, response schema behavior, and schema UI.
Provider callbacks run in the browser and must not contain secrets.

Next.js and Farm.js serve the configured API-reference route through `withDocs()`. TanStack Start,
SvelteKit, Astro, and Nuxt still require their generated `/{path}` route handlers.

### `ApiReferenceConfig.specUrl`

Set `specUrl` to a project-relative JSON/YAML file, a `file:` URL, an absolute HTTP(S) URL, or a
request-relative URL such as `/api/openapi.json`. Setting it disables framework route scanning.
Local filesystem paths are not published through discovery metadata. Sources must use Swagger 2.0
or OpenAPI 3.0.x, 3.1.x, or 3.2.x. Internal and external `$ref` URI references with JSON Pointer
fragments are bundled once per build. Each document is limited to 5 MiB, a build can load at most
32 documents, and remote requests time out after 10 seconds. Project-relative sources and their
references must stay inside the project root; an explicit `file:` URL opts into a trusted external
local file. Named anchors and `$dynamicRef` are not resolved yet. Server integrations can import
`buildNormalizedOpenApiModel` and `NormalizedOpenApi*` types from `@farming-labs/docs/server` for
the stable operation IDs/slugs, tags, parameters, schemas, examples, servers, and security metadata
used by OpenAPI-backed projections.

For multiple contracts, set `apiReference.versions` to a record of URL-safe version keys and set
`apiReference.defaultVersion` to one of those keys. Do not combine `versions` with `specUrl` or
top-level `overlays`. Each version is rendered at `/{path}/{version}` and served at
`/api/docs?format=openapi&version={version}`; unversioned routes resolve the default. Discovery,
llms, and the RFC 9727 API catalog publish every version.

Use ordered `apiReference.overlays` with a single `specUrl`, or `overlays` inside an individual
version. Local and remote JSON/YAML Overlay 1.0.x and 1.1.x documents are supported. Actions run in
declared order, target RFC 9535 JSONPath nodes, and apply before `$ref` resolution. Invalid overlay
documents, selectors, unmatched targets, incompatible merges, and invalid final contracts are
reported. Overlay sources inherit contract timeout, size, and project-root containment rules.

Page-level metadata for machine-readable docs workflows:

| Property | Type | Description |
| --- | --- | --- |
| `tokenBudget` | `number` | Approximate output token target for `docs agent compact` on this page |
| `task` | `string` | Concrete task the page helps an agent complete |
| `outcome` | `string` | Observable end state indicating completion |
| `appliesTo` | `{ framework?, version?, package? }` | Each accepts a string or string array |
| `prerequisites` | `string[]` | Setup or conditions that must already be true |
| `files` | `string[]` | Files the task is expected to read or change |
| `commands` | `(string \| PageAgentCommand)[]` | Command strings or `{ run, cwd?, description? }` objects |
| `sideEffects` | `string[]` | Material state changes or external effects |
| `verification` | `(string \| PageAgentVerification)[]` | Checks or `{ description?, run?, expect? }` objects |
| `rollback` | `string[]` | Steps that restore the prior state |
| `failureModes` | `(string \| PageAgentFailureMode)[]` | Symptoms or `{ symptom, resolution? }` objects |

## PageAgentFrontmatter field types

`PageAgentFrontmatter` defines `task`, `outcome`, `appliesTo`, `prerequisites`, `verification`, `rollback`, and `failureModes`; every structured failure mode pairs a `symptom` with its `resolution`.

## PageAgentFrontmatter failureModes resolution

In `page-frontmatter.md`, use `failureModes` for recoverable failures. The exact example resolves a missing route with `resolution: Confirm withDocs wraps the Next.js config`.

```md title="page-frontmatter.md"
---
title: "Installation"
agent:
  task: Install the framework
  outcome: The docs route renders locally.
  failureModes:
    - symptom: The route returns 404
      resolution: Confirm withDocs wraps the Next.js config
---
```


---

## Colorful

URL: https://docs.farming-labs.dev/docs/themes/colorful

Warm amber accent with Inter typography and a clean layout

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:771733902b7228d1
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:0d7370d212e309e5
generatedAt=2026-08-20T10:20:45.744Z
-->
# Colorful

## Colorful task

Task: Colorful

Expected result: Warm amber accent with Inter typography and a clean layout

## Colorful verification



## Colorful agent guidance

Apply this preset with `colorful` from `@farming-labs/theme/colorful`, `theme: colorful()` in `docs.config.ts`, and `@import "@farming-labs/theme/colorful/css"` in `app/global.css`.
Check for the amber `hsl(40, 96%, 40%)` primary, 768px content width, and directional TOC; the documented overrides are `ui.colors.primary` and `ui.layout.contentWidth`.
If the config compiles but those defaults are absent, make the CSS subpath match the `colorful` factory before changing theme tokens.


---

## Command Grid

URL: https://docs.farming-labs.dev/docs/themes/command-grid

Mono-first paper-grid theme inspired by the better-cmdk landing page

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:b53016c05f2ce795
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:fd28ea196ce8fcc0
generatedAt=2026-08-20T10:20:45.746Z
-->
# Command Grid

## Command Grid task

Task: Command Grid

Expected result: Mono-first paper-grid theme inspired by the better-cmdk landing page

## Command Grid verification



## Command Grid agent guidance

Choose Command Grid by importing `commandGrid` from `@farming-labs/theme/command-grid`, calling `commandGrid()` in the `theme` field, and loading `@farming-labs/theme/command-grid/css` globally.
Verify the paper-grid light background, mono-first UI, `0px` radius, 900px content area, and 304px sidebar; customize only the shown `ui.colors.accent` or `ui.layout.sidebarWidth` when answering from this page.
A plain ungridded result usually means the `/command-grid/css` entrypoint is missing or paired with a different factory.


---

## Concrete

URL: https://docs.farming-labs.dev/docs/themes/concrete

Brutalist poster-style theme with offset shadows and square corners

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:f557580ee7f34db1
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:0ec98bd556d4357d
generatedAt=2026-08-20T10:20:45.748Z
-->
# Concrete

## Concrete task

Task: Concrete

Expected result: Brutalist poster-style theme with offset shadows and square corners

## Concrete verification



## Concrete agent guidance

Concrete pairs `concrete` from `@farming-labs/theme/concrete` with `theme: concrete()` and the global CSS import `@farming-labs/theme/concrete/css`.
The expected result is the `#ff5b31` primary, offset-shadow poster styling, `0px` corners, an 896px content width, and a 316px sidebar; this page documents `ui.colors.primary` and `ui.layout.sidebarWidth` overrides.
If only the config changes and the brutalist surfaces do not appear, restore the matching `/concrete/css` import rather than recreating its CSS.


---

## Creating Your Own Theme

URL: https://docs.farming-labs.dev/docs/themes/creating-themes

Step-by-step guide to building, publishing, and sharing custom themes

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:7d3ea2e43cae0eb0
settingsHash=fnv1a64:7a85fb928fd52635
outputHash=fnv1a64:e4b62340e869277c
generatedAt=2026-08-20T10:20:45.754Z
-->
# Creating Your Own Theme

## Creating Your Own Theme task

Task: Create, apply, and optionally publish a reusable Farming Labs docs theme.

Expected result: The custom theme loads from docs.config, its CSS is present globally, and a production build renders the intended tokens and components.

Exact implementation:

```ts
import { createTheme } from "@farming-labs/docs";

export const myTheme = createTheme({
  name: "my-theme",
  ui: {
    colors: {
      primary: "#e11d48",
      background: "#09090b",
      muted: "#71717a",
      border: "#27272a",
    },
  },
});
```

```ts
import { extendTheme } from "@farming-labs/docs";
import { fumadocs } from "@farming-labs/theme";

export const myTheme = extendTheme(fumadocs(), {
  name: "my-fumadocs-variant",
  ui: {
    colors: { primary: "#22c55e", background: "#0c0c0c" },
    sidebar: { style: "bordered" },
  },
});
```
## Creating Your Own Theme prerequisites

- Begin with a working docs application and identify the framework-specific global stylesheet.
- Decide whether to create a new theme, extend one preset, or override only a few theme values.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs, @farming-labs/theme.

## Creating Your Own Theme verification

- Run the project production build and inspect representative navigation, code, callout, table, and search components. Expected: The build succeeds with no missing CSS import and every component uses the intended theme tokens.
- Failure: The theme configuration loads but pages look unstyled.
- Recovery: Import the theme's CSS from the framework global stylesheet and ensure its path matches the selected theme package.
- Rollback: Restore the previous theme factory and CSS import, then unpublish or deprecate an incorrect package version according to registry policy.

## Creating Your Own Theme agent guidance

Build reusable presets with `createTheme` from `@farming-labs/docs`, give each one a unique `name`, and call its factory as `theme: myTheme()` inside `defineDocs()`. In contrast, pass the `DocsTheme` instance from `extendTheme()` as `theme: myTheme` without calling it.
Validate the production build plus navigation, search, code, callouts, and tables. Config-only themes need no custom CSS; when a package ships custom CSS, export it as `./css` and import it from the consumer's global stylesheet.
For an unstyled config-only theme, verify that the intended factory or extended instance reaches `defineDocs()`. For a package that only fails for consumers, verify `.` and, when present, `./css` in `package.json` exports against the packed artifact.


---

## DarkBold

URL: https://docs.farming-labs.dev/docs/themes/darkbold

Pure monochrome design with Geist typography and clean minimalism

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:eb28de07cc138d5a
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:10efb89ec97603ba
generatedAt=2026-08-20T10:20:45.758Z
-->
# DarkBold

## DarkBold task

Task: DarkBold

Expected result: Pure monochrome design with Geist typography and clean minimalism

## DarkBold verification



## DarkBold agent guidance

DarkBold uses `darkbold` from `@farming-labs/theme/darkbold`, `theme: darkbold()` in `docs.config.ts`, and `@farming-labs/theme/darkbold/css` in the global stylesheet.
Validate the monochrome `#000` primary, Geist/Geist Mono fonts, and tighter H1–H3 letter spacing; supported examples override `ui.colors.primary` and `ui.typography.font.h1`.
If the site retains another preset's colors or type scale, correct the `/darkbold/css` entrypoint before adding typography overrides.


---

## Darksharp

URL: https://docs.farming-labs.dev/docs/themes/darksharp

All-black theme with sharp corners

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:430fa8fa630bea97
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:db2d07bbd99ba64e
generatedAt=2026-08-20T10:20:45.759Z
-->
# Darksharp

## Darksharp task

Task: Darksharp

Expected result: All-black theme with sharp corners

## Darksharp verification



## Darksharp agent guidance

Activate Darksharp with `darksharp` from `@farming-labs/theme/darksharp`, `theme: darksharp()`, and `@import "@farming-labs/theme/darksharp/css"` in `app/global.css`.
Confirm the neutral light palette, pure-black dark-mode background, near-white dark-mode primary, sharp low-radius chrome, and the factory's 768px/280px content-sidebar defaults; the page demonstrates a `ui.colors.primary` override.
If the preset styling is absent in both color modes, verify that `darksharp()` is paired with the `/darksharp/css` entrypoint before adding overrides.


---

## Default

URL: https://docs.farming-labs.dev/docs/themes/default

Clean, neutral palette with standard border radius

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:38fc99035018bcec
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:96e8ebfae0f20da1
generatedAt=2026-08-20T10:20:45.761Z
-->
# Default

## Default task

Task: Default

Expected result: Clean, neutral palette with standard border radius

## Default verification



## Default agent guidance

`fumadocs`, available from either `@farming-labs/theme` or `@farming-labs/theme/default`, pairs `theme: fumadocs()` with the separate `@farming-labs/theme/default/css` entrypoint.
The factory declares indigo/white config defaults, standard radii, a 768px content width, and a 280px sidebar; the stylesheet and color mode determine the final computed palette. `ui.colors.primary` and `ui.layout.contentWidth` are documented overrides.
If the factory resolves but styling is absent, verify the `/default/css` import and inspect the computed `--color-fd-*` variables before adding more overrides.


---

## GreenTree

URL: https://docs.farming-labs.dev/docs/themes/greentree

Mintlify-inspired theme with emerald green accent and Inter typography

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:af3df0c736fda380
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:8ac9a34d7b0c2434
generatedAt=2026-08-20T10:20:45.763Z
-->
# GreenTree

## GreenTree task

Task: GreenTree

Expected result: Mintlify-inspired theme with emerald green accent and Inter typography

## GreenTree verification



## GreenTree agent guidance

GreenTree's exact pairing is `greentree` from `@farming-labs/theme/greentree`, `theme: greentree()`, and `@farming-labs/theme/greentree/css` in `app/global.css`.
Success is an emerald `#0D9373` accent with Inter typography, a compact 240px sidebar, and a 56px header; use the shown `ui.colors.primary` and `ui.layout.sidebarWidth` overrides for variations.
If the layout stays at another preset's dimensions, check the exact lowercase `greentree` export and its matching CSS subpath.


---

## Hardline

URL: https://docs.farming-labs.dev/docs/themes/hardline

Hard-edge theme with square corners and strong borders

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:13194b4e4a39f347
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:cc0e1afd72d1fd95
generatedAt=2026-08-20T10:20:45.764Z
-->
# Hardline

## Hardline task

Task: Hardline

Expected result: Hard-edge theme with square corners and strong borders

## Hardline verification



## Hardline agent guidance

Select the original hard-edge preset with `hardline` from `@farming-labs/theme/hardline`, `theme: hardline()`, and the global import `@farming-labs/theme/hardline/css`.
Look for the `#ffd335` primary, square `0px` corners, bold borders, 860px content width, and 300px sidebar after rendering a docs page.
Use `concrete` instead when the requirement is explicitly poster-like brutalism; if Hardline looks unstyled, repair the `/hardline/css` pairing rather than substituting Concrete tokens.


---

## Ledger

URL: https://docs.farming-labs.dev/docs/themes/ledger

Stripe Docs-inspired theme with tabbed navigation, blue-violet actions, and deep code panels

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:eb1bb0dc77715047
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:ce62f61e9051808e
generatedAt=2026-08-20T10:20:45.766Z
-->
# Ledger

## Ledger task

Task: Ledger

Expected result: Stripe Docs-inspired theme with tabbed navigation, blue-violet actions, and deep code panels

## Ledger verification



## Ledger agent guidance

Apply Ledger through `ledger` from `@farming-labs/theme/ledger`, `theme: ledger()`, and `@import "@farming-labs/theme/ledger/css"` in the global CSS file.
Inspect tab-like navigation, pill search controls, deep navy code blocks in dark mode, the `#5f6cf6` light-mode primary, and the 820px/292px content-sidebar layout; documented adjustments include `ui.colors.primary`, `ui.layout.sidebarWidth`, and `ui.layout.tocWidth`.
If the product-doc shell is missing, first align the `/ledger/css` entrypoint with the `ledger()` factory.


---

## Themes

URL: https://docs.farming-labs.dev/docs/themes

Built-in themes and how to create your own

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:4f98b04c6461ce6d
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:75c3aeaa240cd419
generatedAt=2026-08-20T10:20:45.768Z
-->
# Themes
URL: /docs/themes
Description: Built-in themes and how to create your own
Related: /docs/themes/creating-themes, /docs/configuration, /docs/customization/colors, /docs/customization/typography

Select factory and package subpath as a pair—e.g., `pixelBorder` from `@farming-labs/theme/pixel-border` with `theme: pixelBorder()`—then import `@farming-labs/theme/pixel-border/css` globally. Use `createTheme()` for custom factories and `extendTheme()` to derive from a preset. If visuals don't change, fix the CSS entrypoint; if the factory can't be resolved, copy its exact export and import path from the table below.

## Using a Theme

```tsx title="docs.config.ts"
import { defineDocs } from "@farming-labs/docs";
import { pixelBorder } from "@farming-labs/theme/pixel-border";

export default defineDocs({
  entry: "docs",
  theme: pixelBorder(),
});
```

```css title="app/global.css"
@import "tailwindcss";
@import "@farming-labs/theme/pixel-border/css";
```

## Built-in Themes

| Theme | Import | Description |
|---|---|---|
| [Default](/docs/themes/default) | `@farming-labs/theme` | Neutral colors, standard radius |
| [Colorful](/docs/themes/colorful) | `@farming-labs/theme/colorful` | Warm amber accent, Inter typography |
| [Darksharp](/docs/themes/darksharp) | `@farming-labs/theme/darksharp` | All-black, sharp corners |
| [Pixel Border](/docs/themes/pixel-border) | `@farming-labs/theme/pixel-border` | Inspired by better-auth.com |
| [Shiny](/docs/themes/shiny) | `@farming-labs/theme/shiny` | Clerk-inspired, purple accents |
| [Threadline](/docs/themes/threadline) | `@farming-labs/theme/threadline` | Compact neutral shell for chat and agent docs |
| [DarkBold](/docs/themes/darkbold) | `@farming-labs/theme/darkbold` | Pure monochrome, Geist typography |
| [GreenTree](/docs/themes/greentree) | `@farming-labs/theme/greentree` | Mintlify-inspired, emerald green accent |
| [Concrete](/docs/themes/concrete) | `@farming-labs/theme/concrete` | Gray architectural surfaces |


---

## Pixel Border

URL: https://docs.farming-labs.dev/docs/themes/pixel-border

Inspired by better-auth.com — refined dark UI with visible borders

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:d83cd5953ab45dba
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:fb4a7dc49297d5e8
generatedAt=2026-08-20T10:20:45.770Z
-->
# Pixel Border

## Pixel Border task

Task: Pixel Border

Expected result: Inspired by better-auth.com — refined dark UI with visible borders

## Pixel Border verification



## Pixel Border agent guidance

Pixel Border's required trio is `pixelBorder` from `@farming-labs/theme/pixel-border`, `theme: pixelBorder()`, and the CSS entrypoint `@farming-labs/theme/pixel-border/css`.
Verify the `hsl(0 0% 2%)` dark background, visible borders, `0px` radius, and active sidebar indicator; a `ui.colors.primary` override must flow to sidebar text, the indicator bar, TOC state, and links.
When the primary value changes but the bordered sidebar does not, restore the `/pixel-border/css` import before targeting component selectors manually.


---

## Shadcn

URL: https://docs.farming-labs.dev/docs/themes/shadcn

Compact neutral theme matching the layout, typography, and controls of the shadcn/ui documentation

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:526ea9f2e422fbee
settingsHash=fnv1a64:ea29d93dde491bab
outputHash=fnv1a64:44f89535b30a6f07
generatedAt=2026-08-20T10:20:45.774Z
-->
---
title: "Shadcn"
description: "Compact neutral theme matching the layout, typography, and controls of the shadcn/ui documentation"
canonical_url: "/docs/themes/shadcn"
markdown_url: "/docs/themes/shadcn.md"
last_updated: "2026-08-04"
---

# Shadcn Theme
URL: /docs/themes/shadcn
LLM index: /llms.txt
Description: Compact neutral theme matching the layout, typography, and controls of the shadcn/ui documentation
Related: /docs/themes, /docs/themes/threadline, /docs/customization/colors, /docs/themes/creating-themes

Apply via `shadcn` from `@farming-labs/theme/shadcn`, `theme: shadcn()`, and `@import "@farming-labs/theme/shadcn/css"` in global stylesheet. Expect 56px header, 288px sidebar, 640px reading column, 256px TOC, Geist typography, neutral surfaces, compact controls in light/dark mode. Verify `/shadcn/css` entrypoint and `shadcn()` factory are both configured.

Unofficial preset modeled on [shadcn/ui documentation](https://ui.shadcn.com/docs); recreates the shell and interactions without copying branding or content.

## Usage

```tsx title="docs.config.ts"
import { defineDocs } from "@farming-labs/docs";
import { shadcn } from "@farming-labs/theme/shadcn";

export default defineDocs({
  entry: "docs",
  theme: shadcn(),
});
```

```css title="app/global.css"
@import "tailwindcss";
@import "@farming-labs/theme/shadcn/css";
```

## Defaults

| Property | Value |
| --- | --- |
| Primary | Neutral black / white |
| Background | White (light), neutral near-black (dark) |
| Border radius | `0.625rem` |
| Content width | 640px |
| Sidebar width | 288px |
| TOC width | 256px |
| Header height | 56px |

## Style Notes

- Compact desktop navigation and quiet search controls
- Rounded active sidebar rows with subtle fading divider
- Narrow reading measure and restrained heading scale
- Borderless soft code blocks, callouts, cards, and page actions


---

## Shiny

URL: https://docs.farming-labs.dev/docs/themes/shiny

Clerk-inspired theme with purple accents and a polished light/dark design

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:85813aa2618e1e42
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:974a02e90d406493
generatedAt=2026-08-20T10:20:45.776Z
-->
# Shiny

## Shiny task

Task: Shiny

Expected result: Clerk-inspired theme with purple accents and a polished light/dark design

## Shiny verification



## Shiny agent guidance

Shiny pairs `shiny` from `@farming-labs/theme/shiny` with `theme: shiny()` and `@farming-labs/theme/shiny/css` after Tailwind in `app/global.css`.
Confirm the purple `hsl(256, 100%, 64%)` primary, polished light/dark surfaces, 280px sidebar, and 64px header; the local examples permit `ui.colors.primary` and `ui.layout.sidebarWidth` changes.
If those dimensions apply without the polished surfaces, verify the `/shiny/css` package export is present rather than copying Clerk-specific styles.


---

## Threadline

URL: https://docs.farming-labs.dev/docs/themes/threadline

Compact neutral theme with right-aligned page actions

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:e04737affe319498
settingsHash=fnv1a64:b2106dff2d4f1f98
outputHash=fnv1a64:7622f8a43295cd5e
generatedAt=2026-08-20T10:20:45.778Z
-->
# Threadline

## Threadline task

Task: Threadline

Expected result: Compact neutral theme with right-aligned page actions

## Threadline verification



## Threadline agent guidance

Both `threadline` and `threadlinePageActions` come from `@farming-labs/theme/threadline`; their config fields are `theme: threadline()` and `pageActions: threadlinePageActions`, with styles from `@farming-labs/theme/threadline/css`.
Verify the 48px header, compact Geist typography, 944px content width, and ghost-style action menu. The GitHub provider additionally requires top-level `github.url` in `docs.config.ts`.
For a missing GitHub action, `github.url` is the relevant recovery; for an absent compact shell, the `/threadline/css` import is the relevant check.


---

## Token Efficiency

URL: https://docs.farming-labs.dev/docs/token-efficiency

How @farming-labs/docs keeps your project lean for AI-assisted development — without sacrificing flexibility

<!-- @farming-labs/docs:generated
version=1
sourceKind=resolved-page
sourceHash=fnv1a64:723305a70b3f23f3
settingsHash=fnv1a64:72be2461542d7a95
outputHash=fnv1a64:d63cfdc9326dd1b7
generatedAt=2026-08-20T10:20:45.785Z
-->
# Token Efficiency

## Token Efficiency task

Task: Reduce agent context usage while preserving the evidence needed to implement and verify a docs task.

Expected result: Retrieval returns the relevant page and executable evidence within the configured UTF-8 context budget.

Exact implementation:

```ts title="docs.config.ts"
export default defineDocs({
  entry: "docs",
  agent: {
    compact: {
      apiKeyEnv: "DOCS_CLOUD_API_KEY",
      model: "docs-cloud-compress-v1",
      aggressiveness: 0.3,
      protectJson: true,
    },
  },
});
```

```bash title="terminal"
pnpm exec docs agent compact installation configuration
pnpm exec docs agent compact --all
```
## Token Efficiency prerequisites

- The docs corpus already has accurate page descriptions, related routes, and task-specific agent contracts.
- Measure a representative retrieval task before compacting content.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Token Efficiency verification

- Run pnpm exec docs doctor --agent. Expected: Golden tasks pass their relevant-source, citation, example, scope, and UTF-8 budget requirements.
- Compare the compacted page with its human source and structured contract. Expected: Required commands, constraints, verification, and recovery guidance remain intact.
- Failure: Context is under budget but omits the command or expected result.
- Recovery: Improve retrieval and structured contracts before increasing compaction aggressiveness.
- Rollback: Restore the previous agent.md files and raise or remove page token budgets that discard required evidence.

## Token Efficiency agent guidance

Measure retrieval before compacting. Set per-page `agent.tokenBudget` in `page.mdx` and configure
`agent.compact` in `docs.config.ts[x]`; keep the Docs Cloud key outside source control through
`agent.compact.apiKeyEnv`. Preview writes with
`pnpm exec docs agent compact --changed --dry-run`, then compact only pages whose task commands,
constraints, expected results, and recovery steps remain recoverable. For SvelteKit or Astro,
append `--config src/lib/docs.config.ts` to this command and the doctor command below.

Run `pnpm exec docs doctor --agent` after compaction. Any configured golden tasks should still
satisfy their source, citation, scope, example, and UTF-8 budget requirements. Remember that a
generated sibling `agent.md` replaces only machine-readable page output; the rendered `page.mdx`
remains unchanged. If a compacted result drops required evidence or lowers the relevant page below
an overview, restore the prior `agent.md`, improve its contract and retrieval metadata, and rerun
the task before raising compaction aggressiveness.
## docs-cloud-compress-v1 protectJson docs agent compact --all

Configure `model: "docs-cloud-compress-v1"` with `protectJson: true`, then run `pnpm exec docs agent compact --all` and verify retrieval with `pnpm exec docs doctor --agent`.

## docs-cloud-compress-v1 agent context model

Use `model: "docs-cloud-compress-v1"` for page-level agent compaction and keep its API key outside source control.

## protectJson compact agent context

Set `protectJson: true` so compaction preserves structured configuration and schema examples.

## docs agent compact --all token budget verification

Run `pnpm exec docs agent compact --all`, then confirm golden retrieval, citations, executable examples, version selection, and context usage with `pnpm exec docs doctor --agent`.


---