From bbc69d134f2f8d80dae6f01a04ccb8fae1cdc77a Mon Sep 17 00:00:00 2001
From: Max Howell <mxcl@me.com>
Date: Fri, 14 Apr 2023 05:49:34 -0400
Subject: [PATCH] Tweaks

---
 docs/get-started/install-tea.md |   6 +-
 docs/magic.md                   |   9 +-
 docs/using-tea/README.md        | 147 +++++++++++++++++++++++++++++---
 3 files changed, 148 insertions(+), 14 deletions(-)

diff --git a/docs/get-started/install-tea.md b/docs/get-started/install-tea.md
index e1cc1e7..0f5820f 100644
--- a/docs/get-started/install-tea.md
+++ b/docs/get-started/install-tea.md
@@ -6,7 +6,9 @@ The easiest way to install tea is with our installer:
 sh <(curl https://tea.xyz)
 ```
 
-> Using `fish`? Then: `sh <(curl https://tea.xyz | psub)`
+{% hint style="question" %}
+`fish` user? Then you need `sh <(curl https://tea.xyz | psub)` instead.
+{% endhint %}
 
 The script installs to `~/.tea` and sets up magic (we ask politely first).
 
@@ -57,11 +59,13 @@ Both aarch64 (arm64) and x86-64 for these platforms:
 * Linux glibc >=2.28 (consult [repology](https://repology.org/project/glibc/versions))
 * WSL >=2
 
+{% hint style="info" %}
 `linux-aarch64` builds are done using a dockerized Debian image on Apple arm64
 processors. We have tested and confirmed functionality on Raspberry Pi4 running
 Ubuntu 22.04.2 LTS, and it should work on similar 64-bit Pi Foundation hardware
 with a sufficient glibc, which should include the last several releases of
 Raspbian Linux. 32-bit CPU builds are not being done at this time.
+{% endhint %}
 
 We want to support Windows native and after that every platform; yes even
 your NAS and IoT devices. We’re going to get the above sorted first though.
diff --git a/docs/magic.md b/docs/magic.md
index 3467dad..4c5ce52 100644
--- a/docs/magic.md
+++ b/docs/magic.md
@@ -14,9 +14,13 @@ Magic is entirely optional, tea is still entirely usable without it.
 
 {% hint style="warning" %}
 Our “command not found” magic only works at a terminal prompt. Thus eg.
-VSCode won’t magically find `deno`. Shell scripts won’t automatically
+your editor won’t automagically install `deno`. Shell scripts won’t automatically
 install tools they try to run. This is intentional. *Magic should not lead
 to anarchy*.
+
+We try where possible to have tools magically *find* packages if they are
+already installed. Thus eg. VSCode will find your packages in your [developer
+environment]
 {% endhint %}
 
 Our magic means that tea packages are not generally accessible from the rest
@@ -95,3 +99,6 @@ Thus you can make a script that can effortlessly use any tool from the open
 source ecosystem. If they have tea installed it uses their installation, if
 not it installs everything (including tea itself) to a temporary sandbox
 that’s gone when the script completes.
+
+
+[developer environment]: /using-tea/developer-environments.md
\ No newline at end of file
diff --git a/docs/using-tea/README.md b/docs/using-tea/README.md
index 8f3d952..98ae582 100644
--- a/docs/using-tea/README.md
+++ b/docs/using-tea/README.md
@@ -1,28 +1,151 @@
 
-# Sandbox Usage
+`tea`’s magic means you just type the commands you want and `tea` takes care
+of installing the tools and all their dependencies automagically.
 
-Without any other setup, play with the tools you want temporarily:
+```sh
+$ node --eval 'console.log("node: hello world")'
+tea: installing node and its dependencies…
+node: hello world
+```
 
-`sh <(curl https://tea.xyz) +python.org +pip.pypa.io sh`
+{% hint style="info" %}
+Magic is optional, if you didn’t set it up, prefix with `tea`:
+
+```sh
+$ tea node --version
+tea: installing node and its dependencies…
+v19.8.1
+```
+{% endhint %}
+
+Most package managers only offer the (almost) latest version of tools. `tea`
+not only offers the latest versions immediately it knows you need to be able
+to pick and choose what versions of tools you use:
+
+```sh
+$ node^16 --version
+tea: installing nodejs.org^16
+v16.8.1
+```
+
+# Scripts
+
+`tea` typically knows what you need to run a script:
+
+```sh
+$ tea my-script.py
+tea: installing python…
+# tea executes the script
+```
+
+When the package requirements are more advanced you can inject packages into
+the script using `tea`’s +pkg syntax:
+
+```sh
+$ tea +python.org +gnu.org/coreutils my-script.sh
+tea: installing dependencies…
+# tea executes the script
+```
+
+{% hint style="info" %}
+Notably you can also use our one-liner:
+
+```sh
+$ sh <(curl tea.xyz) +python.org +gnu.org/coreutils https://example.com/my-script.sh
+```
+
+If the user has `tea` installed, the one-liner uses the already installed
+`tea`. If they don’t it *doesn’t install `tea`*; it does a temporary install
+without changing anything on their system.
+{% endhint %}
 
 
-# ... or With tea Installed
+# Sandboxes
 
-Same as above, but with 'tea' instead of the "sh <(...)", thus:
+An idiomatic use of `tea`’s underlying functionality is the ability
+to try out new projects in a temporary sandbox:
 
-`tea +python.org +pip.pypa.io sh`
+```sh
+$ tea +bun.sh sh
+```
+
+{% hint style="info" %}
+And of course, with our one-liner this becomes quite tweetable:
+
+```sh
+$ sh <(curl tea.xyz) tea +bun.sh sh
+```
+
+{% endhint %}
 
 
-# ... or With a [Developer Environment](https://docs.tea.xyz/features/developer-environments):
+# Developer Environments
 
-Add the tool dependencies to your dev docs and enter a shell where it's all available:
+With magic you can just step into a directory and tea ensures the correct
+versions of all the tools you need are loaded:
 
-`tea -E sh`
+```sh
+$ cd my-node-project
+$ node --version
+16.8.1
+$ cat .node-version
+16
+```
+
+For more details see the
+[Developer Environments](/features/developer-environments)
+documentation.
 
 
+# VSCode
 
-# ... and With [Magic](https://docs.tea.xyz/features/magic)
+If you installed tea’s magic then projects will magically find their tools.
 
-`cd my-sandboxed-project`
+At this time you will need to run `tea --sync --env` or `tea -SE` at least
+once to ensure the tools in the developer environment are installed first.
 
-... and everything is just _there_.
+# Other Editors
+
+If your editor checks the shell for its environment for project directories
+you’ll find that everything you need is readily installed. Otherwise our
+recommended solution is to create a symlink to `tea` with the name of the tool
+you need exposed to GUI tools like editors.
+
+```
+$ sudo ln -s ~/.tea/tea.xyz/v0/bin/tea /usr/local/bin/node
+$ /usr/local/bin/node
+tea: installing node…
+```
+
+Some tools (not all!) will work when called directly. All tools are installed
+into versioned, namespaced compartmentalized directories in `~/.tea`:
+
+```
+~/.tea/nodejs.org/v16.8.1/bin/node
+```
+
+We also create proxy version symlinks that can be useful for such tools:
+
+```
+$ ls ~/.tea/nodejs.org/
+v*    -> v16.8.1
+v16   -> v16.8.1
+v16.8 -> v16.8.1
+v16.8.1
+```
+
+
+# Updating Packages
+
+```sh
+$ tea --sync
+# ^^ updates the pantry
+```
+
+Synchronizing ensures the package definitions `tea` knows about are up to
+date. It doesn’t update any packages.
+
+```sh
+$ tea -S +nodejs.org
+# ^^ updates node
+```