Validation and doctor

Two read-only checks, with no AI. Run larecipe:validate after every docs change to check that the docs are correct, and larecipe:doctor after a deploy to check what agents get from your app.

php artisan larecipe:validate
php artisan larecipe:doctor

larecipe:validate reads every page through the real renderer and reports broken links, schema errors, unknown components, missing snippets, live references that stopped resolving and more. It exits with 1 when it finds an error, so CI can stop on it. Warnings never fail it. Your coding agent runs it before every push.

Each issue names its level, rule, page and line, with a fix when LaRecipe knows one:

  ERROR  links.broken  3.x/agents/mcp line 220
         Link to ../sources/docs-migrations.md: there is no page at "sources/docs-migrations".
         Fix: Fix the link, or write the page it points to.

That one is from this site, while these docs were being written: the page it links to was next in line.

larecipe:validate

Without options it checks every version and language of every doc set. Narrow it down, or ask for the report agents read:

php artisan larecipe:validate --set=docs --docs-version=3.x
php artisan larecipe:validate --json

The version option is --docs-version because Symfony reserves --version for the application. A set or version that does not exist exits with 2.

Every issue has a stable rule id, such as links.broken or components.unknown. Validation and rendering never disagree: the component, snippet, reference and placeholder rules come straight from the renderer, which reports every problem it meets while rendering the page.

{
    "ok": false,
    "summary": { "pages": 41, "errors": 48, "warnings": 3 },
    "issues": [
        {
            "level": "error",
            "rule": "links.broken",
            "set": "docs",
            "page": "3.x/operate/validation",
            "file": "3.x/operate/validation.md",
            "line": 8,
            "message": "Link to caching.md#the-cache-stor: anchor #the-cache-stor not found.",
            "fix": "Use #the-cache-store."
        }
    ]
}

php artisan larecipe:validate [--set [SET]] [--docs-version [DOCS-VERSION]] [--json]

In CI

One step is enough. The exit code fails the job on errors:

- run: php artisan larecipe:validate

For GitHub Actions, the installer can write a ready-made workflow that also lists the pages a pull request left stale: see the CI check.

larecipe:doctor

The doctor grades each doc set the way the AFDocs checks grade a docs site for agents, from inside your app: Markdown twins, llms.txt and its links, 404s, discovery headers, redirects, skill.md, the MCP endpoint and the cache store. It sends real requests through the app's HTTP kernel, with the user agent LaRecipe-Doctor/1.0, so it needs no running server and sees your middleware, headers and exception handler exactly as an agent would. URLs are built from APP_URL.

Each check passes, warns, fails or is skipped, with a fix for every finding, and the set gets a grade from A to D. The command exits with 1 only when a check fails. --set limits it to one set, and --json prints the report.

  docs http://127.0.0.1:8780/

  PASS  llms.txt: llms.txt is served and every index is under 50,000 characters.
  PASS  llms.txt links: 10 sampled llms.txt links resolve to Markdown.
  WARN  Markdown twins: Only 93% of the words on http://127.0.0.1:8780/3.x are in its Markdown.
        Fix: Give custom components a Markdown form (LaRecipe::component(...)->markdown(...)).
  PASS  Missing pages: A missing page is a real 404, with a Markdown body for agents.
  PASS  Discovery hints: Pages send Link headers to their Markdown twin and llms.txt, and link to llms.txt in the page.
  PASS  Redirects: 1 redirects land on a page.
  PASS  skill.md: skill.md is served as the "larecipe" skill.
  PASS  MCP endpoint: http://127.0.0.1:8780/mcp serves search_docs, read_page, list_pages, submit_feedback.
  SKIP  Cache store: Repository sets read from files; no cache store is needed.

  Agent readiness: A (94 / 100)

php artisan larecipe:doctor [--set [SET]] [--json]

Which one when

A page can pass validation and still fail the doctor: a proxy that strips Link headers, or an exception handler that turns a 404 into a soft error page, never shows up in the content.

Next

• Deployment: where both commands fit in a deploy.
• The CI check: go deeper with the ready-made GitHub Actions workflow.
• Agent surfaces: the files the doctor checks.