@powerhousedao/academy 2.5.0-dev.25 → 2.5.0-dev.26

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.5.0-dev.26 (2025-06-16)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
 ## 2.5.0-dev.25 (2025-06-13)
 
 ### 🚀 Features

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

@@ -18,7 +18,8 @@ Install the Powerhouse command-line tool `ph-cmd` and then use it to install a p
 
 ## Step 1: Install the Powerhouse CLI
 
-You will use the Powerhouse CLI to launch a local environment with a "**Contributor Billing**" package. This package demonstrates how you might track and bill for contributions in a project. First, you need the Powerhouse command-line interface (CLI). Open your terminal and run the installation command:
+You will use the Powerhouse CLI to launch a local environment with a "**ToDoList Demo Package**". 
+This is also the package that you'll recreate during the tutorials and get's you familiar with Powerhouse. 
 
 ```bash
 pnpm install -g ph-cmd
@@ -36,18 +37,13 @@ Now, use the `ph` command to install the demo package into a global project.
 
 ```bash
 # Install the package
-ph install @powerhousedao/contributor-billing
+ph install @powerhousedao/todo-demo-package.
 ```
 
-This command downloads and sets up the Contributor Billing package, making its features available in your Powerhouse environment.
+This command downloads and sets up the todo-demo-package, making its features available in your Powerhouse environment.
 
 You have now successfully installed `ph-cmd` and added your first package! 
 
-:::info 
-Let's explore what exactly you can do with this package. 
-At the bottom of the Connect Application you'll find a button with 'invoice'. This allows you to open an invoice document. The invoice document helps contributors to get paid for their work through crypto, stablecoins or a number of other currencies. Contributors can change the state of their invoice from draft to issued, while processors or clients can follow up on the payment of these invoices. In the next steps you can explore this for yourself. 
-:::
-
 ## Step 3: Run the Connect App in Studio mode
 To run the package locally in Connect Studio (our collaboration and contributor app), run the `ph connect` command. 
 

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

@@ -82,7 +82,9 @@ In the terminal, you will be asked to enter the project name. Fill in the projec
 
     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.    
+    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.   
 
 :::tip
 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)

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

@@ -79,7 +79,7 @@ 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**' in the Connect application, paying close attention to capitalization. 
 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.

package/docs/academy/01-GetStarted/03-ImplementOperationReducers.md

@@ -111,10 +111,10 @@ Here are the tests for the three operations implemented in the reducers file. Th
 <details>
 <summary>Operation Reducers Tests</summary>
 ```typescript
-import utils from '../../gen/utils';
-import { reducer } from '../../gen/reducer';
-import * as creators from '../../gen/creators';
-import { ToDoListDocument } from '../../gen/types';
+import utils from '../../gen/utils.js';
+import { reducer } from '../../gen/reducer.js';
+import * as creators from '../../gen/creators.js';
+import { ToDoListDocument } from '../../gen/types.js';
 
 // REMARKS:
 // These tests demonstrate the event sourcing principles of our document model.

package/docs/academy/01-GetStarted/04-BuildToDoListEditor.md

@@ -29,7 +29,7 @@ Manual build steps are typically only needed when publishing packages.
 
 ## ToDoList Editor
 
-Below is the complete code for the To-Do List editor. 
+Below is the complete code for the To-Do List editor. Paste this code in `editors/to-do-list/editor.tsx`.
 
 <details>
 <summary>Complete ToDoList Editor Example (using Tailwind CSS)</summary>
@@ -43,7 +43,7 @@ import {
     ToDoItem,
     actions,
     ToDoListDocument,
-} from '../../document-models/to-do-list';
+} from '../../document-models/to-do-list/index.js';
 import { useState } from 'react';
 
 // EditorProps is a generic type that provides the document and a dispatch function.
@@ -207,16 +207,12 @@ The editor will update dynamically, so you can play around with your editor styl
 Congratulations!
 If you managed to follow this tutorial until this point, you have successfully implemented the **ToDoList** document model with its reducer operations and editor. 
 
-### Up Next: Drive Explorers & Drive Apps
-
-Now you can move on to creating a [custom drive explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) for your ToDoList document.    
-Imagine you have many ToDoLists sitting in a drive. A custom drive explorer will allow you to organize and track them at a glance, opening up a new world of possibilities to increase the functionality of your documents!
-
-
 ### Up Next: Mastery Track
 
-In the [Mastery Track chapther: Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel) we guide you through the theoretics of the previous steps while created a more advanced ToDoList.
+In the [Mastery Track chapther: Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel) we guide you through the theoretics of the previous steps while created a more advanced version of the ToDoList.
+
 You will learn: 
 - The in's & out's of a document model.
 - How to use UI & Scalar components from the Document Engineering system.
+- How to build Custom Drive Apps or Drive Explorers. 
 

package/docs/academy/01-GetStarted/home.mdx

@@ -85,15 +85,7 @@ import BrowserOnly from '@docusaurus/BrowserOnly';
     position: 'relative'
   }}>
     <img src="/img/Union.svg" alt="Powerhouse Union" width="250" />
-    <div style={{
-      position: 'absolute',
-      top: '18px',
-      backgroundColor: 'white',
-      padding: '8px 16px',
-      borderRadius: '8px',
-      textAlign: 'center',
-      zIndex: 2,
-    }}>
+    <div className={styles.masteryTrackTitle}>
       <h3 className="card-title" style={{ margin: 0 }}>Mastery Track</h3>
     </div>
   </div>

package/docs/academy/01-GetStarted/styles.module.css

@@ -96,4 +96,35 @@
 :global(.path-button:hover) {
   background: #ffffff;
   border-color: #d1d5db;
+}
+
+.masteryTrackTitle {
+  background-color: white;
+  padding: 8px 16px;
+  border-radius: 8px;
+  text-align: center;
+  z-index: 2;
+  position: absolute;
+  top: 18px;
+}
+
+:global([data-theme='dark']) .masteryTrackTitle {
+  background-color: var(--ifm-card-background-color);
+  border: 1px solid var(--ifm-color-emphasis-200);
+}
+
+:global([data-theme='dark']) .pathCard {
+  background: var(--ifm-card-background-color);
+  border: 1px solid var(--ifm-color-emphasis-200);
+}
+
+:global([data-theme='dark']) :global(.path-button) {
+  background: var(--ifm-color-emphasis-100);
+  border-color: var(--ifm-color-emphasis-200);
+  color: var(--ifm-font-color-primary);
+}
+
+:global([data-theme='dark']) :global(.path-button:hover) {
+  background: var(--ifm-color-emphasis-200);
+  border-color: var(--ifm-color-emphasis-300);
 } 

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/02-StandardDocumentModelWorkflow.md

@@ -1,9 +1,13 @@
-# Creating Powerhouse packages
+# Create Powerhouse packages
 
-This tutorial guides you through creating a Powerhouse Document Model, from initial setup to publishing a distributable package. We'll leverage the Powerhouse CLI and Connect Studio Mode for a streamlined development experience.
+:::warning
+**This tutorial is a summary for builders that are familiar with building document models**.    
+It guides you through creating a Powerhouse Document Model, from initial setup to publishing a distributable package. 
+Please start with the '**Get Started**' Chapter or '**Document Model Creation**' section if you are unfamiliar with building a document model.
+:::
 
 <details>
-<summary>Key Commands</summary>
+<summary>Key Commands that you'll use in this flow</summary>
 
 -   `pnpm install -g ph-cmd`: Installs the Powerhouse CLI globally.
 -   `ph init`: Initializes a new Powerhouse project or sets up the local environment.

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/03-BuilderTools.md

@@ -1,6 +1,6 @@
 # Powerhouse Builder Tooling
 
-This page provides an overview of all the builder tooling offered by the Powerhouse ecosystem.
+This page provides an overview of all the builder tooling offered by the Powerhouse ecosystem.   
 This list will be maintained and updated as our toolkit grows.
 
 ## Powerhouse Command Line Interface

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/01-WhatIsADocumentModel.md

@@ -2,14 +2,14 @@
 
 :::tip
 This chapter on **Document Model Creation** will help you with an in depth practicial understanding while building an **advanced ToDoList** document model. 
-If you have completed the Get Started tutorial you will revisit familiar topics. 
+Although not required, if you have completed the 'Get Started' tutorial you will revisit familiar topics and can update your existing document model.
 :::
 
 :::info **Definition: What is a Document Model?**
 A Document Model is a programmable document structure that defines how data is stored, changed, and interpreted in a decentralized system. It acts like a living blueprint—capturing state, tracking changes, and enabling interaction through defined operations.
-:::
 
-For instance, an invoice document model might define fields like issuer, lineItems, and status, with operations such as AddLineItem and MarkAsPaid.
+For instance, an invoice document model might define fields like *issuer*, *lineItems*, and *status*, with operations such as *AddLineItem* and *MarkAsPaid*.
+:::
 
 A Document Model can be understood as: 
 - A structured software framework that represents and **manages business logic** within a digital environment. 
@@ -43,19 +43,19 @@ Example of a **GraphQL-like state schema** for an invoice document:
 
 ```graphql
 type InvoiceState {
-  id: OID!             # Unique identifier for the invoice
-  issuer: OID!         # Reference to the issuing entity
-  recipient: OID!      # Reference to the recipient entity
-  status: String @default(value: "DRAFT") # Invoice status
-  dueDate: DateTime    # Payment due date
+  id: OID!                # Unique identifier for the invoice
+  issuer: OID!            # Reference to the issuing entity
+  recipient: OID!         # Reference to the recipient entity
+  status: String          # (value: "DRAFT") # Invoice status
+  dueDate: DateTime       # Payment due date
   lineItems: [LineItem!]! # List of line items
-  totalAmount: Currency  # Computed field for total invoice value
+  totalAmount: Currency   # Computed field for total invoice value
 }
 
 type LineItem {
   id: OID!
   description: String
-  quantity: Int @default(value: 1)
+  quantity: Int 
   unitPrice: Currency
 }
 ```
@@ -64,7 +64,6 @@ type LineItem {
 
 - Uses **GraphQL-like definitions** for a **clear, structured schema**.
 - Supports **custom scalar types** like `OID`, `Currency`, and `DateTime`. Or other Web3 specific scalars
-- Allows **default values** using `@default(value: "DRAFT")`.
 - Defines **relationships** using object references (`OID!`).
 
 The state schema acts as a **template** for document instances. Every new invoice created will follow this structure.
@@ -81,7 +80,7 @@ Example operations for modifying an invoice:
 input AddLineItemInput {
   invoiceId: OID!
   description: String
-  quantity: Int @default(value: 1)
+  quantity: Int 
   unitPrice: Currency
 }
 
@@ -95,7 +94,8 @@ input MarkAsPaidInput {
 }
 ```
 
-Each operation **modifies the document state** without altering past data. Instead, a new event is appended to the document history.
+Each operation **modifies the document state** without altering past data.    
+Instead, a new event is appended to the document history.
 
 ---
 
@@ -202,4 +202,4 @@ Document Models are a powerful primitive within the Powerhouse vision, offering
 
 ### Up Next: How to build a Document Model
 
-In the next chapters, we'll teach you how to build a ToDoList document model while explaining all of the theory that is involved. d
+In the next chapters, we'll teach you how to build a ToDoList document model while explaining all of the theory that is involved.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/02-SpecifyTheStateSchema.md

@@ -31,6 +31,7 @@ You can modify types using lists and non-null indicators:
 ## Example: ToDoList State Schema
 
 Let's revisit the `ToDoList` example from the "Define the ToDoList document specification" tutorial.
+Only this time, we'll also add a 'Stats' type. Since we want to keep track of the number of completed To-Do's.
 
 ```graphql
 # The state of our ToDoList
@@ -44,6 +45,12 @@ type ToDoItem {
   text: String!
   checked: Boolean!
 }
+# The statistics on our to-do's
+type ToDoListStats {
+  total: Int!
+  checked: Int!
+  unchecked: Int!
+}
 ```
 
 ### Breakdown:
@@ -59,6 +66,11 @@ type ToDoItem {
     *   `text: String!`: The textual description of the to-do item. It cannot be null, ensuring every to-do has a description.
     *   `checked: Boolean!`: Indicates whether the to-do item is completed. It defaults to a boolean value (true or false) and cannot be null.
 
+*   **`ToDoListStats` type**: This type holds the summary statistics for the to-do list.
+    *   `total: Int!`: The total count of all to-do items. This field must be an integer and cannot be null.
+    *   `checked: Int!`: The number of to-do items that are marked as completed. This must be an integer and cannot be null.
+    *   `unchecked: Int!`: The number of to-do items that are still pending. This also must be an integer and cannot be null.
+
 ## Best Practices for Designing Your State Schema
 
 1.  **Start Simple, Iterate**: Begin with the core entities and properties. You can always expand and refine your schema as your understanding of the document's requirements grows.
@@ -73,5 +85,61 @@ type ToDoItem {
 
 By carefully defining your state schema, you lay a solid foundation for your Powerhouse document model, making it robust, maintainable, and easy to work with. The schema dictates not only how data is stored but also how it can be queried and mutated through operations, which will be covered in the next section.
 
-At the end of this Document Model Creation Chapter you will find the ToDoList Repository where you can explore the code and implementation of all the items we have discussed. 
-You'll be able to run the advanced ToDoList in Connect Studio and explore the reducers and editor code. 
+## Practical Implementation: Defining the State Schema in Connect
+
+Now that you understand the concepts behind the state schema, let's put it into practice. This section will guide you through creating a document model specification for the advanced ToDoList example discussed above.
+
+<details>
+<summary>Tutorial: The State Schema Specification</summary> 
+
+### Prerequisites
+
+-   You have a Powerhouse project set up. If not, please follow the [Create a new Powerhouse Project](../../GetStarted/CreateNewPowerhouseProject) tutorial.
+-   Connect Studio is running. If not, navigate to your project directory in the terminal and run `ph connect`.
+
+### Steps
+
+1.  **Create a New Document Model**:
+    -   With Connect Studio open in your browser, navigate into your local drive.
+    -   At the bottom of the page in the 'New Document' section, click the `DocumentModel` button to create a new document model specification.
+
+2.  **Define Document Metadata**:
+    -   **Name**: Give your document model a descriptive name, for example, `ToDoList`. **Pay close attention to capitalization, as it influences our code.**
+    -   **Document Type**: In the 'Document Type' field, enter a unique identifier for this document type, for instance, `powerhouse/todolist`.
+
+3.  **Specify the State Schema**:
+    -   In the code editor provided, you'll see a template for a GraphQL schema.
+    -   Replace the entire content of the editor with the advanced `ToDoList` schema we've designed in this chapter:
+
+    ```graphql
+    # The state of our ToDoList
+    type ToDoListState {
+      items: [ToDoItem!]!
+    }
+
+    # A single to-do item
+    type ToDoItem {
+      id: ID!
+      text: String!
+      checked: Boolean!
+    }
+    # The statistics on our to-do's
+    type ToDoListStats {
+      total: Int!
+      checked: Int!
+      unchecked: Int!
+    }
+    ```
+
+4.  **Sync Schema and View Initial State**:
+    -   After pasting the schema, click the **'Sync with schema'** button.
+    -   This action processes your schema and generates an initial JSON state for your document model based on the `ToDoListState` type. You can view this initial state, which helps you verify that your schema is structured correctly.
+
+    For now, you can ignore the "Modules & Operations" section. We will define and implement the operations that modify this state in the upcoming sections of this Mastery Track.
+
+By completing these steps, you have successfully specified the data structure for the advanced ToDoList document model. The next step is to define the operations that will allow users to interact with and change this state.
+
+</details>
+
+For a complete, working example, you can always refer to the [Example ToDoList Repository](./07-ExampleToDoListRepository.md) which contains the full implementation of the concepts discussed in this Mastery Track.
+

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/03-SpecifyDocumentOperations.md

@@ -16,10 +16,9 @@ Each operation acts as a command that, when applied, transitions the document fr
 
 ## Connecting Operations to the Schema
 
-In the "Define ToDoList Document Model" guide, we used GraphQL `input` types to define the structure of the data required for each operation. Let's revisit that:
+In the "Define ToDoList Document Model" chapter in the "Get Started" guide, we used GraphQL `input` types to define the structure of the data required for each operation. Let's revisit that:
 
 ```graphql
-# From 02-DefineToDoListDocumentModel.md
 # Defines a GraphQL input type for adding a new to-do item
 input AddTodoItemInput {
   id: ID!
@@ -96,7 +95,6 @@ The generated code from `ph generate` (as seen in `03-ImplementOperationReducers
 For example, the `ToDoListToDoListOperations` type generated by Powerhouse will expect methods corresponding to `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`.
 
 ```typescript
-// From 03-ImplementOperationReducers.md
 import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
 
 export const reducer: ToDoListToDoListOperations = {
@@ -112,6 +110,63 @@ export const reducer: ToDoListToDoListOperations = {
 };
 ```
 
+## Practical Implementation: Defining Operations in Connect
+
+Now that you understand the theory, let's walk through the practical steps of defining these operations for our `ToDoList` document model within the Powerhouse Connect application.
+
+<details>
+<summary>Tutorial: Specifying `ToDoList` Operations</summary>
+
+Assuming you have already defined the state schema for the `ToDoList` as covered in the previous section, follow these steps to add the operations:
+
+1.  **Create a Module for Operations:**
+    Below the schema editor in Connect, find the input field labeled `Add module`. Modules help organize your operations.
+    *   Type `to_do_list` into the field and press Enter.
+
+2.  **Add the `ADD_TODO_ITEM` Operation:**
+    A new field, `Add operation`, will appear under your new module.
+    *   Type `ADD_TODO_ITEM` into this field and press Enter.
+    *   An editor will appear for the operation's input type. You need to define the data required for this operation. Paste the following GraphQL `input` definition into the editor:
+
+    ```graphql
+    # Defines a GraphQL input type for adding a new to-do item
+    input AddTodoItemInput {
+      id: ID!
+      text: String!
+    }
+    ```
+
+3.  **Add the `UPDATE_TODO_ITEM` Operation:**
+    *   In the `Add operation` field again, type `UPDATE_TODO_ITEM` and press Enter.
+    *   Paste the corresponding `input` definition into its editor:
+
+    ```graphql
+    # Defines a GraphQL input type for updating a to-do item
+    input UpdateTodoItemInput {
+      id: ID!
+      text: String
+      checked: Boolean
+    }
+    ```
+
+4.  **Add the `DELETE_TODO_ITEM` Operation:**
+    *   Finally, type `DELETE_TODO_ITEM` in the `Add operation` field and press Enter.
+    *   Paste its `input` definition:
+
+    ```graphql
+    # Defines a GraphQL input type for deleting a to-do item
+    input DeleteTodoItemInput {
+      id: ID!
+    }
+    ```
+
+5.  **Review and Export:**
+    After adding all three operations, your document model specification in Connect is complete for now. You can see how each operation (`ADD_TODO_ITEM`, etc.) is now explicitly linked to an input type that defines its payload.
+
+    The next step in a real project would be to click the `Export` button to save this specification file. In the next chapter, we will see how this exported file is used to generate code for our reducers.
+
+</details>
+
 ## Conclusion
 
 Specifying document operations is a foundational step in building robust and predictable document models in Powerhouse. By clearly defining the **"what" (the operation and its input)** before implementing the **"how" (the reducer logic)**, you create a clear contract for state transitions. This approach enhances type safety, testability, and the overall maintainability of your document model.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/04-UseTheDocumentModelGenerator.md

@@ -90,22 +90,42 @@ Leveraging the `ph generate` command offers numerous advantages:
 5.  **Alignment with Powerhouse Ecosystem:** The generated code is designed to integrate seamlessly with other parts of the Powerhouse ecosystem, such as the reducer execution engine and UI components.
 6.  **Single Source of Truth:** Ensures that your codebase (especially types and action creators) stays synchronized with the document model specification defined in Connect. If the specification changes, regenerating the model will update these components accordingly.
 
-## Example Workflow Snippet
+## Practical Implementation: Generating the `ToDoList` Model
 
-Let's assume you have defined a `ProjectTask` document model and exported `ProjectTask.phdm.zip`.
+Now that you understand what the Document Model Generator does, let's walk through the practical steps of using it with our `ToDoList` example.
 
-1.  **Navigate to your Powerhouse project root in the terminal.**
-2.  **Run the generator:**
+<details>
+<summary>Tutorial: Generating the `ToDoList` Document Model</summary>
+
+This tutorial assumes you have completed the previous steps in this Mastery Track, where you defined the state schema and operations for the `ToDoList` model in Connect and exported it.
+
+### Prerequisites
+
+*   **`ToDoList.phdm.zip` file**: You must have the document model specification file exported from Connect. If you do not have this file, please revisit the previous sections on specifying the state schema and operations.
+
+### Steps
+
+1.  **Place the Specification File in Your Project**:
+    *   Navigate to the root directory of your Powerhouse project.
+    *   Move or copy your `ToDoList.phdm.zip` file into this directory.
+
+2.  **Run the Generator Command**:
+    *   Open your terminal in the root directory of your Powerhouse project.
+    *   Execute the `ph generate` command, pointing to your specification file:
     ```bash
-    ph generate ProjectTask.phdm.zip
+    ph generate ToDoList.phdm.zip
     ```
-3.  **Explore the generated files:**
-    You would now find a new directory `document-models/project-task/` containing:
-    *   `project-task/spec.json`
-    *   `project-task/schema.graphql`
-    *   `project-task/gen/types.ts` (with `ProjectTaskState`, `AssignUserInput`, etc.)
-    *   `project-task/gen/operations.ts` (with `creators.assignUser(...)`, `creators.completeTask(...)`, etc.)
-    *   `project-task/src/reducers/project-task.ts` (with empty functions like `assignUserOperation`, `completeTaskOperation` awaiting your implementation).
+
+3.  **Explore the Generated Files**:
+    *   After the command completes successfully, you will find a new directory: `document-models/to-do-list/`.
+    *   Take a moment to explore its contents, which will match the structure described earlier in this document:
+        *   `spec.json` and `schema.graphql`: The definition of your model.
+        *   `gen/`: Type-safe, generated code including `types.ts`, `operations.ts`, etc.
+        *   `src/`: The skeleton for your implementation, most importantly `src/reducers/to-do-list.ts`, which will contain empty functions for `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`, ready for you to implement.
+
+With these files generated, you have successfully scaffolded your document model. The project is now set up for you to implement the core business logic.
+
+</details>
 
 ## Next Steps
 

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/05-ImplementDocumentReducers.md

@@ -47,7 +47,6 @@ Let's break down its components and principles:
     While you can write one large reducer that uses a `switch` statement or `if/else if` blocks based on `action.type`, Powerhouse's generated code typically encourages a more modular approach. You'll often implement a separate function for each operation, which are then combined into a main reducer object or map. The `ph generate` command usually sets up this structure for you. For example, in your `document-models/to-do-list/src/reducers/to-do-list.ts`, you'll find an object structure like this:
 
     ```typescript
-    // Example structure from 01-GetStarted/03-ImplementOperationReducers.md
     import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js'; // Generated type for operations
     import { ToDoListState } from '../../gen/types.js'; // Generated type for state
 
@@ -76,9 +75,9 @@ Let's break down its components and principles:
 
 ## Implementing Reducer Logic: A Practical Guide
 
-Let's use our familiar `ToDoList` example (as detailed in `01-GetStarted/03-ImplementOperationReducers.md`) to illustrate common patterns.
+Let's use our familiar `ToDoList` example to illustrate common patterns. For this example, we'll assume our state schema has been updated to include a `stats` object to track the number of total, checked, and unchecked items.
 
-Assume our `ToDoListState` is:
+Our `ToDoListState` now looks like this:
 ```typescript
 interface ToDoItem {
   id: string;
@@ -86,8 +85,15 @@ interface ToDoItem {
   checked: boolean;
 }
 
+interface ToDoListStats {
+  total: number;
+  checked: number;
+  unchecked: number;
+}
+
 interface ToDoListState {
   items: ToDoItem[];
+  stats: ToDoListStats;
 }
 ```
 
@@ -226,46 +232,105 @@ Using these types provides:
 *   **Autocompletion and IntelliSense**: Improved developer experience in your IDE.
 *   **Clearer code**: Types serve as documentation for the expected data structures.
 
-## Testing Your Reducers
+## Practical Implementation: Writing the `ToDoList` Reducers
+
+Now that you understand the principles, let's put them into practice by implementing the reducers for our `ToDoList` document model.
+
+<details>
+<summary>Tutorial: Implementing the `ToDoList` Reducers</summary>
 
-Reducers, being pure functions, are inherently easy to test. For each reducer:
-1.  Set up an initial state.
-2.  Create an action object (ideally using the generated action creators from `../../gen/creators.js` or `../../gen/operations.js`).
-3.  Call the reducer function with the initial state and the action.
-4.  Assert that the returned new state is what you expect it to be.
-5.  Crucially, also assert that the *original* state object was not modified.
+This tutorial assumes you have followed the steps in the previous chapters, especially using `ph generate ToDoList.phdm.zip` to scaffold your document model's code.
 
-The `01-GetStarted/03-ImplementOperationReducers.md` document provides excellent examples of reducer tests:
+### Implement the Operation Reducers
+
+Navigate to `document-models/to-do-list/src/reducers/to-do-list.ts`. The generator will have created a skeleton file. Replace its contents with the following logic.
 
 ```typescript
-// Example from 01-GetStarted/03-ImplementOperationReducers.md (simplified)
-import utils from '../../gen/utils'; // For createDocument
-import { reducer } from '../../gen/reducer'; // The combined reducer
-import * as creators from '../../gen/creators'; // Action creators
-import { ToDoListDocument, ToDoListState } from '../../gen/types';
-
-describe('Todolist Operations', () => {
-  let document: ToDoListDocument; // Assuming ToDoListDocument wraps ToDoListState
-
-  beforeEach(() => {
-    document = utils.createDocument(); // Gets initial state
-  });
-
-  it('should handle addTodoItem operation', () => {
-    const input = { id: '1', text: 'Buy milk' };
-    const action = creators.addTodoItem(input); // Use action creator
-
-    // Assuming your main reducer takes the whole document and action
-    const updatedDocument = reducer(document, action);
-
-    expect(updatedDocument.state.global.items).toHaveLength(1);
-    expect(updatedDocument.state.global.items[0].text).toBe('Buy milk');
-    // Also check that document.state.global.items is different from updatedDocument.state.global.items (immutability)
-  });
-});
+import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
+import { ToDoListState } from '../../gen/types.js'; // Assuming this now includes the 'stats' object
+
+// REMARKS: This is our main reducer object. It implements all operations defined in the schema.
+// The ToDoListToDoListOperations type is auto-generated from our GraphQL specification and ensures type safety.
+export const reducer: ToDoListToDoListOperations = {
+    // REMARKS: The addTodoItemOperation adds a new item and updates our tracking statistics.
+    // - state: The current document state. Powerhouse uses a library like Immer.js,
+    //   so you can write code that looks like it's mutating the state directly.
+    //   Behind the scenes, Powerhouse ensures this results in an immutable update.
+    // - action: Contains the operation's 'type' and 'input' data from the client.
+    // - dispatch: A function to trigger subsequent operations (advanced, not used here).
+    addTodoItemOperation(state, action, dispatch) {
+        // REMARKS: We update our statistics for total and unchecked items.
+        state.stats.total += 1;
+        state.stats.unchecked += 1;
+
+        // REMARKS: We push the new to-do item into the items array.
+        // The data for the new item comes from the operation's input.
+        state.items.push({
+            id: action.input.id,
+            text: action.input.text,
+            checked: false, // New items always start as unchecked.
+        });
+    },
+
+    // REMARKS: The updateTodoItemOperation modifies an existing to-do item.
+    // It handles partial updates for text and checked status.
+    updateTodoItemOperation(state, action, dispatch) {
+        // REMARKS: First, we find the specific item we want to update using its ID.
+        const item = state.items.find(item => item.id === action.input.id);
+        
+        // REMARKS: It's good practice to handle cases where the item might not be found.
+        if (!item) {
+            throw new Error(`Item with id ${action.input.id} not found`);
+        }
+        
+        // REMARKS: We only update the text if it was provided in the input.
+        // This allows for partial updates (e.g., just checking an item without changing its text).
+        if (action.input.text) {
+            item.text = action.input.text;
+        }
+
+        // REMARKS: When the checked status changes, we also update our statistics.
+        // We check for `true` and `false` explicitly.
+        if (action.input.checked) { // This is true only if action.input.checked is true
+            // Note: This assumes the item was previously unchecked. For a more robust implementation,
+            // you could check `if (item.checked === false)` before updating stats to prevent inconsistencies.
+            state.stats.unchecked -= 1;
+            state.stats.checked += 1;
+            item.checked = action.input.checked;
+        }
+        if (action.input.checked === false) {
+            // Note: This assumes the item was previously checked.
+            state.stats.unchecked += 1;
+            state.stats.checked -= 1;
+            item.checked = action.input.checked;
+        }
+    },
+
+    // REMARKS: The deleteTodoItemOperation removes an item from the list.
+    deleteTodoItemOperation(state, action, dispatch) {
+        // REMARKS: Before removing the item, we find it to determine its checked status.
+        // This is necessary to correctly decrement our statistics.
+        const item = state.items.find(item => item.id === action.input.id);
+
+        // REMARKS: We always decrement the total count.
+        state.stats.total -= 1;
+
+        // REMARKS: We then decrement the 'checked' or 'unchecked' count based on the item's status.
+        if (item?.checked) { // This is shorthand for item?.checked === true
+            state.stats.checked -= 1;
+        }
+        if (item?.checked === false) {
+            state.stats.unchecked -= 1;
+        }
+
+        // REMARKS: Finally, we create a new 'items' array that excludes the deleted item.
+        // Assigning to 'state.items' is handled by Powerhouse to produce a new immutable state.
+        state.items = state.items.filter(item => item.id !== action.input.id);
+    },
+};
 ```
 
-The generator typically creates a test file skeleton (e.g., `document-models/<YourModelName>/src/reducers/tests/<your-model-name>.test.ts`) to get you started. **Thoroughly testing your reducers is paramount for a robust document model.**
+</details>
 
 ## Reducers and the Event Sourcing Model
 
@@ -279,4 +344,4 @@ This is why purity and immutability are so critical:
 
 Implementing document reducers is where you breathe life into your document model's specification. By adhering to the principles of purity and immutability, and by leveraging the type safety provided by Powerhouse's code generation, you can build predictable, testable, and maintainable business logic. These reducers form the immutable backbone of your document's state management, perfectly aligning with the event sourcing architecture that underpins Powerhouse.
 
-With your reducers implemented and tested, your document model is now functionally complete from a data manipulation perspective. The next stages often involve building user interfaces or integrations that interact with this model by dispatching the operations you've now so carefully implemented.
+With your reducers implemented, your document model is now functionally complete from a data manipulation perspective. The next chapter covers how to write tests for this logic to ensure its correctness and reliability.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/06-ImplementDocumentModelTests.md

@@ -2,267 +2,124 @@
 
 ## Ensuring Robustness and Reliability
 
-In the previous sections, we've meticulously defined our document model's state schema, specified its operations, used the generator to scaffold our codebase, and implemented the core reducer logic. Now, we reach a critical stage that underpins the reliability and correctness of our entire document model: **Implementing Document Model Tests**.
+In the previous chapter, we implemented the core reducer logic for our document model. Now, we reach a critical stage that underpins the reliability and correctness of our entire model: **Implementing Document Model Tests**.
 
-Testing is not merely an afterthought; it's an integral part of the development lifecycle, especially in systems like Powerhouse where data integrity, predictable state transitions, and auditable histories are paramount. Well-crafted tests serve as a safety net, allowing you to refactor and extend your document model with confidence, ensuring that it behaves as expected under all conditions.
+Testing is not an afterthought; it's an integral part of the development lifecycle, especially in systems like Powerhouse where data integrity and predictable state transitions are paramount. Well-crafted tests serve as a safety net, allowing you to refactor and extend your document model with confidence.
 
-This document will provide a deep dive into testing Powerhouse document models, focusing on the testing of reducer logic, which forms the heart of your model's behavior.
+This document provides a practical, hands-on tutorial for testing the `ToDoList` document model reducers you have just built.
 
-## The Importance of Testing Document Model Reducers
+## Practical Implementation: Writing and Running the ToDoList Tests
 
-Document model reducers, as explored in "[Implement Document Reducers](05-ImplementDocumentReducers.md)", are pure functions responsible for calculating the next state of a document based on its current state and a given operation. Their purity and deterministic nature make them inherently testable. Testing reducers thoroughly ensures:
+This tutorial assumes you have implemented the `ToDoList` reducers as described in the previous chapter and that the code generator has created a test file skeleton at `document-models/to-do-list/src/reducers/tests/to-do-list.test.ts`.
 
-1.  **Correctness of Business Logic**: Verifies that each operation transforms the document state according to the defined business rules.
-2.  **State Immutability**: Confirms that reducers do not mutate the original state, a cornerstone of Powerhouse's event sourcing architecture.
-3.  **Integrity of Operation History**: While reducers focus on state, tests can also implicitly verify that operations are being correctly structured for the event log (as seen in example tests in `01-GetStarted/03-ImplementOperationReducers.md`).
-4.  **Regression Prevention**: Protects against accidental breakage of existing functionality when new features are added or existing code is refactored.
-5.  **Living Documentation**: Well-written tests can serve as examples of how operations are intended to be used and how they affect the document state.
+<details>
+<summary>Tutorial: Implementing and Running the `ToDoList` Reducer Tests</summary>
 
-## Setting Up the Test Environment
+### 1. Implement the Reducer Tests
 
-Powerhouse projects, when initialized using `ph init` (as detailed in "[Standard Document Model Workflow](../01-BuilderEnvironment/02-StandardDocumentModelWorkflow.md)"), typically come pre-configured with a testing framework like Jest. You'll find that test files often end with `.test.ts` (e.g., `your-model-name.test.ts`) and are co-located with the code they test, often in a `tests/` subdirectory within the `src/reducers/` folder.
+With the reducer logic in place, it's critical to test it. Navigate to the generated test file at `document-models/to-do-list/src/reducers/tests/to-do-list.test.ts` and replace its contents with the following test suite.
 
-The Document Model Generator (`ph generate YourModelName.phdm.zip`) usually creates a skeleton test file for your reducers (e.g., `document-models/YourModelName/src/reducers/tests/your-model-name.test.ts`). This provides a great starting point.
+This suite tests each operation, verifying not only that the `items` array is correct, but also that our `stats` object is updated as expected and that the operation itself is recorded properly in the document's history.
 
-Key tools and concepts you'll encounter in these test files include:
-
-*   **`describe(name, fn)`**: Creates a block that groups together several related tests.
-*   **`it(name, fn)`** or **`test(name, fn)`**: This is your actual test case.
-*   **`beforeEach(fn)`**: A function that runs before each test case in a `describe` block. Useful for setting up a common initial state for each test.
-*   **`expect(value)`**: Used with "matcher" functions to assert that a certain value meets expectations. Common matchers include `toBe()`, `toEqual()`, `toHaveLength()`, `toThrow()`, etc.
-
-## Core Components for Testing Document Model Reducers
-
-When testing your document model reducers, you'll primarily interact with artifacts generated by the Powerhouse Document Model Generator and the reducer logic you've written:
-
-1.  **Initial Document State (`utils.createDocument()`):**
-    *   The `gen/utils.ts` file (or similar) often exports a `createDocument()` function. This utility, derived from your state schema (including default values), is crucial for creating a fresh, predictable starting state for your document model instance before each test.
-    *   Example: `document = utils.createDocument();`
-
-2.  **Action Creators (`creators` or `operations`):**
-    *   The `gen/operations.ts` or `gen/creators.ts` file exports action creator functions for each operation defined in your schema. Using these functions (e.g., `creators.addTodoItem(input)`) instead of manually constructing action objects is highly recommended because they ensure your actions are correctly typed and structured, reducing the chance of errors in your tests.
-    *   Example: `const action = creators.addTodoItem({ id: '1', text: 'Test item' });`
-
-3.  **The Main Reducer (`reducer`):**
-    *   The primary export from your reducer implementation file (e.g., `document-models/YourModelName/src/reducers/your-model-name.ts`) is the main reducer object or function that combines all your individual operation handlers. This is what you'll call with the current state and an action to get the new state.
-    *   In some generated setups (like the `ToDoList` example from `01-GetStarted`), there might be a top-level `reducer` function exported from `gen/reducer.ts` that wraps your custom reducer logic and handles the overall document structure (state, operations history).
-    *   Example: `const updatedDocument = reducer(document, action);`
-
-4.  **Generated Types (`types.ts`):**
-    *   Using the TypeScript types from `gen/types.ts` (e.g., `ToDoListState`, `ToDoItem`, input types) in your test setup and assertions helps maintain type safety and clarity in your tests.
-
-## Writing Effective Test Cases for Reducers
-
-Let's draw inspiration from the `ToDoList` example tests found in `01-GetStarted/03-ImplementOperationReducers.md` and expand on the principles.
-
-A typical test file structure:
 ```typescript
-import utils from '../../gen/utils'; // For createDocument
-import { reducer } from '../../gen/reducer'; // The main reducer
-import * as creators from '../../gen/creators'; // Action creators
-import { ToDoListDocument, ToDoListState, ToDoItem } from '../../gen/types'; // Your model's types
-
-describe('ToDoList Document Model Operations', () => {
-  let initialDocument: ToDoListDocument; // Or your specific document type
-
-  beforeEach(() => {
-    // Start with a fresh, empty document for each test
-    initialDocument = utils.createDocument();
-  });
-
-  // Test suite for ADD_TODO_ITEM operation
-  describe('addTodoItemOperation', () => {
-    it('should add a new item to an empty list', () => {
-      const input = { id: 'task1', text: 'Buy groceries' };
-      const action = creators.addTodoItem(input);
-
-      const updatedDocument = reducer(initialDocument, action);
-      const state = updatedDocument.state.global; // Accessing the specific state slice
-
-      expect(state.items).toHaveLength(1);
-      expect(state.items[0]).toEqual({
-        id: 'task1',
-        text: 'Buy groceries',
-        checked: false, // Assuming default
-      });
-      // Verify immutability: the new items array should be a different instance
-      expect(state.items).not.toBe(initialDocument.state.global.items);
-    });
+import utils from '../../gen/utils.js';
+import { reducer } from '../../gen/reducer.js';
+import * as creators from '../../gen/creators.js';
+import { ToDoListDocument } from '../../gen/types.js';
 
-    it('should add a new item to an existing list', () => {
-      // First, add an initial item
-      const firstItemInput = { id: 'task1', text: 'First task' };
-      let currentDocument = reducer(initialDocument, creators.addTodoItem(firstItemInput));
-
-      // Now, add the second item
-      const secondItemInput = { id: 'task2', text: 'Second task' };
-      const action = creators.addTodoItem(secondItemInput);
-      currentDocument = reducer(currentDocument, action);
-
-      const state = currentDocument.state.global;
-      expect(state.items).toHaveLength(2);
-      expect(state.items[1]).toEqual({
-        id: 'task2',
-        text: 'Second task',
-        checked: false,
-      });
-    });
-  });
-
-  // Test suite for UPDATE_TODO_ITEM operation
-  describe('updateTodoItemOperation', () => {
-    let docWithItem: ToDoListDocument;
-    const initialItemId = 'item-to-update';
+describe('Todolist Operations', () => {
+    let document: ToDoListDocument;
 
     beforeEach(() => {
-      // Setup: add an item that can be updated in subsequent tests
-      const addAction = creators.addTodoItem({ id: initialItemId, text: 'Original Text' });
-      docWithItem = reducer(initialDocument, addAction);
+        // REMARKS: We start with a fresh, empty document for each test.
+        // The `createDocument` utility initializes the state with an empty 'items' array
+        // and a 'stats' object with all counts set to 0.
+        document = utils.createDocument();
     });
 
-    it('should update the text of an existing item', () => {
-      const updateInput = { id: initialItemId, text: 'Updated Text' };
-      const action = creators.updateTodoItem(updateInput);
-
-      const updatedDocument = reducer(docWithItem, action);
-      const item = updatedDocument.state.global.items.find(i => i.id === initialItemId);
-
-      expect(item).toBeDefined();
-      expect(item?.text).toBe('Updated Text');
-      // The 'checked' status should remain unchanged if not provided
-      expect(item?.checked).toBe(false);
-      // Verify immutability for the updated item and the items array
-      expect(updatedDocument.state.global.items).not.toBe(docWithItem.state.global.items);
-      expect(item).not.toBe(docWithItem.state.global.items.find(i => i.id === initialItemId));
+    it('should handle addTodoItem operation', () => {
+        const input = { id: '1', text: 'Buy milk' };
+        
+        // REMARKS: We apply the 'addTodoItem' operation.
+        const updatedDocument = reducer(document, creators.addTodoItem(input));
+
+        // REMARKS: We verify the operation was recorded in the document's history.
+        // Powerhouse records every operation in an array.
+        expect(updatedDocument.operations.global).toHaveLength(1);
+        expect(updatedDocument.operations.global[0].type).toBe('ADD_TODO_ITEM');
+        // REMARKS: We also check that the input data and index are recorded correctly.
+        expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+        expect(updatedDocument.operations.global[0].index).toEqual(0);
+
+        // REMARKS: Finally, we verify the state was updated according to our reducer logic.
+        expect(updatedDocument.state.global.items).toHaveLength(1);
+        expect(updatedDocument.state.global.stats.total).toBe(1);
+        expect(updatedDocument.state.global.stats.unchecked).toBe(1);
     });
 
-    it('should update the checked status of an existing item', () => {
-      const updateInput = { id: initialItemId, checked: true };
-      const action = creators.updateTodoItem(updateInput);
-
-      const updatedDocument = reducer(docWithItem, action);
-      const item = updatedDocument.state.global.items.find(i => i.id === initialItemId);
-
-      expect(item?.checked).toBe(true);
-      // The 'text' should remain unchanged
-      expect(item?.text).toBe('Original Text');
+    it('should handle updateTodoItem operation', () => {
+        // REMARKS: For an update, we first need to add an item.
+        const addInput = { id: '1', text: 'Buy milk' };
+        const updateInput = { id: '1', checked: true }; // We'll test checking the item.
+
+        // REMARKS: Operations are applied sequentially to build up document state.
+        const createdDocument = reducer(document, creators.addTodoItem(addInput));
+        const updatedDocument = reducer(createdDocument, creators.updateTodoItem(updateInput));
+
+        // REMARKS: Now we should have 2 operations in the history.
+        expect(updatedDocument.operations.global).toHaveLength(2);
+        expect(updatedDocument.operations.global[1].type).toBe('UPDATE_TODO_ITEM');
+        expect(updatedDocument.operations.global[1].input).toStrictEqual(updateInput);
+        
+        // REMARKS: We check that the state reflects the update, including our stats.
+        expect(updatedDocument.state.global.items[0].checked).toBe(true);
+        expect(updatedDocument.state.global.stats.total).toBe(1);
+        expect(updatedDocument.state.global.stats.unchecked).toBe(0);
+        expect(updatedDocument.state.global.stats.checked).toBe(1);
     });
 
-    it('should update both text and checked status', () => {
-      const updateInput = { id: initialItemId, text: 'New Text Again', checked: true };
-      const action = creators.updateTodoItem(updateInput);
+    it('should handle deleteTodoItem operation', () => {
+        const addInput = { id: '1', text: 'Buy milk' };
+        const deleteInput = { id: '1' };
 
-      const updatedDocument = reducer(docWithItem, action);
-      const item = updatedDocument.state.global.items.find(i => i.id === initialItemId);
+        const createdDocument = reducer(document, creators.addTodoItem(addInput));
+        const updatedDocument = reducer(createdDocument, creators.deleteTodoItem(deleteInput));
 
-      expect(item?.text).toBe('New Text Again');
-      expect(item?.checked).toBe(true);
+        // REMARKS: After deletion, we still have 2 operations in history,
+        // but the items array is now empty and the stats are back to zero.
+        expect(updatedDocument.operations.global).toHaveLength(2);
+        expect(updatedDocument.operations.global[1].type).toBe('DELETE_TODO_ITEM');
+        expect(updatedDocument.state.global.items).toHaveLength(0);
+        expect(updatedDocument.state.global.stats.total).toBe(0);
+        expect(updatedDocument.state.global.stats.unchecked).toBe(0);
     });
-
-    it('should throw an error or not change state if item to update is not found', () => {
-      const updateInput = { id: 'non-existent-id', text: 'Wont matter' };
-      const action = creators.updateTodoItem(updateInput);
-
-      // Depending on your reducer's error handling for "item not found":
-      // Option 1: Reducer throws an error (as in 01-GetStarted/03-ImplementOperationReducers.md example)
-      expect(() => reducer(docWithItem, action)).toThrowError('Item with id non-existent-id not found');
-      
-      // Option 2: Reducer returns original state (if it handles errors gracefully by not changing state)
-      // const updatedDocument = reducer(docWithItem, action);
-      // expect(updatedDocument.state.global).toEqual(docWithItem.state.global);
-    });
-  });
-
-  // Test suite for DELETE_TODO_ITEM operation
-  describe('deleteTodoItemOperation', () => {
-    let docWithItems: ToDoListDocument;
-    const item1Id = 'item1';
-    const item2Id = 'item2';
-
-    beforeEach(() => {
-      // Setup: add multiple items
-      const addAction1 = creators.addTodoItem({ id: item1Id, text: 'Item One' });
-      let tempDoc = reducer(initialDocument, addAction1);
-      const addAction2 = creators.addTodoItem({ id: item2Id, text: 'Item Two' });
-      docWithItems = reducer(tempDoc, addAction2);
-    });
-
-    it('should delete an existing item', () => {
-      const deleteInput = { id: item1Id };
-      const action = creators.deleteTodoItem(deleteInput);
-
-      const updatedDocument = reducer(docWithItems, action);
-      const state = updatedDocument.state.global;
-
-      expect(state.items).toHaveLength(1);
-      expect(state.items.find(item => item.id === item1Id)).toBeUndefined();
-      expect(state.items[0].id).toBe(item2Id);
-      // Verify immutability
-      expect(state.items).not.toBe(docWithItems.state.global.items);
-    });
-
-    it('should not change state if item to delete is not found', () => {
-      const deleteInput = { id: 'non-existent-id' };
-      const action = creators.deleteTodoItem(deleteInput);
-      
-      const updatedDocument = reducer(docWithItems, action);
-      expect(updatedDocument.state.global.items).toHaveLength(2);
-      expect(updatedDocument.state.global).toEqual(docWithItems.state.global); // Or check for array instance equality
-    });
-  });
-
-  // Testing Operation History (as shown in 01-GetStarted/03-ImplementOperationReducers.md)
-  it('should record operations in the document history', () => {
-    const addAction = creators.addTodoItem({ id: 'hist1', text: 'History Test' });
-    let doc = reducer(initialDocument, addAction);
-
-    expect(doc.operations.global).toHaveLength(1);
-    expect(doc.operations.global[0].type).toBe('ADD_TODO_ITEM'); // Ensure this matches actual operation type string
-
-    const updateAction = creators.updateTodoItem({ id: 'hist1', checked: true });
-    doc = reducer(doc, updateAction);
-
-    expect(doc.operations.global).toHaveLength(2);
-    expect(doc.operations.global[1].type).toBe('UPDATE_TODO_ITEM');
-  });
 });
 ```
 
-### Key Assertions to Make:
+### 2. Run the Tests
 
-1.  **State Changes**:
-    *   Verify that the relevant parts of the state are updated correctly (e.g., an item is added to an array, a field is changed).
-    *   Use `toEqual()` for deep equality checks on objects and arrays.
-    *   Check array lengths, specific property values, etc.
+Now, run the tests from your project's root directory to verify your implementation.
 
-2.  **Immutability**:
-    *   **Crucial**: Always assert that your reducers return *new* state objects/arrays when changes occur, rather than mutating the original ones.
-    *   For objects: `expect(newState).not.toBe(oldState);`
-    *   For arrays: `expect(newState.items).not.toBe(oldState.items);`
-    *   For modified items within an array: `expect(updatedItem).not.toBe(originalItem);`
+```bash
+pnpm run test
+```
 
-3.  **Operation History (if applicable at this testing layer)**:
-    *   As seen in `01-GetStarted/03-ImplementOperationReducers.md`, the top-level reducer provided by Powerhouse might also update an `operations` log in the document. If your tests involve this encompassing reducer, you can assert that operations are correctly recorded.
-    *   `expect(updatedDocument.operations.global).toHaveLength(expectedCount);`
-    *   `expect(updatedDocument.operations.global[index].type).toBe('EXPECTED_OPERATION_TYPE');`
+If all tests pass, you have successfully verified the core logic of your `ToDoList` document model. This ensures that the reducers you wrote behave exactly as expected.
 
-4.  **Edge Cases and Error Handling**:
-    *   Test what happens when an operation receives invalid input (e.g., trying to update/delete an item that doesn't exist).
-    *   If your reducer is designed to throw errors, use `expect(() => reducer(...)).toThrowError('Expected error message');`.
-    *   If it handles errors by returning the original state or a specific error state, test for that outcome.
+</details>
 
 ## Best Practices for Document Model Tests
 
-*   **Isolate Tests**: Each `it` block should ideally test one specific aspect or scenario. `beforeEach` can help reset state for this.
+While the tutorial provides a concrete example, keep these general best practices in mind when writing your tests:
+
+*   **Isolate Tests**: Each `it` block should ideally test one specific aspect or scenario. `beforeEach` is crucial for resetting state between tests.
 *   **Descriptive Names**: Name your `describe` and `it` blocks clearly so they explain what's being tested.
 *   **AAA Pattern (Arrange, Act, Assert)**:
-    *   **Arrange**: Set up the initial state and any required test data.
-    *   **Act**: Execute the operation (call the reducer).
-    *   **Assert**: Check if the outcome is as expected.
-*   **Test Pure Logic**: Focus on testing the input/output behavior of your reducers. Avoid testing implementation details if possible.
-*   **Cover All Operations**: Ensure every defined document operation has corresponding tests.
-*   **Cover All State Transitions**: For each operation, test different scenarios that lead to different state changes or outcomes.
-*   **Refactor Tests with Code**: As your reducer logic evolves, update your tests accordingly. Outdated tests are worse than no tests.
+    *   **Arrange**: Set up the initial state and any required test data (e.g., using `utils.createDocument()` and defining `input` objects).
+    *   **Act**: Execute the operation by calling the `reducer` with an action from a `creator`.
+    *   **Assert**: Check if the outcome is as expected using `expect()`.
+*   **Test Immutability**: A key assertion is to ensure the state is not mutated directly. You can check that a new array or object was created: `expect(newState.items).not.toBe(oldState.items);`.
+*   **Cover Edge Cases**: Test what happens when an operation receives invalid input (e.g., trying to update an item that doesn't exist). Your test should confirm the reducer either throws an error or returns the state unchanged, depending on your implementation.
 *   **Run Tests Frequently**: Integrate testing into your development workflow. Run tests after making changes to ensure you haven't broken anything. The `pnpm run test` command is your friend.
 
 ## Conclusion: The Payoff of Diligent Testing
@@ -274,4 +131,4 @@ Implementing comprehensive tests for your document model reducers is an investme
 *   **Easier Debugging**: When tests fail, they pinpoint the exact operation and scenario that's problematic.
 *   **Better Collaboration**: Tests clarify the intended behavior of the document model for all team members.
 
-By following the principles and practices outlined in this document, and by drawing on the generated code and examples provided by Powerhouse, you can build a strong suite of tests that safeguard the integrity and functionality of your document models. This diligence is a hallmark of a "Mastery Track" developer, ensuring that the solutions you build are not just functional but also stable, maintainable, and trustworthy.
+By following the tutorial and applying these best practices, you can build a strong suite of tests that safeguard the integrity and functionality of your document models. This diligence is a hallmark of a "Mastery Track" developer, ensuring that the solutions you build are not just functional but also stable, maintainable, and trustworthy.

package/docs/academy/02-MasteryTrack/05-Launch/03-SetupEnvironment.md

@@ -337,8 +337,11 @@ The `install` script provides a streamlined way to install the Powerhouse CLI to
     ```
     You will see that `ph-cli` is not yet installed. This is expected, as it will be installed by the service setup command.
 
-4. Create a project with `ph-init <projectname>`. After creation, move into the project with `cd <projectname>`. 
-   Up next is the configurations of your services. 
+4. Create a project with `ph-init <projectname>`. 
+
+5. After creation, move into the project with `cd <projectname>`. 
+
+Up next is the configurations of your services. 
 
 ### Service Configuration
 

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

@@ -15,19 +15,29 @@ 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. 
 :::
 
-In the next few chapters of our documentation, we will start with the simplest scalar components first, then move on to more complex, Powerhouse-specific components, and combine these in the Layout components.
+## Scalars vs. General UI Components
 
-## **3 types of components**
+### Scalar Components
 
-1. **Scalar Component** has a simple scalar value as input 
-    - Component, Composition of smaller UI controls (e.g. Scalar component)
-2. **Complex Component** has an object/array value 
-    - Group of components (e.g. sidebar tree view)
-3. **Layout Component** will contain other components 
-    - Containers for other components, Sections (e.g. list of other components, color layouts, etc.)
-4. **fragments Component** 
+Scalars are here to help you define custom fields in your document model schema and speed up the development process.
+There are two applications of scalar components in the document model workflow:
 
-For each of these components an implementation example will be given in our documentation. 
+1. At the **schema definition** level where you build your schema and write your GraphQL state schema.
+2. At the **frontend / react** level where you import it and place it in your UI to represent the scalar field
+
+These are specialized form components, each corresponding to a GraphQL scalar type (e.g., String, Number, Boolean, Currency, PHID). They are built on top of react-hook-form, offering out-of-the-box validation but must be wrapped with a Form component in order to work properly.
+
+**Location:** @powerhousedao/document-engineering/scalars    
+https://github.com/powerhouse-inc/document-engineering
+
+**Key Feature**: Must be used within a Form component provided by this library.
+
+### General-Purpose UI Components
+
+This category includes a broader range of UI elements such as simplified versions of the Scalar components (which don't require a Form wrapper but lack built-in validation), as well as other versatile components like Dropdown, Tooltip, Sidebar, ObjectSetTable and more. These are designed for crafting diverse and complex user interfaces.
+
+**Location:** @powerhousedao/document-engineering/ui   
+https://github.com/powerhouse-inc/document-engineering
 
 ## Exploring Components with Storybook
 
@@ -39,8 +49,15 @@ We use Storybook as an interactive catalog for our design system components. It
 2.  **Usage Snippet:** Below the demo, you'll typically find a basic code example demonstrating how to include the component in your code (e.g., `<Checkbox defaultValue label="Accept terms and conditions" />`). This provides a starting point for implementation.
 3.  **Props Table:** Further down, a table lists the properties (`props`) the component accepts. Props are like settings or configuration options. For the `Checkbox`, this table would show props like `label`, `defaultValue`, `value`, `onChange`, etc., often with descriptions of what they control.
 
+## **Storybook vs. Source Code:**
+
+Storybook serves as essential documentation and a usage guide. Our developers write Storybook "stories" to demonstrate components and document their common props. However, the **ultimate source of truth** for a component's capabilities is its actual source code (e.g., the `.tsx` file within the `@powerhousedao/document-engineering/scalars` package).
+While Storybook aims for accuracy, there might occasionally be discrepancies or undocumented props.
+
 ## Implementing a Component
 
+@callme-t
+
 Let's walk through the typical workflow for using a component from the document-engineering system, using the `Checkbox` from the [To-do List editor](/academy/GetStarted/BuildToDoListEditor).
 
 1.  **Identify the Need:** While building your feature (e.g., the To-do List editor in `editor.tsx`), you determine the need for a standard UI element, like a checkbox.
@@ -124,12 +141,6 @@ Within the project, the following import maps are available:
 - `#ui` - UI components 
 - `#graphql` - GraphQL related utilities
 
-
-## **Storybook vs. Source Code:**
-
-Storybook serves as essential documentation and a usage guide. Our developers write Storybook "stories" to demonstrate components and document their common props. However, the **ultimate source of truth** for a component's capabilities is its actual source code (e.g., the `.tsx` file within the `@powerhousedao/document-engineering/scalars` package).
-While Storybook aims for accuracy, there might occasionally be discrepancies or undocumented props.
-
 Please don't hesitate to reach out in our discord channels with any questions.    
 Happy designing! 
 

package/docs/academy/06-ComponentLibrary/02-CreateCustomScalars.md

@@ -3,13 +3,6 @@
 This tutorial provides step-by-step instructions for creating custom scalars & components, and to contributing to the document-engineering project.
 The github repo for the Document-Engineering can be found [here](https://github.com/powerhouse-inc/document-engineering/tree/main)
 
-:::info
-When contributing as an open source developer please submit a pull request to the Powerhouse team. 
-Although a design or UI for your scalar is not mandatory, it definitely helps reviewers if there's a visual reference. 
-That said, not all scalars require a dedicated UI component. 
-Some scalars, like scalar Title or scalar Description, might both map to a string and use the same UI, in this case scalars plays more semantic role than a type definition.
-:::
-
 ## Table of Contents
 
 - [Creating New GraphQL Scalars](#creating-new-graphql-scalars)
@@ -393,6 +386,14 @@ export const type = 'string'
 export const schema = z.string().datetime()
 ```
 
+:::info
+**Contributing and UI for Scalars**
+
+- **Open Source**: Please submit contributions as a pull request to the Powerhouse team.
+- **UI is Optional but Helpful**: A design or UI for your scalar isn't required, but it helps reviewers understand its purpose.
+- **Semantic Scalars**: Some scalars don't need a unique UI. For instance, `Title` and `Description` might both use a simple text input but serve a semantic role by adding specific meaning and validation to the schema.
+:::
+
 ### Tips
 
 - Always follow the naming convention: use PascalCase for scalar names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "2.5.0-dev.25",
+  "version": "2.5.0-dev.26",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/sidebars.ts

@@ -122,7 +122,6 @@ const sidebars = {
         },
         'academy/ComponentLibrary/CreateCustomScalars',
         'academy/ComponentLibrary/IntegrateIntoAReactComponent',
-        'academy/ComponentLibrary/ScalarVsUIComponents',
       ],
     },
 
@@ -134,7 +133,6 @@ const sidebars = {
     },
     { type: 'doc', id: 'academy/Cookbook', label: 'Cookbook' },
     { type: 'doc', id: 'academy/Glossary', label: 'Glossary' },
-    { type: 'doc', id: 'academy/AIResources', label: 'AI Resources' },
     // ...add more as needed
   ],
 };

package/docs/academy/06-ComponentLibrary/04-ScalarVsUIComponents.md

@@ -1,28 +0,0 @@
-import { Tabs, TabItem } from '@theme/Tabs';
-
-# Scalar vs. UI component
-
-Scalars are here to help you define custom fields in your document model schema and speed up the development process.
-There are two applications of scalar components in the document model workflow:
-
-1. At the **schema definition** level where you build your schema and write your GraphQL state schema.
-2. At the **frontend / react** level where you import it and place it in your UI to represent the scalar field
-
-## Overview
-The Document Engineering library provides two main categories of components.
-
-https://github.com/powerhouse-inc/document-engineering
-
-### Scalar Components
-
-These are specialized form components, each corresponding to a GraphQL scalar type (e.g., String, Number, Boolean, Currency, PHID). They are built on top of react-hook-form, offering out-of-the-box validation but must be wrapped with a Form component in order to work properly.
-
-Location: @powerhousedao/document-engineering/scalars
-
-**Key Feature**: Must be used within a Form component provided by this library.
-
-### General-Purpose UI Components
-
-This category includes a broader range of UI elements such as simplified versions of the Scalar components (which don't require a Form wrapper but lack built-in validation), as well as other versatile components like Dropdown, Tooltip, Sidebar, ObjectSetTable and more. These are designed for crafting diverse and complex user interfaces.
-
-Location: @powerhousedao/document-engineering/ui