@powerhousedao/academy 3.2.0-dev.8 → 3.2.0-dev.9

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 3.2.0-dev.9 (2025-07-02)
+
+### 🩹 Fixes
+
+- updated processor generator and added codegen test for it ([6af3bbcf7](https://github.com/powerhouse-inc/powerhouse/commit/6af3bbcf7))
+- added test to generate and compile a generated document-model ([17bbca3bb](https://github.com/powerhouse-inc/powerhouse/commit/17bbca3bb))
+
+### ❤️ Thank You
+
+- Benjamin Jordan (@thegoldenmule)
+
 ## 3.2.0-dev.8 (2025-07-01)
 
 ### 🚀 Features

package/docs/academy/01-GetStarted/00-ExploreDemoPackage.mdx

@@ -1,18 +1,5 @@
 # Explore the demo package
 
-<details>
-<summary>How long will this tutorial take?</summary>
-
-We've designed this "Get Started" track to be as smooth as possible. The time it takes will vary based on your familiarity with modern web development tools.
-
-- **For Experienced Developers** (familiar with TypeScript, React, and CLIs), you can expect to complete the entire four-part tutorial in approximately **1 to 1.5 hours**.
-- **For Developers New to This Stack**, we recommend setting aside **3.5 to 4.5 hours**. This allows for time to understand not just the steps, but the core concepts behind them.
-
-This is just a guideline. The goal is to learn comfortably and build a solid foundation with Powerhouse!
-
-A more theoretical and advanced version of this tutorial can also be found in [Mastery Track - Document Model Creation](../MasteryTrack/DocumentModelCreation/WhatIsADocumentModel).
-</details>
-
 ## Let's get started
 
 To give you a quick idea of how the Powerhouse ecosystem operates on document models and packages, why don't you try installing a package? 
@@ -109,7 +96,55 @@ Here, you'll see that you've installed the `@powerhousedao/todo-demo-package`, w
   <figcaption>The Package Manager showing the installed todo-demo-package.</figcaption>
 </figure>
 
-## Step 4: Log in with Renown
+## Step 4: Create a todo list document
+
+:::tip What is a 'drive' at Powerhouse?
+A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized 'Drive Apps' for your documents. Think of a Drive App 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. To learn more, visit [Building A Drive App](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
+:::
+
+### 4.1 Create a local todolist app drive
+
+First, let's create a dedicated drive for your to-do lists:
+
+- Click the new drive icon in the interface
+- In the **Drive App** field, select 'To-do Drive App'
+- This creates a specialized drive that's optimized for to-do list documents
+
+### 4.2 Create a todolist document
+
+Now move into the drive you've just created:
+
+- Click the button at the bottom of the page to create a new to-do list document
+- This opens the to-do list editor where you can start managing your tasks
+
+### 4.3 Add a few todos and inspect the document history
+
+- Add a few to-dos that are on your mind
+- You'll see a statistics widget that counts the open to-dos
+- After closing the document, look at the To-do Drive App interface—you'll see that it tracks your tasks and displays a progress bar
+
+<figure className="image-container">
+  <img src={require("./images/TodoDriveApp.png").default} alt="Todo Drive App" />
+  <figcaption>A list of todo's in the custom todo drive app. </figcaption>
+</figure>
+
+A key feature you get with Connect is the **Operations History**. Every change to a document is stored as an individual operation, creating an immutable and replayable history. This provides complete auditability and transparency, as you can inspect each revision, its details, and any associated signatures. For example, you can see a chronological list of all modifications, along with who made them and when.
+
+<figure className="image-container">
+  <img src={require("./images/OperationsHistoryButton.png").default} alt="Operations History Button" />
+  <figcaption> You can find the button to visit the operations history in the document model toolbar </figcaption>
+</figure>
+
+<figure className="image-container">
+  <img src={require("./images/OperationsHistory.png").default} alt="Operations History" />
+  <figcaption>Example of the operations history for a document, showing all modifications made to it in a list. </figcaption>
+</figure>
+
+Learn more about the [Operations History](../MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free.
+
+This is the power of Drive Apps. They offer a customized interface that works well with the different documents inside your drive. Read more about drive apps in the Mastery Track: [Drive Apps and Drive Explorers](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
+
+## Step 5: Enable operation signing and verification through Renown
 
 Renown is Powerhouse's **decentralized identity and reputation system** designed to address the challenge of trust within open organizations, 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.
 
@@ -117,16 +152,18 @@ Renown is Powerhouse's **decentralized identity and reputation system** designed
 When signing in with Renown, use an Ethereum or blockchain address that can function as your 'identity', as this address will accrue more experience and history over time.
 :::
 
-### Login flow
-"**Log in with Renown**" is a decentralized authentication flow that enables you to log into applications by signing a credential with your Ethereum wallet. Upon signing in, a Decentralized Identifier (DID) is created based on your Ethereum key. 
+### 5.1 Click the renown icon and connect your eth identity
+
+"**Log in with Renown**" is a decentralized authentication flow that enables you to log into applications by signing a credential with your Ethereum wallet. Upon signing in, a Decentralized Identifier (DID) is created based on your Ethereum key.
 
 <figure className="image-container">
   <img src={require("./images/RenownLogin.png").default} alt="Renown Login" />
   <figcaption>The Renown login screen, prompting for a signature from a wallet.</figcaption>
 </figure>
 
-### Generate a DID to sign operations in Connect
-This DID is then associated with a credential that authorizes a specific Connect instance to act on your behalf. That credential is stored securely on Ceramic, a decentralized data network. When you perform actions through the Powerhouse Connect interface, those operations are signed with the DID and transmitted to Switchboard, which serves as the verifier. 
+### 5.2 Authorize Connect to sign document edits on your behalf
+
+This DID is then associated with a credential that authorizes a specific Connect instance to act on your behalf. That credential is stored securely on Ceramic, a decentralized data network. When you perform actions through the Powerhouse Connect interface, those operations are signed with the DID and transmitted to Switchboard, which serves as the verifier.
 
 <figure className="image-container">
   <img src={require("./images/ConnectAddress.png").default} alt="Connect Address for DID" />
@@ -138,45 +175,17 @@ This DID is then associated with a credential that authorizes a specific Connect
   <figcaption>Confirmation of a successful login with Renown.</figcaption>
 </figure>
 
-### Verifying signatures
-**Switchboard**, our (remote & local) data processing engine, acts as a verifier in the Renown authentication flow. Switchboard checks the validity of the DID and credential, ensuring the operation request is legitimate. This flow is designed to offer a verifiable, cryptographically secure login system that replaces traditional password-based authentication with decentralized identity and signature-based trust.
+### 5.3 Verify the signatures of new operations in the todo list
 
-## Step 5: Create a to-do list and explore the document operations history
-
-<figure className="image-container">
-  <img src={require("./images/OperationsHistory.png").default} alt="Operations History" />
-  <figcaption>Example of the operations history for a document, showing all modifications made to it in a list. </figcaption>
-</figure>
+By leveraging this system, every operation or modification made to a document is cryptographically signed by the contributor's Renown identity. This ensures that each change is verifiable, traceable, and attributable to a specific pseudonymous user, providing a robust audit trail for all document activity.
 
-By leveraging this system, every operation or modification made to a document is cryptographically signed by the contributor's Renown identity. This ensures that each change is verifiable, traceable, and attributable to a specific pseudonymous user, providing a robust audit trail for all document activity. 
-
-A key feature you get with Connect is the **Operations History**. Every change to a document is stored as an individual operation, creating an immutable and replayable history. This provides complete auditability and transparency, as you can inspect each revision, its details, and any associated signatures. For example, you can see a chronological list of all modifications, along with who made them and when. This ensures every action is traceable and verifiable.
-Learn more about the [Operations History](../MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free.
-
-
-### 5.1 Create a to-do list
-
-Now, move back to your local drive and create a to-do list. Add a few to-dos that are on your mind. You'll see a statistics widget that counts the open to-dos.
-
-### 5.2 Create a specific to-do drive app
-
-:::tip What is a 'drive' at Powerhouse?
-A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized 'Drive Apps' for your documents. Think of a Drive App 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. To learn more, visit [Building A Drive App](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
-:::
-
-Since your previous to-do list was created inside a local drive with a general-purpose drive explorer, it didn't look particularly special.
-
-- Now let's create a new drive by clicking the new drive icon. In the **Drive App** field, select 'To-do Drive App'.  
-- Now move into the drive you've just created and create a new to-do list by clicking the button at the bottom of the page. 
-- Add a new set of random to-dos
-- After closing the document, look at the To-do Drive App interface. You'll see that it tracks your tasks and displays a progress bar.
+Now, return to your to-do list and make some additional changes. You'll notice that these operations are now signed with your Renown identity, making every action traceable and verifiable in the operations history.
 
 <figure className="image-container">
-  <img src={require("./images/TodoDriveApp.png").default} alt="Operations History" />
-  <figcaption>A list of todo's in the custom todo drive app. </figcaption>
+  <img src={require("./images/OperationsHistorySignature.png").default} alt="Operation History Signature" />
+  <figcaption>Your DID is now signing the operations that are being added to the history.</figcaption>
 </figure>
 
-This is the power of Drive Apps. They offer a customized interface that works well with the different documents inside your drive. Read more about drive apps in the Mastery Track: [Drive Apps and Drive Explorers](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
 ## Step 6: Export a document
 
 Export the document as a `.phd` (Powerhouse Document) file using the export button in the document toolbar at the top. In this toolbar, you will find all available functionality for your documents. The `.phd` file can be sent through any of your preferred channels to other users on your network. 

package/docs/academy/01-GetStarted/01-CreateNewPowerhouseProject.md

@@ -1,4 +1,4 @@
-# Create a to-do list document
+# Create a new to-do list document
 
 ## Overview
 This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **To-do List**.   
@@ -18,52 +18,32 @@ Create a new Powerhouse project with a single command:
 ```bash
 ph init
 ```
-<details>
-<summary>How to use different branches</summary>
-
-When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches.   
-These branches contain more experimental features then the latest stable release the PH CLI uses by default.   
-They can be used to get access to a bugfix or features under development.
-
-| Command | Description |
-|---------|-------------|
-| **pnpm install -g ph-cmd** | Install latest stable version |
-| **pnpm install -g ph-cmd@dev** | Install development version |
-| **pnpm install -g ph-cmd@staging** | Install staging version |
-| **ph init** | Use latest stable version of the boilerplate |
-| **ph init --dev** | Use development version of the boilerplate |
-| **ph init --staging** | Use staging version of the boilerplate |
-| **ph use** | Switch all dependencies to latest production versions |
-| **ph use dev** | Switch all dependencies to development versions |
-| **ph use prod** | Switch all dependencies to production versions |
-
-Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
-</details>
 
 ## Before you begin
 1. Open your terminal (either your system terminal or IDE's integrated terminal)
-2. Navigate to your desired project directory using:
+2. Optionally, create a folder first to keep your Powerhouse projects:
 
    ```bash
-   cd your-directory
+   mkdir ph-projects
+   cd ph-projects
    ```
 3. Ensure you're in the correct directory before running the `ph init` command.  
 In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter.
    ```bash
-    you@yourmachine:~/Powerhouse$ ph init
+    you@yourmachine:~/ph-projects % ph init
 
-    ? What is the project name? ‣ <ToDoList>
+    ? What is the project name? ‣ getting-started
     ```	
 
     Once the project is created, you will see the following output:
     ```bash
-    Initialized empty Git repository in /Users/yourmachine/<ToDoList>/.git/
+    Initialized empty Git repository in /Users/you/ph-projects/getting-started/.git/
     The installation is done! 
     ```
 
     Navigate to the newly created project directory:
     ```bash
-    cd <yourprojectname>
+    cd getting-started
     ```
     Once in the project directory, run the `ph connect` command to start a local instance of the Connect application. This allows you to start your document model specification document.
     Run the following command to start the Connect application:

package/docs/academy/01-GetStarted/02-DefineToDoListDocumentModel.md

@@ -1,4 +1,4 @@
-# Define the to-do list document specification 
+# Write the document specification 
 
 In this tutorial, you will learn how to define the specifications for a **To-do List** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
 If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification.

package/docs/academy/02-MasteryTrack/04-WorkWithData/05-AnalyticsProcessorTutorial/02-CreateNewPowerhouseProject.md

@@ -16,7 +16,7 @@ Let's start with step 1 & 2 in the next section of the tutorial!
 
 To create a new Powerhouse Document Model Library project, you can use the `ph init` command in your terminal. This command will create a new project in the current directory.
 
-## Create new Powerhouse document model library project
+## Create new Powerhouse document model project
 
 :::info
 This command will create a new project in the current directory.
@@ -24,8 +24,10 @@ You can run the command in the terminal window of your OS or you open the newly
 You will need VSCode later in the tutorial once you have generated the document model.
 Make sure the terminal reflects the directory where you want to create the new project.
 To open a directory in a terminal, you use the cd command to change your current directory. The cd command takes an argument, usually the name of the folder you want to move to, so the full command is 
+
 ```bash
-cd your-directory
+mkdir ph-projects
+cd ph-projects
 ```
 This essentially opens that folder and places you in it.
 :::

package/docs/academy/03-ExampleUsecases/Chatroom/02-CreateNewPowerhouseProject.md

@@ -13,7 +13,8 @@ To create a new Powerhouse Document Model Library project, you can use the `ph i
 This command will create a new project in the current directory. You can run the command in the terminal window of your OS or you open the newly installed VSCode and run the command in the terminal window of VSCode.Make sure the terminal reflects the directory where you want to create the new project.
 
 ```bash
-cd your-directory
+mkdir ph-projects
+cd ph-projects
 ```
 This essentially opens that folder and places you in it.
 

package/docs/academy/06-ComponentLibrary/00-DocumentEngineering.md

@@ -15,6 +15,22 @@ Here are the key points to understand:
 - **Custom Scalars:** Besides the built-in scalars, you can define custom scalars (e.g., a Date type) if you need to handle more specific formats or validations. Powerhouse does this specific for the web3 ecosystem. 
 :::
 
+## What are Components?
+
+In the context of Powerhouse Builder platform, components can be thought of as reusable elements, or ready-to-use building blocks that help builders implement **document editors & viewers** with little to no effort. An important utility aspect of a component is that it serves its users as a **data input field**, providing structured ways to enter and manipulate information within your document models.
+
+## Document Editors vs Document Viewers
+
+Understanding the relationship between document editors and viewers is crucial for component usage:
+
+**Document Editor**: A specific document type that is used by one or more users to make data entries and update its state. Key utility is the ability to enter data in a structured format, making it a great tool for collaboration within a group of authorized users.
+
+**Document Viewer**: Does not allow modifications. It's a great way to inform about the state of the document type, making it a great tool for providing a broader group or public with transparent insights. Document viewers do not have to match the view of the editor one-to-one - the data presented could be framed as a specific selection, or filtered to provide desired insights.
+
+:::tip Component Behavior in Different Contexts
+The same component that will be used in a document viewer will have a **disabled state** (not allowed to edit documents). Document editors precede document viewers - you would start by creating a document editor and then, if needed, decide which viewer format is useful.
+:::
+
 ## Scalars vs. General UI Components
 
 ### Scalar Components
@@ -39,6 +55,42 @@ This category includes a broader range of UI elements such as simplified version
 **Location:** @powerhousedao/document-engineering/ui   
 https://github.com/powerhouse-inc/document-engineering
 
+## Component Types Classification
+
+Inspired by atomic design methodology, Powerhouse classifies components into the following categories:
+
+### Fragment
+The smallest element that combined together makes up a scalar or other simple component.
+**Examples:** Character counter, Checkbox field, Label
+
+### Scalar (Simple Component)
+The simplest component that contains the basic input field for one-dimensional data type (single value).
+**Examples:** Integer, Boolean, String, Powerhouse ID (PHID)
+
+### Complex Component
+Compound component that has an object/array value. It's made up of multiple scalars combined to serve a specific function.
+**Examples:** Sidebar (tree structure navigation component with content-style navigation for hierarchical data)
+
+### Layout Component
+Purpose-specific container for other components like lists of other components, color layouts, sections, etc.
+**Examples:** Homepage section layout
+
+:::info Component Library Philosophy
+The Powerhouse team is building a Component library with a wide range of components embedding best UX practices & key functionality. This library establishes standards and best practices for building documents while fast-tracking the building process through facilitation of the most basic & useful component types.
+:::
+
+## Component Behavior & UX Principles
+
+Besides the ability to input data, components have another crucial utility: they describe the mechanism of user interaction through implementing a defined set of behavior rules. 
+
+**Best Practices for Component Behavior:**
+- Implementing behaviors at a component level is much more efficient than at the document level
+- Good component behavior feels natural to the user and is easily understood
+- Components should be intuitive and not require additional tutorials or explanations
+- Start with the most simple/basic behaviors first, then layer additional behaviors on top
+- Keep behaviors as simple as needed - less is more
+
+
 ## Exploring Components with Storybook
 
 We use Storybook as an interactive catalog for our design system components. It allows you to visually explore each component, interact with different states, and understand how to integrate them into your projects. [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)

package/docs/academy/07-Cookbook.md

@@ -14,7 +14,7 @@ You need to install the Powerhouse CLI (`ph-cmd`) to create and manage Powerhous
 
 ## Prerequisites
 - node.js 22 installed
-- pnpm package manager installed
+- pnpm package manager 10 installed
 - Terminal or command prompt access
 
 ## Solution
@@ -169,7 +169,7 @@ You need to access experimental features, bugfixes, or development versions of P
 
 ## Prerequisites
 - Terminal or command prompt access
-- pnpm package manager installed
+- pnpm package manager 10 installed
 - Node.js 22 installed
 
 ## Solution

package/package.json

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

package/src/css/custom.css

@@ -157,6 +157,21 @@ a {
   color: #003d7a; /* darker blue on hover */
 }
 
+/* Dark mode specific styles for better readability */
+[data-theme='dark'] .docs-doc-page .theme-doc-markdown a,
+[data-theme='dark'] .markdown a,
+[data-theme='dark'] details a,
+[data-theme='dark'] .theme-doc-markdown details a {
+  color: #66b3ff !important; /* lighter blue for dark mode */
+}
+
+[data-theme='dark'] .docs-doc-page .theme-doc-markdown a:hover,
+[data-theme='dark'] .markdown a:hover,
+[data-theme='dark'] details a:hover,
+[data-theme='dark'] .theme-doc-markdown details a:hover {
+  color: #99ccff !important; /* even lighter blue on hover for dark mode */
+}
+
 /* Reset styling for navigation elements, category pages, and utility links */
 .breadcrumbs a,
 .pagination-nav a,