nick's suggestions

src/apis/terminal.md

@@ -1,4 +1,7 @@
 # Terminal API
+It is extremely rare for an app to have direct access to the terminal api.
+Normally, the terminal will be used to call scripts, which will have access to the process in question.
+For documentation on using, writing, publishing, and composing scripts, see the [terminal use documentation](../terminal.md), or for a quick start, the [script cookbook](../cookbook/writing_scripts.md).
 
 The Kinode terminal is broken up into two segments: a Wasm app, called `terminal:terminal:sys`, and a runtime module called `terminal:distro:sys`.
 The Wasm app is the central area where terminal logic and authority live.
@@ -21,7 +24,7 @@ For example, `hi:terminal:sys` can be shortened to just `hi` as in: `hi default-
 
 The other most commonly used script is `m:terminal:sys`, or just `m` - which stands for `Message`. `m` let's you send a request to any node or application like so:
 ```bash
-m john.os@proc:pkg:pub {"foo":"bar"}
+m john.os@proc:pkg:pub '{"foo":"bar"}'
 ```
 
 Note that if your process has the ability to message the `terminal` app, then that process can call any script - of which there may be many on a machine, so we cannot possibly write all of them down in this document.

src/cookbook/writing_scripts.md

@@ -7,7 +7,7 @@ When writing a script, you cannot control the `OnExit` behavior like you can wit
 - Scripts are registered in the `scripts.json` file instead of the `manifest.json` file
 
 ## Writing a Script
-Let's look at the simplest possible script: `echo`, which takes in an argument, and prints it out again:
+Consider the simplest possible script: `echo`, which takes in an argument, and prints it out again:
 ```rust
 use kinode_process_lib::{await_next_request_body, call_init, println, Address, Response};
 
@@ -30,21 +30,21 @@ fn init(_our: Address) {
     let _ = Response::new().body(args).send();
 }
 ```
-From writing applications, this should look very familiar - the imports, `wit_bindge::generate!`, `call_init!`, `init(our: Address)`, etc. are all exactly the same.
+From writing applications, this should look very familiar - the imports, `wit_bindgen::generate!`, `call_init!`, `init(our: Address)`, etc. are all exactly the same.
 The first unique thing about scripts is that we will have no `loop` where we `await_message`.
 Instead, our initial arguments will come from a single message from the terminal - which we get by calling `await_next_message_body()`.
 Next, all we do is `String`ify the message body, and print it out.
 
 Arbitrary logic can be put below `await_next_message_body` - just like an app, you can fire-off a number of requests, choose to await their responses, handle errors, etc. just like normal.
 
-In this case, we send a `Response` containing the arguments passed in.
-The `Response` let's us compose `echo` with other scripts via [piping](../terminal.md#piping-and-composing-scripts).
+In this case, `echo` sends a `Response` containing the arguments passed in.
+The `Response` enables composition of scripts via [piping](../terminal.md#piping-and-composing-scripts), so that the output of `echo` can serve as the input to the next program.
 Not every script needs to end with a `Response`.
-It would be valid to simply `println` the `args` and terminate, but this would mean that our script has no "return value" to compose with other scripts via pipes.
+It would be valid to simply `println` the `args` and terminate, but this would mean that the script has no "return value" to compose with other scripts via pipes.
 
 ## Publishing a Script
-Unlike processes accociated with a long-running application, which will be put into the `manifest.json`, scripts must be registered in a separate `scripts.json` file.
-While very similar, there are a few important differences; let's take a look at an example that could live in your packages `pkg/scripts.json` file:
+Unlike processes associated with a long-running application, which will be put into the `manifest.json`, scripts must be registered in a separate `scripts.json` file.
+While very similar, there are a few important differences; here's an example that could live in your packages `pkg/scripts.json` file:
 ```json
 {
     "echo.wasm": {
@@ -60,7 +60,7 @@ This `scripts.json` file corresponds to a package which publishes a single scrip
 The keys of this object are the process paths inside of the `pkg/` folder.
 The name of the script will be the file path, with `.wasm` taken off.
 The object that `echo.wasm` points to is very similar to `manifest.json`, with a few things removed, and `root` has been added:
-- `root` means that all the capabilities held by the `terminal:terminal:sys` are passed to this script. This is rarely needed.
+- `root` means that all the capabilities held by the `terminal:terminal:sys` are passed to this script (this is powerful, and rarely needed)
 - `public`: same as `manfiest.json` - corresponds to whether or not other processes can message `echo.wasm` without the messsaging cap
 - `requestNetworking`: same as `manfiest.json` - corresponds to whether or not this script will need to send messaages over the network
 - `requestCapabilities`: same as `manifest.json` - a list of capabilities that will be granted to this script on startup (NOTE if you have `root`, there is no reason to populate `requestCapabilities` as well)

src/terminal.md

@@ -3,7 +3,7 @@
 ## Commands
 
 All commands in the terminal are calling scripts - a special kind of process.
-KinodeOS comes pre-loaded with a number of scripts useful for debugging and everyday use.
+Kinode OS comes pre-loaded with a number of scripts useful for debugging and everyday use.
 These scripts are fully named `<SCRIPT>:terminal:sys` e.g `hi:terminal:sys`, but the distro [aliases](#alias---alias-a-script-name) these to short names, in this case just `hi`, for convenience.