diff --git a/apps/bugsink/README.md b/apps/bugsink/README.md
index 34eb07925..9d902e665 100644
--- a/apps/bugsink/README.md
+++ b/apps/bugsink/README.md
@@ -38,6 +38,14 @@ move across with `bugsink-manage migrate_to_current_objectstorage`.
 The R2 credentials also live on the `bugsink-r2` item in the `vers` 1Password vault. Unset the four
 `R2_*` secrets and Bugsink falls back to storing files in the database.
 
+## Alerts
+
+New-issue, regression, and unmute alerts post to the alarms Discord channel: every project carries a
+Discord messaging-service config pointing at the channel's incoming webhook (the
+`bugsink-discord-webhook` item in the `vers` 1Password vault), and a new project gets the same
+webhook added in its settings. No outgoing email is configured — alerting is webhook-only, and
+per-project alert toggles live in each Bugsink project's settings.
+
 ## Housekeeping
 
 The `.github/workflows/bugsink-vacuum.yml` workflow runs `bugsink-manage vacuum_files` monthly (and
diff --git a/docs/architecture/deployment.md b/docs/architecture/deployment.md
index 0cbd14284..6b323149b 100644
--- a/docs/architecture/deployment.md
+++ b/docs/architecture/deployment.md
@@ -291,7 +291,9 @@ fly secrets unset CREATE_SUPERUSER -a vers-bugsink
 
 In the Bugsink UI, create one project per app, set each project's DSN as that app's `SENTRY_DSN`
 secret, and set the web project's DSN as the `VITE_SENTRY_DSN` GitHub Actions variable plus a
-`vers-app-web` secret of the same name. Mint an API token for CI source-map uploads
+`vers-app-web` secret of the same name. Add the alarms Discord webhook (the
+`bugsink-discord-webhook` item in the `vers` 1Password vault) as each project's messaging service,
+so new-issue alerts reach the alarms channel. Mint an API token for CI source-map uploads
 (`SENTRY_AUTH_TOKEN` GitHub secret) and one for the MCP server, added to the vault item as
 `mcp-token`.