khan: update api ref

content/reference/arvo/khan/khan.md

@@ -12,13 +12,15 @@ not yet proper libraries for other languages that can make use of it. Therefore,
 these documents will only touch on Khan's internal interface.
 
 Khan's internal interface lets you run threads via Khan rather than having to
-poke [Spider](/reference/arvo/threads/reference) and subscribe for the result. This interface is simpler and more
+poke [Spider](/reference/arvo/threads/reference) and subscribe for the result.
-ergonomic than Spider's, so is usually preferable.
+This interface is simpler and more ergonomic than Spider's, so is usually
+preferable.
 
-There are currently three `task`s to run a thread: `%fard`, `%fyrd`, and `%lard`.
+There are two `task`s for running threads from userspace:
-Only `%fard` is currently documented in
+[`%fard`](/reference/arvo/khan/tasks#fard) and
-the [API Reference](/reference/arvo/khan/tasks) section, and a practical example
+[`%lard`](/reference/arvo/khan/tasks#lard). The former is for running a thread
-is given in the [Example](/reference/arvo/khan/example) section.
+from file and the latter is for running an "in-line" thread, where you pass
+Khan the thread directly.
 
 ## Sections
 

content/reference/arvo/khan/tasks.md

@@ -3,31 +3,101 @@ title = "API Reference"
 weight = 2
 +++
 
-Khan's external interface is still experimental, so there's only one `task` that
+These are the `task`s Khan can be passed and the `gift`s it can give.
-is currently useful:
 
-## `%fard`
+## Tasks
+
+Here are the `task`s you can pass Khan. You'd either use
+[`%fard`](#fard) to run a thread from a file or [`%lard`](#lard) to run
+an in-line thread.
+
+### `%fard`
+
+Run a thread from within Arvo.
 
 ```hoon
 [%fard p=(fyrd cage)]
 ```
 
-Run a thread from within Arvo
-
 `p` contains the thread location, name, and start arguments. See the
 [`fyrd`](/reference/arvo/khan/types#fyrd) data type reference entry for details.
 
 #### Returns
 
 When the thread finishes, either by succeeding or failing, Khan will return an
-`%arow` `gift`, which looks like :
+[`%arow`](#arow) gift.
+
+---
+
+### `%fyrd`
+
+External thread.
+
+```hoon
+[%fyrd p=(fyrd cast)]
+```
+
+This is passed to Khan by the runtime when a thread is run externally.
+You would not use this from userspace.
+
+---
+
+### `%lard`
+
+In-line thread.
+
+```hoon
+[%lard =bear =shed]
+```
+
+The [`bear`](/reference/arvo/khan/types#bear) is either a `desk` or
+`beak`. The [`shed`](/reference/arvo/khan/types#shed) is the thread
+itself. Since Spider doesn't need to read out the thread from Clay, the
+`bear` doesn't do much apart from be included in the thread name that
+Spider generates. Khan will have Spider run the given thread, and
+eventually give an [`%arow`](#arow) gift back with the result.
+
+#### Returns
+
+When the thread eventually finishes (or if it fails), Khan with give an
+[`%arow`](#arow) gift back with the result.
+
+---
+
+## Gifts
+
+These are the two `gift`s Khan can give. In userspace, you'd only
+receive an [`%arow`](#arow).
+
+### `%arow`
+
+In-arvo result.
 
 ```hoon
 [%arow p=(avow cage)]
 ```
 
-`p` either contains the result in a `cage`, or an error and stack trace if it
+This gift contains the result of a finished thread if successful, or an
-failed. See the [`avow`](/reference/arvo/khan/types#avow) data type reference
+error and stack trace if it failed. It's given for threads run from
-entry for details.
+within Arvo. See the [`avow`](/reference/arvo/khan/types#avow) entry in
+the types reference for more details.
+
+---
+
+### `%avow`
+
+External result.
+
+```hoon
+[%avow p=(avow page)]
+```
+
+This gift contains the result of running a thread externally. You would
+not receive this in userspace.
+
+
+A `page` is a pair of `mark` and `noun`. See the
+[`avow`](/reference/arvo/khan/types#avow) entry in the types reference
+for more details of that mold builder.
 
 ---