@powerhousedao/academy 3.2.0-dev.2 → 3.2.0-dev.3

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

@@ -1,8 +1,8 @@
-# Specify the State Schema
+# Specify the state schema
 
 The state schema is the backbone of your document model. It defines the structure, data types, and relationships of the information your document will hold. In Powerhouse, we use the GraphQL Schema Definition Language (SDL) to define this schema. A well-defined state schema is crucial for ensuring data integrity, consistency, and for enabling powerful querying and manipulation capabilities.
 
-## Core Concepts
+## Core concepts
 
 ### Types
 At the heart of GraphQL SDL are **types**. Types define the shape of your data. You can define custom object types that represent the entities in your document. For example, in a `ToDoList` document, you might have a `ToDoListState` type and a `ToDoItem` type.
@@ -23,12 +23,13 @@ GraphQL has a set of built-in **scalar types**:
 
 In addition to these standard types, the Powerhouse Document-Engineering system introduces custom scalars that are linked to reusable front-end components. These scalars are tailored for the web3 ecosystem and will be explored in the Component Library section of the documentation.
 
-### Lists and Non-Null
+### Lists and non-null
+
 You can modify types using lists and non-null indicators:
 *   **Lists**: To indicate that a field will return a list of a certain type, you wrap the type in square brackets, e.g., `[ToDoItem!]!`. This means the field `items` in `ToDoListState` will be a list of `ToDoItem` objects.
 *   **Non-Null**: To indicate that a field cannot be null, you add an exclamation mark `!` after the type name, e.g., `String!`. This means that the `text` field of a `ToDoItem` must always have a value. The outer `!` in `[ToDoItem!]!` means the list itself cannot be null (it must be at least an empty list), and the inner `!` on `ToDoItem!` means that every item within that list must also be non-null.
 
-## Example: ToDoList State Schema
+## 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.
@@ -71,7 +72,7 @@ type ToDoListStats {
     *   `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
+## 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.
 2.  **Clarity and Explicitness**: Name your types and fields clearly and descriptively. This makes the schema easier to understand and maintain.
@@ -85,12 +86,12 @@ type ToDoListStats {
 
 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.
 
-## Practical Implementation: Defining the State Schema in Connect
+## 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> 
+<summary>Tutorial: The state schema specification</summary> 
 
 ### Prerequisites
 
@@ -105,7 +106,7 @@ Now that you understand the concepts behind the state schema, let's put it into
 
 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`.
+    -   **Document Type**: In the 'Document Type' field, enter a unique identifier for this document type: `powerhouse/todolist`.
 
 3.  **Specify the State Schema**:
     -   In the code editor provided, you'll see a template for a GraphQL schema.
@@ -115,6 +116,7 @@ Now that you understand the concepts behind the state schema, let's put it into
     # The state of our ToDoList
     type ToDoListState {
       items: [ToDoItem!]!
+      stats: ToDoListStats!
     }
 
     # A single to-do item
@@ -141,5 +143,5 @@ By completing these steps, you have successfully specified the data structure fo
 
 </details>
 
-For a complete, working example, you can always refer to the [Example ToDoList Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.
+For a complete, working example, you can always have a look at the [Example ToDoList Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.
 

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

@@ -1,12 +1,12 @@
-# Specify Document Operations
+# Specify document operations
 
 In the previous section, we defined the state schema for our document model. Now, we turn our attention to a critical aspect of document model creation: **specifying document operations**. These operations are the heart of your document's behavior, dictating how its state can be modified.
 
-## What are Document Operations?
+## What are document operations?
 
 In Powerhouse, document models adhere to event sourcing principles. This means that every change to a document's state is the result of a sequence of operations (or events). Instead of directly mutating the state, you define specific, named operations that describe the intended change.
 
-For example, in our `ToDoList` document model, operations might include:
+For example, in our `To-do List` document model, operations might include:
 
 *   `ADD_TODO_ITEM`: To add a new task.
 *   `UPDATE_TODO_ITEM`: To modify an existing task (e.g., change its text or mark it as completed).
@@ -14,9 +14,9 @@ For example, in our `ToDoList` document model, operations might include:
 
 Each operation acts as a command that, when applied, transitions the document from one state to the next. The complete history of these operations defines the document's journey to its current state.
 
-## Connecting Operations to the Schema
+## Connecting operations to the schema
 
-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:
+In the "Define To-do List 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
 # Defines a GraphQL input type for adding a new to-do item
@@ -46,7 +46,7 @@ These `input` types are not just abstract definitions; they are the **specificat
 
 The Powerhouse Connect application uses these GraphQL input types when you define operations within a module (e.g., the `to_do_list` module with operations `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`).
 
-## Designing Effective Document Operations
+## Designing effective document operations
 
 Careful design of your document operations is crucial for a robust and maintainable document model. Here are some key considerations:
 
@@ -57,7 +57,7 @@ Operations should be granular enough to represent distinct user intentions or lo
 *   **Too fine:** While possible, having separate operations like `SET_TODO_ITEM_TEXT` and `SET_TODO_ITEM_CHECKED_STATUS` might be overly verbose if these are often updated together. `UPDATE_TODO_ITEM` with optional fields offers a good balance.
 *   **Just right:** The `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, and `DELETE_TODO_ITEM` operations for our `ToDoList` are good examples. They represent clear, atomic changes.
 
-### 2. Naming Conventions
+### 2. Naming conventions
 Clear and consistent naming makes your operations understandable. A common convention is `VERB_NOUN` or `VERB_NOUN_SUBJECT`.
 
 *   Examples: `ADD_ITEM`, `UPDATE_USER_PROFILE`, `ASSIGN_TASK_TO_USER`.
@@ -65,7 +65,7 @@ Clear and consistent naming makes your operations understandable. A common conve
 
 The name you provide in the Connect UI (e.g., `ADD_TODO_ITEM`) directly corresponds to the operation type that will be recorded and that your reducers will handle.
 
-### 3. Input Types (Payloads)
+### 3. Input types (payloads)
 The input type for an operation (its payload) should contain all the necessary information to perform that operation, and nothing more.
 
 *   **Completeness:** If an operation needs a user ID to authorize a change, include it in the input.
@@ -74,15 +74,15 @@ The input type for an operation (its payload) should contain all the necessary i
 
 The GraphQL `input` types we defined earlier (`AddTodoItemInput`, `UpdateTodoItemInput`, `DeleteTodoItemInput`) serve precisely this purpose. They ensure that whoever triggers an operation provides the correct data in the correct format.
 
-### 4. Immutability and Pure Functions
+### 4. Immutability and pure functions
 While not specified in the operation definition itself, remember that the *implementation* of these operations (the reducers) should treat state as immutable and behave as pure functions. The operation specification (input type) provides the data for these pure functions.
 
-## Role in Event Sourcing and CQRS
+## Role in event sourcing and CQRS
 
 *   **Events:** Each successfully executed operation is recorded as an event in the document's history. This history provides an audit trail and allows for replaying events to reconstruct state, which is invaluable for debugging and understanding how a document evolved.
 *   **Commands:** Document operations are essentially "commands" in a Command Query Responsibility Segregation (CQRS) pattern. They represent an intent to change the state. The processing of this command (by the reducer) leads to one or more events being stored and the state being updated.
 
-## From Specification to Implementation
+## From specification to implementation
 
 Specifying your document operations is the bridge between defining your data structure (the state schema) and implementing the logic that changes that data (the reducers).
 
@@ -110,14 +110,14 @@ export const reducer: ToDoListToDoListOperations = {
 };
 ```
 
-## Practical Implementation: Defining Operations in Connect
+## 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.
+Now that you understand the theory, let's walk through the practical steps of defining these operations for our `To-do List` document model within the Powerhouse Connect application.
 
 <details>
-<summary>Tutorial: Specifying ToDoList Operations</summary>
+<summary>Tutorial: Specifying To-do List 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:
+Assuming you have already defined the state schema for the `To-do List` 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.

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

@@ -1,4 +1,4 @@
-# Use the Document Model Generator
+# Use the document model generator
 
 In the Powerhouse Document Model development workflow, after specifying your document model's state schema and operations within the Connect application and exporting it as a `.phdm.zip` file, the next crucial step is to translate this specification into a tangible codebase. This is where the Powerhouse Document Model Generator comes into play.
 
@@ -13,7 +13,7 @@ Before you can use the Document Model Generator, ensure you have the following:
 1.  **Powerhouse CLI (`ph-cmd`) Installed:** The generator is part of the Powerhouse CLI. If you haven't installed it, refer to the [Builder Tools documentation](/academy/MasteryTrack/BuilderEnvironment/BuilderTools#installing-the-powerhouse-cli).
 2.  **Document Model Specification File (`.phdm.zip`):** You must have already defined your document model in Connect and exported it. This file (e.g., `YourModelName.phdm.zip`) contains the GraphQL schema for your document's state and operations. This process is typically covered in a preceding step, such as "Define [YourModelName] Document Model."
 
-## The Command
+## The command
 
 The core command to invoke the Document Model Generator is:
 
@@ -29,7 +29,7 @@ ph generate Invoice.phdm.zip
 
 When executed, this command reads and parses the specification file and generates a set of files and directories within your Powerhouse project.
 
-## What Happens Under the Hood? A Deep Dive into the Generated Artifacts
+## What happens under the hood? A deep dive into the generated artifacts
 
 Running `ph generate` triggers a series of actions that lay the groundwork for your document model's implementation. Let's explore the typical output structure and the significance of each generated component.
 
@@ -79,7 +79,7 @@ For example, using `Invoice.phdm.zip` would result in a directory structure unde
         *   **Purpose:** You can create this directory for any custom utility functions specific to your document model's implementation that don't fit directly into the reducers.
         *   **Significance:** Helps in organizing shared logic or complex computations that might be used across multiple reducers or other parts of your model's ecosystem.
 
-## Benefits of Using the Document Model Generator
+## Benefits of using the document model generator
 
 Leveraging the `ph generate` command offers numerous advantages:
 
@@ -90,14 +90,14 @@ 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.
 
-## Practical Implementation: Generating the `ToDoList` Model
+## Practical implementation: Generating the `To-do List` model
 
-Now that you understand what the Document Model Generator does, let's walk through the practical steps of using it with our `ToDoList` example.
+Now that you understand what the Document Model Generator does, let's walk through the practical steps of using it with our `To-do List` example.
 
 <details>
-<summary>Tutorial: Generating the ToDoList Document Model</summary>
+<summary>Tutorial: Generating the `To-do List` 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.
+This tutorial assumes you have completed the previous steps in this Mastery Track, where you defined the state schema and operations for the `To-do List` model in Connect and exported it.
 
 ### Prerequisites
 
@@ -127,7 +127,7 @@ With these files generated, you have successfully scaffolded your document model
 
 </details>
 
-## Next Steps
+## Next steps
 
 Once the Document Model Generator has successfully scaffolded your project, the immediate next step is to implement the logic for each operation within the generated reducer files (e.g., `document-models/YourModelName/src/reducers/your-model-name.ts`). This involves taking the current state and the action input, and returning the new state of the document.
 

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

@@ -1,12 +1,12 @@
-# Implement Document Reducers
+# Implement document reducers
 
-## The Heart of Document Logic
+## The heart of document logic
 
 In our journey through Powerhouse Document Model creation, we've defined the "what" – the structure of our data ([State Schema](02-SpecifyTheStateSchema.md)) and the ways it can be changed ([Document Operations](03-SpecifyDocumentOperations.md)). We've also seen how the [Document Model Generator](04-UseTheDocumentModelGenerator.md) translates these specifications into a coded scaffold. Now, we arrive at the "how": implementing **Document Reducers**.
 
 Reducers are the core logic units of your document model. They are the functions that take the current state of your document and an operation (an "action"), and then determine the *new* state of the document. They are the embodiment of your business rules and the engine that drives state transitions in a predictable, auditable, and immutable way.
 
-## Recap: The Journey to Reducer Implementation
+## Recap: The journey to reducer implementation
 
 Before diving into the specifics of writing reducers, let's recall the preceding steps:
 
@@ -16,7 +16,7 @@ Before diving into the specifics of writing reducers, let's recall the preceding
 
 This generated reducer file is our starting point. It will contain function stubs or an object structure expecting your reducer implementations, all typed according to your schema.
 
-## What is a Reducer? The Core Principles
+## What is a reducer? The core principles
 
 In the context of Powerhouse and inspired by patterns like Redux, a reducer is a **pure function** with the following signature (conceptually):
 
@@ -30,7 +30,7 @@ Let's break down its components and principles:
     *   An `input` property (or similar, like `payload`): An object containing the data necessary for the operation, matching the GraphQL `input` type you defined (e.g., `{ id: '1', text: 'Buy groceries' }` for `AddTodoItemInput`).
 *   **`newState`**: The reducer must return a *new* state object representing the state after the operation has been applied. If the operation does not result in a state change, the reducer should return the `currentState` object itself.
 
-### Key Principles Guiding Reducer Implementation:
+### Key principles guiding reducer implementation:
 
 1.  **Purity**:
     *   **Deterministic**: Given the same `currentState` and `action`, a reducer must *always* produce the same `newState`.
@@ -43,7 +43,7 @@ Let's break down its components and principles:
 
 3.  **Single Source of Truth**: The document state managed by reducers is the single source of truth for that document instance. All UI rendering and data queries are derived from this state.
 
-4.  **Delegation to Specific Operation Handlers**:
+4.  **Delegation to specific operation handlers**:
     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
@@ -73,7 +73,7 @@ Let's break down its components and principles:
 
     The `dispatch` parameter is an advanced feature allowing a reducer to trigger subsequent operations. While powerful for complex workflows, it's often not needed for basic operations and can be ignored if unused.
 
-## Implementing Reducer Logic: A Practical Guide
+## Implementing reducer logic: A practical guide
 
 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.
 
@@ -102,7 +102,7 @@ And our action creators (from `../../gen/creators` or `../../gen/operations.js`)
 *   `actions.updateTodoItem({ id: 'item-id', text: 'Updated Task Text', checked: true })`
 *   `actions.deleteTodoItem({ id: 'item-id' })`
 
-### 1. Adding an Item (e.g., `addTodoItemOperation`)
+### 1. Adding an item (e.g., `addTodoItemOperation`)
 
 To add a new item to the `items` array immutably:
 
@@ -125,7 +125,7 @@ addTodoItemOperation(state: ToDoListState, action: /* AddTodoItemActionType */ a
 *   We use the spread operator (`...state`) to copy top-level properties from the old state into the new state object.
 *   For the `items` array, we create a *new* array by spreading the existing `state.items` and then appending the `newItem`.
 
-### 2. Updating an Item (e.g., `updateTodoItemOperation`)
+### 2. Updating an item (e.g., `updateTodoItemOperation`)
 
 To update an existing item in the `items` array immutably:
 
@@ -171,7 +171,7 @@ if (!itemToUpdate) {
 // ... proceed with map
 ```
 
-### 3. Deleting an Item (e.g., `deleteTodoItemOperation`)
+### 3. Deleting an item (e.g., `deleteTodoItemOperation`)
 
 To remove an item from the `items` array immutably:
 
@@ -189,7 +189,7 @@ deleteTodoItemOperation(state: ToDoListState, action: /* DeleteTodoItemActionTyp
 **Explanation**:
 *   We use the `filter` array method, which returns a *new* array containing only the elements for which the callback function returns `true`.
 
-## Leveraging Generated Types
+## Leveraging generated types
 
 As highlighted in [Using the Document Model Generator](04-UseTheDocumentModelGenerator.md), `ph generate` produces TypeScript types for your state (e.g., `ToDoListState`, `ToDoItem`) and the inputs for your operations (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`).
 
@@ -232,16 +232,16 @@ Using these types provides:
 *   **Autocompletion and IntelliSense**: Improved developer experience in your IDE.
 *   **Clearer code**: Types serve as documentation for the expected data structures.
 
-## Practical Implementation: Writing the `ToDoList` 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>
+<summary>Tutorial: Implementing the ToDoList reducers</summary>
 
 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.
 
-### Implement the Operation Reducers
+### 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.
 
@@ -332,7 +332,7 @@ export const reducer: ToDoListToDoListOperations = {
 
 </details>
 
-## Reducers and the Event Sourcing Model
+## Reducers and the event sourcing model
 
 Every time a reducer processes an operation and returns a new state, Powerhouse records the original operation (the "event") in an append-only log associated with the document instance. The current state of the document is effectively a "fold" or "reduction" of all past events, applied sequentially by the reducers.
 

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

@@ -1,21 +1,21 @@
-# Implement Document Model Tests
+# Implement document model tests
 
-## Ensuring Robustness and Reliability
+## Ensuring robustness and reliability
 
 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 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 provides a practical, hands-on tutorial for testing the `ToDoList` document model reducers you have just built.
+This document provides a practical, hands-on tutorial for testing the `To-do List` document model reducers you have just built.
 
-## Practical Implementation: Writing and Running the ToDoList Tests
+## Practical implementation: Writing and running the To-do List tests
 
-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`.
+This tutorial assumes you have implemented the `To-do List` 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`.
 
 <details>
-<summary>Tutorial: Implementing and Running the `ToDoList` Reducer Tests</summary>
+<summary>Tutorial: Implementing and running the `To-do List` reducer tests</summary>
 
-### 1. Implement the Reducer Tests
+### 1. Implement the reducer tests
 
 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.
 
@@ -96,7 +96,7 @@ describe('Todolist Operations', () => {
 });
 ```
 
-### 2. Run the Tests
+### 2. Run the tests
 
 Now, run the tests from your project's root directory to verify your implementation.
 
@@ -104,11 +104,11 @@ Now, run the tests from your project's root directory to verify your implementat
 pnpm run test
 ```
 
-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.
+If all tests pass, you have successfully verified the core logic of your `To-do List` document model. This ensures that the reducers you wrote behave exactly as expected.
 
 </details>
 
-## Best Practices for Document Model Tests
+## Best practices for document model tests
 
 While the tutorial provides a concrete example, keep these general best practices in mind when writing your tests:
 
@@ -122,7 +122,7 @@ While the tutorial provides a concrete example, keep these general best practice
 *   **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
+## Conclusion: The payoff of diligent testing
 
 Implementing comprehensive tests for your document model reducers is an investment that pays dividends in the long run. It leads to:
 
@@ -133,7 +133,7 @@ Implementing comprehensive tests for your document model reducers is an investme
 
 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.
 
-## Up Next
-In the next chapter of the Mastery Track - Building User Experiences you will learn how to implement an editor for your document model so you can see a simple user interface for the **ToDoList** document model in action.
+## Up next
+In the next chapter of the Mastery Track - Building User Experiences you will learn how to implement an [editor](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors) for your document model so you can see a simple user interface for the **To-do List** document model in action. 
 
-For a complete, working example, you can always refer to the [Example ToDoList Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.
+For a complete, working example, you can always have a look at the [Example To-do List Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/07-ExampleToDoListRepository.md

@@ -1,4 +1,4 @@
-# Example: ToDo Demo Package
+# Example: Todo demo package
 
 :::info
 
@@ -9,12 +9,12 @@ https://github.com/powerhouse-inc/todo-demo-package
 
 There are several ways to explore this package:
 
-### Option 1: Rebuild the ToDo Demo Package
+### Option 1: Rebuild the todo demo package
 
 The ToDo Demo package and repository are your main reference points during the Mastery Track.  
 Follow the steps in the "Mastery Track – Document Model Creation" chapters to build along with the examples.
 
-### Option 2: Clone and Run the Code Locally
+### Option 2: Clone and run the code locally
 
 The package includes:  
 - The Document Model  
@@ -29,7 +29,7 @@ You can clone the repository and run Connect Studio to see all the code in actio
 ph connect
 ```
 
-### Option 3: Install the ToDo Demo Package in a (Local) Host App
+### Option 3: Install the todo demo package in a (local) host app
 
 Alternatively, you can install this package in a Powerhouse project or in your deployed host apps:
 

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/01-BuildingDocumentEditors.md

@@ -1,10 +1,10 @@
-# Build Document Editors
+# Build document editors
 
-## Build with React on Powerhouse
+## Build with react on powerhouse
 
 At Powerhouse, frontend development for document editors follows a simple and familiar flow, leveraging the power and flexibility of React.
 
-### Development Environment
+### Development environment
 
 Connect Studio is your primary tool for development.   
 When you run `ph connect`, it provides a dynamic, local environment where you can define and preview your document models and their editors live. This replaces the need for tools like Storybook for editor development, though Storybook remains invaluable for exploring the [Powerhouse Component Library](#powerhouse-component-library).
@@ -19,18 +19,18 @@ Powerhouse aims to keep your developer experience clean, familiar, and focused:
 - Use styling approaches you're comfortable with.
 - Trust Connect Studio to handle the setup and build processes for you.
 
-### Generating Your Editor Template
+### Generating your editor template
 
 To kickstart your editor development, Powerhouse provides a command to generate a basic editor template. This command reads your document model specifications and creates the initial `editor.tsx` file.
 If you want a refresher on how to define your document model specification please read the chapter on [specifying the State Schema](/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
 
-For example, to generate an editor for a `ToDoList` document model with a document type `powerhouse/todolist`:
+For example, to generate an editor for a `To-do List` document model with a document type `powerhouse/todolist`:
 ```bash
 ph generate --editor ToDoList --document-types powerhouse/todolist
 ```
 This will create the template in the `editors/to-do-list/editor.tsx` folder.
 
-### Styling Your Editor
+### Styling your editor
 
 You have several options for styling your editor components:
 
@@ -74,7 +74,7 @@ You have several options for styling your editor components:
 
 Choose the method or combination of methods that best suits your project needs and team preferences. Connect Studio (`ph connect`) will allow you to see your styles applied in real-time.
 
-### State Management in Editors
+### State management in editors
 
 When you build an editor in Powerhouse, your main editor component receives `EditorProps`. These props are crucial for interacting with the document:
 
@@ -112,11 +112,11 @@ Your document model's generated code (e.g., in `document-models/your-model/index
 ```
 The actual state modification logic resides in your document model's reducers, ensuring that all changes are consistent and follow the defined operations.
 
-## Powerhouse Component Library
+## Powerhouse component library
 
 Powerhouse provides a rich set of reusable UI components through the **`@powerhousedao/document-engineering/scalars`** package. These components are designed for consistency, efficiency, and seamless integration with the Powerhouse ecosystem, with many based on GraphQL scalar types.
 
-### Exploring Components
+### Exploring components
 You can explore available components, see usage examples, and understand their properties (props) using our Storybook instance:
 [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
 
@@ -126,7 +126,7 @@ Storybook allows you to:
 *   View code snippets for basic implementation.
 *   Consult the props table for detailed configuration options.
 
-### Using Components
+### Using components
 1.  **Import**: Add an import statement at the top of your editor file:
     ```typescript
     import { Checkbox, StringField, Form } from '@powerhousedao/document-engineering/scalars';
@@ -145,18 +145,18 @@ Storybook allows you to:
     ```
 
 <details>
-<summary>Tutorial: Implementing the `ToDoList` Editor</summary>
+<summary>Tutorial: Implementing the `To-do List` Editor</summary>
 
-## Build a ToDoList Editor
+## Build a To-do List editor
 
-In this final part of our tutorial we will continue with the interface or editor implementation of the **ToDoList** document model. This means you will create a simple user interface for the **ToDoList** document model which will be used inside the Connect app to create, update and delete your ToDoList items, but also dispaly the statistics we've implemented in our reducers. 
+In this final part of our tutorial we will continue with the interface or editor implementation of the **To-do List** document model. This means you will create a simple user interface for the **To-do List** document model which will be used inside the Connect app to create, update and delete your To-do List items, but also dispaly the statistics we've implemented in our reducers. 
 
 ## Generate the editor template
 
-Run the command below to generate the editor template for the **ToDoList** document model.   
-This command reads the **ToDoList** document model definition from the `document-models` folder and generates the editor template in the `editors/to-do-list` folder as `editor.tsx`.
+Run the command below to generate the editor template for the **To-do List** document model.   
+This command reads the **To-do List** document model definition from the `document-models` folder and generates the editor template in the `editors/to-do-list` folder as `editor.tsx`.
 
-Notice the `--editor` flag which specifies the **ToDoList** document model, and the `--document-types` flag defines the document type `powerhouse/todolist`.
+Notice the `--editor` flag which specifies the **To-do List** document model, and the `--document-types` flag defines the document type `powerhouse/todolist`.
 
 ```bash
 ph generate --editor ToDoList --document-types powerhouse/todolist
@@ -165,7 +165,7 @@ ph generate --editor ToDoList --document-types powerhouse/todolist
 Once complete, navigate to the `editors/to-do-list/editor.tsx` file and open it in your editor.
 
 
-### Editor Implementation Options
+### Editor implementation options
 
 When building your editor component within the Powerhouse ecosystem, you have several options for styling, allowing you to leverage your preferred methods:
 
@@ -177,13 +177,12 @@ Connect Studio provides a dynamic local environment (`ph connect`) to visualize
 
 ---
 
-## ToDoList Editor
+## To-do List editor
 
-:::tip
-### Implementing Components
+:::tip Implementing components
 The editor we are about to implement makes use of some components from **Powerhouse Document Engineering**. 
 When you add the editor code, you'll see it makes use of two components, the `Checkbox` and `InputField`.
-These are imported from the Powerhouse Document Engineering design system (`@powerhousedao/document-engineering/scalars`).   
+These are imported from the Powerhouse Document Engineering design system (`@powerhousedao/document-engineering/scalars`) which you should find under 'devdependencies' in your package.json file.   
 
 This system provides a library of reusable components to ensure consistency and speed up development.  
 You can explore available components, see usage examples, and understand their properties (props) using our Storybook instance. For a detailed guide on how to leverage the Document Engineering design system and Storybook, see [Using the Powerhouse Document Engineering](/academy/ComponentLibrary/DocumentEngineering) page.
@@ -262,7 +261,7 @@ export const InputField = (props: InputFieldProps) => {
 Below is the complete code for the To-Do List editor. It primarily uses Tailwind CSS for styling and imports the local `Checkbox` and `InputField` components you created in the previous step. These local components, in turn, utilize elements from the Powerhouse Document Engineering design system.
 
 <details>
-<summary>Complete ToDoList Editor Example (using Tailwind CSS)</summary>
+<summary>Complete To-do List Editor Example (using Tailwind CSS)</summary>
 
 ```typescript
 import { EditorProps } from 'document-model'; // Core type for editor components.
@@ -273,7 +272,7 @@ import {
     ToDoItem,            // Type for a single item in the list.
     actions,             // Object containing action creators for dispatching changes.
     ToDoListDocument     // The complete document structure including state and metadata.
-} from '../document-models/to-do-list/index.js'; // Path to your document model definition.
+} from '../../document-models/to-do-list/index.js'; // Path to your document model definition.
 import { useState } from 'react'; // React hook for managing component-local state.
 import { Checkbox } from './components/checkbox.js'; // Custom Checkbox component.
 import { InputField } from './components/inputfield.js'; // Custom InputField component.
@@ -486,23 +485,22 @@ export default function Editor(props: IProps) {
 ```
 </details>
 
-Now you can run the Connect app and see the **ToDoList** editor in action.
+Now you can run the Connect app and see the **To-do List** editor in action.
 
 ```bash
 ph connect
 ```
 
-In Connect, in the bottom right corner you'll find a new Document Model that you can create: **ToDoList**.    
-Click on it to create a new ToDoList document.
+In Connect, in the bottom right corner you'll find a new Document Model that you can create: **To-do List**. Click on it to create a new To-do List document.
 
-:::info
+:::tip Connect as your dynamic development environment
 The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Connect Studio. 
 :::
 
 </details>
 
 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. 
+If you managed to follow this tutorial until this point, you have successfully implemented the **To-do List** document model with its reducer operations and editor. 
 
-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!
+Now you can move on to creating a [custom drive explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) for your To-do List document.    
+Imagine you have many To-do Lists 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!