@@ -0,0 +1,841 @@
9+- [Introduction](#introduction)
10+- [Read and Subscribe](#read-and-subscribe)
11+ - [%sing](#sing) - Read a file or directory.
12+ - [%next](#next) - Subscribe for the next change to a file or directory.
13+ - [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
14+ - [%many](#many) - Track changes to a `desk` for the specified range of revisions.
15+ - [Cancel Subscription](#cancel-subscription)
16+- [Write and Modify](#write-and-modify)
17+ - [%ins](#ins) - Add a file.
18+ - [%del](#del) - Delete a file.
19+ - [%mut](#mut) - Change a file.
20+ - [Multiple Changes](#multiple-changes) - Change multiple files.
21+- [Manage Mounts](#manage-mounts)
22+ - [%boat](#boat) - List mounts.
23+ - [%mont](#mont) - Mount something.
24+ - [%ogre](#ogre) - Unmount something.
25+ - [%dirk](#dirk) - Commit changes.
26+- [Merge Desks](#merge-desks)
28+- [Permissions](#permissions)
29+ - [%perm](#perm) - Set file permissions.
30+ - [%cred](#cred) - Add permission group.
31+ - [%crew](#crew) - Get permission groups.
32+ - [%crow](#crow) - Get group usage.
33+- [Foreign Ships](#foreign-ships)
34+ - [%warp](#warp) - Read a file on a foreign ship.
35+ - [%merg](#merg) - Merge from a foreign `desk`.
39+This document contains a number of examples of interacting with Clay using its various `task`s. Sections correspond to the general details in the [API Reference](@/docs/arvo/clay/tasks.md) document.
41+Most examples use one of these two threads which you can save to the `ted` directory of your `%home` `desk`:
48+=, strand=strand:spider
53+=/ uarg !< (unit task:clay) arg
55+ (strand-fail:strand %no-arg ~)
57+=/ =card:agent:gall [%pass /foo %arvo %c task]
58+;< ~ bind:m (send-raw-card:strandio card)
62+`send-task-take-gift.hoon`
67+=, strand=strand:spider
72+=/ uarg !< (unit task:clay) arg
74+ (strand-fail:strand %no-arg ~)
76+=/ =card:agent:gall [%pass /foo %arvo %c task]
77+;< ~ bind:m (send-raw-card:strandio card)
78+;< res=[wire sign-arvo] bind:m take-sign-arvo:strandio
85+See the [Read and Subscribe](@/docs/arvo/clay/tasks.md#read-and-subscribe) section of the [API Reference](@/docs/arvo/clay/tasks.md) document for general details.
89+Here we'll look at reading files by passing Clay a `%warp` `task` with a `%sing` `rave` and receiving a `%writ` `gift` containing the data in response.
92+Using the `send-task-take-gift.hoon` thread, let's try reading `gen/hood/hi.hoon`:
95+> -send-task-take-gift [%warp our %home ~ %sing %x da+now /gen/hood/hi/hoon]
98+You should see something like this as the output:
104+ [ p=[p=%x q=[%da p=~2021.5.20..23.37.50..e79b] r=%home]
111+ 3.548.750.706.400.251.607.252.023.288.575.526.190.856.734.474.077.821.289.791.377.301.707.878.697.553.411.219.689.905.949.957.893.633.811.025.757.107.990.477.902.858.170.125.439.223.250.551.937.540.468.638.902.955.378.837.954.792.031.592.462.617.422.136.386.332.469.076.584.061.249.923.938.374.214.925.312.954.606.277.212.923.859.309.330.556.730.410.200.952.056.760.727.611.447.500.996.168.035.027.753.417.869.213.425.113.257.514.474.700.810.203.348.784.547.006.707.150.406.298.809.062.567.217.447.347.357.039.994.339.342.906
119+The `cage` in the `riot` of the `%writ` contains the file's data due to our use of an `%x` `care`. It needn't be `%x` though. If we change it to `%u`, for example, we'll get a `?` `cage` instead:
122+> -send-task-take-gift [%warp our %home ~ %sing %x da+now /gen/hood/hi/hoon]
126+ [ p=[p=%u q=[%da p=~2021.5.20..23.42.21..bb33] r=%home]
128+ r=[p=%flag q=[#t/?(%.y %.n) q=0]]
134+Here's a breakdown of the `task` we sent:
136+
140+Here we'll look at subscribing to the next version of a file by passing Clay a `%warp` `task` with a `%next` `rave` and receiving a `%writ` `gift` when the file changes.
142+Using the `send-task-take-gift.hoon` thread, let's subscribe to the next version of `foo.txt`:
145+> -send-task-take-gift [%warp our %home ~ %next %x da+now /foo/txt]
148+Now, in unix, create a file called `foo.txt` in the root of the `home` directory of your ship. In the dojo, hit backspace to disconnect the thread from the dojo prompt and run `|commit %home`. You should see something like:
153+[%writ p=[~ [p=[p=%x q=[%ud p=3] r=%home] q=/foo/txt r=[p=%txt q=[#t/*'' q=0]]]]]
154++ /~zod/home/3/foo/txt
157+As you can see, the `riot` in the `%writ` includes a `cage` with the data of `/foo/txt` due to our use of an `%x` `care`.
159+Now run the thread again, and this time delete the file in unix and again `|commit %home` in the dojo. You should see:
165+- /~zod/home/4/foo/txt
168+You can see the `riot` is just `~` due to the file being deleted.
170+Here's a breakdown of the task we sent:
172+
176+Here we'll look at subscribing to the next version of multiple files by passing Clay a `%warp` `task` with a `%mult` `rave` and receiving a `%wris` `gift` when any of the files change.
178+This thread will subscribe to `/foo/txt` with an `%x` `care` and `/bar/txt` with a `%u` `care`. It will print out the `%wris` it gets back from Clay.
185+=, strand=strand:spider
190+=/ files=(set (pair care:clay path))
195+;< =bowl:strand bind:m get-bowl:strandio
196+=/ =task:clay [%warp our.bowl %home ~ %mult da+now.bowl files]
197+=/ =card:agent:gall [%pass /mult %arvo %c task]
198+;< ~ bind:m (send-raw-card:strandio card)
199+;< response=(pair wire sign-arvo) bind:m take-sign-arvo:strandio
204+Save the above to `ted/sub-mult.hoon`, `|commit %home` and run with `-sub-mult`. Now, create `foo.txt` and `bar.txt` in your home directory, hit backspace in the dojo to disconnect the thread and run `|commit %home`. You should see something like:
209+[%wris p=[%da p=~2021.4.27..06.07.08..5ec4] q={[p=%u q=/bar/txt] [p=%x q=/foo/txt]}]
210++ /~zod/home/151/foo/txt
211++ /~zod/home/151/bar/txt
214+You'll notice that, unlike a `%writ`, the `%wris` doesn't give you the data. It merely tells you the `care`s and `path`s of the files that changed. If you need to actually get the data, you can just scry or send a request for the files in question.
216+Now, run the thread again, open `bar.txt` in an editor, modify its contents, save it and `|commit %home`. You'll notice you didn't receive a `%wris`. This is because we subscribed to `/bar/txt` with `%u` care and its existence didn't change.
218+Lastly, delete `foo.txt` and `|commit %home`. You should see something like:
223+[%wris p=[%da p=~2021.4.27..06.15.03..0da4] q={[p=%x q=/foo/txt]}]
224+- /~zod/home/153/foo/txt
227+As you can see, a relevant change to any of the subscribed files will trigger a response, not just when all of them change.
229+Here's a breakdown of the `task` we sent:
231+
235+Here we'll look at subscribing to a range of changes to a `desk` by passing Clay a `%warp` `task` with a `%many` `rave` and receiving `%writ` `gift`s when changes occur.
237+This thread will subscribe to changes to your `%home` `desk` for the next three minutes. The `track` is `%.y` so it will only inform you of changes, not send the full `nako`. It will only get updates if the specified file exists. It contains a `main-loop` that will take an arbitrary number of `sign`s and print them out in the dojo. Since it never ends, you'll need to stop it with the `:spider|kill` command in the dojo.
244+=, strand=strand:spider
249+ %- (main-loop:strandio ,~)
252+ ;< res=(pair wire sign-arvo)
254+ ((handle:strandio ,(pair wire sign-arvo)) take-sign-arvo:strandio)
263+=/ uarg !< (unit path) arg
265+ (strand-fail:strand %no-arg ~)
267+;< =bowl:strand bind:m get-bowl:strandio
268+=/ =task:clay [%warp our.bowl %home ~ %many %.y da+now.bowl da+(add ~m3 now.bowl) path]
269+=/ =card:agent:gall [%pass /many %arvo %c task]
270+;< ~ bind:m (send-raw-card:strandio card)
271+;< ~ bind:m take-sign-loop
275+Make sure `foo.txt` doesn't exist in the root of your `%home` `desk`. Save this to `ted/sub-many.hoon`, `|commit %home`, run it like `-sub-many /foo/txt`, and hit backspace in the dojo to free up the dojo prompt. Now, add a file called `bar.txt` to your `desk` and `|commit %home`. You should see something like:
280++ /~zod/home/260/bar/txt
283+Notice you've received no `%writ` from Clay. This is because `/foo/txt` doesn't exist. Now, create `foo.txt` and `|commit %home` again. You should see:
289+ q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=261] r=%home] q=/ r=[p=%null q=[#t/@n q=0]]]]]]
291++ /~zod/home/261/foo/txt
294+Now that `/foo/txt` exists it will inform you of updates. Note that if you delete `/foo/txt` again it will again stop sending updates.
296+Now try adding `baz.txt`:
302+ q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=262] r=%home] q=/ r=[p=%null q=[#t/@n q=0]]]]]]
304++ /~zod/home/262/baz/txt
307+Now wait until the three minutes is up and try making a change, for example deleting `baz.txt`:
313+ q=[%clay [%writ p=[~ [p=[p=%w q=[%ud p=264] r=%home] q=/ r=[p=%null q=[#t/@n q=0]]]]]]
315+[p=/many q=[%clay [%writ p=~]]]
316+- /~zod/home/263/baz/txt
319+You can see that along with the normal `%writ` it's also sent a second `%writ` with a null `riot` to indicate the subscription has ended. This is because it has now passed the end of the range of `case`s to which you subscribed.
321+Run `:spider|kill` to stop the thread.
323+Here's a breakdown of the `task` we sent:
325+
327+## Cancel Subscription
329+Here we'll look at cancelling a subscription by sending Clay a `%warp` `task` with a null `(unit rave)` in the `riff`.
331+This thread will subscribe to the `%next` version of `/foo/txt`, then immediately cancel the subscription and wait for a response to print (which it will never receive).
338+=, strand=strand:spider
343+;< =bowl:strand bind:m get-bowl:strandio
344+=/ =task:clay [%warp our.bowl %home ~ %next %x da+now.bowl /foo/txt]
345+=/ =card:agent:gall [%pass /next %arvo %c task]
346+;< ~ bind:m (send-raw-card:strandio card)
347+=. task [%warp our.bowl %home ~]
348+=. card [%pass /next %arvo %c task]
349+;< ~ bind:m (send-raw-card:strandio card)
350+;< =riot:clay bind:m (take-writ:strandio /next)
355+Save the above to `ted/stop-sub.hoon`, `|commit %home`, run it with `-stop-sub` and hit backspace to detach it from the dojo prompt. Now, add `foo.txt` to the root of your `%home` `desk` and `|commit %home`. You should see:
360++ /~zod/home/266/foo/txt
363+As you can see we've received no `%writ`. We can thus conclude the subscription has successfully been cancelled.
365+Run `:spider|kill` to stop the thread.
367+Here's a breakdown of the `task` we sent:
369+
373+See the [Write and Modify](@/docs/arvo/clay/tasks.md#write-and-modify) section of the [API Reference](@/docs/arvo/clay/tasks.md) document for general details.
377+Here we'll look at adding a file by sending Clay a `%info` `task` containing a `%ins` `miso`.
379+Using the `send-task.hoon` thread, let's try adding a `foo.txt` file with 'foo' as its contents:
382+> -send-task [%info %home %& [/foo/txt %ins %txt !>(~['foo'])]~]
383++ /~zod/home/5/foo/txt
386+If you have a look in the home of your pier you'll see there's now a file called `foo.txt` with the text `foo` in it.
388+We've created the `cage` of the content like `[%txt !>(~['foo'])]`, if you want to write something besides a text file you'd just give it the appropriate `mark` and `vase`.
390+Here's a breakdown of the `task` we sent:
392+
396+Here we'll look at deleting a file by sending Clay a `%info` `task` containing a `%del` `miso`.
398+Using the `send-task.hoon` thread, let's try deleting the `foo.txt` file created in the [previous example](#ins):
401+> -send-task [%info %home %& [/foo/txt %del ~]~]
402+- /~zod/home/6/foo/txt
405+If you have a look in the home of your pier you'll see the `foo.txt` file is now gone.
407+Here's a breakdown of the `task` we sent:
409+
413+Identical to the [%ins](#ins) example, just replace `%ins` with `%mut`.
417+Here we'll look at changing multiple files in one request by sending Clay a `%info` `task` containing multiple `miso` in the `soba`.
419+Since `soba` is just a `list` of `miso`, you can add a bunch of `miso` and they'll all be applied. This thread adds three files and then deletes them. Here there's only one type of `miso` in each request but you could mix different types together too.
426+=, strand=strand:spider
431+=/ soba-a :~ [/foo/txt %ins %txt !>(['foo' ~])]
432+ [/bar/txt %ins %txt !>(['bar' ~])]
433+ [/baz/txt %ins %txt !>(['baz' ~])]
435+=/ soba-b :~ [/foo/txt %del ~]
439+;< ~ bind:m (send-raw-card:strandio [%pass /info %arvo %c %info %home %& soba-a])
440+;< ~ bind:m (send-raw-card:strandio [%pass /info %arvo %c %info %home %& soba-b])
444+Save to `ted/multi-change.hoon`, `|commit %home`, and run:
448++ /~zod/home/37/foo/txt
449++ /~zod/home/37/bar/txt
450++ /~zod/home/37/baz/txt
451+- /~zod/home/38/foo/txt
452+- /~zod/home/38/bar/txt
453+- /~zod/home/38/baz/txt
458+See the [Manage Mounts](@/docs/arvo/clay/tasks.md#manage-mounts) section of the [API Reference](@/docs/arvo/clay/tasks.md) document for general details.
462+Here we'll look at requesting the list of existing mount points on a ship by sending Clay a `%boat` `task` and receiving a `%hill` `gift`.
464+Using the `send-task-take-gift.hoon` thread, let's make such a request:
467+> -send-task-take-gift [%boat ~]
473+Here we'll look at mounting `desk`s, directories and files to unix by sending Clay a `%mont` `task`.
475+Using the `send-task.hoon` thread, let's first try mounting our `%kids` desk:
478+> -send-task [%mont %kids [our %kids da+now] /]
481+If you look in your pier, you should now see a `kids` folder which contains the contents of that `desk`.
483+If we make a `%boat` request as detailed in the [%boat](#boat) section, we'll now see the mount point listed:
486+> -send-task-take-gift [%boat ~]
487+[%hill p=~[%kids %home]]cruz gift. It looks like:
489+[%cruz cez=(map @ta crew)] :: permission groups
490+The cez is just a map from group name to crew
493+Note the mount point doesn't need to match a `desk`, file or directory. We can also do:
496+> -send-task [%mont %wibbly-wobbly [our %home da+now] /]
499+And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` `desk`. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.
501+Let's try mounting a subdirectory and a single folder:
504+> -send-task [%mont %gen [our %home da+now] /gen]
505+> -send-task [%mont %hi [our %home da+now] /gen/hood/hi]
508+If you look in your pier you'll now see a `gen` folder with the contents of `/gen` and a `hi.hoon` file by itself. Notice how the file extension has been automatically added.
512+Here we'll look at unmounting `desk`s, directories and files by sending Clay a `%ogre` `task`.
514+Using the `send-task.hoon` thread, let's unmount what we mounted in the [%mont](#mont) section. First we'll unmount the `%kids` desk:
517+-send-task [%ogre %kids]
520+Our custom mount point `%wibbly-wobbly`:
523+-send-task [%ogre %wibbly-wobbly]
526+And the single `hi.hoon` we previously mounted by specifying its mount point `%hi`:
529+-send-task [%ogre %hi]
532+If we specify a non-existent mount point it will fail with an error printed to the dojo like:
535+> -send-task [%ogre %kids]
539+If we give it an unmounted `beam` it will not print an error but still won't work.
543+Here we'll look at committing changed files by sending Clay a `%dirk` `task`.
545+With your `%home` `desk` mounted, try adding a file and, using the `send-task.hoon` thread, send a `%dirk` to commit the change:
548+> -send-task [%dirk %home]
549++ /~zod/home/12/foo/txt
552+Clay will print the changed files to the dojo with a leading `+`, `-` or `:` to indicate a new file, deleted file and changed file respectively.
554+If you have the same `desk` mounted to multiple points, a committed change in one mount will also update the others.
558+See the [Merge Desks](@/docs/arvo/clay/tasks.md#merge-desks) section of the [API Reference](@/docs/arvo/clay/tasks.md) document for general details.
562+Here we'll look at merging `desk`s by sending Clay a `%merg` `task` and receiving a `%mere` `gift` in response.
564+First, using the `send-task-take-gift.hoon` thread, let's try creating a new `desk`:
567+> -send-task-take-gift [%merg %foo our %home da+now %init]
571+Now if we scry for our `desk`s we'll see `%foo` is there:
574+> .^((set desk) %cd /===)
578+Next, we'll create a merge conflict and try a couple of things. Mount `%foo` with `|mount /=foo=`, then add a `foo.txt` to both `desk`s but with different text in each and `|commit` them.
580+Now we'll try merging `%home` into `%foo` with a `%mate` strategy:
583+> -send-task-take-gift [%merg %foo our %home da+now %mate]
591+ q=~[[%rose p=[p="/" q="/" r=""] q=[i=[%leaf p="foo"] t=[i=[%leaf p="txt"] t=~]]]]
599+As you can see, the merge has failed. Let's try again with a `%meld` strategy:
602+> -send-task-take-gift [%merg %foo our %home da+now %meld]
603+[/foo [%clay [%mere p=[%.y p={/foo/txt}]]]]
606+Now the merge has succeeded and the `%mere` notes the file with a merge conflict. If we try with a `%only-that` strategy:
609+> -send-task-take-gift [%merg %foo our %home da+now %only-that]
610+[/foo [%clay [%mere p=[%.y p={}]]]]
611+: /~zod/foo/6/foo/txt
614+...you can see it's overwritten the `foo/txt` in the `%foo` `desk` and the `%mere` now has an empty `set`, indicating no merge conflicts.
616+Next, let's look at subscribing for future changes. Since the `case` is specified explicitly in the `%merge` `task`, we can set it in the future:
619+> -send-task-take-gift [%merg %foo our %home da+(add ~m2 now) %only-that]
622+Now change the text in the `foo.txt` in the `%home` `desk`, hit backspace to detach the thread and `|commit %home`. After the two minutes pass you should see:
625+[/foo [%clay [%mere p=[%.y p={}]]]]
626+: /~zod/foo/7/foo/txt
629+You can also specify it by revision number or label.
633+See the [Permissions](@/docs/arvo/clay/tasks.md#permissions) section of the [API Reference](@/docs/arvo/clay/tasks.md) document for general details.
637+Here we'll look at setting permissions by sending Clay a `%perm` `task`.
639+First, using the `send-task.hoon` thread, let's try allow `~nes` to read `/gen/hood/hi/hoon`:
642+> -send-task [%perm %home /gen/hood/hi/hoon %r ~ %white (sy [%.y ~nes]~)]
645+...and we'll do a `%p` scry to see that the permission was set:
648+> .^([r=dict:clay w=dict:clay] %cp /===/gen/hood/hi/hoon)
649+[r=[src=/gen/hood/hi/hoon rul=[mod=%white who=[p={~nes} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]
652+You can see that `~nes` is now in the read whitelist. Next, let's try a write permission:
655+> -send-task [%perm %home /ted %w ~ %white (sy [%.y ~nes]~)]
658+You can see `~nes` can now write to `/ted`:
661+> .^([r=dict:clay w=dict:clay] %cp /===/ted)
662+[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ted rul=[mod=%white who=[p={~nes} q={}]]]]
665+Since we've set it for the whole `/ted` directory, if we check a file inside it we'll see it also has this permission:
668+> .^([r=dict:clay w=dict:clay] %cp /===/ted/aqua/ames/hoon)
669+[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ted rul=[mod=%white who=[p={~nes} q={}]]]]
672+...and you'll notice that `src` tells us it's inherited the rule from `/ted`.
674+Now let's try setting both read and write permissions:
677+> -send-task [%perm %home /gen/help/hoon %rw `[%black (sy [%.y ~nes]~)] `[%white (sy [%.y ~nes]~)]]
681+ .^([r=dict:clay w=dict:clay] %cp /===/gen/help/hoon)
682+[r=[src=/gen/help/hoon rul=[mod=%black who=[p={~nes} q={}]]] w=[src=/gen/help/hoon rul=[mod=%white who=[p={~nes} q={}]]]]
685+Lastly, let's look at deleting a permission rule we've previously set. To do that, we just send a null `(unit rule)` in the `rite`.
687+For example, to remove a read permission (or write if you specify `%w`):
690+> -send-task [%perm %home /gen/help/hoon %r ~]
694+> .^([r=dict:clay w=dict:clay] %cp /===/gen/help/hoon)
695+[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/gen/help/hoon rul=[mod=%white who=[p={~nes} q={}]]]]
698+...and to remove both read and write at the same time:
701+> -send-task [%perm %home /gen/help/hoon %rw ~ ~]
705+> .^([r=dict:clay w=dict:clay] %cp /===/gen/help/hoon)
706+[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]
709+As you can see it's back to the default inherited from `/`.
711+Here's a breakdown of a `%perm` task:
713+
717+Here we'll look at creating a permission group by sending Clay a `%cred` `task`.
719+Using the `send-task.hoon` thread, try:
722+-send-task [%crew 'foo' (sy ~[~zod ~nec ~bud ~wes ~sev])]
725+We'll check it with the next kind of `task`: [%crew](#crew).
729+Here we'll look at retrieving permission groups by sending Clay a `%crew` `task` and receiving a `%cruz` `gift` in response.
731+Let's check, using the `send-task-take-gift.hoon` thread, for the permission group created in the [%cred](#cred) example:
734+> -send-task-take-gift [%crew ~]
735+[%cruz cez={[p=~.foo q={~nec ~bud ~wes ~zod ~sev}]}]
740+Here we'll look at retrieving a list of all files and directories in all `desk`s which have permissions set for a group by sending Clay a `%crow` `task` and receiving a `%croz` `gift` in response.
742+First we'll set a couple of permissions for the `foo` group we created in the [%cred](#cred) section using the `send-task.hoon` thread:
745+> -send-task [%perm %home /gen/hood/hi/hoon %w ~ %white (sy [%.n 'foo']~)]
746+> -send-task [%perm %home /ted %w ~ %white (sy [%.n 'foo']~)]
749+Notice we use a `%.n` in the `whom` to indicate a group rather than the `%.y` of a ship.
751+Now we'll use the `send-task-take-gift.hoon` thread to try `%crow`:
754+> -send-task-take-gift [%crow 'foo']
761+ { [p=/gen/hood/hi/hoon q=[mod=%white who={[%.n p=~.foo]}]]
762+ [p=/ted q=[mod=%white who={[%.n p=~.foo]}]]
772+See the [Foreign Ships](@/docs/arvo/clay/tasks.md#foreign-ships) section of the [API Reference](@/docs/arvo/clay/tasks.md) document for general details.
776+Here we'll look at reading files on a foreign ship by sending Clay a `%warp` `task` with a foreign ship in the `wer` field and receiving a `%writ` `gift` in response.
778+We'll use a fake ~nes as the the foreign ship and a fake ~zod as the local ship.
780+First we'll set permissions on the foreign ship. Create a file called `foo.txt` in the `%home` of ~nes. Using the `send-task.hoon` thread, send a `%perm` request to allow ~zod to read and write the file:
783+> -send-task [%perm %home /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]
786+If we scry the file for its permissions with a `%p` `care`, we'll see ~zod is now whitelisted:
789+> .^([r=dict:clay w=dict:clay] %cp /===/foo/txt)
790+[r=[src=/foo/txt rul=[mod=%white who=[p={~zod} q={}]]] w=[src=/foo/txt rul=[mod=%white who=[p={~zod} q={}]]]]
793+Back on ~zod: Using the `send-task-take-gift.hoon` thread, send a `%x` read request for `/foo/txt` on ~nes like:
796+> -send-task-take-gift [%warp ~nes %home ~ %sing %x da+now /foo/txt]
800+ [ p=[p=%x q=[%da p=~2021.5.3..08.24.22..9ce7] r=%home]
802+ r=[p=%txt q=[#t/txt=*'' q=[7.303.014 0]]]
808+As you can see, we've received a `%writ` containing the requested data just as we would with a local request. Let's try a `%u`:
811+> -send-task-take-gift [%warp ~nes %home ~ %sing %u da+now /foo/txt]
815+ [ p=[p=%u q=[%da p=~2021.5.3..08.26.32..88cf] r=%home]
817+ r=[p=%flag q=[#t/?(%.y %.n) q=0]]
823+If we send a `%d` request however, it will crash:
826+> -send-receive-task [%warp ~nes %home ~ %sing %d da+now /foo/txt]
828+/sys/vane/clay/hoon:<[4.085 3].[4.314 5]>
830+/sys/vane/clay/hoon:<[1.365 7].[1.365 51]>
831+[ %clay-bad-foreign-request-care
832+ [%sing mood=[care=%d case=[%da p=~2021.5.3..20.04.57..1092] path=/foo/txt]]
834+/sys/vane/clay/hoon:<[1.365 48].[1.365 50]>
839+To merge a foreign `desk` into a local one, you just send Clay a `%merg` `task` (as you would for a local merge) and specify the foreign ship in the `her` field. For an example, see the [%merg](#merg) section.
841+The foreign ship will respond only if correct permissions have been set. See the [%perm](#perm) section for an example.