docs: update modified documentation files

Author: xrissoula

docs/Getting-Started/polykey-cli/README.md

@@ -30,16 +30,20 @@ The CLI is open-source and available on GitHub:
 
 Polykey is continuously built and tested on:
 
-- Linux x64 / arm64
+- Linux x64
 - MacOS x64 / arm64
 - Windows x64
 - Docker
 
-:::note Polykey is currently in beta. Its interface is at various levels of
+:::note Note
+
+ Polykey is currently in beta. Its interface is at various levels of
 stability. So bear with us as we perfect its design. You can contribute by
 discussing with us on [Discord](https://discord.gg/h3UShM8WUN) or creating issue
 tickets in the
-[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). :::
+[Polykey-CLI repo on GitHub](https://github.com/MatrixAI/Polykey-CLI). 
+
+:::
 
 ## Getting Started
 

docs/Getting-Started/polykey-cli/bootstrapping.md

@@ -24,8 +24,17 @@ encryption and decryption of all node state and secret data managed by Polykey.
 You will be prompted to provide a root password. This password encrypts the root
 key.
 
-:::note Remember to keep your password in a secure location as you will need it
-each time you start the Polykey agent. :::
+:::note Note
+
+Remember to keep your password in a secure location as you will need it each time you start the Polykey agent.
+
+:::
+
+:::important
+
+Bootstrapping also returns a **recovery code**. This code is required to recover a node with the same ID, so it is critical that you store it safely and securely. If lost, node identity recovery will not be possible.
+
+:::
 
 ### Starting the Polykey Agent
 
@@ -64,7 +73,8 @@ If the Polykey agent does not terminate properly, you can force quit the process
 through the Activity Monitor on your machine. If you encounter this or any other
 issue, please consider making a
 [bug report](https://github.com/MatrixAI/Polykey-CLI/issues/new/choose) to help
-improve Polykey.
+improve Polykey. Please make sure to check for existing issues before creating a
+new one.
 
 ## Check Agent Status
 
@@ -80,19 +90,19 @@ including its connectivity and activity within the network.
 ### Example Output
 
 ```bash
-status           	LIVE
-pid              	96992
+sstatus           	LIVE
+pid              	20004
 nodeId           	vgijtpv0h8m1eajeir77g73muq88n5kj0413t6fjdqsv9kt8dq4pg
-clientHost       	::1
-clientPort       	54975
+clientHost       	127.0.0.1
+clientPort       	51980
 agentHost        	::
-agentPort        	60358
-upTime           	8
-startTime        	1716509093
-connectionsActive	3
-nodesTotal       	11
-version          	1.2.3-alpha.4-1-1
-sourceVersion    	1.2.3-alpha.4
+agentPort        	58078
+upTime           	120
+startTime        	1742186927
+connectionsActive	0
+nodesTotal       	2
+version          	1.21.4-1-1
+sourceVersion    	1.21.4
 stateVersion     	1
 networkVersion   	1
 ```

docs/Getting-Started/polykey-cli/claiming-digital-identities.md

@@ -1,4 +1,4 @@
-# Claiming Digital Identities: Establishing Identity Linkages in Polykey
+# Establishing Identity Linkages in Polykey
 
 In Polykey, claiming a digital identity is a crucial step that allows users to
 establish their identity across various platforms and link these identities to
@@ -8,7 +8,7 @@ cryptographic link to a publicly verifiable location.
 
 This tutorial will guide you through the steps to authenticate with GitHub and
 claim an identity using Polykey, enhancing security and streamlining identity
-verification, making it easier for other users to discover and trust your nodes.
+verification, making it easier for other users to discover and trust your nodes. Currently, we only support github as an identity provider, but we plan to add more in the future.
 
 ## Step 1: Authenticate with GitHub
 
@@ -31,7 +31,9 @@ polykey identities authenticate <providerId>
 `<providerId>`: The identifier for the digital identity provider, such as
 "github". :::
 
-:::note Since Polykey currently only supports GitHub as an IdP, this is the
+:::note Note
+
+Since Polykey currently only supports GitHub as an IdP, this is the
 command that you will use to start the authentication process.
 
 ```bash
@@ -72,19 +74,19 @@ identityId	maverick
 During the authentication process, here's what Polykey requests access to and
 why:
 
-- **Create Gists:** Polykey creates a gist under your GitHub account containing
+- **Currently: Create Gists:** Polykey creates a gist under your GitHub account containing
   a cryptographic link. This link is a verifiable method that proves the
   ownership of your GitHub identity to anyone checking your Polykey gestalt
   graph.
 
-- **Read All User Profile Data:** This enables Polykey to access your profile
+-:::note Note
+
+ **Future Plan: Read All User Profile Data:** This enables Polykey to access your profile
   details, including your username, followers, and public repository data. This
   information is used to ensure that the identity you claim corresponds
   accurately to your public digital footprint, enhancing trust and verification.
 
-- **Access User Email Addresses (read-only):** By accessing the email addresses
-  associated with your account, Polykey can better manage notifications related
-  to your secrets operations.
+  :::
 
 #### Security and Privacy Considerations
 
@@ -148,7 +150,13 @@ https://gist.github.com/my-github-username
 
 This gist contains the cryptographic link confirming that your Polykey identity
 is correctly linked to your GitHub profile. Viewing this gist ensures your claim
-was successful and publicly verifiable.
+was successful and publicly verifiable. 
+
+:::note Note
+
+This information should not be modified or the claim might be invalidated.
+
+:::
 
 ## Understanding Gestalt Graphs
 

docs/Getting-Started/polykey-cli/discovering-other-users.md

@@ -38,10 +38,11 @@ polykey identities discover <gestaltId>
 ```bash
 polykey identities discover github.com:maverick
 ```
-
+:::note Note
 This command adds the node associated with the GitHub username "maverick" to
 your discovery queue, allowing you to initiate interactions with this user.
-:::note
+
+:::
 
 ## Troubleshooting Discovery and Connection Issues
 
@@ -77,8 +78,6 @@ network.
 
 :::
 
-:::info
-
 ### Future Enhancements
 
 Polykey is actively working to enhance the discovery process by implementing
@@ -116,13 +115,9 @@ Permissions in Polykey determine what actions a node or an identity can perform
 within the network. Here’s a general list of potential permissions that can be
 managed:
 
-- **Read:** Allows viewing but not modifying.
-- **Write:** Allows both viewing and modifying.
-- **Execute:** Allows performing specific actions.
+- **Scan:** Allows the node to scan for vaults
 - **Notify:** Allows sending notifications about changes or updates.
-- **Trust:** Allows a node to be trusted, generally affecting how interactions
-  are secured.
-
+- **Claim** Allows a different gstalt to claim the node 
 #### Example Command to Set Permissions
 
 ```bash
@@ -197,7 +192,7 @@ polykey identities list
 
 ### Trusting and Untrusting Nodes
 
-You can explicitly trust or untrust a node to refine how notifications and
+You can explicitly trust or untrust individual nodes or entire gestalts to refine how notifications and
 access controls are handled:
 
 ```bash

docs/Getting-Started/polykey-cli/installation.md

@@ -126,13 +126,13 @@ $ nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(
 We will be working on other distribution methods.
 
   </TabItem>
-  <TabItem value="macos" label="MacOs">
+  <TabItem value="macOS" label="MacOS">
 
 ## MacOS
 
 :::info
 
-ARM-64 builds are not currently supported on MacOS as of **26-03-24.** However,
+ARM-64 builds are not currently supported on MacOS as of **6 April 2025.** However,
 building Polykey yourself on MacOS resolves in a working binary. Follow this
 guide below to manually build and install Polykey on macOS.
 
@@ -284,13 +284,21 @@ echo 'export PATH=~/Downloads:$PATH' >> ~/.zshrc && source ~/.zshrc
 </TabItem>
  <TabItem value="bash" label="Bash">
 
+:::tip
+
+The path export should not pint to the Polykey executable itself, but rather to
+the directory containing the executable. Otherwise, the executable will not be
+found and will not work. 
+
+:::
+
 #### 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.
+   this would be `~/Downloads` 
 
 :::tip
 
@@ -408,7 +416,7 @@ docker run -it 0e1addd9855a agent start --background -np /tmp/polykey
 Making sure to replace `0e1addd9855a` with your corresponding image ID.
 
 ```shell
- docker run -it  0e1addd9855a agent start --background -np /tmp/polykey
+$ docker run -it  0e1addd9855a agent start --background -np /tmp/polykey
 WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
 ✔ Enter new password … *
 ✔ Confirm new password … *
@@ -418,7 +426,7 @@ clientHost  	127.0.0.1
 clientPort  	45509
 agentHost   	::
 agentPort   	37468
-recoveryCode	net elephant gentle eight pulp oyster panther sing own autumn silly whip simple warfare daughter pepper detail bachelor awkward forget ignore cream silly raw
+recoveryCode	(random text recovery code goes here)
 
 ```
 

docs/Getting-Started/polykey-cli/managing-multiple-nodes.md

@@ -2,10 +2,7 @@
 
 Managing multiple local
 
-nodes in Polykey can serve various purposes. For example, you might maintain one
-node for personal projects and another for professional work. This segregation
-ensures that the vaults and their respective contents remain distinct based on
-their usage context.
+nodes in Polykey can serve various purposes. For example, you might maintain one node for personal projects and another for professional work. This segregation ensures that the vaults and their respective contents remain distinct based on their usage context.
 
 This approach is particularly advantageous for demonstrations or training
 purposes, as it allows you to simulate sharing vaults between two nodes on the
@@ -41,8 +38,12 @@ node we are starting an agent for. If unsure of the syntax to use for command
 operations, adding the --help at the end of each subcommand provides useful
 context.
 
-:::note If a node has not been created before, initializing the Polykey agent
-for it will also initiate the bootstrap process. :::
+:::note Note
+
+ If a node has not been created before, initializing the Polykey agent
+for it will also initiate the bootstrap process. 
+
+:::
 
 When working with multiple nodes, specifying the node path in each command can
 become cumbersome. To streamline this process in your terminal shell session,