@powerhousedao/academy 5.1.0-dev.9 → 5.1.0

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/06-DocumentTools/00-DocumentToolbar.mdx

@@ -1,9 +1,5 @@
 # Document Toolbar
 
-:::warning Work in Progress
-This documentation is still being written and may be incomplete.
-:::
-
 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">

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

@@ -63,10 +63,6 @@ You can also view the committer's address for each revision, supporting full tra
 
 ![Committer Address Popup](./images/committer-address-popup.png)
 
-
-:::warning Work in Progress
-This remainder of this documentation is still being written and may be incomplete.
-:::
 ## Replay, branch, and merge (under development)
 
 - **Replay:** When you load a document, the system replays all operations to build its state.

package/docs/academy/02-MasteryTrack/05-Launch/04-ConfigureEnvironment.md

@@ -75,7 +75,7 @@ PH_CONNECT_ARBITRUM_ALLOW_LIST=""
 PH_CONNECT_RWA_ALLOW_LIST=""
 PH_CONNECT_HIDE_DOCUMENT_MODEL_SELECTION_SETTINGS="true"
 
-PH_CONNECT_RENOWN_URL="https://www.renown.id"
+PH_CONNECT_RENOWN_URL="https://auth.renown.id"
 PH_CONNECT_RENOWN_NETWORK_ID="eip155"
 PH_CONNECT_RENOWN_CHAIN_ID=1
 PH_CONNECT_DISABLED_EDITORS="powerhouse/document-drive"

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

@@ -1,112 +1,46 @@
-# Create a new chatroom project
+# Create New Powerhouse Project
 
-:::tip Tutorial Repository
-📦 **Reference Code**: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo)
+:::tip **Prerequisites**
 
-This tutorial has a complete reference implementation available. You can:
-- View the complete code for each step
-- Clone and compare your implementation
-- Use `git diff` to compare your code with the reference
-:::
-
-<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.
-
-### 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: ChatRoom
-   cd ChatRoom
-   ```
-
-2. **Add the tutorial repository as a remote** to access reference code:
-   ```bash
-   git remote add tutorial https://github.com/powerhouse-inc/chatroom-demo.git
-   git fetch tutorial --prune
-   ```
-
-3. **Create your own branch** to keep your work organized:
-   ```bash
-   git checkout -b my-chatroom-project
-   ```
-
-Now you have access to the complete reference implementation while working on your own code!
-
-### Compare your work with the reference
-
-At any point, compare what you've built with the reference:
-
-```bash
-# Compare your current work with the reference
-git diff tutorial/main
-
-# Compare specific files
-git diff tutorial/main -- package.json
-```
-
-### If you get stuck
-
-Reset your code to match the reference:
-
-```bash
-# Reset to reference (WARNING: loses your changes)
-git reset --hard tutorial/main
-```
-
-</details>
-
-## Overview
-
-This tutorial guides you through creating a **ChatRoom** application using Powerhouse.  
-A Powerhouse project primarily consists of a document model and its editor. The ChatRoom demonstrates real-time collaboration features where users can post messages and react with emojis.
-
-## Prerequisites
-
-- Powerhouse CLI installed: `pnpm install -g ph-cmd` or `npm install -g ph-cmd`
-- node.js 22 and a package manager (pnpm or npm) installed
+- Powerhouse CLI installed: `pnpm install -g ph-cmd`
+- node.js 22 and pnpm installed
 - Visual Studio Code (or your preferred IDE)
 - Terminal/Command Prompt access
 
 If you need help with installing the prerequisites you can visit our page [prerequisites](/academy/MasteryTrack/BuilderEnvironment/Prerequisites)
+:::
 
-## Quick start
-
-Create a new Powerhouse project with a single command:
+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.
+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
-ph init
+mkdir ph-projects
+cd ph-projects
 ```
 
-## Before you begin
+This essentially opens that folder and places you in it.
 
-1. Open your terminal (either your system terminal or IDE's integrated terminal)
-2. Optionally, create a folder first to keep your Powerhouse projects:
+Once you've navigated to the directory where you want to create the new project and in your terminal, run the following command:
 
-   ```bash
-   mkdir ph-projects
-   cd ph-projects
-   ```
+```bash
+ph init
+```
 
-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.
+In the terminal, you will be asked to enter the project name. Fill in the project name and press enter. Make sure to pay attention to the capitalization of our name `ChatRoom` as it will influence your code generation.
 
-   ```bash
-   you@yourmachine:~/ph-projects % ph init
+```bash
+you@yourmachine:~/Powerhouse$ ph init
 
-   ? What is the project name? ‣ ChatRoom
-   ```
+? What is the project name? ‣ ChatRoom
+```
 
 Once the project is created, you will see the following output:
 
 ```bash
-Initialized empty Git repository in /Users/you/ph-projects/ChatRoom/.git/
-The installation is done!
+ The installation is done!
+
+ You can start by typing:
+    cd ChatRoom
 ```
 
 Navigate to the newly created project directory:
@@ -115,9 +49,9 @@ Navigate to the newly created project directory:
 cd ChatRoom
 ```
 
-## Develop your document model in Connect
+Once you are in the project directory, now you can run the `ph connect` command to instantiate a local version of the Connect application to start building your document model.
 
-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:
 
 ```bash
 ph connect
@@ -126,36 +60,26 @@ ph connect
 The Connect application will start and you will see the following output:
 
 ```bash
+you@yourmachine:~/Powerhouse/chatroom$ ph run connect
+
+> Chatroom@1.0.0 connect
+> connect --config-file ./powerhouse.config.json
+
+Watching local document models at '/home/you/Powerhouse/ChatRoom/document-models'...
+Watching local document editors at '/home/you/Powerhouse/ChatRoom/editors'...
   ➜  Local:   http://localhost:3000/
-  ➜  Network: http://192.168.5.110:3000/
   ➜  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.
 
-:::tip 
-If your local drive is not present, navigate to Settings in the bottom left corner. Settings > Danger Zone > Clear Storage.
-Clear the storage of your localhost application as it might have an old session cached.
-:::
+If you don't have a local drive created yet, create one using the Generic Drive Explorer app.
 
-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. Name your document `ChatRoom` (PascalCase, no spaces or hyphens).
+Open your Local Drive and create a new document model by clicking the `DocumentModel` button in the "New Document" section. The GIF below shows where to click.
 
-   **Pay close attention to capitalization, as it influences code generation.**
 
 ![Create New Document Model](./images/ChatRoomConnectApp.gif)
 
-If you've followed the steps correctly, you'll have an empty `ChatRoom` document where you can define the **'Document Specifications'**.
-
-## Verify your setup
-
-At this point, your project structure should include:
-
-- 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`
-
-## Up next
+If you followed the steps correctly, you should have an empty document model created called `ChatRoom`.
 
 In the next tutorial, you will learn how to design your document model and export it to be later used in your Powerhouse project.

package/docs/academy/03-ExampleUsecases/Chatroom/03-DefineChatroomDocumentModel.md

@@ -1,100 +1,54 @@
-# Write the document specification
+# Define the chatroom document model
 
-:::tip Tutorial Repository
-📦 **Reference Code**: [chatroom-demo](https://github.com/powerhouse-inc/chatroom-demo)
+In this tutorial, you will learn how to design your document model and export it to be later used in your Powerhouse project.
+If you don't have a document model created yet, have a look at the previous steps of this tutorial to create a new document model.
 
-This tutorial step has a corresponding implementation in the repository. After completing this step, your project will have a document model specification with:
-- Document model specification files (`chat-room.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 ChatRoom.phd`, compare with the reference:
-
-```bash
-# Compare all generated files with the reference
-git diff tutorial/main -- document-models/chat-room/
-
-# View a specific file from the reference
-git show tutorial/main:document-models/chat-room/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/main`
-3. Review all file differences in the visual interface
-
-See step 1 for detailed GitHub Desktop instructions.
+Before you start, make sure you have the Connect application running.
 
-</details>
+## Chatroom document model schema
 
-In this tutorial, you will learn how to define the specifications for a **ChatRoom** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
+We use GraphQL Schema Definition Language (SDL) to define the document model schema. Below, you can see the SDL for the `ChatRoom` document model.
 
-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:
-
-```bash
-ph connect
-```
-
-## ChatRoom document specification
-
-Make sure you have named your document model `ChatRoom` (PascalCase, no spaces or hyphens).  
-**Pay close attention to capitalization, as it influences code generation.**
-
-We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model. Below, you can see the SDL for the `ChatRoom` document model.
-
-:::info
-This schema defines the **data structure** of the document model and the types involved in its operations. Documents in Powerhouse leverage **event sourcing principles**, where every state transition is represented by an operation. GraphQL input types describe operations, ensuring that user intents are captured effectively.
+:::info **The State Schema**
+This schema contains the data structure of the document model and the basic operations that can be performed on the document model. For more in depth information please visit [State Schema](/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
 :::
 
-<details>
-<summary>State schema of our ChatRoom</summary>
+## State schema (See next steps)
 
 ```graphql
-# The state of our ChatRoom
+# Defines a GraphQL type for the state of the chatroom document
 type ChatRoomState {
-  id: OID!              # Unique identifier for the chat-room
-  name: String!         # Name of the chat-room
-  description: String   # Optional description of the chat-room
-  createdAt: DateTime!  # Timestamp of when the chat-room was created
-  createdBy: ID!        # Agent ID of the user who created the chat-room
+  id: OID! # Unique identifier for the chat-room
+  name: String! # Name of the chat-room
+  description: String # Optional description of the chat-room
+  createdAt: DateTime! # Timestamp of when the chat-room was created
+  createdBy: ID! # Agent ID of the user who created the chat-room
   messages: [Message!]! # List of messages in the chat-room
 }
 
-# A single message in the chat-room
+# Defines a GraphQL type for the state of a message
 type Message {
-  id: OID!              # Unique identifier for the message
-  sender: Sender!       # Agent details of the message sender
-  content: String       # Message content
-  sentAt: DateTime!     # Timestamp of when the message was sent
+  id: OID! # Unique identifier for the message
+  sender: Sender! # Agent details of the message sender
+  content: String # Message content
+  sentAt: DateTime! # Timestamp of when the message was sent
   reactions: [Reaction!] # Reactions to the message
 }
 
-# The sender of a message
+# Defines a GraphQL type for the state of a sender
 type Sender {
-  id: ID!               # Unique identifier for the sender
+  id: ID! # Unique identifier for the sender
   name: String
-  avatarUrl: URL        # Allows us to pull the ENS and/or NFT of the person's profile
+  avatarUrl: URL # Allows us to pull the ENS and/or nft of the persons profile
 }
 
-# A reaction to a message
+# Defines a GraphQL type for the state of a reaction to a message
 type Reaction {
-  type: ReactionType!   # Type of reaction (one of the predefined emoji)
-  reactedBy: [ID!]!     # Agent IDs of users who reacted
+  type: ReactionType! # Type of reaction (one of the predefined emoji)
+  reactedBy: [ID!]! # Agent ID of the user who reacted
 }
 
-# The predefined emoji reactions
+# Defines the various predefined emojis to react to a message
 enum ReactionType {
   THUMBS_UP
   THUMBS_DOWN
@@ -102,72 +56,38 @@ enum ReactionType {
   HEART
   CRY
 }
+```
 
-type ChatRoomState {
-  id: OID!
-  name: String!
-  description: String
-  createdAt: DateTime
-  createdBy: ID
-  messages: [Message!]!
-}
-
-type Message {
-  id: OID!
-  sender: Sender!
-  content: String
-  sentAt: DateTime!
-  reactions: [Reaction!]
-}
-
-type Sender {
-  id: ID!
-  name: String
-  avatarUrl: URL
-}
-
-type Reaction {
-  type: ReactionType!
-  reactedBy: [ID!]!
-}
-
-enum ReactionType {
-  THUMBS_UP
-  THUMBS_DOWN
-  LAUGH
-  HEART
-  CRY
-}
+## Operations schema (See next steps)
 
-# messages
+```graphql
+# add_message
 
 input AddMessageInput {
-  messageId: OID!
-  sender: SenderInput!
-  content: String!
+  messageId: OID! # ID of the message that is being added
+  sender: SenderInput! # ID of the user sending the message
+  content: String! # Content of the message
   sentAt: DateTime!
 }
 
 input SenderInput {
-  id: ID!
+  id: ID! # Unique identifier for the sender
   name: String
-  avatarUrl: URL
+  avatarUrl: URL # Allows us to pull the ENS and/or nft of the persons profile
 }
 
 input AddEmojiReactionInput {
-  messageId: OID!
-  reactedBy: ID!
-  type: ReactionType!
+  messageId: OID! # ID of the message to which the reaction is being added
+  reactedBy: ID! # ID of the user adding the reaction
+  type: ReactionType! # Type of the reaction (emoji)
 }
 
 input RemoveEmojiReactionInput {
-  messageId: OID!
-  senderId: ID!
-  type: ReactionType!
+  messageId: OID! # ID of the message to which the reaction is being removed
+  senderId: ID! # ID of the user that is removing the reaction
+  type: ReactionType! # Type of the reaction (emoji)
 }
 
-# settings
-
 input EditChatNameInput {
   name: String
 }
@@ -177,154 +97,55 @@ input EditChatDescriptionInput {
 }
 ```
 
-</details>
+## Define the document model
 
-<details>
-<summary>Messages Module: Operations schema of our ChatRoom Messages</summary>
+To be able to define the document model, you need to open the Chatroom document model editor in Connect.
 
-```graphql
-# Add a new message to the chat-room
-input AddMessageInput {
-  messageId: OID!       # ID of the message being added
-  sender: SenderInput!  # Sender information
-  content: String!      # Content of the message
-  sentAt: DateTime!     # Timestamp when the message was sent
-}
+The steps below show you how to do this:
 
-# Sender information for a message
-input SenderInput {
-  id: ID!               # Unique identifier for the sender
-  name: String
-  avatarUrl: URL        # Avatar URL for the sender
-}
+1. In the Connect application, click on the `ChatRoom` document model you've created in the previous step, to open the document model editor.
+2. You'll be welcomed with a form to fill, this is metadata about the document model, fill in the details in the fields.
 
-# Add an emoji reaction to a message
-input AddEmojiReactionInput {
-  messageId: OID!       # ID of the message to react to
-  reactedBy: ID!        # ID of the user adding the reaction
-  type: ReactionType!   # Type of the reaction (emoji)
-}
-
-# Remove an emoji reaction from a message
-input RemoveEmojiReactionInput {
-  messageId: OID!       # ID of the message to remove reaction from
-  senderId: ID!         # ID of the user removing the reaction
-  type: ReactionType!   # Type of the reaction (emoji)
-}
+   In the `Document Type` field, type `powerhouse/chat-room`. This defines the new type of document that will be created with this document model.
 
+   ![Chatroom Document Model Form Metadata](image-2.png)
 
-</details>
+3. In the code editor, you can see the SDL for the document model. Replace the existing SDL with the SDL defined in the [State Schema](#state-schema) section above. Only copy and paste the types, leaving the inputs for the next step. You can however already press 'Sync with schema' button to set the initial state of your document model based on your Schema Definition Language. Verify that your Global State Initial Value looks like this.
 
+```json
+{
+  "id": "",
+  "name": "",
+  "description": null,
+  "createdAt": null,
+  "createdBy": null,
+  "messages": []
+}
+```
 
-<details>
-<summary>Settings Module: Operations schema of our ChatRoom Settings</summary>
+4. Below the editor, there is an input field **'Add module'**. You need to create and name a module that the input operations will be added to. In this case, we will name the module **'general_operations'**. Press enter.
+5. Now there is a new field, called **'Add operation'**. Here you will have to add each input operation to the module, one by one.
+6. Inside the **'Add operation'** field, type **'ADD_MESSAGE'** and press enter. A small editor will appear under 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:
 
-# Edit the chat-room name
-input EditChatNameInput {
-  name: String
+```graphql
+input AddMessageInput {
+  messageId: OID!
+  sender: SenderInput!
+  content: String!
+  sentAt: DateTime!
 }
 
-# Edit the chat-room description
-input EditChatDescriptionInput {
-  description: String
+input SenderInput {
+  id: ID! # Unique identifier for the sender
+  name: String
+  avatarUrl: URL # Allows us to pull the ENS and/or nft of the persons profile
 }
 ```
 
-</details>
-
-## Define the document model specification
-
-To define the document model, you need to open the document model editor in Connect.
-
-### Steps to define your document model:
-
-1. In the Connect application, click on **'ChatRoom' Document** to open the document model specification editor.
-
-2. 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/chat-room` (lowercase with hyphen). This defines the new type of document that will be created with this document model specification.
-
-   ![Chatroom Document Model Form Metadata](image-2.png)
-
-3. 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** section above. Only copy and paste the types, leaving the inputs for the next step. You can press the 'Sync with schema' button to set the initial state of your document model based on your Schema Definition Language.
-
-4. Verify that your **Global State Initial Value** looks like this:
-
-   ```json
-    {
-      "name": "",
-      "description": null,
-      "createdAt": null,
-      "createdBy": null,
-      "messages": []
-    }
-   ```
-
-5. Below the editor, find the input field `Add module`. Create and name a module for organizing your input operations. Name the module `general_operations`. Press enter.
-
-6. Now there is a new field, called `Add operation`. Here you will add each input operation to the module, one by one.
-
-7. Inside the `Add operation` field, type `ADD_MESSAGE` and press enter. A small editor will appear underneath with an empty input type that you need to fill. Copy the `AddMessageInput` and `SenderInput` from the **Operations Schema** section and paste them in the editor:
-
-   ```graphql
-   input AddMessageInput {
-     messageId: OID!
-     sender: SenderInput!
-     content: String!
-     sentAt: DateTime!
-   }
-
-   input SenderInput {
-     id: ID!
-     name: String
-     avatarUrl: URL
-   }
-   ```
-
-8. Repeat step 7 for the other input operations: `ADD_EMOJI_REACTION`, `REMOVE_EMOJI_REACTION`, `EDIT_CHAT_NAME`, and `EDIT_CHAT_DESCRIPTION`. Note that you only need to add the operation name (e.g., `ADD_EMOJI_REACTION`) without the `Input` suffix—it will be generated automatically.
-
-9. Add reducer exceptions to the `ADD_MESSAGE` operation for validation: `MessageContentCannotBeEmpty` and `MessageContentExceedsTheMaximumLength`. These will be used later to validate messages.
-
-10. Once you have added all the input operations, click the `Export` button at the top right of the editor to save the document model specification to your local machine. Save the file in the root of your Powerhouse project.
+7. Repeat step 6 for the other input operations based on the [Operations Schema](#operations-schema). If you noticed, you only need to add the name `(ADD_EMOJI_REACTION, EDIT_CHAT_NAME, etc)` of the operation without the `input` suffix. Then it will be generated once you press enter.
+8. Let's just add a couple more reducer exceptions to the `ADD_MESSAGE` operation which we'll be using later to avoid empty messages or messages exceeding a maximum lenght. Add `MessageContentCannotBeEmpty` and `MessageContentExceedsTheMaximumLenght` to the reducer exceptions of `ADD_MESSAGE`
+9. Once you have added all the input operations, click on the `Export` button, at the top right of the editor, to save the document model on your local machine. Ideally you already save your file in the root of your powerhouse project on your machine.
 
 Check the screenshot below to verify the complete implementation:
 
 ![Chatroom Document Model](image-3.png)
-
-## Verify your document model generation
-
-After running `ph generate ChatRoom.phd`, your project should have the following structure in `document-models/chat-room/`:
-
-```
-document-models/chat-room/
-├── gen/                              # Auto-generated code (don't edit)
-│   ├── actions.ts
-│   ├── creators.ts                   # Action creator functions
-│   ├── types.ts                      # TypeScript type definitions
-│   ├── reducer.ts
-│   └── general-operations/
-│       └── operations.ts             # Operation type definitions
-├── src/                              # Your custom implementation
-│   ├── reducers/
-│   │   └── general-operations.ts     # Reducer functions (to implement next)
-│   └── tests/
-│       └── general-operations.test.ts # Test file scaffolding
-├── chat-room.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 the reference
-git diff tutorial/main -- document-models/chat-room/
-
-# List what was generated in the reference
-git ls-tree -r --name-only tutorial/main document-models/chat-room/
-```
-
-## Up next: Reducers
-
-In the next step, you'll learn how to implement the runtime logic that will use the `ChatRoom` document model specification you've just created and exported.