@powerhousedao/academy 3.2.0-dev.3 → 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

@@ -6,8 +6,8 @@ A **document model** in Powerhouse is the core unit for managing business data.
 - **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)
@@ -33,7 +33,7 @@ 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
 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.

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

@@ -1,8 +1,8 @@
 # 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,7 +23,18 @@ 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.
+:::
+
+<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
 

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

@@ -3,7 +3,10 @@
 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.
+
+#### 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.
 
 ### Detailed login flow
 
@@ -11,7 +14,11 @@ Renown provides a decentralized identity and reputation hub, where users connect
 - 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)
+
+<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:  
@@ -26,7 +33,11 @@ Renown provides a decentralized identity and reputation hub, where users 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)
+
+<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.

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

@@ -4,27 +4,21 @@
 
 **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 To-do Listexample** 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.   
@@ -50,12 +44,12 @@ If the remote drive or Reactor isn't present yet in connect you can add it by cl
 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
@@ -68,7 +62,7 @@ Now that we have some data in our document model we can query it through the Gra
 
 ### 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**.

package/docs/academy/04-APIReferences/01-ReactHooks.md

@@ -0,0 +1,209 @@
+# React Hooks
+
+On this page we're providing an overview of the available hooks you can make use of as a builder. 
+
+<details>
+<summary>Need a refresher on React Hooks?</summary>
+
+React Hooks allow you to use various React features directly within your functional components. You can use built-in Hooks or combine them to create your own custom Hooks.
+
+**What are Custom Hooks?**
+A custom hook is a JavaScript function whose name starts with "use" and that calls other Hooks. They are used to:
+- Reuse stateful logic between components.
+- Abstract complex logic into a simpler interface.
+- Isolate side effects, particularly those managed by `useEffect`.
+
+**Key Built-in Hooks Examples:**
+- `useState`: Lets a component "remember" information (state).
+- `useEffect`: Lets a component perform side effects (e.g., data fetching, subscriptions, manually changing the DOM).
+- `useContext`: Lets a component receive information from distant parent components without explicitly passing props through every level of the component tree.
+
+**Naming Convention:**
+Hook names must always start with `use` followed by a capital letter (e.g., `useState`, `useOnlineStatus`).
+
+**Rules of Hooks:**
+1.  **Only Call Hooks at the Top Level**: Don't call Hooks inside loops, conditions, or nested functions.
+2.  **Only Call Hooks from React Functions**: Call Hooks from React functional components or from custom Hooks.
+
+It's important to note that a function should only be named and treated as a hook if it actually utilizes one or more built-in React hooks. If a function (even if named `useSomething`) doesn't call any built-in hooks, it behaves like a regular JavaScript function, and making it a "hook" offers no specific React advantages.
+
+For more details, see the official documentation and API references of React:
+- [Reusing Logic with Custom Hooks (react.dev)](https://react.dev/learn/reusing-logic-with-custom-hooks)
+- [Rules of Hooks (react.dev)](https://react.dev/reference/rules/rules-of-hooks)
+- [Powerhouse React Hooks API Reference](docs/academy/APIReferences/ReactHooks)
+
+</details>
+
+The idea is to make the usage of our hooks feel as simple and familiar as using `useState`.   
+The Powerhouse team is currently working on a happy path for builders that look like this: 
+
+```js
+// in a component that only needs to read a value, you can use
+const invoiceName = useReadDocumentField('myInvoiceDocumentId', 'name') // returns a string which is the `name`
+// and for documents that need to update data as well, you would have
+const updateInvoiceName = useUpdateDocumentField('myInvoiceDocumentId', 'name') // returns a function that takes a new string for the new name and dispatches the update
+// finally, we can combine these into a single hook which works like react's useState hook returning both the value and updater function
+const [invoiceName, updateInvoiceName] = useDocumentField('myInvoiceDocumentId', 'name')
+
+
+// Read-only value
+const invoiceName = useReadDocumentField('docId', 'name')
+
+// Write-only updater
+const updateInvoiceName = useUpdateDocumentField('docId', 'name')
+
+// Combined read + write (like useState)
+const [invoiceName, updateInvoiceName] = useDocumentField('docId', 'name')
+```
+
+
+## An overview of currently available hooks
+
+### 1. Getting or changing data 
+These are tools you can use in your app to get or change data:
+
+<details>
+<summary>`useDrives`, `useDriveById(id)`: Lets you access folders (called "drives").</summary>
+
+### Hook Name and Signature   
+The name of the hook and its TypeScript (or JavaScript) signature.
+### Description
+A brief explanation of what the hook does and when to use it.
+### Usage Example   
+A code snippet showing how to use the hook in a real-world scenario.
+### Parameters
+A table or list describing each parameter, its type, and its purpose.
+### Return Value   
+A description (and sometimes a table) of what the hook returns.
+### Notes / Caveats   
+Any important details, gotchas, or best practices.
+### Related Hooks
+Links to other relevant hooks or documentation.
+</details>
+
+<details>
+<summary>`useDocuments`, `useDocumentById(id)`: Lets you access files (called "documents").</summary>
+
+### Hook Name and Signature   
+The name of the hook and its TypeScript (or JavaScript) signature.
+### Description
+A brief explanation of what the hook does and when to use it.
+### Usage Example   
+A code snippet showing how to use the hook in a real-world scenario.
+### Parameters
+A table or list describing each parameter, its type, and its purpose.
+### Return Value   
+A description (and sometimes a table) of what the hook returns.
+### Notes / Caveats   
+Any important details, gotchas, or best practices.
+### Related Hooks
+Links to other relevant hooks or documentation.
+</details>
+
+<details>
+<summary>`useEditorModules`, `useEditor(documentType)`: Loads the relevant editor UI/tools for a document.</summary>
+
+### Hook Name and Signature   
+The name of the hook and its TypeScript (or JavaScript) signature.
+### Description
+A brief explanation of what the hook does and when to use it.
+### Usage Example   
+A code snippet showing how to use the hook in a real-world scenario.
+### Parameters
+A table or list describing each parameter, its type, and its purpose.
+### Return Value   
+A description (and sometimes a table) of what the hook returns.
+### Notes / Caveats   
+Any important details, gotchas, or best practices.
+### Related Hooks
+Links to other relevant hooks or documentation.
+</details>
+
+<details>
+<summary>`useDocumentModule`, `useDocumentModel(documentType)`: Gets the technical model behind a document type—like its schema and operations.</summary>
+
+### Hook Name and Signature   
+The name of the hook and its TypeScript (or JavaScript) signature.
+### Description
+A brief explanation of what the hook does and when to use it.
+### Usage Example   
+A code snippet showing how to use the hook in a real-world scenario.
+### Parameters
+A table or list describing each parameter, its type, and its purpose.
+### Return Value   
+A description (and sometimes a table) of what the hook returns.
+### Notes / Caveats   
+Any important details, gotchas, or best practices.
+### Related Hooks
+Links to other relevant hooks or documentation.
+</details>
+
+### 2. Managing selection state
+You can now use the following to manage and track what's currently selected:
+
+<details>
+<summary>`useSelectedDrive` and `useSetSelectedDrive(driveId)`: Get/set the selected folder.</summary>
+
+### Hook Name and Signature   
+The name of the hook and its TypeScript (or JavaScript) signature.
+### Description
+A brief explanation of what the hook does and when to use it.
+### Usage Example   
+A code snippet showing how to use the hook in a real-world scenario.
+### Parameters
+A table or list describing each parameter, its type, and its purpose.
+### Return Value   
+A description (and sometimes a table) of what the hook returns.
+### Notes / Caveats   
+Any important details, gotchas, or best practices.
+### Related Hooks
+Links to other relevant hooks or documentation.
+</details>
+
+<details>
+<summary>`useSelectedDocument` and `useSetSelectedDocument(documentId)`: Get/set the selected file.</summary>
+
+### Hook Name and Signature   
+The name of the hook and its TypeScript (or JavaScript) signature.
+### Description
+A brief explanation of what the hook does and when to use it.
+### Usage Example   
+A code snippet showing how to use the hook in a real-world scenario.
+### Parameters
+A table or list describing each parameter, its type, and its purpose.
+### Return Value   
+A description (and sometimes a table) of what the hook returns.
+### Notes / Caveats   
+Any important details, gotchas, or best practices.
+### Related Hooks
+Links to other relevant hooks or documentation.
+</details>
+
+## More documentation coming soon!
+
+Global access to drive state: A top-level, possibly context-based, way to introspect and interact with any document and its state tree without manually passing things around.
+
+Global dispatcher access: A utility or API (probably a hook or service function) where they give a document ID and get back all the relevant dispatch functions — kind of like a command palette for document ops.
+
+### Core Hooks & Patterns	
+- useDocumentField
+- useReadDocumentField
+- useUpdateDocumentField
+- useDocumentDispatch(docId):  updateX, delete, ... 
+
+### Global Drive Access	
+- How to access and manipulate the global document tree
+- How to inspect children from parent context
+- Tree traversal utilities (if any)
+
+### Convenience APIs	
+- Utility functions like getDispatchFunctions(docId)
+- "Quick Start" to manipulate any document like a pro
+
+### Working with Context	
+- DriveContext: what lives there, how to use it
+- Example: using context to get current doc, sibling docs
+
+### Best Practices & Patterns	
+- When to use useDocumentField vs getDispatch
+- Composing document fields into custom logic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "3.2.0-dev.3",
+  "version": "3.2.0-dev.4",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/docs/academy/04-APIReferences/01-ReactHooks

@@ -1,98 +0,0 @@
-# React Hooks (WIP)
-
-The idea is to make this feel as simple and familiar as using useState.
-Happy Path would look something like this: 
-
-```js
-// in a component that only needs to read a value, you can use
-const invoiceName = useReadDocumentField('myInvoiceDocumentId', 'name') // returns a string which is the `name`
-// and for documents that need to update data as well, you would have
-const updateInvoiceName = useUpdateDocumentField('myInvoiceDocumentId', 'name') // returns a function that takes a new string for the new name and dispatches the update
-// finally, we can combine these into a single hook which works like react's useState hook returning both the value and updater function
-const [invoiceName, updateInvoiceName] = useDocumentField('myInvoiceDocumentId', 'name')
-
-
-// Read-only value
-const invoiceName = useReadDocumentField('docId', 'name')
-
-// Write-only updater
-const updateInvoiceName = useUpdateDocumentField('docId', 'name')
-
-// Combined read + write (like useState)
-const [invoiceName, updateInvoiceName] = useDocumentField('docId', 'name')
-```
-
-Request	Translation
-Global access to drive state: A top-level, possibly context-based, way to introspect and interact with any document and its state tree without manually passing things around.
-Global dispatcher access: A utility or API (probably a hook or service function) where they give a document ID and get back all the relevant dispatch functions — kind of like a command palette for document ops.
-Time spent wiring > time spent building	Frustration with current DX (developer experience) — they want abstractions and helpers to just do the thing.
-
-Core Hooks & Patterns	
-- useDocumentField
-- useReadDocumentField
-- useUpdateDocumentField
-- useDocumentDispatch(docId):  updateX, delete, ... 
-
-Global Drive Access	
-- How to access and manipulate the global document tree
-- How to inspect children from parent context
-- Tree traversal utilities (if any)
-
-Convenience APIs	
-- Utility functions like getDispatchFunctions(docId)
-- “Quick Start” to manipulate any document like a pro
-
-Working with Context	
-- DriveContext: what lives there, how to use it
-- Example: using context to get current doc, sibling docs
-
-Best Practices & Patterns	
-- When to use useDocumentField vs getDispatch
-- Composing document fields into custom logic
-
-<details>
-<summary>Refresher on React Hooks</summary>
-
-React Hooks allow you to use various React features directly within your functional components. You can use built-in Hooks or combine them to create your own custom Hooks.
-
-**What are Custom Hooks?**
-A custom hook is a JavaScript function whose name starts with "use" and that calls other Hooks. They are used to:
-- Reuse stateful logic between components.
-- Abstract complex logic into a simpler interface.
-- Isolate side effects, particularly those managed by `useEffect`.
-
-**Key Built-in Hooks Examples:**
-- `useState`: Lets a component "remember" information (state).
-- `useEffect`: Lets a component perform side effects (e.g., data fetching, subscriptions, manually changing the DOM).
-- `useContext`: Lets a component receive information from distant parent components without explicitly passing props through every level of the component tree.
-
-**Naming Convention:**
-Hook names must always start with `use` followed by a capital letter (e.g., `useState`, `useOnlineStatus`).
-
-**Rules of Hooks:**
-1.  **Only Call Hooks at the Top Level**: Don't call Hooks inside loops, conditions, or nested functions.
-2.  **Only Call Hooks from React Functions**: Call Hooks from React functional components or from custom Hooks.
-
-It's important to note that a function should only be named and treated as a hook if it actually utilizes one or more built-in React hooks. If a function (even if named `useSomething`) doesn't call any built-in hooks, it behaves like a regular JavaScript function, and making it a "hook" offers no specific React advantages.
-
-For more details, see the official documentation and our API reference:
-- [Reusing Logic with Custom Hooks (react.dev)](https://react.dev/learn/reusing-logic-with-custom-hooks)
-- [Rules of Hooks (react.dev)](https://react.dev/reference/rules/rules-of-hooks)
-- [Powerhouse React Hooks API Reference](docs/academy/APIReferences/ReactHooks)
-
-</details>
-
-### Hook Name and Signature   
-The name of the hook and its TypeScript (or JavaScript) signature.
-### Description
-A brief explanation of what the hook does and when to use it.
-### Usage Example   
-A code snippet showing how to use the hook in a real-world scenario.
-### Parameters
-A table or list describing each parameter, its type, and its purpose.
-### Return Value   
-A description (and sometimes a table) of what the hook returns.
-### Notes / Caveats   
-Any important details, gotchas, or best practices.
-### Related Hooks
-Links to other relevant hooks or documentation.