Docs: self-serve DM registration walkthrough + Matrix-side registration-code flow #75

New issue

Open

opened 2026-07-10 23:21:38 +00:00 by robocub · 0 comments

robocub commented

2026-07-10 23:21:38 +00:00

Collaborator

User-facing documentation for bridging a room by DMing the management bot — the self-serve link flow — plus the Matrix-side onboarding docs (getting a nether.im invite code and how to get/use registration/approval codes).

Gap

The mechanism is documented for operators (README "Runtime bridges & the management bot" / "Two-sided link auth" / "Open registration"), and the bot self-documents via help. But there is no end-user walkthrough for someone bridging their own room over DM. docs/hosted-instance.md (shipped in #58) explicitly defers this: it notes the page "will gain a self-serve DM flow once open registration is turned on," and until then points people to request bridges by hand. This is a launch dependency for open registration.

Scope

On nether.codes (this repo's docs/):

A user-facing "bridge your room over DM" walkthrough: DM the bridge bot, run link <name> <matrix-room-id> <discord-guild-id> <discord-channel-id>, the room prerequisites (PL-0 for org.matrix.msc3401.call.member, invite for restricted rooms, puppet bots in the guild), and the two-sided consent path.
The registration/approval-code flow, step by step: a link that passes the probes is held pending and answered with a one-time code; someone with Manage Server on the target Discord guild runs /bridge approve code:<code> within the timeout. Document where the code comes from, who can approve, the timeout, and what both sides see on success/failure.
Getting a nether.im account — the homeserver is invite-code-gated; document how to obtain an invite code and who to ask. (Note: a federated Matrix user can also DM the bot without a nether.im-local account — cover both paths.)
unlink / list scoping for self-serve users, and the per-owner tenant limit.
Un-defer the docs/hosted-instance.md self-serve section once open registration is live in prod.

On nether.wiki (nether.codes/nether/wiki — git-backed markdown, edit + push updates the wiki; see #3):

Extend the Matrix-side documentation set to cover the same self-serve/registration-code flow and the invite-code onboarding for a general Matrix audience (not just self-hosters reading this repo).

Dependencies / cross-refs

Gated on open registration being enabled in prod (the #47 require_room_authority / require_discord_approval / open_registration knobs are shipped but currently OFF).
Related: #58 (deferred the DM flow), #3 (NetherWiki docs), #43 (public instance), #47 (multi-tenant hardening), #76 (live-validate the auth path first).

User-facing documentation for bridging a room by **DMing the management bot** — the self-serve `link` flow — plus the Matrix-side onboarding docs (**getting a nether.im invite code** and **how to get/use registration/approval codes**). ## Gap The mechanism is documented for operators (README "Runtime bridges & the management bot" / "Two-sided link auth" / "Open registration"), and the bot self-documents via `help`. But there is **no end-user walkthrough** for someone bridging their own room over DM. `docs/hosted-instance.md` (shipped in #58) explicitly **defers** this: it notes the page "will gain a self-serve DM flow once open registration is turned on," and until then points people to request bridges by hand. This is a launch dependency for open registration. ## Scope **On nether.codes (this repo's `docs/`):** - [ ] A user-facing "bridge your room over DM" walkthrough: DM the bridge bot, run `link <name> <matrix-room-id> <discord-guild-id> <discord-channel-id>`, the room prerequisites (PL-0 for `org.matrix.msc3401.call.member`, invite for restricted rooms, puppet bots in the guild), and the two-sided consent path. - [ ] **The registration/approval-code flow, step by step:** a `link` that passes the probes is held pending and answered with a one-time code; someone with **Manage Server** on the target Discord guild runs `/bridge approve code:<code>` within the timeout. Document where the code comes from, who can approve, the timeout, and what both sides see on success/failure. - [ ] **Getting a nether.im account** — the homeserver is **invite-code-gated**; document how to obtain an invite code and **who to ask**. (Note: a federated Matrix user can also DM the bot without a nether.im-local account — cover both paths.) - [ ] `unlink` / `list` scoping for self-serve users, and the per-owner tenant limit. - [ ] Un-defer the `docs/hosted-instance.md` self-serve section once open registration is live in prod. **On nether.wiki (`nether.codes/nether/wiki` — git-backed markdown, edit + push updates the wiki; see #3):** - [ ] Extend the Matrix-side documentation set to cover the same self-serve/registration-code flow **and the invite-code onboarding** for a general Matrix audience (not just self-hosters reading this repo). ## Dependencies / cross-refs - Gated on **open registration being enabled in prod** (the #47 `require_room_authority` / `require_discord_approval` / `open_registration` knobs are shipped but currently OFF). - Related: #58 (deferred the DM flow), #3 (NetherWiki docs), #43 (public instance), #47 (multi-tenant hardening), #76 (live-validate the auth path first).

robocub referenced this issue

2026-07-10 23:51:24 +00:00

Abuse observability: link/approve/unlink audit trail + report path #78

robocub referenced this issue

2026-07-11 03:09:27 +00:00

Self-serve UX: name the approval bot in the link pending-code reply #80

robocub referenced this issue

2026-07-11 06:00:33 +00:00

Abuse observability: link/approve/unlink audit trail + report path #78

robocub referenced this issue from a commit

2026-07-11 06:36:04 +00:00

docs: self-serve DM bridging walkthrough (#75)