fedipod 0.18.0 → 1.0.0

package/README.md

@@ -2,121 +2,110 @@
 
 - access the Fediverse from a Solid pod
 
-`FediPod` is a merger of three federating protocols - feeds from Mastodon and other Fediverse servers and from Bluesky and other ATProto servers, with all user data stored on a Solid pod. There are four different kinds of FediPod accounts :
-
-| Kind of Account | Description | User requirements | Host requirements |
-|---|---|---|---|
-| FediPod Solo | Browse & interact with the Fediverse and ATProto from a Solid pod | an always-on pod, a usually on local agent | — |
-| FediPod Group | Host a discussion group of Fediverse/ATProto users from a Solid pod | an always-on pod, a usually on local agent | — |
-| FediPod Gateway | Solo or Group with spam filtering & optional community identity | same + gateway pass-through account | any always-on host, Netlify will do |
-| FediPod Server | Full ActivityPub server as a CSS component | a pod on a CSS server implementing the FediPod component | a CSS server implementing the FediPod component |
-
-## Installation & Setup
-
-You may sign up for free for a solo, group, or gateway account at https://fedipod.net/ .  Wizards will walk you through install and setup. If you want to host a community, instructions are available for [Fediverse User Group](https://github.com/jeff-zucker/FediPod/blob/main/groups.md), the lightweight [FediPod Gateway](https://github.com/jeff-zucker/FediPod/blob/main/gateway.md) and for the full CSS component [FediPod Server](https://github.com/jeff-zucker/FediPod/blob/main/packages/fedipod-server/README.md). 
-
-### Installing
-
-```
-npm install -g fedipod
-```
-
-Needs Node 20 or newer.
-
-### Running the agent - 
-
-Run `fedipod start`. You may optionally add a port number (`fedipod start --port 8081`) to change your local agent's port (default is 8030).
-
-Now point your browser (any) at `https://localhost:8030` — or your own port if you set one — and there you go!
-
-### Running the agent as a service (recommended)
-
-If you don't want to run the agent each time, you can install it as a system service. This is recommended as leaving the agent off causes your mail to pile up on the pod host.  To create a system service :
-```
-fedipod install-service
-```
-It registers every identity on this machine, one service each, so all of your actors start at boot. An identity running in a terminal is stopped and taken over by its service.
-
-`fedipod uninstall-service` reverses it. 
-
-## Managing your FediPod install
-
-You can manage your posts, see logs, park, move, transfer your account and perform other actions. See the [GUI admin](https://github.com/jeff-zucker/FediPod/blob/main/gui.md) and [CLI admin](https://github.com/jeff-zucker/FediPod/blob/main/cli.md) pages.
-
-You can also use the admin tools to create other actors, either groups or persons.  You may have as many as you want on the local machine, but each one needs a separate pod.
-
-Every agent checks once a day whether a newer FediPod is published. When one
-exists, the record page offers **Update**, and `fedipod update`
-does the same from the terminal. `AP_UPDATE_CHECK=0` turns the check off.
-
-## A FediPod.net Gateway account (reccommended)
-
-Most of what a Fediverse inbox receives is broadcast noise. A gateway is a
-shared, always-on door that verifies each delivery, drops the junk, and
-passes the rest to your pod — while your key and data stay on your own
-pod. There is a free gateway at [fedipod.net](https://fedipod.net/). Attaching to it or detaching from it is a few wizard-guided clicks.
-
-Users are recommended to associate with a gateway as it reduces the mail load on your pod host.
-
-## Fediverse Clients
-
-The UI is the bundled [Phanpy](https://github.com/cheeaun/phanpy)
-client (MIT, by Chee Aun). It is served same-origin over the agent's Mastodon client-API facade, and logging in is one click — the instance is filled in for you. If you ever enter it by hand, use the address on the record's **local host** row.
-
-The agent federates for real: follow/unfollow, post, reply, favourite,
-boost, media, delete; incoming boosts from people you follow and a
-configurable public-hashtag feed (`POST /tagfeed`) fill the timeline.
-Also: editing posts, content warnings, voting in polls, all four visibility
-levels (followers-only and direct posts work only on a pod that enforces
-WAC access control — on one that doesn't, the composer refuses and says why),
-a conversations view for direct messages, bookmarks, favourites, lists,
-keyword filters, scheduled posts, pinned posts (visible from other servers),
-blocking and muting from the client, custom emojis, and web-push
-notifications that reach you while the client is closed.
-
-Polls: up to four options, one answer or several, running from five minutes to
-a month.
-
-### Other clients
-
-- **Web clients**: drop any static Mastodon client dist into `ui/<name>/`
-  and it is served at `/<name>/`, same-origin — see `ui/README.md`.
-- **Desktop clients** (Tuba, Whalebird, …): add `https://localhost:8030` (or other port for other agent) as a
-  custom instance.
-- **Streaming**: the agent serves the Mastodon streaming API
-  (`/api/v1/streaming`, WebSocket) so clients update live instead of polling.
-
-## Bluesky and ATProto
-
-`FediPod` includes experimental support for ATProto. A Bluesky connection lets your `FediPod` agent drive an existing Bluesky (or other ATProto) account alongside your Fediverse identity. When you post a public post from `FediPod`, it will be cross-posted to Bluesky as a mirror (a toggle you can turn off). Private DMs from `FediPod` to Bluesky are not currently supported.  Bluesky replies and activity flow into your timeline so you see, for example, a combined Bluesky and Mastodon feed.  You can like, boost, and reply to Bluesky posts from within `FediPod`.  None of these features require `Bridgy Fed`, however, fully joining a `FediPod` group from a Bluesky client other than `FediPod` does require a bridge.
-
-## Your other Fediverse accounts
-
-If you also hold an account on Mastodon — or on any other server speaking the Mastodon API, such as GoToSocial, Pleroma, Akkoma, Pixelfed or Friendica — you can connect it and read it here. Its home timeline and notifications join the feed you already read, interleaved by time, and a post both accounts see appears once rather than twice. Favouriting, boosting and replying act as the account the post came through, on its own server. Connect one from the **Other identities** row of the admin page: you sign in at that server, and the token it hands back stays on this machine.
-
-
-## Architecture
-
-`Activitypods` requires a server which provides both an ActivityPub server and a Solid server and thus requires a specific server setup.  `FediPod Solo & FediPod Group`, can be installed on any subdomained https-served pod without any modification to the server.  It does this by splitting the ActivityPub server into two parts.  The pod part provides discovery (webfinger) and stores mostly public data while the local agent provides the ActivityPub actions and storage for most private data. The exception is private direct messages which are stored on the pod protected by ACL resources. The same protected area also holds followers-only posts, and the pending-follow
-and blocked collections. [`FediPod Gateway`](https://github.com/jeff-zucker/FediPod/blob/main/gateway.md) can be supported from any lightweight Internet-facing box including Netlify, it does not require a full server and can work with any FediPod-capable pod.  [`FediPod Server`](https://github.com/jeff-zucker/FediPod/blob/main/packages/fedipod-server/README.md) works as a CSS server component.  If the pod host installs it, anyone with a pod on that server can opt-in to using their pod as a FediPod account fed by the server itself.
-
-![Fedipod Gateway flow](https://raw.githubusercontent.com/jeff-zucker/FediPod/main/architecture.svg)
-
-### Protocol conformance
-
-FediPod is a full ActivityPub server, on both of the spec's profiles:
-server-to-server (§7) and client-to-server (§6) — `POST /ap/outbox` on the
-agent takes an activity (or a bare Note) and does the id-minting,
-side-effects and delivery, authenticated by a Solid-OIDC token whose WebID is
-the owner's. The Mastodon REST API is the everyday client interface; C2S is
-the spec's own.
-
-Group actors follow FEP-1b12: a carried post names the group as its
-`audience`, the moderator roster is published as the actor's `attributedTo`,
-a followed group's announced `Delete` of a post it carried is honoured, and
-the group's own moderation is announced to the membership. The FEP-4ccd
-pending-follow collections and the FEP-c648 blocked collection are published
-as owner-only documents. See [Groups](https://github.com/jeff-zucker/FediPod/blob/main/groups.md).
+FediPod gives you a Fediverse account whose data lives on a Solid pod. You
+follow people on Mastodon, Bluesky, and other Fediverse or ATProto servers in
+one timeline. Your posts, followers and settings stay on your pod.
+
+The easiest way to run FediPod is to use it in any browser at https://fedipod.net. Nothing to install. A wizard will walk you through getting a pod (you can also bring your own) and creating a Fediverse identity attached to the pod.  There are also a number of [other ways to run FediPod](#other-ways-to-run-fedipod) which offer a variety of scenarios.
+
+## Requirements
+
+- A current browser, on a desktop or a phone.
+- A Solid pod with a host name of its own, such as
+  `https://alice.solidcommunity.net/`. Sign-up can create one for you at
+  solidcommunity.net or another provider, or use a pod you already have. A
+  pod that lives on a path of a shared host, like `https://server.example/alice/`,
+  cannot be a Fediverse address.
+- Followers-only and direct posts need a pod that enforces WAC access control.
+  On one that does not, the composer refuses those two and says why. Public
+  and unlisted posts work on any pod.
+
+## Getting an account
+
+1. Open https://fedipod.net and choose **create an account**.
+2. Choose a pod: a new one at the provider you name, or a pod you already have.
+3. Choose your handle. Your address is `@handle@yourpod`. Both parts are
+   permanent; display name, bio and pictures are set later in the client.
+4. Enter your pod password once. It creates the account and locks your
+   signing key. The password is not stored.
+
+Your account then opens in the client. To use it from another browser, go to
+https://fedipod.net, enter your address, sign in at your pod, and unlock your
+key with your password once on that browser.
+
+## What you can do
+
+The client is [Phanpy](https://github.com/cheeaun/phanpy) (MIT, by Chee Aun),
+served by fedipod.net. Through it you follow and unfollow, post, reply,
+favourite, boost, attach media, edit and delete. Content warnings, polls with
+up to four options and one or several answers, all four visibility levels, a
+conversations view for direct messages, bookmarks, lists, keyword filters,
+pinned posts that other servers can see, blocking and muting, and the custom
+emojis other servers send.
+
+**Bluesky.** Connect a Bluesky account, or any other ATProto account, from the
+manage page. Your public posts are mirrored to it, Bluesky replies and
+activity flow into your timeline, and you can like, repost and reply to
+Bluesky posts. Direct messages to Bluesky are not supported. None of this
+needs Bridgy Fed.
+
+**Your other Fediverse accounts.** If you also hold an account on Mastodon,
+or on any other server speaking the Mastodon API such as GoToSocial, Pleroma,
+Akkoma, Pixelfed or Friendica, connect it from the manage page and read it
+here. Its home timeline and notifications join the feed you already read,
+interleaved by time, and a post both accounts see appears once. Favouriting,
+boosting and replying act as the account the post came through. The token it
+hands back stays in your browser unless you choose to keep it on your pod.
+
+**Moving in.** Mastodon-format exports of follows, blocks, mutes, lists and
+domain blocks import from the manage page. Your old account can be listed as
+an alias, so a Move from it lands here.
+
+**The manage page.** `manage account` in the bar opens it: your profile,
+aliases, the gateway, key rotation, recovering posts, parking, moving to
+another server, retiring, and clearing a backlog. It is the same interface
+the installed agent has, described in [the admin interface](gui.md).
+
+**More than one browser.** One browser runs your account at a time. Opening
+it in a second browser shows your timeline read-only, and the moment you act
+there it takes over; the first drops back to reading.
+
+## What the browser version does not do
+
+- **Scheduled posts.** Nothing runs between now and the time you picked, so
+  the composer refuses one rather than dropping it later.
+- **Notifications while the client is closed.** There is no push service.
+  Open the tab and they are there.
+- **Live updates.** The client refreshes by polling.
+- **Hosting a group.** Joining one works.
+- **Other clients.** A phone app or desktop client has nothing on the network
+  to connect to.
+
+For these, see [Other ways to run FediPod](#other-ways-to-run-fedipod).
+
+## Your data and your keys
+
+Everything you publish and everything you read is stored on your pod. Your
+signing key is stored there too, encrypted under your password, so nobody who
+can read your pod, its host included, can post as you. fedipod.net holds no
+key: it verifies incoming mail, drops the junk, forwards the rest to your pod,
+and hands your browser the app. You can detach from it at any time and attach
+to a gateway of your own. Your address and your data do not change.
+
+## Other ways to run FediPod
+
+- [The installed agent](installed-agent.md) runs on your own machine and
+  adds scheduled posts, push notifications, live updates, group hosting and
+  the use of any Mastodon client.
+- [Groups](groups.md): hosting a discussion group of Fediverse and Bluesky
+  users from a pod.
+- [The gateway](gateway.md): running an always-on door of your own, on
+  Netlify or any small host.
+- [FediPod Server](packages/fedipod-server/README.md): a full ActivityPub
+  server as a Community Solid Server component, giving every pod on the server
+  the option of a Fediverse account.
+- [Architecture](architecture.md): how the pieces fit, and which protocols
+  FediPod speaks.
 
 ## Acknowledgements
 
@@ -129,3 +118,4 @@ This package was created using a heavily hectored claude.
 ## License
 
 (c) Jeff Zucker, 2026; may be freely used with an MIT license.
+p

package/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+FediPod splits an ActivityPub server into two parts. The pod provides
+discovery and stores the public record: the actor, its outbox, followers and
+posts, and the inbox that receives deliveries. The agent provides the
+ActivityPub actions: it drains the inbox, builds the timeline, signs and
+delivers, and answers the Mastodon client. The agent runs either in your
+browser, served by fedipod.net, or as [the installed agent](installed-agent.md)
+on your own machine. Private direct messages, followers-only posts and the
+pending-follow and blocked collections live on the pod in an area protected by
+access control.
+
+A [gateway](gateway.md) can stand in front of the pod: an always-on door that
+verifies each delivery where the signature can still be checked, drops spam,
+and forwards the rest to the pod inbox with a receipt. It holds no key. The
+browser version always has one; the installed agent may use one. Any
+lightweight host will do, Netlify included.
+
+[FediPod Server](packages/fedipod-server/README.md) puts the agent inside a
+Community Solid Server, so anyone with a pod on that server can opt in to a
+Fediverse account fed by the server itself.
+
+![The browser version](https://raw.githubusercontent.com/jeff-zucker/FediPod/main/browser.svg)
+
+![The installed agent, with a gateway](https://raw.githubusercontent.com/jeff-zucker/FediPod/main/architecture.svg)
+
+## Protocol conformance
+
+FediPod is a full ActivityPub server, on both of the spec's profiles:
+server-to-server (§7) and client-to-server (§6). `POST /ap/outbox` on the
+installed agent takes an activity, or a bare Note, and does the id-minting,
+side-effects and delivery, authenticated by a Solid-OIDC token whose WebID is
+the owner's. The Mastodon REST API is the everyday client interface; C2S is
+the spec's own.
+
+Group actors follow FEP-1b12: a carried post names the group as its
+`audience`, the moderator roster is published as the actor's `attributedTo`,
+a followed group's announced `Delete` of a post it carried is honoured, and
+the group's own moderation is announced to the membership. The FEP-4ccd
+pending-follow collections and the FEP-c648 blocked collection are published
+as owner-only documents. See [Groups](groups.md).

package/bin/fedipod.mjs

@@ -964,13 +964,12 @@ if (cmd === 'up') {
   let copied;
   try {
     copied = await copyPrivateHalf({
-      from: { state: agent.privateStorage(cred, 'state'), fediverse: agent.privateStorage(cred, 'fediverse') },
-      to: { state: agent.privateStorage(destCred, 'state'), fediverse: agent.privateStorage(destCred, 'fediverse') },
+      from: { state: agent.privateStorage(cred, 'state') },
+      to: { state: agent.privateStorage(destCred, 'state') },
       log: (...a) => console.log('[state]', ...a),
     });
   } catch (e) { console.error(e.message); process.exit(1); }
   console.log(`copied ${copied.docs} state document(s)`);
-  console.log(`copied ${copied.notes} note(s)`);
 
   // An empty source produces an empty destination, and every check above
   // passes: nothing failed to land because nothing was sent. The command then
@@ -2071,8 +2070,7 @@ WantedBy=default.target
     if (res.status >= 400) { console.error(body.error || `HTTP ${res.status}`); process.exit(1); }
     if (body.why) { console.error(body.why); process.exit(1); }
     console.log(`the pod indexed ${body.indexed} post(s); recovered ${body.recovered}`
-      + `${body.reblogs ? `, and marked ${body.reblogs} of them boosted` : ''}`
-      + `${body.rdf ? ` (${body.rdf} written back to the RDF)` : ''}`);
+      + `${body.reblogs ? `, and marked ${body.reblogs} of them boosted` : ''}`);
     if (body.dropped) console.log(`${body.dropped} fell past the 1000-status cap`);
     if (!body.landed) { console.error('the state write did NOT land — nothing is saved'); process.exit(1); }
     if (!body.recovered && !has('from-notes')) {

package/browser.svg

@@ -0,0 +1,72 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 860 486" font-family="Helvetica, Arial, sans-serif">
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#333"/>
+    </marker>
+  </defs>
+  <rect x="0" y="0" width="860" height="486" fill="#ffffff"/>
+
+  <!-- boxes (draw.io palette) -->
+  <g stroke-width="1.5">
+    <rect x="315" y="24"  width="230" height="72" rx="6" fill="#dae8fc" stroke="#6c8ebf"/>
+    <rect x="315" y="190" width="230" height="68" rx="6" fill="#e1d5e7" stroke="#9673a6"/>
+    <rect x="40"  y="372" width="210" height="70" rx="6" fill="#f8cecc" stroke="#b85450"/>
+    <rect x="580" y="360" width="250" height="88" rx="6" fill="#d5e8d4" stroke="#82b366"/>
+  </g>
+
+  <!-- box labels -->
+  <g fill="#111" text-anchor="middle">
+    <text x="430" y="56"  font-size="17" font-weight="bold">Open Social Web</text>
+    <text x="430" y="80"  font-size="13">Mastodon · Pixelfed · Bluesky …</text>
+
+    <text x="430" y="220" font-size="17" font-weight="bold">FediPod Gateway</text>
+    <text x="430" y="242" font-size="13">the mail door &amp; the relay</text>
+
+    <text x="145" y="391" font-size="17" font-weight="bold">Your Pod</text>
+    <text x="145" y="409" font-size="13">AP S2S formatted data</text>
+    <text x="145" y="426" font-size="13">in addition to other pod data</text>
+
+    <text x="705" y="392" font-size="17" font-weight="bold">Any Browser</text>
+    <text x="705" y="414" font-size="13">runs your FediPod Agent,</text>
+    <text x="705" y="431" font-size="13">a Mastodon API client</text>
+  </g>
+
+  <!-- arrows -->
+  <g stroke="#333" stroke-width="1.6" fill="none">
+    <!-- 1: Open Social Web <-> Gateway (AP S2S mail) -->
+    <line x1="430" y1="96" x2="430" y2="190" marker-start="url(#arrow)" marker-end="url(#arrow)"/>
+    <!-- 2: Your Pod -> Open Social Web (UNCHANGED, pod answers lookups) -->
+    <path d="M110,372 C46,300 46,150 322,92" marker-end="url(#arrow)"/>
+    <!-- 3: Gateway -> Your Pod (one way now) -->
+    <path d="M338,258 C300,300 250,330 205,372" marker-end="url(#arrow)"/>
+    <!-- 4: Gateway <-> Any Browser (agent loaded; signed posts sent) -->
+    <path d="M632,360 C560,320 522,300 472,258" marker-start="url(#arrow)" marker-end="url(#arrow)"/>
+    <!-- 5: Your Pod <-> Any Browser (Solid) -->
+    <line x1="250" y1="408" x2="580" y2="408" marker-start="url(#arrow)" marker-end="url(#arrow)"/>
+    <!-- 6: Any Browser <-> Open Social Web (ATProto client — Bluesky) -->
+    <path d="M760,360 C824,300 824,150 538,92" marker-start="url(#arrow)" marker-end="url(#arrow)"/>
+  </g>
+
+  <!-- arrow labels -->
+  <g fill="#333" font-size="13">
+    <text x="418" y="134" text-anchor="end">raw mail in</text>
+    <text x="418" y="150" text-anchor="end">relayed posts out</text>
+    <text x="442" y="142" text-anchor="start">AP S2S Protocol</text>
+
+    <text x="96"  y="250" text-anchor="start">Pod responds to requests for</text>
+    <text x="96"  y="266" text-anchor="start">webfinger, actor, public posts</text>
+
+    <text x="300" y="322" text-anchor="start">verified mail in</text>
+
+    <text x="588" y="302" text-anchor="middle">FediPod Agent loaded in browser;</text>
+    <text x="588" y="318" text-anchor="middle">signed posts sent to gateway</text>
+
+    <text x="430" y="400" text-anchor="middle" font-weight="bold" fill="#111">Solid Protocol</text>
+    <text x="430" y="428" text-anchor="middle">reads &amp; writes your pod</text>
+
+    <text x="780" y="238" text-anchor="end">ATProto</text>
+    <text x="780" y="254" text-anchor="end">client protocol</text>
+  </g>
+
+  <text x="830" y="474" text-anchor="end" font-size="11" fill="#888">© 2026 Jeff Zucker · CC BY-SA 4.0</text>
+</svg>

package/cli.md

@@ -70,6 +70,15 @@ fedipod revoke-credential --email EMAIL  # cut this machine off from the pod acc
 ```
 A new password takes effect when a running agent restarts.
 
+**A client hosted somewhere else now needs one.** A client running on its own
+site (Elk, Phanpy on someone's own domain) asks the agent to send the sign-in
+result back to that site. Without a password there is nothing to approve that
+with — and the agent used to do it anyway, which meant any page you happened
+to have open could ask for the same thing and be given a key to your account.
+So: no password, no sending credentials off this machine. Clients that live on
+the agent itself (the bundled one, a dist in `ui/`, anything on
+`https://localhost:<port>`) are unaffected and need no password.
+
 ## Bluesky
 
 ```

package/gateway.md

@@ -0,0 +1,160 @@
+# The gateway
+
+Most of what a Fediverse inbox receives is broadcast noise. A gateway is an
+always-on, internet-facing door that stands in front of your pod: it checks
+each delivery's signature where the headers still exist, drops forgeries and
+junk before they ever touch your pod, and passes the rest on with a receipt
+saying it checked.
+
+Your name, your signing key and your data stay on your own pod. The gateway is
+**keyless** — it never holds the key you sign with, so it cannot post as you,
+read your private things, or be you anywhere. The worst a broken one can do is
+push items into your inbox, and those still face your agent's own checks.
+
+A FediPod install works without any gateway at all. Deliveries go straight to
+your pod inbox, which holds them whether your agent is running or not.
+
+## Attaching your pod to one
+
+There is a gateway at [fedipod.net](https://fedipod.net/). Attaching happens
+from your own agent, which proves the pod with its own credential — no
+password is typed anywhere:
+
+1. Open your agent's admin page and, in the **Gateway** panel, give the
+   gateway's address and the name you want there. The panel checks the name
+   is free as you type.
+2. Choose a pod-based name (`@you@your.pod`) or a gateway-based name
+   (`@you@the-gateway`). The gateway account is created automatically either
+   way. A pod-based attach applies immediately; taking a gateway-based name
+   restarts the agent itself to publish under it.
+
+The same attach from the command line, against the running agent:
+
+```
+fedipod gateway --attach https://fedipod.net --name yourname
+```
+
+`--name` defaults to your handle; add `--fronted` for a gateway-based name.
+
+To undo it:
+
+```
+fedipod gateway --detach
+```
+
+That republishes your actor with your pod's own inbox. Nothing else moves.
+Detach talks to the running agent, so start it first. For a fronted identity,
+detaching also moves every published id back to the pod — a rename other
+servers see, not just a mail change.
+
+## Easing into it
+
+Attaching does not have to change how deliveries are treated on day one. The
+mode says how far you trust the door, and every step is reversible:
+
+- **off** — configured but not advertised; nothing changes on the wire. This
+  is where a by-hand configure starts, and the step back short of forgetting
+  the gateway entirely.
+- **shadow** — your actor advertises the gateway and the agent measures how
+  much real traffic verifies.
+- **trust** — verified follows are accepted without review.
+- **locked** — your inbox accepts writes only from the gateway.
+
+In every mode past **off**, the door itself is already filtering: blocked
+actors, content that does not concern you, and forged signatures are dropped
+at the door and never reach the pod. The mode says only how far the agent
+believes the door's receipts.
+
+The shadow numbers come from the agent:
+
+```
+curl -k https://localhost:8030/gateway
+```
+
+which reports the mode and the verified and unverified counts.
+
+Set it from the agent's own API:
+
+```
+curl -k -X POST https://localhost:8030/gateway -H 'content-type: application/json' \
+  -d '{"action":"mode","mode":"shadow"}'
+```
+
+8030 is the default identity's port; `fedipod status`
+prints the right one for each identity.
+
+## The receipt secret
+
+The gateway stamps each verification receipt with a secret shared between it
+and your agent, and your agent believes a receipt only when the stamp checks
+out. That is what stops somebody dropping a forged "verified" receipt beside a
+forged delivery.
+
+You never fetch this secret from anywhere. When you run your own gateway,
+your agent mints it and shows it to you once; you carry it to the gateway
+yourself. When you attach to a multi-user gateway, the direction is reversed:
+the gateway mints the secret and answers the attach with it, and your agent
+records it.
+
+## What the gateway can see
+
+It reads only public data to decide what concerns you: your published
+followers and following, and a small public policy document your agent writes
+with a mirror of your blocklist. Nothing private leaves your pod. Publishing
+that mirror does make your blocklist public, which is part of the bargain of
+running behind a door.
+
+## Running a gateway
+
+Any always-on box will do — a VPS, a home server behind a tunnel, a serverless
+host. The logic is plain Node in `lib/gateway-core.mjs`, and a host needs only
+a thin adapter that calls `handleDelivery`.
+
+Two ways are ready to use:
+
+- **On Netlify**, with the adapter in `netlify/functions/inbox.mjs`. See
+  [netlify/README.md](netlify/README.md) for the deployment specifics.
+- **On any box of your own**, with your own adapter around the same core.
+- **Inside a Community Solid Server**, as the same door run in-process by the
+  CSS component — see [packages/fedipod-server](packages/fedipod-server/README.md).
+
+### Offering accounts to other people
+
+A gateway can also be a front for many people, so a host can offer
+`@name@their-host` addresses. Each user keeps their own pod, their own agent
+and their own signing key; the front answers WebFinger for all of them, serves
+each public face by rewriting that user's pod ids onto the shared domain, and
+routes every verified delivery into the right pod.
+
+A fronted identity is the gateway-based name choice in the admin page's
+Gateway panel, or:
+
+```
+fedipod gateway --attach <front-origin> --name <name> --fronted
+```
+
+Choose at attach time: changing an existing identity's front later renames
+every published id, and the attach refuses it.
+
+**A front is only a doorway.** It never hosts pods and never dictates where
+they live. A host who also wants to offer pods to people who have none runs a
+pod server separately, with the duties that carries — and users may always
+bring a pod of their own instead.
+
+## Setting one up by hand
+
+If you are not using a signup page:
+
+1. Deploy the door to your box.
+2. Give it Append on your inbox, using a dedicated low-privilege pod account —
+   never your owner credential. FediPod's default inbox is public-Append, so
+   this is optional: with no credential the door writes with a plain PUT.
+3. Point your agent at it, which mints the shared secret and returns it once:
+
+   ```
+   curl -k -X POST https://localhost:8030/gateway -H 'content-type: application/json' \
+     -d '{"action":"configure","url":"<door-inbox-url>","webId":"<door-webid>"}'
+   ```
+
+   Copy that secret into the door's environment.
+4. Walk the modes above, starting at shadow.

package/groups.md

@@ -14,6 +14,13 @@ and pick group rather than person, or take the group path on a signup page.
 You can turn on join review as you create it. The group's pod must be the root
 of its own host, so its handle resolves.
 
+**Running a group needs the installed agent.** The in-browser build makes
+personal identities only — the sign-up wizard has no group option, and the
+moderation surface (join review, members, muting, the moderation queue) is not
+part of that build. You can *join* a group from the browser exactly as from
+anywhere else: joining is following, and that works everywhere. It is hosting
+one that needs an install.
+
 Being in a group also connects you to the people in it: posts from fellow
 members reach your timeline even when you do not follow them individually,
 so a reply in the room is something you see rather than something filed
@@ -62,8 +69,6 @@ boosting the author.
 
 A group can be handed on rather than abandoned using the `Transfer this account away` button. This tells every follower to migrate, so the membership survives a change of host.
 
-
-
 ## Bluesky members
 
 A group with a connected Bluesky account is joinable from Bluesky: following

package/gui.md

@@ -1,5 +1,10 @@
 # The Admin interface
 
+In the browser version at fedipod.net, `manage account` in the bar opens this
+same page for your account. The rest of this page describes it as the
+installed agent serves it; the controls are the same, minus the manual inbox
+drain and the local log, which a browser does not have.
+
 Open `https://localhost:8030/` while any agent is running — it forwards you to the agent — then choose `manage account` and select the actor you want from the local actors dropdown.
 Picking an actor marked "(stopped)" starts its agent, then opens its page.
 
@@ -91,7 +96,10 @@ is marked **sign in again** rather than quietly dropped.
 ## Handling follow requests
 
 New followers appear under **Follow requests** with **Accept** and **Refuse**
-beside them; nothing is accepted without you. Groups are different — joining
+beside them; nothing is accepted without you.
+They show in any Mastodon client as well, now that the client API serves the
+queue and takes both answers.
+Groups are different — joining
 follows the group's own moderation settings; see [Groups](groups.md).
 
 **Accept all** answers the whole queue at once, and the identity pane's
@@ -123,6 +131,8 @@ account*); your followers arrive by themselves. Removing an alias asks
 twice — servers still processing the move check it while they retry. The CSV
 files from the old server's export are imported with the CLI; see
 [CLI admin](cli.md).
+The in-browser build runs the same importer, so a CSV can be handed to it
+there too.
 
 ## Protecting & recovering your data