update overview doc

1 files changed, 13 insertions, 11 deletions

diff --git a/doc/README.md b/doc/README.md
index 4fc7997..d7f3c12 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -16,10 +16,10 @@ Design Goals
 * Transparent authentication and collaboration across federated instances
 * Participating servers and their repos may be either private access or public
 * Users should never need to trust any server in the network other than their home-server
-* Users never send any login credentials to other participating servers
+* Users should never need to send any login credentials to other participating servers
 * Users should never need to run any JavaScript from other participating servers
-* Users can interact with foreign repos in all of the typical collaborative ways, just as if they had an account on each foreign host
-* Allow most (or ideally all) collaborative interactions with or without a web browser (e.g. via email, custom clients, etc)
+* Users should be able to interact with foreign repos in all of the typical collaborative ways, just as if they had an account on each foreign host
+* Most (or ideally all) collaborative interactions should be accessible with or without a web browser (e.g. via email, custom clients, etc)
 * The preceding, closely related, three bullet points are intended to allow interfaces to be maximally customizable; so that for examples:
   - A) People who rely on accessibility features could run a home instance or client which is particularly well suited to screen readers
   - B) The cool kids can use or create snazzy CSS/JS websites for web browsers
@@ -30,19 +30,21 @@ How It Works
 ------------
 
 * Everyone can view repos on public hosts without logging in (just as you would expect)
-* Users can create an account on any public instance or may host their own - (this server will be henceforth referred to as the "home-server")
-* Users never interact directly with any foreign host
-* All non-trivial user interaction with foreign hosts are mediated by the user's home-server
+* Users can create an account on any public instance or may host their own - (this server will be henceforth referred to as that user's "home-server")
 * Users can create repos on their home-server only
 * Users can fork foreign repos to their home-server without signing-in to the foreign host
 * Users can send merge requests (eg: "pull-requests", raw patches), open tracker issues, post comments, subscribe to updates (eg: "watch", "follow"), and endorse foreign repos (eg: "favorite", "star"), all without signing-in to the foreign host
+* All non-trivial user interaction with foreign hosts are mediated by the user's home-server
+* Users never need to interact directly with any foreign host; though it is possible for it to appear transparently as if doing so, albeit indirectly in reality
 * All of the above interactions will be possible with or without a web browser (e.g. via email)
 * Savvy admins and users can interact with the system by implementing parts of the protocol in custom services and clients
-* Participating hosts validate the identity of foreign users against credentials supplied by that user's home-server
-* Server instances will verify and vouch for the identity of it's users using HTTP signatures
-* Instances can optionally sign commits/comments with GPG and/or send the user's GPG public key for verifying commits/comments
-* Instances should notify foreign hosts of events to which their local users are subscribed, so that it may notify their local users (e.g. on-site alerts, email alerts)
-* Instances should also periodically poll other instances for such events to ensure maximal robustness
+* Home-servers will verify the identity of foreign users against credentials supplied by that user's home-server
+* Home-servers will vouch for the identity of their users using HTTP signatures
+* Home-servers could optionally sign submissions to foreign hosts with the user's GPG key, such as commits and comments, and send the public key along with the submission for verification
+* Home-servers could log actions of foreign users for display purposes (listing remote forks, listing remote subscribers, displaying validated signatures, etc), as phantom, non-login users in their database
+* Home-servers should notify foreign hosts of events to which their local users are subscribed, so that it may notify their local users (e.g. on-site alerts, email alerts, activity-pub "toots")
+* Home-servers should also periodically poll remote hosts, which host repos and/or users to which their users are subscribed, for events that may have been missed due to one of the servers being offline at the time the even occurred, in order to ensure maximal robustness
+* The preceding bullet point is intended to encourage users to self-host their own forge, even if they do so with a laptop, and also interact with their forge while offline, without missing incoming federated events nor dropping outgoing federated events. This would also allow forges to implement advanced features such as mirroring and synchronizing the entire data set of remote repos robustly; so that their users could interact with foreign forges in all of the expected ways while offline and/or without ever contacting the foreign directly.
 
 
 See [EXAMPLE_WORKFLOWS.md](EXAMPLE_WORKFLOWS.md) for some general ideas on how users could interact with the system.