@powerhousedao/academy 0.1.0-dev.3 → 0.1.0-dev.4

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

@@ -0,0 +1,277 @@
+# Implement Document Model Tests
+
+## 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**.
+
+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.
+
+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.
+
+## The Importance of Testing Document Model Reducers
+
+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:
+
+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.
+
+## Setting Up the Test Environment
+
+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.
+
+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.
+
+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);
+    });
+
+    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';
+
+    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);
+    });
+
+    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 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 update both text and checked status', () => {
+      const updateInput = { id: initialItemId, text: 'New Text Again', 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?.text).toBe('New Text Again');
+      expect(item?.checked).toBe(true);
+    });
+
+    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:
+
+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.
+
+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);`
+
+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');`
+
+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.
+
+## 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.
+*   **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.
+*   **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
+
+Implementing comprehensive tests for your document model reducers is an investment that pays dividends in the long run. It leads to:
+
+*   **Higher Quality Models**: More reliable and robust document models with fewer bugs.
+*   **Increased Confidence**: Ability to make changes and refactor code without fear of breaking existing functionality.
+*   **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.

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

@@ -0,0 +1 @@
+# Example: ToDoList Repo

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/_category_.json

@@ -0,0 +1,7 @@
+{
+    "label": "Document Model Creation",
+    "link": {
+      "type": "generated-index",
+      "description": "This tutorial will guide you through the process of creating an advanced to-do list document model in Powerhouse, while getting you familiar with the Powerhouse document model framework."
+    }
+  }

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/03-BuildingUserExperiences/02-ConfiguringDrives.md

@@ -5,7 +5,7 @@ A drive in Powerhouse is a container or a wrapper for documents and data. It's a
 ## Prerequisites
 
 Before configuring a drive, ensure you have:
-- Powerhouse [CLI installed](/docs/academy/AdvancedTutorial/Create/BuilderTools)
+- Powerhouse [CLI installed](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
 - Access to a Powerhouse instance
 - Appropriate permissions to create and manage drives
 
@@ -38,7 +38,7 @@ A drive exists by making use of a reactor and the storagelayer that specific rea
 
 These customized editors are called Drive explorers or Drive Apps. They provide custom views, organization tools, and interactive features tailored to specific use cases. For example, a Drive Explorer might present data as a Kanban board, provide aggregated insights, or offer specialized widgets for data processing. 
 
-To learn more about building and customizing Drive Explorers, check out our [Building a Drive Explorer](/docs/academy/AdvancedTutorial/BuildingUserExperiences/BuildingADriveExplorer) guide.
+To learn more about building and customizing Drive Explorers, check out our [Building a Drive Explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) guide.
 
 
 ## Creating a New Drive

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/03-BuildingUserExperiences/03-BuildingADriveExplorer.md

@@ -69,7 +69,7 @@ The application allows users to create and manage todo lists with a visual progr
    - Start by running Connect locally with `ph connect`
 
 :::warning
-Since you've likely already run through the [document modeling process](/docs/academy/GetStarted/ToDoList/DefineToDoListDocumentModel) of a simplified todo list, we'll offer you a **slightly more advanced** todo list below! 
+Since you've likely already run through the [document modeling process](/academy/GetStarted/DefineToDoListDocumentModel) of a simplified todo list, we'll offer you a **slightly more advanced** todo list below! 
 :::
 
      - Download [todo.phdm.zip](https://github.com/powerhouse-inc/todo-drive-explorer/blob/ee63786fa8ceed71de63cd9c52f1795ad11ac403/todo.phdm.zip) from our GitHub repo. 

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/07-DocumentTools/00-DocumentToolbar.md

@@ -0,0 +1,20 @@
+# Document Toolbar
+
+The Document Toolbar is a central component in Powerhouse Connect, appearing at the top of every document view. It provides quick access to a variety of tools and functions designed to streamline your workflow and enhance document management.
+
+## Overview
+
+The toolbar is designed to be intuitive and context-aware, offering relevant options based on the document type and your current task. Its capabilities range from basic actions to more advanced document control features.
+
+Key functionalities often include:
+*   **Switchboard API Access:** Access the Switchboard API via its logo in the toolbar. This opens the Apollo Studio Sandbox, pre-populating the DocumentID for your current document model. This feature is unavailable for locally stored documents.
+*   **Navigation and Versioning:** Tools for managing [document versions](/academy/MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory), such as undo/redo, and accessing the [revision history timeline](/academy/MasteryTrack/BuildingUserExperiences/DocumentTools/RevisionHistoryTimeline).
+*   **Document Actions:** Buttons for common operations like exporting or deleting documents.
+*   **Information Display:** Shows the document title and may include indicators for status (e.g., connectivity, errors) or active modes.
+*   **Search and Filtering:** Integrated search capabilities to find assets or attachments within the document context.
+*   **View Customization:** Options to switch between different views or display modes.
+*   **Contextual Tools:** Depending on the document, you might find toggles, dropdowns for specific actions (e.g., "Sync Schema", "Fixed Income Purchase"), or buttons for settings and configurations.
+
+The specific set of tools available on the toolbar can be configured and may evolve as new features are introduced. This section will detail the various components and options you may encounter.
+
+*(Detailed sections on each toolbar feature, such as "Export Button", "Title Display", "Search Functionality", "Toggle Switches", "Icon Buttons", etc., will follow here.)*

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/03-BuildingUserExperiences/07-DocumentTools/01-OperationHistory.md

@@ -49,7 +49,7 @@ Hovering over a revision reveals its event ID and state hash, providing traceabi
 
 ### Signature Verification
 Clicking the signature badge shows signature details, including signer address, hash, and verification status. This ensures every operation is cryptographically auditable.
-Read more about how we are using [Renown](/docs/academy/AdvancedTutorial/BuildingUserExperiences/Authorization/RenownAuthenticationFlow) for authentication & verification of signer data. 
+Read more about how we are using [Renown](/academy/MasteryTrack/BuildingUserExperiences/Authorization/RenownAuthenticationFlow) for authentication & verification of signer data. 
 
 ![Signature Details Popup](./images/signature-details-popup.png)
 

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/04-WorkWithData/01-ReadingAndWritingThroughTheAPI.mdx

@@ -17,8 +17,8 @@ Your API requests are authenticated using API keys or tokens. Any request that d
 
 ### Starting the reactor locally
 
-In this documentation we'll show how to use a **GraphQL** query to query a document model. We'll **continue on the ToDoList example** from our [introduction tutorial](/docs/academy/GetStarted/ToDoList/DefineToDoListDocumentModel) , but the process can be applied to any other document model.
-To make our document model available in the Apollo Studio Sandbox we'll need to store it on a remote [Reactor](/docs/academy/Architecture/WorkingWithTheReactor).
+In this documentation we'll show how to use a **GraphQL** query to query a document model. We'll **continue on the ToDoList example** from our [introduction tutorial](/academy/GetStarted/DefineToDoListDocumentModel) , but the process can be applied to any other document model.
+To make our document model available in the Apollo Studio Sandbox we'll need to store it on a remote [Reactor](/academy/Architecture/WorkingWithTheReactor).
 
 :::info
 **Powerhouse Reactors** are the nodes in the network that store documents, resolve conflicts and rerun operations to verify document event histories. 

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/04-WorkWithData/02-GraphQLAtPowerhouse.md

@@ -2,7 +2,7 @@
 
 In this section, we will cover **the core concepts of GraphQL with examples applied to the Powerhouse ecosystem**. More specifically, GraphQL is used as:
 - The **schema definition language (SDL)** for defining our document models and thereby self-documenting the API to the data model. It allows developers to define the structure and relationships of data in a strongly-typed format.
-- As the **query language in subgraphs**, which allow different services to expose and query structured data dynamically. Jump to the section [GraphQL and Subgraphs](/docs/academy/AdvancedTutorial/WorkWithData/WorkingWithSubgraphs/GraphQLAndSubgraphs) to learn more about this.
+- As the **query language in subgraphs**, which allow different services to expose and query structured data dynamically. Jump to the section [GraphQL and Subgraphs](/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs/GraphQLAndSubgraphs) to learn more about this.
 
 
 ### Why GraphQL?

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/04-WorkWithData/06-Analytics Engine/graphql/index.md

@@ -31,7 +31,7 @@ query {
 ```
 
 In this example, query is the operation type, user is the field on the root type, and name, email, and friends are fields on the user type. The id: `"1"` is a parameter passed to the query, specifying which user to fetch.
-You can find more examples of GraphQL core concept in the section [GraphQL at Powerhouse](/docs/academy/AdvancedTutorial/WorkWithData/GraphQLAtPowerhouse).
+You can find more examples of GraphQL core concept in the section [GraphQL at Powerhouse](/academy/MasteryTrack/WorkWithData/GraphQLAtPowerhouse).
 
 ## Analytics Query Structure
 

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/05-Launch/02-IntroductionToPackages.md

@@ -4,7 +4,7 @@ Packages of document models are a core structuring mechanism in the Powerhouse f
 
 By packaging document models together, developers can create well-organized, interoperable sets of data structures that capture the specific needs of various operational processes. Whether used for financial operations, governance, or contributor management, these packages streamline development and integration within Powerhouse's decentralized framework.
 
-### Key Features
+### Key Features of Packages
 
 - **Modular Structure** – Packages encapsulate related document models, making it easier to manage and deploy them as a cohesive unit.
 - **Standardized Definitions** – Each document model within a package follows Powerhouse's structured schema approach, ensuring consistency in data representation.
@@ -12,7 +12,7 @@ By packaging document models together, developers can create well-organized, int
 - **Dependency Management** – Developers can define dependencies between document models, ensuring proper relationships and data flows between interconnected components.
 - **Automated Schema Evolution** – Versioning mechanisms allow document models within a package to evolve over time without breaking existing functionality.
 
-### Example Use Cases
+### Example Use Cases of Packages
 
 - **Finance Package** – A set of document models handling invoices, payments, budgets, and financial reporting. link
 - **Contributor Billing Package** – Defines document models for tracking work, invoicing, and facilitating payments (in both fiat and crypto) for contributors in decentralized organizations. link

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/05-Launch/03-RunOnACloudServer.md

@@ -1,4 +1,4 @@
-# Run it on a EC2 instance
+# Run on a EC2 instance (WIP)
 
 ## Tutorial Workflow
 
@@ -8,7 +8,7 @@ To help you navigate the steps involved, the diagram below illustrates the overa
 
 ![tutorial schema](images/tutorialschema.png)
 
-Understanding this process is key because, within the Powerhouse ecosystem, users typically start by installing pre-built packages onto their Connect or Switchboard instances. These packages are often sourced from a central repository, similar to an app store. In the previous tutorial, we have [created and published our package](/docs/academy/AdvancedTutorial/Launch/PublishYourProject) on the Node Package Manager (NPM) registry as our "app store", and now you'll learn how to deploy your own package to a cloud environment.
+Understanding this process is key because, within the Powerhouse ecosystem, users typically start by installing pre-built packages onto their Connect or Switchboard instances. These packages are often sourced from a central repository, similar to an app store. Now that we have [created and published our package](/academy/MasteryTrack/Launch/PublishYourProject) on the Node Package Manager (NPM) registry as our "app store", and now you'll learn how to deploy your own package to a cloud environment.
 
 ## 1. Setting up your cloud environment
 ### 1.1. Launching your server instance (AWS \- EC2 \- Ubuntu)
@@ -79,7 +79,7 @@ The script contains the following commands and will help you set up a series of
 - **pnpm**: Fast, disk-space-efficient package manager
 
 :::info
-ph-cmd is a tool that helps you manage your Powerhouse projects. It's a command-line interface package that you can install globally on your server and personal machine. It gives you access to a series of powerful commands to create or manage your projects, start or stop your services, install your project on a server instance, etc. Visit this page to learn more about the [Powerhouse builder tooling](/docs/academy/AdvancedTutorial/Create/BuilderTools)
+ph-cmd is a tool that helps you manage your Powerhouse projects. It's a command-line interface package that you can install globally on your server and personal machine. It gives you access to a series of powerful commands to create or manage your projects, start or stop your services, install your project on a server instance, etc. Visit this page to learn more about the [Powerhouse builder tooling](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
 
 <details>
 <summary> How to make use of different branches? </summary>

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/05-Launch/03-SetupEnvironment.md

@@ -1,4 +1,4 @@
-# Powerhouse Setup Guide
+# Powerhouse Setup Guide (WIP)
 
 ## Introduction
 Powerhouse is a powerful platform that helps you manage and deploy your applications efficiently. This guide will walk you through the process of setting up both the Powerhouse CLI and configuring your server machine to run Powerhouse services. Whether you're setting up a development environment or preparing for production deployment, this guide provides all the necessary steps and considerations.

package/docs/academy/{02-AdvancedTutorial → 02-MasteryTrack}/_category_.json

@@ -1,5 +1,5 @@
 {
-    "label": "Advanced Tutorial",
+    "label": "Mastery Track",
     "link": {
       "type": "generated-index",
       "description": "A set of tutorials that support the creation of more complex Powerhouse documents, drive apps and packages."