@@ -11,6 +11,7 @@ This document is complemented by talk's source code, but doesn't require it. Def
1111 * [Partners](#partners)
1212 * [Access control](#access-control)
1313 * [Federation](#federation)
14+ * [General use](#general-use)
1415* [Interfaces for applications](#interfaces-for-applications)
1516 * [Interactions](#interactions)
1617 * [Subscriptions](#subscriptions)
@@ -44,6 +45,13 @@ To begin to gain an understanding of how the broker functions, let's look at its
4445 readers/(map bone (set knot)) :< our message readers
4546 :: ... ::
4647 == ::
48+```
49+
50+Aside from keeping track of `readers`, the different applications that use the broker, it also stores a map of named stories.
51+
52+### Stories
53+
54+```
4755++ story :> wire content
4856 $: grams/(list telegram) :< all messages
4957 locals/group :< local presence
@@ -55,19 +63,26 @@ To begin to gain an understanding of how the broker functions, let's look at its
5563 == ::
5664```
5765
58−Aside from keeping track of `readers`, the different applications that use the broker, it also stores a map of stories.
59−
60−### Stories
61−
62−Stories are the primary driver behind the broker. Whether you're hosting a group chat, or just want a place to aggregate messages into, a `story` will be created for it. They contain all data they need to be complete, from messages to metadata.
63−
64−Looking carefully at that metadata, stories seem to store both "local" and "remote" versions. This is to facilitate the "aggregate messages" use-case mentioned above, and core to how subscriptions function. Looking at the `config` structure, we see the following attribute:
66+Stories are the primary driver behind the broker. Whether you're hosting a group chat, or just want a place to aggregate messages into, a `story` will be created for it. They contain all data they need to be complete, from messages to metadata. Let's see what that metadata is made up of.
6567
6668```
67−src/(set partner) :< pulls from
69+++ group (map ship status) :< presence map
70+++ status {pec/presence man/human} :< participant
71+++ config :> circle config
72+ $: src/(set partner) :< pulls from
73+ cap/cord :< description
74+ con/control :< restrictions
75+ fed/federal :< federators
76+ == ::
77+++ control {sec/security ses/(set ship)} :< access control
78+++ federal {may/(set ship) fes/(set ship)} :< federation control
6879```
6980
70−Every story has a set of sources from which it receives data. If there's nothing in this set, the story will only receive messages people explicitly target towards it. If there *are* sources in that set, then their message will get forwarded to the story automatically. Presences and configurations for those sources are kept track of as well.
81+A `group` consists of ships and their `status` within a story. A status encompasses both `presence` (whether they're online, idle, typing, etc.) and `human` (their display name).
82+
83+A `config` contains all configuration for a story, from its description to its access control. (More on [`con`](#access-control) and [`fed`](#federation) below.) The `src` attribute in configurations is worth elaborating on.
84+
85+Every story has a set of sources from which it receives data. If there's nothing in this set, the story will only receive messages people explicitly target towards it. If there *are* sources in that set, then their message will get forwarded to the story automatically. Presences and configurations for those sources are kept track of as well, which is why we see not only "local" but also "remote" data in the story structure.
7186
7287In short, stories store messages. They get these either directly, or through any sources they have subscribed to.
7388
@@ -101,14 +116,24 @@ Though not important to the broker's architecture, the way access control for st
101116
102117A `channel` is publicly readable and writable, with a blacklist for banishing.
103118A `village` is privately readable and writable, with a whitelist for inviting.
104−A `journal` is publicly readable and privately writable, with a whitelist for authors.
119+A `journal` is publicly readable and privately writable, with a whitelist for authors.
105120A `mailbox` is readable by its owner and publicly writable, with a blacklist for blocking.
106121
107122### Federation
108123
109−One of the primary aspects of Urbit is its decentralized nature. The broker can happily make use of that by federating circles. That is, hosting them on multiple ships simultaneously. They share all messages, presence and configuration, regardless of where that data or change originated.
124+One of the primary aspects of Urbit is its decentralized nature. To make full use of that, the broker can federate circles. That is, circles can be hosted on multiple ships simultaneously. They share all messages, presence and configuration, regardless of where that data or change originated.
110125This can help spread heavy load across multiple ships, makes circles easier to access, and allows for fallback in case one of the hosts goes offline.
111126
127+The `fed` configuration attribute is used to determine which ships are allowed to federate a circle, and keep track of the ones that are currently doing so.
128+
129+### General use
130+
131+Upon initial startup, the broker creates a default story, a mailbox named `porch`. (This name is different for stars and galaxies.) This mailbox is the primary target for anyone and anything that wants to reach its owner. Applications can use it to send notifications and other information to the user (the broker itself does this as well), and users can use it to direct-message others.
132+
133+Talk reader applications are encouraged to use the default mailbox as the primary messaging hub. This way, users can easily switch between different applications without "losing" their subscriptions, message backlog, etc.
134+
135+As an example, the "official" talk reader operates like this, serving as an interface for reading from and managing the user's mailbox. Local stories are subscribed to through the `porch`, which ends up containing all messages the user receives.
136+
112137
113138## Interfaces for applications
114139
@@ -192,6 +217,7 @@ These changes get sent as `lowdown`s.
192217 {$glyph (jug char (set partner))} :< glyph bindings
193218 {$names (map ship (unit human))} :< nicknames
194219 == ::
220+++ crowd {loc/group rem/(map partner group)} :< our & srcs presences
195221```
196222
197223Aside from the initial lowdown that is sent when a subscription starts, these contains exclusively the changes as they occur. Configurations are wrapped in `unit`s so that deletion can be indicated. This also means that simple applications don't necessarily need to keep state. If all they want to do is show events as they happen, then the broker subscription will provide all they need.
@@ -201,7 +227,7 @@ Aside from the initial lowdown that is sent when a subscription starts, these co
201227
202228Brokers can communicate with other brokers to send commands and subscription updates.
203229
204−### Interaction
230+### Interactions
205231
206232To request changes to a story, brokers can send `command`s.
207233
@@ -216,6 +242,8 @@ To request changes to a story, brokers can send `command`s.
216242 == ::
217243 {$relief nom/knot who/(set ship)} :< federation ended
218244 == ::
245+++ lobby {loc/config rem/(map circle config)} :< our & srcs configs
246+++ crowd {loc/group rem/(map partner group)} :< our & srcs presences
219247```
220248
221249A `%review` command contains messages. These are sent to foreign brokers to be published to one of their stories.