@@ -85,7 +85,9 @@ The type of the next field is a `note:agent:gall` (henceforth just `note`), whic
8585 [below](#task).
8686- An `%arvo` `note` is a request to a vane. We'll discuss such requests
8787 [below](#note-arvo).
88−- A `%pyre` `note` is XX TODO
88+- A `%pyre` `note` is used to abort an event. It's mostly used internally by
89+ Kiln, it's unlikely you'd use it in your own agent. The `tang` contains an
90+ error message.
8991
9092### `task`
9193
@@ -114,10 +116,9 @@ These can be divided into two categories:
114116 card](#pass).
115117- `%watch-as`: This is the same as `%watch`, except Gall will convert updates to
116118 the given `mark` before delivering them to your agent.
117−- `%leave`: Unsubscribe from something to which you previously subscribed. The
118− subscription to cancel is determined by the `wire` at the beginning of the
119− [`pass` card](#pass) rather than the subscription `path`, so its argument is
120− just `~`.
119+- `%leave`: Unsubscribe. The subscription to cancel is determined by the `wire`
120+ at the beginning of the [`pass` card](#pass) rather than the subscription
121+ `path`, so its argument is just `~`.
121122
122123**Examples**
123124
@@ -134,9 +135,8 @@ Unlike subscriptions, these are just one-off messages.
134135
135136A `%poke` contains a `cage` of some data. A `cage` is a cell of `[mark vase]`.
136137The `mark` is just a `@tas` like `%foo`, and corresponds to a mark file in the
137−`/mar` directory. We'll cover marks in detail later, but you can refer to the
138−[`mark`](/docs/userspace/gall-guide/types#mark) entry in the type reference for
139−further details. The `vase` contains the actual data you're sending.
138+`/mar` directory. We'll cover marks in greater detail later. The `vase` contains
139+the actual data you're sending.
140140
141141The `%poke-as` task is the same as `%poke` except Gall will convert the `cage`
142142to the `mark` you specify before sending it off.
@@ -189,9 +189,8 @@ section in the [Arvo documentation](/docs/arvo/arvo).
189189
190190The purpose of a `%give` card is to respond to a request made by another agent
191191or vane. More specifically, it's either for acknowledging a request, or for
192−sending out updates to subscribers (which are technically in response to their
193−initial subscription request, however long ago it may have been). This is in
194−contrast to a [`%pass`](#give) card, which is essentially unsolicited.
192+sending out updates to subscribers. This is in contrast to a [`%pass`](#give)
193+card, which is essentially unsolicited.
195194
196195A `%give` card contains a `gift:agent:gall` (henceforth just `gift`), which is
197196defined in `lull.hoon` as:
@@ -213,8 +212,9 @@ These can be divided into two categories:
213212request respectively. If the `(unit tang)` is null, it's an ack - a positive
214213acknowledgement. If the `(unit tang)` is non-null, it's a nack - a negative
215214acknowledgement, and the `tang` contains an error message. Gall automatically
216−sends a nack with a traceback if your agent crashes while processing the
217−request, and automatically sends an ack if it does not. Therefore, you would not explicitly produce a `%watch-ack` or `%poke-ack` gift.
215+sends a nack with a stack trace if your agent crashes while processing the
216+request, and automatically sends an ack if it does not. Therefore, you would not
217+explicitly produce a `%watch-ack` or `%poke-ack` gift.
218218
219219#### Examples
220220
@@ -226,17 +226,16 @@ request, and automatically sends an ack if it does not. Therefore, you would not
226226### Subscriptions
227227
228228`%fact` and `%kick` are both sent out to existing subscribers - entities that
229−have previously successfully `%watch`ed a path on your ship.
229+have previously `%watch`ed a path on your ship.
230230
231−A `%kick` gift takes a list of `path`s, which are subscription paths, and a
232−`(unit ship)`, which is the ship to kick from those paths. If the `unit` is
233−null, all subscribers are kicked from the specified paths. Note that sometimes
234−Gall can produce `%kick` gifts without your agent explicitly sending a card, due
235−to networking conditions. Therefore, you should not assume `%kick`s you receive
236−are intentional, and should try resubscribing by default.
231+A `%kick` gift takes a list of subscription `path`s. and a `(unit ship)`, which
232+is the ship to kick from those paths. If the `unit` is null, all subscribers are
233+kicked from the specified paths. Note that sometimes Gall can produce `%kick`
234+gifts without your agent explicitly sending a card, due to networking
235+conditions.
237236
238−`%fact` gifts are how updates are sent out to subscribers. The `paths` field is
239−a list of subscription paths - all subscribers of the specified `path`s will
237+`%fact`s are how updates are sent out to subscribers. The `paths` field is a
238+list of subscription paths - all subscribers of the specified `path`s will
240239receive the `%fact`. The `cage` is the data itself - a cell of a `mark` and a
241240`vase`.
242241