vercel agent readability

How the two fit together

@vercel/agent-readability is an MIT-licensed package from Vercel. Its audit CLI checks a whole site against Vercel’s own readability checklist and can fail a CI job below a threshold. The Mumm gateway serves the clean version of your pages from your connected sources, and the Mumm for Business console reports what AI agents request.

Step	Tool	What it does
1. Audit the site	`@vercel/agent-readability`	Runs 25 weighted checks across the site. Exits 1 below `--min-score`.
2. Serve agents	`@rebilder/gateway`	Serves markdown from your sources to AI agents and to requests for markdown, with `Vary: Accept`. Browsers and search crawlers get your HTML.
3. Check key pages	`rebilder` CLI	Scores single URLs against ARS. Exits 1 when a page grades below `--fail-on`.
4. Measure	Mumm for Business console	Shows AI visits, the pages agents request and searches that found no answer.

1. Audit the site

The audit needs no install. Point it at a deployed URL, such as a preview deployment. The CLI needs Node.js 20 or later.

npx @vercel/agent-readability audit https://example.com --min-score 70 --json

--json prints the result as JSON: the score, a rating, and each check with its tier, detail and fix hint.
--min-score 70 exits with code 1 when the score is below 70. Choose the threshold that fits your site.
Without --json the CLI prints a readable report. Each failed check comes with a suggested fix.

2. Serve the clean version

The audit’s “Can agents read you?” group checks whether an agent that wants markdown receives it. Install the gateway with the Quickstart and connect your sources. It answers those requests with markdown rendered from your own product, service and page data. Browsers and search crawlers keep getting your HTML at the same URL.

Audit check	What the gateway does
`Agent UA → markdown`	Serves markdown to recognized AI agents on every URL a source answers.
`Accept header → markdown`	Serves markdown when a request sends `Accept: text/markdown`.
`Vary: Accept`	Sends `Vary: Accept` on the markdown and appends it to your HTML response. Next.js App Router pages replace that header on the HTML, so put `Accept` in the cache key of any cache in front of Vercel. Details.
`llms.txt`, `llms.txt valid`	`generateLlmsTxt` builds a spec-shaped llms.txt from the same sources. See llms.txt.
`.md URL → markdown`	With `markdownUrls: true`, serves each sourced page’s markdown at its URL plus `.md`, with a canonical `Link` back to the page.
`Markdown link alternate`	`markdownAlternateTypes` adds `<link rel="alternate" type="text/markdown">` to your Next.js metadata. `markdownAlternate` gives the same link for other frameworks.
`Frontmatter`	With `frontmatter: true`, starts each response with `title`, `description`, `canonical_url` and `last_updated` from your source. `last_updated` appears only for pages with an `updated` date.
`sitemap.md`	`createSitemapMdRouteHandler` serves your pages as a markdown list.
`Missing page → markdown`	With `notFound`, answers an agent’s request for a missing page with a 404 and a short markdown body that links your sitemap and llms.txt.

These options are off by default. Help agents find your markdown shows the config and how each adapter decides a page is missing. The <lastmod> dates the sitemap.xml check wants come from your own sitemap; use the dates your pages already state.

3. Check key pages against ARS

Vercel’s audit looks across the site. rebilder check scores single URLs against the Agent Readability Spec (ARS), including whether the facts a page needs, such as a price or opening hours, appear early. Pick the pages customers rely on. The CLI needs Node.js 22 or later.

npx rebilder check https://example.com/services/consulting https://example.com/pricing --fail-on B

--fail-on B passes a grade of B or better and exits 1 below it. Without the flag the command reports and exits 0.
Exit code 3 means the page could not be fetched. Exit code 4 means the check was blocked by policy, for example a robots.txt opt-out. Neither one is a grade.
--format junit --out ars.xml writes a report your CI can display.

4. Measure and improve

CI shows what an agent would receive. The Mumm for Business console shows what agents actually requested: AI visits, the pages they asked for and searches that found no answer. Connect the gateway’s event sink to fill it. See Events.

From there, customer checks and Opportunities point to missing answers. You publish sourced answers through Answers Hub, and Autopilot on Pro keeps supported answers current. See pricing.

Example: both checks in one workflow

A GitHub Actions workflow that runs both checks. Set SITE_URL to the deployment you want to check, and replace the page path with one of yours.

name: Agent readability

on:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    env:
      SITE_URL: https://example.com   # the deployment to check
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 22

- name: Audit the site (@vercel/agent-readability)
        run: npx @vercel/agent-readability audit ${{ env.SITE_URL }} --min-score 70 --json

- name: Check key pages (ARS)
        if: always()   # report both, even when the audit fails
        run: npx rebilder check ${{ env.SITE_URL }}/services/consulting --fail-on B --format junit --out ars.xml

Both commands fetch your live pages, so run them after the deploy they should check.