Document shanes

pkg/arvo/neo/cod/std/src/fil/behn.txt

@@ -0,0 +1,82 @@
+# Behn
+
+Behn takes one request —  to set a timer or cancel one —  and gives one response to say a timer went off.
+
+```
+++  behn
+  |%
+  ::  $req: Timer request
+  ::
+  ::    %wait: Set timer
+  ::    %rest: Cancel timer
+  ::
+  +$  req  $>(?(%rest %wait) task:^behn)
+  ::  $res: Timer response
+  ::
+  ::    %wake: Timer went off
+  ::
+  +$  res  $>(%wake gift:^behn)
+  --
+```
+
+The request is a regular `task:behn`, the code above just filters for `task:behn`s head-tagged with `%rest` and `%wait`. The response is a regular `gift:behn`, but filtered for `%wake` `gift`s. 
+
+The Behn shane itself is just a `(jug @da pith)`, as we see in `/sur/neo.hoon`. This is Shrubbery's conception of Behn's state.
+
+```
++$  behn  (jug @da pith)
+```
+
+***
+
+## Tasks
+
+[explain $ pith]
+
+[explain %behn-req]
+
+### `%wait`
+
+In this example, we set a behn timer to go off five seconds after the shrub has been initialized.
+
+```
+++  init
+  |=  old=(unit pail:neo)
+  ^-  (quip card:neo pail:neo)
+  :_  old
+  :~  [#/[p/our.bowl]/$/behn %poke %behn-req !>([%wait (add now.bowl ~5s)])]
+  ==
+```
+
+### `%rest`
+
+This shrub accepts a poke that cancels a specific timer. We identify the timer to cancel by passing in the time it was supposed to go off.
+
+```
+++  poke
+  |=  [=stud:neo vaz=vase]
+  ^-  (quip card:neo pail:neo)
+  =/  act  !<(example-diff vaz)
+  ?>  =(-.act %rest)
+  :_  state
+  ::  cancel timer that was set to go off at ~2024.7.10..15.0.0
+  :~  [#/[p/our.bowl]/$/behn %poke %behn-req !>([%rest ~2024.7.10..15.0.0])]
+  ==
+```
+
+## Gifts
+
+### `%wake`
+
+When /app/neo receives a `%wake` task from the Behn vane, it pokes the relevant shrubs with the `%wake` `gift:behn`.
+
+```
+++  poke
+  |=  [=stud:neo vaz=vase]
+  ^-  (quip card:neo pail:neo)
+  =/  act  !<(behn-res vaz)
+  :_  state
+  :~  [#/[p/our.bowl]/$/behn %poke %example-diff !>([%timeout ~])]
+      [#/[p/opponent.bowl]/$/behn %poke %example-diff !>([%timeout ~])]
+  ==
+```

pkg/arvo/neo/cod/std/src/fil/clay.md

@@ -0,0 +1,46 @@
+# Clay
+
+Clay is Arvo's filesystem vane. Shrubbery uses Clay to track changes in specific files.
+
+## Types
+
+The Clay shane stores a map of {pith} to {dk how to word this} in its state.
+
+```
++$  clay
+  (map [src=pith hand=pith] [case=@ud =desk =path as=(unit mark)])
+```
+
+The Clay shane takes two requests, one response, and defines a `peer` type for subscriptions. The `peer` is a desk, a path to the file in question in that desk, and optionally a specific mark we'd like to receive updated versions of that file through.
+
+```
+++  clay
+  |%
+  +$  peer  [=desk =path as=(unit mark)]
+  +$  req
+    $%  [%peer =pith =peer]
+        [%pull =pith]
+    ==
+  +$  res  [=pith case=@ud files=(axol cage)]
+  --
+```
+
+## Tasks
+
+### `%peer`
+
+Subscribe to a file at the given `pith`.
+
+### `%pull`
+
+Cancel a subscription to a file at the given `pith`.
+
+## Gifts
+
+The response from Clay, relayed from Shrubbery to the userspace shrub.
+
+```
++$  res  [=pith case=@ud files=(axol cage)]
+```
+
+Contains the `pith` to the relevant directory in Clay, a version number for that directory, and a recursive tree of `cage`s containing the updated files in that directory.

pkg/arvo/neo/cod/std/src/fil/eyre.md

@@ -0,0 +1,75 @@
+# Eyre
+
+Eyre is Urbit's HTTP server vane. Shrubbery can use Eyre to serve UIs to your device and serve resources of all kinds to the clearweb. 
+
+## Types
+
+The Eyre shane stores three things in its state.
+- `by-id`: Map of HTTP request ID to the pith of the shrub which is handling the request.
+- `by-pith`: Map of pith to ID; `by-id` in reverse.
+- `bind`: Map of Eyre [binding](https://docs.urbit.org/system/kernel/eyre/reference/data-types#binding)s to `pith`s.
+
+```
++$  eyre
+  $:  by-id=(map @ta pith)
+      by-pith=(map pith @ta)
+      bind=(map binding:^^eyre pith)
+  ==
+```
+
+The Eyre shane manages several requests and responses, covered in detail below.
+
+```
+++  eyre
+  |%
+  +$  req  [%connect =binding:^eyre =pith]
+  +$  res  [%bound ~]
+  +$  sign  (pair @ta gift)
+  +$  gift
+    $%  [%head =response-header:http]
+        [%data dat=(unit octs)]
+        [%done ~]
+    ==
+  +$  task
+    (pair @ta inbound-request:^eyre)
+  --
+```
+
+Note: `task:eyre:neo` is the type of [`inbound-request`](https://docs.urbit.org/system/kernel/eyre/reference/data-types#inbound-request) that comes in via HTTP from the clearweb. You wouldn't send this from a shrub.
+
+## Tasks
+
+### `%connect` 
+
+The `%connect` pail is the Eyre shane's version of Eyre's [`%request`](https://docs.urbit.org/system/kernel/eyre/reference/tasks#request) task. It's the only type of `req:eyre:neo`.
+
+In the code below, we construct a `req:eyre:neo` by giving it a `binding:eyre` and a `pith:neo`. The `binding` corresponds to the subdomain `/neo/sky` (to serve a frontend to `<localhost:port>/neo/sky`) and the `pith` is `here.bowl`, the location of this shrub.
+
+```
+++  init
+  |=  pal=(unit pail:neo)
+  :_  sig/!>(~)
+  =/  =pith:neo  #/[p/our.bowl]/$/eyre
+  =/  =binding:eyre  [~ ~[%neo %sky]]
+  =/  =req:eyre:neo  [%connect binding here.bowl]
+  :~  [pith %poke eyre-req/!>(req)]
+  ==
+```
+
+## Gifts
+
+### `%head`
+
+The HTTP header of the response. Has to be given immediately so the connection doesn't time out.
+
+### `%data`
+
+The actual data of the HTTP request.
+
+### `%done`
+
+HTTP request has finished, the connection has closed.
+
+### `%bound`
+
+URL has been successfully bound.

pkg/arvo/neo/cod/std/src/fil/gall.md

@@ -0,0 +1,63 @@
+# Gall
+
+Gall is Arvo's userspace software vane. Shrubbery interfaces with Gall by accepting subscription updates, {what else?}.
+
+## Types
+
+???
+
+{peer could be subscription, peek is probably a scry?}
+
+{what is `=<  gall` storing?}
+
+```
+++  gall
+  =<  gall
+  |%
+  +$  gall
+    $:  peer=(jug pith pith)
+        peek=(map pith peek:^^gall)
+    ==
+  --
+```
+
+The Gall shane takes four requests and only gives one response, a `(pair pith sign)` for subscription updates from agents.
+
+```
+++  gall
+  |%
+  +$  req
+    $%  [%peek p=@dr]
+        [%keep ~]
+        [%reap ~]
+        [%peer ~]
+    ==
+  +$  peek  [src=(set pith) refresh=@dr]
+  +$  sign  sign:agent:^gall
+  +$  res   (pair pith sign)
+  --
+```
+
+## Tasks
+
+### `%peek`
+
+???
+
+### `%keep`
+
+???
+
+### `%reap`
+
+???
+
+### `%peer`
+
+???
+
+## Gifts
+
+### `(pair pith sign)`
+
+Subscription update from a Gall agent, in practice usually `%facts`. The `pith` corresponds to the [`wire`](https://docs.urbit.org/courses/app-school/types#wire) and the `sign` the [`sign:agent:gall`](https://docs.urbit.org/system/kernel/gall/reference/data-types#signagent).

pkg/arvo/neo/cod/std/src/fil/iris.md

@@ -0,0 +1,75 @@
+# Iris
+
+[Iris](https://docs.urbit.org/system/kernel/iris) is the HTTP client vane, used to fetch resources from the web.
+
+## Types
+
+The Iris shane takes one request (`res`) and one response (`req`).
+
+```
+++  iris
+  |%
+  +$  req  [hand=pith dat=request:http]
+  +$  res  [hand=pith dat=request:http]
+  --
+```
+
+In both types the `hand` is "the wire" as far as Shrubbery is concerned, and `dat` is Eyre's `request:http`.
+
+## Tasks
+
+### `%request`
+
+Iris' [`%request`](https://docs.urbit.org/system/kernel/iris/reference/tasks#request) task fetches a remote HTTP resource. You can send this task in Shrubbery through the `%iris-req` poke.
+
+```
+++  poke
+  |=  [=stud:neo vax=vase]
+  ^-  (quip card:neo pail:neo)
+  =+  !<(keys=@t q.pail)
+  ?+    stud  !!
+    ...
+      %openapi-req
+    =+  !<(=req:openai vax)
+    ?>  ?=(%chat-create -.q.req)
+    :_  [%txt !>(keys)]
+    =/  =request:http
+      :*  %'POST'
+          'https://api.openai.com/v1/chat/completions'
+          (headers:openai keys)
+          `(as-octt:mimes:html (trip (en:json:html (chat-create-req:enjs:openai +.q.req))))
+      ==
+    ~&  [%req request]
+    =/  =req:iris:neo  [#/foo request]
+    :~  [#/[p/our.bowl]/$/iris %poke [%iris-req !>(req)]]
+    ==
+  ==
+```
+
+## Gifts
+
+### `%http-response`
+
+When Eyre receives the HTTP resource, it sends Shrubbery a [`client-response`](https://docs.urbit.org/system/kernel/iris/reference/data-types#client-response) head-tagged with `%finished`. This response contains the `hand` pith specified in the request, so once you've routed to the `%iris-res` pail you could further route on the `hand` to handle more than one kind of HTTP response.
+
+```
+++  poke
+  |=  [=stud:neo vax=vase]
+  ^-  (quip card:neo pail:neo)
+  =+  !<(keys=@t q.pail)
+  ?+    stud  !!
+      %iris-res
+    =+  !<(=res:iris:neo vax)
+    ?.  ?=(%finished -.dat.res)
+      `pail
+    ?~  full-file.dat.res
+      `pail
+    =/  body=cord  q.data.u.full-file.dat.res
+    =/  jon=json  (need (de:json:html body))
+    ~&  [%jon jon]
+    ~&  [%result (chat-completion-res:dejs:openai jon)]
+    `pail
+    ...
+  ==
+```
+