@powerhousedao/academy 5.1.0-dev.3 → 5.1.0-dev.5

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 5.1.0-dev.5 (2025-12-04)
+
+### 🚀 Features
+
+- connect crypto signer and verifier ([918fb1fab](https://github.com/powerhouse-inc/powerhouse/commit/918fb1fab))
+
+### ❤️ Thank You
+
+- Benjamin Jordan (@thegoldenmule)
+
+## 5.1.0-dev.4 (2025-12-03)
+
+### 🚀 Features
+
+- **codegen,ph-cli:** add tsx code generator ([#2116](https://github.com/powerhouse-inc/powerhouse/pull/2116))
+- **academy:** add new todo list tutorial content ([b6dc16545](https://github.com/powerhouse-inc/powerhouse/commit/b6dc16545))
+
+### ❤️ Thank You
+
+- Ryan Wolhuter @ryanwolhuter
+- ryanwolhuter @ryanwolhuter
+
 ## 5.1.0-dev.3 (2025-12-02)
 
 ### 🚀 Features

package/blog/BeyondCommunication-ABlueprintForDevelopment.md

@@ -1,7 +1,8 @@
 ---
 title: Beyond Communication - A Blueprint for Development
-description: GraphQL Schema’s as a common language for software design
+description: GraphQL Schema's as a common language for software design
 slug: Graphql-schema-as-a-common-language
+date: 2024-12-02
 authors:
   - name: Call me T.
     title: Product Manager at Powerhouse

package/blog/TheChallengeOfChange.md

@@ -2,6 +2,7 @@
 title: The Challenge of Change
 description: Rapid Application Development with document models.
 slug: Rapid-Application-Development-with-document-models.
+date: 2024-12-02
 authors:
   - name: Call me T.
     title: Product Manager at Powerhouse

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

@@ -2,13 +2,13 @@
 
 ## 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?
+To give you a quick idea of how the Powerhouse Vetra builder platform operates on document models and packages, why don't you try installing a package?
 We will show you how to install the Powerhouse command-line tool `ph-cmd` and then use it to install a pre-built demo package containing a document model, an editor, and a drive app.
 
 ## Step 1: Install the Powerhouse CLI
 
-You will use the Powerhouse CLI to launch a local environment with a "To-do List Demo Package".
-This is also the package that you'll recreate during the tutorials and gets you familiar with Powerhouse.
+You will use the Powerhouse CLI to launch a local environment with a "To-do List Demo Package" installed.
+This is also the package that you'll recreate during the tutorials and gets you familiar with Powerhouse Vetra.
 
 ```bash
 pnpm install -g ph-cmd
@@ -20,16 +20,21 @@ Verify the installation:
 ph --version
 ```
 
-## Step 2: Install the to-do list demo package
+## Step 2: Initialize a new project 
 
-Now, use the `ph` command to install the demo package into a global project.
+Now use the `ph init` command to initialize a new project and install a Powerhouse package inside the project. 
+You'll be asked to name your project. Afterwards, move inside your project with `cd project-name`
+
+## Step 3: Install the to-do list demo package
+
+Now, use the `ph install` command to install the demo package inside the project. 
 
 ```bash
 # Install the package
-ph install @powerhousedao/todo-demo-package
+ph install @powerhousedao/todo-demo
 ```
 
-This command downloads and sets up the `@powerhousedao/todo-demo-package`, making its features available in your Powerhouse environment.
+This command downloads and sets up the `@powerhousedao/todo-demo`, making its features available in your Powerhouse project.
 
 <details>
 <summary>Expected CLI result</summary>
@@ -73,9 +78,9 @@ This command downloads and sets up the `@powerhousedao/todo-demo-package`, makin
 
 </details>
 
-You have now successfully installed `ph-cmd` and added your first package!
+You have now successfully installed `ph-cmd`, initalized a product project and added your first package!
 
-## Step 3: Run the connect app in studio mode
+## Step 4: Run the connect app in studio mode
 
 To run the package locally in Connect Studio (our collaboration and contributor app), run:
 
@@ -91,7 +96,7 @@ Click the returned localhost URL and you should see Connect Studio appear in you
 </figure>
 
 When you click the settings wheel in the bottom right corner, you'll get access to the **Package Manager**.
-Here, you'll see that you've installed the `@powerhousedao/todo-demo-package`, which contains not only a **Document Model** and its accompanying editor but also a **Drive App** specific to the to-do document model.
+Here, you'll see that you've installed the `@powerhousedao/todo-demo`, which contains not only a **Document Model** and its accompanying editor but also a **Drive App** specific to the to-do document model.
 
 <figure className="image-container">
   <img
@@ -103,13 +108,13 @@ Here, you'll see that you've installed the `@powerhousedao/todo-demo-package`, w
   </figcaption>
 </figure>
 
-## Step 4: Create a todo list document
+## Step 5: 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
+### 5.1 Create a local todolist app drive
 
 First, let's create a dedicated drive for your to-do lists:
 
@@ -117,14 +122,14 @@ First, let's create a dedicated drive for your to-do lists:
 - 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
+### 5.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
+### 5.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
@@ -134,14 +139,6 @@ This is an example of the **usefulness and impact 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).
 
-<figure className="image-container">
-  <img
-    src={require("./images/TodoDriveApp.png").default}
-    alt="Todo Drive App"
-  />
-  <figcaption>A list of todos in the custom todo drive app.</figcaption>
-</figure>
-
 A key feature of 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">
@@ -167,7 +164,7 @@ You can find the button to visit the operations history in the document model to
 
 Learn more about the [Operations History](../MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free.
 
-## Step 5: Enable operation signing and verification through Renown
+## Step 6: 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.
 
@@ -175,7 +172,7 @@ 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.
 :::
 
-### 5.1 Click the renown icon and connect your Ethereum identity
+### 6.1 Click the renown icon and connect your Ethereum 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.
 
@@ -186,7 +183,7 @@ When signing in with Renown, use an Ethereum or blockchain address that can func
   </figcaption>
 </figure>
 
-### 5.2 Authorize Connect to sign document edits on your behalf
+### 6.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.
 
@@ -208,7 +205,7 @@ This DID is then associated with a credential that authorizes a specific Connect
   <figcaption>Confirmation of a successful login with Renown.</figcaption>
 </figure>
 
-### 5.3 Verify the signatures of new operations in the todo list
+### 6.3 Verify the signatures of new operations in the todo list
 
 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.
 
@@ -224,7 +221,7 @@ Now, return to your to-do list and make some additional changes. You'll notice t
   </figcaption>
 </figure>
 
-## Step 6: Export a document
+## Step 7: 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,12 +1,100 @@
 # Create a new to-do list document
 
+:::tip Tutorial Repository
+📦 **Reference Code**: [step-1-initialize-with-ph-init](https://github.com/powerhouse-inc/todo-tutorial/tree/step-1-initialize-with-ph-init)
+
+This tutorial step has a corresponding branch in the repository. You can:
+- View the complete code for this step
+- Clone and checkout the branch to see the result
+- Compare your implementation using `git diff`
+:::
+
+<details>
+<summary>📖 How to use this tutorial</summary>
+
+This tutorial is designed for you to **build your own project from scratch** while having access to reference code at each step.
+
+### Setup: Create your project and connect to tutorial repo
+
+1. **Create your project** following the tutorial:
+   ```bash
+   mkdir ph-projects
+   cd ph-projects
+   ph init
+   # When prompted, enter project name: todo-tutorial
+   cd todo-tutorial
+   ```
+
+2. **Add the tutorial repository as a remote** to access reference branches:
+   ```bash
+   git remote add tutorial https://github.com/powerhouse-inc/todo-tutorial.git
+   git fetch tutorial --prune
+   ```
+
+3. **Create your own branch** to keep your work organized:
+   ```bash
+   git checkout -b my-todo-project
+   ```
+
+Now you have access to all tutorial step branches while working on your own code!
+
+### Compare your work with reference steps
+
+At any point, compare what you've built with a tutorial step:
+
+```bash
+# Compare your current work with step-1
+git diff tutorial/step-1-initialize-with-ph-init
+
+# See what changed between tutorial steps
+git diff tutorial/step-1-initialize-with-ph-init..tutorial/step-2-generate-todo-list-document-model
+
+# Compare specific files
+git diff tutorial/step-1-initialize-with-ph-init -- package.json
+```
+
+### Visual diff with GitHub Desktop
+
+For a more visual comparison, use GitHub Desktop:
+
+1. **First, make your initial commit** (GitHub Desktop won't show your branch until you have at least one commit):
+   ```bash
+   git add .
+   git commit -m "Initial project setup"
+   ```
+
+2. **Open GitHub Desktop** and open your repository
+
+3. **Compare branches visually**:
+   - Click on **Branch** menu in the top menu bar
+   - Select **"Compare to Branch..."**
+   - Choose the tutorial branch you want to compare with (e.g., `tutorial/step-1-initialize-with-ph-init`)
+   - GitHub Desktop will show you all file differences in a visual interface
+
+4. **Review the differences**:
+   - Click on any file to see side-by-side or unified diff view
+   - See exactly what's different between your code and the reference
+
+**Tip**: You can also use VS Code's Git Graph extension or the command palette → "Git: Compare with Branch"
+
+### If you get stuck
+
+Reset your code to match a tutorial step:
+
+```bash
+# Reset to step-2 (WARNING: loses your changes)
+git reset --hard tutorial/step-2-generate-todo-list-document-model
+```
+
+</details>
+
 ## Overview
 
 This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **To-do List**.  
 A Powerhouse project primarily consists of a document model and its editor. 
 As your projects use-case expands you can add data-integrations or a specific drive-app as seen in the demo package. 
 
-For todays purpose, you'll be using Connect, our user-centric collaboration tool and Vetra Studio, the builder tooling through which developers can access and manage specifications of their project. 
+For todays purpose, you'll be using Connect, our user-centric collaboration tool and Vetra Studio, the builder tooling through which developers can access and manage specifications of your project. 
 
 ## Prerequisites
 
@@ -41,19 +129,19 @@ ph init
    ````bash
     you@yourmachine:~/ph-projects % ph init
 
-    ? What is the project name? ‣ getting-started
+    ? What is the project name? ‣ todo-tutorial
     ```
 
 
 Once the project is created, you will see the following output:
     ```bash
-    Initialized empty Git repository in /Users/you/ph-projects/getting-started/.git/
+    Initialized empty Git repository in /Users/you/ph-projects/todo-tutorial/.git/
     The installation is done!
     ```
 
 Navigate to the newly created project directory:
     ```bash
-    cd getting-started
+    cd todo-tutorial
     ```
 
 ## Develop a single document model in Connect
@@ -73,20 +161,41 @@ The Connect application will start and you will see the following output:
       ➜  press h + enter to show help
     ```
 
-A new browser window will open and you will see the Connect application. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser.
+A new browser window will open and you will see the Connect application. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser. You will see your local drive and a button to create a new drive.
 
-You will see your local drive and a button to create a new drive.
+:::tip 
 If you local drive is not present navigate into Settings in the bottom left corner. Settings > Danger Zone > Clear Storage.
 Clear the storage of your localhost application as it might has an old session cached.
+:::
 
 4. Move into your local drive.  
-   Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page.
+   Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page. Name your document `TodoList` (PascalCase, no spaces or hyphens).
+
+If you've followed the steps correctly, you'll have an empty `TodoList` document where you can define the **'Document Specifications'**.
+
+## Verify your setup
 
-If you've followed the steps correctly, you'll have an empty document where you can define the **'Document Specifications'**.
+At this point, your project structure should match the `step-1-initialize-with-ph-init` branch. You should have:
 
-## Develop a package in Vetra Studio
+- Empty `document-models/`, `editors/`, `processors/`, and `subgraphs/` directories
+- Configuration files: `powerhouse.config.json`, `powerhouse.manifest.json`
+- Package management files: `package.json`, `pnpm-lock.yaml`
+- Build configuration: `tsconfig.json`, `vite.config.ts`, `vitest.config.ts`
 
+### Compare with reference implementation
 
+Verify your initial setup matches the tutorial:
+
+```bash
+# Compare your project structure with step-1
+git diff tutorial/step-1-initialize-with-ph-init
+
+# List files in the tutorial's step-1
+git ls-tree -r --name-only tutorial/step-1-initialize-with-ph-init
+
+# View a specific config file from step-1
+git show tutorial/step-1-initialize-with-ph-init:package.json
+```
 
 ## Up next
 

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

@@ -1,6 +1,55 @@
 # 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.
+:::tip Tutorial Repository
+📦 **Reference Code**: [step-2-generate-todo-list-document-model](https://github.com/powerhouse-inc/todo-tutorial/tree/step-2-generate-todo-list-document-model)
+
+This tutorial step has a corresponding branch. After completing this step, your project will have a generated document model with:
+- Document model specification files (`todo-list.json`, `schema.graphql`)
+- Auto-generated TypeScript types and action creators
+- Reducer scaffolding ready for implementation
+:::
+
+<details>
+<summary>📖 How to use this tutorial</summary>
+
+**Prerequisites**: Complete step 1 and set up the tutorial remote (see previous step).
+
+### Compare your generated code
+
+After running `ph generate TodoList.phdm.zip`, compare with the reference:
+
+```bash
+# Compare all generated files with step-2
+git diff tutorial/step-2-generate-todo-list-document-model
+
+# Compare specific directory
+git diff tutorial/step-2-generate-todo-list-document-model -- document-models/todo-list/
+```
+
+### See what was generated
+
+View the complete step-2 reference code:
+
+```bash
+# List files in the tutorial's step-2
+git ls-tree -r --name-only tutorial/step-2-generate-todo-list-document-model document-models/
+
+# View a specific file from step-2
+git show tutorial/step-2-generate-todo-list-document-model:document-models/todo-list/schema.graphql
+```
+
+### Visual comparison with GitHub Desktop
+
+After making a commit, use GitHub Desktop for visual diff:
+1. **Branch** menu → **"Compare to Branch..."**
+2. Select `tutorial/step-2-generate-todo-list-document-model`
+3. Review all file differences in the visual interface
+
+See step 1 for detailed GitHub Desktop instructions.
+
+</details>
+
+In this tutorial, you will learn how to define the specifications for a **TodoList** 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.
 
 Before you start, make sure you have the Connect application running locally with the command:
@@ -17,14 +66,13 @@ The Connect application will start and you will see the following output:
   ➜  press h + enter to show help
 ```
 
-## To-do list document specification
+## TodoList document specification
 
-Likely you have called your project 'ToDoList'.  
-If you've used a different name, please create a new document specification named 'ToDoList'.  
-**Pay close attention to capitalization, as it influences our code.**
+Make sure you have named your document model `TodoList` (PascalCase, no spaces or hyphens).  
+**Pay close attention to capitalization, as it influences our code generation.**
 
 We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model.  
-Below, you can see the SDL for the `To-do List` document model.
+Below, you can see the SDL for the `TodoList` document model.
 
 :::info
 This schema defines the **data structure** of the document model and the types involved in its operations, which are detailed further as input types.
@@ -32,17 +80,17 @@ Documents in Powerhouse leverage **event sourcing principles**, where every stat
 :::
 
 <details>
-<summary>State schema of our simplified To-do list</summary>
+<summary>State schema of our simplified TodoList</summary>
 
 ```graphql
-# The state of our ToDoList
-type ToDoListState {
-  items: [ToDoItem!]!
+# The state of our TodoList
+type TodoListState {
+  items: [TodoItem!]!
 }
 
 # A single to-do item
-type ToDoItem {
-  id: ID!
+type TodoItem {
+  id: OID!
   text: String!
   checked: Boolean!
 }
@@ -51,29 +99,25 @@ type ToDoItem {
 </details>
 
 <details>
-<summary>Operations schema of our simplified to-do list</summary>
+<summary>Operations schema of our simplified TodoList</summary>
 ```graphql
 # Defines a GraphQL input type for adding a new to-do item
 input AddTodoItemInput {
-  id: ID!
   text: String!
 }
 
 # Defines a GraphQL input type for updating a to-do item
-
 input UpdateTodoItemInput {
-id: ID!
-text: String
-checked: Boolean
+  id: OID!
+  text: String
+  checked: Boolean
 }
 
 # Defines a GraphQL input type for deleting a to-do item
-
 input DeleteTodoItemInput {
-id: ID!
+  id: OID!
 }
-
-````
+```
 </details>
 
 ## Define the document model specification
@@ -83,21 +127,20 @@ To be able to define the document model, you need to open the document model edi
 ### The steps below show you how to do this:
 
 1. In the Connect application, click on **'document model'** to open the document model specification editor.
-2. Name your document model '**ToDoList**' in the Connect application, paying close attention to capitalization.
+2. Name your document model `TodoList` (PascalCase, no spaces or hyphens) in the Connect application. **Pay close attention to capitalization, as it influences code generation.**
 3. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields.
 
-    In the **Document Type** field, type `powerhouse/todolist`. This defines the new type of document that will be created with this document model specification.
+    In the **Document Type** field, type `powerhouse/todo-list` (lowercase with hyphen). This defines the new type of document that will be created with this document model specification.
 
-    ![ToDoList Document Model Form Metadata](./images/DocumentModelHeader.png)
+    ![TodoList Document Model Form Metadata](./images/DocumentModelHeader.png)
 
 4. In the code editor, you can see the SDL for the document model. Replace the existing SDL template with the SDL defined in the [State Schema](#state-schema) section. Only copy and paste the types, leaving the inputs for the next step. You can, however, already press the 'Sync with schema' button to set the initial state of your document model specification based on your Schema Definition Language.
-5. Below the editor, find the input field `Add module`. You'll use this to create and name a module for organizing your input operations. In this case, we will name the module `to_do_list`. Press enter.
+5. Below the editor, find the input field `Add module`. You'll use this to create and name a module for organizing your input operations. In this case, we will name the module `todos`. Press enter.
 6. Now there is a new field, called `Add operation`. Here you will have to add each input operation to the module, one by one.
 7. Inside the `Add operation` field, type `ADD_TODO_ITEM` and press enter. A small editor will appear underneath it, with an empty input type that you have to fill. Copy the first input type from the [Operations Schema](#operations-schema) section and paste it in the editor. The editor should look like this:
 
     ```graphql
     input AddTodoItemInput {
-        id: ID!
         text: String!
     }
     ```
@@ -110,7 +153,41 @@ Check below screenshot for the complete implementation:
 
 ![ToDoList Document Model](./images/DocumentModelOperations.png)
 
+## Verify your document model generation
+
+After running `pnpm generate TodoList.phd`, your project should have the following structure in `document-models/todo-list/`:
+
+```
+document-models/todo-list/
+├── gen/                          # Auto-generated code (don't edit)
+│   ├── actions.ts
+│   ├── creators.ts              # Action creator functions
+│   ├── types.ts                 # TypeScript type definitions
+│   ├── reducer.ts
+│   └── todos/
+│       └── operations.ts        # Operation type definitions
+├── src/                          # Your custom implementation
+│   ├── reducers/
+│   │   └── todos.ts            # Reducer functions (to implement next)
+│   └── tests/
+│       └── todos.test.ts        # Test file scaffolding
+├── todo-list.json               # Document model specification
+└── schema.graphql               # GraphQL schema
+```
+
+### Compare with reference
+
+Verify your generated files match the expected structure:
+
+```bash
+# Compare your generated files with step-2
+git diff tutorial/step-2-generate-todo-list-document-model -- document-models/todo-list/
+
+# List what was generated in the reference
+git ls-tree -r --name-only tutorial/step-2-generate-todo-list-document-model document-models/todo-list/
+```
+
 ### Up next: reducers
 
-Up next, you'll learn how to implement the runtime logic and components that will use the `ToDoList` document model specification you've just created and exported.
+Up next, you'll learn how to implement the runtime logic and components that will use the `TodoList` document model specification you've just created and exported.