feat(docs): launch revamp from the older branch

Author: CryptoTotalWar

.npmrc

@@ -11,7 +11,7 @@ The documentation is structured using [Divio system](https://documentation.divio
 
 - [Tutorials](./tutorials) - these are a series of steps to introduce Polykey to new beginners to achieve a practical outcome
 - [How-To Guides](/docs/how-to-guides) - these are short guides on how to achieve a specific use-case which makes assumptions on the reader
-- [Theory](./reference/) - these are important for understanding the "why" of Polykey
+- [Theory](./theory/) - these are important for understanding the "why" of Polykey
 - [Reference](./reference/) - these are useful when you need remember how to use a particular command or function
 
 <img src="/images/divio_quadrant.png" width="100%" />

docs/README.md

@@ -41,3 +41,49 @@ See for fast check usage, model checking, async model checking, concurrent model
 - https://github.com/MatrixAI/Polykey/issues/382
 - https://github.com/MatrixAI/Polykey/issues/382#issuecomment-1280285365
 - https://github.com/MatrixAI/Polykey/issues/382#issuecomment-1294353491
+
+---
+
+This guide is specifically designed for developers interested in contributing to the Polykey repository. It provides step-by-step instructions tailored for users on macOS, Windows, and Linux, outlining the necessary setup steps to prepare their development environment.
+
+Please note, this guide is distinct from the Polykey installation and usage documentation. It focuses solely on the initial setup required for contributing to the Polykey project, including the installation of development tools and the configuration of development environments.
+
+For detailed instructions on how to install and use Polykey, please refer to the official Polykey documentation.
+
+## macOS Setup Guide
+
+This section provides instructions for macOS users.
+
+### Installing Homebrew
+
+Homebrew is a package manager for macOS that simplifies the installation of software. To install Homebrew, follow the instructions on the [Homebrew website](https://brew.sh/).
+
+### Installing Git
+
+Git is a distributed version control system that is required for contributing to the repository. To install Git using Homebrew, open Terminal and run:
+
+`brew install git`
+
+### Installing GitHub CLI (gh)
+
+The GitHub CLI is a command-line tool that simplifies GitHub interactions. To install the GitHub CLI using Homebrew, open Terminal and run:
+
+`bash brew install gh`
+
+### Authenticating GitHub CLI
+
+After installing the GitHub CLI, you need to authenticate it with your GitHub account. To do this, open Terminal and run:
+
+`bash gh auth login`
+
+Follow the prompts to complete the authentication process.
+
+### Installing Git LFS
+
+Git LFS is a Git extension for versioning large files. To install Git LFS using Homebrew, open Terminal and run:
+
+`bash brew install git-lfs`
+
+After installing Git LFS, initialize it by running:
+
+`bash git lfs install`

docs/development-guide/development-environment.md

@@ -0,0 +1,60 @@
+# `polykey agent`
+
+## `start`
+
+Starts the Polykey Agent:
+
+Usage:
+
+```sh
+polykey agent start --background
+✔ Enter new password … ******
+✔ Confirm new password … ******
+pid    1585746
+nodeId    "v60g23b4b9g5tq2npc3kpikpalqqdpuvocegdd8bsdj28a1hsp0g0"
+clientHost    "::1"
+clientPort    35809
+agentHost    "::"
+agentPort    38197
+recoveryCode    "dynamic two gadget nature diet grass priority library reveal idle guess creek impact nasty impulse accuse surface walk history admit legend various joy mail"
+```
+
+## `stop`
+
+Stops the active Polykey Client:
+
+Usage:
+
+```sh
+polykey agent stop
+```
+
+## `unlock`
+
+Requests a new token and starts a new session.
+
+Usage;
+
+```sh
+polykey agent unlock
+```
+
+## `lock`
+
+Locks the Polykey client and clears the current session token.
+
+Usage:
+
+```sh
+polykey agent lock
+```
+
+## `lockall`
+
+Locks all Polykey clients and clear the current session token.
+
+Usage:
+
+```sh
+polykey agent lockall
+```

docs/reference/polykey-cli/commands/agent.md

@@ -1,14 +1,12 @@
-# bootstrap
+# `polykey bootstrap`
 
-A live keynode is a live process known as a PolyKey Agent process. A dead
-keynode consists of only the keynode state stored at the node path.
+Bootstraps the node state and sets up a key root pair.
 
-When launching the Polykey Agent, the node goes into a bootstrapping phase. This
-is where it constructs the keynode state. The keynode state is also known as the
-node path. This can exist in your operating system's user profile data.
+A live node is a live process known as a PolyKey Agent process.
 
-On Linux this would be `~/.local/share/polykey`. However you can select the
-exact location of the node path, it can be anywhere.
+A node consists of only the node state stored at the node path.
+
+On Linux this would be `~/.local/share/polykey`. However you can select the exact location of the node path, it can be anywhere.
 
 This location is where all the vault state, networking state, discovery state
 will be stored.
@@ -22,126 +20,21 @@ will do is to generate a root certificate and the root key consisting the root
 public key and root private key.
 
 The root private key needs to be password protected. The user must supply the
-root password in order to encrypt the root public key.
+root password in order to encrypt the root private key.
 
-The root certificate is an X.509 certificate. This certificate will serve as the
-secure digital identity of the keynode.
+The root certificate is an X.509 certificate. This certificate will serve as the secure digital identity of the node.
 
 The root public key which is encoded in the root certificate is the globally
-unique identity of the keynode. This is known as the node ID. The node ID is
-used to identify the node in the peer to peer distributed hash table .
-
-Our current root keys are RSA keys. Eventually we will move to using Ed25519 keys.
-Because our current root keys are RSA keys, they are very long. Our node IDs are
-therefore MD5 hashes of the PEM-encoded RSA public key. This is temporary until
-we have integrated Ed25519 keys, and our node IDs will be much shorter.
-
-Note that current modern websites tend to use ECDSA root keys, this is similar to
-Ed25519, but we will be looking to use Ed22519 instead of ECDSA in the future.
-
-Here are some examples.
-
-RSA:
+unique identity of the node. This is known as the node ID. The node ID is
+used to identify the node in the peer to peer network.
 
-```
-        Subject Public Key Info:
-            Public Key Algorithm: RSA
-                Public-Key: (4096 bit)
-                Modulus:
-                    b7:5b:b2:ca:29:f3:5b:21:b4:6a:d0:ec:42:d2:d6:
-                    b4:ce:73:69:38:cc:60:49:03:c5:d4:e0:64:9f:bb:
-                    f8:05:d0:26:f8:c2:bd:18:73:62:b6:ac:e5:b3:04:
-                    d4:31:0a:1b:19:7e:e8:2c:f1:01:0b:e1:48:dd:cc:
-                    37:44:ec:fc:85:6e:c5:51:78:1b:f7:58:c5:29:f9:
-                    b4:5a:65:73:0c:c7:d2:a0:e5:88:b6:38:c0:e2:f1:
-                    c3:2b:55:74:ce:ec:a0:63:e3:11:2f:02:b4:e4:e6:
-                    0a:5b:ab:83:8d:b7:e2:86:9c:06:54:5b:e8:13:75:
-                    26:57:8d:e6:a5:49:dc:a4:1a:48:b4:13:b3:56:27:
-                    19:76:96:b0:95:4d:da:a8:c4:d6:33:e3:eb:8c:34:
-                    af:b7:b9:41:a6:5d:52:25:44:9a:68:83:0a:29:2f:
-                    5d:5d:86:55:6c:31:d4:f5:06:ff:c4:ab:cf:af:67:
-                    cb:d2:ea:3b:c3:2d:0f:cd:72:c5:8c:4d:93:24:10:
-                    77:4e:48:59:98:b9:91:d9:59:3e:4e:5a:53:6e:27:
-                    e2:98:1a:78:35:47:f2:cb:3f:a4:14:ad:c0:a0:fd:
-                    4d:fb:b4:aa:e6:66:05:49:ef:45:a0:0d:52:b1:09:
-                    c7:40:76:85:af:b1:d0:7a:39:66:24:86:2c:49:fa:
-                    40:2f:98:af:91:ca:0d:6a:58:ef:7d:4b:3f:cd:f9:
-                    60:15:37:59:10:5c:e2:4a:c3:18:1d:ad:a9:b4:38:
-                    53:77:4f:48:ae:e4:e0:0a:27:e9:84:b0:cf:5e:6d:
-                    5c:30:61:b0:fa:c4:1d:33:d5:1b:13:0f:5a:c7:3a:
-                    d6:27:a3:da:bf:fb:bd:31:74:5f:8a:be:eb:02:c4:
-                    a8:b6:b4:64:c6:b0:43:9e:83:08:51:9d:81:30:0f:
-                    6c:5a:3e:cd:2c:1c:87:35:33:61:b2:d4:65:d9:b1:
-                    f2:28:71:8b:9c:ca:45:ae:53:6b:dd:9a:a6:77:af:
-                    56:84:79:65:10:6d:d0:f2:e0:8c:fa:d1:6f:57:e7:
-                    26:c0:e9:30:f6:34:61:b4:86:36:8b:5b:4e:47:2d:
-                    50:0d:dd:4e:8c:5d:5c:49:6e:2a:71:7c:d8:5d:8b:
-                    ab:46:73:ed:64:df:9b:3a:7d:11:92:e7:9f:da:9d:
-                    13:c0:86:2c:ef:83:63:76:95:12:c3:0d:a8:f9:e6:
-                    75:a4:df:60:86:98:5d:85:14:a7:0f:d2:b2:20:05:
-                    53:27:b0:d7:89:c2:a4:0e:4f:20:1c:89:02:ee:06:
-                    ff:ac:11:5b:30:a4:bd:35:cd:9a:6a:4f:c4:2c:01:
-                    56:58:94:e6:ca:30:3b:bf:14:6d:60:d7:90:02:98:
-                    04:79
-                Exponent: 65537 (0x10001)
-```
+The root key pair uses Ed25519 protocol.
 
-ECDSA:
+Usage:
 
+```sh
+polykey --node-path ./tmp/nodeZ bootstrap
+✔ Enter new password … *
+✔ Confirm new password … *
+rule budget game easily collect alone zoo panda clump advice drill area click enhance chicken raise sadness glare relief easily glove chicken draft draw
 ```
-        Subject Public Key Info:
-            Public Key Algorithm: ECDSA
-                Public-Key: (256 bit)
-                X:
-                    de:db:39:24:5f:4d:61:ed:2e:9b:2f:89:2c:9d:2e:
-                    7b:9d:56:28:3c:2e:4f:eb:71:cf:41:08:39:b8:25:
-                    e1:5a
-                Y:
-                    17:5d:2c:b9:e5:de:f9:e9:5e:17:02:8d:d3:e6:a7:
-                    a4:b4:25:42:c4:a9:8e:13:4b:4d:0a:50:35:6e:6f:
-                    67:b3
-                Curve: P-256
-```
-
-The root key is used to generate and encrypt symmetric vault keys. The vault
-keys will be used to encrypt the vault filesystems.
-
-After the root certificate, root keys are generated, and initial state
-directories are generated, the node enters the network bootstrapping phase.
-
-This means it will start a gRPC server listening on `0.0.0.0:1314`. This gRPC
-server is how the Polykey CLI and Polykey GUI and Polykey Browser Extension will
-communicate with the Polykey Agent.
-
-It will also start an uTP server on `0.0.0.0:1314` over UDP for NAT traversal.
-
-It will also start an HTTP 1.1 server on `0.0.0.0:1315` for HTTP integration.
-
-All keynodes are preconfigured to trust and contact the bootstrap keynode
-`bootstrap.polykey.com`. This in the future will likely be load balanced via
-both DNS load balancing and also TCP/UDP load balancing.
-
-The `bootstrap.polykey.com` is itself a Polykey keynode. This node is maintained
-by the official Polykey team. This nodes serves 3 duties:
-
-1. P2P DHT synchronisation to allow globally decentralised nodes to share their node table information
-2. STUN NAT traversal - to faciliate direct P2P connections between compatible nodes
-3. TURN Relay NAT traversal - to facilitate proxied P2P connections between incompatible nodes
-
-The first duty is the most important one. Without the `bootstrap.polykey.com`, it
-is not possible for nodes that are on separate subnets to discover each other.
-
-Users are able to run their own "bootstrap nodes". Corporate networks can run
-their own bootstrap nodes. You can override the bootstrap node configuration to
-point to other bootstrap nodes. You can pay us to run bootstrap nodes.
-
-The second and third duties are much more process intensive and is there to
-allow users of PolyKey to bust through NATs. NATs were developed to get around
-the limited amount of IPv4 addresses available. With IPv6 they are now
-considered obsolete. Some corporate networks may still use NATs as a
-rudimentary firewall. In the future, PolyKey will fully support IPv6 and the
-need for STUN or TURN NAT busting will be lessened.
-
-At this point the node is setup and fully operational. It is time to create
-vaults, put secrets into them, discover your friends and enemies, and share
-your vaults with them.