@@ -13,58 +13,167 @@ each `task` that Iris can be `%pass`ed, and which `gift`(s) Ames can `%give` in
1313
1414### `%born`
1515
16+Each time you start your Urbit the Arvo kernel calls the `%born` `task` for
17+Iris. This causes Iris to cancel any outstanding http requests and resets all
18+connection states.
19+
1620#### Accepts
1721
22+```hoon
23+[ ~ ]
24+```
25+
1826#### Returns
1927
28+In response to a `%born` `task` Iris `give`s a `%http-response %cancel` `gift`
29+to each outstanding connection.
30+
2031
2132### `%cancel-request`
2233
34+This `task` cancels a previous fetch. Iris knows which request is meant based on the
35+`duct` that the `task` comes on.
36+
37+ We note that `%cancel-request` is also a `gift` that Iris can `%give`.
38+
2339#### Accepts
2440
41+```hoon
42+[ ~ ]
43+```
44+
2545#### Returns
2646
47+```hoon
48+[%cancel-request id=@ud]
49+```
50+Iris `%give`s a `%cancel-request` `gift` in response to this `task`. `id` is
51+obtained via a `(map duct @ud)`, with the `duct` corresponding to one along
52+which the `%cancel-request` `task` came with.
2753
2854
2955### `%crud`
3056
57+`%crud` is called whenever an error involving Iris occurs. It produces a crash
58+report in response.
3159
3260#### Accepts
3361
62+```hoon
63+[p=@tas q=(list tank)]
64+```
65+
66+`p` is the type of error, `q` is the error message.
67+
3468#### Returns
3569
70+Iris does not `%give` a `gift` in response to a `%crud` `task`, but it does
71+`%slip` Dill a `%flog` `task` instructing it to print the error.
72+
3673
3774### `%receive`
3875
76+The `%receive` `task` is used to receive a response to an `http-request` that
77+was made.
78+
3979#### Accepts
4080
81+```hoon
82+[id=@ud =http-event:http]
83+```
84+
85+`id` is the identification number assigned by Iris to the http connection under
86+consideration. `http-event` is a packet that contains a header and data.
87+
4188#### Returns
4289
90+The response depends on what kind of packet `http-event` is: `%start`,
91+`%continue`, or `%cancel` and whether the `complete` flag is `%.y` or `%.n`.
92+
93+If the packet says to `%start` or `%continue` and `complete=%.n`, Iris will `%give` a
94+`%http-response %progress` `gift`.
95+
96+If the packet says to `%start` or `%continue` and `complete=%.y`, Iris will
97+`%give` a `%http-response %finished` `gift`.
98+
99+If the packet says to `%cancel`, Iris will `%give` a `%http-response %cancel`
100+`gift` in return. The `complete` flag is unused here.
101+
43102
44103### `%request`
45104
105+`%request` is used to fetch a remote resource. `%request` is also a `gift` Iris
106+can `%give`.
107+
46108#### Accepts
47109
110+```hoon
111+[=request:http =outbound-config]
112+```
113+
114+A `$request` consists of the following:
115+ - `=method`, the http method, which is one of `CONNECT`, `DELETE`, `GET`,
116+ `HEAD`, `OPTIONS`, `POST`, `PUT`, and `TRACE`.
117+ - `url=@t`, the URL being requested
118+ - `=header-list`, a list of headers to pass with the request,
119+ - `body=(unit octs)`, optional data to include in the request.
120+
121+ A `$outbound-config` contains the number of redirects and retries that Iris
122+ will attempt. By default this is 5 redirects (the recommended limit for the
123+ http standard) and 3 retries.
124+
48125#### Returns
49126
127+```hoon
128+[id=@ud request=request:http]
129+```
130+Iris will `%give` a `%request` `gift` in response to a `%request` `task`. This
131+contains the `request` in the original `task` as well as the ID number assigned
132+by Iris for that particular http connection, which is extracted from the input `task`.
133+
50134
51135### `%trim`
52136
137+This `task` is sent by the interpreter to free up memory. It has no effect on Iris.
138+
53139#### Accepts
54140
141+```hoon
142+[ ~ ]
143+```
144+
55145#### Returns
56146
147+This `task` returns no `gift`s.
148+
57149
58150### `%vega`
59151
152+This `task` informs the vane that the kernel has been upgraded. Iris does not do
153+anything in response to this.
154+
60155#### Accepts
61156
157+```hoon
158+[ ~ ]
159+```
160+
62161#### Returns
63162
163+This `task` returns no `gift`s.
164+
64165
65166### `%wegh`
66167
168+This `task` asks Iris to product a memory usage report.
169+
67170#### Accepts
68171
172+This `task` has no arguments.
173+
69174#### Returns
70175
176+When Iris is `%pass`ed this `task`, it will `%give` a `%mass` `gift` in response
177+containing Iris' current memory usage.
178+
179+