@@ -11,33 +11,7 @@ The various Clay scries are specified by a `care`, which is a single character c
1111[~.~zod ~.home ~.~2021.4.26..02.29.03..d31b ~]
1212```
1313
14−## Contents
15−
16−- [%a](#a) - Build a `hoon` file.
17−- [%b](#b) - Dynamic `mark`.
18−- [%c](#c) - Dynamic `mark` conversion.
19−- [%d](#d) - List `desk`s.
20−- [%e](#e) - Static `mark`.
21−- [%f](#f) - Static `mark` conversion.
22−- [%p](#p) - File permissions.
23−- [%r](#r) - Vase-wrapped file data.
24−- [%s](#s) - Miscellaneous scries:
25− - [%yaki](#yaki) - `yaki:clay` of the specified commit.
26− - [%blob](#blob) - `blob:clay` of file.
27− - [%hash](#hash) - Content hash of the specified commit.
28− - [%cage](#cage) - `cage` of the data of a file.
29− - [%open](#open) - Compile prelude of file.
30− - [%late](#late) - Most recent `case` of `desk`.
31− - [%base](#base) - Mergebase of two `desk`s.
32−- [%t](#t) - List files in directory.
33−- [%u](#u) - Check for existence of file.
34−- [%v](#v) - Desk state.
35−- [%w](#w) - Revision number of the given `desk` `case`.
36−- [%x](#x) - Raw data of file.
37−- [%y](#y) - `arch` of a file or directory.
38−- [%z](#z) - Content hash of a file or directory.
39−
40−## %a
14+## %a - Build hoon.
4115
4216A scry with a `care` of `%a` will build a `hoon` file and return it as a `vase`.
4317
@@ -47,7 +21,7 @@ Example:
4721.^(vase %ca /===/lib/strandio/hoon)
4822```
4923
50−## %b
24+## %b - Dyn. mark core.
5125
5226A scry with a `care` of `%b` will produce a `dais:clay` processed `mark` core for the specified `mark`. The `path` in the scry is a `mark`.
5327
@@ -57,9 +31,9 @@ Example:
5731.^(dais:clay %cb /===/txt)
5832```
5933
60−## %c
34+## %c - Dyn. mark convert.
6135
62−A scry with a `care` of `%c` will produce a `tube:clay` dynamically typed `mark` conversion gate. The `path` specifies two `mark`s - *from* and *to*, like `/txt/noun`.
36+A scry with a `care` of `%c` will produce a `tube:clay` dynamically typed `mark` conversion gate. The `path` specifies two `mark`s - _from_ and _to_, like `/txt/noun`.
6337
6438Example:
6539
@@ -69,7 +43,7 @@ Example:
6943[p=/text/plain q=[p=3 q=7.303.014]]
7044```
7145
72−## %d
46+## %d - List desks.
7347
7448A scry with a `care` of `%d` will return a `(set desk)` of the `desk`s that exist on your ship.
7549
@@ -80,19 +54,19 @@ Example:
8054{%home %kids}
8155```
8256
83−## %e
57+## %e - Static mark core.
8458
85−A scry with a `care` of `%e` will return a statically typed `nave:clay` `mark` core in a `vase`. The `path` in the scry specifies the `mark`.
59+A scry with a `care` of `%e` will return a statically typed `nave:clay` `mark` core. The `path` in the scry specifies the `mark`. The type returned is a `(nave:clay {type} {diff})`, where `{type}` is the type the `mark` takes and `{diff}` is the type taken by the `mark` specified in `+form:grad`.
8660
8761Example:
8862
8963```
90−.^(vase %ce /===/noun)
64+.^((nave:clay noun noun) %ce /===/noun)
9165```
9266
93−## %f
67+## %f - Stat. mark convert.
9468
95−A scry with a `care` of `%f` will return a static `mark` conversion gate. The `path` specifies two `mark`s - *from* and *to*, like `/txt/mime`.
69+A scry with a `care` of `%f` will return a static `mark` conversion gate. The `path` specifies two `mark`s - _from_ and _to_, like `/txt/mime`.
9670
9771```
9872> =a .^($-(text mime) %cf /===/txt/mime)
@@ -100,7 +74,7 @@ A scry with a `care` of `%f` will return a static `mark` conversion gate. The `p
10074[p=/text/plain q=[p=3 q=7.303.014]]
10175```
10276
103−## %p
77+## %p - File permissions.
10478
10579A scry with a `care` of `%p` will return the permissions of the file or directory in question. The type returned is a `[dict:clay dict:clay]` where the head is read permissions and the tail is write permissions.
10680
@@ -113,7 +87,7 @@ Example:
11387[[src=/ rul=[mod=%white who=[p={} q={}]]] src=/ rul=[mod=%white who=[p={} q={}]]]
11488```
11589
116−## %r
90+## %r - File as vase.
11791
11892A scry with a `care` of `%r` will return the data of the given file wrapped in a `vase` or crash if it's a directory. It's basically just a vase-wrapped `%x` scry.
11993
@@ -137,13 +111,13 @@ Examples:
137111Crash!
138112```
139113
140−## %s
114+## %s - Misc. scries.
141115
142116A scry with a `care` of `%s` is for miscellaneous internal and debug functions and is liable to change in the future.
143117
144118Rather than just a `path` to a file, the head of the `path` is tagged with one of `%yaki %blob %hash %cage %open %late %base` and the tail depends on which tag you use. We'll look at each in turn.
145119
146−### %yaki
120+### %yaki - Commit.
147121
148122This will return the [yaki:clay](/docs/arvo/clay/data-types#yaki-clay-commit) of the specified commit. It takes a [tako:clay](/docs/arvo/clay/data-types#tako-clay-commit-reference).
149123
@@ -168,7 +142,7 @@ Here we scry the [dome:clay](/docs/arvo/clay/data-types#dome-desk-data) for `/==
168142]
169143```
170144
171−### %blob
145+### %blob - File blob.
172146
173147This will return the [blob:clay](/docs/arvo/clay/data-types#blob-clay-data) of some file. It takes a [lobe:clay](/docs/arvo/clay/data-types#lobe-clay-data-reference).
174148
@@ -191,7 +165,7 @@ Here we grab the `lobe:clay` of `/gen/hood/hi/hoon` with a `%y` scry, then use i
191165]
192166```
193167
194−### %hash
168+### %hash - Commit hash.
195169
196170This will return the `@uvI` content hash of the specified commit. It takes a `tako:clay`.
197171
@@ -206,7 +180,7 @@ Here we grab the `dome:clay` for `/===` with a `%v` scry, get the latest `tako:c
2061800v16.er7uq.oke4u.cru7u.nglu9.q3su7.6ub1o.bh4qk.r5uav.ut12d.5rdl5
207181```
208182
209−### %cage
183+### %cage - File as cage.
210184
211185This will return a `cage` of the data of some file. It takes a `lobe:clay`.
212186
@@ -228,11 +202,11 @@ Here we grab the `lobe:clay` of `/gen/hood/hi/hoon` with a `%y` scry, then use i
228202]
229203```
230204
231−### %open
205+### %open - Build prelude.
232206
233207This is like a `%a` scry but it only compiles the prelude to the file, e.g. the Ford rune imports. Proper documentation for this will be done as part of Ford documentaton at a later date.
234208
235−### %late
209+### %late - Latest case.
236210
237211This will return the most recent revision number of a `desk` that has been fully downloaded. The type it returns is a `cass:clay`. The `case` in the `beak` must be a revision number rather than a date. You can just provide a case of `1` since it returns the latest regardless. If we have nothing for the specified `desk`, this will just return the bunt of a `cass:clay` like `cass=[ud=0 da=~2000.1.1]`.
238212
@@ -248,7 +222,7 @@ cass=[ud=50 da=~2021.4.22..10.38.50..57a8]
248222cass=[ud=0 da=~2000.1.1]
249223```
250224
251−### %base
225+### %base - Merge-base.
252226
253227This will return the mergebase (i.e. most recent common ancestor) between two `desk`s. The type it returns is a `(list tako:clay)`. The first `desk` will just be the one in the `beak` `path` prefix and the second will be specified like `/ship/desk` at the end of the scry `path`. If there is no common ancestor between the two `desk`s, this will just produce an empty `list`.
254228
@@ -264,7 +238,7 @@ Examples:
264238~
265239```
266240
267−## %t
241+## %t - List files.
268242
269243A scry with a `care` of `%t` will return a `(list path)` of all files in the given directory, or just a `(list path)` of the single file if it's a file. This is done recursively so will provide files in subdirectories as well. The paths will be fully qualified except for the `ship`, `desk` and `case`. If the directory or file specified does not exist, it will return an empty `list`.
270244
@@ -292,7 +266,7 @@ Examples:
292266~
293267```
294268
295−## %u
269+## %u - Check exists.
296270
297271A scry with a `care` of `%u` will return a `?` depending on whether the file exists. It will produce `%.n` if it's a directory or doesn't exist and will produce `%.y` if it's a file and exists.
298272
@@ -313,7 +287,7 @@ Examples:
313287%.n
314288```
315289
316−## %v
290+## %v - Desk state.
317291
318292A scry with a care of `%v` will return the entire state of a `desk` as a `dome:clay`.
319293
@@ -327,7 +301,7 @@ Example:
327301
328302Note: If you try printing this it will take forever and probably OOM your ship.
329303
330−## %w
304+## %w - Revision number.
331305
332306A scry with a `care` of `%w` will return the revision number and date of a given `case`. The type returned is a `cass:clay` like `[ud=@ud da=@da]` where `ud` is the revision number and `da` is the date.
333307
@@ -338,11 +312,10 @@ Example:
338312[ud=2 da=~2021.4.13..19.12.49..3389]
339313```
340314
341−## %x
315+## %x - Read file.
342316
343317A scry with a `care` of `%x` will return the raw data of a file as an `@` or crash if it's a directory.
344318
345−
346319Examples:
347320
348321```
@@ -360,7 +333,7 @@ Examples:
360333Crash!
361334```
362335
363−## %y
336+## %y - Read arch.
364337
365338A scry with a `care` of `%y` will return the `arch` of a file or directory.
366339
@@ -401,7 +374,7 @@ Examples:
401374[fil=~ dir={}]
402375```
403376
404−## %z
377+## %z - Content hash.
405378
406379A scry with a `care` of `%z` will return the hash of a file or the recursive hash of a directory. If the file or directory doesn't exist it will return a null value.
407380