diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index 8d07487..020c28e 100644
--- a/AGENT-INSTALL.md
+++ b/AGENT-INSTALL.md
@@ -62,7 +62,8 @@ The pages get a build step, even though nothing is compiled. The build is what r
 2. Install `@patchstack/connect` as a runtime dependency with the project's package manager. If it is missing, `setup` adds it itself.
 3. Run `npx @patchstack/connect setup`. In a hosted builder, scope `PATCHSTACK_ENVIRONMENT=sandbox` to that command — see "Automated setup".
 4. Finish any `✘` line under `To do` in the report at the end of `setup`. "Automated setup" names each one. Do not start, restart or stop the person's app, and do not touch its data, to check the install: `setup` never runs the app, and the protection check needs an app the person already has running.
-5. End by passing on the `──── Summary ────` that `setup` prints: what Patchstack found, the link, what is left to do and the next step, with a reminder to deploy when they are ready. See "The message you end on".
+5. Run `npx @patchstack/connect doctor`. Fix every `✗` it reports, as its `Fix:` line says, and run it again until none is left. A `✗` marked "for the app owner" (connecting their Patchstack account, publishing the app) is not yours to fix: the summary already hands it to the person.
+6. End by passing on the `──── Summary ────` that `setup` prints: what Patchstack found, the link, what is left to do and the next step, with a reminder to deploy when they are ready. See "The message you end on".
 
 **In a workspace repo** — a root `package.json` that declares `workspaces`, with the app in a package such as `apps/web` (Hostinger Horizons generates this shape) — run every command from the repo root. The site is recorded in the root's `.patchstackrc.json`, and `setup` wires the guard and the widget into the app package from there. Do not run `setup` inside the app package, and do not create a `.patchstackrc.json` there. When `setup`, `scan`, `widget` or `protect` is run inside a package of a repo whose root records the site, it runs at the root instead and prints `Running at the project root (…)`.
 
@@ -85,6 +86,7 @@ Every command at a glance — what it does, whether it reads your source, what i
 | `guide` | Print this project's setup status: what is left to do and the four steps, with tailored commands. `--full` adds this reference. | Reads local protection wiring for verification | Nothing | Nothing |
 | `status` | Re-print the site UUID + dashboard URL and check whether the site still exists (active / removed / could not verify) and whether it is connected to an account. | No | The connected note in `.patchstackrc.json`, when it changed | Site-existence and connection checks |
 | `next` | Say where the project stands and the one thing to do now: connect the account (with the link), or go live (with the same steps `go-live` prints, or asking where the app is hosted when the project does not say). Answers the "done" the summary ends on. | Reads the project files `guide` and `go-live` read | The connected note in `.patchstackrc.json`, when it changed | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is) |
+| `doctor [--url <live app>]` | Check that everything Patchstack needs works, and print each problem with its fix: the install, the site, the account, the guard's wiring, its rules file, the read-only rules credential, the map link, the build steps, and whether the published app fetches its rules. A problem only the app's owner can fix (connecting the account, publishing) is marked as theirs. Exits 1 when it finds a problem. | Reads the project files `guide` and `protect --check` read | Nothing | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is); the read-only rules credential from the guard's rules file, and the site key when this machine holds one, each once to `monitor/pulse/token`, to check Patchstack accepts them; one GET with that token to `monitor/pulse/sync-status/<your site uuid>`, which answers only when the published app (read-only credential) and a key-holding copy last fetched rules, and how many (doctor never fetches rules itself, which would be recorded as a fetch); with `--url`, two GET requests to that address: its page, and the same page with a test attack in a `file` parameter, which another firewall in front of the app may also flag |
 | `vulns` | Show what Patchstack found in this project's packages: vulnerabilities by severity and outdated packages, as counts, with the link that shows the details. Package names are shown in the dashboard once the site is connected. | No | Nothing | The site UUID, to the public claim page that returns the counts |
 | `go-live [--host <name>]` | Show how to add the project's API key to its host and deploy, in three steps. The host is read from project files (`vercel.json`, `netlify.toml`, `wrangler.toml`, `fly.toml`, `render.yaml`, `railway.json`, `amplify.yml`, `Procfile`, `.replit`, a Lovable project's packages) or named with `--host`. The commands it prints read the key from `.patchstackrc.local.json` as they run; it never prints the key. | Reads those project files only | Nothing | Nothing |
 | `widget [--remove]` | Add the Patchstack Connector widget tag to the root page (in a workspace repo, the app package's root page), or take the tag Connect added out with `--remove` (a tag added by hand is left alone). Saves the choice as `"widget"` in `.patchstackrc.json`, which `scan` and `mark-build` follow; `setup --widget` saves the same choice. | Reads the root page to find where the tag goes | `.patchstackrc.json`; the widget `<script>` tag in the root HTML shell or framework root | Nothing |
@@ -956,6 +958,7 @@ Three more endpoints the package can call, for completeness:
 ## Verifying the install
 
 - `npx @patchstack/connect status` re-prints the site UUID and dashboard URL, and checks whether the site still exists on Patchstack (`Site status: active / removed / could not be verified`).
+- `npx @patchstack/connect doctor` runs every check at once and prints each problem with its fix; `--url <live app>` adds the live app's widget and a test attack.
 - `npx @patchstack/connect protect --check` verifies from the source that the runtime guard is connected to the request path. It does not run the app. When the project records a site, it also fails if a guard Connect wrote does not carry it (`the guard carries this project's Patchstack site`): such a guard blocks with the rules it shipped with but fetches no rule updates and reports nothing. Run `npx @patchstack/connect protect` from the project root to fill the site in, then deploy.
 - `npx @patchstack/connect protect --check --runtime` additionally **starts the app** on a loopback port and sends it one request, to establish that a request reaches the guard seam. Opt-in, and the only command that runs the application; exit `0`/`1`/`2` as described in step 4.
 - Load the site in a browser — the widget should appear, as the "Connect this website" panel while the site is unclaimed. Refresh a page that was already open before the tag was added: the widget only loads with the page.
diff --git a/README.md b/README.md
index 5ef4579..8b0c402 100644
--- a/README.md
+++ b/README.md
@@ -189,6 +189,8 @@ patchstack-connect setup  [--widget] [options]     Run scan, add the widget with
 patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json with
                                                    an existing site UUID
 patchstack-connect status [options]                Show current configuration
+patchstack-connect doctor [--url <live app>]       Check that everything Patchstack needs works and
+                                                   say how to fix each problem
 patchstack-connect vulns                           Show vulnerabilities by severity and outdated
                                                    packages, with the link to the details
 patchstack-connect go-live [--host <name>]         Show how to add your API key to your host
diff --git a/src/cli.ts b/src/cli.ts
index b3aa51d..f16b507 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -114,6 +114,7 @@ import { formatRuntimeCheck, runRuntimeCheck, runtimeExitCode } from './protect/
 import { runMap } from './map-command.js';
 import { bundleRulesAllowed } from './bundled-rules.js';
 import { getStringFlag } from './flags.js';
+import { renderDoctor, runDoctorChecks } from './doctor.js';
 import { isCanonicalUuid } from './endpoint-policy.js';
 import { setupProtection, wireBuildScripts, wireDevelopmentScript } from './setup.js';
 import { runDevelopment } from './dev-command.js';
@@ -137,6 +138,7 @@ function startScreen(color: boolean): string[] {
     '',
     'Then:',
     command('next', 'what to do next'),
+    command('doctor', 'check that everything works'),
     command('vulns', 'see what was found'),
     command('widget', 'show Patchstack inside your app (optional)'),
     command('go-live', 'how to go live on your host'),
@@ -192,6 +194,17 @@ Usage:
   patchstack-connect summary                         Print the summary the last setup wrote, from
                                                      .patchstack/summary.md. Sends nothing; writes
                                                      nothing
+  patchstack-connect doctor [--url <live app>]       Check that everything Patchstack needs works in this
+                                                     project, and say how to fix each problem: install,
+                                                     site, account, protection wiring, the guard's rules
+                                                     file and its read-only credential, the map link and
+                                                     the build steps, and whether the published app
+                                                     fetches its rules. Sends the site UUID to the public
+                                                     claim page, asks Patchstack whether it accepts the
+                                                     credentials and when the app last fetched rules;
+                                                     with --url, also requests the live app's page and
+                                                     one test attack. Writes nothing.
+                                                     Exits 1 when it finds a problem
   patchstack-connect vulns                           Show what Patchstack found in this project's
                                                      packages: vulnerabilities by severity and
                                                      outdated packages, with the link to the
@@ -1693,6 +1706,18 @@ function runSummary(): number {
  * The one thing to do now, for the word the summary ends on. Connection lives on the server, so it is
  * looked up unless `.patchstackrc.json` already records it; everything else is read from the project.
  */
+/** Check everything Patchstack needs in this project and print each problem with its fix. */
+async function runDoctor(args: ParsedArgs): Promise<number> {
+  const cwd = process.cwd();
+  const config = await resolveCliConfig(args);
+  const state = await collectGuideState(cwd);
+  const url = getStringFlag(args.flags, 'url') ?? null;
+  const findings = await runDoctorChecks(cwd, state, config, { url, claimPreview: fetchClaimPreview });
+  for (const line of renderDoctor(findings, { url })) console.log(line);
+
+  return findings.some((finding) => finding.status === 'problem') ? 1 : 0;
+}
+
 async function runNext(args: ParsedArgs): Promise<number> {
   const config = await resolveCliConfig(args);
   if (config.siteUuid === null) {
@@ -2274,12 +2299,12 @@ async function main(): Promise<number> {
 
 /** Commands `runCommand` dispatches; anything else is an unknown command and sends no notice. */
 const KNOWN_COMMANDS = new Set([
-  'init', 'scan', 'vulns', 'next', 'summary', 'go-live', 'widget', 'status', 'uninstall', 'mark-build', 'protect',
+  'init', 'scan', 'vulns', 'next', 'doctor', 'summary', 'go-live', 'widget', 'status', 'uninstall', 'mark-build', 'protect',
   'demo', 'demo-guide', 'guide', 'setup', 'map', 'claim', 'login',
 ]);
 
 /** Commands that act on the whole project, so in a workspace package they run at the root that holds the site. */
-const ROOT_COMMANDS = new Set(['setup', 'scan', 'widget', 'protect']);
+const ROOT_COMMANDS = new Set(['setup', 'scan', 'widget', 'protect', 'doctor']);
 
 /**
  * A run that sent nothing the site's activity log records still tells Patchstack it ran, by the site's
@@ -2306,6 +2331,8 @@ async function runCommand(args: ParsedArgs): Promise<number> {
       return runSummary();
     case 'next':
       return runNext(args);
+    case 'doctor':
+      return runDoctor(args);
     case 'go-live':
       return runGoLive(args);
     case 'widget':
diff --git a/src/client.ts b/src/client.ts
index e215281..c5c6a2b 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -129,6 +129,13 @@ export function authFailureMessage(status: number, config: Config): string | nul
 }
 
 /** Build the live Patchstack for JavaScript rules URL corresponding to a manifest endpoint override. */
+/** Where a site's own credential reads when its app last fetched rules, beside the rules endpoint. */
+export function buildSyncStatusUrl(manifestEndpoint: string, siteUuid: string): string {
+  const url = new URL(buildRulesUrl(manifestEndpoint, siteUuid));
+  url.pathname = url.pathname.replace(/\/rules\/([^/]+)$/, '/sync-status/$1');
+  return url.toString();
+}
+
 export function buildRulesUrl(manifestEndpoint: string, siteUuid: string): string {
   const url = new URL(manifestEndpoint);
   const path = url.pathname.replace(/\/$/, '');
diff --git a/src/doctor.ts b/src/doctor.ts
new file mode 100644
index 0000000..4e09b29
--- /dev/null
+++ b/src/doctor.ts
@@ -0,0 +1,375 @@
+// `doctor`: one check of everything Patchstack needs to work in this project, each problem with its fix.
+//
+// It reads the project the way `guide` and `protect --check` do, and adds the checks behind the failures
+// that are otherwise silent: a guard rules file setup cannot find, a missing or retired read-only rules
+// credential, and a map that is not linked to the guard. With --url it also looks at the live app. It
+// writes nothing.
+
+import { readFileSync } from 'node:fs';
+
+import { readBuildStamp } from './build-id.js';
+import { findRulesFile, ruleBundleOf } from './build-stamp.js';
+import { buildClaimUrl, buildSyncStatusUrl, type ClaimPreview } from './client.js';
+import { assertConnectableEndpoint } from './endpoint-policy.js';
+import { DEV_ONLY_INSTALL, guideMissing, needsSourceProductionMarker, type GuideState } from './guide.js';
+import { buildTokenUrl, parsePulseAuth } from './pulse-token.js';
+import { connectHeaders } from './report-context.js';
+import type { Config } from './types.js';
+
+export type DoctorStatus = 'ok' | 'problem' | 'unknown';
+
+export interface DoctorFinding {
+  status: DoctorStatus;
+  /** What was found, in one short sentence. */
+  text: string;
+  /** What to do about it, one line each. */
+  fix?: string[];
+  /** A step only the app's owner can take (connecting their account, publishing), not a change to the project. */
+  owner?: boolean;
+}
+
+export interface DoctorOptions {
+  /** The live app's address, for the checks that need it. */
+  url?: string | null;
+  fetchImpl?: typeof fetch;
+  /** Whether the site has an owner, from the public claim page. */
+  claimPreview: (config: Config) => Promise<ClaimPreview>;
+  /** How long to give the live app to finish the rules check its visit started, before reading sync status. */
+  settleMs?: number;
+}
+
+const READER = /^rr_[0-9a-f]{48}-\d+$/;
+const PROBE = '../../../../etc/passwd';
+const LIVE_TIMEOUT_MS = 10_000;
+/** A published app re-checks its rules every few minutes while it has visitors; older than this is worth a look. */
+const SYNC_STALE_MS = 2 * 60 * 60 * 1000;
+
+type Exchange = { verdict: 'accepted' | 'refused' | 'unreachable'; token: string | null };
+
+/** Ask Patchstack whether it accepts a credential. The token is used only for the sync-status read below. */
+async function exchangeCredential(config: Config, credential: string, fetchImpl: typeof fetch): Promise<Exchange> {
+  const parsed = parsePulseAuth(credential);
+  if (parsed === null) return { verdict: 'refused', token: null };
+  try {
+    const url = buildTokenUrl(config.endpoint);
+    assertConnectableEndpoint(config, url);
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', ...connectHeaders() },
+      body: JSON.stringify({ grant_type: 'client_credentials', client_id: parsed.clientId, client_secret: parsed.clientSecret }),
+      signal: AbortSignal.timeout(config.timeoutMs),
+    });
+
+    if (!response.ok) return { verdict: response.status === 401 || response.status === 403 ? 'refused' : 'unreachable', token: null };
+    const token = ((await response.json().catch(() => null)) as { access_token?: unknown } | null)?.access_token;
+
+    return { verdict: 'accepted', token: typeof token === 'string' && token !== '' ? token : null };
+  } catch {
+    return { verdict: 'unreachable', token: null };
+  }
+}
+
+/** The guard's rules file: where it is, the read-only credential in it, and whether the map is linked. */
+async function rulesFileFindings(cwd: string, config: Config, fetchImpl: typeof fetch): Promise<{ findings: DoctorFinding[]; token: string | null }> {
+  const location = findRulesFile(cwd);
+  if (location.kind === 'none') {
+    return { token: null, findings: [{
+      status: 'problem',
+      text: "Patchstack cannot find the guard's rules file, so setup cannot keep its rules current",
+      fix: ['Run: npx @patchstack/connect protect', 'Then: npx @patchstack/connect setup'],
+    }] };
+  }
+  if (location.kind === 'unreadable') {
+    return { token: null, findings: [{
+      status: 'problem',
+      text: `The guard's rules file is not valid JSON (${location.paths.join(', ')})`,
+      fix: ['Restore it from version control, or delete it and run: npx @patchstack/connect protect', 'Then: npx @patchstack/connect setup'],
+    }] };
+  }
+  if (location.kind === 'ambiguous') {
+    return { token: null, findings: [{
+      status: 'problem',
+      text: `Two Patchstack guards are installed, each with its own rules file (${location.paths.join(', ')})`,
+      fix: [
+        'Keep the guard npx @patchstack/connect protect --check reports as wired.',
+        'Remove the other guard and its rules file, after checking nothing in the app imports that guard.',
+        'Then: npx @patchstack/connect setup',
+      ],
+    }] };
+  }
+
+  let bundle: Record<string, unknown> | null = null;
+  try {
+    bundle = ruleBundleOf(JSON.parse(readFileSync(location.path, 'utf8')));
+  } catch {
+    // Read as missing below.
+  }
+  const findings: DoctorFinding[] = [];
+  let token: string | null = null;
+  const reader = (bundle?._patchstack as { rules_reader?: unknown } | undefined)?.rules_reader;
+  if (typeof reader !== 'string' || !READER.test(reader)) {
+    findings.push({
+      status: 'problem',
+      text: "The guard's rules file has no read-only rules credential, so the published app cannot fetch rule updates or report attacks without the site key",
+      fix: ['Run: npx @patchstack/connect setup (it writes the credential; it needs the site key on this machine)', 'Then publish the app again.'],
+    });
+  } else {
+    const { verdict, token: readerToken } = await exchangeCredential(config, reader, fetchImpl);
+    token = readerToken;
+    findings.push(
+      verdict === 'accepted'
+        ? { status: 'ok', text: 'The read-only rules credential works: the published app can fetch rule updates and report attacks' }
+        : verdict === 'refused'
+          ? {
+              status: 'problem',
+              text: 'Patchstack refused the read-only rules credential (the site key was replaced, or the site was removed)',
+              fix: ['Run: npx @patchstack/connect setup (it writes a current one)', 'Then publish the app again.'],
+            }
+          : { status: 'unknown', text: 'Could not reach Patchstack to check the read-only rules credential' },
+    );
+  }
+  if (bundle === null || readBuildStamp(bundle) === null) {
+    findings.push({
+      status: 'problem',
+      text: "The app's map is not linked to the guard, so rules written for this app's own inputs can only report, not block",
+      fix: ['Run: npx @patchstack/connect setup --verbose and fix the reason on its "could not bind this map" line', 'Then run setup again.'],
+    });
+  } else {
+    findings.push({ status: 'ok', text: "The app's map is linked to the guard" });
+  }
+
+  return { findings, token };
+}
+
+/** "3 minutes ago", "5 hours ago", "2 days ago". */
+function ago(at: number, now: number): string {
+  const minutes = Math.max(0, Math.round((now - at) / 60_000));
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+  const days = Math.round(hours / 24);
+  return `${days} day${days === 1 ? '' : 's'} ago`;
+}
+
+type Fetch = { at: string; rule_count: number | null } | null;
+
+/**
+ * Whether the published app fetches its rules, from Patchstack's own record of rules fetches.
+ *
+ * The published app fetches on the read-only credential; a copy holding the site key (the workspace, or a
+ * deployment that sets PATCHSTACK_API_KEY) on the key. doctor reads the record and never fetches rules
+ * itself, which would be recorded as a fetch. An app with no visitors does not fetch, so an old fetch is
+ * only a problem once `visited` says doctor has just sent the live app a request.
+ */
+async function syncFindings(config: Config, token: string, visited: boolean, fetchImpl: typeof fetch): Promise<DoctorFinding[]> {
+  let body: { rules_fetches?: { reader?: Fetch; site_key?: Fetch } };
+  try {
+    const url = buildSyncStatusUrl(config.endpoint, config.siteUuid as string);
+    assertConnectableEndpoint(config, url);
+    const response = await fetchImpl(url, {
+      headers: { Accept: 'application/json', Authorization: `Bearer ${token}`, ...connectHeaders() },
+      signal: AbortSignal.timeout(config.timeoutMs),
+    });
+    if (response.status === 404) return [{ status: 'unknown', text: 'Patchstack does not report rules syncing for this site yet' }];
+    if (!response.ok) return [{ status: 'unknown', text: 'Could not get the rules sync status from Patchstack' }];
+    body = (await response.json()) as typeof body;
+  } catch {
+    return [{ status: 'unknown', text: 'Could not reach Patchstack to check whether the published app fetches its rules' }];
+  }
+
+  const now = Date.now();
+  const reader = body.rules_fetches?.reader ?? null;
+  const key = body.rules_fetches?.site_key ?? null;
+  const at = (fetch: Fetch) => (fetch === null ? NaN : Date.parse(fetch.at));
+  const count = (fetch: Fetch) => (fetch?.rule_count == null ? '' : ` (${fetch.rule_count} rule${fetch.rule_count === 1 ? '' : 's'})`);
+  const visit = 'Run: npx @patchstack/connect doctor --url <your live app> (it visits the app, which makes it check its rules), then look again.';
+
+  if (reader !== null && now - at(reader) <= SYNC_STALE_MS) {
+    return [{ status: 'ok', text: `The published app fetched its rules from Patchstack ${ago(at(reader), now)}${count(reader)}` }];
+  }
+  const notSyncing = [
+    'Publish the app again on the latest @patchstack/connect.',
+    'Check the guard is wired: npx @patchstack/connect protect --check',
+    'Then: npx @patchstack/connect doctor --url <your live app>',
+  ];
+  if (reader !== null) {
+    const text = `The published app last fetched its rules from Patchstack ${ago(at(reader), now)}${count(reader)}`;
+    return [visited
+      ? { status: 'problem', text: `${text}, and did not fetch them when doctor just visited it`, fix: notSyncing }
+      : { status: 'unknown', text: `${text}. An app with no visitors does not fetch`, fix: [visit] }];
+  }
+  if (key !== null) {
+    return [{
+      status: 'unknown',
+      text: `Only a copy holding the site key has fetched rules (${ago(at(key), now)}): a published app that sets PATCHSTACK_API_KEY fetches that way; otherwise the published app has never fetched them`,
+      fix: visited ? notSyncing : [visit],
+    }];
+  }
+
+  return [visited
+    ? { status: 'problem', text: 'The published app has never fetched its rules from Patchstack, even when doctor just visited it', fix: notSyncing }
+    : { status: 'unknown', text: 'The published app has never fetched its rules from Patchstack', fix: ['If the app is published, ' + visit.charAt(0).toLowerCase() + visit.slice(1), 'If it is not published yet, publish it.'] }];
+}
+
+/** The live app: whether it carries the widget and whether its guard stops a test attack. */
+async function liveFindings(url: string, state: GuideState, fetchImpl: typeof fetch): Promise<{ findings: DoctorFinding[]; reached: boolean }> {
+  let page: URL;
+  try {
+    page = new URL(url);
+    if (page.protocol !== 'https:' && page.protocol !== 'http:') throw new Error('not http');
+  } catch {
+    return { reached: false, findings: [{ status: 'unknown', text: `${url} is not a web address; pass the live app's address, e.g. --url https://your-app.example` }] };
+  }
+
+  const findings: DoctorFinding[] = [];
+  try {
+    const response = await fetchImpl(page, { signal: AbortSignal.timeout(LIVE_TIMEOUT_MS) });
+    const html = await response.text();
+    // A page that does not load says nothing about the guard either, so the test attack is not sent.
+    if (!response.ok) {
+      return { reached: false, findings: [{ status: 'unknown', text: `The live app answered ${response.status}, so it could not be checked (is it published? a private publish shows a sign-in page)` }] };
+    }
+    if (!state.widgetOptOut && state.siteUuid !== null) {
+      findings.push(
+        html.includes('patchstack-widget.js') && html.includes(state.siteUuid)
+          ? { status: 'ok', text: 'The live app carries the Patchstack widget for this site' }
+          : { status: 'problem', text: 'The live app does not carry the Patchstack widget for this site yet', fix: ['Publish the app again: the live app still runs a build from before setup.'], owner: true },
+      );
+    }
+  } catch {
+    return { reached: false, findings: [{ status: 'unknown', text: `Could not reach ${page.origin}` }] };
+  }
+
+  const probe = new URL(page);
+  probe.searchParams.set('file', PROBE);
+  try {
+    const response = await fetchImpl(probe, { signal: AbortSignal.timeout(LIVE_TIMEOUT_MS) });
+    const body = await response.text();
+    findings.push(
+      response.status === 403 && /blocked by Patchstack/i.test(body)
+        ? { status: 'ok', text: "The live app's guard blocked a test attack" }
+        : {
+            status: 'problem',
+            text: `The live app let a test attack through (it answered ${response.status} to ?file=${PROBE})`,
+            fix: [
+              'If the app has not been published since setup, publish it again.',
+              'If the site is not connected to a Patchstack account that includes protection, Patchstack only reports attacks: connect it.',
+            ],
+            owner: true,
+          },
+    );
+  } catch {
+    findings.push({ status: 'unknown', text: `Could not reach ${page.origin} for the test attack` });
+  }
+
+  return { findings, reached: true };
+}
+
+/**
+ * Every check, in the order a fix is worth making. `state` is `collectGuideState` for the project.
+ */
+export async function runDoctorChecks(cwd: string, state: GuideState, config: Config, options: DoctorOptions): Promise<DoctorFinding[]> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const findings: DoctorFinding[] = [];
+
+  if (state.installed === null) {
+    return [{ status: 'problem', text: 'Patchstack is not installed in this project', fix: ['Run: npx @patchstack/connect setup'] }];
+  }
+  if (state.siteUuid === null) {
+    return [{ status: 'problem', text: 'This project is not on Patchstack yet', fix: ['Run: npx @patchstack/connect setup'] }];
+  }
+
+  // Whether the site has an owner. The note in .patchstackrc.json answers it once it is recorded.
+  let connected: boolean | null = state.claimed ? true : null;
+  if (connected === null) {
+    const preview = await options.claimPreview(config);
+    connected = preview.state === 'claimed' ? true : preview.state === 'unclaimed' ? false : null;
+  }
+  if (connected === null) findings.push({ status: 'unknown', text: 'Could not reach Patchstack to check whether this site is connected to an account' });
+
+  // Each thing setup leaves to do, as setup and guide word it. The connection is reported above, with its link.
+  const missing = guideMissing(state, { connected: true });
+  if (connected === false) {
+    const link = config.endpointTrusted !== false ? buildClaimUrl(config.endpoint, state.siteUuid) : null;
+    findings.push({
+      status: 'problem',
+      text: 'Not connected to a Patchstack account, so Patchstack only reports attacks and does not block them',
+      fix: [link ? `Open ${link} and sign in.` : 'Run: npx @patchstack/connect claim'],
+      owner: true,
+    });
+  } else if (connected) {
+    findings.push({ status: 'ok', text: 'Connected to a Patchstack account' });
+  }
+  for (const item of missing) {
+    findings.push({ status: 'problem', text: item.plain?.text ?? item.text, fix: [...(item.hint ?? []), ...(item.detail ?? [])] });
+  }
+  const keys = new Set(missing.map((item) => item.key));
+
+  if (!keys.has(DEV_ONLY_INSTALL)) findings.push({ status: 'ok', text: `Patchstack ${state.installed.version} is installed` });
+  if (!state.protectionApplicable) {
+    findings.push({ status: 'ok', text: 'This app has no server to protect, so runtime protection does not apply' });
+  } else if (state.protectionWired) {
+    findings.push({ status: 'ok', text: `Protection is wired into your server (${state.protectionStack})` });
+  }
+  if (state.installScanWired && (!state.hasBuildScript || (state.prebuildWired && state.postbuildWired))) {
+    findings.push({ status: 'ok', text: 'Your installs and builds run the Patchstack check' });
+  }
+  if (needsSourceProductionMarker(state) && state.productionMarkerWired) {
+    findings.push({ status: 'ok', text: 'Your pages carry the marker that tells Patchstack when the app is live' });
+  }
+
+  let readerToken: string | null = null;
+  if (state.protectionApplicable && state.protectionWired) {
+    const rules = await rulesFileFindings(cwd, config, fetchImpl);
+    findings.push(...rules.findings);
+    readerToken = rules.token;
+  }
+  let visited = false;
+  if (options.url) {
+    const live = await liveFindings(options.url, state, fetchImpl);
+    findings.push(...live.findings);
+    visited = live.reached;
+  }
+  if (state.protectionApplicable && state.protectionWired) {
+    // The site key on this machine when there is one, otherwise the read-only credential checked above.
+    const key = config.pulseAuth ?? config.apiKey;
+    const token = typeof key === 'string' && key !== '' ? (await exchangeCredential(config, key, fetchImpl)).token ?? readerToken : readerToken;
+    if (token !== null) {
+      // A visit can start the app's rules check in the background; give it a moment to be recorded.
+      if (visited) await new Promise((resolve) => setTimeout(resolve, options.settleMs ?? 3_000));
+      findings.push(...await syncFindings(config, token, visited, fetchImpl));
+    }
+  }
+
+  // Problems first, in the order found, then what could not be checked, then what passed.
+  const rank: Record<DoctorStatus, number> = { problem: 0, unknown: 1, ok: 2 };
+
+  return findings.map((finding, index) => ({ finding, index }))
+    .sort((a, b) => rank[a.finding.status] - rank[b.finding.status] || a.index - b.index)
+    .map(({ finding }) => finding);
+}
+
+/** The report, ending with what to do next for whoever runs it, person or assistant. */
+export function renderDoctor(findings: DoctorFinding[], { url }: { url?: string | null } = {}): string[] {
+  const mark: Record<DoctorStatus, string> = { ok: '✓', problem: '✗', unknown: '?' };
+  const lines = ['Patchstack doctor: is Patchstack set up and working in this project?', ''];
+  for (const finding of findings) {
+    lines.push(`  ${mark[finding.status]} ${finding.text}${finding.owner ? ' (for the app owner)' : ''}`);
+    for (const [index, fix] of (finding.fix ?? []).entries()) lines.push(`      ${index === 0 ? 'Fix: ' : '     '}${fix}`);
+  }
+  lines.push('');
+  const problems = findings.filter((finding) => finding.status === 'problem');
+  const toFix = problems.filter((finding) => !finding.owner).length;
+  const forOwner = problems.length - toFix;
+  if (problems.length === 0) lines.push('No problems found.');
+  if (toFix > 0) {
+    lines.push(`${toFix} problem${toFix === 1 ? '' : 's'} to fix in the project. Fix each ✗ above as its Fix line says, then run npx @patchstack/connect doctor again until none is left.`);
+  }
+  if (forOwner > 0) {
+    lines.push(`${forOwner} step${forOwner === 1 ? '' : 's'} for the app owner (marked "for the app owner"): connecting their Patchstack account or publishing the app. Pass ${forOwner === 1 ? 'it' : 'them'} on; nothing in the project fixes ${forOwner === 1 ? 'it' : 'them'}.`);
+  }
+  if (findings.some((finding) => finding.status === 'unknown')) lines.push('A ? could not be checked from here; it is not a problem on its own.');
+  if (!url) lines.push("To also check the live app, run: npx @patchstack/connect doctor --url <your live app's address>");
+
+  return lines;
+}
diff --git a/tests/doctor.test.ts b/tests/doctor.test.ts
new file mode 100644
index 0000000..dfb972b
--- /dev/null
+++ b/tests/doctor.test.ts
@@ -0,0 +1,205 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { renderDoctor, runDoctorChecks, type DoctorFinding } from '../src/doctor.js';
+import { collectGuideState } from '../src/guide.js';
+import { runProtect } from '../src/protect/install/index.js';
+import type { ClaimPreview } from '../src/client.js';
+import type { Config } from '../src/types.js';
+
+const UUID = '556d8930-ae4d-4bf2-bee8-3bc53c096876';
+const READER = `rr_${'a'.repeat(48)}-4242`;
+const dirs: string[] = [];
+afterEach(() => {
+  dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true }));
+  vi.restoreAllMocks();
+});
+
+function config(overrides: Partial<Config> = {}): Config {
+  return {
+    siteUuid: UUID,
+    apiKey: null,
+    pulseAuth: null,
+    endpoint: 'https://api.patchstack.com/monitor/pulse/manifest',
+    timeoutMs: 5_000,
+    environment: 'production',
+    widget: false,
+    ...overrides,
+  } as Config;
+}
+
+/** A plain Node server with the generic guard wired the way the guide says, rules file stamped as setup leaves it. */
+function project(patchstack: Record<string, unknown> | null = { rules_reader: READER, build_id: 'b'.repeat(64) }): string {
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+  const cwd = mkdtempSync(join(tmpdir(), 'ps-doctor-'));
+  dirs.push(cwd);
+  writeFileSync(join(cwd, 'package.json'), JSON.stringify({
+    name: 'doctor-fixture', type: 'module',
+    scripts: { start: 'node server.js', postinstall: 'patchstack-connect scan' },
+    dependencies: { '@patchstack/connect': '^0.5.68' },
+  }));
+  writeFileSync(join(cwd, '.patchstackrc.json'), JSON.stringify({ siteUuid: UUID, widget: false, claimed: true }));
+  writeFileSync(join(cwd, 'server.js'), "import http from 'node:http';\nimport { patchstackMiddleware } from './patchstack/guard.js';\nconst handler = (req, res) => res.end('ok');\nhttp.createServer((req, res) => patchstackMiddleware(req, res, () => handler(req, res))).listen(3000);\n");
+  runProtect(cwd);
+  if (patchstack !== null) {
+    const rules = JSON.parse(readFileSync(join(cwd, 'patchstack/rules.json'), 'utf8'));
+    writeFileSync(join(cwd, 'patchstack/rules.json'), JSON.stringify({ ...rules, _patchstack: patchstack }));
+  }
+  return cwd;
+}
+
+const minutesAgo = (minutes: number) => new Date(Date.now() - minutes * 60_000).toISOString();
+type SyncAnswer = { reader?: { at: string; rule_count: number } | null; site_key?: { at: string; rule_count: number } | null } | number;
+
+/** Patchstack's token and sync-status endpoints, and a live app answering the page and the test attack. */
+function network({ token = 200, page = 200, attack = 403, sync = { reader: { at: minutesAgo(3), rule_count: 17 }, site_key: null } }: { token?: number | 'down'; page?: number; attack?: number; sync?: SyncAnswer } = {}) {
+  const calls: string[] = [];
+  const auth: string[] = [];
+  const fetchImpl = vi.fn(async (input: string | URL, init: RequestInit = {}) => {
+    const url = String(input);
+    calls.push(url);
+    if (url.endsWith('/token')) {
+      if (token === 'down') throw new Error('offline');
+      return new Response(token === 200 ? '{"access_token":"reader-token","expires_in":3600}' : '{}', { status: token });
+    }
+    if (url.includes('/sync-status/')) {
+      auth.push(String((init.headers as Record<string, string>)?.Authorization));
+      return typeof sync === 'number' ? new Response('{}', { status: sync }) : Response.json({ site_uuid: UUID, rules_fetches: { reader: null, site_key: null, ...sync } });
+    }
+    if (url.includes('file=')) return new Response(attack === 403 ? '{"error":"This request has been blocked by Patchstack."}' : '<html></html>', { status: attack });
+    return new Response(`<html><script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="${UUID}"></script></html>`, { status: page });
+  }) as unknown as typeof fetch;
+  return { fetchImpl, calls, auth };
+}
+
+const claimed = async (): Promise<ClaimPreview> => ({ state: 'claimed', summary: null });
+async function doctor(cwd: string, options: { url?: string; claimPreview?: () => Promise<ClaimPreview>; net?: ReturnType<typeof network>; config?: Partial<Config> } = {}) {
+  const net = options.net ?? network();
+  const state = await collectGuideState(cwd);
+  return runDoctorChecks(cwd, state, config(options.config), { url: options.url ?? null, fetchImpl: net.fetchImpl, claimPreview: options.claimPreview ?? claimed, settleMs: 0 });
+}
+const problems = (findings: DoctorFinding[]) => findings.filter((f) => f.status === 'problem').map((f) => f.text);
+
+describe('doctor', () => {
+  it('finds no problem in a project set up the way setup leaves it', async () => {
+    const findings = await doctor(project());
+    expect(problems(findings)).toEqual([]);
+    expect(findings.map((f) => f.text)).toContain('The read-only rules credential works: the published app can fetch rule updates and report attacks');
+    expect(renderDoctor(findings).join('\n')).toContain('No problems found.');
+  });
+
+  it('says what to run when the project is not on Patchstack', async () => {
+    const cwd = project();
+    rmSync(join(cwd, '.patchstackrc.json'));
+    expect(await doctor(cwd, { config: { siteUuid: null } as never })).toEqual([
+      { status: 'problem', text: 'This project is not on Patchstack yet', fix: ['Run: npx @patchstack/connect setup'] },
+    ]);
+  });
+
+  it('flags a site with no owner as report-only, with the link to connect it', async () => {
+    const cwd = project();
+    writeFileSync(join(cwd, '.patchstackrc.json'), JSON.stringify({ siteUuid: UUID, widget: false }));
+    const findings = await doctor(cwd, { claimPreview: async () => ({ state: 'unclaimed', summary: null }) });
+    const finding = findings.find((f) => f.text.startsWith('Not connected'));
+    expect(finding?.status).toBe('problem');
+    expect(finding?.fix?.[0]).toContain(`claim?site=${UUID}`);
+    expect(findings.filter((f) => /connected/i.test(f.text))).toHaveLength(1);
+  });
+
+  it('flags a rules file without the read-only credential, and one Patchstack refuses', async () => {
+    expect(problems(await doctor(project({ build_id: 'b'.repeat(64) })))).toEqual([
+      "The guard's rules file has no read-only rules credential, so the published app cannot fetch rule updates or report attacks without the site key",
+    ]);
+    expect(problems(await doctor(project(), { net: network({ token: 401 }) }))).toEqual([
+      'Patchstack refused the read-only rules credential (the site key was replaced, or the site was removed)',
+    ]);
+    const offline = await doctor(project(), { net: network({ token: 'down' }) });
+    expect(problems(offline)).toEqual([]);
+    expect(offline.find((f) => f.status === 'unknown')?.text).toBe('Could not reach Patchstack to check the read-only rules credential');
+  });
+
+  it('flags a map that is not linked to the guard', async () => {
+    expect(problems(await doctor(project({ rules_reader: READER })))).toEqual([
+      "The app's map is not linked to the guard, so rules written for this app's own inputs can only report, not block",
+    ]);
+  });
+
+  it('flags a guard that is not wired', async () => {
+    const cwd = project();
+    writeFileSync(join(cwd, 'server.js'), "import http from 'node:http';\nhttp.createServer((req, res) => res.end('ok')).listen(3000);\n");
+    expect(problems(await doctor(cwd))).toEqual(['Blocking attacks needs a server']);
+  });
+
+  describe('with --url', () => {
+    it('passes a live app that carries the widget and blocks the test attack', async () => {
+      const cwd = project();
+      writeFileSync(join(cwd, '.patchstackrc.json'), JSON.stringify({ siteUuid: UUID, widget: true, claimed: true }));
+      const findings = await doctor(cwd, { url: 'https://app.example' });
+      expect(findings.filter((f) => f.text.startsWith('The live app')).map((f) => [f.status, f.text])).toEqual([
+        ['ok', 'The live app carries the Patchstack widget for this site'],
+        ['ok', "The live app's guard blocked a test attack"],
+      ]);
+    });
+
+    it('flags a live app that lets the test attack through', async () => {
+      const findings = await doctor(project(), { url: 'https://app.example', net: network({ attack: 200 }) });
+      expect(problems(findings)).toEqual(['The live app let a test attack through (it answered 200 to ?file=../../../../etc/passwd)']);
+    });
+
+    it('sends no test attack to a page that does not load', async () => {
+      const net = network({ page: 404 });
+      const findings = await doctor(project(), { url: 'https://app.example', net });
+      expect(findings.find((f) => f.text.startsWith('The live app'))?.status).toBe('unknown');
+      expect(net.calls.some((url) => url.includes('file='))).toBe(false);
+    });
+  });
+
+  describe('whether the published app fetches its rules', () => {
+    const syncText = (findings: DoctorFinding[]) => findings.find((f) => /fetched|never fetched|rules syncing/.test(f.text));
+
+    it('passes an app that fetched them recently, reading the record with the token and never fetching rules itself', async () => {
+      const net = network();
+      const finding = syncText(await doctor(project(), { net }));
+      expect(finding).toMatchObject({ status: 'ok', text: 'The published app fetched its rules from Patchstack 3 minutes ago (17 rules)' });
+      expect(net.auth).toEqual(['Bearer reader-token']);
+      expect(net.calls.some((url) => url.includes('/rules/'))).toBe(false);
+    });
+
+    it('treats an old fetch as a question until doctor has visited the app, then as a problem', async () => {
+      const stale = { reader: { at: minutesAgo(300), rule_count: 17 } };
+      expect(syncText(await doctor(project(), { net: network({ sync: stale }) }))?.status).toBe('unknown');
+      const visited = syncText(await doctor(project(), { url: 'https://app.example', net: network({ sync: stale }) }));
+      expect(visited).toMatchObject({ status: 'problem', text: 'The published app last fetched its rules from Patchstack 5 hours ago (17 rules), and did not fetch them when doctor just visited it' });
+    });
+
+    it('flags an app that has never fetched them once doctor has visited it', async () => {
+      const finding = syncText(await doctor(project(), { url: 'https://app.example', net: network({ sync: { reader: null } }) }));
+      expect(finding).toMatchObject({ status: 'problem', text: 'The published app has never fetched its rules from Patchstack, even when doctor just visited it' });
+    });
+
+    it('does not call a key-holding copy the published app', async () => {
+      const finding = syncText(await doctor(project(), { net: network({ sync: { reader: null, site_key: { at: minutesAgo(10), rule_count: 17 } } }) }));
+      expect(finding?.status).toBe('unknown');
+      expect(finding?.text).toContain('Only a copy holding the site key has fetched rules (10 minutes ago)');
+    });
+
+    it('says so when Patchstack does not report syncing yet', async () => {
+      expect(syncText(await doctor(project(), { net: network({ sync: 404 }) }))).toMatchObject({ status: 'unknown', text: 'Patchstack does not report rules syncing for this site yet' });
+    });
+  });
+
+  it('ends by telling whoever runs it to fix each problem and run it again', () => {
+    const lines = renderDoctor([{ status: 'problem', text: 'x', fix: ['Run: a', 'Then: b'] }], { url: 'https://app.example' }).join('\n');
+    expect(lines).toContain('  ✗ x\n      Fix: Run: a\n           Then: b');
+    expect(lines).toContain('1 problem to fix in the project. Fix each ✗ above as its Fix line says, then run npx @patchstack/connect doctor again until none is left.');
+  });
+
+  it('keeps the owner\'s steps apart from what the project needs, so an assistant does not wait on them', () => {
+    const lines = renderDoctor([{ status: 'problem', text: 'Not connected', fix: ['Open the link'], owner: true }]).join('\n');
+    expect(lines).toContain('✗ Not connected (for the app owner)');
+    expect(lines).not.toContain('to fix in the project');
+    expect(lines).toContain('1 step for the app owner');
+  });
+});