@powerhousedao/academy 3.2.0-dev.2 → 3.2.0-dev.4

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/07-DocumentTools/{00-DocumentToolbar.md → 00-DocumentToolbar.mdx}

@@ -2,11 +2,16 @@
 
 The Document Toolbar is a central component in Powerhouse Connect, appearing at the top of every document view. It provides quick access to a variety of tools and functions designed to streamline your workflow and enhance document management.
 
+<figure className="image-container">
+  <img src={require("./images/DocumentToolbar.png").default} alt="Document Toolbar" />
+  <figcaption>The Document Toolbar can be found at the top of any generic document.</figcaption>
+</figure>
+
 ## Overview
 
 The toolbar is designed to be intuitive and context-aware, offering relevant options based on the document type and your current task. Its capabilities range from basic actions to more advanced document control features.
 
-Key functionalities often include:
+### Key functionalities in the future will include:
 *   **Switchboard API Access:** Access the Switchboard API via its logo in the toolbar. This opens the Apollo Studio Sandbox, pre-populating the DocumentID for your current document model. This feature is unavailable for locally stored documents.
 *   **Navigation and Versioning:** Tools for managing [document versions](/academy/MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory), such as undo/redo, and accessing the [revision history timeline](/academy/MasteryTrack/BuildingUserExperiences/DocumentTools/RevisionHistoryTimeline).
 *   **Document Actions:** Buttons for common operations like exporting or deleting documents.
@@ -17,4 +22,4 @@ Key functionalities often include:
 
 The specific set of tools available on the toolbar can be configured and may evolve as new features are introduced. This section will detail the various components and options you may encounter.
 
-*(Detailed sections on each toolbar feature, such as "Export Button", "Title Display", "Search Functionality", "Toggle Switches", "Icon Buttons", etc., will follow here.)*
+*(Detailed information on each toolbar feature, such as "Export Button", "Title Display", "Search Functionality", "Toggle Switches", "Icon Buttons", etc., will follow here.)*

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/07-DocumentTools/01-OperationHistory.md

@@ -1,13 +1,13 @@
-# Operations History
+# Operations history
 
-## What Is a Document Model?
+## What is a document model?
 A **document model** in Powerhouse is the core unit for managing business data. Each document (such as an invoice, contributor agreement, or scope of work) is created from a specific document model, which defines:
 
 - **State schema:** What data the document contains
 - **Operations:** What actions can modify that document
 
-## What Is Operations History?
-Every time a user edits a document, they do so by submitting a document operation (e.g., `ADD_LINE_ITEM`, `UPDATE_RECIPIENT`). These operations are:
+## What is an operations history?
+Every time a user edits a document, they do so by submitting a document operation or a 'command' in CQRS (e.g., `ADD_LINE_ITEM`, `UPDATE_RECIPIENT`). These operations are:
 
 - **Appended** to the document's history
 - **Immutable** (you never overwrite; you always append)
@@ -15,14 +15,14 @@ Every time a user edits a document, they do so by submitting a document operatio
 
 This design is based on **event sourcing** principles.
 
-## Why Use an Operations History?
+## Why use an operations history?
 - **Auditability:** Inspect every change ever made to a document.
 - **Transparency:** Contributors see what others have done.
 - **Versioning:** Revert to any prior state or resolve conflicts using branching and merging.
 - **Interoperability:** Operations are just data—they can be signed, stored on-chain, or synchronized across systems.
 
 
-## Example: Invoice Document
+## Example: Invoice document
 Suppose you're editing a `powerhouse/invoice` document. Its operations history might look like this:
 
 ```plaintext
@@ -33,34 +33,34 @@ UPDATE_DUE_DATE(date: "2025-06-01")
 
 The document's state at any time is the result of running those operations in order.
 
-## Visualizing Operations History
+## Visualizing the operations history
 
-### Revision List and Details
+### Revision list and details
 In Connect the Powerhouse UI displays a chronologic list of all applied modifications to the document, each with a unique event ID, state hash, and commit message. You can inspect each revision for signatures and errors.
 
 ![Revision History List](./images/revision-history-list.png)
 
 
-### Viewing Revision Hashes and Event IDs
+### Viewing revision hashes and event IDs
 Hovering over a revision reveals its event ID and state hash, providing traceability for every change.
 
 ![Revision Hash Popup](./images/revision-hash-popup.png)
 
 
-### Signature Verification
+### Signature verification
 Clicking the signature badge shows signature details, including signer address, hash, and verification status. This ensures every operation is cryptographically auditable.
 Read more about how we are using [Renown](/academy/MasteryTrack/BuildingUserExperiences/Authorization/RenownAuthenticationFlow) for authentication & verification of signer data. 
 
 ![Signature Details Popup](./images/signature-details-popup.png)
 
 
-### Viewing Committer Addresses
+### Viewing committer addresses
 You can also view the committer's address for each revision, supporting full transparency and accountability.
 
 ![Committer Address Popup](./images/committer-address-popup.png)
 
 
-## Replay, Branch, and Merge (UNDER DEVELOPMENT)
+## Replay, branch, and merge (under development)
 - **Replay:** When you load a document, the system replays all operations to build its state.
 - **Branch:** Create a parallel version of the document to test changes or handle conflicts.
 - **Merge:** Combine branches intelligently based on operations, not just raw field values.

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/07-DocumentTools/02-RevisionHistoryTimeline.md

@@ -1,8 +1,8 @@
-# Revision History Timeline
+# Revision history timeline
 
-The timeline feature enables users to view document history and navigate through different revisions of a document. This guide explains how to implement and customize the timeline functionality in your Powerhouse application.
+The history timeline feature enables users to view document history and navigate through different revisions of a document. This guide explains how to implement and customize the timeline functionality in your Powerhouse application.
 
-## Enabling the Timeline Feature
+## How to enable the timeline feature
 
 To enable the timeline feature in your document editor, you need to set `timelineEnabled: true` in your editor module configuration:
 
@@ -23,9 +23,20 @@ export const module: EditorModule<ToDoDocument> = {
 
 This setting enables the timeline button in the document toolbar.
 
-## Implementation Options
+:::warning Heads Up! 
+The revision history timeline will only become visible once your document model has some operations or 'history'. 
+Add a few to-do's or some data in the model you are working on and the revision history timeline button in the Document Toolbar will be activated. 
+Click the button to see the timeline expand and see the first history 'candle' appear.
+:::
 
-### Default Drive Explorer
+<figure className="image-container">
+  <img src={require("./images/revision-history-timeline.png").default} alt="revision history timeline" />
+  <figcaption>Once your document has a few operations added to it's history the revision history timeline gets activated.</figcaption>
+</figure>
+
+## How to implement the timeline feature
+
+### Default drive explorer
 
 When using the default drive explorer with `ph connect`, the timeline functionality is handled automatically:
 
@@ -33,7 +44,7 @@ When using the default drive explorer with `ph connect`, the timeline functional
 - The timeline button appears in the toolbar when enabled
 - Users can click on timeline items to view document revisions
 
-### Custom Drive Explorer
+### Custom drive explorer
 
 For custom drive explorers, you need to handle timeline items fetching and user interaction manually. Here's how:
 
@@ -86,7 +97,7 @@ const [selectedTimelineItem, setSelectedTimelineItem] = useState<TimelineItem |
 />
 ```
 
-## Handling Timeline Revisions in Document Editor
+## Handling timeline revisions in document editor
 
 In your document editor (e.g., `editors/to-do-list/editor.tsx`), you need to handle the timeline context props:
 

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/08-Authorization/01-RenownAuthenticationFlow.md

@@ -1,34 +1,45 @@
-# Renown Authentication Flow
+# Renown authentication flow
 
 The Renown login flow leverages decentralized identity (DID) creation and the Ceramic network for credential storage and verification, ensuring secure and verifiable actions within decentralized organizations. Below is a detailed breakdown of the process, aimed at developers integrating the Renown, Connect, and Switchboard components.
 
 ### Renown in the decentralized workplace
-Renown provides a decentralized identity and reputation hub, where users connect their Ethereum address, creating a **Decentralized Identifier (DID)** tied to their wallet. Renown is designed to address the challenge of trust within DAOs, where contributors often operate under pseudonyms. In traditional organizations, personal identity and reputation are key to establishing trust and accountability. Renown replicates this dynamic in the digital space, allowing contributors to earn experience and build reputation without revealing their real-world identities. Over time, contributors can share their pseudonymous profiles with other organizations as cryptographic resumes, helping to secure new opportunities while maintaining privacy.
+Renown provides a decentralized identity and reputation hub, where users connect their Ethereum address, creating a **Decentralized Identifier (DID)** tied to their wallet.
 
-### Detailed Login Flow
+#### Why an integrated identity solution?
+Renown is designed to address the challenge of trust within DAOs, where contributors often operate under pseudonyms. In traditional organizations, personal identity and reputation are key to establishing trust and accountability. Renown replicates this dynamic in the digital space, allowing contributors to earn experience and build reputation without revealing their real-world identities. Over time, contributors can share their pseudonymous profiles with other organizations as cryptographic resumes, helping to secure new opportunities while maintaining privacy.
 
-#### 1. User Login via Wallet Connection
+### Detailed login flow
+
+#### 1. User login via wallet connection
 - The user starts by logging into Renown using their Ethereum address. This is done by signing a message with their wallet.
 - The Ethereum key is used to create a DID (Decentralized Identifier), which uniquely represents the user without exposing their personal identity.
 
-![Renown Login](./images/ConnectAddress.png)
 
-#### 2. DID Creation
+<figure className="image-container">
+  <img src={require("./images/ConnectAddress.png").default} alt="Connect Address" />
+  <figcaption>Connecting your Ethereum address to generate Decentralized Identifier with Renown.</figcaption>
+</figure>
+
+#### 2. DID creation
 - A Decentralized Identifier (DID) is created based on the user's Ethereum key. The DID follows a specific format:  
   `did:example:123456789abcdefghijk`
 - This DID acts as the user's digital identifier across decentralized systems.
 
-#### 3. Credential Generation
+#### 3. Credential generation
 - A credential is generated, allowing the DID to sign operations on behalf of the user. This credential is stored on Ceramic, a decentralized data stream network.
 - Ceramic ensures that the credentials are securely stored and verifiable across the network. Credentials include the user's signing permissions and are linked to the DID.
 
-#### 4. Operation Signing with Connect
+#### 4. Operation signing with Connect
 - Connect uses the newly created DID to sign operations performed by the user. For example, when a document or transaction is edited in Connect, the operation is signed with the user's DID.
 - This ensures that every action taken within the Connect system is linked to the user's decentralized identity, maintaining transparency and accountability.
 
-![Renown Login](./images/OperationsHistory.png)
 
-#### 5. Switchboard Verification
+<figure className="image-container">
+  <img src={require("./images/OperationsHistory.png").default} alt="Renown Login" />
+  <figcaption>Your DID is used to sign operations performed by the user.</figcaption>
+</figure>
+
+#### 5. Switchboard verification
 - Once an operation is signed by the DID through Connect, it is sent to Switchboard for verification.
 - Switchboard verifies whether the DID has a valid credential stored on Ceramic and if the DID was indeed the one that signed the operation.
 - The request includes critical metadata such as the user's Ethereum address, the DID, the signed operation, and other parameters required for validation.
@@ -42,7 +53,7 @@ Renown provides a decentralized identity and reputation hub, where users connect
   } 
   ```
 
-#### 6. Operation Validation and Execution
+#### 6. Operation validation and execution
 - After Switchboard validates the operation, it ensures the operation context is accurate and the credentials match the signer. 
 - The operation is then either approved or rejected based on the verification results.
 - Approved operations are processed, and changes made within the Connect system are synchronized across the relevant nodes.

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/08-Authorization/02-Authorization.md

@@ -1,15 +1,15 @@
-# Switchboard Authorization
+# Switchboard authorization
 
 This tutorial explains how to configure authorization for the Powerhouse Switchboard using the new role-based authentication system.
 
-## Basic Configuration
+## Basic configuration
 
 The Switchboard supports two main ways to configure authorization:
 
 1. Using environment variables
 2. Using the powerhouse configuration file
 
-### Environment Variables
+### Environment variables
 
 The following environment variables can be used to configure authorization:
 
@@ -27,7 +27,7 @@ USERS="0xdef,0xghi"
 ADMINS="0x123,0x456"
 ```
 
-### Powerhouse Configuration
+### Powerhouse configuration
 
 Alternatively, you can configure authorization in your `powerhouse.config.json`:
 
@@ -44,7 +44,7 @@ Alternatively, you can configure authorization in your `powerhouse.config.json`:
 }
 ```
 
-## Role-Based Access Control
+## Role-based access control
 
 The new authorization system implements role-based access control with three distinct roles:
 
@@ -63,7 +63,7 @@ The new authorization system implements role-based access control with three dis
    - Can manage drives
    - Can perform administrative tasks
 
-## Docker Configuration
+## Docker configuration
 
 When running the Switchboard in Docker, you can pass these configurations as environment variables:
 
@@ -75,13 +75,13 @@ docker run -e AUTH_ENABLED=true \
            your-switchboard-image
 ```
 
-## Authorization Flow
+## Authorization flow
 
 1. Authentication can be enabled/disabled using AUTH_ENABLED
 2. Users are assigned roles based on their wallet addresses
 3. Each role has specific permissions and access levels
 
-## Security Best Practices
+## Security best practices
 
 1. Keep your admin wallet addresses secure
 2. Use HTTPS in production environments

package/docs/academy/02-MasteryTrack/04-WorkWithData/01-ReadingAndWritingThroughTheAPI.mdx

@@ -1,30 +1,24 @@
-# Read & Write through the API
+# Read and write through the API
 
 ## Introduction to Switchboard
 
 **Switchboard** is the API interface that allows developers and data engineers to get access to the data, that is being collected through the use of document models in Connect & Fusion.
 After structurally capturing the desired data of your formalised business processes the data can be used to build insightful experiences in external websites, drive widgets or create specific reports and dashboard in fusion. 
-**Since your document models have been defined with a GraphQL schema, you can use the same objects and fields in your queries and mutations to retrieve or write data from and to your document models.**
 
-<details>
-  <summary>Get your Switchboard API token (if required)</summary>
-
-Your API requests are authenticated using API keys or tokens. Any request that doesn't include an API key will return an error. You can generate an API token from your Switchboard instance at any time [by logging in with your Ethereum address here](https://apps.powerhouse.io/develop/powerhouse/switchboard/user).
-
-</details>
+:::tip Using the state schema of your document
+Since your document models have been defined with a GraphQL schema, you can use the same objects and fields in your queries and mutations to retrieve or write data from and to your document models.
+:::
 
 ## Querying a document with the GraphQL API
 
 ### Starting the reactor locally
 
-In this documentation we'll show how to use a **GraphQL** query to query a document model. We'll **continue on the ToDoList example** from our [introduction tutorial](/academy/GetStarted/DefineToDoListDocumentModel) , but the process can be applied to any other document model.
+In this tutorial we'll show how to use a **GraphQL** query to query a document model. We'll **continue on the To-do List example** from our [introduction tutorial](/academy/GetStarted/CreateNewPowerhouseProject) , but the process can be applied to any other document model.
 To make our document model available in the Apollo Studio Sandbox we'll need to store it on a remote [Reactor](/academy/Architecture/WorkingWithTheReactor).
 
-:::info
+:::info What are reactors?
 **Powerhouse Reactors** are the nodes in the network that store documents, resolve conflicts and rerun operations to verify document event histories. 
 Reactors can be configured for local storage, centralized cloud storage or on a decentralized storage network. 
-
-A reactor allows you to store multiple documents, but also host **drives** with different organisational purposes, users, access rights and more.
 :::
 
 Just like we can run Connect locally in studio mode we can run a remote node or a Reactor locally.   
@@ -44,18 +38,18 @@ It will return a url to access the Reactor.
 [Reactor]:   ➜  Reactor:   http://localhost:4001/d/powerhouse
 ```
 
-### Adding a remote drive or reactor to Connect:
+### Adding a remote drive or reactor to Connect
 
 If the remote drive or Reactor isn't present yet in connect you can add it by clicking the (+) button in the Connect drive navigation 
 and using the localhost url to add a new drive with it's underlying reactor. Usually http://localhost:4001/d/powerhouse
 
 Get access to an **organisations drive** instances by adding their drive to your Connect Drive navigation tree view with the help of the correct drive url. 
-click the (+) to add a public drive. To add a new drive you'll have to know the correct public URL of the drive.
+Click the (+) to add a public drive. To add a new drive you'll have to know the correct public URL of the drive.
 
 ## Querying the state of a document
 
 Now that we have our remote reactor and/or drive running we can store our document model on it.   
-Let's quickly create a new **todo list document** to test the process.
+Let's quickly create a new to-do list document to test the process.
 
 Add to following todo's to your list:
 - [ ] Sign up for Powerhouse
@@ -66,9 +60,9 @@ Add to following todo's to your list:
 
 Now that we have some data in our document model we can query it through the GraphQL API.
 
-### 1. The complete state of the document: 
+### 1. The complete state of the document
 
-Whenever you want to start a query from a document within connect you can open up switchboard by looking for the Switchboard logo in the top right hand corner of the document editor interface. 
+Whenever you want to start a query from a document within connect you can open up Switchboard by looking for the Switchboard logo in the top right hand corner of the document editor interface. 
 This will prepopulate the Apollo Studio Sandbox with the correct **DocumentID** for your document model. This feature will not be available for documents stored on local drives.
 
 ![Switchboardbutton](./images/SwitchboardButton.png)
@@ -79,7 +73,7 @@ The documentation on the left hand side of the Apollo Sandbox will show you all
 
 Alternatively we can just use our reactor url and endpoint to figure out the document id.  
 We can find out what the id of our document is by querying the drive for it's documents.   
-Since we only have one document in our drive it will return the id of our todo list document.
+Since we only have one document in our drive it will return the id of our to-do list document.
 
 This example query is structured to request a document by its unique identifier (id).   
 It extracts common fields such as **id**, **name**, **documentType**, **revision**, **created**, and **lastModified**.
@@ -93,7 +87,7 @@ As you can see there is a 'Delete' operation in the history on revision 5 as we
 
 Now let's query the content of the document using Apollo Studio Sandbox. The left sidebar shows the schema documentation, where you can explore all available fields and types for your document model. 
 
-For our TodoList document, let's construct a query that fetches the operations with the help of a nested operations field
+For our To-do List document, let's construct a query that fetches the operations with the help of a nested operations field
 
 ```graphql
 query {

package/docs/academy/02-MasteryTrack/04-WorkWithData/02-GraphQLAtPowerhouse.md

@@ -11,7 +11,7 @@ In this section, we will cover **the core concepts of GraphQL with examples appl
 - **Single Endpoint**: With GraphQL, you can access all the data you need through one endpoint, reducing the number of network requests.
 - **Dynamic Queries**: Its introspective nature allows developers to explore the API's schema dynamically, which streamlines development and documentation.
 
-## GraphQL: Core Concepts
+## GraphQL: Core concepts
 
 ### Schema
 The schema defines the structure of a GraphQL API. It acts as a contract between the client and server, detailing:
@@ -60,7 +60,7 @@ For example the contributor type has a relationship with the project type
 
 ---
 
-### Fields & Arguments
+### Fields and arguments
 - **Field**: A specific piece of data you can request from an object. When you build a query, you select the fields you want to retrieve.
 - **Argument**: Key-value pairs that can be attached to fields to customize and refine the query. Some fields require arguments to work correctly, especially when dealing with mutations.
 
@@ -101,7 +101,7 @@ GraphQL APIs are self-documenting. Through introspection, you can query the API
   ```
 
 ---
-### Connections, Edges, and Nodes
+### Connections, edges, and nodes
 When dealing with lists of data, GraphQL employs a pattern that includes:
 
 - **Connection**: A structure that represents a list of related objects.

package/docs/academy/02-MasteryTrack/04-WorkWithData/03-WorkingWithSubgraphs/02-GraphQLAndSubgraphs.mdx

@@ -1,4 +1,4 @@
-# GraphQL and Subgraphs
+# GraphQL and subgraphs
 
 GraphQL plays a fundamental role in defining document model data schemas, handling data access patterns, and enabling event-driven workflows within the Powerhouse ecosystem.   
 This document provides an intro to graphQL and how it is used at Powerhouse when dealing with subgraphs
@@ -8,7 +8,7 @@ More specifically, GraphQL is used as:
 - As the **query language in subgraphs**, which allow different services to expose and query structured data dynamically.
 
 
-## Powerhouse's use of GraphQL Subgraphs
+## Powerhouse's use of GraphQL subgraphs
 Powerhouse structures its data into subgraphs, which are modular GraphQL services that connect to the Reactor, Powerhouse's core data infrastructure, or Operational Data Stores fueled by data from a processor.
 
 ### Fetching data from the Reactor
@@ -16,7 +16,7 @@ Powerhouse structures its data into subgraphs, which are modular GraphQL service
 Powerhouse uses GraphQL to expose system-level data, such as drives, users, and operational records.  
 Example: The **System Subgraph** allows querying of drives, stored files and folders.
 
-### Operational Data Stores
+### Operational data stores
 
 Custom subgraphs can be created to store and retrieve operational data in real time.
 Example: A subgraph can track file uploads and expose this data via GraphQL queries.    ????
@@ -41,7 +41,7 @@ This schema ensures that every File entity has an ID, name, size, and timestamp.
 
 In Powerhouse, each subgraph has its own SDL, ensuring modularity and flexibility while working within the ecosystem.
 
-## CQRS Breakdown
+## CQRS breakdown
 
 Powerhouse uses CQRS to separate write operations (commands) from read operations (queries).   
 This improves system scalability and flexibility. 
@@ -55,7 +55,7 @@ Powerhouse's subgraphs act as the read layer, while processors handle write oper
 | Write Model (Commands) | Handles state changes (adding, modifying, deleting) | GraphQL Mutations | Processor |
 | Read Model (Queries) | Optimized for fetching/reading/retrieving data | GraphQL Queries | Subgraph |
 
-### Read & Write Separation  
+### Read and write separation  
 **Read Model (Query)**  
 
 - Optimized for data retrieval
@@ -89,7 +89,7 @@ mutation {
 }
 ```
 
-### GraphQL & Event-Driven Architecture (EDA)
+### GraphQL and event-driven architecture (EDA)
 Event-Driven Architecture (EDA) enables asynchronous processing where events trigger actions. Powerhouse uses GraphQL to expose real-time event data from its Reactor and Operational Data Stores.
 
 How GraphQL Fits into EDA
@@ -97,13 +97,13 @@ How GraphQL Fits into EDA
 - **Event Subscription Mechanism** – Powerhouse is working towards integrating GraphQL Subscriptions for real-time updates.
 - **Efficient Decoupling** – Events are stored in an operational datastore, and GraphQL queries retrieve structured results.
 
-#### Example: Powerhouse's Event Flow
+#### Example: Powerhouse's event flow
 1. Processor detects an event (e.g., file upload).
 2. Writes event data to the Operational Data Store.
 3. Subgraph exposes the updated data via GraphQL.
 
 
-## GraphQL Subscriptions
+## GraphQL subscriptions
 Although Powerhouse currently uses queries and mutations, GraphQL Subscriptions could allow real-time streaming of event-based data.
 
 #### Example (future implementation):