@osqd/bothandlerjs 0.3.0

package/docs/reference/configuration.md

@@ -0,0 +1,175 @@
+# Configuration reference
+
+Every option `BotHandler` takes, grouped by what it is for.
+
+← [Documentation](../index.md)
+
+---
+
+```ts
+new BotHandler({
+  // Detection
+  detectors, extraDetectors, signatures, extraSignatures,
+  suspectThreshold: 60, strictEvidence, detectorTimeoutMs: 300,
+
+  // Policy
+  preset, rules, defaultAction: "allow", defaultActionParams,
+  falsePositivePolicy: "strict", fallbackAction, terminalScoreThreshold: 85,
+
+  // Addresses — invalid CIDRs throw at construction, never match silently
+  allowlist, denylist, datacenterRanges, crawlerRanges: { gptbot: ["1.2.3.0/24"] },
+
+  // Identity and scope
+  proxy: { trustProxy, trustedProxies, hops, header },
+  actorKey: (facts) => facts.ip,
+  ignorePaths, isHuman,
+
+  // Observation
+  audit: { windowMs: 300_000, baselineMs: 3_600_000, minSamples: 50 },
+  onAssessment, onDecision, onDenial, onDowngrade, onChallenge,
+  onDetectorFailure, onPolicyChange, onGuardChange, onRangeChange, onActorChange, onAnomaly,
+
+  // Infrastructure
+  challenge, store, notifications, handlers, resolver, clock,
+  shareConfirmations: false,              // proof crosses replicas; suspicion does not
+  actorWindowMs: 900_000, maxActors: 20_000, exposeVerdictHeaders: false,
+  metrics: true,                          // or { perDetectorTiming: true }
+  onError, onWarning,
+});
+```
+
+---
+
+## Detection
+
+| Option | Default | |
+| ------ | ------- | - |
+| `detectors` | the default set | replaces it **entirely** |
+| `extraDetectors` | — | appended; ignored when `detectors` is given |
+| `signatures` | `BOT_SIGNATURES` | replaces the [signature database](../detection/signatures.md) |
+| `extraSignatures` | — | appended to it |
+| `suspectThreshold` | `60` | score at or above which an unproven request is `suspected-bot` |
+| `strictEvidence` | `true` outside production | reject `certain` evidence carrying no `deterministicBasis` |
+| `detectorTimeoutMs` | `300` | budget per `io` detector; exceeding it drops the detector, not the request |
+
+`strictEvidence` downgrades to a warning when `NODE_ENV` is `production`, so a third-party
+detector with a missing basis cannot take a live site down. See
+[evidence](../concepts/evidence.md).
+
+## Policy
+
+| Option | Default | |
+| ------ | ------- | - |
+| `preset` | — | a named [starting policy](../policy/presets.md) |
+| `rules` | — | your own [rules](../policy/rules.md), evaluated **before** any preset's |
+| `defaultAction` | `"allow"` | when nothing matches |
+| `defaultActionParams` | — | params for it |
+| `falsePositivePolicy` | `"strict"` | [the guard's](../concepts/the-guard.md) mode |
+| `fallbackAction` | `"challenge"` | substituted when the guard stops a terminal action; **cannot itself be terminal** |
+| `terminalScoreThreshold` | `85` | score needed for a terminal action under `balanced` |
+
+## Addresses
+
+| Option | |
+| ------ | - |
+| `allowlist` | exempt from detection **entirely** — your monitors, your office, your CI |
+| `denylist` | treated as proven automation; an explicit local decision |
+| `datacenterRanges` | hosting-provider ranges; none ships with the library |
+| `crawlerRanges` | published ranges keyed by signature id — see [verification](../detection/verification.md) |
+
+Invalid CIDRs **throw at construction**. A range that silently matches nothing is a control
+you believe you have and do not.
+
+`allowlist` is the strongest thing here: an address on it is not judged leniently, it is not
+judged at all. Do not put loopback on it — see [the client IP](../integration/client-ip.md).
+
+## Identity and scope
+
+| Option | Default | |
+| ------ | ------- | - |
+| `proxy` | `{ trustProxy: false }` | **read [the client IP](../integration/client-ip.md) first** |
+| `actorKey` | the client address | the single most valuable thing to replace |
+| `ignorePaths` | — | health checks, your own polling endpoints, static assets |
+| `isHuman` | — | your application declaring a request human |
+
+`isHuman` produces `certain` human evidence — the only conclusive human signal available,
+because it comes from you and not from the client. An authenticated session, a completed
+payment, whatever bar you set:
+
+```ts
+isHuman: (facts) => Boolean(facts.session && sessions.get(facts.session)?.authenticated)
+```
+
+## Observation
+
+`audit` takes [`AuditOptions`](../operations/audit.md) or `false`. Every `onX` hook mirrors
+an [event](../operations/index.md#events-and-hooks) — the config form is convenient, the
+emitter form can be subscribed to later and removed.
+
+## Infrastructure
+
+| Option | Default | |
+| ------ | ------- | - |
+| `challenge` | — | enables the [challenge action](../challenge/index.md); without it those rules degrade to `tag` |
+| `store` | in-memory | see [stores](../integration/stores.md) |
+| `shareConfirmations` | `false` | proof crosses replicas; suspicion does not. Needs a shared store |
+| `notifications` | — | [sinks, filtering, redaction](../operations/notifications.md) |
+| `handlers` | — | [`custom` action](../policy/actions.md#custom) handlers |
+| `resolver`, `clock` | system | injected for tests and the [corpus](../testing/corpus.md) |
+| `actorWindowMs` | `900_000` | how long an idle [actor](../concepts/actors.md) is remembered |
+| `maxActors` | `20_000` | a memory budget; past it the least recently seen actor is evicted |
+| `exposeVerdictHeaders` | `false` | **leave it off** — see below |
+| `metrics` | `true` | or `{ perDetectorTiming: true }` |
+| `onError`, `onWarning` | — | |
+
+### `exposeVerdictHeaders`
+
+An `X-Bot-Score` in the *response* is a live feedback signal for anyone tuning a scraper
+against you: change one header, watch the number fall, iterate. Request-side tagging gives
+your application the same information and tells the client nothing. It is off by default and
+should stay off.
+
+---
+
+## Performance and memory
+
+Detection on a clean browser request costs about **9 µs** to assess and **12 µs** end to
+end, and allocates a few hundred bytes. `npm run bench` reports the median of several
+rounds; `npm run bench:guard` enforces a ratio-based budget so a regression fails the build
+rather than shipping quietly.
+
+Five things got it there, each a trap the next person will meet too:
+
+- `header-order` computed an HMAC fingerprint on every request before knowing whether it had
+  anything to report — it cost more than the other twelve detectors combined.
+- `randomBytes` was called per request for the request id; it is now drawn from a pooled
+  buffer.
+- The User-Agent tokeniser ran eagerly, when a mainstream browser string never needs it.
+- The notification event — an ISO timestamp included — was built before checking whether any
+  sink was listening.
+- Per-detector timing allocated a closure per detector per request *whether or not it was
+  switched on*: 8 µs a request to support a feature that is off by default. The benchmark
+  caught that one, which is what a benchmark is for.
+
+Signatures compile once into an Aho–Corasick automaton with a flat transition table for the
+root node, so matching is O(input length) regardless of how many signatures exist, and text
+that matches nothing allocates nothing at all.
+
+DNS runs only when a request actually claimed a verifiable identity, and results are cached:
+successes for an hour, transient failures for a minute, definitive absences for an hour.
+
+Per-actor state is a fixed budget: 32 arrival timestamps, 64 path *hashes* (not strings), up
+to 4 User-Agents. At 20,000 tracked actors that is tens of megabytes, not hundreds. Every
+structure keyed by anything a client controls is a bounded LRU — an unbounded map here would
+be a remote OOM.
+
+The trade-off: `requestsWithin` saturates at 32, so a very heavy actor is reported as "at
+least 32" with `undercounted: true` rather than at its true rate. Deliberate — that series
+exists to describe an actor cheaply, and exact counting belongs to the
+[`rate-limit`](../policy/actions.md#rate-limit) action, which uses the store.
+
+## Related
+
+- [API](api.md) — the methods and the exported names
+- [The guard](../concepts/the-guard.md) — the four options that decide how far a rule may go
+- [Runtime changes](../operations/runtime-changes.md) — what can be changed without a restart

package/docs/start/choosing-a-policy.md

@@ -0,0 +1,127 @@
+# Choosing a policy
+
+The decision, start to finish.
+
+← [Documentation](../index.md) · [Getting started](../index.md)
+
+---
+
+## Start with the question, not the preset
+
+Not "how do I block bots" but: **what is this site for, and what would it cost me to be
+wrong?**
+
+| If being wrong about a *person* costs you… | and being wrong about a *bot* costs you… | start with |
+| --- | --- | --- |
+| a reader | some bandwidth | [`allow-crawlers`](../policy/presets.md#allow-crawlers) |
+| a customer | your content, scraped | [`protect-content`](../policy/presets.md#protect-content) |
+| a customer | your pricing, in a competitor's spreadsheet | [`protect-data`](../policy/presets.md#protect-data) |
+| a broken integration | an API bill | [`protect-api`](../policy/presets.md#protect-api) |
+| a lost signup | a compromised account | [`protect-auth`](../policy/presets.md#protect-auth), on those routes |
+| your search traffic | your work in a training corpus | [`decline-ai-training`](../policy/presets.md#decline-ai-training) |
+
+Whatever the answer, **the first week is [`monitor-only`](../policy/presets.md#monitor-only)**.
+
+## The four questions worth answering explicitly
+
+### 1. Which crawlers do you actually want?
+
+This is a business decision, not a security one, and it deserves to be a visible rule you
+can point at rather than a threshold somebody tuned.
+
+Search and social crawlers bring readers. AI training crawlers take work and return nothing
+you can measure. SEO crawlers serve your competitors. Feed readers and link unfurlers are
+somebody's actual reading habit.
+
+If you decline any of them, **say so in [`robots.txt`](../policy/robots.md)** — the ones
+worth declining honour it, and a rule that blocks a crawler nobody told is load with no
+compliance.
+
+### 2. What happens to suspicion?
+
+The [guard](../concepts/the-guard.md) settles the top of the range: unproven never means
+denied. Below that, you choose between `tag`, `delay`, `rate-limit` and `challenge`, and the
+right answer depends on who your unusual visitors are.
+
+A `challenge` needs a browser. On an API it breaks your customers' integrations and stops
+nobody, which is why [`protect-api`](../policy/presets.md#protect-api) uses rate limits
+instead. A `delay` excludes nobody at all and is the quiet choice on a form.
+
+Look at [`bothandler_score_bucket`](../operations/metrics.md) before you move a threshold. It
+tells you how many requests sit in the ten points you are about to cross.
+
+### 3. Where does the policy *not* apply?
+
+`ignorePaths` for health checks and static assets. `allowlist` for your monitors, your
+office and your CI — and remember that an allowlisted address is not judged leniently, it is
+not judged at all.
+
+And the routes that need a *different* policy get their own handler:
+
+```ts
+app.use(botHandler(siteDetector));
+app.use("/login",    botHandler(authDetector));
+app.use("/checkout", botHandler(authDetector));
+```
+
+### 4. Who is allowed to change it, and how fast?
+
+An incident is when you will want to change a rule without a deploy. Decide now whether
+[the dashboard's editor](../operations/runtime-changes.md) is enabled, who can reach it, and
+whether the [guard panel](../concepts/the-guard.md) is enabled separately — it is a different
+power with different consequences.
+
+---
+
+## Check it before it meets anybody
+
+```bash
+npx @osqd/bothandlerjs check --preset protect-content --audience human
+npx @osqd/bothandlerjs replay /var/log/nginx/access.log --preset protect-content
+```
+
+The first is [526 shapes of real traffic](../testing/corpus.md); the second is *yours*. Both
+print every request the policy would have refused, with the evidence.
+
+For your own configuration rather than a preset:
+
+```ts
+import { runCorpus } from "@osqd/bothandlerjs/corpus";
+const scorecard = await runCorpus({
+  create: ({ resolver, clock }) => new BotHandler({ ...myConfig, resolver, clock }),
+  assertActions: false,
+});
+if (scorecard.falsePositives.length > 0) throw new Error("this policy turns people away");
+```
+
+## Owning it rather than naming it
+
+A preset is an array of [rules](../policy/rules.md). Once you have changed one thing, take
+the whole set:
+
+```ts
+import { protectContent } from "@osqd/bothandlerjs";
+
+const rules = protectContent()
+  .filter((rule) => rule.id !== "http-client-challenge")   // our partners use curl
+  .concat({ id: "partner-allow", match: { path: "/api/partner" }, action: "allow" });
+```
+
+Your own rules are evaluated **before** a preset's, so `rules` plus `preset` is a valid way
+to prepend exceptions without copying anything.
+
+## What to watch once it is live
+
+| Signal | Means |
+| ------ | ----- |
+| `bothandler_downgrades_total` rising | your rules ask for more than the evidence supports |
+| `challenge-solve-rate` high | the challenges are taxing people, not filtering bots |
+| `verdicts_total{verdict="unknown"}` falling | your traffic changed, or your detection did |
+| a `denial-spike` anomaly | read the denials before assuming they are all bots |
+
+## Next
+
+- [Presets](../policy/presets.md) — all eight, in detail
+- [Rules](../policy/rules.md) — the grammar
+- [Actions](../policy/actions.md) — ordered by what each costs a person
+- [Threat model](../concepts/threat-model.md) — what none of this can do

package/docs/start/first-integration.md

@@ -0,0 +1,127 @@
+# Your first integration
+
+Working in five minutes, safe in one week.
+
+← [Documentation](../index.md) · [Getting started](../index.md)
+
+---
+
+## The five minutes
+
+```ts
+import { BotHandler } from "@osqd/bothandlerjs";
+import { botHandler } from "@osqd/bothandlerjs/adapters";
+
+const detector = new BotHandler({
+  preset: "monitor-only",               // watch first; enforce later
+  allowlist: ["10.0.0.0/8"],            // your monitors and CI
+  ignorePaths: ["/healthz", "/metrics"],
+});
+
+app.use(botHandler(detector));
+
+await detector.serveDashboard({ port: 9674 });
+```
+
+Open **http://localhost:9674/**. Every request lands in the feed with its verdict, and any
+row opens to show the [evidence](../concepts/evidence.md) behind it.
+
+Nothing is being withheld from anybody — [`monitor-only`](../policy/presets.md#monitor-only)
+never acts. That is deliberate, and it is step one of four.
+
+## The four steps
+
+### 1. Watch, for a week
+
+Run `monitor-only` on real traffic and look at the dashboard. You are looking for the
+integration you forgot about: the partner's nightly sync, the status-page prober, the
+marketing team's link checker, your own server-side renderer.
+
+Every bot policy that has caused an outage was deployed straight to enforcement by someone
+who was sure they knew what their traffic looked like.
+
+### 2. Fix the client address
+
+If anything sits in front of your process — a load balancer, a CDN, nginx, a service mesh —
+this is the setting that matters most:
+
+```ts
+proxy: { trustProxy: true, trustedProxies: ["10.0.0.0/8"] }
+```
+
+The client address becomes the [actor key](../concepts/actors.md), which every rate limit,
+allowlist entry and behavioural signal depends on. Getting it wrong is silent. Read
+[the client IP](../integration/client-ip.md) — it is short and it is the page most worth
+reading twice.
+
+### 3. Check the policy you are about to enable
+
+```bash
+npx @osqd/bothandlerjs check --preset protect-content
+npx @osqd/bothandlerjs replay /var/log/nginx/access.log --preset protect-content
+```
+
+The first runs your policy against [526 shapes of real traffic](../testing/corpus.md); the
+second runs it against yours. Read the list of would-be-denied requests. If any of them is a
+person, the policy is wrong — and you found out from a log file.
+
+Put the `check` in CI. It exits non-zero when a case marked as a person is denied.
+
+### 4. Enable it
+
+```ts
+const detector = new BotHandler({
+  preset: "protect-content",
+  proxy: { trustProxy: true, trustedProxies: ["10.0.0.0/8"] },
+  challenge: {
+    secrets: [process.env.BOT_CHALLENGE_SECRET!],
+    contactHtml: '<p>Locked out? Email <a href="mailto:support@example.com">support@example.com</a>.</p>',
+  },
+  allowlist: ["10.0.0.0/8"],
+  ignorePaths: ["/healthz", "/metrics"],
+  onDowngrade: ({ decision }) => log.warn(`rule ${decision.rule} asked for more than its evidence`),
+});
+```
+
+Then watch `bothandler_downgrades_total` — see [metrics](../operations/metrics.md).
+
+## What a working configuration does
+
+| Request | Result |
+| ------- | ------ |
+| A real Chrome navigation | `200` — served, untouched |
+| `curl https://yoursite/` | challenge page — proven `http-client` |
+| A `Googlebot` UA from an address DNS refutes | `403` — proven `impersonator` |
+| `sqlmap` | `403` — self-identified scanner |
+| A hit on a [trap](../detection/detectors.md) link | `403` — no person can reach it |
+| `GET /healthz` | `200` — never assessed |
+| Real Googlebot, confirmed by DNS | `200` — explicitly allowed |
+
+## Three things people wish they had done sooner
+
+**Replace `actorKey`.** An address is a poor identity — shared by an office, changed by a
+phone every few minutes. A session id makes every behavioural detector sharper:
+
+```ts
+actorKey: (facts) => facts.session ?? facts.ip
+```
+
+**Add `isHuman`.** Your authenticated session is the only conclusive human signal that
+exists. Telling the library about it stops it second-guessing your own customers:
+
+```ts
+isHuman: (facts) => Boolean(sessions.get(facts.session ?? "")?.authenticated)
+```
+
+**Mount [`protect-auth`](../policy/presets.md#protect-auth) separately** on login, signup and
+checkout — and *only* there. Site-wide it refuses your webhooks and your renderer.
+
+```ts
+app.use("/login", botHandler(authDetector));
+```
+
+## Next
+
+- [Choosing a policy](choosing-a-policy.md)
+- [Adapters](../integration/adapters.md) — Fastify, Koa, Hono, Next.js, Workers
+- [The dashboard](../operations/dashboard.md) — before you expose it anywhere real

package/docs/start/installation.md

@@ -0,0 +1,63 @@
+# Installation
+
+← [Documentation](../index.md) · [Getting started](../index.md)
+
+---
+
+```bash
+npm install @osqd/bothandlerjs
+```
+
+**Node 18 or later.** ESM and CJS builds, TypeScript declarations included.
+
+## Zero runtime dependencies
+
+The library imports nothing but `node:` builtins, and CI fails if that ever stops being
+true. Nothing here can hand your project a transitive advisory, an install script, or a
+version conflict with something you already run.
+
+Redis, if you use it, is your client passed in: `RedisStore` describes the five commands it
+needs structurally and imports neither `ioredis` nor `node-redis`.
+
+```ts
+import { RedisStore } from "@osqd/bothandlerjs";
+new BotHandler({ store: new RedisStore(redis) });
+```
+
+## The entry points
+
+| Import | Contains |
+| ------ | -------- |
+| `@osqd/bothandlerjs` | the engine, detectors, presets, robots, stores, notifiers, challenge, dashboard |
+| `@osqd/bothandlerjs/adapters` | [Express, Fastify, Koa, Fetch](../integration/adapters.md) |
+| `@osqd/bothandlerjs/client` | the browser-side [client signals](../detection/client-signals.md) script |
+| `@osqd/bothandlerjs/corpus` | [`runCorpus`](../testing/corpus.md) and all 526 cases |
+| `@osqd/bothandlerjs/cli` | the [command line](../testing/cli.md) |
+
+## Runtimes
+
+| Runtime | Notes |
+| ------- | ----- |
+| Node 18+ | everything works |
+| Bun, Deno | use the [Fetch adapter](../integration/adapters.md) |
+| Cloudflare Workers | enable `nodejs_compat` — the engine uses `node:crypto` |
+| Vercel Edge, Netlify Edge | Fetch adapter; set `clientIp` explicitly |
+
+On every Fetch runtime, two things differ. There is no socket, so the client address comes
+from a header — read [the client IP](../integration/client-ip.md) before you deploy. And
+header order is normalised, so `header-order` returns nothing there; drop it.
+
+## Without installing anything
+
+Every CLI command runs through `npx`:
+
+```bash
+npx @osqd/bothandlerjs explain "curl/8.4.0"
+npx @osqd/bothandlerjs check --preset protect-content
+npx @osqd/bothandlerjs replay /var/log/nginx/access.log
+```
+
+## Next
+
+- [Your first integration](first-integration.md)
+- [Choosing a policy](choosing-a-policy.md)

package/docs/start/upgrading.md

@@ -0,0 +1,72 @@
+# Upgrading
+
+← [Documentation](../index.md) · [Getting started](../index.md)
+
+---
+
+## Versioning
+
+Semantic versioning, with one clarification that matters for a library like this:
+
+**A new detector, or a signature added to the database, is a minor release.** It can change
+what your policy does to a request that was previously unrecognised — that is the point of
+installing it — but it cannot change the [guard's](../concepts/the-guard.md) guarantee, and
+it cannot turn a probabilistic verdict into a proven one.
+
+**A change to how a tier is assigned is a major release.** Moving something from `strong` to
+`certain` changes what may be denied, which is exactly the boundary this library exists to
+hold still.
+
+## Before you upgrade
+
+Run your own configuration against the corpus and compare:
+
+```bash
+npx @osqd/bothandlerjs check --preset protect-content --json > before.json
+npm install @osqd/bothandlerjs@latest
+npx @osqd/bothandlerjs check --preset protect-content --json > after.json
+```
+
+Or, for a configuration that is not a preset:
+
+```ts
+import { runCorpus } from "@osqd/bothandlerjs/corpus";
+const scorecard = await runCorpus({
+  create: ({ resolver, clock }) => new BotHandler({ ...myConfig, resolver, clock }),
+  assertActions: false,
+});
+```
+
+The invariant — nothing marked as a person is denied — holds across versions and is checked
+on every release. What can move is which *bots* a policy catches, and the scorecard shows
+that as a diff rather than a surprise.
+
+## 0.x
+
+The library is pre-1.0. The engine, the evidence model, the guard and the policy grammar are
+stable and are what everything else is built on; the surfaces most likely to change before
+1.0 are the dashboard's options and the shape of the corpus scorecard.
+
+Pin an exact version if you depend on either:
+
+```json
+{ "dependencies": { "@osqd/bothandlerjs": "0.2.0" } }
+```
+
+## When a signature changes hands
+
+Not a library upgrade, but the same class of problem: a crawler's published ranges go stale,
+and a stale list turns a verified crawler into an accused impersonator.
+
+```ts
+import { startCrawlerRangeRefresh } from "@osqd/bothandlerjs";
+const stop = startCrawlerRangeRefresh(botHandler);   // twice a day
+```
+
+See [verification](../detection/verification.md) and
+[runtime changes](../operations/runtime-changes.md).
+
+## Related
+
+- [The corpus](../testing/corpus.md) — the regression suite you can run yourself
+- [Design decisions](../design/decisions.md) — what a future change would be undoing

package/docs/testing/cli.md

@@ -0,0 +1,119 @@
+# The CLI
+
+Five commands, no server, no installation.
+
+← [Documentation](../index.md) · [Testing](index.md)
+
+---
+
+```
+bothandlerjs replay <file> [options]   Replay an access log and report what would have happened
+bothandlerjs check [--preset <p>]      Run a policy against the traffic corpus: who would it hurt?
+bothandlerjs explain [request]         Assess one request and show the evidence behind the verdict
+bothandlerjs robots [options]          Generate a robots.txt from a policy preset
+bothandlerjs detectors [--preset <p>]  List the detectors a configuration installs
+```
+
+---
+
+## `explain`
+
+The question that arrives by ticket rather than by traffic.
+
+```bash
+bothandlerjs explain "curl/8.4.0"
+pbpaste | bothandlerjs explain --preset protect-data
+bothandlerjs explain --ip 203.0.113.9 --url /checkout "Mozilla/5.0 ..."
+```
+
+It takes a User-Agent, a `curl` command copied out of devtools, or a raw header block — from
+an argument or from stdin — and prints the verdict, the rule that would fire, and every
+piece of [evidence](../concepts/evidence.md) behind it.
+
+It runs as a **[dry run](../detection/index.md)**, so nothing is recorded and asking does
+not change the answer. It has no history by construction, so what it answers is *what would
+this look like as a first request* — which is what a ticket is asking anyway.
+
+## `check`
+
+The CI step.
+
+```bash
+npx @osqd/bothandlerjs check --preset protect-content
+```
+
+```
+  protect-content against 522 shapes of real traffic
+
+  human            181 cases   3 tag, 175 allow, 3 challenge
+  benign-bot       144 cases   6 allow, 86 tag, 48 block, 2 challenge, 2 rate-limit
+  declared-bot      32 cases   18 tag, 2 rate-limit, 3 allow, 9 block
+  unwanted-bot     105 cases   8 tag, 11 rate-limit, 3 block, 70 challenge, 13 allow
+  hostile           27 cases   6 challenge, 17 block, 4 allow
+  infrastructure    33 cases   7 allow, 12 tag, 14 challenge
+
+  No case marked as a person was denied service.
+```
+
+The question this library is organised around, asked before a deploy rather than after one:
+*if I point this configuration at the actual internet, who gets hurt?*
+
+**It exits non-zero if any case marked `human` is denied service**, which is what makes it a
+CI step rather than a report.
+
+| Option | |
+| ------ | - |
+| `--preset <name>` | which policy to test (default `protect-content`) |
+| `--audience <a>` | `human` \| `benign-bot` \| `declared-bot` \| `unwanted-bot` \| `hostile` \| `infrastructure` |
+| `--json` | the scorecard, for a pipeline |
+| `--strict` | also fail on differing actions, not only the invariants |
+
+`--audience human` is the one to reach for first: it shows only the part that matters.
+
+See [the corpus](corpus.md) for what it is running against.
+
+## `replay`
+
+Your policy against your own traffic. See [log replay](replay.md) — including the reason
+JSON Lines is much better than CLF.
+
+```bash
+npx @osqd/bothandlerjs replay /var/log/nginx/access.log --preset protect-content
+```
+
+| Option | |
+| ------ | - |
+| `--preset <name>` | default `protect-content` |
+| `--limit <n>` | stop after n parsed lines |
+| `--show <n>` | how many would-be-denied requests to print in full (default 10) |
+| `--format <f>` | `clf` \| `json` (detected from the first line by default) |
+| `--json` | the report, machine-readable |
+
+## `robots`
+
+```bash
+bothandlerjs robots --preset decline-ai-training --sitemap https://example.com/sitemap.xml > public/robots.txt
+```
+
+Generates a `robots.txt` from a preset's rules (default preset: `protect-data`), with the
+trap paths disallowed for you.
+
+Notes about rules that could not be reflected go to **stderr**, so a redirect into the file
+stays clean while the reasoning still reaches whoever ran the command. Read them — see
+[robots.txt](../policy/robots.md) for why an unreflected rule matters.
+
+## `detectors`
+
+```bash
+bothandlerjs detectors --preset protect-api
+```
+
+Lists what a configuration actually installs, with each detector's cost and stage. Useful
+for the question "is `identity-rotation` on?", which has caused more confusion than any
+other single setting.
+
+## Related
+
+- [The corpus](corpus.md) · [Log replay](replay.md)
+- [Detectors](../detection/detectors.md) — what `detectors` is listing
+- [robots.txt](../policy/robots.md) — what `robots` is generating