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

New issue

Open

opened 2026-07-12 05:38:00 +00:00 by robocub · 0 comments

robocub commented

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

Collaborator

Operator suggestion (2026-07-12, straight from watching two real first-time users struggle):

1. Unknown input offers the tutorial. Today a non-command in a DM gets Unrecognized command — send help for the command list. — accurate, unhelpful to a newcomer. Change to something like: I didn't recognize that. New here? Send tutorial for a guided walkthrough, or help for the command list. (Keep the silent-outside-DMs contract untouched.)

2. tutorial = a complete, illustrated, step-by-step walkthrough delivered as a sequence of DMs with attached pictures. Proposed shape:

Stepped, not a wall of text: tutorial starts a small per-room state machine — one step per message, advance with next (plus stop to bail; state in-memory like pending_announce). A newcomer reads one screen at a time.
Steps ≈ (1) what the bridge does + what you'll need (Matrix room you moderate, Discord server with Manage Server, ~2 min); (2) prepare the Matrix room — Element Call once / the power-level trap, WITH the #98 screenshots; (3) invite the puppet bots to the Discord server (invite links via docs_url instance page); (4) find your IDs — Discord Developer Mode → Copy Server/Channel ID (screenshot), Element → Settings → Advanced → internal room ID (screenshot); (5) compose the link command — templated example they can copy-edit; (6) the approval — someone with Manage Server runs /bridge approve code:… (screenshot of the slash command); (7) done — list, unlink, report, the help room, the open-beta note.
Pictures: m.image attachments. Assets live in the repo (docs/images/tutorial/), uploaded to the media repo lazily on first use and the mxc:// URIs cached (per-process is fine). E2EE DMs need encrypted attachments — use the SDK's send_attachment (it handles EncryptedFile in encrypted rooms; plain m.image with a naked mxc leaks in an E2EE room and some clients refuse to render it). The E2EE-DM path is live-proven as of tonight, so this must work encrypted from day one.
Config: reuse docs_url/instance_notice; tutorial text should be instance-agnostic with the instance specifics (invite links page, help room) injected from config.

Asset overlap: the 3 screenshots in #98 are a strict subset of the tutorial's shot list — take them once, use in docs AND tutorial. Full tutorial shot list: the #98 three + Discord Developer Mode toggle, Copy Server ID / Copy Channel ID context menus, Element internal-room-ID panel, /bridge approve in Discord, and a finished bridged call side-by-side (the README hero shot works).

Testing: e2e extension of the mgmt scenario (or its own): tutorial → step markers arrive in order → next advances → stop halts; assert image events present (content type, not pixels). Unknown-input reply asserts the new wording (heads-up: mgmt_self_serve_link does NOT currently assert the unrecognized-command text, so the wording change is regression-safe, but double-check at build time).

Related: #92 (docs_url plumbing), #98 (screenshots), #101 (invite-flow politeness — same spirit: the bot should never leave a newcomer at a dead end).

Operator suggestion (2026-07-12, straight from watching two real first-time users struggle): **1. Unknown input offers the tutorial.** Today a non-command in a DM gets `Unrecognized command — send help for the command list.` — accurate, unhelpful to a newcomer. Change to something like: `I didn't recognize that. New here? Send tutorial for a guided walkthrough, or help for the command list.` (Keep the silent-outside-DMs contract untouched.) **2. `tutorial` = a complete, illustrated, step-by-step walkthrough delivered as a sequence of DMs with attached pictures.** Proposed shape: - **Stepped, not a wall of text**: `tutorial` starts a small per-room state machine — one step per message, advance with `next` (plus `stop` to bail; state in-memory like pending_announce). A newcomer reads one screen at a time. - **Steps ≈** (1) what the bridge does + what you'll need (Matrix room you moderate, Discord server with Manage Server, ~2 min); (2) prepare the Matrix room — Element Call once / the power-level trap, WITH the #98 screenshots; (3) invite the puppet bots to the Discord server (invite links via `docs_url` instance page); (4) find your IDs — Discord Developer Mode → Copy Server/Channel ID (screenshot), Element → Settings → Advanced → internal room ID (screenshot); (5) compose the `link` command — templated example they can copy-edit; (6) the approval — someone with Manage Server runs `/bridge approve code:…` (screenshot of the slash command); (7) done — `list`, `unlink`, `report`, the help room, the open-beta note. - **Pictures**: `m.image` attachments. Assets live in the repo (`docs/images/tutorial/`), uploaded to the media repo lazily on first use and the `mxc://` URIs cached (per-process is fine). **E2EE DMs need encrypted attachments** — use the SDK's `send_attachment` (it handles `EncryptedFile` in encrypted rooms; plain `m.image` with a naked mxc leaks in an E2EE room and some clients refuse to render it). The E2EE-DM path is live-proven as of tonight, so this must work encrypted from day one. - **Config**: reuse `docs_url`/`instance_notice`; tutorial text should be instance-agnostic with the instance specifics (invite links page, help room) injected from config. **Asset overlap**: the 3 screenshots in #98 are a strict subset of the tutorial's shot list — take them once, use in docs AND tutorial. Full tutorial shot list: the #98 three + Discord Developer Mode toggle, Copy Server ID / Copy Channel ID context menus, Element internal-room-ID panel, `/bridge approve` in Discord, and a finished bridged call side-by-side (the README hero shot works). **Testing**: e2e extension of the mgmt scenario (or its own): `tutorial` → step markers arrive in order → `next` advances → `stop` halts; assert image events present (content type, not pixels). Unknown-input reply asserts the new wording (heads-up: `mgmt_self_serve_link` does NOT currently assert the unrecognized-command text, so the wording change is regression-safe, but double-check at build time). Related: #92 (docs_url plumbing), #98 (screenshots), #101 (invite-flow politeness — same spirit: the bot should never leave a newcomer at a dead end).