docs: record the Devdesk hookshot webhook

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jared Vititoe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -352,6 +352,8 @@ Webhook URL format: `https://matrix.lotusguild.org/webhook/<uuid>`
 | Owncast (Livestream) | `9993e911-c68b-4271-a178-c2d65ca88499` | STREAM_STARTED / STREAM_STOPPED |
 | Bazarr | `470fb267-3436-4dd3-a70c-e6e8db1721be` | Subtitle events (Apprise JSON notifier) |
 | Tinker-Tickets | `6e306faf-8eea-4ba5-83ef-bf8f421f929e` | Custom transformation code |
+| Ci-Alert | `5e7051e7-fd0c-4930-a711-9c67daf6f0b9` | Gitea Actions `notify-failure` jobs (org secret `MATRIX_WEBHOOK_URL`); transform `hookshot/ci-alert.js` |
+| Devdesk | `4a3ccfc9-e1fe-4124-b014-7842fe51b9dc` | DevDesk "Claude needs you" (CT 126 `devdesk-notify-matrix`, URL in `/etc/devdesk/matrix-webhook`); transform `hookshot/devdesk.js`; avatar set via the appservice token |
 
 **Hookshot notes:**
 - Spam and Stuff is intentionally **unencrypted** — hookshot bridges cannot join E2EE rooms
@@ -361,6 +363,7 @@ Webhook URL format: `https://matrix.lotusguild.org/webhook/<uuid>`
 - NPM proxies `/sfu/get` and `/get_token` → `http://10.10.10.29:8070` (lk-jwt-service). Both paths are in `/data/nginx/proxy_host/49.conf` on LXC 139 — **NPM will overwrite these if proxy host 49 is re-saved via the UI; re-add both location blocks after any NPM save**
 - Proxmox sends Discord embed format: `data.embeds[0].{title,description,fields}` — NOT flat fields
 - Transform functions are stored as Matrix room state (`uk.half-shot.matrix-hookshot.generic.hook`) and deployed via `hookshot/deploy.sh`
+- Hook UUIDs are **not** in that state. Hookshot creates them and keeps a `{uuid: name}` map in the `@hookshot` bot's room account data (same event type). Deploying a new transform creates the hook. To look a UUID up on LXC 151, use the appservice token from `/etc/matrix-synapse/hookshot-registration.yaml`: `GET /_matrix/client/v3/user/@hookshot:matrix.lotusguild.org/rooms/<room>/account_data/uk.half-shot.matrix-hookshot.generic.hook?user_id=@hookshot:matrix.lotusguild.org`
 
 **Deploying hookshot transforms manually:**
 ```bash

hookshot/devdesk.js

@@ -0,0 +1,19 @@
+// DevDesk "Claude needs you" (devdesk#28)
+// Receives: { session, message, url, host, text } from devdesk-notify-matrix on
+// CT 126 when a Claude session waits for input and no browser tab or SSH client
+// is attached to it.
+var session = String(data.session || 'a session');
+var message = String(data.message || 'Claude is waiting for your input');
+var url = data.url ? String(data.url) : '';
+function esc(t) {
+  return t.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+// m.text, not m.notice: notices are muted by default push rules, and this one
+// exists to reach your phone.
+result = {
+  version: 'v2',
+  plain: '🔔 Claude needs you in ' + session + ': ' + message + (url ? ' — ' + url : ''),
+  html: '🔔 <b>Claude needs you</b> in <code>' + esc(session) + '</code>: ' + esc(message)
+    + (url ? ' — <a href="' + esc(url) + '">open in DevDesk</a>' : ''),
+  msgtype: 'm.text',
+};