--- title: "Agent Primitive" description: "Author human- and agent-specific page context, generated AGENTS.md instructions, and machine-readable route discovery." canonical_url: "https://docs.farming-labs.dev/docs/customization/agent-primitive" markdown_url: "https://docs.farming-labs.dev/docs/customization/agent-primitive.md" last_updated: "2018-10-20" agent: tokenBudget: 1100 task: "Add audience-specific agent guidance without changing the human page or exposing private data." outcome: "Human HTML and search exclude agent-only guidance while Markdown, Ask AI, MCP, llms-full.txt, and exports include it consistently." appliesTo: framework: - "nextjs" - "tanstackstart" - "sveltekit" - "astro" - "nuxt" version: - ">=0.2.60" package: - "@farming-labs/docs" prerequisites: - "The target page is MDX when it uses Agent, Human, or Audience components." - "Decide whether additive embedded guidance or a full sibling agent.md override is required." - "Remove secrets and private content because audience projection is not authorization." files: - "app/docs/example/page.mdx" - "app/docs/example/agent.md" - "docs/example/page.mdx" - "docs/example/agent.md" - "docs.config.ts" - "docs.config.tsx" - "src/lib/docs.config.ts" commands: - run: "pnpm exec docs doctor --agent" description: "Audit audience coverage, usefulness, and discovery parity." verification: - description: "Compare the rendered HTML page with its .md route and MCP read_page output." expect: "Human-only content stays in HTML, agent-only content stays in agent projections, and shared content appears in both." - run: "pnpm exec docs doctor --agent" expect: "Audience coverage and agent surface checks report no new failures." rollback: - "Remove the audience wrapper or sibling agent.md and restore the shared page content." failureModes: - symptom: "Agent-only instructions appear in rendered HTML or public search." resolution: "Use a static Agent block or Audience only=\"agent\" and verify that every surface uses the shared exposure resolver." - symptom: "The .md route omits the whole human-authored page." resolution: "Remove an accidental sibling agent.md override or copy the required contract into that override." --- ## Agent Contract Task: Add audience-specific agent guidance without changing the human page or exposing private data. Outcome: Human HTML and search exclude agent-only guidance while Markdown, Ask AI, MCP, llms-full.txt, and exports include it consistently. ### Applies To - Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt` - Version: `>=0.2.60` - Package: `@farming-labs/docs` ### Prerequisites - The target page is MDX when it uses Agent, Human, or Audience components. - Decide whether additive embedded guidance or a full sibling agent.md override is required. - Remove secrets and private content because audience projection is not authorization. ### Files - `app/docs/example/page.mdx` - `app/docs/example/agent.md` - `docs/example/page.mdx` - `docs/example/agent.md` - `docs.config.ts` - `docs.config.tsx` - `src/lib/docs.config.ts` ### Commands - `pnpm exec docs doctor --agent` — Audit audience coverage, usefulness, and discovery parity. ### Verification - Compare the rendered HTML page with its .md route and MCP read_page output. - Expected: Human-only content stays in HTML, agent-only content stays in agent projections, and shared content appears in both. - Run `pnpm exec docs doctor --agent` - Expected: Audience coverage and agent surface checks report no new failures. ### Rollback - Remove the audience wrapper or sibling agent.md and restore the shared page content. ### Failure Modes - Agent-only instructions appear in rendered HTML or public search. — Recovery: Use a static Agent block or Audience only="agent" and verify that every surface uses the shared exposure resolver. - The .md route omits the whole human-authored page. — Recovery: Remove an accidental sibling agent.md override or copy the required contract into that override. # 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 `...` inside `page.mdx` - Hidden in the normal docs UI - Included in agent-projected output when there is no sibling `agent.md` 2. `Human` - Embed `...` inside `page.mdx` - Included in rendered HTML and public search - Removed from agent-projected output 3. `Audience` - Use `...` as the explicit form of `Agent` - Use `...` 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 `` 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 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. ``` ## 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 `` 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. ## Sitemap See the full [sitemap](/sitemap.md) for all pages. Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md). Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).