PK-Docs: Getting Started | Home | PK-CLI | Docs 1.0 revamp PR

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/getting-started/claiming-digital-identities.md

@@ -0,0 +1,107 @@
+# Claim Your Digital Identity
+
+This guide demonstrates how to link your Polykey node to a GitHub identity, enhancing discoverability and trust within the network.
+
+<details>
+<summary>Why Link a GitHub Identity?</summary>
+Linking your Polykey node to GitHub improves discoverability and simplifies trust-building within the network by providing a familiar and verifiable identity.
+</details>
+
+## Prerequisites
+
+- Your default Polykey node must be installed and operational.
+- Have access to your GitHub credentials.
+
+<details>
+<summary>Handled Data and Privacy</summary>
+
+- **Technical Use of Permissions**: During the authentication process, Polykey requests access to create gists, read all user profile data, and access user email addresses (read-only) to ensure accurate identity verification and manage notifications.
+
+- **Security and Privacy Considerations**: Polykey adheres to high standards of security and privacy, using accessed data strictly for mentioned operations and not sharing it with third parties. For more details, refer to our [privacy policy](https://polykey.com/privacy-policy).
+</details>
+
+## Step 1: Authenticate with GitHub
+
+Initiate authentication with GitHub to allow your node to access necessary identity information.
+
+```pkcli
+polykey identities authenticate github.com
+```
+
+:::tip
+
+Follow the terminal prompts to log into GitHub and authorize Polykey to access your information.
+
+:::
+
+![GitHub Authentication](/images/github-authentication.png)
+
+## Step 2: Claim Your Identity
+
+Link your GitHub identity with your Polykey node to establish a verifiable identity connection.
+
+```pkcli
+polykey identities claim github.com:<my-gh-username>
+```
+
+:::tip
+Replace `my-gh-username` with your actual GitHub username.
+:::
+
+<img src="/images/cryptolink.png" alt="Cryptolink" style={{ width: '70%', height: 'auto' }} />
+
+## Step 3: Verify Your Claim
+
+Check the link to the GitHub gist provided by Polykey to verify your identity claim.
+
+![Claim Id](/images/claim-id.png)
+:::note
+Visit the gist URL to ensure it exists and is correct.
+:::
+
+## Understanding the Impact
+
+Claiming a GitHub identity creates a gestalt graph that enhances the discoverability of your node.
+
+![gestalts](/images/gestalts.png)
+
+<details>
+<summary>Learn More About Gestalt Graphs</summary>
+
+### Understanding Gestalt Graphs
+
+**Gestalt Graphs** are visual representations of the relationships and trust connections between different digital identities within Polykey. Each node on a graph symbolizes an identity or a claim, and the edges between nodes represent cryptographic verifications or trust relationships.
+
+#### How Gestalt Graphs Work
+
+- **Nodes**: Represent individual identities linked to Polykey, such as a GitHub username.
+- **Edges**: Signify the trust connections or verification links between various identities.
+
+As you expand your digital presence by claiming more identities, or by adding more nodes to your network, the gestalt graph grows accordingly. This dynamic expansion enhances the network's utility by streamlining the process of identity verification and making the establishment of trust relationships more transparent and traceable.
+
+#### Claiming Multiple Identities
+
+Polykey allows for flexible management of digital identities, accommodating multiple use cases:
+
+- **Multiple IdPs for a Single Node**: You can link one Polykey node to several identity providers, enhancing your digital verification pathways and security.
+- **Single IdP Across Multiple Nodes**: Claim and link the same identity provider, like a GitHub username, across multiple Polykey nodes you control, thus broadening your digital identity and reach within the network.
+
+#### Future Plans and IdP Support
+
+Currently, Polykey integrates with GitHub as a primary identity provider. Our ongoing development aims to broaden this integration to include various major identity providers (IdPs), significantly enhancing accessibility and user engagement. Future updates will also allow organizations to implement their own IdPs, offering even greater control and customization of identity management operations within Polykey.
+
+#### Benefits of Federated Identities
+
+Adopting a federated identity model through gestalt graphs provides several advantages:
+
+- **Enhanced Security**: Links multiple identity proofs to fortify the authenticity and credibility of your digital identity.
+- **Simplified Identity Management**: Manages multiple identities through a unified interface, reducing complexity and streamlining user interactions.
+- **Interoperability**: Facilitates seamless interactions across different platforms and services, leveraging a cohesive identity framework.
+
+Utilizing gestalt graphs within Polykey enhances operational security and simplifies digital identity management, making it an indispensable tool for users navigating complex digital environments.
+
+</details>
+
+## Conclusion
+
+Linking your GitHub identity with Polykey enhances both security and usability, making your digital interactions within the network more seamless and verifiable.