diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b80622..19ae6b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,70 @@
 All notable changes to JayShield are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 1.3.0 - 2026-09-14
+
+A release about being usable on a real site, and honest about what a scan
+means.
+
+### Added
+
+- WordPress awareness. A scan recognises a WordPress install and prints its
+  version, and every flagged file that belongs to WordPress itself is tagged
+  `config`, `core`, `theme`, or `plugin` in the report and in `--json`. Those
+  files carry different advice: replace them with a clean copy of the same
+  version rather than only removing them, because quarantining one takes the
+  site or the theme offline. Scanning only `wp-content` still knows its site.
+- `--include <dir,...>` scans folders that are skipped by name, and
+  `--include all` scans everything. The report now says how many folders were
+  skipped and which names, so a clean result is never quieter than it should
+  be. Skipped names are also listed in `--help`.
+- A clear answer when given a website address. `jayshield https://example.com`
+  used to fail with "no such file or folder"; it now explains that JayShield
+  reads files on disk and shows the two ways to scan that site, over SSH or on
+  a downloaded copy.
+- README: a Requirements section, a step-by-step guide to scanning a WordPress
+  site on any hosting, an after-the-scan checklist for the things a file
+  scanner cannot do, and a plain list of what JayShield can and cannot promise.
+- `scan()` accepts `includeDirs` and returns `sites`, `skippedDirNames`, and
+  `stats.skippedDirs`; each infected record may carry `site`. The site helpers
+  and the walker are exported from the package.
+
+### Changed
+
+- Folders named `cache` are now scanned. On WordPress, `wp-content/cache` is
+  web-served, writable, and a common place to plant a shell, and the upload
+  heuristic already treated it as one, so skipping it left a blind spot.
+- The upload heuristic no longer flags a cached page whose only PHP is the
+  `<?php die(); ?>` guard that WP Super Cache writes. A payload after the
+  guard is still caught.
+- The clean-scan line now reads "Nothing in the files scanned matched a known
+  technique, heuristic, or bad hash", which is what a clean result means.
+
+### Fixed
+
+- A pristine WordPress 7.1 download was reported as 26 infected files, five
+  of them critical. Every one was a false positive, and every one is fixed:
+  - The WSO webshell rule matched the letters w-s-o inside any word, so
+    "Dawson", "WSODs", `useNewSodiumAPI`, and a certificate bundle were all
+    called a webshell. It now matches WSO's own function and constant names.
+  - The hex-escape rule flagged every long binary constant, in sodium_compat,
+    getID3, and SimplePie. It now flags a dangerous function name or request
+    variable spelled in hex, or a hex string literal called as a function,
+    and is high severity because that is never innocent.
+  - The hidden iframe rule matched `marginwidth="0"`, a hidden scratch frame
+    with a `javascript:` source, and the Google Tag Manager noscript snippet
+    that sits in most theme headers. It now requires a hidden frame with a
+    real destination, and a page full of unterminated tags can no longer
+    stall a scan.
+  - The long-line, high-entropy, and base64-blob heuristics fired on SVG
+    icons, entity tables, arrays of class names, and an embedded WebAssembly
+    module. Each now also requires a decoder, an execution call, or request
+    input on the same file or line, which a packed payload cannot do without.
+- Verified clean with the new rules against WordPress 7.1 with and without
+  `--include vendor`, WooCommerce 11.1.0, the Astra theme 4.13.11, jQuery
+  3.7.1, and Laravel 12.x, while every planted threat in the test fixtures is
+  still found.
+
 ## 1.2.1 - 2026-07-13
 
 ### Changed
diff --git a/README.md b/README.md
index 4024458..d56102d 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,18 @@ site stops serving them right away.
 It is one small tool with no dependencies, so you can trust it, read it, and run
 it anywhere Node is installed.
 
+## Requirements
+
+- **Node.js 18 or newer** on the machine that runs the scan. Check with
+  `node -v`. If that prints nothing or an older version, install Node from
+  [nodejs.org](https://nodejs.org/) (macOS, Windows, and Linux installers).
+- **The site's files on that machine.** JayShield reads files on disk. It does
+  not connect to a website address, so `jayshield https://example.com` is
+  refused with an explanation. See [Scan a WordPress site](#scan-a-wordpress-site)
+  for the two ways to get the files in front of it.
+
+Nothing else: no account, no PHP, no database access, no background service.
+
 ## Quick start
 
 No install required, run it straight from npm:
@@ -57,6 +69,81 @@ jayshield ./public_html
 
 The examples below write `jayshield` for short, meaning however you choose to run it.
 
+## Scan a WordPress site
+
+JayShield finds the files an attacker planted or changed. To do that it needs
+the site's files, so pick whichever of these fits your hosting.
+
+**Path A: run it on the server.** If your host gives you SSH (most VPS plans,
+managed WordPress hosts, and many shared hosts), log in and check for Node:
+
+```bash
+ssh you@your-server
+node -v
+```
+
+If Node is there, scan the site root, which is usually `public_html`, `htdocs`,
+`www`, or `/var/www/<your-site>`:
+
+```bash
+npx @jayhackpro/jayshield ~/public_html
+```
+
+If Node is missing and you cannot install it, use Path B. On many shared hosts
+you can install Node without root through cPanel's "Setup Node.js App" or with
+[nvm](https://github.com/nvm-sh/nvm).
+
+**Path B: scan a downloaded copy.** This works on any hosting, including
+hosting with no SSH at all. Download the whole site folder with an SFTP client
+(FileZilla, Cyberduck, WinSCP), with the "compress and download" button in your
+host's file manager, or from a full backup made by your backup plugin. Unzip it
+on your own computer and scan the folder:
+
+```bash
+npx @jayhackpro/jayshield ~/Downloads/example.com
+```
+
+The report is about the copy. Nothing on the live site changes, so clean the
+live site by hand using the paths in the report: delete planted files over SFTP
+and replace infected WordPress files with clean copies (see below).
+
+**Scan the whole site root, not just `wp-content`.** Attackers also edit
+`wp-config.php`, `.htaccess`, and the root `index.php`, and JayShield can only
+report on what it is pointed at. For a deeper scan add `--include vendor` so
+plugin dependency folders are read too.
+
+**Reading the results on a WordPress site.** JayShield recognises a WordPress
+install, prints its version, and tags each flagged file that belongs to
+WordPress itself:
+
+- **No tag** (`wp-content/uploads`, `wp-content/cache`, a stray file in the
+  root): almost always planted. Quarantine it.
+- **`[wordpress config]`**, **`[wordpress core]`**, **`[wordpress theme]`**,
+  **`[wordpress plugin]`**: a real file with injected code. The whole file is
+  untrusted, so replace it with a clean copy of the same version (core and
+  plugins from wordpress.org, the theme from where you got it) rather than only
+  removing it. Quarantining one of these takes the site or the theme offline
+  until you do; `--restore` puts it back if that happens.
+
+**After the scan.** Removing the files is the start, not the end. Do these too,
+because JayShield cannot:
+
+1. Update WordPress, every plugin, and every theme, and delete the ones you do
+   not use. The way in was almost always an outdated or nulled one.
+2. Change every password: WordPress admins, hosting panel, SFTP, and the
+   database user in `wp-config.php`. Rotate the salts in `wp-config.php` with
+   [new values](https://api.wordpress.org/secret-key/1.1/salt/).
+3. Look for admin users you did not create, in Users, and remove them.
+4. Check the database, which JayShield never reads: `siteurl` and `home` in
+   `wp_options`, unknown entries in `wp_options`, and `<script>` or `<iframe>`
+   tags inside `wp_posts` content.
+5. Verify core against the official checksums with
+   [WP-CLI](https://wp-cli.org/): `wp core verify-checksums`. This catches
+   changed core files that match no signature.
+6. Read `.htaccess` for redirects you did not write.
+7. If Google flagged the site, request a review in Search Console once it is
+   clean.
+
 ## What a scan looks like
 
 A report ranked by severity, with the exact line and a plain-language reason for every finding:
@@ -92,6 +179,12 @@ JayShield never deletes your files. When you are ready to clean up, quarantine
 moves each flagged file into a local vault and records where it came from, so
 your live site stops serving it at once while every byte is kept.
 
+On a WordPress site, check the tags in the report first. Files tagged
+`[wordpress core]`, `[wordpress config]`, `[wordpress theme]`, or
+`[wordpress plugin]` are the site's own code with something injected;
+quarantining them takes the site or the theme offline until you replace them
+with clean copies. Run `--dry-run` first so you know what will move.
+
 ```bash
 # preview what would move, changing nothing
 jayshield ./public_html --quarantine --dry-run
@@ -130,6 +223,7 @@ jayshield [paths...] [options]
 | `--purge --yes` | Permanently delete the vault (last resort) |
 | `--min-severity <level>` | `critical`, `high`, `medium`, or `low` |
 | `--ignore-rule <id,...>` | Silence one or more rules by id |
+| `--include <dir,...>` | Scan folders that are skipped by name, or `all` |
 | `--hashes <file>` | Add known bad sha256 hashes, one per line |
 | `--max-size <MB>` | Skip files larger than this (default 5) |
 | `--vault <dir>` | Quarantine folder (default `.jayshield-quarantine`) |
@@ -147,6 +241,15 @@ jayshield [paths...] [options]
 Exit codes: `0` clean, `1` threats found, `2` error. That makes JayShield easy
 to drop into a CI pipeline or a cron job.
 
+**What is skipped, and how to see it.** Folders named `.git`, `.svn`, `.hg`,
+`node_modules`, `vendor`, `.cache`, and the quarantine vault are skipped by
+default so a project scan stays fast, and files over 5 MB are skipped for size.
+The report says how many folders were skipped and which names, so a clean
+result is never quieter than it should be. `--include vendor` scans one of
+them, `--include all` scans everything, `--max-size` raises the size cap.
+A folder named plainly `cache` is scanned: on WordPress, `wp-content/cache` is
+a favourite place to plant a shell.
+
 ## Use it in a pipeline
 
 ```bash
@@ -168,11 +271,14 @@ npm install @jayhackpro/jayshield
 ```js
 import { scan, quarantineFiles } from "@jayhackpro/jayshield";
 
-const result = await scan(["./public_html"]);
+const result = await scan(["./public_html"], { includeDirs: ["vendor"] });
 console.log(`${result.infected.length} infected of ${result.stats.scanned} scanned`);
+for (const site of result.sites) console.log(`WordPress ${site.version} at ${site.root}`);
 
-if (result.infected.length) {
-  await quarantineFiles(result.infected, { vaultDir: ".vault" });
+// Quarantine planted files. Files tagged as the site's own code need a clean copy instead.
+const planted = result.infected.filter((r) => !r.site);
+if (planted.length) {
+  await quarantineFiles(planted, { vaultDir: ".vault" });
 }
 ```
 
@@ -197,17 +303,48 @@ readable objects. Each one has an id, a severity, the file kinds it applies to,
 and a pattern. Add one, add a test in [`test/rules.test.mjs`](test/rules.test.mjs),
 and send a pull request.
 
-## What it is, and what it is not
-
-JayShield is a fast first responder for web malware. It is excellent at finding
-the webshells, backdoors, injections, and known bad files that make up the large
-majority of website compromises, and at removing them without data loss.
-
-It is not a full endpoint protection suite and does not run in the kernel or
-watch memory in real time. On a busy production server it works best alongside a
-host scanner and a web application firewall, as the fast, readable, scriptable
-layer you can run on demand and in your pipelines. Signatures find known
-techniques, so pair a scan with good backups and prompt updates.
+## What JayShield can and cannot promise
+
+JayShield is a fast first responder for web malware: a file scanner you run on
+demand, read in full, and script.
+
+**It can:**
+
+- Read every file under the folders you name, except the skipped folder names
+  and oversized files it tells you about, and match each one against its
+  signature library, its heuristics, and the known bad hash set.
+- Show the exact file, line, and evidence for every finding, so you can judge
+  it yourself.
+- Recognise a WordPress install and tell you which flagged files are the site's
+  own code, so you replace those and remove the rest.
+- Quarantine without data loss. Every moved file is kept byte for byte and can
+  be restored.
+- Fit a pipeline: JSON output, exit codes, no dependencies, no network calls.
+
+**It cannot:**
+
+- Scan a website by its address. It has no crawler, and a webshell in
+  `wp-content/uploads` is invisible from the outside anyway. Get the files.
+- Read a database. Malware that lives in `wp_options` or inside posts, and rogue
+  admin users, are out of its sight.
+- Prove a file is unchanged. It has no copy of the official WordPress, plugin,
+  or theme checksums; use `wp core verify-checksums` for that.
+- Know which plugin versions are vulnerable, or how the attacker got in.
+- Watch in real time, block requests, or replace a firewall and backups.
+- Catch everything. Signatures and heuristics find known techniques. A clean
+  report means nothing matched, not that the site is clean.
+- Be right every time. Odd but legitimate code can trip a heuristic. The report
+  shows the line so you can decide, and `--ignore-rule` silences a rule you
+  have checked.
+
+**How it is checked.** Before a release the rules are run over real, clean
+code and must report nothing. For 1.3.0 (September 2026) that corpus was
+WordPress 7.1 with and without `--include vendor`, WooCommerce 11.1.0, the
+Astra theme 4.13.11, jQuery 3.7.1, and Laravel 12.x, over twelve thousand files
+in all, with zero findings. The same run must still catch every planted threat
+in the test fixtures. The test suite runs on every change on Node 18, 20, and
+22. If JayShield flags a clean file on your site, that is a bug worth
+[reporting](https://github.com/JayHackPro/JayShield/issues).
 
 ## Development
 
diff --git a/bin/jayshield.js b/bin/jayshield.js
index 08aedf7..dc05cbe 100755
--- a/bin/jayshield.js
+++ b/bin/jayshield.js
@@ -11,6 +11,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { scan } from "../src/scanner.js";
+import { DEFAULT_SKIP_DIRS } from "../src/walk.js";
 import { parseHashList } from "../src/hashes.js";
 import {
   quarantineFiles,
@@ -50,11 +51,17 @@ const BOOLEAN_FLAGS = new Set([
   "json", "follow-symlinks", "no-color", "verbose", "dry-run",
   "yes", "help", "version", "banner", "no-banner"
 ]);
-const VALUE_FLAGS = new Set(["min-severity", "ignore-rule", "hashes", "max-size", "vault"]);
+const VALUE_FLAGS = new Set(["min-severity", "ignore-rule", "hashes", "max-size", "vault", "include"]);
+const LIST_FLAGS = new Set(["ignore-rule", "include"]);
 const ALIASES = { h: "help", V: "version", v: "verbose", q: "quarantine", j: "json" };
 
+// A website address is not something JayShield can open. It reads files.
+const LOOKS_LIKE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+const LOOKS_LIKE_HOST = /^(?:www\.)?[a-z0-9-]+(?:\.[a-z0-9-]+)+(?:\/.*)?$/i;
+const GUIDE_URL = "https://github.com/JayHackPro/JayShield#scan-a-wordpress-site";
+
 function parseArgs(argv) {
-  const flags = { "ignore-rule": [] };
+  const flags = { "ignore-rule": [], include: [] };
   const positionals = [];
   let bad = null;
 
@@ -75,7 +82,7 @@ function parseArgs(argv) {
       if (VALUE_FLAGS.has(name)) {
         if (value === null) value = argv[++i];
         if (value === undefined) { bad = `--${name} needs a value`; break; }
-        if (name === "ignore-rule") flags["ignore-rule"].push(...value.split(",").map((s) => s.trim()).filter(Boolean));
+        if (LIST_FLAGS.has(name)) flags[name].push(...value.split(",").map((s) => s.trim()).filter(Boolean));
         else flags[name] = value;
       } else if (BOOLEAN_FLAGS.has(name)) {
         flags[name] = true;
@@ -107,9 +114,17 @@ function helpText(v) {
     jayshield file.php app/            scan several targets
     jayshield .                        scan the current folder
     jayshield . --min-severity high    show only high and critical
+    jayshield . --include vendor       also scan a folder skipped by name
     jayshield . --json > report.json   machine-readable output
     jayshield . --verbose              include rule ids and references
 
+  ${color.bold("Websites")}
+    JayShield reads files on disk. It does not connect to a URL.
+    To check a live site, run it on the server over SSH, or on a copy of
+    the site downloaded with SFTP or a backup. WordPress files that are
+    flagged are marked, with advice to replace rather than only remove.
+    ${color.dim(GUIDE_URL)}
+
   ${color.bold("Remove")}   ${color.dim("(safe: files are moved, never deleted)")}
     jayshield . --quarantine           move every threat into a local vault
     jayshield . --quarantine --dry-run preview what would move
@@ -124,6 +139,8 @@ function helpText(v) {
   ${color.bold("Options")}
     --min-severity <level>   critical | high | medium | low
     --ignore-rule <id,...>   silence one or more rules
+    --include <dir,...>      scan folders skipped by name, or "all"
+                             (skipped: ${[...DEFAULT_SKIP_DIRS].join(" ")})
     --hashes <file>          add known-bad sha256 hashes (one per line)
     --max-size <MB>          skip files larger than this (default 5)
     --vault <dir>            quarantine folder (default ${QUARANTINE_DIR})
@@ -150,6 +167,20 @@ function fail(message) {
   process.exitCode = 2;
 }
 
+/** Someone passed a website address. Say plainly what JayShield can do instead. */
+function failUrl(target) {
+  const host = target.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").replace(/\/.*$/, "") || "example.com";
+  const lines = [
+    `JayShield scans files on disk. It cannot connect to ${target}.`,
+    "  To check that site, run JayShield where its files are:",
+    color.brand(`    on the server, over SSH      jayshield /var/www/${host}/public_html`),
+    color.brand(`    or on a downloaded copy      jayshield ~/Downloads/${host}`),
+    "  Get the files with SFTP, your host's file manager, or a full site backup.",
+    color.dim(`  Guide: ${GUIDE_URL}`)
+  ];
+  fail(lines.join("\n"));
+}
+
 async function main() {
   const { flags, positionals, bad } = parseArgs(process.argv.slice(2));
   if (flags["no-color"] || flags.json) setColor(false);
@@ -191,15 +222,18 @@ async function main() {
 
   const targets = positionals.length ? positionals : ["."];
   for (const t of targets) {
+    if (LOOKS_LIKE_URL.test(t)) return failUrl(t);
     try {
       await fs.access(t);
     } catch {
+      if (LOOKS_LIKE_HOST.test(t)) return failUrl(t);
       return fail(`no such file or folder: ${t}`);
     }
   }
 
   const result = await scan(targets, {
     ignoreRules: new Set(flags["ignore-rule"]),
+    includeDirs: flags.include,
     extraHashes,
     maxBytes,
     minSeverity: flags["min-severity"],
diff --git a/docs/app.js b/docs/app.js
index ec91dea..f726546 100644
--- a/docs/app.js
+++ b/docs/app.js
@@ -193,7 +193,7 @@
     const lines = [
       { d: 350, html: "" },
       { d: 260, html: '<span class="t-banner"><span class="t-ascii">' + ASCII + '</span><span class="t-compact">  ▓█ JayHackPro █▓</span></span>' },
-      { d: 140, html: '<span class="t-sub">  JayShield®  ·  find and remove web malware</span><span class="t-dim">   v1.2.1</span>' },
+      { d: 140, html: '<span class="t-sub">  JayShield®  ·  find and remove web malware</span><span class="t-dim">   v1.3.0</span>' },
       { d: 100, html: '<span class="t-dim">  github.com/JayHackPro/JayShield</span>' },
       { d: 200, html: "" },
       { d: 420, html: '<span class="t-dim">  Scanned 1,284 files (24.6 MB) in 0.9s</span>' },
diff --git a/docs/assets/scan.html b/docs/assets/scan.html
index f1d8c23..6ba12a5 100644
--- a/docs/assets/scan.html
+++ b/docs/assets/scan.html
@@ -54,7 +54,7 @@
 ██   ██║██╔══██║  ╚██╔╝  ██╔══██║██╔══██║██║     ██╔═██╗ ██╔═══╝ ██╔══██╗██║   ██║
 ╚█████╔╝██║  ██║   ██║   ██║  ██║██║  ██║╚██████╗██║  ██╗██║     ██║  ██║╚██████╔╝
  ╚════╝ ╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝ ╚═════╝</pre>
-<pre class="out"><span class="g b">JayShield®  ·  find and remove web malware</span><span class="dim">   v1.2.1</span>
+<pre class="out"><span class="g b">JayShield®  ·  find and remove web malware</span><span class="dim">   v1.3.0</span>
 <span class="dim">github.com/JayHackPro/JayShield</span>
 
 <span class="dim">Scanned 1,284 files (24.6 MB) in 0.9s</span>
diff --git a/docs/assets/scan.png b/docs/assets/scan.png
index 2002598..2c69f8b 100644
Binary files a/docs/assets/scan.png and b/docs/assets/scan.png differ
diff --git a/docs/index.html b/docs/index.html
index 4d4cea3..97041ce 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -178,7 +178,7 @@ <h2>Remove threats without losing a byte.</h2>
     <div class="wrap install-wrap">
       <p class="kicker">// get started</p>
       <h2>Run your first scan in one line.</h2>
-      <p class="section-lede">No account, no agent, no dependencies to download. It runs anywhere Node does.</p>
+      <p class="section-lede">No account, no agent, no dependencies to download. It runs anywhere Node 18 or newer does, and it reads files on disk: run it on the server over SSH, or on a copy of the site downloaded with SFTP or a backup. It does not scan a URL.</p>
       <div class="install-cards">
         <div class="install-card">
           <p class="install-label">Scan a folder, no install</p>
@@ -193,7 +193,7 @@ <h2>Run your first scan in one line.</h2>
           <button class="copy-cmd wide" data-cmd="npm install -g @jayhackpro/jayshield"><span class="copy-prompt">$</span><code>npm install <span class="nb">-g</span> <span class="nb">@jayhackpro/jayshield</span></code><span class="copy-icon" aria-hidden="true">⧉</span></button>
         </div>
       </div>
-      <p class="install-foot">Exit codes make it drop straight into CI: <code>0</code> clean, <code>1</code> threats found, <code>2</code> error. Add <code>--json</code> for machine-readable output.</p>
+      <p class="install-foot">Exit codes make it drop straight into CI: <code>0</code> clean, <code>1</code> threats found, <code>2</code> error. Add <code>--json</code> for machine-readable output. WordPress owners: the <a href="https://github.com/JayHackPro/JayShield#scan-a-wordpress-site">step-by-step guide</a> covers any hosting, and the report tags WordPress core, theme, and plugin files so you replace those instead of only removing them.</p>
     </div>
   </section>
 
diff --git a/package.json b/package.json
index 0829d95..d19097b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@jayhackpro/jayshield",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Find and remove web malware, webshells, and backdoors. A fast, dependency-free malware scanner and quarantine tool by JayHackPro.",
   "keywords": [
     "malware",
diff --git a/src/heuristics.js b/src/heuristics.js
index c10fc62..1f1892b 100644
--- a/src/heuristics.js
+++ b/src/heuristics.js
@@ -57,6 +57,39 @@ const UPLOAD_PATH = /(?:wp-content\/(?:uploads|cache)|\/uploads?\/|\/media\/|\/a
 const PHP_TAG = Buffer.from("<?php");
 const PHP_SHORT = Buffer.from("<?=");
 
+// WP Super Cache and similar plugins store cached pages as .php files that
+// open with a `<?php die(); ?>` guard and hold only HTML after it. The guard
+// runs nothing, so a file whose only PHP is that guard is not an executable
+// planted in the cache. Anything else in the file is still scanned as usual.
+const PHP_GUARD = /<\?php\s+(?:die|exit)\s*(?:\(\s*(?:['"][^'"]*['"])?\s*\))?\s*;?\s*\?>/g;
+const CODE_MARKER = /<\?php\b|<\?=|<%|#!/;
+
+/** True when the text carries a die/exit guard and no other code marker. */
+export function onlyGuardPhp(text) {
+  const stripped = text.replace(PHP_GUARD, "");
+  return stripped.length !== text.length && !CODE_MARKER.test(stripped);
+}
+
+// Shape alone is not evidence. A packed payload has to unpack and run itself,
+// so the shape heuristics below also require one of these: a decoder, an
+// execution primitive, or request input. An SVG icon on one long line, a
+// lookup table full of escapes, or an embedded WebAssembly module has none.
+const SERVER_PRIMITIVE = /\b(?:eval|assert|base64_decode|gzinflate|gzuncompress|gzdecode|str_rot13|create_function|preg_replace|system|passthru|shell_exec|exec|popen|proc_open)\s*\(|\$_(?:GET|POST|REQUEST|COOKIE)\b|\$\w+\s*\(\s*\$/i;
+const BROWSER_SINK = /\beval\s*\(|\bFunction\s*\(|document\.write\s*\(|\.innerHTML\s*=|createElement\s*\(\s*['"]script|location(?:\.href|\.replace)?\s*[=(]|\.src\s*=/;
+
+/** Every line at or over the length cap, so a check can look inside them. */
+function longLines(text, min) {
+  const out = [];
+  let start = 0;
+  for (let i = 0; i <= text.length; i++) {
+    if (i === text.length || text.charCodeAt(i) === 10) {
+      if (i - start >= min) out.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  return out;
+}
+
 /** Byte offset of the first PHP open tag anywhere in a buffer, or -1. */
 function phpTagOffset(buffer) {
   const a = buffer.indexOf(PHP_TAG);
@@ -126,8 +159,9 @@ export function runHeuristics(file) {
   const findings = [];
   const posix = file.path.toLowerCase().replace(/\\/g, "/");
 
-  // An executable script sitting in an uploads or media folder.
-  if (EXECUTABLE_KINDS.has(file.kind) && UPLOAD_PATH.test(posix)) {
+  // An executable script sitting in an uploads or media folder. A cache page
+  // whose only PHP is the die() guard is left alone, see onlyGuardPhp.
+  if (EXECUTABLE_KINDS.has(file.kind) && UPLOAD_PATH.test(posix) && !onlyGuardPhp(file.text)) {
     findings.push(mk(
       "heuristic.exec_in_uploads",
       "Executable script in an uploads folder",
@@ -140,10 +174,11 @@ export function runHeuristics(file) {
   }
 
   // Very high entropy in a text-based source file means packed or encrypted
-  // content, which legitimate source rarely is.
+  // content. Legitimate source rarely has it, but data tables do, so the file
+  // must also hold something that could unpack or run the payload.
   if (file.kind === "php" || file.kind === "asp" || file.kind === "perl") {
     const entropy = shannonEntropy(file.buffer);
-    if (entropy >= 5.6 && file.buffer.length >= 512) {
+    if (entropy >= 5.6 && file.buffer.length >= 512 && SERVER_PRIMITIVE.test(file.text)) {
       findings.push(mk(
         "heuristic.high_entropy",
         "Packed or encrypted server script",
@@ -156,24 +191,33 @@ export function runHeuristics(file) {
     }
   }
 
-  // A single enormous line in a server script is almost always a minified
-  // one-line payload rather than hand-written code.
+  // A single enormous line in a server script that also decodes or runs
+  // something is the shape of a one-line payload. A long line of SVG markup
+  // or a big array literal is just a long line.
   if ((file.kind === "php" || file.kind === "asp") && longestLine(file.text) >= 2000) {
-    findings.push(mk(
-      "heuristic.long_line",
-      "Very long single line in a server script",
-      "medium",
-      "obfuscation",
-      file.text,
-      /.{2000,}/,
-      "One line thousands of characters long is the shape of a compressed, hidden payload."
-    ));
+    const payloadLine = longLines(file.text, 2000).find((line) => SERVER_PRIMITIVE.test(line));
+    if (payloadLine) {
+      findings.push(mk(
+        "heuristic.long_line",
+        "Very long single line that decodes or runs code",
+        "medium",
+        "obfuscation",
+        file.text,
+        /.{2000,}/,
+        "One line thousands of characters long, with a decoder or an execution call on it, is the shape of a compressed, hidden payload."
+      ));
+    }
   }
 
-  // A large base64 blob assigned to a variable, then handed to a decoder, is
-  // the loader half of most packed shells.
+  // A large base64 blob paired with a decoder is the loader half of most
+  // packed shells. In the browser the decoded text must also reach something
+  // that runs it; an embedded WebAssembly module or font decoded with atob
+  // does not.
   const blob = /['"][A-Za-z0-9+/]{200,}={0,2}['"]/;
-  if ((file.kind === "php" || file.kind === "js") && blob.test(file.text) && /(?:base64_decode|atob|gzinflate|gzuncompress)/.test(file.text)) {
+  const decoderNearby = file.kind === "js"
+    ? /\batob\s*\(/.test(file.text) && BROWSER_SINK.test(file.text)
+    : /(?:base64_decode|gzinflate|gzuncompress|gzdecode)\s*\(/.test(file.text);
+  if ((file.kind === "php" || file.kind === "js") && blob.test(file.text) && decoderNearby) {
     findings.push(mk(
       "heuristic.base64_blob",
       "Large encoded blob with a decoder nearby",
diff --git a/src/index.js b/src/index.js
index 4e62f58..9469fc3 100644
--- a/src/index.js
+++ b/src/index.js
@@ -15,6 +15,14 @@
  */
 
 export { scan, scanBuffer, worstSeverity, SEVERITY_RANK } from "./scanner.js";
+export { walk, DEFAULT_SKIP_DIRS, skipDirsWithout } from "./walk.js";
+export {
+  findWordPressRoots,
+  classifySiteFile,
+  readWordPressVersion,
+  countSiteRoles,
+  SITE_ROLES
+} from "./site.js";
 export { RULES, rulesForKind, kindForPath } from "./rules.js";
 export { runHeuristics, shannonEntropy } from "./heuristics.js";
 export { KNOWN_BAD, sha256, matchHash, parseHashList } from "./hashes.js";
diff --git a/src/report.js b/src/report.js
index 2fc99b0..cd7a5f3 100644
--- a/src/report.js
+++ b/src/report.js
@@ -8,6 +8,7 @@
 
 import { color, severityColor } from "./colors.js";
 import { worstSeverity } from "./scanner.js";
+import { countSiteRoles, SITE_ROLES } from "./site.js";
 
 const GLYPH = {
   critical: "✕", // x
@@ -69,11 +70,21 @@ export function formatHuman(result, opts = {}) {
     if (result.stats.unreadable) notes.push(`${result.stats.unreadable} unreadable`);
     out.push("  " + color.dim(notes.join(", ")));
   }
+  for (const site of result.sites || []) {
+    const v = site.version ? `WordPress ${site.version}` : "WordPress (version not read)";
+    out.push("  " + color.dim(`${v} at ${site.root}`));
+  }
+  if (result.stats.skippedDirs) {
+    const names = (result.skippedDirNames || []).join(", ");
+    const plural = result.stats.skippedDirs === 1 ? "folder" : "folders";
+    const include = (result.skippedDirNames || []).join(",") || "all";
+    out.push("  " + color.dim(`Skipped ${result.stats.skippedDirs} ${plural} by name (${names}). Scan them too with --include ${include}`));
+  }
   out.push("");
 
   if (!result.infected.length) {
     out.push("  " + color.green(color.bold("✔ No malware found.")));
-    out.push("  " + color.dim("Every file scanned came back clean."));
+    out.push("  " + color.dim("Nothing in the files scanned matched a known technique, heuristic, or bad hash."));
     out.push("");
     return out.join("\n");
   }
@@ -82,7 +93,8 @@ export function formatHuman(result, opts = {}) {
     const worst = record.findings[0].severity;
     const paint = severityColor(worst);
     const verb = opts.quarantined ? color.dim(" (quarantined)") : "";
-    out.push("  " + paint(color.bold(worst.toUpperCase().padEnd(9))) + color.bold(record.path) + verb);
+    const site = record.site ? color.dim(` [wordpress ${record.site.role}]`) : "";
+    out.push("  " + paint(color.bold(worst.toUpperCase().padEnd(9))) + color.bold(record.path) + site + verb);
 
     for (const f of record.findings) {
       const g = severityColor(f.severity)(GLYPH[f.severity] || "•");
@@ -117,14 +129,33 @@ export function formatHuman(result, opts = {}) {
   );
   out.push("");
 
+  const roles = countSiteRoles(result.infected);
+  const siteFiles = Object.values(roles).reduce((a, b) => a + b, 0);
+  if (siteFiles) {
+    const breakdown = SITE_ROLES.filter((r) => roles[r]).map((r) => `${roles[r]} ${r}`).join(", ");
+    out.push("  " + color.yellow(color.bold(`${siteFiles} flagged file${siteFiles === 1 ? " is" : "s are"} part of WordPress itself`)) + color.dim(` (${breakdown})`));
+    out.push("  " + color.dim("Injected code inside a real file means the whole file is untrusted. Replace these with"));
+    out.push("  " + color.dim("clean copies of the same version rather than only removing them:"));
+    for (const role of SITE_ROLES) {
+      if (!roles[role]) continue;
+      const advice = result.infected.find((r) => r.site && r.site.role === role).site.advice;
+      out.push("  " + color.dim(`  ${role}: `) + color.gray(advice));
+    }
+    out.push("");
+  }
+
   if (!opts.quarantined) {
     out.push("  " + color.dim("Review the findings, then remove them safely with:"));
     out.push("  " + color.brand(`    jayshield ${quoteTargets(result.targets)} --quarantine`));
     out.push("  " + color.dim("Quarantine moves files into a local vault. Put them back any time with --restore."));
+    if (siteFiles) out.push("  " + color.dim("Quarantining the WordPress files above takes the site offline until you replace them."));
     out.push("");
   } else {
     out.push("  " + color.dim("Files above were moved into the quarantine vault. Restore any of them with:"));
     out.push("  " + color.brand("    jayshield --restore"));
+    if (siteFiles) {
+      out.push("  " + color.yellow("WordPress files were moved too. If the site is offline now, restore them, then replace them with clean copies."));
+    }
     out.push("");
   }
 
@@ -147,12 +178,15 @@ export function toJson(result, extra = {}) {
       startedAt: result.startedAt,
       durationMs: result.durationMs,
       targets: result.targets,
+      sites: result.sites || [],
       summary: {
         scanned: result.stats.scanned,
         clean: result.stats.clean,
         infected: result.infected.length,
         skippedLarge: result.stats.skippedLarge,
         unreadable: result.stats.unreadable,
+        skippedDirs: result.stats.skippedDirs || 0,
+        skippedDirNames: result.skippedDirNames || [],
         worstSeverity: worstSeverity(result),
         bySeverity: result.countsBySeverity,
         byCategory: result.countsByCategory
@@ -160,6 +194,7 @@ export function toJson(result, extra = {}) {
       infected: result.infected.map((r) => ({
         path: r.path,
         size: r.size,
+        site: r.site ? { type: r.site.type, role: r.site.role, root: r.site.root } : null,
         findings: r.findings.map((f) => ({
           rule: f.id,
           name: f.name,
diff --git a/src/rules.js b/src/rules.js
index 744872d..c7178c1 100644
--- a/src/rules.js
+++ b/src/rules.js
@@ -72,6 +72,36 @@ export function kindForPath(filePath) {
   }
 }
 
+/**
+ * The hex-escaped spelling of a word, either letter case per character, so
+ * "\x65\x76\x61\x6c" and "\x45\x56\x41\x4C" both read as eval. Legitimate code
+ * writes binary constants as hex escapes all the time; nobody spells a
+ * function name that way unless they want it unseen.
+ */
+function hexWord(word) {
+  return word
+    .split("")
+    .map((ch) => {
+      const lower = ch.toLowerCase().charCodeAt(0).toString(16).padStart(2, "0");
+      const upper = ch.toUpperCase().charCodeAt(0).toString(16).padStart(2, "0");
+      return lower === upper ? `\\\\x${lower}` : `\\\\x(?:${lower}|${upper})`;
+    })
+    .join("");
+}
+
+const HEX_HIDDEN_WORDS = [
+  "eval", "assert", "system", "passthru", "shell_exec", "exec", "popen", "proc_open",
+  "base64_decode", "gzinflate", "gzuncompress", "gzdecode", "str_rot13", "create_function",
+  "preg_replace", "file_put_contents", "fwrite", "move_uploaded_file",
+  "_GET", "_POST", "_REQUEST", "_COOKIE"
+];
+
+// A dangerous name spelled in hex, or a hex string literal called as a function.
+const HEX_HIDDEN = new RegExp(
+  HEX_HIDDEN_WORDS.map(hexWord).join("|") + `|["'](?:\\\\x[0-9a-f]{2}){3,}["']\\s*\\(`,
+  "i"
+);
+
 export const RULES = [
   // ----- PHP obfuscation: decode-then-run, the signature of almost every shell
   {
@@ -176,12 +206,12 @@ export const RULES = [
   },
   {
     id: "php.hex_obfuscation",
-    name: "Long hex-escaped string",
-    severity: "medium",
+    name: "Function name hidden in hex escapes",
+    severity: "high",
     category: "obfuscation",
     kinds: ["php", "js"],
-    pattern: /(?:\\x[0-9a-f]{2}){12,}/i,
-    description: "A long run of hex escapes is a common way to hide function names and payloads.",
+    pattern: HEX_HIDDEN,
+    description: "A dangerous function or request variable is spelled out as hex escapes so a reader does not see it. Binary constants written in hex are normal and are not flagged.",
     references: ["https://owasp.org/www-community/attacks/Web_Shell"]
   },
   {
@@ -242,8 +272,8 @@ export const RULES = [
     severity: "critical",
     category: "webshell",
     kinds: ["php", "other"],
-    pattern: /WSO(?:hex)?|wso_ex|\$default_charset\s*=.*['"]FilesMan['"]/i,
-    description: "Fingerprint of the WSO webshell, one of the most widely reused PHP shells.",
+    pattern: /\bWSO_VERSION\b|\bwso(?:Login|Logout|Header|Footer|SecParam|Ex|PrintTree|Action|Ajax)\s*\(|\$wso_ex\b|\bWSO\s+(?:shell|\d+\.\d+)|\$default_charset\s*=.*['"]FilesMan['"]/i,
+    description: "Fingerprint of the WSO webshell, one of the most widely reused PHP shells. Matches its own function and constant names, not the letters w-s-o inside another word.",
     references: ["https://owasp.org/www-community/attacks/Web_Shell"]
   },
   {
@@ -324,8 +354,14 @@ export const RULES = [
     severity: "high",
     category: "injection",
     kinds: ["html", "php", "js"],
-    pattern: /<iframe\b[^>]*(?:(?:width|height)\s*=\s*["']?\s*[01]\b|style\s*=\s*["'][^"']*(?:display\s*:\s*none|visibility\s*:\s*hidden|position\s*:\s*absolute[^"']*(?:top|left)\s*:\s*-?\d))/i,
-    description: "An invisible iframe usually delivers malware or ad fraud to visitors without a trace on the page.",
+    // A hidden iframe that points somewhere, so it must carry a src. Skipped:
+    // a tag with no src, an empty or javascript: frame (upload libraries use
+    // those as a scratch target), and the Google Tag Manager noscript snippet
+    // that sits in most theme headers.
+    // Attribute scans stop at the next tag and are bounded, so a page full of
+    // unterminated tags costs linear time rather than stalling the scan.
+    pattern: /<iframe\b(?=[^<>]{0,3000}\bsrc\s*=)(?![^<>]{0,3000}\bsrc\s*=\s*(?:["']?\s*(?:javascript:|about:blank)|["']\s*["']|["']?[^"'>\s]{0,300}googletagmanager\.com\/ns\.html))[^<>]{0,3000}(?:\b(?:width|height)\s*=\s*["']?\s*[01]\b|style\s*=\s*["'][^"'<>]{0,3000}(?:display\s*:\s*none|visibility\s*:\s*hidden|position\s*:\s*absolute[^"'<>]{0,3000}(?:top|left)\s*:\s*-?\d))/i,
+    description: "An invisible iframe that loads another address usually delivers malware or ad fraud to visitors without a trace on the page.",
     references: ["https://owasp.org/www-community/attacks/Content_Spoofing"]
   },
   {
@@ -378,7 +414,7 @@ export const RULES = [
     severity: "medium",
     category: "spam",
     kinds: ["html", "php"],
-    pattern: /<(?:div|span)\b[^>]*style\s*=\s*["'][^"']*(?:display\s*:\s*none|position\s*:\s*absolute[^"']*left\s*:\s*-\d{3,})[^"']*["'][^>]*>\s*(?:<a\b[^>]*>[^<]*<\/a>\s*){2,}/i,
+    pattern: /<(?:div|span)\b[^<>]{0,3000}style\s*=\s*["'][^"'<>]{0,3000}(?:display\s*:\s*none|position\s*:\s*absolute[^"'<>]{0,3000}left\s*:\s*-\d{3,})[^"'<>]{0,3000}["'][^<>]{0,3000}>\s*(?:<a\b[^<>]{0,3000}>[^<]{0,3000}<\/a>\s*){2,}/i,
     description: "A block of links hidden from visitors but read by search engines, the shape of injected spam.",
     references: ["https://developers.google.com/search/docs/essentials/spam-policies"]
   },
diff --git a/src/scanner.js b/src/scanner.js
index 11ad9f0..0a9bd02 100644
--- a/src/scanner.js
+++ b/src/scanner.js
@@ -7,10 +7,11 @@
  */
 
 import { promises as fs } from "node:fs";
-import { walk, DEFAULT_SKIP_DIRS } from "./walk.js";
+import { walk, DEFAULT_SKIP_DIRS, skipDirsWithout } from "./walk.js";
 import { rulesForKind, globalize, kindForPath } from "./rules.js";
 import { runHeuristics, runByteHeuristics, evidenceAt } from "./heuristics.js";
 import { matchHash } from "./hashes.js";
+import { findWordPressRoots, noteWordPressRoot, classifySiteFile, readWordPressVersion } from "./site.js";
 
 export const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
 const DEFAULT_MAX_BYTES = 5 * 1024 * 1024; // 5 MB
@@ -106,7 +107,8 @@ export function scanBuffer(filePath, buffer, options = {}) {
  * @param {number} [options.maxBytes]        skip files larger than this
  * @param {Set<string>} [options.ignoreRules]
  * @param {Map} [options.extraHashes]
- * @param {Set<string>} [options.skipDirs]
+ * @param {Set<string>} [options.skipDirs]     directory names to skip (default DEFAULT_SKIP_DIRS)
+ * @param {Iterable<string>} [options.includeDirs]  default-skipped names to scan anyway, or "all"
  * @param {boolean} [options.followSymlinks]
  * @param {string} [options.minSeverity]     drop findings below this level
  * @param {(info:{path:string,findings:Array}) => void} [options.onFile]
@@ -115,21 +117,35 @@ export function scanBuffer(filePath, buffer, options = {}) {
 export async function scan(targets, options = {}) {
   const maxBytes = options.maxBytes || DEFAULT_MAX_BYTES;
   const minRank = SEVERITY_RANK[options.minSeverity] || 0;
-  const skipDirs = options.skipDirs || DEFAULT_SKIP_DIRS;
+  const skipDirs = options.skipDirs || (options.includeDirs ? skipDirsWithout(options.includeDirs) : DEFAULT_SKIP_DIRS);
 
   const started = Date.now();
   const result = {
     targets,
     infected: [],
-    stats: { scanned: 0, skippedLarge: 0, unreadable: 0, bytes: 0, clean: 0 },
+    stats: { scanned: 0, skippedLarge: 0, unreadable: 0, bytes: 0, clean: 0, skippedDirs: 0 },
+    skippedDirNames: [],
+    sites: [],
     countsBySeverity: { critical: 0, high: 0, medium: 0, low: 0 },
     countsByCategory: {},
     startedAt: new Date(started).toISOString(),
     durationMs: 0
   };
 
+  const skippedNames = new Set();
+  const onSkip = (name) => {
+    result.stats.skippedDirs++;
+    skippedNames.add(name);
+  };
+
+  // Which WordPress installs do these targets belong to? Checked up front so
+  // a scan of only wp-content still knows its site, and extended during the
+  // walk when a wp-settings.php turns up deeper in the tree.
+  const wpRoots = new Set(await findWordPressRoots(targets));
+
   for (const target of targets) {
-    for await (const entry of walk(target, { skipDirs, followSymlinks: options.followSymlinks })) {
+    for await (const entry of walk(target, { skipDirs, followSymlinks: options.followSymlinks, onSkip })) {
+      noteWordPressRoot(entry.path, wpRoots);
       if (entry.size > maxBytes) {
         result.stats.skippedLarge++;
         continue;
@@ -164,6 +180,18 @@ export async function scan(targets, options = {}) {
   result.infected.sort(
     (a, b) => topRank(b.findings) - topRank(a.findings) || a.path.localeCompare(b.path)
   );
+
+  // Which flagged files are the site's own code. The report gives these
+  // different advice: replace with a clean copy rather than only remove.
+  for (const record of result.infected) {
+    const site = classifySiteFile(record.path, wpRoots);
+    if (site) record.site = site;
+  }
+  for (const root of [...wpRoots].sort()) {
+    result.sites.push({ type: "wordpress", root, version: await readWordPressVersion(root) });
+  }
+
+  result.skippedDirNames = [...skippedNames].sort();
   result.durationMs = Date.now() - started;
   return result;
 }
diff --git a/src/site.js b/src/site.js
new file mode 100644
index 0000000..4e28611
--- /dev/null
+++ b/src/site.js
@@ -0,0 +1,172 @@
+/*!
+ * JayShield by JayHackPro
+ * Find and remove web malware, webshells, and backdoors.
+ * Released under JayHackPro® Inc. Designed by Jayden Yoon ZK.
+ * MIT License: use it freely, and keep this notice. The brand stays behind the code.
+ * https://github.com/JayHackPro/JayShield
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * Site awareness.
+ *
+ * JayShield scans files on disk. On a WordPress site some of those files are
+ * the site's own code, and the site cannot run without them. When one of them
+ * is flagged, the honest advice is different: quarantining wp-config.php or a
+ * theme's functions.php takes the site offline, and injected code inside a
+ * real file means the whole file is untrusted and should be replaced with a
+ * clean copy. This module tells the report which flagged files are which.
+ */
+
+// A WordPress root holds these two side by side.
+const WP_MARKER_FILE = "wp-settings.php";
+const WP_MARKER_DIR = "wp-includes";
+const MAX_ANCESTORS = 16;
+
+/** Role labels, in the order the report should mention them. */
+export const SITE_ROLES = ["config", "core", "theme", "plugin"];
+
+const ADVICE = {
+  config:
+    "This is a WordPress configuration file. Quarantining it takes the site offline. Open it, remove the injected code by hand or rebuild it from wp-config-sample.php, and rotate the database password and salts.",
+  core:
+    "This is a WordPress core file. Quarantining it takes the site offline. Replace it with a clean copy of the same version from wordpress.org, or reinstall core.",
+  theme:
+    "This is a theme file. Quarantining it breaks the theme and can blank the site. Reinstall the theme from where you got it, or switch to a default theme first.",
+  plugin:
+    "This is a plugin file. Quarantining it makes WordPress deactivate the plugin. Delete the plugin and reinstall a clean copy from wordpress.org or the vendor."
+};
+
+// Root files the site cannot serve without.
+const ROOT_CONFIG = new Set(["wp-config.php", ".htaccess", "web.config", ".user.ini", "php.ini"]);
+const ROOT_CORE = new Set([
+  "index.php", "wp-load.php", "wp-settings.php", "wp-blog-header.php", "wp-cron.php",
+  "wp-login.php", "xmlrpc.php", "wp-mail.php", "wp-links-opml.php", "wp-signup.php",
+  "wp-activate.php", "wp-comments-post.php", "wp-trackback.php", "wp-config-sample.php"
+]);
+
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+
+async function isWordPressRoot(dir) {
+  try {
+    const [f, d] = await Promise.all([
+      fs.stat(path.join(dir, WP_MARKER_FILE)),
+      fs.stat(path.join(dir, WP_MARKER_DIR))
+    ]);
+    return f.isFile() && d.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Read the WordPress version from wp-includes/version.php, or null. */
+export async function readWordPressVersion(root) {
+  try {
+    const text = await fs.readFile(path.join(root, WP_MARKER_DIR, "version.php"), "utf8");
+    const m = /\$wp_version\s*=\s*['"]([^'"]+)['"]/.exec(text);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Find the WordPress installs that contain or sit under the scan targets.
+ * Each target is checked, then its ancestors, so scanning only wp-content
+ * still knows which site it belongs to. Roots found while walking are added
+ * later by the scanner through noteWordPressRoot().
+ *
+ * @param {string[]} targets
+ * @returns {Promise<string[]>} absolute root directories
+ */
+export async function findWordPressRoots(targets) {
+  const roots = new Set();
+  for (const target of targets) {
+    let dir;
+    try {
+      const stat = await fs.stat(target);
+      dir = path.resolve(stat.isDirectory() ? target : path.dirname(target));
+    } catch {
+      continue;
+    }
+    for (let i = 0; i < MAX_ANCESTORS; i++) {
+      if (await isWordPressRoot(dir)) {
+        roots.add(dir);
+        break;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return [...roots];
+}
+
+/**
+ * Called by the scanner for every file it sees. If this file is the marker
+ * of a WordPress install that has not been recorded yet, record its root.
+ *
+ * @param {string} filePath
+ * @param {Set<string>} roots  absolute roots, mutated in place
+ */
+export function noteWordPressRoot(filePath, roots) {
+  if (path.basename(filePath) !== WP_MARKER_FILE) return;
+  roots.add(path.resolve(path.dirname(filePath)));
+}
+
+/**
+ * Which part of a WordPress site a file belongs to, or null for files the
+ * site does not need (uploads, cache, stray scripts, anything outside a
+ * known install). Only files under a detected root are classified, so a
+ * random index.php elsewhere is never called core.
+ *
+ * @param {string} filePath
+ * @param {Iterable<string>} roots  absolute WordPress roots
+ * @returns {{type:"wordpress", root:string, role:string, advice:string}|null}
+ */
+export function classifySiteFile(filePath, roots) {
+  const abs = path.resolve(filePath);
+  for (const root of roots) {
+    const rel = path.relative(root, abs);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) continue;
+    const posix = toPosix(rel);
+    const role = roleFor(posix);
+    if (!role) return null;
+    return { type: "wordpress", root, role, advice: ADVICE[role] };
+  }
+  return null;
+}
+
+function roleFor(rel) {
+  const parts = rel.split("/");
+  const name = parts[parts.length - 1];
+  if (parts.length === 1) {
+    if (ROOT_CONFIG.has(name)) return "config";
+    if (ROOT_CORE.has(name)) return "core";
+    return null;
+  }
+  const top = parts[0];
+  if (top === "wp-admin" || top === "wp-includes") return "core";
+  if (top === "wp-content" && parts.length >= 3) {
+    // wp-content/themes/<theme>/... and wp-content/plugins/<plugin>/...
+    // Only code counts; a stray image inside a theme is not site code.
+    if (!/\.(?:php\d?|phtml|pht|inc)$/i.test(name)) return null;
+    if (parts[1] === "themes" && parts.length >= 4) return "theme";
+    if (parts[1] === "plugins" && parts.length >= 4) return "plugin";
+  }
+  return null;
+}
+
+/** Count flagged records by site role, for the report. */
+export function countSiteRoles(records) {
+  const counts = {};
+  for (const r of records) {
+    if (!r.site) continue;
+    counts[r.site.role] = (counts[r.site.role] || 0) + 1;
+  }
+  return counts;
+}
diff --git a/src/walk.js b/src/walk.js
index 4d8ee31..81f539c 100644
--- a/src/walk.js
+++ b/src/walk.js
@@ -11,8 +11,12 @@ import path from "node:path";
 
 /**
  * Directory names that are noise for a malware scan. They are skipped by
- * default so a scan of a real project stays fast and readable. The user
- * can still force them back in with --include.
+ * default so a scan of a real project stays fast and readable. The scan
+ * report says which of them were skipped, and --include puts them back.
+ *
+ * A plain "cache" folder is NOT on this list on purpose. On a WordPress site
+ * wp-content/cache is web-served, often writable, and a common place to plant
+ * a shell, so skipping it would turn a real infection into a clean report.
  */
 export const DEFAULT_SKIP_DIRS = new Set([
   ".git",
@@ -21,10 +25,16 @@ export const DEFAULT_SKIP_DIRS = new Set([
   "node_modules",
   "vendor",
   ".jayshield-quarantine",
-  ".cache",
-  "cache"
+  ".cache"
 ]);
 
+/** The skip set minus the names the user asked to include. "all" includes everything. */
+export function skipDirsWithout(include) {
+  const wanted = new Set(include || []);
+  if (wanted.has("all")) return new Set();
+  return new Set([...DEFAULT_SKIP_DIRS].filter((name) => !wanted.has(name)));
+}
+
 /**
  * Walk a starting path and yield every file underneath it, one at a time,
  * without ever loading the whole tree into memory. Symbolic links are not
@@ -36,11 +46,13 @@ export const DEFAULT_SKIP_DIRS = new Set([
  * @param {Set<string>} [options.skipDirs]  directory names to skip
  * @param {boolean} [options.followSymlinks=false]
  * @param {(dir: string) => boolean} [options.enterDir]  return false to skip a directory
+ * @param {(name: string, dir: string) => void} [options.onSkip]  called for every directory skipped by name
  */
 export async function* walk(root, options = {}) {
   const skipDirs = options.skipDirs || DEFAULT_SKIP_DIRS;
   const followSymlinks = Boolean(options.followSymlinks);
   const enterDir = options.enterDir;
+  const onSkip = typeof options.onSkip === "function" ? options.onSkip : null;
 
   const stat = await fs.lstat(root);
   if (stat.isFile()) {
@@ -79,7 +91,10 @@ export async function* walk(root, options = {}) {
       }
 
       if (dirent.isDirectory()) {
-        if (skipDirs.has(entry.name)) continue;
+        if (skipDirs.has(entry.name)) {
+          if (onSkip) onSkip(entry.name, full);
+          continue;
+        }
         if (enterDir && !enterDir(full)) continue;
         stack.push(full);
       } else if (dirent.isFile()) {
diff --git a/test/cli.test.mjs b/test/cli.test.mjs
index a422ea3..64e899d 100644
--- a/test/cli.test.mjs
+++ b/test/cli.test.mjs
@@ -88,3 +88,65 @@ test("a missing target fails cleanly with exit 2", () => {
   assert.equal(r.status, 2);
   assert.match(r.stderr, /no such file or folder/);
 });
+
+test("a website address is refused with an explanation, not a confusing file error", () => {
+  for (const target of ["https://example.com", "http://example.com/wp-admin/", "example.com", "www.example.com/blog"]) {
+    const r = run([target]);
+    assert.equal(r.status, 2, target);
+    assert.match(r.stderr, /scans files on disk/, target);
+    assert.match(r.stderr, /cannot connect to/, target);
+    assert.match(r.stderr, /over SSH/, target);
+    assert.match(r.stderr, /downloaded copy/, target);
+    assert.doesNotMatch(r.stderr, /no such file or folder/, target);
+  }
+});
+
+test("--include scans a folder that is skipped by name", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "jayshield-cli-include-"));
+  try {
+    await fs.mkdir(path.join(dir, "vendor"));
+    await fs.writeFile(path.join(dir, "ok.php"), "<?php echo 1;");
+    await fs.writeFile(path.join(dir, "vendor", "bad.php"), "<?php eval(base64_decode($_POST['x']));");
+
+    const skipped = run([dir, "--json"]);
+    assert.equal(skipped.status, 0);
+    const a = JSON.parse(skipped.stdout);
+    assert.equal(a.summary.skippedDirs, 1);
+    assert.deepEqual(a.summary.skippedDirNames, ["vendor"]);
+
+    const included = run([dir, "--json", "--include", "vendor"]);
+    assert.equal(included.status, 1);
+    const b = JSON.parse(included.stdout);
+    assert.equal(b.summary.skippedDirs, 0);
+    assert.equal(b.summary.infected, 1);
+
+    const human = run([dir]);
+    assert.match(human.stdout, /Skipped 1 folder by name \(vendor\)/);
+    assert.match(human.stdout, /--include vendor/);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("the report names WordPress files and says to replace them, in text and in JSON", async () => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "jayshield-cli-wp-"));
+  try {
+    await fs.mkdir(path.join(dir, "wp-includes"));
+    await fs.writeFile(path.join(dir, "wp-settings.php"), "<?php // settings");
+    await fs.writeFile(path.join(dir, "wp-includes", "version.php"), "<?php $wp_version = '6.8.2';");
+    await fs.writeFile(path.join(dir, "wp-config.php"), "<?php eval(base64_decode($_POST['x']));");
+
+    const human = run([dir]);
+    assert.equal(human.status, 1);
+    assert.match(human.stdout, /WordPress 6\.8\.2 at /);
+    assert.match(human.stdout, /\[wordpress config\]/);
+    assert.match(human.stdout, /part of WordPress itself/);
+    assert.match(human.stdout, /takes the site offline/);
+
+    const json = JSON.parse(run([dir, "--json"]).stdout);
+    assert.equal(json.sites[0].version, "6.8.2");
+    assert.equal(json.infected[0].site.role, "config");
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
diff --git a/test/heuristics.test.mjs b/test/heuristics.test.mjs
index 3e88f71..947351b 100644
--- a/test/heuristics.test.mjs
+++ b/test/heuristics.test.mjs
@@ -1,7 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { scanBuffer } from "../src/scanner.js";
-import { shannonEntropy, longestLine } from "../src/heuristics.js";
+import { shannonEntropy, longestLine, onlyGuardPhp } from "../src/heuristics.js";
 
 const idsFor = (p, content) => scanBuffer(p, Buffer.from(content)).map((f) => f.id);
 
@@ -43,6 +43,19 @@ test("flags an executable script inside a web uploads folder", () => {
   assert.ok(ids.includes("heuristic.exec_in_uploads"));
 });
 
+test("a cached page whose only PHP is the die() guard is not an executable in the cache", () => {
+  const guard = "<?php die(); ?>\n<!DOCTYPE html><html><body>cached</body></html>\n";
+  assert.equal(onlyGuardPhp(guard), true);
+  assert.equal(onlyGuardPhp("<?php exit; ?>\n<html></html>"), true);
+  assert.equal(onlyGuardPhp("<html>no php at all</html>"), false);
+  assert.equal(onlyGuardPhp("<?php die(); ?>\n<?php system($_GET['c']); ?>"), false);
+  assert.deepEqual(idsFor("/var/www/site/wp-content/cache/supercache/wp-cache-1.php", guard), []);
+  // The guard does not hide a payload that follows it.
+  const ids = idsFor("/var/www/site/wp-content/cache/supercache/wp-cache-2.php", "<?php die(); ?>\n<?php system($_GET['c']); ?>");
+  assert.ok(ids.includes("heuristic.exec_in_uploads"));
+  assert.ok(ids.includes("php.exec_user_input"));
+});
+
 test("does NOT flag a normal script just because a system ancestor is named tmp or cache", () => {
   // Regression: earlier the heuristic walked every ancestor up to root, so a
   // file under /private/tmp or /var/cache was wrongly called an upload.
@@ -51,9 +64,43 @@ test("does NOT flag a normal script just because a system ancestor is named tmp
 });
 
 test("flags packed or one-line payloads by shape", () => {
-  const packed = "<?php $x='" + "A".repeat(2600) + "'; // one very long line";
+  const packed = "<?php eval(gzinflate(base64_decode('" + "A".repeat(2600) + "')));";
   assert.ok(idsFor("packed.php", packed).includes("heuristic.long_line"));
 
   const blob = "<?php $data = '" + "QUJD".repeat(80) + "'; echo base64_decode($data);";
   assert.ok(idsFor("loader.php", blob).includes("heuristic.base64_blob"));
+
+  const browser = "var p='" + "QUJD".repeat(80) + "'; document.write(atob(p));";
+  assert.ok(idsFor("loader.js", browser).includes("heuristic.base64_blob"));
+});
+
+test("shape alone is not a finding: long data lines, hex tables, and embedded wasm are left alone", () => {
+  // Real WordPress core shapes that used to be flagged.
+  const svgLine = "<?php return array( 'icon' => '<svg " + "d=\"M0 0h24v24H0z\" ".repeat(150) + "' );";
+  assert.deepEqual(idsFor("wp-includes/blocks/social-link.php", svgLine), []);
+
+  const entityTable = "<?php\n" + "$t = array(\n" + Array.from({ length: 400 }, (_, i) => `  '&#x${(0x1f300 + i).toString(16)};&#x200d;&#xfe0f;' => ${i},`).join("\n") + "\n);";
+  assert.deepEqual(idsFor("wp-includes/formatting.php", entityTable), []);
+
+  const wasm = "const bytes = atob('" + "AGFzbQEAAAAB".repeat(40) + "'); WebAssembly.instantiate(Uint8Array.from(bytes, c => c.charCodeAt(0)));";
+  assert.deepEqual(idsFor("router/index.js", wasm), []);
+
+  // High entropy with no way to unpack or run anything is data, not a payload.
+  const noise = "<?php\n$table = \"" + Array.from({ length: 4000 }, (_, i) => "\\x" + ((i * 7919) % 256).toString(16).padStart(2, "0")).join("") + "\";";
+  assert.ok(!idsFor("table.php", noise).includes("heuristic.high_entropy"));
+  assert.ok(!idsFor("table.php", noise).includes("php.hex_obfuscation"));
+
+  // A dense payload with a decoder next to it is still flagged. The bytes are
+  // pseudo-random so the base64 text is close to the entropy of a real packer.
+  let seed = 12345;
+  const bytes = Buffer.alloc(6000);
+  for (let i = 0; i < bytes.length; i++) {
+    seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+    bytes[i] = (seed >>> 16) & 0xff;
+  }
+  const packed = "<?php eval(gzinflate(base64_decode('" + bytes.toString("base64") + "')));";
+  assert.ok(idsFor("packed.php", packed).includes("heuristic.high_entropy"));
+  // The same dense blob with nothing to unpack it is left alone.
+  const data = "<?php $blob = '" + bytes.toString("base64") + "';";
+  assert.ok(!idsFor("data.php", data).includes("heuristic.high_entropy"));
 });
diff --git a/test/rules.test.mjs b/test/rules.test.mjs
index 97e1370..e4dac59 100644
--- a/test/rules.test.mjs
+++ b/test/rules.test.mjs
@@ -73,6 +73,43 @@ test("catches browser cryptominers and injected iframes", () => {
   assert.ok(idsFor("p.html", '<iframe src="http://x" width="0" height="0"></iframe>').includes("js.hidden_iframe"));
 });
 
+test("the WSO rule matches WSO's own names, not the letters w-s-o inside another word", () => {
+  assert.ok(idsFor("x.php", "<?php define('WSO_VERSION', '2.5');").includes("shell.wso"));
+  assert.ok(idsFor("x.php", "<?php function wsoLogin() { die(); } wsoLogin();").includes("shell.wso"));
+  assert.ok(idsFor("x.php", "<?php echo '<title>WSO 4.2.5</title>';").includes("shell.wso"));
+  // Real WordPress core lines that used to be called a webshell.
+  assert.deepEqual(idsFor("wp-admin/includes/continents-cities.php", "<?php __( 'Dawson', 'continents-cities' );"), []);
+  assert.deepEqual(idsFor("wp-includes/load.php", "<?php // that should be protected against WSODs and the plugin is paused."), []);
+  assert.deepEqual(idsFor("Compat.php", "<?php if (self::useNewSodiumAPI()) { return 1; }"), []);
+  assert.deepEqual(idsFor("ca-bundle.crt", "utI3gzhTODY7z2zp+WsO0PsE6E9312UBeIYMej4hYvF/Y3EMyZ9E26gnonW+boE+18DrG5gPcFw0"), []);
+});
+
+test("the hex rule flags hidden function names, not binary constants", () => {
+  // "system" and "eval" spelled in hex, lower and upper case.
+  assert.ok(idsFor("x.php", '<?php $f = "\\x73\\x79\\x73\\x74\\x65\\x6d"; $f($_GET["c"]);').includes("php.hex_obfuscation"));
+  assert.ok(idsFor("x.php", '<?php "\\x45\\x56\\x41\\x4C"($_POST["p"]);').includes("php.hex_obfuscation"));
+  // A hex string literal invoked directly, whatever it spells.
+  assert.ok(idsFor("x.php", '<?php "\\x61\\x62\\x63"("x");').includes("php.hex_obfuscation"));
+  // $_POST spelled in hex.
+  assert.ok(idsFor("x.js", 'var k = "\\x5f\\x50\\x4f\\x53\\x54";').includes("php.hex_obfuscation"));
+  // Binary constants from real WordPress core, sodium_compat, and getID3.
+  assert.deepEqual(idsFor("compat-utf8.php", '<?php $x = "\\x00\\x01\\x02\\x03\\x04\\x05\\x06\\x07\\x08\\x09\\x0a\\x0b\\x0c\\x0d\\x0e\\x0f";'), []);
+  assert.deepEqual(idsFor("AEGIS256.php", "<?php define('SODIUM_COMPAT_AEGIS_C0', \"\\x00\\x01\\x01\\x02\\x03\\x05\\x08\\x0d\\x15\\x22\\x37\\x59\\x90\\xe9\\x79\\x62\");"), []);
+  assert.deepEqual(idsFor("H.php", '<?php const L = "\\xed\\xd3\\xf5\\x5c\\x1a\\x63\\x12\\x58\\xd6\\x9c\\xf7\\xa2\\xde\\xf9\\xde\\x14\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x10";'), []);
+});
+
+test("the hidden iframe rule wants a frame that goes somewhere", () => {
+  assert.ok(idsFor("p.html", '<iframe src="http://x" width="0" height="0"></iframe>').includes("js.hidden_iframe"));
+  assert.ok(idsFor("p.php", "<?php echo '<iframe src=\"//evil.example/l.php\" style=\"visibility:hidden\"></iframe>';").includes("js.hidden_iframe"));
+  assert.ok(idsFor("p.js", "document.write('<iframe src=\"http://evil.example/x\" width=1 height=1></iframe>');").includes("js.hidden_iframe"));
+  // marginwidth="0" is not width="0".
+  assert.deepEqual(idsFor("embed.php", '<?php echo \'<iframe sandbox="allow-scripts" src="%1$s" width="%2$d" height="%3$d" frameborder="0" marginwidth="0" marginheight="0" scrolling="no"></iframe>\';'), []);
+  // A hidden scratch frame with no destination, as upload libraries create.
+  assert.deepEqual(idsFor("moxie.js", "temp.innerHTML = '<iframe id=\"' + uid + '_iframe\" src=\"javascript:&quot;&quot;\" style=\"display:none\"></iframe>';"), []);
+  // The Google Tag Manager noscript snippet that sits in most theme headers.
+  assert.deepEqual(idsFor("header.php", '<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXX" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>'), []);
+});
+
 test("catches the EICAR test string in any file kind", () => {
   const ids = idsFor("note.txt", "harmless X5O EICAR-STANDARD-ANTIVIRUS-TEST-FILE marker");
   assert.ok(ids.includes("test.eicar"));
diff --git a/test/scanner.test.mjs b/test/scanner.test.mjs
index 34189bd..1018761 100644
--- a/test/scanner.test.mjs
+++ b/test/scanner.test.mjs
@@ -15,6 +15,28 @@ async function tempTree() {
   return dir;
 }
 
+/** A WordPress install with threats planted where they turn up in real life. */
+async function wordpressTree() {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "jayshield-wp-"));
+  const mk = async (rel, text) => {
+    const full = path.join(dir, rel);
+    await fs.mkdir(path.dirname(full), { recursive: true });
+    await fs.writeFile(full, text);
+  };
+  await mk("wp-settings.php", "<?php // settings");
+  await mk("wp-includes/version.php", "<?php\n$wp_version = '6.8.2';\n");
+  await mk("wp-includes/load.php", "<?php // load");
+  await mk("wp-config.php", "<?php\ndefine('DB_NAME', 'wp');\neval(base64_decode($_POST['x']));\n");
+  await mk("wp-content/themes/twentytwentyfive/functions.php", "<?php\nadd_action('init', 'x');\n$_GET['f']($_GET['a']);\n");
+  await mk("wp-content/plugins/akismet/akismet.php", "<?php // clean plugin");
+  await mk("wp-content/uploads/2026/09/shell.php", "<?php system($_POST['cmd']);");
+  await mk("wp-content/cache/planted.php", "<?php system($_GET['c']);");
+  await mk("wp-content/cache/supercache/wp-cache-abc.php", "<?php die(); ?>\n<html><body>cached</body></html>\n");
+  await mk("vendor/lib/x.php", "<?php // vendor");
+  await mk("node_modules/y/index.js", "module.exports = 1;");
+  return dir;
+}
+
 test("scan walks a tree and reports infected files only", async () => {
   const dir = await tempTree();
   try {
@@ -75,6 +97,86 @@ test("binary files are not run through the text rules", () => {
   assert.ok(!findings.some((f) => f.id === "php.eval_decode"));
 });
 
+test("a cache folder is scanned by default, and a shell planted there is found", async () => {
+  const dir = await wordpressTree();
+  try {
+    const result = await scan([dir]);
+    const paths = result.infected.map((r) => path.relative(dir, r.path).split(path.sep).join("/"));
+    assert.ok(paths.includes("wp-content/cache/planted.php"), "planted cache shell was not found");
+    // The legacy WP Super Cache page, whose only PHP is the die() guard, is not a threat.
+    assert.ok(!paths.includes("wp-content/cache/supercache/wp-cache-abc.php"), "guard-only cache page was flagged");
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("skipped folders are counted and named, and --include puts them back", async () => {
+  const dir = await wordpressTree();
+  try {
+    const byDefault = await scan([dir]);
+    assert.equal(byDefault.stats.skippedDirs, 2);
+    assert.deepEqual(byDefault.skippedDirNames, ["node_modules", "vendor"]);
+
+    const withVendor = await scan([dir], { includeDirs: ["vendor"] });
+    assert.equal(withVendor.stats.skippedDirs, 1);
+    assert.deepEqual(withVendor.skippedDirNames, ["node_modules"]);
+    assert.equal(withVendor.stats.scanned, byDefault.stats.scanned + 1);
+
+    const everything = await scan([dir], { includeDirs: ["all"] });
+    assert.equal(everything.stats.skippedDirs, 0);
+    assert.equal(everything.stats.scanned, byDefault.stats.scanned + 2);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a WordPress install is recognised and its own flagged files are marked", async () => {
+  const dir = await wordpressTree();
+  try {
+    const result = await scan([dir]);
+    assert.equal(result.sites.length, 1);
+    assert.equal(result.sites[0].type, "wordpress");
+    assert.equal(result.sites[0].version, "6.8.2");
+    assert.equal(result.sites[0].root, path.resolve(dir));
+
+    const roleOf = (name) => {
+      const r = result.infected.find((x) => x.path.endsWith(name));
+      assert.ok(r, `${name} was not flagged`);
+      return r.site ? r.site.role : null;
+    };
+    assert.equal(roleOf("wp-config.php"), "config");
+    assert.equal(roleOf("functions.php"), "theme");
+    assert.equal(roleOf("shell.php"), null);
+    assert.equal(roleOf("planted.php"), null);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("scanning only wp-content still knows which WordPress site it belongs to", async () => {
+  const dir = await wordpressTree();
+  try {
+    const result = await scan([path.join(dir, "wp-content")]);
+    assert.equal(result.sites.length, 1);
+    assert.equal(result.sites[0].root, path.resolve(dir));
+    const theme = result.infected.find((x) => x.path.endsWith("functions.php"));
+    assert.equal(theme.site.role, "theme");
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("a plain folder reports no site and no site roles", async () => {
+  const dir = await tempTree();
+  try {
+    const result = await scan([dir]);
+    assert.deepEqual(result.sites, []);
+    assert.ok(result.infected.every((r) => !r.site));
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
 test("a clean tree returns an empty result", async () => {
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "jayshield-clean-"));
   try {
diff --git a/test/site.test.mjs b/test/site.test.mjs
new file mode 100644
index 0000000..74f7d7e
--- /dev/null
+++ b/test/site.test.mjs
@@ -0,0 +1,106 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  findWordPressRoots,
+  classifySiteFile,
+  readWordPressVersion,
+  countSiteRoles
+} from "../src/site.js";
+
+/** A small WordPress install with the markers JayShield looks for. */
+async function wordpressTree() {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "jayshield-site-"));
+  const site = path.join(dir, "public_html");
+  for (const sub of [
+    "wp-includes",
+    "wp-admin",
+    "wp-content/themes/twentytwentyfive",
+    "wp-content/plugins/akismet",
+    "wp-content/uploads/2026/09",
+    "wp-content/cache"
+  ]) {
+    await fs.mkdir(path.join(site, sub), { recursive: true });
+  }
+  await fs.writeFile(path.join(site, "wp-settings.php"), "<?php // settings");
+  await fs.writeFile(path.join(site, "wp-includes", "version.php"), "<?php\n$wp_version = '6.8.2';\n");
+  return { dir, site };
+}
+
+test("finds the WordPress root from the root itself, a child folder, and a single file", async () => {
+  const { dir, site } = await wordpressTree();
+  try {
+    assert.deepEqual(await findWordPressRoots([site]), [site]);
+    assert.deepEqual(await findWordPressRoots([path.join(site, "wp-content", "uploads")]), [site]);
+    assert.deepEqual(await findWordPressRoots([path.join(site, "wp-settings.php")]), [site]);
+    // A folder with no WordPress above it finds nothing.
+    assert.deepEqual(await findWordPressRoots([dir]), []);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("reads the WordPress version, and returns null when it cannot", async () => {
+  const { dir, site } = await wordpressTree();
+  try {
+    assert.equal(await readWordPressVersion(site), "6.8.2");
+    assert.equal(await readWordPressVersion(dir), null);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("classifies the files a WordPress site cannot run without", () => {
+  const root = "/srv/site";
+  const role = (rel) => {
+    const hit = classifySiteFile(path.join(root, rel), [root]);
+    return hit ? hit.role : null;
+  };
+  assert.equal(role("wp-config.php"), "config");
+  assert.equal(role(".htaccess"), "config");
+  assert.equal(role("index.php"), "core");
+  assert.equal(role("wp-load.php"), "core");
+  assert.equal(role("wp-includes/load.php"), "core");
+  assert.equal(role("wp-admin/includes/file.php"), "core");
+  assert.equal(role("wp-content/themes/twentytwentyfive/functions.php"), "theme");
+  assert.equal(role("wp-content/plugins/akismet/akismet.php"), "plugin");
+  assert.equal(role("wp-content/plugins/akismet/views/config.php"), "plugin");
+});
+
+test("does not call the files a site can live without site files", () => {
+  const root = "/srv/site";
+  const hit = (rel) => classifySiteFile(path.join(root, rel), [root]);
+  assert.equal(hit("wp-content/uploads/2026/09/shell.php"), null);
+  assert.equal(hit("wp-content/cache/planted.php"), null);
+  assert.equal(hit("wp-content/mu-plugins/dropper.php"), null);
+  assert.equal(hit("wp-content/themes/twentytwentyfive/screenshot.png"), null);
+  assert.equal(hit("wp-content/plugins/akismet/readme.txt"), null);
+  assert.equal(hit("wp-content/themes/index.php"), null);
+  assert.equal(hit("backup.php"), null);
+});
+
+test("a file outside every known root is never called core, whatever its name", () => {
+  assert.equal(classifySiteFile("/srv/other/index.php", ["/srv/site"]), null);
+  assert.equal(classifySiteFile("/srv/site-two/wp-config.php", ["/srv/site"]), null);
+  assert.equal(classifySiteFile("/srv/site/index.php", []), null);
+});
+
+test("every classification carries plain advice and the site it belongs to", () => {
+  const hit = classifySiteFile("/srv/site/wp-config.php", ["/srv/site"]);
+  assert.equal(hit.type, "wordpress");
+  assert.equal(hit.root, "/srv/site");
+  assert.match(hit.advice, /offline/);
+  assert.match(hit.advice, /salts/);
+});
+
+test("counts flagged records by role", () => {
+  const counts = countSiteRoles([
+    { site: { role: "core" } },
+    { site: { role: "core" } },
+    { site: { role: "theme" } },
+    { path: "uploads/shell.php" }
+  ]);
+  assert.deepEqual(counts, { core: 2, theme: 1 });
+});