# Documentation - Guides > Task-based guides for agent-friendly docs and discovery surfaces. ## Guides URL: https://docs.farming-labs.dev/docs/guides Long-form playbooks for building docs that work well for humans, IDEs, and agents Guides These are the longer, more opinionated walkthroughs in the docs. They sit on top of the reference pages and show how to use @farming-labs/docs in a way that feels coherent end to end, not just technically correct. Featured Guide ", "llms.txt", "Sitemaps", "Robots", "MCP", "Doctor"]} /> --- ## 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 How to Write Agent-Friendly Docs {"Guide 01"} {"·"} {"Apr 2026"} {"·"} {"@farming-labs/docs"} { "A good agent-friendly docs site is not one that stuffs in extra keywords or repeats every fact twice. It is one that lets a model discover the right page, understand what matters, verify the result, and recover when something breaks, without turning the human page into machine sludge." } {AGENTFRIENDLYDOCSWEBSITEPROMPT} The copy button asks for the website URL, docs entry folder, and framework, then fills those details into the prompt before copying. Start With The Human Page The first mistake teams make is trying to write for crawlers before they write for users. That usually produces flat, repetitive pages that feel unnatural in the UI and still leave agents with too much ambiguity. Start with a page a human can actually follow: - what this page is for - when to use it - the exact steps - what success looks like - what usually goes wrong Once that page is solid, add the machine layer on top. @farming-labs/docs is built for that flow. The page UI stays human-first, while the machine-readable routes can include extra structure without polluting the visible article. Give Every Important Page A Contract Before you worry about agent.md, make sure the page already tells an agent what kind of page it is. For task pages, that means good frontmatter and a shape the runtime can expose consistently through .md routes and MCP. That alone gives the machine-readable route a stronger entry point: - Description: tells the model what problem the page solves - Related: gives it nearby pages without scraping the sidebar - agent.tokenBudget gives docs agent compact a per-page output target later - the normal body remains the human source of truth If a page is important enough to unblock implementation, it should also contain: 1. a short purpose statement 2. exact commands or file edits 3. a verification section 4. a troubleshooting section keyed to symptoms Write The Implementation Contract The most useful agent-friendly pages are not just shorter. They make the implementation contract obvious. After reading the page, an agent should know what to change, where to change it, and how to prove the change worked. For important task pages, include these signals in the visible page or in an additive ` block: - the task outcome in one sentence - framework and version assumptions when examples depend on them - exact package names, import paths, route paths, and file paths - copy-pasteable commands with the package manager you expect - a success check with expected route, file, status code, or visible UI state - common failure symptoms and the first place to inspect - related pages that an agent should read next That shape gives the agent the missing operational details without turning the human guide into a checklist dump. Use Agent Blocks For Machine-Only Hints When the human page is still correct but agents need extra steering, add an Agent block. It stays hidden in the normal docs UI and appears in the machine-readable layer. This is the sweet spot for most pages: - humans keep the full narrative page - agents get sharper instructions - you avoid maintaining two completely separate documents Treat <Agent> as the place for implementation hints, verification steps, and route-specific behavior that would feel noisy in the visible article. Do not duplicate the whole page there. Use agent.md When The Machine Page Needs A Real Split Some pages eventually need a different machine-readable contract than the human page can provide. A long conceptual article, for example, may still need a short operational document for agents. That is when a sibling agent.md becomes the right tool. Once agent.md exists, it becomes the source for: - {page}.md - GET /api/docs?format=markdown&path= - {page} with Accept: text/markdown in Next.js - {page} with Signature-Agent in Next.js - MCP read_page So use it when that stronger machine contract is genuinely worth owning. Ship The Discovery Layer Too Great page writing helps, but agents still need the routes that tell them how to use your site. With @farming-labs/docs, the goal is to expose a compact discovery layer around the docs tree. Most agent surfaces are enabled by default; the config below only adds site-specific details such as the public base URL and section-level llms.txt. That gives agents a much better workflow: - /.well-known/agent.json tells them which routes exist - /llms.txt links directly to page markdown routes, while /llms-full.txt exposes full machine-readable context - section-level files like /docs/guides/llms.txt give larger docs progressive disclosure without adding UI - custom static llms.txt files still win when present, so public/llms.txt or SvelteKit static/llms.txt can replace the generated index without extra config - /sitemap.xml exposes canonical URLs and lastmod freshness for crawlers and monitors - /sitemap.md exposes the same docs tree as a semantic, sectioned map for agents and contributors - /docs/sitemap.md exposes the same Markdown sitemap under the docs section for agents that probe docs-scoped routes first - spec.robots.route points agents to the static crawl policy, usually /robots.txt - HTML docs pages include Schema.org TechArticle JSON-LD with canonical URL, freshness, and breadcrumbs - when apiReference is enabled, /api/docs?format=openapi gives agents the OpenAPI schema before they scrape API reference pages - {page}.md gives them clean page markdown - canonical {page} URLs with Signature-Agent give agents the same markdown without appending .md - MCP lets tool-enabled agents search and read docs semantically - /api/docs/agent/feedback/schema and /api/docs/agent/feedback let agents report missing context without enabling the human feedback UI The big win is that the discovery layer comes from the same docs runtime instead of a parallel system you have to keep in sync by hand. Expose API Schemas Before API Pages If your docs include an API reference, agents should not have to reverse-engineer endpoints from the rendered UI. Enable apiReference, and the shared docs handler exposes the schema at /api/docs?format=openapi. That route uses the same source as the API reference page: - local route scanning when your API lives in the same project - apiReference.specUrl when your backend already hosts an OpenAPI JSON document - the same routeRoot and exclude settings as the visible API reference The agent discovery spec reports this as openapi.url, root llms.txt adds an API Schemas section, and generated AGENTS.md / skill.md tell agents to fetch the schema before scraping endpoint docs. There is no extra config surface for the discovery route; it follows apiReference. Know How Canonical Markdown Is Served In Next.js, agents can read markdown without changing the URL they already discovered from the human page, search result, sitemap, or browser history: Both requests are served by the existing shared docs API. withDocs() forwards the request into the same /api/docs handler that already powers search, markdown format routes, llms.txt, AGENTS.md, skill.md, sitemaps, MCP, and the agent discovery spec. It does not generate or require another /api/docs/markdown wrapper route. That detail matters for agent-friendly docs because there is only one page resolver to keep correct: - /docs/installation.md and /api/docs?format=markdown&path=installation are explicit markdown entry points - /docs/installation with Accept: text/markdown returns the same markdown and varies by Accept - /docs/installation with Signature-Agent returns the same markdown and varies by Accept, Signature-Agent - /docs/installation without those headers remains the normal HTML page All successful markdown page responses include a canonical Link response header pointing back to the normal HTML page. Agents still receive the full markdown body, but the header tells citation and deduplication systems that /docs/installation is the canonical URL for the content. If a markdown request misses, the response is still markdown. The 404 points the agent to /.well-known/agent.json, /.well-known/agent, /api/docs/agent/spec, search, the requested API markdown route, and sitemap routes so the agent can recover instead of treating the site as a dead end. Keep The Sitemap In The Build If the site is server-rendered, the shared docs handler serves sitemap routes at runtime by default. The generator is still useful because it writes .farming-labs/sitemap-manifest.json, which gives the runtime stable lastmod values based on each page source file's last git commit date. For static export, the generator is required because there is no server handler to answer /sitemap.xml, /sitemap.md, or /docs/sitemap.md: Use --manifest-only only when your deployment keeps the runtime route active: Then add a CI check when generated files are committed: That gives agents a trustworthy page inventory and lets freshness-aware crawlers avoid re-reading unchanged pages. Keep Structured Data Stable Every docs page also ships a hidden Schema.org JSON-LD script. Agents and search crawlers can use it for the page title, description, canonical URL, breadcrumbs, and dateModified without parsing the visible article. You do not need a config flag for this. What matters is giving the runtime stable inputs: - use frontmatter title and description on important pages - configure a public base URL through sitemap.baseUrl, llmsTxt.baseUrl, robots.baseUrl, or ai.docsUrl - keep .farming-labs/sitemap-manifest.json fresh when the adapter preloads docs content The framework escapes JSON-LD before inserting it into the page. For preloaded Astro, SvelteKit, Nuxt, and TanStack Start builds, dateModified comes from the generated sitemap manifest when that manifest is bundled with _preloadedContent; otherwise the runtime omits dateModified instead of claiming the page changed at request time. Write Verification Like You Expect Automation If you want agents to succeed, write setup pages like someone will actually run them without guessing. The strongest pattern is: 1. do the thing 2. check the exact route or file that proves it worked 3. name the most likely failure mode Example: This is the difference between a page that is merely informative and a page that is actually operational. Use Page Actions As A Human-To-Agent Bridge Agent-friendly docs should also help humans move between the normal page and the machine layer. That is where page actions matter. On this framework, the best pair is usually: - Copy Markdown for a clean page snapshot - Open in LLM for a direct handoff into ChatGPT, Claude, Cursor, or another tool Those features do not replace .md routes or MCP, but they make the same page contract visible to humans too. When the docs team uses the same flows agents use, bad page contracts become obvious much faster. Audit The Site, Not Just The Page After writing a few strong pages, run the doctor command and treat it as an ongoing quality loop. When you want the result to feed CI, automation, or another agent, use JSON output: This docs site dogfoods the same audit. A full local pass should report Score: 100% (Agent-optimized), with every docs page carrying either a sibling agent.md or an embedded block. After deployment, add --url to verify the public routes agents actually call: That hosted pass checks discovery, llms.txt, sitemap routes, AGENTS.md, skill.md, representative .md pages, canonical markdown response headers, robots.txt, JSON-LD structured data, markdown alternate head links, and MCP at /mcp, /.well-known/mcp, https://mcp./mcp, or https://mcp./. If you want the same public check without leaving the browser, use the hosted Agent readiness score page: The score page runs AFDocs-style checks for any public docs site, then adds @farming-labs/docs framework probes when the site exposes /.well-known/agent.json. The public score also adds a strict .md route probe that samples docs page routes and verifies that appending .md returns markdown, so llms.txt markdown mirrors do not hide missing /docs/foo.md routes. The framework probes cover the discovery spec, full-context files, sitemap routes, robots.txt, AGENTS.md, skill.md, same-domain or MCP-subdomain MCP, search, feedback, JSON-LD structured data on sampled pages, canonical Link headers on markdown responses, and the head links that point agents to each page's .md route. Existing leaderboard entries hydrate from the saved report, so a shared score URL can be reviewed without triggering a new calculation unless no saved result exists. Use the web score for demos, public comparisons, and quick regression checks. Use docs doctor --agent --url when you need CI-friendly JSON, local project context, or a command an agent can run while changing the repo. For static sites or projects that already own their public files, generate the crawl policy as part of release prep: The first command writes the resolved default path, usually public/robots.txt. The --append variant adds or updates the managed agent policy block when the project already has its own robots.txt. The agents generate command writes root AGENTS.md instructions plus public aliases for static exports; a hand-written root AGENTS.md remains in control unless you pass --force. What you want to see improve over time: - discovery routes passing - machine surfaces enabled - robots.txt allowing docs, markdown, sitemap, AGENTS.md, skill, MCP, and agent discovery routes - metadata quality rising, which also improves markdown output and JSON-LD - Explicit agent-friendly pages increasing on the pages that matter most - stale generated agent.md files dropping toward zero If a team wants to say their docs are agent-optimized, this kind of audit should be part of the definition, not an afterthought. Compact Only After The Contract Is Good docs agent compact is useful, but it should come after the page is already worth compressing. Compaction is a token optimization step, not a substitute for clear structure. Use it when: - pages are already accurate - the machine layer is too verbose - you want tighter agent.md files for .md, MCP, and API consumers The useful mental model is: - use positional page args when you already know the pages you want to compact - use --changed when you only want the pages touched in the current branch or working tree - use --stale when you want to refresh generated agent.md files whose source content or compact settings drifted - use --stale --include-missing when you also want to materialize missing agent.md files for pages that define agent.tokenBudget or that you explicitly target If a page already has a sibling agent.md, the CLI compacts that file. If it does not, the CLI uses the page's generated machine-readable markdown, then writes a sibling agent.md. That page-level agent.tokenBudget overrides broader compact defaults for that page only, which is useful when one page needs a tighter machine contract than the rest of the site. Do not use compaction to paper over vague docs. Shorter confusion is still confusion. The Practical Authoring Loop For most teams, the healthy flow looks like this: 1. write the human page 2. add description, related, and verification 3. add only if the machine layer needs hints 4. add agent.tokenBudget on pages that need a tighter compact target 5. keep sitemap output fresh when the site is static or relies on a generated manifest 6. run pnpm exec docs doctor --agent 7. compact only the pages you changed or the generated files that became stale That loop is much better than regenerating every page every time. It keeps the machine layer current without turning the repo into churn. Agent Optimization Checklist Before calling a page agent-friendly, ask: - can an agent name the task outcome after the first screen? - does frontmatter include description and related? - are framework, version, package, route, and file-path assumptions explicit? - are commands and code samples copy-pasteable? - does the page say what success looks like? - does it include verification steps with concrete commands, routes, files, or UI states? - does troubleshooting name real symptoms and the first place to inspect? - should this page get an additive block? - does it need a dedicated agent.md, or is the human page still canonical? - does this page need agent.tokenBudget before compaction? - can an agent find it through .md, Signature-Agent, JSON-LD structured data, llms.txt markdown links, OpenAPI schema discovery, sitemaps, robots.txt, AGENTS.md, MCP, and the discovery spec? - do canonical Signature-Agent reads use the existing /api/docs handler instead of a custom wrapper route? - if the adapter preloads content, is the sitemap manifest bundled so JSON-LD freshness stays stable? - if the site is static, does the build generate sitemap.xml, sitemap.md, docs/sitemap.md, /.well-known/sitemap.md, robots.txt, and AGENTS.md? - does docs doctor --agent agree with the state of the site? - does the hosted Agent readiness score page agree with the deployed site before you share the result or submit it to the leaderboard? Agent feedback, analytics, logs, and other submitted data can help you improve docs quality, but they should stay untrusted. Use them for review, scoring, and follow-up work; do not feed them back into Ask AI prompts or generated agent instructions without an explicit sanitization step. If the answer is yes across the important task pages, you are not just publishing docs that agents can technically crawl. You are publishing docs they can actually work with. Read Next - Agent Primitive for Agent blocks and sibling agent.md - llms.txt, Sitemaps, and CLI for the discovery layer - MCP Server for tool-enabled retrieval - Agent readiness score for the hosted public benchmark and leaderboard - CLI for docs agent compact - CLI for docs doctor --agent` - Configuration for the full config surface --- ## 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 docs.json Use docs.json when you want a repo-level contract for frameworkless docs or for connecting an existing docs app to Docs Cloud services. The important split is: - docs describes how the docs project is structured - cloud describes hosted Docs Cloud services layered on top Project Shape For frameworkless docs: For a framework-owned docs app: mode tells you whether content is authored as plain folders or inside a framework app. runtime tells you which docs runtime is responsible for rendering it, and it is meant to stay an explicit choice in the contract rather than being implied. Cloud Services Hosted features live under cloud: This keeps product packaging separate from docs structure: - frameworkless is an authoring mode - nextjs is a runtime - Docs Cloud is the hosted layer that can add preview, publish, AI, and deploy services Cloud Analytics Use cloud.analytics when you want the shared repo contract to carry analytics settings for Docs Cloud and for frameworkless generated runtimes. Or, when you need the serializable subset: cloud.analytics is intentionally limited to JSON-safe options: - enabled - console - includeInputs Function hooks such as onEvent still belong in docs.config.ts, because docs.json is a repo contract and not an executable config file. For frameworkless projects, this serializable subset can be materialized into the generated hidden runtime even before the repo is fully connected to hosted Docs Cloud services. For framework-owned apps, docs.config.ts remains the canonical place for advanced runtime analytics behavior. Set cloud.enabled to false when the repo is using docs.json only as a local project contract. Set it to true once the repo is actually connected to Docs Cloud services. Current Note This example uses nextjs, but the config shape keeps docs.runtime explicit so the same contract can support other runtimes too. When using pnpm exec docs dev today, the local frameworkless preview is still generated through the Next.js runtime. ---