docs: document search, the word filter, and what the board puts in a browser

MEI-124 pass two, finished. Three pages, and one corrected claim.

docs/guides/community/search.md — the four controls, and the fact that
makes switching search off safe to try: the index is kept and goes on
being maintained, so turning it back on needs no reindex. Also separates
the two limits people conflate, since setting one does nothing about the
other: the flood interval is per member and about impatience, the hourly
cap is aimed at a script.

docs/guides/community/word-filter.md — a pattern is a literal, not a
wildcard, so `.*` matches two characters and nothing else. The filter
runs at render time and never edits stored text, which is why removing a
rule brings the original word back everywhere and why a quote of a
filtered post carries the original.

docs/guides/operations/cookies-and-headers.md — every cookie, why it
exists, and why SameSite differs by purpose: Lax for the SSO handshake
because a Strict cookie is not sent on the identity provider's
navigation back, Strict for the admin, second-factor and passkey
exchanges because none of those ever start elsewhere. The nonce CSP, and
REMOTE_IMAGES as the one environment variable that widens it.

The corrected claim: moderation-guide.md said the word filter rewrites
words "wherever a post is shown — thread pages, excerpts, feeds, search
results". All seven filterWords call sites guard a body, an excerpt or a
summary; none guards a title. A filtered word stays visible in every
forum listing and beside its own filtered excerpt in search results. The
guide now says so, and the gap is filed separately.

Verified before writing rather than reproduced: searchScopeFor really is
built from the forum audience, and staff really do see unapproved and
deleted posts in results; the flood interval is bypassed by the
flood.bypass permission; REMOTE_IMAGES is what adds https: to img-src.

Author: claude

README.md

@@ -93,8 +93,11 @@ The table below is generated from `apps/web/content/docs.manifest.json` by `pnpm
 | Configuration & guides | [`guides/community/groups.md`](./docs/guides/community/groups.md) | What a group carries: board-wide permissions, the daily allowances, colours and badges, display groups, the groups a plugin may grant, and the rules that promote members automatically. |
 | Configuration & guides | [`guides/community/antispam.md`](./docs/guides/community/antispam.md) | The registration challenge, the limits on pages nobody has signed in to, the three login counters, and the hourly allowances — what each is worth and what it costs a real visitor. |
 | Configuration & guides | [`guides/community/reputation.md`](./docs/guides/community/reputation.md) | Members rating each other: what a rating is worth, the four settings, the two that decide between a one-press thanks and a form, and why the totals cannot drift. |
+| Configuration & guides | [`guides/community/search.md`](./docs/guides/community/search.md) | The four controls over the most expensive thing a visitor can ask for: switching search off without losing the index, the shortest word a query may rest on, and the two different limits on how often. |
+| Configuration & guides | [`guides/community/word-filter.md`](./docs/guides/community/word-filter.md) | Rewriting words as a page renders, never in the stored post: what a rule is, why a pattern is a literal rather than a wildcard, and exactly which surfaces it covers. |
 | Configuration & guides | [`guides/operations/operating.md`](./docs/guides/operations/operating.md) | Routine checks, configuration, maintenance commands, backups, recovery, and troubleshooting for a running board. |
 | Configuration & guides | [`guides/operations/monitoring.md`](./docs/guides/operations/monitoring.md) | Liveness versus readiness, the optional Prometheus metrics endpoint and what to alert on, distributed tracing, and shipping logs. |
+| Configuration & guides | [`guides/operations/cookies-and-headers.md`](./docs/guides/operations/cookies-and-headers.md) | What the board puts in a visitor's browser and what it tells the browser to refuse: every cookie and why it exists, the nonce Content Security Policy, and the one environment variable that changes it. |
 | Configuration & guides | [`guides/operations/upgrading.md`](./docs/guides/operations/upgrading.md) | Moving a board between versions: the upgrade command, how far you can jump, and the behaviour changes each release brings. |
 | Configuration & guides | [`guides/operations/disaster-recovery.md`](./docs/guides/operations/disaster-recovery.md) | The runbook for the day the server is gone: what recovery consumes, the order of operations from provisioning to DNS, and the rehearsal that turns it from a hope into a plan. |
 | Configuration & guides | [`guides/operations/single-sign-on.md`](./docs/guides/operations/single-sign-on.md) | Two-factor authentication, federated sign-in and passkeys: what each means for your members, how to configure them, and the record of what has opened an account. |

apps/web/content/docs.manifest.json

@@ -198,6 +198,26 @@
       "primary": false,
       "group": "Running your community"
     },
+    {
+      "slug": "search",
+      "file": "guides/community/search.md",
+      "section": "guides",
+      "title": "Search",
+      "blurb": "The four controls over the most expensive thing a visitor can ask for: switching search off without losing the index, the shortest word a query may rest on, and the two different limits on how often.",
+      "generated": false,
+      "primary": false,
+      "group": "Running your community"
+    },
+    {
+      "slug": "word-filter",
+      "file": "guides/community/word-filter.md",
+      "section": "guides",
+      "title": "The word filter",
+      "blurb": "Rewriting words as a page renders, never in the stored post: what a rule is, why a pattern is a literal rather than a wildcard, and exactly which surfaces it covers.",
+      "generated": false,
+      "primary": false,
+      "group": "Running your community"
+    },
     {
       "slug": "operating",
       "file": "guides/operations/operating.md",
@@ -218,6 +238,16 @@
       "primary": false,
       "group": "Operating the server"
     },
+    {
+      "slug": "cookies-and-headers",
+      "file": "guides/operations/cookies-and-headers.md",
+      "section": "guides",
+      "title": "Cookies and security headers",
+      "blurb": "What the board puts in a visitor's browser and what it tells the browser to refuse: every cookie and why it exists, the nonce Content Security Policy, and the one environment variable that changes it.",
+      "generated": false,
+      "primary": false,
+      "group": "Operating the server"
+    },
     {
       "slug": "upgrading",
       "file": "guides/operations/upgrading.md",

docs/README.md

@@ -37,11 +37,14 @@ Running your community — browser only, no shell access:
 - [Groups and promotions](./guides/community/groups.md) — what a group carries board-wide.
 - [Spam controls and rate limits](./guides/community/antispam.md) — the registration challenge and every threshold.
 - [Reputation](./guides/community/reputation.md) — members rating each other, and the two settings that decide what a post offers.
+- [Search](./guides/community/search.md) — switching it off without losing the index, and the two limits on how often.
+- [The word filter](./guides/community/word-filter.md) — rewriting words at render time, and exactly which surfaces it covers.
 
 Operating the server:
 
 - [Operations](./guides/operations/operating.md) — health checks, configuration, CLI commands, mail, backups, and troubleshooting.
 - [Monitoring & alerting](./guides/operations/monitoring.md) — liveness versus readiness, metrics, tracing, and logs.
+- [Cookies and security headers](./guides/operations/cookies-and-headers.md) — every cookie the board sets, and the Content Security Policy.
 - [Upgrading](./guides/operations/upgrading.md) — move between released versions safely.
 - [Disaster recovery](./guides/operations/disaster-recovery.md) — restore a board when the original server is unavailable.
 - [Signing in](./guides/operations/single-sign-on.md) — passwords, two-factor authentication, federated sign-in, passkeys, and sessions.

docs/guides/community/moderation-guide.md

@@ -248,12 +248,13 @@ system working, not a gap in your permissions.
 Two things do quiet work beside you, and neither needs anything from
 you day to day:
 
-- **The word filter** rewrites listed words wherever a post is shown —
-  thread pages, excerpts, feeds, search results — without ever changing
-  what is stored. You see the original in the queue and on the report
-  screens, because you are judging the words. Adding to the filter is
-  the administrator's job, and a change applies everywhere on the next
-  page load.
+- **[The word filter](./word-filter.md)** rewrites listed words as a
+  page renders — post bodies, excerpts, feeds and search results —
+  without ever changing what is stored. **It does not cover thread
+  titles**, so a title is a rename rather than a filter rule. You see
+  the original in the queue and on the report screens, because you are
+  judging the words. Adding to the filter is the administrator's job,
+  and a change applies everywhere on the next page load.
 - **Reputation** lets members rate each other's posts — a thanks button
   by default, and a rating form if the board allows rating down. New
   members must post a few times before they may rate, which keeps it

docs/guides/community/search.md

@@ -0,0 +1,72 @@
+# Search
+
+Search is the most expensive thing a visitor can ask a board to do, and
+on a busy board it is the first thing to misbehave. This page is the
+four controls over it and what each is actually worth.
+
+Three live under `/admin/settings?group=search`. The fourth is a rate
+limit and sits with the [spam controls](./antispam.md).
+
+## Switching search off
+
+**Enable search** does four things at once, and the fourth is the one
+that makes it a safe thing to try:
+
+- The **Search link leaves the board navigation**.
+- **`/search`**, and any results page still linked to, is replaced with a
+  line saying search is off.
+- **`GET /api/v1/search` answers 403.** An API token is not a way round
+  the setting.
+- **The index is kept, and goes on being maintained.** Posts written
+  while search is off are still indexed.
+
+That last point is why this is reversible at no cost: switching it back
+on needs no reindex and loses nothing. It is a reasonable thing to do
+for an afternoon while a board is under load.
+
+## The shortest word a search may rest on
+
+A search is refused unless **at least one of its words** is this long.
+The default is 2, so at 3 the search *a good post* runs and *a b c* does
+not.
+
+The short words are **not dropped**. They are still sent to the index,
+which decides for itself which of them carry no meaning. The setting is
+a floor on the query as a whole, not a filter on its words — it exists
+to refuse the searches that scan the most and mean the least.
+
+Raise it if the expensive searches on your board turn out to be short
+ones. Most boards never need to.
+
+## Two different limits on how often
+
+These are separate controls and they answer different problems. Setting
+one does nothing about the other.
+
+**The search flood interval** (`search` settings, 30 seconds by default)
+is the minimum gap between one member's searches. It is per member, it
+is about impatience, and a member who is over it is told how long to
+wait. A group with **bypass flood check** is not subject to it.
+
+**Searches per hour** (`antispam` settings, `0` — off — by default) is
+an hourly cap, and it is aimed at the visitor who is not a member at
+all. `0` means no cap rather than no searches, as everywhere else in
+those settings. See [Spam controls](./antispam.md) for how the hourly
+allowances work and what they cost a real visitor.
+
+If a board is struggling under search load, the hourly cap is usually
+the one to reach for. The flood interval slows a person down; the hourly
+cap is what stops a script.
+
+## What a result shows
+
+Search results carry an excerpt from the post, and **the excerpt has the
+[word filter](./word-filter.md) applied**. The thread title beside it
+does not — see that page for what the filter covers.
+
+Results obey permissions. The scope is built from the same forum
+audience the rest of the board uses, so a member never sees a hit in a
+forum they could not open. **Administrators and super moderators also
+see unapproved and deleted posts** in results, which is deliberate — it
+is how you find something that was hidden — and is worth knowing before
+you read a staff member's result count as the board's.

docs/guides/community/word-filter.md

@@ -0,0 +1,82 @@
+# The word filter
+
+The word filter rewrites words as a page is rendered. It is the board's
+way of taking the sting out of language without editing anybody's post
+or standing over the composer.
+
+`/admin/content` holds it, under **Word filters**. It is an
+administrator's control: a moderator's route to bad language is the
+warning ladder or a hidden post, not this screen.
+
+## What a rule is
+
+Three fields:
+
+- **The pattern** — the word to look for.
+- **The replacement** — what to put in its place. It may be empty,
+  which removes the word.
+- **Whole word** — on, the pattern only matches when it stands alone as
+  a word; off, it matches anywhere inside a longer one.
+
+Matching is **case-insensitive**, and the replacement is inserted
+exactly as you typed it. A rule with an empty pattern is ignored.
+
+> [!IMPORTANT]
+> **A pattern is a literal, not a pattern language.** Every character is
+> matched as itself — `*`, `?`, `.` and the rest are just those
+> characters. There are no wildcards and no regular expressions, so
+> `.*` matches the two characters `.` and `*` and nothing else. If you
+> want to catch several spellings of a word, that is several rules.
+
+**Whole word is the setting that surprises people.** With it off, a rule
+for `ass` rewrites the middle of *class*, *passage* and *assessment*.
+With it on, only the word on its own is touched. Leave it on unless you
+have a reason.
+
+## What it changes, and what it does not
+
+**The filter runs at render time. It never edits stored text.** The post
+in the database is exactly what its author typed, and removing a rule
+brings the original word back everywhere immediately. Nothing is
+destroyed, so a rule is never a decision you have to live with.
+
+Two consequences worth knowing:
+
+- **A member who quotes a filtered post gets the original word**, because
+  the quote is built from the stored text.
+- **The moderation queue deliberately shows text unfiltered** — you are
+  judging the words, so you see them. See
+  [the moderator's guide](./moderation-guide.md#the-approval-queue).
+
+The filter only touches the text a reader sees. It steps over HTML tags,
+so it never rewrites a link's address, a class name or an attribute — a
+rule for `cat` cannot break a link to `example.com/catalogue`.
+
+### Where it applies
+
+| Filtered | Not filtered |
+| --- | --- |
+| Post bodies | **Thread titles** |
+| Excerpts in the latest-posts lists | Signatures |
+| Search result excerpts, on the board and through the REST API | Custom profile fields |
+| Feed summaries (RSS and Atom) | Usernames |
+| The description in a page's metadata, which is what a link preview shows | |
+
+> [!WARNING]
+> **Thread titles are not filtered.** A filtered word in a title stays
+> visible in every forum listing, in search results beside a filtered
+> excerpt, and in the feed. If a title is the problem, rename the thread
+> — a moderator can — rather than expecting a rule to cover it. This is
+> a gap rather than a decision, and it is tracked.
+
+## What it costs
+
+Very little. The compiled rules are cached board-wide and rebuilt when
+you change one, and the substitution runs over text the board was
+rendering anyway. A long list of rules is fine; it is one pass per rule
+over the visible text of a page.
+
+The real cost is judgement. A filter that rewrites a word into a joke
+reads as the board making light of something a member was serious about,
+and members can tell the difference between a board that removed a slur
+and one that made a punchline of it.

docs/guides/operations/cookies-and-headers.md

@@ -0,0 +1,116 @@
+# Cookies and security headers
+
+What the board puts in a visitor's browser, and what it tells the
+browser to refuse. This is the page to read when somebody asks what you
+store about them, when a cookie banner is being drafted, or when
+something on the board is being blocked and you need to know by what.
+
+None of it is configurable from the admin panel. It is part of the
+software, and the one thing that changes it is an environment variable,
+named below.
+
+## The cookies
+
+**The board sets no third-party cookies, runs no analytics, and stores
+nothing for advertising.** Every cookie below is first-party, set by the
+board itself, and there to make a specific thing work.
+
+| Cookie | What it is for | Lifetime |
+| --- | --- | --- |
+| `fs_session` | The signed-in session | Until it expires or you sign out |
+| `fs_remember` | *Remember me* on the sign-in form | The remember period |
+| `fs_guest` | Counts one reader once, for "who's online" | 1 day |
+| `fs_admin` | Admin-panel re-authentication | The admin session |
+| `fs_2fa` | A sign-in that has given a password and owes a second factor | Short |
+| `fs_sso` | The single sign-on handshake | 10 minutes |
+| `fs_passkey` | The passkey exchange | Short |
+
+Every one is **`HttpOnly`** — script cannot read any of them — and every
+one is **`Secure`** wherever the board is served over HTTPS. Over HTTPS
+they also carry the **`__Host-` prefix** (`__Host-fs_session` and so on),
+which binds a cookie to the exact origin that set it and forbids a
+subdomain from writing it.
+
+`SameSite` differs by purpose, and the differences are deliberate:
+
+- **`Lax`** for the session, remember, guest and SSO cookies. The SSO
+  one has to be `Lax`: an identity provider returns the member with a
+  top-level navigation from another site, and a `Strict` cookie is not
+  sent on that request, so every federated sign-in would fail.
+- **`Strict`** for the admin, second-factor and passkey cookies. Nothing
+  in those exchanges ever starts on another site, so nothing is lost by
+  refusing to send them cross-site.
+
+The admin cookie is also **scoped to `/admin`**, so it is not sent with
+ordinary board requests at all.
+
+### The guest cookie, and what it is not
+
+`fs_guest` is the only cookie a visitor gets without signing in, and it
+exists for one figure: "37 guests reading". That number is not derivable
+from a stateless request — without something that comes back, every page
+view is a stranger.
+
+It is **an opaque random value and nothing else**. No code path turns it
+into an identity, and the session lookup refuses a row with no user
+behind it. The most it can say about the person holding it is that they
+were here. It lasts a day.
+
+Whether that needs consent where you operate is a question for you, not
+for this page — but "strictly necessary" is an argument you can actually
+make about it, which is not true of an analytics cookie.
+
+## The Content Security Policy
+
+Every page is served under a **nonce-based policy**, generated fresh per
+request:
+
+```
+default-src 'self';
+img-src 'self' data:;
+style-src 'self' 'unsafe-inline';
+script-src 'self' 'nonce-<per-request>' 'strict-dynamic';
+connect-src 'self'; worker-src 'self'; manifest-src 'self';
+frame-ancestors 'self'; object-src 'none';
+base-uri 'self'; form-action 'self'
+```
+
+What that means in practice:
+
+- **An injected `<script>` does not run.** It has no nonce, and
+  `'strict-dynamic'` means the browser trusts scripts the board's own
+  nonced scripts load, and nothing else.
+- **Nothing loads from another origin** — no CDN, no font host, no
+  embedded widget. A theme or plugin that reaches for one will be
+  blocked, and the browser console will say so.
+- **`form-action 'self'`** means a form on your board cannot be made to
+  post somewhere else.
+- **`frame-ancestors 'self'`** means the board cannot be framed by
+  another site.
+
+**One environment variable changes it.** `REMOTE_IMAGES=1` adds `https:`
+to `img-src`, which is what lets members hotlink images from elsewhere.
+It is off by default: allowing remote images means every post can make a
+reader's browser fetch from a third party, which leaks the reader's IP
+address to whoever hosts it.
+
+The e2e suite asserts that every page carries the policy **and that
+nothing on the page is refused under it**, so a change that would have
+needed `unsafe-inline` fails before it ships.
+
+## The other headers
+
+Sent on every response:
+
+| Header | Value | What it stops |
+| --- | --- | --- |
+| `X-Content-Type-Options` | `nosniff` | A browser guessing a type and running an upload as script |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` | A full path leaking to another site |
+| `Strict-Transport-Security` | `max-age=63072000` | A downgrade to HTTP for two years |
+| `X-Frame-Options` | `SAMEORIGIN` | Framing, for browsers older than `frame-ancestors` |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` | Anything asking for hardware the board never uses |
+
+If you terminate TLS at a reverse proxy, it has to pass these through
+rather than replace them — see
+[Docker Compose](../../getting-started/deployment/docker-compose.md) for
+the CSP note on proxying.