Merge pull request #226 from kinode-dao/hf/make-some-fixes

make some fixes throughout

README.md

@@ -7,6 +7,7 @@
 ```sh
 cargo install mdbook
 cargo install mdbook-linkcheck
+cargo install mdbook-webinclude
 
 mdbook serve
 ```

book.toml

@@ -13,3 +13,5 @@ enable = true
 level = 1
 
 [output.linkcheck]
+
+[preprocessor.webinclude]

src/apis/frontend_development.md

@@ -42,11 +42,17 @@ Your UI should be developed and compiled with the base URL set to the appropriat
 
 #### Vite
 
-In `vite.config.ts` (or `.js`) set `base` to your full process name, i.e. `base: '/my_process:my_package:template.os'`.
+In `vite.config.ts` (or `.js`) set `base` to your full process name, i.e.
+```
+base: '/my_process:my_package:template.os'
+```
 
 #### Create React App
 
-In `package.json` set `homepage` to your full process name, i.e. `homepage: '/my_process:my_package:template.os'`.
+In `package.json` set `homepage` to your full process name, i.e.
+```
+homepage: '/my_process:my_package:template.os'
+```
 
 ### Proxying HTTP Requests
 
@@ -59,7 +65,10 @@ Follow the `server` entry in the [kit template](https://github.com/kinode-dao/ki
 
 #### Create React App
 
-In `package.json` set `proxy` to your Kinode's URL, i.e. `proxy: 'http://localhost:8080'`.
+In `package.json` set `proxy` to your Kinode's URL, i.e.
+```
+proxy: 'http://localhost:8080'
+```
 
 ### Making HTTP Requests
 

src/apis/kinode_wit.md

@@ -16,17 +16,17 @@ To see exactly how to use WIT to write Kinode processes, see the [My First App](
 To see `kinode.wit` for itself, see the [file in the GitHub repo](https://github.com/kinode-dao/kinode-wit/blob/master/kinode.wit).
 Since this interface applies to all processes, it's one of the places in the OS where breaking changes are most likely to make an impact.
 To that end, the version of the WIT file that a process uses must be compatible with the version of Kinode OS on which it runs.
-We intend to achieve perfect backwards compatibility upon first major release (1.0.0) of the OS and the WIT file.
+Kinode DAO intends to achieve perfect backwards compatibility upon first major release (1.0.0) of the OS and the WIT file.
 After that point, since processes signal the version of the WIT file they use, subsequent updates can be made without breaking existing processes or needing to change the version they use.
 
 ## Types
 
-[These 14 types](https://github.com/kinode-dao/kinode-wit/blob/373542a9a94ae61a7d216159f9f7bdf9266cd935/kinode.wit#L8-L103) make up the entirety of the shared type system between processes and the kernel.
+[These 15 types](https://github.com/kinode-dao/kinode-wit/blob/758fac1fb144f89c2a486778c62cbea2fb5840ac/kinode.wit#L8-L106) make up the entirety of the shared type system between processes and the kernel.
 Most types presented here are implemented in the [process standard library](../process_stdlib/overview.md) for ease of use.
 
 ## Functions
 
-[These 15 functions](https://github.com/kinode-dao/kinode-wit/blob/373542a9a94ae61a7d216159f9f7bdf9266cd935/kinode.wit#L105-L184) are available to processes.
+[These 16 functions](https://github.com/kinode-dao/kinode-wit/blob/758fac1fb144f89c2a486778c62cbea2fb5840ac/kinode.wit#L108-L190) are available to processes.
 They are implemented in the kernel.
 Again, the process standard library makes it such that these functions often don't need to be directly called in processes, but they are always available.
 The functions are generally separated into 4 categories: system utilities, process management, capabilities management, and message I/O.

src/apis/terminal.md

@@ -1,4 +1,5 @@
 # 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).
@@ -14,18 +15,27 @@ This is a powerful capability, equivalent to giving an application `root` author
 For this reason, users are unlikely to grant direct terminal access to most apps.
 
 If one does have the capability to send `Request`s to the terminal, they can execute commands like so:
-`script_name:package_name:publisher_name <ARGS>`
+```
+script_name:package_name:publisher_name <ARGS>
+```
 
-For example, the `hi` script, which pings another node's terminal with a message, can be called like so: `hi:terminal:sys default-router-1.os what's up?`.
+For example, the `hi` script, which pings another node's terminal with a message, can be called like so:
+```
+hi:terminal:sys default-router-1.os what's up?
+```
 In this case, the arguments are both `default-router-1.os` and the message `what's up?`.
 
 Some commonly used scripts have shorthand aliases because they are invoked so frequently.
-For example, `hi:terminal:sys` can be shortened to just `hi` as in: `hi default-router-1.os what's up?`.
+For example, `hi:terminal:sys` can be shortened to just `hi` as in:
+```
+hi default-router-1.os what's up?
+```
 
-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
+The other most commonly used script is `m:terminal:sys`, or just `m` - which stands for `Message`.
+`m` lets you send a request to any node or application like so:
+```
 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.
+Note that if your process has the ability to message the `terminal` app, then that process can call any script.
 However, they will all have this standard calling convention of `<script-name> <ARGS>`.

src/apis/websocket.md

@@ -8,7 +8,7 @@ The process receives the `channel_id` for pushing data into the WebSocket, and a
 
 To open a WebSocket channel, connect to the main route on the node `/` and send a `WsRegister` message as either text or bytes.
 
-The simplest way to connect from a browser is to use the `@uqbar/client-encryptor-api` like so:
+The simplest way to connect from a browser is to use the `@kinode/client-api` like so:
 
 ```rs
 const api = new KinodeEncryptorApi({
@@ -22,7 +22,7 @@ const api = new KinodeEncryptorApi({
 })
 ```
 
-`@uqbar/client-encryptor-api` is available here: [https://www.npmjs.com/package/@uqbar/client-encryptor-api](https://www.npmjs.com/package/@uqbar/client-encryptor-api)
+`@kinode/client-api` is available here: [https://www.npmjs.com/package/@kinode/client-api](https://www.npmjs.com/package/@kinode/client-api)
 
 Simple JavaScript/JSON example:
 

src/chess_app/chat.md

@@ -235,7 +235,7 @@ A simple demonstration of how to extend the functionality of a given process.
 There are a few key things to keep in mind when doing this, if you want to build stable, maintainable, upgradable applications:
 
 - By adding chat, you changed the format of the "chess protocol" implicitly declared by this program.
-If a user is running the old code, their version won't know how to handle the new `Message` request type we added.
+If a user is running the old code, their version won't know how to handle the new `Message` request type you added.
 **Depending on the serialization/deserialization strategy used, this might even create incompatibilities with the other types of requests.**
 This is a good reason to use a serialization strategy that allows for "unknown" fields, such as JSON.
 If you're using a binary format, you'll need to be more careful about how you add new fields to existing types.

src/chess_app/chess_engine.md

@@ -36,12 +36,12 @@ fn init(our: Address) {
 }
 ```
 
-Now, we have access to a chess board and can manipulate it easily.
+Now, you have access to a chess board and can manipulate it easily.
 
 The [pleco docs](https://github.com/pleco-rs/Pleco#using-pleco-as-a-library) show everything you can do using the pleco library.
 But this isn't very interesting by itself!
-We want to play chess with other people.
-Let's start by creating a persisted state for the chess app and a `body` format for sending messages to other nodes.
+Chess is a multiplayer game.
+To make your app multiplayer, start by creating a persisted state for the chess app and a `body` format for sending messages to other nodes.
 
 In `my_chess/src/lib.rs` add the following simple Request/Response interface and persistable game state:
 ```rust
@@ -90,7 +90,7 @@ The `ChessState` `struct` shown above can also be persisted using the `set_state
 Note that the `Game` `struct` here has `board` as a `String`.
 This is because the `Board` type from pleco doesn't implement `Serialize` or `Deserialize`.
 We'll have to convert it to a string using `fen()` before persisting it.
-Then, we will convert it back to a `Board` with `Board::from_fen()` when we load it from state.
+Then, you will convert it back to a `Board` with `Board::from_fen()` when you load it from state.
 
 The code below will contain a version of the `init()` function that creates an event loop and handles ChessRequests.
 First, however, it's important to note that these types already bake in some assumptions about our "chess protocol".

src/chess_app/putting_everything_together.md

@@ -3,10 +3,10 @@
 After adding a frontend in the previous chapter, your chess game is ready to play.
 
 Hopefully, you've been using `kit build <your_chess_app_name>` to test the code as the tutorial has progressed.
-If not, do so now in order to get a compiled package we can install onto a node.
+If not, do so now in order to get a compiled package you can install onto a node.
 
 Next, use `kit start-package <your_chess_app_name> -p <your_test_node_port>` to install the package.
-You should see the printout we added to `init()` in your terminal: `chess by <your_node_name>: start`.
+You should see the printout you added to `init()` in your terminal: `chess by <your_node_name>: start`.
 
 Remember that you determine the process names via the `manifest.json` file inside `/pkg`, and the package & publisher name from `metadata.json` located at the top level of the project.
 Open your chess frontend by navigating to your node's URL (probably something like `http://localhost:8080`), and use the names you chose as the path.

src/chess_app/setup.md

@@ -1,11 +1,11 @@
 # Environment Setup
 
 To prepare for this tutorial, follow the environment setup guide [here](../my_first_app/chapter_1.md), i.e. [start a fake node](../my_first_app/chapter_1.md#booting-a-fake-kinode-node) and then, in another terminal, run:
-```bash
+```
 kit new my_chess
 cd my_chess
 kit build
 kit start-package
 ```
 
-Once you have the template app installed and can see it running on your testing node, continue to the next chapter...
+Once you have the template app installed and can see it running on your testing node, continue to the next chapter...

src/cookbook/file_transfer.md

@@ -542,7 +542,7 @@ let mut file: Option<File> = None;
 let mut size: Option<u64> = None;
 ```
 
-And then in the main loop we pass it to `handle_message()`:
+And then in the main loop, pass it to `handle_message()`:
 
 ```rust
 struct Component;
@@ -726,7 +726,7 @@ WorkerRequest::Size(incoming_size) => {
 
 One more thing: once you're done sending, you can exit the process; the worker is not needed anymore.
 Change your `handle_message()` function to return a `Result<bool>` instead telling the main loop whether it should exit or not.
-As a bonus, we can add a print when it exits of how long it took to send/receive!
+As a bonus, you can add a print when it exits of how long it took to send/receive!
 
 ```rust
 fn handle_message(

src/cookbook/writing_scripts.md

@@ -30,9 +30,10 @@ fn init(_our: Address) {
 }
 ```
 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.
+The first unique thing about scripts is that they have no `loop` over `await_message`.
+Instead, the initial arguments will come from a single message from the terminal.
+`process_lib` provides a convenience function, `await_next_message_body()`, to make it easy to read.
+Next, simply `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.
 

src/design_philosophy.md

@@ -34,7 +34,7 @@ Those features include:
 
 The above properties are achieved by governance.
 Successful protocols launched on Kinode will be ones that decentralize their governance in order to maintain these properties.
-We believe that systems that don't proactively specify their point of control will eventually centralize, even if unintentionally.
+Kinode DAO believes that systems that don't proactively specify their point of control will eventually centralize, even if unintentionally.
 The governance of Kinode itself must be designed to encourage decentralization, playing a role in the publication and distribution of userspace software protocols.
 In practice, this looks like an on-chain permissionless App Store.
 
@@ -50,4 +50,4 @@ Our current architecture relies on the following systems:
 - Wasmtime: a standalone Wasm runtime
 
 In addition, Kinode is inspired by the [Bytecode Alliance](https://bytecodealliance.org/) and their vision for secure, efficient, and modular software.
-We make extensive use of their tools and standards.
+Kinode DAO makes extensive use of their tools and standards.

src/hosted-nodes.md

@@ -5,7 +5,7 @@ These hosted Kinodes are useful for both end users and developers.
 This guide is largely targeted at developers who want to develop Kinode applications using their hosted Kinode.
 End users may also find the [Managing Your Kinode](#managing-your-kinode) section useful.
 
-Here, we use `ssh` extensively.
+Here, `ssh` is used extensively.
 This guide is specifically tailored to `ssh`s use for the Kinode hosting service.
 A more expansive guide can be found [here](https://www.digitalocean.com/community/tutorials/ssh-essentials-working-with-ssh-servers-clients-and-keys).
 

src/http_server_and_client.md

@@ -18,6 +18,8 @@ At startup, the server either:
 
 The server then binds this port, listening for HTTP and WebSocket requests.
 
+You can find usage examples [here](./cookbook/talking_to_the_outside_world.md).
+
 ## Private and Public Serving
 
 All server functionality can be either private (authenticated) or public.

src/identity_system.md

@@ -45,4 +45,4 @@ The main takeaway for the identity system is that _domain provenance_ and _domai
 
 Like .eth for ENS, the KNS domain space is fixed inside the `.os` top-level domain.
 However, Kinode DAO has the right to manage domains, including domains other than `.os`, so domain availability is likely to expand in the future (subject to governance decisions).
-Eventually, we hope to link various TLDs to existing NFT communities and other identity systems.
+Eventually, Kinode DAO hopes to link various TLDs to existing NFT communities and other identity systems.

src/install.md

@@ -5,19 +5,18 @@ After acquiring the software, you can learn how to run it and [Join the Network]
 
 - If you are just interested in starting development as fast as possible, skip to [My First Kinode Application](./build-and-deploy-an-app.md).
 - If you want to run a Kinode without managing it yourself, use the [Valet](https://valet.kinode.org) hosted service.
-- If you want to make edits to the Kinode core software, see [Build From Source](#build-from-source).
+- If you want to make edits to the Kinode core software, see [Build From Source](#option-3-build-from-source).
 
 ## Option 1: Download Binary (Recommended)
 
-The Kinode DAO distributes pre-compiled binaries for Ubuntu and MacOS.
+The Kinode DAO distributes pre-compiled binaries for MacOS and Linux Debian derivatives, like Ubuntu.
 
 First, get the software itself by downloading a [precompiled release binary](https://github.com/kinode-dao/kinode/releases).
 Choose the correct binary for your particular computer architecture and OS.
 There is no need to download the `simulation-mode` binary — it is used behind the scenes by [`kit`](./kit/boot-fake-node.md).
 Extract the `.zip` file: the binary is inside.
 
 Note that some operating systems, particularly Apple, may flag the download as suspicious.
-While the binary has not been tested exhaustively on all Linux distributions, it should _just work_.
 
 ### Apple
 
@@ -29,7 +28,7 @@ Then, go to `System Settings > Privacy and Security` and click to `Open Anyway`
 ## Option 2: Docker
 
 Kinode can also be run using Docker.
-Linux and MacOS are supported.
+MacOS and Debian derivatives of Linux, like Ubuntu, are supported.
 Windows may work but is not officially supported.
 
 ### Installing Docker
@@ -93,13 +92,13 @@ If your system doesn't already have `cmake` and OpenSSL, download them:
 
 #### Linux
 
-```sh
+```bash
 sudo apt-get install cmake libssl-dev
 ```
 
 #### Mac
 
-```sh
+```bash
 brew install cmake openssl
 ```
 

src/kit/boot-fake-node.md

@@ -18,7 +18,7 @@ You can start a network of fake nodes that can communicate with each other (but
 You'll need to start a new terminal for each fake node.
 For example, to start two fake nodes, `fake.dev` and `fake2.dev`:
 
-```
+```bash
 kit boot-fake-node
 
 # In a new terminal

src/kit/chain.md

@@ -11,11 +11,11 @@ The default port is `8545` and the chain ID is `31337`.
 ## Discussion
 
 `kit chain` starts an anvil node with the arguments `--load-state kinostate.json`.
-This json file includes the [KNS](https://github.com/kinode-dao/KNS) & app_store contracts, and is included in the `kit` binary.
+This json file includes the [KNS](https://github.com/kinode-dao/KNS) & `app_store` contracts, and is included in the `kit` binary.
 
-The [kinostate.json](https://github.com/kinode-dao/kit/blob/master/src/chain/kinostate.json) file can be found written into /tmp/kinode-kit-cache/kinostate-{hash}.json upon running the command.
+The [kinostate.json](https://github.com/kinode-dao/kit/blob/master/src/chain/kinostate.json) file can be found written into `/tmp/kinode-kit-cache/kinostate-{hash}.json` upon running the command.
 
-Note that while the kns_indexer and app_store apps in fake nodes use this chain to index events, any events loaded from a json statefile, aren't replayed upon restarting anvil.
+Note that while the `kns_indexer` and `app_store` apps in fake nodes use this chain to index events, any events loaded from a json statefile, aren't replayed upon restarting anvil.
 
 ## Arguments
 

src/kit/inject-message.md

@@ -2,7 +2,7 @@
 
 `kit inject-message` injects the given message to the node running at given port/URL, e.g.,
 
-```
+```bash
 kit inject-message foo:foo:template.os '{"Send": {"target": "fake2.os", "message": "hello world"}}'
 ```
 

src/kit/install.md

@@ -43,9 +43,14 @@ The first chapter of the [My First Kinode App tutorial](../my_first_app/chapter_
 
 ## Getting kit
 
+`kit` requires Rust.
 To get `kit`, run
 
-```
+```bash
+# Install Rust if you don't have it.
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+
+# Install `kit`.
 cargo install --git https://github.com/kinode-dao/kit --locked
 ```
 

src/kit/new.md

@@ -10,7 +10,7 @@ creates the default template (a Rust chat app with no UI) in the `foo/` director
 
 ## Example Usage
 
-```
+```bash
 # Create the default template: rust chat with no UI
 kit new my_rust_chat