diff --git a/docs/FAQ.md b/docs/FAQ.md
index e9f03ff..92ba025 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -55,7 +55,7 @@ as described in the above FAQ.
 ## What are these `^`, `~`, etc. symbols?
 
 tea adheres to [semantic versioning](https://semver.org), and uses
-[`semver`](https://github.com/npm/node-semver#versions) for parsing versions.
+[`semver`](https://devhints.io/semver) for parsing versions.
 
 ## How do I find available packages?
 
diff --git a/docs/magic.md b/docs/magic.md
index 4c5ce52..f1cc10d 100644
--- a/docs/magic.md
+++ b/docs/magic.md
@@ -65,7 +65,7 @@ Welcome to Node 16.7.0
 >
 ```
 
-We support appending [semver](semver.org) ranges:
+We support appending [semver](https://devhints.io/semver) ranges:
 
 ```sh
 $ ln -s tea node^14
diff --git a/docs/using-tea/developer-environments.md b/docs/using-tea/developer-environments.md
index c86ca10..b796b6e 100644
--- a/docs/using-tea/developer-environments.md
+++ b/docs/using-tea/developer-environments.md
@@ -72,6 +72,63 @@ deployments actually remain *more* stable.
 </details>
 
 
+## YAML Format
+
+Either via YAML front matter, or more explicitly with `tea.yaml` we support
+the following:
+
+```yaml
+dependencies:
+  npmjs.com: ^9
+  gnu.org/wget: ^1.2
+env:
+  NODE_ENV: dev
+```
+
+Dependencies use a fully-qualified (FQ) url format. This may seem unusual but there
+are millions of open source projects and any other naming scheme leads to
+Debian. We don’t want to be Debian.
+
+To discover FQ names you have a few options:
+
+1. `tea -n npm` will “dry-run” running `npm`, showing you its path. It’s path contains the FQ name.
+2. `tea pkg search foo` will search the pantry for fuzzy matches on `foo`
+3. https://tea.xyz/+/ has a search interface
+4. [tea/gui](https://tea.xyz/gui/) has a search interface
+
+{% hint style="info" %}
+The `^`, `~` symbols are [semantic-version constraints](https://devhints.io/semver).
+{% endhint %}
+
+### Additions for YAML Front Matter
+
+YAML Front Matter in scripts also supports specifying `args` as a string or
+array or literals. This can be useful for specifying more arguments to the
+interpreter, eg.
+
+```js
+#!/usr/bin/env tea
+/*---
+args:
+  deno --allow-env run
+---*/
+```
+
+The script name is inserted as the last argument.
+
+We also expand some moustaches such as `{{srcroot}}` and `{{home}}`.
+
+{% hint style="info" %}
+Notably you could also insert these arguments on the shebang:
+
+```sh
+#!/usr/bin/env -S tea deno --allow-env run
+```
+
+Though you need to call `env` with `-S` as its first argument.
+{% endhint %}
+
+
 ## Caveats
 
 We still need to do a bit of work here. We don’t install any packages when