# [Use Rebilder with @vercel/agent-readability](https://rebilder.com/docs/vercel-agent-readability)

> Run Vercel’s agent-readability audit in CI, serve the clean version with the Rebilder gateway, then check key pages and measure AI visits.

- **Updated:** 2026-09-28
- **Author:** Rebilder
- **Section:** Getting started
- **Description:** Run Vercel’s agent-readability audit in CI, serve the clean version with the Rebilder gateway, then check key pages and measure AI visits.
- **Publisher:** Rebilder

## How the two fit together

[@vercel/agent-readability](https://www.npmjs.com/package/@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 Rebilder gateway serves the clean version of your pages from your connected sources, and the 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 | Rebilder Console | Shows AI visits, the pages agents request and searches that found no answer. |

> **Two specs with similar names** Vercel’s README calls its checklist the Agent Readability Spec. Rebilder publishes a separate standard, the [Rebilder Agent Readability Spec (ARS)](/spec/ars). They check different things, and a result from one does not convert into a score in the other. For a side-by-side view, see [Rebilder and @vercel/agent-readability](/compare/vercel-agent-readability).

## 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.

terminal

```
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](/docs/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` | Adds `Vary: Accept` to both the markdown and the HTML response of a negotiated URL. |
| `llms.txt`, `llms.txt valid` | `generateLlmsTxt` builds a spec-shaped llms.txt from the same sources. See [llms.txt](/docs/llms-txt). |

Other checks, such as `.md` URLs, a markdown sitemap and markdown 404 pages, depend on how your app routes those addresses. The audit names each failed check with a fix hint.

> **Already route agents with Vercel’s middleware?** Give each path one owner. A gateway source that returns `null` for a path passes the request to your fallthrough, so the gateway can serve your product and service pages while your existing middleware keeps the paths it already handles.

## 3. Check key pages against ARS

Vercel’s audit looks across the site. `rebilder check` scores single URLs against the [Rebilder Agent Readability Spec](/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.

terminal

```
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 [Console](/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](/docs/events).

From there, customer checks and Opportunities point to missing answers. You publish sourced answers through [Answers Hub](/docs/answers-hub), and Autopilot on Pro keeps supported answers current. See [pricing](/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.

.github/workflows/agent-readability.yml

```
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 (Rebilder 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.