rpc-agent 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # Changelog
 
+## 0.5.0
+
+Ship-check: `rpc check <url>` audits a page before launch, from the CLI, in
+CI or through MCP.
+
+### Added
+
+- `rpc check <url>` runs on a phone and a desktop width by default (`-d`
+  to change) and reports findings with an id, severity (`error`, `warn`,
+  `info`), message, selector or URL, devices and a fix. Checks:
+  - Basics: HTTP status, mixed content, uncaught exceptions, console errors,
+    `theme-color`.
+  - Meta and social: title, description, canonical, `lang`, viewport (and
+    zoom blocking), favicon, apple-touch-icon, `og:title`,
+    `og:description`, `og:image`, `og:url`, `twitter:card`. `og:image` is
+    fetched for its status, content type and pixel size.
+  - Layout shift: CLS (largest session window) after load and one scroll,
+    with the elements that moved. Warn above 0.1, error above 0.25.
+  - Unlabelled controls: buttons, links and `[role=button]` with no
+    accessible name, images without `alt`, form fields without a label.
+  - Fonts: missing or `block` `font-display`, above-the-fold fonts that
+    aren't preloaded, preloads without `crossorigin`, unused preloads,
+    font files that fail.
+  - Mobile viewport (phones): `100vh`, sideways scroll with the elements
+    that cause it, tap targets under 44x44, text fields under 16px.
+- Exit code 1 on errors; `--fail-on warn` fails on warnings too.
+  `--json` prints a versioned report (`schema: 1`, documented in the
+  README). `--shots` saves PNGs of the elements behind layout-shift and
+  overflow findings.
+- Auth works as for `rpc shot`: `--cookie`, `--header`,
+  `--storage-state`, `--allow-origin`, saved `rpc login` sessions and
+  `AUTH_REQUIRED` on a redirect to sign-in.
+- MCP `check` tool with the same options and the `screenshot` tool's auth
+  params. It returns a short text summary and the JSON report.
+
+### Unchanged
+
+- `rpc shot`, its output and the MCP `screenshot` tool. The MCP tool list
+  gains `check`.
+
+## 0.4.0
+
+Authenticated captures: screenshot logged-in pages without a hand-written
+"sign in, then screenshot" script.
+
+### Added
+
+- `rpc login <url>` opens a browser window; sign in, press Enter (or close
+  the window) and the storage state is saved for that origin to
+  `~/.config/rpc-agent/sessions/<origin>.json` (file 0600, directory 0700).
+  `--save <file>` writes it elsewhere.
+- `rpc login <url> --form`: headless email + password sign-in for CI and
+  agents, from `RPC_LOGIN_EMAIL` / `RPC_LOGIN_PASSWORD` (or `--email` /
+  `--password`), with `--email-selector`, `--password-selector` and
+  `--submit-selector`.
+- `rpc shot` uses the saved session for the target origin automatically.
+  `--no-session` opts out. `rpc sessions [list]` and
+  `rpc sessions clear [origin]` manage them.
+- `rpc shot --cookie "name=value[; Domain=…; Path=…]"`, `--header
+  "Name: value"` (both repeatable), `--storage-state <file>` and
+  `--allow-origin <origin>`.
+- A capture redirected to a login page (`/login`, `/sign-in`, `/auth`, …)
+  fails with code `AUTH_REQUIRED` and the hint ``Session missing or
+  expired: run `rpc login <origin>` `` instead of screenshotting the sign-in
+  form. Sessions whose cookies have all expired aren't loaded.
+- MCP `screenshot` takes `cookies`, `headers`, `storageState`, `useSession`
+  and `allowOrigins`. New `list_sessions` tool.
+- `rpc install --headed` also downloads full Chromium, for the
+  `rpc login` window. Without it, `rpc login` uses an installed Google
+  Chrome if there is one.
+
+### Security
+
+- Headers and cookies go to the target origin only (plus any
+  `--allow-origin`). Headers are injected per request through the CDP Fetch
+  domain, so a redirect to another host doesn't carry them. Saved sessions
+  and storage-state files load only the target origin's cookies and
+  localStorage.
+- Cookie, header and localStorage values are never printed: output shows
+  names with `•••`, and console errors and failure messages are scrubbed.
+- `--password` prints a warning; use the environment variable.
+
+### Changed
+
+- A page that redirects to a login URL now fails that device with
+  `AUTH_REQUIRED` (exit code 1) even when no auth was given. In 0.3 it
+  screenshotted the sign-in page and reported success.
+
+### Unchanged
+
+- With no auth in play, plain output, `--json` output and MCP results are
+  the 0.3 ones. With auth, they gain an `auth:` line / an `auth` field.
+  Existing MCP params and result fields are unchanged.
+
 ## 0.3.1
 
 Published to npm as `rpc-agent`.

package/README.md

@@ -1,5 +1,7 @@
 # rpc-agent
 
+<img src="https://raw.githubusercontent.com/akintola4/rpc-agent/main/docs/media/banner.png" width="100%" alt="rpc-agent: CLI + MCP server · device screenshots for AI agents · Claude Code, Codex, Cursor. A line drawing of a laptop, tablet and phone with a terminal in front running rpc shot; the Claude Code and Cursor marks and a terminal-prompt glyph for Codex sit beside it, with lines into the prompt.">
+
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/akintola4/rpc-agent/main/docs/media/hero-dark.png">
   <img alt="A site captured by rpc on an iPhone 15, an iPad Air 11 and a 1440 px desktop, each framed in its device bezel" src="https://raw.githubusercontent.com/akintola4/rpc-agent/main/docs/media/hero-light.png">
@@ -35,7 +37,8 @@ Chromium is not downloaded when the package installs. `rpc install` (or
 `npx rpc-agent install`) fetches it with rpc's own Playwright version, so
 the browser always matches the one rpc launches. It installs only
 Chromium's headless shell (plus Playwright's small ffmpeg), not the full
-Chrome for Testing build, since rpc never opens a visible window. Until you run it, every
+Chrome for Testing build, since captures never open a visible window
+(`rpc install --headed` adds it for `rpc login`). Until you run it, every
 command says Chromium is missing and prints that command, instead of
 failing with Playwright's own error. Browsers go to Playwright's usual
 cache, so other Playwright projects on the same version share them.
@@ -60,9 +63,12 @@ these docs say `rpc`, or `pnpm rpc` from inside the repo.
 ```sh
 rpc                    # interactive: pick a URL, devices and options
 rpc shot <url> [options]
+rpc check <url> [options]  # pre-launch audit, see Ship-check below
+rpc login <url> [--form]   # sign in once; later shots of that origin use the session
+rpc sessions [list|clear [origin]]
 rpc devices [--json]
 rpc doctor [--json]    # is Chromium installed, and does it launch?
-rpc install            # download Chromium with rpc's own Playwright version
+rpc install [--headed] # download Chromium with rpc's own Playwright version
 rpc mcp
 rpc help <command>     # options and examples for one command
 ```
@@ -96,6 +102,11 @@ the files it wrote:
 | `--no-emulate` | Viewport and DPR only: no mobile user agent or touch |
 | `--json` | Print the result as JSON |
 | `--open` | Open the output folder when done (`open`, `xdg-open` or `explorer`) |
+| `--cookie <c>` | `name=value[; Domain=…; Path=…]`, repeatable. See [Authenticated pages](#authenticated-pages) |
+| `--header <h>` | `Name: value`, repeatable, sent to the target origin only |
+| `--storage-state <file>` | Load a Playwright storageState JSON |
+| `--no-session` | Don't use the session saved by `rpc login` |
+| `--allow-origin <o>` | Also send headers and loaded cookies to this origin, repeatable |
 
 The URL can be a full URL, a bare local host (`localhost:3000` becomes
 `http://`), a bare domain (`example.com` becomes `https://`) or a path to a
@@ -168,9 +179,352 @@ listening on port N"), proxy, tunnel and offline errors, TLS errors (https
 against a plain-http dev server), missing files, redirect loops, navigation
 and `--wait-for` timeouts.
 
+## Authenticated pages
+
+Dashboards, billing and settings pages sit behind a login. rpc can carry a
+session so you don't need a hand-written "sign in, then screenshot" script.
+
+### Sign in once with `rpc login`
+
+```sh
+rpc login localhost:3000/sign-in
+rpc shot localhost:3000/app/settings/billing -d iphone-15,desktop-1440 --bezels
+```
+
+`rpc login` opens a browser window at the URL. Sign in as you normally
+would (SSO and 2FA work, it's a real browser), then press Enter in the
+terminal or close the window. rpc saves the browser's storage state
+(cookies and localStorage) to
+`~/.config/rpc-agent/sessions/<origin>.json`, for example
+`http-localhost-3000.json`. From then on, `rpc shot` on that origin uses it
+automatically, and the output says so:
+
+```
+auth: session http://localhost:3000 (saved 2026-10-29 22:55)
+ok iphone-15 (393x852 @3x)
+```
+
+The window needs full Chromium, which `rpc install` doesn't download (it
+fetches only the headless shell). Run `rpc install --headed` once, or have
+Google Chrome installed; rpc falls back to it.
+
+`--save <file>` writes the storage state to a file of your choice instead;
+use it with `rpc shot --storage-state <file>`.
+
+```sh
+rpc sessions                      # origins, cookie counts, saved and expiry times
+rpc sessions clear localhost:3000 # forget one origin
+rpc sessions clear                # forget all
+rpc shot localhost:3000/app --no-session   # capture as a signed-out visitor
+```
+
+### When the session is missing or expired
+
+If the page redirects to a login URL (a path segment like `/login`,
+`/sign-in`, `/signin` or `/auth`, different from the one you asked for),
+rpc doesn't screenshot the sign-in form. The device fails with code
+`AUTH_REQUIRED`:
+
+```
+x iphone-15 (393x852 @3x): Redirected to a login page (http://localhost:3000/sign-in) instead of http://localhost:3000/app/settings/billing
+   hint: Session missing or expired: run `rpc login http://localhost:3000`
+```
+
+A saved session whose cookies have all passed their expiry isn't loaded,
+and gives the same hint.
+
+### CI and agents: `rpc login --form`
+
+Without a person at the keyboard, `--form` signs in headlessly through a
+standard email + password form:
+
+```sh
+export RPC_LOGIN_EMAIL=ci@example.test
+export RPC_LOGIN_PASSWORD=...        # from your CI secret store
+rpc login https://staging.example.com/sign-in --form
+rpc shot https://staging.example.com/app/billing --json
+```
+
+It loads the page, waits for it to settle (so a client-side form has
+hydrated), fills the first match of `--email-selector` (default
+`input[type=email]`, then `autocomplete=username`, `name=email`,
+`name=username`, `#email`) and `--password-selector` (default
+`input[type=password]`), clicks `--submit-selector` (default
+`button[type=submit], input[type=submit]`, or presses Enter if there is no
+button), and waits for the URL to leave the login page. If it doesn't
+within `--timeout`, it fails and quotes any alert the page shows ("Invalid
+email or password"). `--email` works as a flag too; see the security notes
+before using `--password`.
+
+### Cookies and headers
+
+```sh
+rpc shot localhost:3000/app --cookie "session=$SESSION"
+rpc shot app.example.com/admin --cookie "sid=$SID; Domain=example.com; Path=/"
+rpc shot api.example.com/docs --header "Authorization: Bearer $TOKEN"
+rpc shot localhost:3000/app --storage-state auth.json
+```
+
+- `--cookie` is host-only on the target unless you give a `Domain`, which
+  must match the target host (or an `--allow-origin` host). `Secure`,
+  `HttpOnly` and `SameSite` are accepted too.
+- `--header` is sent only on requests to the target origin. Images,
+  scripts and API calls to other origins don't get it, and neither does a
+  redirect to another host (every redirect hop is checked).
+- `--storage-state` and saved sessions load only the target origin's
+  cookies and localStorage, even if the file holds others (an SSO domain,
+  analytics).
+- `--allow-origin https://api.example.com` widens all of the above to
+  another origin, for an app that calls a separate API host.
+- A saved session is used unless `--no-session` or `--storage-state` is
+  given. Cookies and headers are added on top of it.
+
+### Security notes
+
+- **Values are never printed.** Plain, rich and `--json` output and MCP
+  results show cookie and header names with `•••`. Console errors and
+  failure messages are scrubbed of every value rpc injected. The `--json`
+  result gains an `auth` field, for example
+  `{"cookies":[{"name":"sid","value":"•••","domain":"localhost","path":"/"}]}`.
+- **Session files are credentials.** They are written with mode 0600 in a
+  0700 directory (`$XDG_CONFIG_HOME/rpc-agent/sessions` if set;
+  `RPC_SESSIONS_DIR` overrides the location). Anyone who can read one can
+  act as you on that site until it expires. `rpc sessions clear` deletes
+  them. Don't commit a `--save` file.
+- **Keep passwords out of shell history.** Prefer `RPC_LOGIN_PASSWORD` from
+  a secret store over `--password`, which lands in your shell history and
+  is visible to other users in the process list; rpc warns when you use it.
+  The same goes for tokens in `--cookie` and `--header`: pass them from an
+  environment variable (`--header "Authorization: Bearer $TOKEN"`), not
+  literally.
+- **Use a test account.** Sign in as a user whose data you're happy for
+  screenshots (and the agent reading them) to see.
+
+## Ship-check
+
+`rpc check <url>` audits one page before you call it done. It loads the page
+on a phone and a desktop width, the way `rpc shot` does, and lists what's
+wrong: missing or broken social tags, layout shift, buttons a screen reader
+can't name, fonts that hide text while they load, and the mobile viewport
+bugs that only show up on a phone.
+
+```sh
+rpc check localhost:3000
+rpc check localhost:3000 --fail-on warn --json     # CI
+rpc check example.com/pricing -d pixel,iphone-se,desktop --shots
+```
+
+<img alt="rpc check in a terminal on turbo-start-paystack.vercel.app: both devices load with HTTP 200 and CLS 0.000, then a Meta and social box (no canonical link, no og:url) and a Mobile viewport box (16 of 54 tap targets under 44x44 px, with selectors and sizes), each finding with a fix, and the line 0 errors, 3 warnings, 0 info" src="https://raw.githubusercontent.com/akintola4/rpc-agent/main/docs/media/terminal-check.png" width="720">
+
+URLs, devices and auth work as in `rpc shot`: `localhost:3000` needs no
+scheme, `-d` takes ids or aliases (default `iphone-15-pro,desktop-1440`),
+and `--cookie`, `--header`, `--storage-state` and the session saved by
+`rpc login` all apply. A page that redirects to a login URL fails with
+`AUTH_REQUIRED`. Each run checks one URL. It isn't Lighthouse: CLS is the
+only performance number it reports.
+
+| Option | Meaning |
+| --- | --- |
+| `-d, --devices <ids>` | Devices to check on. The mobile checks run on phones only |
+| `--fail-on <level>` | `error` (default) exits 1 on errors; `warn` exits 1 on warnings too |
+| `--shots` | Save PNGs of the elements behind layout-shift and overflow findings into `--out` |
+| `-o, --out <dir>` | Where `--shots` writes. Default `./.rpc-shots` |
+| `--json` | Print the report as JSON (see below) |
+| `--wait-for`, `--wait`, `--timeout`, `--color-scheme` | As in `rpc shot` |
+| `--cookie`, `--header`, `--storage-state`, `--no-session`, `--allow-origin` | As in `rpc shot` |
+
+The exit code is 0 when there are no errors (with `--fail-on warn`, no
+warnings either), 1 otherwise and 2 for a usage error.
+
+### How a check runs
+
+Each device gets a fresh browser context, the same one `rpc shot` uses.
+Before the page's own scripts run, rpc installs a `PerformanceObserver` for
+`layout-shift`. It loads the page and waits for network idle (up to 10 s),
+web fonts and pending images. Then it waits a fixed 500 ms, scrolls down one
+viewport and back with a 300 ms pause each way, and reads the page. Because
+the sequence is fixed, CLS comes out the same on every run; the tests check
+the same page twice and allow 0.005 of difference.
+
+When a finding is identical on several devices it's reported once, with
+every device listed, so a missing `lang` appears one time, not two.
+
+### What it checks
+
+Severity decides the exit code. `error` fails the run, `warn` fails it only
+with `--fail-on warn`, and `info` never does.
+
+#### Basics
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `http-status` | error | The page answered 400 or above | Serve it with a 200 |
+| `page-load-failed`, `auth-required` | error | The page didn't load on a device (DNS, refused, timeout) or landed on a login page | The error's own hint, e.g. ``run `rpc login <origin>` `` |
+| `mixed-content` | error (warn if the browser upgraded every request) | `http://` requests on an https page | Load everything over https |
+| `uncaught-exception` | error | Exceptions thrown during load, first three listed | Fix the first one; the rest often follow from it |
+| `console-errors` | warn | `console.error` during load: the count and the first three | Fix or silence them |
+| `theme-color-missing` | info | No `<meta name="theme-color">` | Add one to tint the mobile browser bar |
+
+#### Meta and social
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `title-missing`, `title-long` | error, warn | No `<title>`, or one over 60 characters | 50 to 60 characters, key words first |
+| `description-missing`, `description-long` | warn, info | No meta description, or one over 160 characters | One or two sentences |
+| `canonical-missing` | warn | No `<link rel="canonical">` | The absolute URL to index |
+| `lang-missing` | error | No `lang` on `<html>` | `<html lang="en">` |
+| `viewport-missing`, `viewport-no-zoom` | error | No viewport meta, or one with `user-scalable=no` or `maximum-scale` under 2 | `width=device-width, initial-scale=1` and nothing that blocks zoom |
+| `favicon-missing` | warn | No `<link rel="icon">`, and `/favicon.ico` doesn't load | Add an icon link |
+| `apple-touch-icon-missing` | info | No `apple-touch-icon` | A 180x180 PNG |
+| `og-title-missing`, `og-description-missing`, `og-image-missing`, `og-url-missing` | warn | That Open Graph tag is absent | Add it; link previews read it |
+| `twitter-card-missing` | warn | No `twitter:card` | `summary_large_image` |
+| `og-image-relative` | warn | `og:image` isn't an absolute URL | Make it absolute; most scrapers don't resolve relative URLs |
+| `og-image-broken`, `og-image-not-image` | error | `og:image` doesn't return 200, or isn't served as an image | Point it at the image file |
+| `og-image-small`, `og-image-ratio` | warn, info | Smaller than 600x315, or not the 1.91:1 shape of 1200x630 | Export it at 1200x630 |
+
+rpc fetches `og:image` once per run and reads its pixel size from the file
+header (PNG, JPEG, GIF or WebP). The result is in the report's `ogImage`.
+
+#### Layout shift
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `layout-shift` | error above 0.25, warn above 0.1, info above 0 | CLS for the load and the scroll, with the three elements that moved most and each one's share | Reserve space for late content: `width`/`height` or `aspect-ratio` on media, `min-height` on async sections, nothing inserted above what's on screen |
+
+The score is computed the way Chrome computes it: the largest session
+window, meaning shifts less than 1 s apart and at most 5 s in total. Chrome
+marks shifts that follow input as `hadRecentInput`, including any in the
+first 500 ms after navigation, and those don't count. Totals under 0.001
+count as zero. Each device's score is also in `devices[].cls`.
+
+#### Unlabelled controls
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `button-no-name`, `link-no-name` | error | A button, link or `[role=button]` with no accessible name, such as an icon-only button | `aria-label`, visually hidden text, or alt text on the image inside |
+| `img-no-alt` | error | An `<img>` with no `alt` attribute (`alt=""` is fine) | Describe the image, or `alt=""` if it's decorative |
+| `field-no-label` | error | An input, select or textarea with no label | `<label for>`, a wrapping `<label>`, or `aria-label` |
+| `field-placeholder-only` | warn | A field labelled only by its placeholder | Add a visible label |
+
+rpc works out accessible names in the page from `aria-labelledby`,
+`aria-label`, `<label>`, `alt`, the text inside (minus anything
+`aria-hidden`), an SVG `<title>` and `title`. It skips elements assistive
+tech can't reach: `display: none`, `visibility: hidden`, `aria-hidden` and
+`inert`.
+
+#### Fonts
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `font-display-missing`, `font-display-block` | warn | A loaded `@font-face` has no `font-display` (Chrome then hides its text for up to 3 s) or uses `block`. The message says when it sets text above the fold (FOIT) | `font-display: swap` or `optional`; `&display=swap` for Google Fonts |
+| `font-not-preloaded` | warn | A font file that sets text in the first viewport isn't preloaded | `<link rel="preload" as="font" type="font/woff2" crossorigin>` |
+| `font-preload-no-crossorigin` | warn | A font preload without `crossorigin`, so the file downloads twice | Add `crossorigin` |
+| `font-preload-unused` | info | A preloaded font that no `@font-face` uses | Remove it, or match the URL exactly |
+| `font-failed` | error | A font file returned 400 or above | Fix the `src` URL |
+
+Every font finding names the file URL. The `@font-face` rules come from the
+page's stylesheets; the page can't read cross-origin ones (Google Fonts, a
+CDN), so rpc downloads and parses those itself. Faces with only `local()`
+sources, like next/font's size-adjusted fallbacks, never block text and are
+skipped.
+
+#### Mobile viewport
+
+These run on phone devices only.
+
+| id | Severity | When | Fix |
+| --- | --- | --- | --- |
+| `horizontal-overflow` | error | `scrollWidth` is wider than the layout viewport. Lists the outermost elements that stick out, furthest first | `max-width: 100%` on the element, or `overflow-x: auto` on its wrapper |
+| `vh-units` | warn | A rendered element sized with `100vh` in `height`, `min-height` or `max-height`, from a stylesheet rule that applies or an inline style | `100dvh` or `100svh`, with `100vh` before it as a fallback |
+| `tap-target-small` | warn | Links, buttons and form controls smaller than 44x44 CSS px. Links inside running text are exempt | Padding, `min-height`, or a bigger hit area |
+| `input-zoom` | warn | A text field with `font-size` under 16px; iOS Safari zooms the page when it gets focus | `font-size: 16px` or more |
+
+A headless phone has no browser bars, so `100vh` and `100dvh` measure the
+same there. That's why `vh-units` reads the CSS instead of measuring
+elements. The `height: 100vh; height: 100dvh` fallback pattern isn't
+flagged: the browser keeps only the last value it understands.
+
+### JSON report
+
+`--json` prints this object, and the MCP `check` tool returns the same one.
+`schema` goes up only when a field changes meaning or is removed; new fields
+can appear without it.
+
+```jsonc
+{
+  "schema": 1,
+  "url": "https://example.com/",
+  "devices": [
+    {
+      "device": "iphone-15-pro",
+      "name": "iPhone 15 Pro",
+      "viewport": { "width": 393, "height": 852 },
+      "dpr": 3,
+      "mobile": true,              // the phone-only checks ran here
+      "status": 200,
+      "finalUrl": "https://example.com/",
+      "title": "Example",
+      "cls": 0.012,
+      "layoutShifts": 2,
+      // only when the page didn't load on this device:
+      "error": "…", "code": "ERR_NAME_NOT_RESOLVED", "hint": "…"
+    }
+  ],
+  "summary": { "errors": 1, "warnings": 4, "info": 2 },
+  "findings": [
+    {
+      "id": "horizontal-overflow",      // stable; see the tables above
+      "check": "mobile",                // basics | meta | layout-shift | labels | fonts | mobile
+      "severity": "error",              // error | warn | info
+      "message": "The page scrolls sideways: 601px wide in a 393px viewport",
+      "fix": "Find the element that sticks out …",
+      "devices": ["iphone-15-pro"],
+      "selector": "div.pricing-table",  // when one element is the answer
+      "url": "…",                       // when a file is (a font, og:image)
+      "value": 208,                     // the number behind it, if there is one
+      "items": [                        // elements, files or log lines, when there are several
+        {
+          "selector": "div.pricing-table",
+          "text": "600px wide, 207px past the edge",
+          "value": 207,
+          "screenshot": "/abs/.rpc-shots/…-check-horizontal-overflow-1.png"  // with --shots
+        }
+      ]
+    }
+  ],
+  "ogImage": { "url": "…", "status": 200, "contentType": "image/png", "width": 1200, "height": 630 },
+  "auth": { … }                         // as in rpc shot, values masked
+}
+```
+
+Findings are sorted by check, in the order of the tables above, then by
+severity. `id`, `check`, `severity`, `message`, `fix` and `devices` are
+always there; the other fields appear when they apply.
+
+### In CI
+
+```sh
+npx rpc-agent install
+npx rpc-agent check https://staging.example.com --fail-on warn --json > ship-check.json
+```
+
+The exit code fails the job, and the JSON can go into a PR comment or a
+build artifact. For a page behind a login, sign in first with
+`rpc login <url> --form` (see [CI and agents](#ci-and-agents-rpc-login---form)).
+
+### With a coding agent
+
+Add the MCP server (below) and tell the agent to run `check` before it
+reports UI work as finished, for example in `CLAUDE.md` or `AGENTS.md`:
+
+```md
+Before you say UI work is done, run the rpc `check` tool on each page you
+changed and fix every error. Fix the warnings too, or say why one doesn't apply.
+```
+
 ## MCP server
 
-`rpc mcp` runs an MCP server on stdio with two tools.
+`rpc mcp` runs an MCP server on stdio with four tools.
 
 ### `screenshot`
 
@@ -187,6 +541,11 @@ and `--wait-for` timeouts.
 | `reducedMotion` | false | emulate `prefers-reduced-motion: reduce` |
 | `waitFor`, `waitMs`, `colorScheme`, `outDir`, `timeoutMs` | | as in the CLI |
 | `inline` | true | return images, not just paths |
+| `cookies` | | `[{ name, value, domain?, path? }]`, set on the target origin |
+| `headers` | | `{ "Authorization": "Bearer …" }`, sent to the target origin only |
+| `storageState` | | path to a Playwright storageState JSON |
+| `useSession` | true when one exists | use the session saved by `rpc login` for the origin |
+| `allowOrigins` | | extra origins that also get the headers and cookies |
 
 The result starts with a plain-text block: one line per device (or the error
 and hint), followed by the JSON summary (file paths, pixel sizes,
@@ -213,13 +572,44 @@ skipped (`slices 11-26 (y=8520-21656 css px) skipped inline`), all slices are
 written to disk and the summary gives their paths and the full PNG, so the
 agent can Read the rest without slicing anything itself.
 
+When auth is in play the text starts with an `auth:` line naming the
+session, cookies and headers (values masked), and the JSON summary gains an
+`auth` field. A capture that lands on a login page fails with
+`AUTH_REQUIRED` and the `rpc login` hint. Signing in is something the user
+does in a terminal (`rpc login`); the agent then just calls `screenshot`.
+
+### `check`
+
+Runs [Ship-check](#ship-check) on one URL.
+
+| Param | Default | |
+| --- | --- | --- |
+| `url` | required | http(s), file, bare host or local path |
+| `devices` | `["iphone-15-pro", "desktop-1440"]` | ids or aliases; the mobile checks run on phones |
+| `shots` | false | save PNGs of the elements behind layout-shift and overflow findings |
+| `outDir`, `waitFor`, `waitMs`, `colorScheme`, `timeoutMs` | | as for `screenshot` |
+| `cookies`, `headers`, `storageState`, `useSession`, `allowOrigins` | | as for `screenshot` |
+
+The result is two text blocks. The first is a short summary: the counts,
+then one line per error and warning with its id and selector, like
+`ERROR [button-no-name] 2 buttons with no accessible name at button.icon-menu`.
+The second is the JSON report described under [JSON report](#json-report).
+The call is a tool error only when the page failed to load on every device;
+findings, even errors, come back as a normal result for the agent to act on.
+
 ### `list_devices`
 
 Takes an optional `category` (`apple-phone`, `android-phone`, `tablet`,
 `laptop`) and returns ids, sizes and aliases.
 
+### `list_sessions`
+
+Lists the origins with a saved session: cookie count, when it was saved and
+whether it has expired. Never returns values.
+
 Files go to `outDir`, which is resolved against the server's working
-directory. Claude Code and Cursor start the server in the project root.
+directory. Claude Code and Cursor start the server in the project root; in
+Codex, set `cwd` on the server to choose the directory.
 
 ### Claude Code
 
@@ -261,6 +651,25 @@ so. Add the domain to the allowlist.
 From a clone, use `"command": "node"` and
 `"args": ["/absolute/path/to/rpc-agent/dist/cli.js", "mcp"]`.
 
+### Codex
+
+```sh
+codex mcp add rpc -- npx -y rpc-agent mcp
+```
+
+Or add it to `~/.codex/config.toml` (or `.codex/config.toml` in a trusted
+project). The Codex CLI and IDE extension read the same file:
+
+```toml
+[mcp_servers.rpc]
+command = "npx"
+args = ["-y", "rpc-agent", "mcp"]
+```
+
+From a clone, use `command = "node"` and
+`args = ["/absolute/path/to/rpc-agent/dist/cli.js", "mcp"]`. `/mcp` in the
+Codex TUI lists the servers it started.
+
 ## Development
 
 ```sh
@@ -278,6 +687,13 @@ appear once, that the IntersectionObserver section rendered, and the slice
 count and labels, including through the MCP server. The missing-browser tests
 point `PLAYWRIGHT_BROWSERS_PATH` at an empty temp dir.
 
+The Ship-check tests serve `test/fixtures/check`: one page per check
+(`meta.html`, `shift.html`, `labels.html`, `fonts.html`, `mobile.html`,
+`basics.html`) and `clean.html`, which must produce no errors or warnings.
+`shift.html` inserts a 300 px banner 800 ms after load, so CLS is known in
+advance (300/852 on the phone, 300/1440 on desktop); the test runs it twice
+and compares.
+
 The README media are built from real captures by `scripts/media/build.ts`;
 `docs/media.md` explains how. The CLI's design notes, and what it borrows
 from the `skills` CLI, are in `docs/cli-design.md`.
@@ -295,8 +711,15 @@ from the `skills` CLI, are in `docs/cli-design.md`.
 - The bezel geometry is RPC's, unchanged. On kind-default phones the page
   covers the dynamic island or notch, and generic monitors are drawn edge to
   edge with only the stand showing.
-- No auth, cookies, custom headers or scripted interaction before capture.
+- No scripted interaction before capture (beyond `rpc login --form`).
+- Login-page detection goes by the URL path. An app that shows its sign-in
+  form at the requested URL without redirecting is captured as is.
 - Every MCP call launches a fresh Chromium, which adds about a second.
+- Ship-check reads `100vh` only from stylesheets the page can read and from
+  inline styles; a `100vh` rule in a cross-origin stylesheet is missed. Tap
+  targets are measured by their box, so a hit area enlarged with a
+  pseudo-element still counts as small. CLS covers the load and one scroll,
+  not shifts caused by clicking around.
 
 ## License