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

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/02-ConfiguringDrives.md

@@ -1,4 +1,4 @@
-# Configure a Drive
+# Configure a drive
 
 A drive in Powerhouse is a container or a wrapper for documents and data. It's a place where you can organize and store your documents and share them with others. This guide will walk you through the process of configuring and managing drives in your Powerhouse environment.   
 
@@ -10,13 +10,13 @@ Before configuring a drive, ensure you have:
 - Appropriate permissions to create and manage drives
 :::
 
-## Understanding Drives
+## Understanding drives
 
-### Local Drives
+### Local drives
 
 A local drive is a container for local documents and data, hosted on your local machine. Technically a drive is just another document model with a list of the documents inside the drive. When you run connect locally with `ph connect` a local drive is automatically added. You can also create a new local drive by clicking **'add drive'** in connect.
 
-### Remote Drives vs. reactors 
+### Remote drives vs. reactors 
 
 Remote drives in Powerhouse allow you to connect to and work with data stored in external systems or cloud services. These drives act as bridges between Powerhouse contributors and/or other data sources, enabling seamless data synchronization. Drives can exist in 3 category locations.
 
@@ -33,7 +33,7 @@ A reactor allows you to store multiple documents, but also host **drives** & Dri
 
 A drive exists by making use of a reactor and the storagelayer that specific reactor is based on. A reactor is the lower level component that makes synchronisation of documents & drives possible. 
 
-### Drive Apps 
+### Drive apps 
 
 **Drive Explorers** (also known as Drive Apps) are specialized interfaces that enhance how users interact with document models within a drive. As mentioned previously, technically a drive is just another document, with a list of the documents inside the drive. So it is obvious that you can create a custom editor for your drive-document. 
 
@@ -42,7 +42,7 @@ These customized editors are called Drive explorers or Drive Apps. They provide
 To learn more about building and customizing Drive Explorers, check out our [Building a Drive Explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) guide.
 
 
-## Creating a New Drive
+## Creating a new drive
 
 ![Create New Drive](./images/CreateNewDrive.png)
 
@@ -54,7 +54,7 @@ To create a new drive in Powerhouse, follow these steps:
 5. (Optional) Enable the "Make available offline" toggle if you want to keep a local backup of your drive.
 6. Once all options are set, click the "Create new drive" button to finalize and create your drive.
 
-## Adding a New Remote Drive via GraphQL Mutation
+## Adding a new remote drive via graphql mutation
 
 You can also add a new remote drive to your Connect environment programmatically using GraphQL mutations. This is especially useful for automation, scripting, or integrating with external systems.
 

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/03-BuildingADriveExplorer.md

@@ -1,4 +1,4 @@
-# Build a Drive Explorer
+# Build a drive explorer
 
 **Drive Explorers or Drive Apps** enhance how contributors and organizations interact with document models.   
 An 'app-like' experience is created by providing a **custom interface** for working with or exploring the contents of a drive.  
@@ -7,19 +7,19 @@ A 'Drive Explorer or Drive App' offers a tailored application designed around it
 Think of a Drive Explorer as a specialized lens—it offers **different ways to visualize, organize, and interact with** the data stored within a drive, making it more intuitive and efficient for specific use cases.
 :::
 
-### **Designed for Specific Use Cases**
+### **Designed for specific use cases**
 
 Most Drive Explorers are built by organizations for specific purposes, aligning closely with a document model package or even being part of one. By integrating Drive Apps with document models, organizations can customize user experiences, streamline workflows, and maximize efficiency for their contributors.
 
 Drive Explorers or Drive Apps **bridge the gap between raw data and usability**, unlocking the full potential of document models within the Powerhouse framework.
 
-### **Key Features of Drive Apps**
+### **Key features of drive apps**
 
 - **Custom Views & Organization** – Drive Apps can present data in formats like Kanban boards, list views, or other structured layouts to suit different workflows.
 - **Aggregated Insights** – They can provide high-level summaries of important details across document models, enabling quick decision-making.
 - **Enhanced Interactivity** – Drive Apps can include widgets, data processors, or read models to process and display document data dynamically.
 
-### **Building a Drive App**
+### **Building a drive app**
 
 #### The steps of our tutorial
 
@@ -31,7 +31,6 @@ Here is a **quick overview** of the 3 different steps towards building a Drive A
 Use the `generate drive editor` command to create the basic template structure for your Drive App:
 
 ```bash
-
 ph generate --drive-editor <Drive App>
 ```
 
@@ -40,7 +39,7 @@ ph generate --drive-editor <Drive App>
 After creating your Drive App, update the `manifest.json` file with relevant information:
 The manifest file identifies your project and its components within the Powerhouse ecosystem.
 
-#### Step 3. Customize the Drive App
+#### Step 3. Customize the drive app
 
 Review the generated template and modify it to better suit your document model:
 
@@ -48,7 +47,7 @@ Review the generated template and modify it to better suit your document model:
 2. Add custom views specific to your data model
 3. Implement specialized interactions for your use case
 
-### About the Drive App template
+### About the drive app template
 
 The default template provides a solid foundation. It contains:
 - A tree structure navigation panel
@@ -58,7 +57,7 @@ The default template provides a solid foundation. It contains:
 But the real power comes from tailoring the interface to your specific document models.   
  Now let's implement a specific example for a more complex todo-list then the one we've been working on. 
 
-### Implementation Example: Todo Drive Explorer
+### Implementation example: Todo drive explorer
 
 This example demonstrates how to create a Todo Drive Explorer application using the Powerhouse platform. 
 The application allows users to create and manage todo lists with a visual progress indicator.
@@ -125,7 +124,7 @@ Since you've likely already run through the [document modeling process](/academy
    }
    ```
 
-### Customize the Drive Explorer App
+### Customize the drive explorer app
 
 **1. Remove unnecessary default components:**   
 
@@ -163,7 +162,7 @@ rm -rf editors/todo-drive-explorer/components/FolderTree.tsx
 
    ![Todo Drive Explorer Demo](https://raw.githubusercontent.com/powerhouse-inc/todo-drive-explorer/9a87871e61460e73ddf8635fd756a0cd991306d6/demo.gif)
 
-### **Start Building Your Own Drive Apps, Explorers or Experiences**
+### **Start building your own drive apps, explorers or experiences**
 Congratulations on completing this tutorial! You've successfully built a custom Drive Explorer, enhancing the way users interact with document models.
 
 Now, take a moment to think about the possibilities!

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

@@ -1,12 +1,12 @@
-# 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?
+## 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:
 
 - **Appended** to the document's history
@@ -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 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.
 
-## Enabling the Timeline Feature
+## Enabling 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,9 @@ export const module: EditorModule<ToDoDocument> = {
 
 This setting enables the timeline button in the document toolbar.
 
-## Implementation Options
+## Implementation options
 
-### Default Drive Explorer
+### Default drive explorer
 
 When using the default drive explorer with `ph connect`, the timeline functionality is handled automatically:
 
@@ -33,7 +33,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 +86,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,34 @@
-# 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.
 
-### Detailed Login Flow
+### Detailed login flow
 
-#### 1. User Login via Wallet Connection
+#### 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
+#### 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
+#### 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 +42,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,4 +1,4 @@
-# Read & Write through the API
+# Read and write through the API
 
 ## Introduction to Switchboard
 
@@ -17,7 +17,7 @@ Your API requests are authenticated using API keys or tokens. Any request that d
 
 ### 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 documentation we'll show how to use a **GraphQL** query to query a document model. We'll **continue on the To-do Listexample** from our [introduction tutorial](/academy/GetStarted/DefineToDoListDocumentModel) , 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
@@ -44,7 +44,7 @@ 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
@@ -66,7 +66,7 @@ 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. 
 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.
@@ -93,7 +93,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):