ci: merge staging to master

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

@@ -30,24 +30,31 @@ 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
-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). :::
+:::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).
+
+:::
 
 ## Getting Started
 
 Start your journey with Polykey by following the tutorials below in sequence:
 
-:::tip For a visual walkthrough, check out our
+:::tip Tip
+
+For a visual walkthrough, check out our
 [getting started demo video](https://vimeo.com/884649667) after installing
-Polykey. :::
+Polykey.
+
+:::
 
 1. **[Installation](/docs/tutorials/polykey-cli/installation)** - Install
    Polykey CLI on your platform.

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

@@ -24,8 +24,20 @@ 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 +76,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 +93,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/tutorials/polykey-cli/claiming-digital-identities.md → 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, claiming a digital identity is a crucial step that allows users to
 establish their identity across various platforms and link these identities to
@@ -9,6 +9,8 @@ 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.
+Currently, we only support github as an identity provider, but we plan to add
+more in the future.
 
 ## Step 1: Authenticate with GitHub
 
@@ -31,8 +33,10 @@ 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
-command that you will use to start the authentication process.
+:::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
 polykey identities authenticate github
@@ -72,19 +76,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
-  a cryptographic link. This link is a verifiable method that proves the
-  ownership of your GitHub identity to anyone checking your Polykey gestalt
+- **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
-  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.
+-:::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
 
@@ -150,6 +154,12 @@ 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.
 
+:::note Note
+
+This information should not be modified or the claim might be invalidated.
+
+:::
+
 ## Understanding Gestalt Graphs
 
 In Polykey, claiming identities creates a **gestalt graph**—a dynamic,

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

@@ -39,9 +39,11 @@ polykey identities discover <gestaltId>
 polykey identities discover github.com:maverick
 ```
 
-This command adds the node associated with the GitHub username "maverick" to
-your discovery queue, allowing you to initiate interactions with this user.
-:::note
+:::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.
+
+:::
 
 ## Troubleshooting Discovery and Connection Issues
 
@@ -77,8 +79,6 @@ network.
 
 :::
 
-:::info
-
 ### Future Enhancements
 
 Polykey is actively working to enhance the discovery process by implementing
@@ -116,12 +116,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
 
@@ -197,8 +194,8 @@ polykey identities list
 
 ### Trusting and Untrusting Nodes
 
-You can explicitly trust or untrust a node to refine how notifications and
-access controls are handled:
+You can explicitly trust or untrust individual nodes or entire gestalts to
+refine how notifications and access controls are handled:
 
 ```bash
 polykey identities trust <gestaltId>

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

@@ -7,10 +7,16 @@ environment.
 
 :::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
+## Polykey Core Overview
+
+The Polykey CLI and core primarily use TypeScript for service logic, domain
+business operations, and persistence layers. While the main codebase is in
+TypeScript, some supporting libraries incorporate native C++ or Rust for
+platform‐specific functionality. This approach combines cross‐platform
+convenience with native performance optimizations. 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).
@@ -126,15 +132,15 @@ $ 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,
-building Polykey yourself on MacOS resolves in a working binary. Follow this
-guide below to manually build and install Polykey on macOS.
+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 +290,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 +422,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 +432,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)
 
 ```
 
@@ -433,7 +447,7 @@ The CLI is published as
 Install it with:
 
 ```sh
-npm install -g polykey-cli
+npm install polykey
 ```
 
 This will install the Polykey-CLI into the path pointed to by the command

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

@@ -41,8 +41,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,
@@ -69,7 +73,7 @@ specify a node path, so it automatically targets the default node path.
 **Shell B (for your new node, nodeB):**
 
 ```bash
-polykey agent super_start --node-path ./nodeB --background
+polykey agent start --node-path ./nodeB --background
 ```
 
 This command starts a new Polykey agent for nodeB in the background. The first