PK-Docs 1.0: Revamping tutorials/Getting Started Documentation

docs/README.md

@@ -5,16 +5,25 @@ displayed_sidebar: docs
 
 # Polykey Documentation
 
-Welcome to the Polykey documentation.
+<!-- Web of Trust that has a blockchain wallet feeling to it
 
-The documentation is structured using [Divio system](https://documentation.divio.com/).
+- Introduce the Polykey network (have some sort of media)
+  - a pk agent needs to run for a specified node.
+  - this allows the node the agent is running for, to communicate through the network
+    - you can share vaults b/w nodes that contain secrets
+    - You can more easily discovery, trust, and grant permissions to nodes
+    - you can push/pull secrets in the vaults
+    - secrets are encrypted at rest and in transit
+ -->
 
-- [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](./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
+ <!-- Polykey-CLI usage 
 
-<img src="/images/divio_quadrant.png" width="100%" />
+ - breakdown some functionality 
+ - The CLI on your machine is somewhat of an entry point to Polykey because it's how you familiarize yourself better with the functionality but mostly because it lets you become a node operator  -->
+
+<!-- Polykey Client Library
+
+- this will be where most of the innovation and value from PK comes from, integrating a free and open-source secrets manager in your deployed applications for running secrets management operations  -->
 
 ## Introduction
 
@@ -30,10 +39,6 @@ Polykey helps yourself, teams and software agents to manage and share secrets in
 
 PolyKey is an open-source decentralised peer to peer secrets management system. It provides a software agent that runs on your device locally. Each agent process is a node in the Polykey peer to peer network. This agent manages your secret data and is capable of sharing secrets with other trusted Polykey agents. The secret data can be placed inside any directory on your computer including on USB storage.
 
-## Features
-
-TBD
-
 ## Principles
 
 There are 2 main concepts to understand in Polykey:
@@ -71,6 +76,38 @@ As you deploy more Polykey agents, you can join existing gestalts.
 
 Your gestalt is how other users are able to share secrets with a trusted identity. Your identity is the sum of the reputation of all your digital identities that are part of the gestalt.
 
-## Comparison to other Tools
+<!-- I deleted the instructions for downloading the CLI repo source code... should mention it here.
+
+I deleted instructions on how to contribute. We should have that somewhere else.
+
+  </TabItem>
+
+  <TabItem value="source" label="Source">
+
+## Source
+
+The official source repository is on GitHub. There is an additional mirror on GitLab.
+
+```shell
+git clone https://github.com/MatrixAI/Polykey-CLI.git
+```
+
+Use `npm install` to setup the project.
+
+:::tip
+
+If you have `nix-shell` available, enter into `nix-shell` and it will automatically setup the development environment.
+
+:::
+
+  </TabItem> -->
+
+<!-- ---
+
+We need to have a sepererate section on installing Polykey-CLI on docker
+
+ <TabItem value="docker" label="Docker">
+
+
 
-TBD
+  </TabItem> -->

docs/tutorials/polykey-cli/installation.md → docs/getting-started/installing-polykey-cli.md

@@ -1,20 +1,55 @@
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Installation
+# Set-Up Polykey on your Machine
 
-Installing the CLI can be done in different ways depending on your operating environment.
+:::note
+The Polykey Command Line Interface (CLI) is the primary user interface for the Polykey system. We designed the CLI user-experience (UX) to be suitable for a human operator, but also to be easily scripted and integrated into other tools. It is intended for developers and system administrators who require an advanced tool for managing secrets efficiently.
+:::
+
+## Choose Your Installation Method for the Polykey-CLI
+
+<Tabs>
+
+ <TabItem value="npm" label="NPM CLI Installation Method" default>
+
+### Install using Node Package Manager
+
+The Polykey CLI is available as an [`npm` package](https://www.npmjs.com/package/polykey-cli). This method allows for easy installation across various operating systems using Node.js and npm.
 
 :::info
 
-Polykey-CLI has only been tested on Linux and macOS. We are working on supporting other platforms. There's minor teething problems when it comes supporting other platforms. Help us by reporting any issues with the CLI tool in our Github Repo [here](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) or by dropping a message to the developers in our discord server [here](https://discord.gg/dC32r35TeE).
+#### System Requirements
+
+Before installing, ensure your system meets the following requirements:
+
+- Node.js: Install the latest stable version of Node.js from nodejs.org
+- npm (Node Package Manager): Comes with Node.js, but verify it’s updated by running `npm install -g npm` in your terminal.
+- Environment Variables: Add the `npm` binary path to your system’s `$PATH` to run Polykey CLI from any terminal window.
 
 :::
 
+#### Install the Polykey-CLI using this single command
+
+To install the Polykey CLI globally on your system, execute the following command:
+
+```sh
+npm install -g polykey-cli
+```
+
+**This command installs Polykey CLI globally, allowing you to access it with `pk` or `polykey` from any directory in your command line.**
+
+  </TabItem>
+
+<TabItem value="manual" label="Manual CLI Installation Method">
+
+### Install Manually
+
 <Tabs>
-  <TabItem value="linux" label="Linux" default>
 
-## Linux
+  <TabItem value="linux" label="Linux">
+
+#### Linux
 
 Polykey-CLI code is compiled, bundled and wrapped into a single file executable. You just have to download the executable, give it executable permissions and run it. The executable is not statically linked. It requires a subset of the system libraries that Node.js requires.
 
@@ -25,7 +60,7 @@ Polykey-CLI code is compiled, bundled and wrapped into a single file executable.
 - `libpthread.so.0`
 - `libc.so.6`
 
-### Manually
+##### Manually
 
 Builds for Linux is released on GitHub: https://github.com/MatrixAI/Polykey-CLI/releases.
 
@@ -37,9 +72,9 @@ Make it executable:
 chmod u+x ./polykey
 ```
 
-### Add it to your `$PATH`.
+#### Add it to your `$PATH`.
 
-#### For ZSH:
+##### For ZSH:
 
 1. `cd` into directory where polykey exec is stored.
 2. Edit the zsh config to add polykey to your path, to streamline the process, run the following command making sure to change the path to polykey if the polykey executable is not in the downloads folder.
@@ -59,7 +94,7 @@ You can now run it with `polykey`.
 
 ---
 
-#### For Bash:
+##### For Bash:
 
 1. If you're using Bash, run the following command to add polykey to your path. Ensure to change the path if the executable is not in the downloads folder. For most users, this would be `~/downloads` on Debian-based systems.
 
@@ -77,7 +112,7 @@ You can now run it with `polykey`.
 
 ---
 
-### NixOS
+#### NixOS
 
 We have not yet published a Nixpkgs expression for Polykey. When we do, you will be able to just install `polykey-cli` from Nixpkgs.
 
@@ -101,14 +136,14 @@ Build the application and install it into the user profile:
 nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)"
 ```
 
-### Other
+#### Other
 
 We will be working on other distribution methods.
 
   </TabItem>
   <TabItem value="macos" label="MacOs">
 
-## MacOS
+#### MacOS
 
 :::info
 
@@ -117,7 +152,7 @@ However, building Polykey yourself on MacOS resolves in a working binary. Follow
 
 :::
 
-### Manually
+#### Manually
 
 1. Download the Polykey CLI for macOS from the [GitHub releases page](https://github.com/MatrixAI/Polykey-CLI/releases). Look for the file named `polykey-cli-V.V.V-darwin-universal`, where `V.V.V` is the version number. For Mac, you want to download the file with the `darwin-universal` file extension.
 
@@ -142,7 +177,7 @@ chmod +x polykey
 
 ---
 
-### MacOS Security Bypass
+#### MacOS Security Bypass
 
 MacOS requires additional steps for the binary to be allowed to execute,
 this is due to the fact that as of 20-12-23, the binaries we release are unsigned,
@@ -151,7 +186,8 @@ and MacOS permits running of unsigned binaries, however, to progress past this,
  <Tabs>
       <TabItem value="method1" label="Method #1 - Admin CLI ">
 
-      #### Method #1 - quickest method
+##### Method #1 - quickest method
+
 The xattr command will remove the quarantine attribute from the polykey executable, allowing you to run it without triggering macOS security warnings. Remember to ensure that the file path matches the location of your polykey file.
 
 ```sh
@@ -167,7 +203,7 @@ If you have completed this sucesfully, you may ignore Method #2 and move to the
 </TabItem>
 <TabItem value="method2" label="Method #2 - Apple Setting GUI">
 
-#### Method #2 - Using the Apple Systems Settings GUI
+##### Method #2 - Using the Apple Systems Settings GUI
 
 First type the following command to try running the Polykey CLI but will instead trigger a pop-up.
 
@@ -203,7 +239,7 @@ When prompted in the terminal, type your administrator password and hit enter.
 
 ![install3](/images/mac-install3.png)
 
-#### Click on Open and now Polykey-CLI should be running in your terminal window.
+##### Click on Open and now Polykey-CLI should be running in your terminal window.
 
 :::tip
 You can also verify the version of polykey that was installed with:
@@ -219,14 +255,14 @@ You can also verify the version of polykey that was installed with:
 </TabItem>
 </Tabs>
 
-### Add Polykey to your `$PATH`.
+#### Add Polykey to your `$PATH`.
 
 To enable running the Polykey CLI from any directory in the terminal on macOS, you'll need to update your shell configuration file.
 
 <Tabs>
       <TabItem value="zsh" label="ZSH (default shell on recent macOS versions)">
 
-#### For ZSH (default shell on recent macOS versions):
+##### For ZSH (default shell on recent macOS versions):
 
 1. Navigate (cd) into the directory where the "polykey" executable is stored.
 
@@ -245,7 +281,7 @@ echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc
 </TabItem>
  <TabItem value="bash" label="Bash">
 
-#### For Bash:
+##### For Bash:
 
 1. `cd` into the directory where the "polykey" executable is stored.
 2. Edit the Bash config to add "polykey" to your path. To streamline the process, run the following command, making sure to change the path to "polykey" if the executable is not in the downloads folder. For most users, this would be `~/downloads` on Debian-based systems.
@@ -285,9 +321,14 @@ Polykey for windows should be working but we have yet to create documentation on
 :::
 
   </TabItem>
-  <TabItem value="docker" label="Docker">
 
- ## Docker
+  </Tabs>
+
+  </TabItem>
+
+   <TabItem value="Docker" label="Install PK CLI on Docker" >
+
+## Installing PK CLI on Docker
 
 The Docker image can be used so that Polykey can be deployed into the cloud. It is also possible to use the CLI via the docker container, but it isn't as convenient. The intention is to run the Polykey agent in the cloud.
 
@@ -367,42 +408,47 @@ recoveryCode	net elephant gentle eight pulp oyster panther sing own autumn silly
 
 ```
 
-  </TabItem>
-  <TabItem value="npm" label="npm">
+   </TabItem>
 
-## Node Package Manager
+</Tabs>
 
-The CLI is published as [`npm` package](https://www.npmjs.com/package/polykey-cli).
+## Setting Up Your First Node
 
-Install it with:
+When you run the `polykey agent start` for the first time after installing the CLI, it begins a bootstrapping process for you.
+:::info
+Bootstrapping is the process where the Polykey agent sets itself up as a new Polykey node. This involves creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain.
+:::
 
-```sh
-npm install -g polykey-cli
-```
+<Tabs>
 
-This will install the Polykey-CLI into `$(npm config get prefix)`.
+ <TabItem value="Foreground" label="Run it in the Foreground" default>
 
-If the `npm` bin path is added to the `$PATH` environment variable, then you will be able to execute `pk` or `polykey`.
+### Starting the PK agent in the Foreground
 
-  </TabItem>
-  <TabItem value="source" label="Source">
+ </TabItem>
 
-## Source
+ <TabItem value="Background" label="Run it in the Background (optional)" default>
 
-The official source repository is on GitHub. There is an additional mirror on GitLab.
+### Starting the PK agent in the Background
 
-```shell
-git clone https://github.com/MatrixAI/Polykey-CLI.git
-```
+</TabItem>
 
-Use `npm install` to setup the project.
+</Tabs>
 
-:::tip
+Bootstrapping is the process where the Polykey agent sets itself up as a new Polykey node. This involves creating the encrypted-at-rest node state, and connecting to the [mainnet](https://mainnet.polykey.com/) or a custom specified network domain.
 
-If you have `nix-shell` available, enter into `nix-shell` and it will automatically setup the development environment.
+<!-- <Tabs>
 
-:::
+ <TabItem value="foreground" label="NPM CLI Installation Method" default> -->
 
-  </TabItem>
+### Starting the Polykey Agent
 
-</Tabs>
+You can start the Polykey agent in the foreground of your terminal by running:
+
+```bash
+polykey agent start
+```
+
+:::note
+Running the agent in the foreground allows you to monitor its output directly in the terminal. Ensure this terminal session remains active to keep the agent running. You can execute Polykey commands from any other terminal session while this runs.
+:::

docs/tutorials/polykey-cli/README.md → docs/getting-started/polykey-cli/README.md

@@ -35,15 +35,15 @@ Start your journey with Polykey by following the tutorials below in sequence:
 For a visual walkthrough, check out our [getting started demo video](https://vimeo.com/884649667) after installing Polykey.
 :::
 
-1. **[Installation](/docs/tutorials/polykey-cli/installation)** - Install Polykey CLI on your platform.
-2. **[Bootstrap Keypair](/docs/tutorials/polykey-cli/bootstrapping)** - Set up your node and connect to the network.
-3. **[Managing Vaults](/docs/tutorials/polykey-cli/managing-vaults)** - Securely store secrets within encrypted vaults.
-4. **[Managing Secrets](/docs/tutorials/polykey-cli/managing-secrets)** - Organize and handle secrets within your vaults.
-5. **[Claiming Digital Identities](/docs/tutorials/polykey-cli/claiming-digital-identities)** - Establish and authenticate your identity within the network.
-6. **[Discovering Other User's Identities](/docs/tutorials/polykey-cli/discovering-other-users)** - Find and verify other users to manage permissions.
-7. **[Sharing Vaults](/docs/tutorials/polykey-cli/sharing-vaults)** - Share your encrypted vaults securely with peers.
-8. **[Managing Multiple Nodes](/docs/tutorials/polykey-cli/managing-multiple-nodes)** - Operate multiple local nodes/agents.
-9. **[Using Environment Variables](/docs/tutorials/polykey-cli/using-environment-variables)** - Master `polykey secrets env` for dynamic environment management.
+1. **[Installation](/docs/getting-started/polykey-cli/installation)** - Install Polykey CLI on your platform.
+2. **[Bootstrap Keypair](/docs/getting-started/polykey-cli/bootstrapping)** - Set up your node and connect to the network.
+3. **[Managing Vaults](/docs/getting-started/polykey-cli/managing-vaults)** - Securely store secrets within encrypted vaults.
+4. **[Managing Secrets](/docs/getting-started/polykey-cli/managing-secrets)** - Organize and handle secrets within your vaults.
+5. **[Claiming Digital Identities](/docs/getting-started/polykey-cli/claiming-digital-identities)** - Establish and authenticate your identity within the network.
+6. **[Discovering Other User's Identities](/docs/getting-started/polykey-cli/discovering-other-users)** - Find and verify other users to manage permissions.
+7. **[Sharing Vaults](/docs/getting-started/polykey-cli/sharing-vaults)** - Share your encrypted vaults securely with peers.
+8. **[Managing Multiple Nodes](/docs/getting-started/polykey-cli/managing-multiple-nodes)** - Operate multiple local nodes/agents.
+9. **[Using Environment Variables](/docs/getting-started/polykey-cli/using-environment-variables)** - Master `polykey secrets env` for dynamic environment management.
 
 Explore advanced scenarios in subsequent sections, including: