mgmt: greeting + self-serve help should link the instance user guide (docs_url) #92

New issue

Closed

opened 2026-07-11 22:58:49 +00:00 by robocub · 1 comment

robocub commented

2026-07-11 22:58:49 +00:00

Collaborator

UX gap found while assessing the cold-DM experience (2026-07-11).

A user who discovers the bot cold (bot MXID shared in a chat, seen in a room, etc.) and DMs it gets:

👋 Voice bridge management — send help for commands.

and help returns the command grammar — which is good — but neither message links the actual walkthrough (for nether.im: https://nether.wiki/matrix/voice-bridge/). The grammar alone assumes the user already knows how to find Discord guild/channel IDs, the Matrix internal room ID, and that the puppet bots must be invited first (the invite URLs are ONLY discoverable via the docs). Users arriving from the wiki are fine; users arriving from the bot are stranded one step before success.

Proposal: optional [management] docs_url config knob (exactly like privacy_policy_url, which already exists and is appended to disclosure replies via policy_line()):

appended to the DM greeting: 👋 Voice bridge management — send help for commands. Guide: <docs_url>
appended to SELF_SERVE_HELP_TEXT (and probably HELP_TEXT)
prod config sets it to the wiki guide URL

Tiny change, all in crates/matrix-rtc/src/mgmt.rs + nvb_config; the e2e mgmt_self_serve_link step-1 help assertion may need the harness config to set (or not set) the knob.

Related: #80 shipped the same pattern for approval_bot_name.

**UX gap found while assessing the cold-DM experience (2026-07-11).** A user who discovers the bot cold (bot MXID shared in a chat, seen in a room, etc.) and DMs it gets: > 👋 Voice bridge management — send `help` for commands. and `help` returns the command grammar — which is good — but neither message links the actual walkthrough (for nether.im: https://nether.wiki/matrix/voice-bridge/). The grammar alone assumes the user already knows how to find Discord guild/channel IDs, the Matrix internal room ID, and that the puppet bots must be invited first (the invite URLs are ONLY discoverable via the docs). Users arriving from the wiki are fine; users arriving from the bot are stranded one step before success. **Proposal:** optional `[management] docs_url` config knob (exactly like `privacy_policy_url`, which already exists and is appended to disclosure replies via `policy_line()`): - appended to the DM greeting: `👋 Voice bridge management — send help for commands. Guide: <docs_url>` - appended to `SELF_SERVE_HELP_TEXT` (and probably `HELP_TEXT`) - prod config sets it to the wiki guide URL Tiny change, all in `crates/matrix-rtc/src/mgmt.rs` + `nvb_config`; the e2e `mgmt_self_serve_link` step-1 help assertion may need the harness config to set (or not set) the knob. Related: #80 shipped the same pattern for `approval_bot_name`.

robocub referenced this issue from a commit

2026-07-11 23:20:35 +00:00

feat(mgmt): #92 docs_url — link the user guide from the bot's replies

robocub commented

2026-07-12 00:19:57 +00:00

Author

Collaborator

Shipped in v0.3.0-alpha.22 and deployed to prod 2026-07-12.

[management] docs_url (mirrors privacy_policy_url / policy_line()): a Guide: <url> line is appended to the DM greeting, help (both tiers), the pending-approval reply, and the errors whose fix the guide explains (room-id/snowflake shape, the call.member power-level probe). The greeting also now says what the bot does.
Bonus fixes: the snowflake error pointed at "Server Settings" for Developer Mode (it lives under User Settings → Advanced); the room-id error now says where Element shows the internal ID.
Verification: runner clippy clean + tests green (config 80 / matrix-rtc 112 incl. new docs_line unit / e2e 20); live mgmt_self_serve_link PASS 60.5s on staging with docs_url set in the harness (all reply asserts matched with the appended line; 0 ERROR). Prod deploy: deb sha-verified, config gained docs_url = https://nether.wiki/matrix/voice-bridge/ (backup taken), clean restart — management bot ready, 0 ERROR, all device ids reused.
e2e harness now sets docs_url, so the live scenario exercises it permanently.

Shipped in **v0.3.0-alpha.22** and deployed to prod 2026-07-12. - `[management] docs_url` (mirrors `privacy_policy_url` / `policy_line()`): a `Guide: <url>` line is appended to the DM greeting, `help` (both tiers), the pending-approval reply, and the errors whose fix the guide explains (room-id/snowflake shape, the `call.member` power-level probe). The greeting also now says what the bot does. - Bonus fixes: the snowflake error pointed at "Server Settings" for Developer Mode (it lives under **User** Settings → Advanced); the room-id error now says where Element shows the internal ID. - Verification: runner clippy clean + tests green (config 80 / matrix-rtc 112 incl. new `docs_line` unit / e2e 20); live `mgmt_self_serve_link` PASS 60.5s on staging with `docs_url` set in the harness (all reply asserts matched with the appended line; 0 ERROR). Prod deploy: deb sha-verified, config gained `docs_url = https://nether.wiki/matrix/voice-bridge/` (backup taken), clean restart — `management bot ready`, 0 ERROR, all device ids reused. - e2e harness now sets `docs_url`, so the live scenario exercises it permanently.

robocub closed this issue

2026-07-12 00:19:57 +00:00

robocub referenced this issue

2026-07-12 05:38:00 +00:00

mgmt: tutorial command — guided, illustrated walkthrough over DM; unknown input should offer it #102