@@ -27,6 +27,10 @@ Use `=var` to save a shell variable:
2727
2828 ~fintud-macrep:dojo> =foo (add 2 2)
2929
30+Use `=dir` to set the current working directory:
31+
32+ ~fintud-macrep:dojo> =dir %/web
33+
3034Generators (files in `/gen`) are run with `+`:
3135
3236 ~fintud-macrep:dojo> +hello 'world'
@@ -35,30 +39,169 @@ Save output to a file in `%clay` with `*`:
3539
3640 ~fintud-macrep:dojo> *foo/bar/hoon 'hello world'
3741
38−A system command to `:hood` using `|`:
42+Run system commands from `:hood`, like `reload`, using `|`:
3943
4044 ~fintud-macrep:dojo> |reload %eyre
4145
42−# dir
43−
4446## Manual
4547
46−# special vars
48+<h3 class="first child">Sources and sinks</h3>
49+
50+A dojo command is either a source or a sink. A source is just something that can be printed to your console or the result of some computation. A sink is an *effect*: a change to the filesystem, a network message, a change to your environment, or typed message to an app.
51+
52+Sources can be chained together, but we can only produce one effect per command.
53+
54+### Sinks
55+
56+### `=` - Set variable
57+
58+Set any envronment variable:
59+
60+ ~fintud-macrep:dojo> =foo 42
61+ ~fintud-macrep:dojo> (add 2 foo)
4762
48−# command prefixes
63+ 44
4964
50−### `:` send to app
65+(There are a few special variables that the dojo expects. See below.)
5166
52−Send a poke message to `:square` as an `atom` mark:
67+### `:` - Send to app
5368
54− ~fintud-macrep:dojo> :~fintud-macrep/square &atom (add 2 2)
69+ ~fintud-macrep:dojo> :hood &helm-hi 'hi'
5570
56−### `.` download to Unix
71+### `*` - Save in `%clay`
72+
73+ ~fintud-macrep:dojo> *%/web/foo/md '# hello'
74+
75+### `.` - Download to Unix
5776
5877Download a noun to Unix with `.`:
5978
6079 ~fintud-macrep:dojo> .foo/bar/baz (add 2 2)
6180
62−# generators
81+### Sources
82+
83+### `&` - Mark conversion
84+
85+### `_` - Run a function
86+
87+ _trip &html &md 'foo'
88+
89+### `+` `-` - HTTP requests
90+
91+ +http://google.com is get
92+ +http://google.com &json (joba %a ~) is post {a:null}
93+ -http://localhost:6000/foobar &json (joba %a ~) is put {a:null}
94+
95+ +curl "http://google.com?q={(urle "my params")}"
96+ the trivial generator that sends a get request, the baseline on which you could write a scraper
97+
98+### `+` - Generators
99+
100+### `[1 2 +hello 'world']` - Tuples
101+
102+<h3 class="first child">Variables</h3>
103+
104+You can use `=` to set an environment variable in `:dojo`, but there are a few reserved names that have special uses.
105+
106+#### `dir`
107+
108+Current working `%clay` desk and revision. Read / write.
109+
110+**Examples:**
111+
112+ ~fintud-macrep:dojo> =dir %/web
113+ ~fintud-macrep:dojo> +ls %
114+
115+ 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
116+
117+#### `lib`
118+
119+Current set of libraries (`/lib`) in your environment. Can also be set with `/+`. Read / write.
120+
121+**Examples:**
122+
123+ ~fintud-macrep:dojo> =lib ~[[%react ~]]
124+ ~fintud-macrep:dojo> :: this also works:
125+ ~fintud-macrep:dojo> /+ react
126+ ~fintud-macrep:dojo> :: now we can use arms from lib/react.hoon
127+ ~fintud-macrep:dojo> (react-vale:react %div)
128+
129+#### `sur`
130+
131+Current set of structures (`/sur`) in your environment. Can also be set with `/-`. Read / write.
132+
133+**Examples:**
134+
135+ ~fintud-macrep:dojo> =sur ~[[%sole ~]]
136+ ~fintud-macrep:dojo> :: this also works:
137+ ~fintud-macrep:dojo> /- sole
138+ ~fintud-macrep:dojo> :: now we can use arms in sur/sole.hoon
139+ ~fintud-macrep:dojo> `sole-effect:sole`[%bel ~]
140+
141+#### `now`
142+
143+The current (128-bit `@da`) time. Read-only.
144+
145+**Example:**
146+
147+ ~fintud-macrep:dojo> now
148+
149+ ~2016.3.21..21.10.57..429a
150+
151+#### `our`
152+
153+The current urbit plot. Read-only.
154+
155+**Example:**
156+
157+ ~fintud-macrep:dojo> our
158+
159+ ~fintud-macrep
160+
161+#### `eny`
162+
163+256 bits of entropy. Read-only.
164+
165+**Example:**
166+
167+ ~fintud-macrep:dojo> eny
168+
169+ 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
170+
171+# Generators
172+
173+#### `+cat`
174+
175+#### `+curl` / `+curl-hiss`
176+
177+#### `+hello`
178+
179+#### `+ls`
180+
181+#### `+moon`
182+
183+#### `+pope`
184+
185+#### `+solid`
186+
187+#### `+ticket`
188+
189+#### `+tree`
190+
191+# Hood
192+
193+`|hi`
194+
195+`|ask`
196+
197+`|begin`
198+
199+`|link` / `|unlink`
200+
201+`|mass`
202+
203+`|reload`
204+
205+`|reset`
63206
64−# hood
207+`|start`