Moderator's guide

.gitignore

@@ -18,3 +18,6 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# Emacs
+*~

docs/bot/setup.md

@@ -14,7 +14,7 @@ The E2EE functionality is not part of the Dogfooding program that Draupnir has i
 above that offered by our CI testing. You can read more about this programme in [The Dogfood Guide](/shared/dogfood.md)
 
 If you aren't using encrypted rooms anywhere, get an access token by opening Element in a
-seperate browser profile or incognito tab, and log in as the bot. Then, go to "All Settings", "Help & About", and
+separate browser profile or incognito tab, and log in as the bot. Then, go to "All Settings", "Help & About", and
 click the little triangle next to "Access token". Copy and paste that into your config under `accessToken`.
 
 **Note**: Do not log out, just close the window, otherwise the access token will be invalidated.

docs/concepts/management-room.md

@@ -0,0 +1,20 @@
+---
+sidebar_position: 1
+sidebar_label: Management room
+---
+
+<!--
+SPDX-FileCopyrightText: 2024 Gnuxie <Gnuxie@protonmail.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Management room
+
+The management room is where you will interact with Draupnir. This is
+the room where Draupnir will respond to commands, allowing you to
+coordinate with Draupnir and other moderators without disrupting your
+public Matrix rooms.
+
+The management room should not be public, as anyone present in this
+room can perform any action supported by the bot.

docs/concepts/policy-lists.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 2
+sidebar_label: Policy lists
+---
+
+<!--
+SPDX-FileCopyrightText: 2024 Gnuxie <Gnuxie@protonmail.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Policy lists
+
+## Policies
+
+Policies are what Matrix uses to describe a recommendation for an
+action against an entity. An entity can be any first class Matrix
+concept, but the most common entity is a Matrix user. A recommendation
+is just a flag that describes what the policy is for. For example,
+banning a user from a room with Draupnir usually results in the
+creation of a policy of the type `m.policy.room.user` with the
+recommendation `m.ban`. You can read about in the Matrix specification
+[here](https://spec.matrix.org/latest/client-server-api/#moderation-policy-lists)
+
+These policies are stored in Matrix rooms as _state events_.  When
+this happens, we can refer to the room as a _policy room_.
+If you are unfamiliar with state events, you can read our Matrix
+room essentials documentation [here](./room-essentials.md).
+
+## Policy room vs policy list
+
+A policy room is a Matrix room that contains policies.  A policy room
+is also a policy list, however Draupnir may use the term policy list
+to also refer to what is effectively virtual policy list. A virtual
+policy list would be a collection of policies where the list is not
+backed up by a single Matrix room as the source of the
+policies. Internally, Draupnir actually collects all the policies
+together and places them into the same virtual policy list.

docs/concepts/power-levels.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 0
+sidebar_position: 1
 sidebar_label: Matrix power levels
 ---
 

docs/concepts/room-essentials.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 0
+sidebar_label: Room essentials
+---
+
+<!--
+SPDX-FileCopyrightText: 2024 Gnuxie <Gnuxie@protonmail.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Room essentials
+
+In Matrix, the place where you talk and see other users is called a
+Matrix room. This is Matrix's equivalent to *channels* that you might
+be familiar with on other platforms.
+
+## Events
+
+Everything that happens in Matrix is expressed with *events*.
+This includes everything from the messages that you send to other
+users, notifications that are sent to show that you are typing,
+and profile changes such as changing your displayname within
+a Matrix room.
+
+These events accumulate in the room *timeline*, which is the what you
+can see when you look at a Matrix room within your client.
+
+You can read what the Matrix specification has to say for events [here](https://spec.matrix.org/latest/client-server-api/#events)
+
+## State events
+
+Matrix also has a concept of *state events*. These are special events
+that servers, bots, bridges and clients all use to store and retrieve
+data associated with the room easily. For example, the avatar
+and displayname of a given user in a Matrix room is stored within
+a state event to make it convenient for clients to access.
+
+## Authorization events
+
+Matrix also has a concept of *authorization events*. These are special
+*state events* that are used to control what other events can be
+sent to the room. For example, the `m.room.power_levels` event is
+an authorization event that can be used to control which users can
+send messages to a room.
+
+Your own membership event, of the type `m.room.member`, is also an
+authorization event, that authorizes you to participate within a
+Matrix room.
+
+## Membership
+
+When you join a Matrix room, your homeserver creates a membership
+state event in the room that you are joining. This membership event
+tells all of the servers present within the room that you are also
+present so that they can authorise your messages. They will also
+use the event to remember to send your homeserver new messages.
+
+This membership state event is called `m.room.member`, you can read
+the specification for the event
+[here](https://spec.matrix.org/latest/client-server-api/#room-membership)
+
+The membership event has a protected content field called `membership`,
+which describes the membership state for a Matrix user in a room.
+
+Whenever you ban or remove a user from a room, your homeserver has to
+create a membership event for that user that supersedes their current
+membership event.  Explicitly marking the target user's membership as
+`ban` or `leave`.
+
+## Lazy bans
+
+Unfortunately, due to the nature of Matrix and state events, Draupnir
+has to issue bans lazily. What this means is that Draupnir will not
+ban users from Matrix rooms until they have joined. Normally the ban
+will be issued by Draupnir instantaneously.
+
+It is technically possible for room moderators to issue bans
+preemptively, however if there is another user within the room from
+the same server as the target of the ban, then the target will be
+force-joined to the Matrix room. This normally is not a problem, but
+for private rooms this behaviour can actually alert the target of the
+presence of the room and give them access to the title and profile
+picture.
+
+The other reason Draupnir does not prematurely apply bans is that this
+would lead Draupnir to send thousands of redundant state events to
+every room that is being protected. This is because most of the users
+that are banned will never actually attempt to join a room. These
+events can degrade the performance of all servers that are
+participating.

docs/contributing/CONTRIBUTING.md

@@ -180,13 +180,13 @@ finding a way to conduct business in an ethical way,
 and this is problematic.
 
 Once you start working within capitalism with capitalism, and exchange
-your power and influence over a work to monitize the work itself,
+your power and influence over a work to monetize the work itself,
 the work will gain inertia and a power of its own that you cannot control.
 You will work for the work, for external interests, and these won't
 be the interests of your powerless users who you were among to begin with.
 
 It would be extreme, but I am tempted to suggest that by performing a
-buisness this way, you are part of an effort
+business this way, you are part of an effort
 which not only reinforces capitalism but works to make it more
 efficient. Effectively working to make capitalism more powerful.
 Congratulations.
@@ -198,12 +198,12 @@ the law.
 Therefore I propose a new licensing model, one which appeals
 to the power of public pressure rather than the law.
 
-Such a license would be liberal, allowing incorperation into
+Such a license would be liberal, allowing incorporating into
 proprietary works provided it retained a notice.
 However, any work which is used in any way to conduct business must
-report all software being used by the buisness with this license,
-all turnover made by the buisness, all profit made by the buisness
-and an estimation of both profit and turnover made by the buisness in
+report all software being used by the business with this license,
+all turnover made by the business, all profit made by the business
+and an estimation of both profit and turnover made by the business in
 relation to the collection of software reported.
 
 It is not clear to me how often these figures should be reported
@@ -212,9 +212,9 @@ be found centrally). It is also unclear how to create the legalise
 required.
 
 With the information these licenses would provide, public pressure
-could then be used to demand reperations for the profits made by
+could then be used to demand reparations for the profits made by
 pillaging and destructive businesses.
-It is not clear yet how any reperations would be distributed,
+It is not clear yet how any reparations would be distributed,
 probably through some system of
 [venture communes](https://wiki.p2pfoundation.net/Venture_Commune).
 The idea is to ensure that the developers and users of projects

docs/contributing/context.md

@@ -38,7 +38,7 @@ This has to be because there is no immediate way to know whether the
 new state event represents the current state of the room, or is a
 stale event that has been discovered by Draupnir's homeserver
 (ie a fork in the DAG maintained by another homeserver has converged
-back with the one maintiained by Draupnir's own homeserver).
+back with the one maintained by Draupnir's own homeserver).
 
 ### Policy Lists
 
@@ -132,7 +132,7 @@ active room first.
 
 Mjolnir was originally created by
 [Travis Ralston](https://github.com/turt2live) as a good enough
-solution temprarily made permanent.
+solution temporarily made permanent.
 The abstract architecture of Mjolnir remains today and we are
 thankful for good foundations, and significantly
 [policies](https://spec.matrix.org/latest/client-server-api/#moderation-policy-lists)

docs/intro.md

@@ -1,13 +1,33 @@
 ---
 sidebar_position: 0
+slug: /
 ---
 
-# Welcome to Draupnir Documentation
+# Welcome
 
-Under the Appservice category you will find Appservice Mode Related Documentation.
+## Moderators
 
-Under Bot mode you find documentation related to Bot mode
+If you are a moderator looking for documentation for how to use an
+existing Draupnir, you will want to review the following pages:
 
-Under Shared Documentation you find the documentation that relates to both operating modes.
+- [Moderator's guide](./moderator/setting-up-and-configuring) -
+  Managing your Draupnir and your protected rooms.
+- [Protections](./protections) - Configuring the protections
+  offered by Draupnir.
 
-And Finally under Contributing you find our contribution Documentation.
+## System administrators
+
+If you are a system administrator and you are looking for how
+to setup Draupnir:
+
+- [Setup Draupnir as a bot](./bot/setup) - Configuring Draupnir as a
+  bot to protect a single community.
+- [Setup Draupnir as an appservice](./appservice) - Configuring
+  Draupnir as an appservice that can manage and provision multiple
+  individual Draupnir bots to your homeserver's users or others.
+
+## Contributors
+
+If you are a contributor:
+
+- [Contributing](./contributing) - How to contribute to Draupnir.