From 32111d2579e471ee90cc8f261aa0d6b979210650 Mon Sep 17 00:00:00 2001
From: Ryan Barrett <git@ryanb.org>
Date: Tue, 10 Dec 2024 09:03:42 -0800
Subject: [PATCH] docs: add fediverse admin section

fixes #1465
---
 templates/docs.html | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/templates/docs.html b/templates/docs.html
index 6af7df41..3a2f858d 100644
--- a/templates/docs.html
+++ b/templates/docs.html
@@ -64,6 +64,7 @@
 <li><a href="#fediverse-protocol-bot-user-blocked">I can't find <code>@bsky.brid.gy@bsky.brid.gy</code> on the fediverse!</a></li>
 <li><a href="#fediverse-follow-web">How do I find a bridged web site?</a></li>
 <li><a href="#fediverse-what">Which stuff of mine from the fediverse will get bridged?</a></li>
+<li><a href="#fediverse-admins">I'm a fediverse instance admin. What do I need to know?</a></li>
 
 
 <br>
@@ -75,7 +76,6 @@
 <li><a href="#fediverse-enhanced">Can I use my own domain as my fediverse handle?</a></li>
 <li><a href="#fediverse-delete">I disabled my bridged profile, or deleted a post, but it's still visible in the fediverse!</a></li>
 <li><a href="#instance-subdomains">Could other networks' instances get their own brid.gy subdomains, so that fediverse admins can federate with or block them individually?</a></li>
-
 <br>
 
 <p><em>From Bluesky</em></p>
@@ -448,7 +448,38 @@ <h3 id="from-fediverse">From the fediverse</h3>
 
 <li id="fediverse-what" class="question">Which stuff of mine from the fediverse will get bridged?</li>
 <li class="answer">
-<p>Anything that's fully public and interacts with Bluesky users. This includes your own posts if you have any Bluesky followers, and replies, likes, and reposts <em>if</em> the original post was bridged. Posts on Bluesky are limited to 300 characters, so longer posts from the fediverse are truncated and ellipsized. Hashtags, links, link previews, images, videos, and even alt text are also included.</p>
+<p>Once you've enabled the bridge, anything that's fully public and interacts with Bluesky users. This includes your own posts if you have any Bluesky followers, and replies, likes, and reposts <em>if</em> the original post was bridged. Posts on Bluesky are limited to 300 characters, so longer posts from the fediverse are truncated and ellipsized. Hashtags, links, link previews, images, videos, and even alt text are also included.</p>
+</li>
+
+
+<li id="fediverse-admins" class="question">I'm a fediverse instance admin. What do I need to know?</li>
+<li class="answer">
+<p>Thanks for asking! Beyond <a href="#">what Bridgy Fed is and what it does</a>, here's some useful info for fediverse instance admins.</p>
+
+<ul>
+<li>Bridgy Fed is opt in. When a fediverse user <a href="#fediverse-get-started">enables it</a> for a given network, eg Bluesky, it bridges their profile and posts and other interactions into that network giong forward. It doesn't bridge anything for users who haven't enabled it yet.
+<li>This means that fediverse users don't exist in Bluesky, and can't be followed or found in search there, until they've enabled the bridge.
+<li>Users enable the bridge to Bluesky by following the <code>@bsky.brid.gy@bsky.brid.gy</code> user, and disable it by blocking that user. When they disable it, their profile and posts are all removed from Bluesky.
+<li>Bluesky users can also bridge themselves into the fediverse. Unbridged fediverse users may follow them and interact with them, but those follows and interactions aren't bridged into Bluesky.
+<li>Only fully public posts are bridged into Bluesky. Unlisted aka quiet public, followers-only, and private mention posts aka DMs are never bridged.
+<li>Replies, reposts, and quote posts are only bridged if the original post being replied to, reposted, or quote posted was also bridged.
+<li>Blocks are bridged too. If a fediverse user blocks a bridged Bluesky user, it works just like blocking a normal fediverse user. Bridgy Fed also converts it to a Bluesky block on that end.
+<li>Reports aka <code>Flag</code>s are similarly bridged. If a fediverse user reports a bridged Bluesky user or post, Bridgy Fed sends it to Bluesky's moderation service as a report. The Bluesky team is then able to act on that user or post just like normal.
+<li>In general, bridged Bluesky users in the fediverse work just like normal fediverse users. All admin-level and user-level tools apply to them like you'd expect.
+<li>If a user enables the bridge and it doesn't work for them, <a href="#troubleshooting">point them to our troubleshooting docs</a>.
+<li><a href="https://docs.joinmastodon.org/admin/moderation/#limit-server">Limiting</a> aka silencing <code>brid.gy</code> or its subdomains works, but will make it more difficult for your users to enable the bridge. We also hear that limiting Bridgy Fed can result in <a href="https://www.loomio.com/d/W6tL5cvp/the-bluesky-bridge/104">confusing visibility and behavior that appears buggy</a>. We don't fully understand the details here yet, or whether we can do much about it.
+</ul>
+
+<p>Here are some details on our federation, ActivityPub, and Webfinger support.</p>
+
+<ul>
+<li>Bridgy Fed uses a few different subdomains of <code>brid.gy</code>, including <code>fed.brid.gy</code>, <code>bsky.brid.gy</code>, and <code>web.brid.gy</code>. You'll need to allow federation with all of these domains for it to work.
+<li>Bridgy Fed's instance actor for signing GETs (ie authorize fetch) is <code>https://fed.brid.gy/fed.brid.gy</code> aka <code>@fed.brid.gy@fed.brid.gy</code>.
+<li>Bridged Bluesky users are on the <code>bsky.brid.gy</code> domain. If you want to block them all and defederate from Bluesky entirely, block that domain.
+<li>Some web sites bridged into the fediverse will have Webfinger addresses on their own domains, eg <code>@snarfed.org@snarfed.org</code>. Webfinger requests to those domains redirect to <code>fed.brid.gy</code> and are served there.
+<li>Bridged ActivityPub actors are <code>type: Person</code>. Bot actors like <code>@bsky.brid.gy@bsky.brid.gy</code> and <code>@fed.brid.gy@fed.brid.gy</code> are <code>type: Service</code>.
+<li>When a fediverse user opts into the bridge, their profile and posts will be indexed and searchable in Bluesky's search even if they have the <code>discoverable</code> or <code>indexable</code> flags set to <code>false</code>. Bluesky doesn't currently have a way to opt individual users out of search.
+</ul>
 </li>