docs: refresh docs for 3.2.0 — correct stale content, document recent features

[JohnMcLear]

Why

The docs under doc/ are hand-authored VitePress markdown (not generated from the OpenAPI spec — openapi.ts only builds the runtime Swagger definition and never reads/writes doc/), so they need manual upkeep and had drifted behind a lot of recent work. This pass corrects content that was actively wrong and documents features shipped since the pages were last touched. Every change was verified against source.

Corrections (was wrong / would mislead)

• cli.md — every command said node bin/foo.js, but the scripts are TypeScript run via pnpm; copy-paste failed. Rewrote to pnpm run --filter bin <script>, documented ~13 previously-undocumented operator tools, and split running-vs-stopped requirements. Registered the missing compactStalePads entry in bin/package.json so the documented command actually runs.
• stats.md — described a pre-Prometheus world. Rewrote for the enableMetrics-gated /stats (JSON) and /stats/prometheus endpoints, the live metric set, the opt-in scalingDiveMetrics instruments (Performance: Look deeper into scaling N+ contributors per pad. #7756), and the measured-core library.
• admin/updates.md — removed three false "SMTP not yet wired / would send email" claims (it is wired via nodemailer + the new mail.* block), documented the node-engine-mismatch preflight check and the rollback/preflight failure emails, and stripped obsolete "PR 1 / PR 2" staging language now that all tiers ship.
• api/http_api.md — added the undocumented anonymizeAuthor (GDPR Art. 17) call, fixed copyPad/movePad version annotations (1.2.8 → 1.2.9), corrected getPadID's param name (readOnlyID → roID), and dropped a reference to a non-existent getEtherpad API call.
• skins.md — colibris is the current default, not "experimental, will become default in 2.0".
• localization.md — bare window._('key') is unbound and returns undefined; recommend window.html10n.get(...) / data-l10n-id.
• README.md — bumped the v2.2.5 upgrade example to v3.2.0; fixed a docker.adoc link to docker.md.
• docker.md — added MAIL_*, ENABLE_METRICS, GDPR_AUTHOR_ERASURE_ENABLED, PRIVACY_BANNER_*, PUBLIC_URL, AUTHENTICATION_METHOD, ENABLE_DARK_MODE, ENABLE_PAD_WIDE_SETTINGS; fixed the SOCKETIO_MAX_HTTP_BUFFER_SIZE default (50000 → 1000000).

New documentation

• configuration.md (new) — how settings + ${VAR:default} substitution work, trustProxy, and the previously-undocumented subpath / ingress support (x-proxy-path / X-Forwarded-Prefix / X-Ingress-Path), including the sanitizer rules and Traefik/NGINX examples. Wired into the sidebar and index hero.
• hooks_server-side.md — ccRegisterBlockElements (the server-side companion plugin authors miss), exportConvert, exportHTMLSend, createServer, restartServer, clientReady (deprecated).
• hooks_client-side.md — aceDrop, acePaste, handleClientTimesliderMessage_<name>.

Notes / follow-ups (not in this PR)

• .adoc left in place. It looked like a dead duplicate, but bin/release.ts still runs makeDocs (asciidoctor) and copies the output into ether.github.com/public/doc/v<version> — i.e. it feeds the per-version doc archives at release time. Deciding its fate (migrate the archive to VitePress vs keep) is a separate change.
• src/node/metrics.ts appears to be dead code (never imported/registered), so its gauges are intentionally not documented in stats.md. Worth wiring up or removing in a follow-up.

Test

VitePress build passes locally (pnpm run docs:build), including the dead-link check.

🤖 Generated with Claude Code

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Refresh documentation for 3.2.0: correct stale content and document recent features

📝 Documentation

Walkthroughs

Description

• Corrected stale CLI documentation: rewrote commands from node bin/foo.js to `pnpm run --filter
  bin `, documented ~13 previously-undocumented operator tools, and registered missing
  compactStalePads script in bin/package.json
• Rewrote stats documentation for Prometheus-era metrics: documented /stats (JSON) and
  /stats/prometheus endpoints, live metric set, opt-in scalingDiveMetrics instruments, and
  measured-core library
• Corrected admin/updates documentation: removed three false "SMTP not yet wired" claims, documented
  mail.* SMTP block, node-engine-mismatch preflight check, and rollback/preflight failure emails
• Added new configuration.md documenting settings substitution, trustProxy, and subpath/ingress
  support with Traefik/NGINX examples
• Enhanced API documentation: added undocumented anonymizeAuthor (GDPR Art. 17) call, fixed
  copyPad/movePad version annotations, corrected getPadID parameter name, and removed reference
  to non-existent getEtherpad call
• Documented previously-missing server-side hooks (ccRegisterBlockElements, exportConvert,
  exportHTMLSend, createServer, restartServer, clientReady) and client-side hooks (aceDrop,
  acePaste, handleClientTimesliderMessage_)
• Updated Docker environment variables: added MAIL_*, ENABLE_METRICS,
  GDPR_AUTHOR_ERASURE_ENABLED, PRIVACY_BANNER_*, PUBLIC_URL, AUTHENTICATION_METHOD,
  ENABLE_DARK_MODE, ENABLE_PAD_WIDE_SETTINGS, and fixed SOCKETIO_MAX_HTTP_BUFFER_SIZE default
  (50000 → 1000000)
• Fixed miscellaneous stale content: bumped upgrade example from v2.2.5 to v3.2.0, corrected
  docker.adoc link to docker.md, updated skins.md (colibris is current default), and fixed
  localization.md guidance on window._() binding issue

Diagram

flowchart LR
  A["Hand-authored VitePress docs<br/>drifted behind recent work"] -->|"Corrections:<br/>CLI, stats, updates,<br/>API, skins, localization"| B["Accurate docs<br/>reflecting current state"]
  A -->|"New pages:<br/>configuration.md<br/>with subpath/ingress"| C["Expanded documentation<br/>coverage"]
  A -->|"New hooks:<br/>server-side & client-side"| D["Complete hook<br/>reference"]
  A -->|"Docker env vars<br/>& settings"| E["Comprehensive<br/>deployment guide"]
  B --> F["VitePress build passes<br/>with dead-link check"]
  C --> F
  D --> F
  E --> F

Loading

File Changes

1. README.md 📝 Documentation +3/-3

Updated upgrade example and docker link

README.md

---

2. bin/package.json ⚙️ Configuration changes +1/-0

Registered missing compactStalePads script

bin/package.json

---

3. doc/.vitepress/config.mts 📝 Documentation +1/-0

Added Configuration page to sidebar

doc/.vitepress/config.mts

---

View more (11)

4. doc/admin/updates.md 📝 Documentation +34/-7

Documented SMTP, preflight checks, and email outcomes

doc/admin/updates.md

---

5. doc/api/hooks_client-side.md 📝 Documentation +42/-0

Added aceDrop, acePaste, handleClientTimesliderMessage hooks

doc/api/hooks_client-side.md

---

6. doc/api/hooks_server-side.md 📝 Documentation +96/-0

Added ccRegisterBlockElements, exportConvert, exportHTMLSend, createServer, restartServer, clientReady hooks

doc/api/hooks_server-side.md

---

7. doc/api/http_api.md 📝 Documentation +17/-5

Added anonymizeAuthor, fixed version annotations and parameter names

doc/api/http_api.md

---

8. doc/cli.md 📝 Documentation +105/-22

Rewrote CLI commands and documented ~13 operator tools

doc/cli.md

---

9. doc/configuration.md 📝 Documentation +143/-0

New page documenting settings, trustProxy, and subpath/ingress

doc/configuration.md

---

10. doc/docker.md 📝 Documentation +32/-1

Added MAIL_*, ENABLE_METRICS, GDPR, PRIVACY_BANNER, and other env vars

doc/docker.md

---

11. doc/index.md 📝 Documentation +3/-0

Added Configuration link to hero section

doc/index.md

---

12. doc/localization.md 📝 Documentation +15/-1

Corrected window._() binding issue and recommended html10n.get()

doc/localization.md

---

13. doc/skins.md 📝 Documentation +3/-3

Updated colibris as current default, not experimental

doc/skins.md

---

14. doc/stats.md 📝 Documentation +143/-14

Rewrote for Prometheus endpoints, metrics, and scalingDiveMetrics

doc/stats.md

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0)

1. Nonexistent server.js example ✓ Resolved 🐞 Bug ≡ Correctness

Description

doc/configuration.md documents overriding settings via node src/node/server.js --settings ...,
but this repo runs src/node/server.ts via the tsx loader, so the documented command will fail if
copy/pasted.

Code

doc/configuration.md[R14-15]

Evidence

The docs suggest running src/node/server.js, but the repo’s start scripts run node/server.ts
with node --require tsx/cjs, and the actual entry file present is src/node/server.ts. This makes
the documented example inconsistent with the actual run path.

doc/configuration.md[14-16]
src/package.json[150-157]
src/node/server.ts[1-3]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`doc/configuration.md` shows an example command that references `src/node/server.js`, which is not the entrypoint used by this repo.
## Issue Context
The runtime entrypoint is `src/node/server.ts` and the package scripts execute it with `tsx`.
## Fix Focus Areas
- doc/configuration.md[14-16]
- src/package.json[150-157]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. CLI help references .js ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The new compactStalePads pnpm script runs compactStalePads.ts via tsx, but the script’s own
usage text still instructs node bin/compactStalePads.js ..., which points users to a non-existent
.js file.

Code

bin/package.json[27]

Evidence

The pnpm script runs the TypeScript file via node --import tsx ..., and the docs instruct `pnpm
run --filter bin compactStalePads ..., but the script’s usage output still tells users to run node
bin/compactStalePads.js`, which does not match how the repo is set up.

bin/package.json[21-29]
bin/compactStalePads.ts[256-261]
doc/cli.md[70-75]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `compactStalePads` CLI is now exposed as a pnpm script that executes a `.ts` file via `tsx`, but `bin/compactStalePads.ts` still prints `.js`-based usage instructions.
## Issue Context
Docs now instruct users to run these tools via `pnpm run --filter bin ...`, so the CLI’s help text should match.
## Fix Focus Areas
- bin/compactStalePads.ts[256-261]
- bin/package.json[21-29]
- doc/cli.md[70-75]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[JohnMcLear]

Thanks @qodo — both addressed in 08808b2:

1. Nonexistent server.js — configuration.md now documents the supported launcher bin/run.sh -s <file> (forwards to pnpm run prod) and notes the runtime is src/node/server.ts via tsx; there is no server.js.
2. CLI help references .js — fixed the header comments and runtime usage output in compactStalePads.ts, and also compactPad.ts / compactAllPads.ts for consistency, to the documented pnpm run --filter bin <script> form.