Agent surfaces

• On a versioned set, the root /llms.txt lists the default version's pages, so an agent that starts there reaches the current docs in one fetch, and links every version's own index (/3.x/llms.txt, /2.x/llms.txt) with its status.
• On a multilingual set, each language has its own index: /ar/llms.txt, /ar/3.x/llms.txt.
• llms.txt stays small. Each file stays under agents.llms_txt_limit characters (50,000 by default, the AFDocs threshold). When a version outgrows it, each top-level navigation group moves to its own file, such as /3.x/get-started/llms.txt, and the index links to them. Descriptions are dropped only as a last resort.
• llms-full.txt streams, so a large version never has to fit in memory. A versioned set's root /llms-full.txt redirects to the default version's file. Past agents.llms_full_limit characters (400,000 by default) a version splits by navigation group, like llms.txt, and anything left out is listed by link, never cut silently. The Markdown twins and MCP stay the better way to read one page.

Its frontmatter uses only the portable Agent Skills keys, name and description, so any agent can load it.

---
name: larecipe
description: 'Use when working with LaRecipe: ... Explains how to search and read the LaRecipe docs (MCP tools, llms.txt and a Markdown version of every page) and lists the key pages.'
---

# LaRecipe

## Read the docs

1. Search first: call `search_docs` on the MCP server at https://larecipe.saleem.dev/mcp, or scan the index at https://larecipe.saleem.dev/llms.txt.
2. Read whole pages as Markdown: call `read_page`, or add `.md` to any page URL.
3. Answer from the pages you read, and cite their URLs.

A repository set can ship its own skills in a skills/ folder at the root of its docs, one folder per skill:

docs/
├── larecipe.json
├── skills/
│   └── billing-integration/
│       ├── SKILL.md
│       └── references/
│           └── webhooks.md
└── 3.x/

Each one is served at /skills/{name}/SKILL.md, with its references/, scripts/ and assets/ files next to it. A hand-written skill named like the generated one replaces skill.md. php artisan larecipe:validate checks every SKILL.md against the Agent Skills spec (skills.spec).

/.well-known/agent-skills/index.json lists every skill of every public set on the site, each with its URL and a sha256 digest of the exact bytes served, so tools such as npx skills add https://larecipe.saleem.dev can find and verify them.

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "larecipe",
      "type": "skill-md",
      "description": "Use when working with LaRecipe: ...",
      "url": "https://larecipe.saleem.dev/skill.md",
      "digest": "sha256:b688d79694302d4ae0866b9c855ef418c38dae9714691a1e6065278581184c39"
    }
  ]
}

A .md URL or a text/markdown request for a page that does not exist gets a real 404 with a short Markdown body: the path it asked for, up to five similar pages from the search ranker, and the docs index.

# Page not found

There is no page at `/agents/mcp-server` in LaRecipe.

Similar pages:

- [The MCP server](https://larecipe.saleem.dev/3.x/agents/mcp.md): ...

Docs index: https://larecipe.saleem.dev/llms.txt

A page that exists but is hidden from the caller gets exactly the same answer, so a 404 never confirms that a private page exists. HTML misses get the same suggestions on the not-found page.

Every page response, HTML or Markdown, carries headers that point agents at the other surfaces:

Vary: Accept
Link: <https://larecipe.saleem.dev/3.x/index.md>; rel="alternate"; type="text/markdown", <https://larecipe.saleem.dev/3.x/llms.txt>; rel="describedby"; type="text/plain", <https://larecipe.saleem.dev/mcp>; rel="mcp", <https://larecipe.saleem.dev/skill.md>; rel="describedby"; type="text/markdown"; title="skill"
ETag: "80ff5bd7412bd994f7dc"
Last-Modified: Sat, 17 Oct 2026 15:22:00 GMT

• Vary: Accept tells caches that the same URL answers with HTML or Markdown.
• Link advertises the Markdown twin, the version's llms.txt, the MCP endpoint and skill.md to any client that reads headers. A link appears only when its surface is on.
• ETag and Last-Modified let agents and caches revalidate cheaply. A matching If-None-Match gets a 304.
• Every page body also holds a link to the version's llms.txt, hidden from sight and from the keyboard, for agents that read the HTML but not its headers.

How long each response may be cached, for guests, signed-in readers and private pages, is listed under security.

/sitemap.xml lists every public page of a public set, with lastmod and hreflang alternates for its translations. A sitemap is a public artifact, so it lists only what a guest may see: private sets answer 404, and private versions, private pages, hidden pages and noindex pages are left out.

Agents that can fetch a URL but have no MCP client can search through GET /ask?q= (under a prefixed set, /docs/ask?q=). It is off by default; turn it on with agents.ask_endpoint:

// config/larecipe.php
'agents' => [
    'ask_endpoint' => true,
],

It answers with ranked pages as JSON (title, url, markdown_url, heading, snippet, description, score), using the same ranker and the same access rules as the MCP search_docs tool. version, locale and limit (up to 20) are optional query parameters.

Every fetch of these files fires a Laravel event (MarkdownServed, LlmsTxtServed, SkillServed) with the request kind, so agent traffic that client-side analytics never see can reach your own tools. See analytics and events.

php artisan larecipe:doctor grades all of this from inside the app, the way AFDocs grades it from outside: Markdown parity, llms.txt size and links, 404 behavior, headers and redirects. See validation and doctor.