@powerhousedao/academy 3.2.0-dev.5 → 3.2.0-dev.7

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 3.2.0-dev.7 (2025-06-28)
+
+### 🚀 Features
+
+- starting to stub out a complete example of the analytics processor ([a84ed2dcf](https://github.com/powerhouse-inc/powerhouse/commit/a84ed2dcf))
+
+### ❤️ Thank You
+
+- Benjamin Jordan (@thegoldenmule)
+
+## 3.2.0-dev.6 (2025-06-27)
+
+### 🚀 Features
+
+- **connect:** use atom store and provider from state library ([28f646636](https://github.com/powerhouse-inc/powerhouse/commit/28f646636))
+- added drive analytics processor ([#1607](https://github.com/powerhouse-inc/powerhouse/pull/1607))
+
+### 🩹 Fixes
+
+- updated document-engineering ver ([3522179d6](https://github.com/powerhouse-inc/powerhouse/commit/3522179d6))
+- updated atoms with header changes ([2b557197a](https://github.com/powerhouse-inc/powerhouse/commit/2b557197a))
+
+### ❤️ Thank You
+
+- Benjamin Jordan (@thegoldenmule)
+- Guillermo Puente
+- Guillermo Puente Sandoval
+- ryanwolhuter
+
 ## 3.2.0-dev.5 (2025-06-26)
 
 ### 🚀 Features

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/02-ConfiguringDrives.md

@@ -1,6 +1,6 @@
 # Configure a drive
 
-A drive in Powerhouse is a container or a wrapper for documents and data. It's a place where you can organize and store your documents and share them with others. This guide will walk you through the process of configuring and managing drives in your Powerhouse environment.   
+A drive in Powerhouse is a container for documents and data. It's a place where you can organize and store your documents and share them with others. This guide walks you through configuring and managing drives in your Powerhouse environment.   
 
 :::info **Prerequisites**
 
@@ -14,64 +14,74 @@ Before configuring a drive, ensure you have:
 
 ### Local drives
 
-A local drive is a container for local documents and data, hosted on your local machine. Technically a drive is just another document model with a list of the documents inside the drive. When you run connect locally with `ph connect` a local drive is automatically added. You can also create a new local drive by clicking **'add drive'** in connect.
+A local drive is a container for local documents and data, hosted on your local machine. Technically, a drive is itself a document that contains a list of the documents inside it. When you run Connect locally with `ph connect`, a local drive is automatically added. You can also create a new local drive by clicking **'Create New Drive'** in Connect.
 
 ### Remote drives vs. reactors 
 
-Remote drives in Powerhouse allow you to connect to and work with data stored in external systems or cloud services. These drives act as bridges between Powerhouse contributors and/or other data sources, enabling seamless data synchronization. Drives can exist in 3 category locations.
+Remote drives in Powerhouse allow you to connect to and work with data stored in external systems or cloud services. These drives act as bridges between Powerhouse contributors or other data sources, enabling seamless data synchronization. Drives can exist in three types of locations:
 
 - **Local Storage**: For offline or on-device access.
 - **Cloud Storage**: For centralized, scalable data management.
 - **Decentralized Storage**: Such as Ceramic or IPFS, enabling distributed and blockchain-based storage options.
 
 :::tip **Explainer**
-**Powerhouse Reactors** are the nodes in the network that store and synchronise documents & drives , resolve conflicts and rerun operations to verify document event histories. 
-Reactors can be configured for local storage, centralized cloud storage or on a decentralized storage network. 
+**Powerhouse Reactors** are the nodes in the network that store and synchronize documents and drives, resolve conflicts, and rerun operations to verify document event histories. 
+Reactors can be configured for local storage, centralized cloud storage, or a decentralized storage network. 
 
-A reactor allows you to store multiple documents, but also host **drives** & Drive Explorers with different organisational purposes, users, access rights and more.
+A reactor allows you to store multiple documents and host **drives** and Drive Explorers with different organizational purposes, users, access rights, and more.
 :::
 
-A drive exists by making use of a reactor and the storagelayer that specific reactor is based on. A reactor is the lower level component that makes synchronisation of documents & drives possible. 
+A drive uses a reactor and its underlying storage layer. A reactor is the low-level component that enables the synchronization of documents and drives. 
 
 ### Drive apps 
 
-**Drive Explorers** (also known as Drive Apps) are specialized interfaces that enhance how users interact with document models within a drive. As mentioned previously, technically a drive is just another document, with a list of the documents inside the drive. So it is obvious that you can create a custom editor for your drive-document. 
+**Drive Explorers** (also known as Drive Apps) are specialized interfaces that enhance how users interact with documents within a drive. As mentioned, a drive is technically just another document containing a list of other documents. This means you can create a custom editor for your drive document. 
 
-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. 
+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](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) guide.
 
 
 ## Creating a new drive
 
-![Create New Drive](./images/CreateNewDrive.png)
+<figure className="image-container">
+  <img src={require("./images/CreateDrive.png").default} alt="Create a new drive" />
+  <figcaption>The drive management modal after clicking the 'Create New Drive' button.</figcaption>
+</figure>
 
 To create a new drive in Powerhouse, follow these steps:
-1. Click on the "**Create New Drive**" button in the Connect interface or in the Connect sidebar on the (+) Icon. 
+1. Click the "**Create New Drive**" button in the Connect interface or the **+** icon in the Connect sidebar. 
 2. In the modal that appears, enter a name for your drive in the "**Drive Name**" field.
 3. Select the desired Drive App (such as the Generic Drive Explorer, or any other Drive App you've installed).
 4. Choose the location for your drive: **Local** (only available to you), **Cloud** (available to people in this drive), or **Public** (available to everyone).
 5. (Optional) Enable the "Make available offline" toggle if you want to keep a local backup of your drive.
 6. Once all options are set, click the "Create new drive" button to finalize and create your drive.
 
-## Adding a new remote drive via graphql mutation
+## Add a new remote drive via GraphQL mutation
 
 You can also add a new remote drive to your Connect environment programmatically using GraphQL mutations. This is especially useful for automation, scripting, or integrating with external systems.
 
 :::info **Prerequisites**
-- Access to the Switchboard or remote reactor (server node) of your Connect instance.
-- The GraphQL endpoint for your instance. For example, for the staging environment, use: `https://staging.switchboard.phd/graphql/system` (this is a supergraph gateway).
+- Access to the Switchboard or remote reactor (server node) of your Connect instance. In your local project, you can start your Reactor by running the following command in a different terminal from Connect Studio. 
+  `bash
+  ph reactor
+  `
+- The GraphQL endpoint of your instance. For example, for the staging environment, use: `https://staging.switchboard.phd/graphql/system` (this is a supergraph gateway. Read more about [subgraphs and supergraphs here](/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs).
 - Appropriate permissions to perform mutations.
 :::
 
-### Steps
-1. **Navigate to the GraphQL Playground or use a GraphQL client**
-   - Open [https://staging.switchboard.phd/graphql/system](https://staging.switchboard.phd/graphql/system) in your browser, or use a tool like [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/).
+<figure className="image-container">
+  <img src={require("./images/CreateNewDrive.png").default} alt="Create a new drive" />
+  <figcaption>The GraphQL interface for creating a new drive through a mutation.</figcaption>
+</figure>
 
-2. **Prepare the Mutation**
+### 1. **Navigate to the GraphQL Playground or use a GraphQL client**
+   - Open [https://switchboard.phd/graphql/system](https://switchboard.phd/graphql/system) in your browser, or use a tool like [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/).
+
+### 2. **Prepare the Mutation**
    - Use the following mutation to create a new drive:
 
-   ```graphql
+   ```graphql title="Create Drive Mutation"
    mutation Mutation($name: String!, $icon: String, $addDriveId: String, $slug: String) {
      addDrive(name: $name, icon: $icon, id: $addDriveId, slug: $slug) {
        icon
@@ -82,8 +92,8 @@ You can also add a new remote drive to your Connect environment programmatically
    }
    ```
 
-   - Example variables:
-   ```json
+   - These are the example variables, feel free to change these as you like and add a different name or logo for your drive:
+   ```json title="Example Variables"
    {
      "name": "AcademyTest",
      "icon": "https://static.thenounproject.com/png/3009860-200.png",
@@ -91,12 +101,12 @@ You can also add a new remote drive to your Connect environment programmatically
      "slug": null
    }
    ```
-   - You can also provide a custom `id`, `slug`, or `preferredEditor` if needed.
+   - You can also provide a custom `id` or `slug` if needed.
 
-3. **Execute the Mutation**
+### 3. **Execute the Mutation**
    - Run the mutation. On success, you will receive a response containing the new drive's `icon`, `id`, `name`, and `slug`:
 
-   ```json
+   ```json title="Successful Response"
    {
      "data": {
        "addDrive": {
@@ -109,16 +119,30 @@ You can also add a new remote drive to your Connect environment programmatically
    }
    ```
 
-4. **Construct the Drive URL**
+### 4. **Construct the Drive URL**
    - Once you have the `id` or `slug`, you can construct the drive URL for Connect:
-     - Format: `domain/d/driveId` or `domain/d/driveSlug`
-     - Example: `https://staging.connect.phd/d/6461580b-d317-4596-942d-f6b3d1bfc8fd`
+     - Format: `domain/d/<driveId>` or `domain/d/<driveSlug>` 
+     - Depending on whether you are using a hosted or a local environment, the domain in your URL will change.
+     - Example: `https://connect.phd/d/6461580b-d317-4596-942d-f6b3d1bfc8fd`
+     - Example: `https://localhost:4001/d/6461580b-d317-4596-942d-f6b3d1bfc8fd`
+
+### 5. **Add the Drive in Connect**
+   - Use the constructed URL to add or access the drive in your Connect environment via the 'Add Drive' button. 
 
-5. **Add the Drive in Connect**
-   - Use the constructed URL to add or access the drive in your Connect environment.
+<figure className="image-container">
+  <img src={require("./images/AddDrive.png").default} alt="Create a new drive" />
+  <figcaption>The 'Add Drive' button that allows you to enter your constructed Drive URL.</figcaption>
+</figure>
 
 ---
 
 This approach allows you to automate drive creation and integration with other systems, making it easy to manage drives at scale.
 
+## Up next 
+
+You've now experienced the use of GraphQL to modify or read data captured in Powerhouse for the first time. 
+You can now either continue with:
+- User interfaces and [build a custom drive experiences](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) 
+- Keep playing with data and the [Switchboard API](/academy/MasteryTrack/WorkWithData/ReadingAndWritingThroughTheAPI)
 
+Enjoy!

package/docs/academy/02-MasteryTrack/04-WorkWithData/01-ReadingAndWritingThroughTheAPI.mdx

@@ -2,114 +2,232 @@
 
 ## Introduction to Switchboard
 
-**Switchboard** is the API interface that allows developers and data engineers to get access to the data, that is being collected through the use of document models in Connect & Fusion.
-After structurally capturing the desired data of your formalised business processes the data can be used to build insightful experiences in external websites, drive widgets or create specific reports and dashboard in fusion. 
+**Switchboard** is the API interface that allows developers and data engineers to get access to data collected through document models in Connect and Fusion.
+After structurally capturing the desired data from your formalized business processes, it can be used to build insightful experiences in external websites, drive widgets, or create specific reports and dashboards in Fusion.
 
-:::tip Using the state schema of your document
-Since your document models have been defined with a GraphQL schema, you can use the same objects and fields in your queries and mutations to retrieve or write data from and to your document models.
+:::tip Using your document's state schema
+Since your document models are defined with a GraphQL schema, you can use the same objects and fields in your queries and mutations to retrieve or write data from and to your documents.
 :::
 
 ## Querying a document with the GraphQL API
 
 ### Starting the reactor locally
 
-In this tutorial we'll show how to use a **GraphQL** query to query a document model. We'll **continue on the To-do List example** from our [introduction tutorial](/academy/GetStarted/CreateNewPowerhouseProject) , 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).
+In this tutorial, we'll show how to use a **GraphQL** query to query a document model. We'll continue with the **To-do List example** from our [introduction tutorial](/academy/GetStarted/CreateNewPowerhouseProject), 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 What are reactors?
-**Powerhouse Reactors** are the nodes in the network that store documents, resolve conflicts and rerun operations to verify document event histories. 
-Reactors can be configured for local storage, centralized cloud storage or on a decentralized storage network. 
+**Powerhouse Reactors** are the nodes in the network that store documents, resolve conflicts, and rerun operations to verify document event histories. 
+Reactors can be configured for local storage, centralized cloud storage, or a decentralized storage network.
 :::
 
-Just like we can run Connect locally in studio mode we can run a remote node or a Reactor locally.   
-Use the following commands:
+Just as you can run Connect locally in studio mode, you can also run a Reactor locally. Use the following command in the terminal from within your Powerhouse project directory:
 
 ```bash
 ph reactor
 ```
 
-To start both Connect and a Reactor locally at the same time in a Powerhouse project you can use the following command:
+To start both Connect and a Reactor locally at the same time in a Powerhouse project, you can use the following command:
 ```bash
 ph dev
 ```
 
-It will return a url to access the Reactor.
+This will return a URL to access the Reactor.
 ```bash
 [Reactor]:   ➜  Reactor:   http://localhost:4001/d/powerhouse
 ```
 
-### Adding a remote drive or reactor to Connect
+### Adding a remote drive or Reactor to Connect
 
-If the remote drive or Reactor isn't present yet in connect you can add it by clicking the (+) button in the Connect drive navigation 
-and using the localhost url to add a new drive with it's underlying reactor. Usually http://localhost:4001/d/powerhouse
+If the remote drive or Reactor isn't present yet in Connect, you can add it by clicking the (+) button in the Connect drive navigation and using the localhost URL to add a new drive with its underlying reactor. Usually, this is http://localhost:4001/d/powerhouse.
 
-Get access to an **organisations drive** instances by adding their drive to your Connect Drive navigation tree view with the help of the correct drive url. 
-Click the (+) to add a public drive. To add a new drive you'll have to know the correct public URL of the drive.
+Get access to an **organization's drive** instances by adding their drive to your Connect Drive navigation tree view with the help of the correct drive URL.
+Click the (+) to add a public drive. To add a new drive, you'll have to know the correct public URL of the drive. Read more about [configuring drives](/academy/Architecture/WorkingWithTheReactor).
 
-## Querying the state of a document
+<figure className="image-container">
+  <img src={require("./images/AddNewDriveURL.png").default} alt="Add a drive through an URL" />
+  <figcaption>The 'Add Drive' button that allows you to enter a Drive URL.</figcaption>
+</figure>
 
-Now that we have our remote reactor and/or drive running we can store our document model on it.   
-Let's quickly create a new to-do list document to test the process.
+## Query the state of a document
 
-Add to following todo's to your list:
+Now that we have our remote reactor and/or drive running, we can store our document model on it.
+Let's quickly create a new to-do list document in Connect Studio to test the process. Let's call it **'Powerhouse-onboarding-tasks'**.
+
+
+Add the following to-dos to your list:
 - [ ] Sign up for Powerhouse
 - [ ] Do the work 
 - [ ] Deliver the work
 - [ ] Send the invoice
 - [ ] Get paid
 
-Now that we have some data in our document model we can query it through the GraphQL API.
+Below is the operation history of the to-do list document. As you can see, the operations are logged in the order they were executed.
+
+<figure className="image-container">
+  <img src={require("./images/OnboardingTasks.png").default} alt="Operation history in Connect" />
+  <figcaption>The operation history of the to-do list document, showing each change made.</figcaption>
+</figure>
+
+Now that we have some data in our document model, we can query it through the GraphQL API.
+
+### Option 1: Query your document via the Switchboard API Button.
+
+Whenever you want to start a query from a document within Connect, you can open Switchboard by clicking the Switchboard icon in the top right-hand corner of the document editor interface.
+The Switchboard API button at the top of your document model will get you the complete state of your current document.
+This will prepopulate the Apollo Studio Sandbox with the correct **DocumentID** for your document model.
 
-### 1. The complete state of the document
+<figure className="image-container">
+  <img src={require("./images/SwitchboardButton.png").default} alt="Switchboard button in document editor" />
+  <figcaption>The Switchboard button provides a direct link to the GraphQL API for the document.</figcaption>
+</figure>
 
-Whenever you want to start a query from a document within connect you can open up Switchboard by looking for the Switchboard logo in the top right hand corner of the document editor interface. 
-This will prepopulate the Apollo Studio Sandbox with the correct **DocumentID** for your document model. This feature will not be available for documents stored on local drives.
+### Option 2: Query your document by document ID
 
-![Switchboardbutton](./images/SwitchboardButton.png)
+In your Document Toolbar, you will find an icon to visit your operations history. At the top of the toolbar, you will find your document ID.
+Copy this ID to use it in the Switchboard API.
 
-The documentation on the left hand side of the Apollo Sandbox will show you all of the different fields that are available to query.
+<figure className="image-container">
+  <img src={require("./images/DocumentID.png").default} alt="Copy the DocumentID" />
+  <figcaption>You can copy your Document ID from your operations history.</figcaption>
+</figure>
 
-![document query](./images/QueryDocumentID.png)
+When you navigate to your Switchboard endpoint (e.g., http://localhost:4001/graphql/system, https://switchboard.phd/graphql/system, or a custom domain), you can use this document ID to query the state of your document.
+The documentation on the left-hand side of the Apollo Sandbox will show you all the different fields that are available to query.
 
-Alternatively we can just use our reactor url and endpoint to figure out the document id.  
-We can find out what the id of our document is by querying the drive for it's documents.   
-Since we only have one document in our drive it will return the id of our to-do list document.
+<figure className="image-container">
+  <img src={require("./images/QueryDocumentID.png").default} alt="Apollo Studio with document query" />
+  <figcaption>The Apollo Studio Sandbox showing the available fields for querying a document.</figcaption>
+</figure>
 
-This example query is structured to request a document by its unique identifier (id).   
-It extracts common fields such as **id**, **name**, **documentType**, **revision**, **created**, and **lastModified**.
+### Option 3: Search for your document ID via GraphQL
+
+**Alternatively**, we can use our Reactor URL and endpoint to figure out the document ID.
+e.g., http://localhost:4001/graphql/system, https://switchboard.phd/graphql/system or your custom https://switchboard.domain/graphql/system
+
+We can find out the ID of our document by querying the drive for its documents.
+Since we only have one document in our drive, this query will return the ID of our to-do list document.
+
+```graphQL title="Document ID Query"
+query Query {
+  ToDoList {
+    getDocuments {
+      id
+      name
+      documentType
+      revision
+      created
+      lastModified
+    }
+  }
+}
+```
 
-In the above example we queried for the content of the operations. Let's compare the results with the document operation history. 
-Side by side you can see the document content and the operation history.
+This example query is structured to request all documents of type `ToDoList` from the drive.
+It extracts common metadata fields such as **id**, **name**, **documentType**, **revision**, **created**, and **lastModified**.
 
-Below is the operation history of the todo list document. As you can see the operations are logged in the order they were executed.
-As you can see there is a 'Delete' operation in the history on revision 5 as we forgot to add 'Send the invoice' to our list.
-![Operation History](./images/OperationHistory.png)
+### Get the state of the document
 
-Now let's query the content of the document using Apollo Studio Sandbox. The left sidebar shows the schema documentation, where you can explore all available fields and types for your document model. 
+Once you've found your document via any of the three options, you'll be able to query its state.
 
-For our To-do List document, let's construct a query that fetches the operations with the help of a nested operations field
+In the previous step, we queried for document metadata. Now let's query for the actual content of the document state.
 
-```graphql
-query {
-  document(id: "...") {
-    name
-    documentType
-    revision
-    created
-    lastModified
-    ... on TodoList {
-      operations {
-        type
-        id
-        inputText
+```graphql title="Get the Document state"
+query getDocument($documentId: PHID!, $driveId: String) {
+  ToDoList {
+    getDocument(docId: $documentId, driveId: $driveId) {
+      id
+      created
+      lastModified
+      name
+      revision
+      state {
+        items { id text checked } stats { total checked unchecked }
       }
     }
   }
 }
 ```
 
-This query will return all operations performed on the document, including ADD_TODO_ITEM and DELETE_TODO_ITEM operations, allowing us to see the complete history of changes.
+```graphql title="Example variables"
+{
+  "documentId": "03eb6780-f1d7-438c-84a0-6d93dfb8f6af", // or replace this with your specific doc ID
+  "driveId": "powerhouse" // or replace this with your specific driveId
+}
+```
+
+This query will return the current state of the document, including all to-do items and stats.
+
+<figure className="image-container">
+  <img src={require("./images/OperationsQuery.png").default} alt="Executing a mutation for a to-do item in Apollo Studio" />
+  <figcaption>The Apollo Studio Sandbox showing the <code>addTodoItem</code> mutation. You can see the variables passed in and the response from the server.</figcaption>
+</figure>
+
+
+## Mutate the state of a document
+
+Now that we know how to query the state of a document, we can start to write to it.
+
+To perform write operations, we use **GraphQL Mutations**. Mutations are similar to queries, but they are used to create, update, or delete data. For our To-do List, we'll want to add, check, and remove items.
+
+### Adding a new to-do item
+
+Let's start by adding a new item to our list. The document model for our to-do list has an `ADD_TODO_ITEM` operation, which translates to an `addTodoItem` mutation in GraphQL.
+To use this mutation, you need to provide the `docId` of the to-do list you want to modify, and the `text` and `id` for the new to-do item. We'll specify these via variables.
+
+Here is an example of how to structure the mutation:
+
+```graphql title="example-add-mutation"
+mutation Mutation($docId: PHID, $input: ToDoList_AddTodoItemInput) {
+  ToDoList_addTodoItem(docId: $docId, input: $input)
+}
+```
+
+```graphql title="example-variables"
+{
+  "docId": "03eb6780-f1d7-438c-84a0-6d93dfb8f6af",
+  "input": {
+    "text": "My new to-do from GraphQL",
+    "id": "1"
+  }
+}
+```
+
+Replace the example `docId` with the actual ID of your document. You can get this ID by querying the drive as we did before.
+
+When you execute this mutation in Apollo Studio, it will add the new item to your to-do list. The response will return the number of to-do's on your list.
+
+### Deleting a to-do item
+
+To delete an item, you'll need its unique identifier. When you query for the to-do items in your list, each one will have an `id`. You'll use this `id` to specify which item to delete.
+
+The document model provides a `DELETE_TODO_ITEM` operation, which corresponds to a `deleteTodoItem` mutation.
+
+Here's how you can use it:
+```graphql title="example-delete-mutation"
+mutation Mutation($docId: PHID, $input: ToDoList_DeleteTodoItemInput) {
+  ToDoList_deleteTodoItem(docId: $docId, input: $input)
+}
+```
+
+```graphql title="example-variables"
+{
+  "docId": "03eb6780-f1d7-438c-84a0-6d93dfb8f6af",
+  "input": {
+    "id": "0.6325811781889789"
+  }
+}
+```
+
+Make sure to replace the `docId` and `id` with the appropriate values for your document and the item you wish to delete.
+
+After executing this mutation, the specified to-do item will be removed from your list.
+
+### Verifying the changes
+
+After performing a write mutation, you can verify that the change was successful in a couple of ways:
 
-## Writing to a document
+1.  **Query the document state again:** Rerun the `getDocument` query from earlier in this tutorial. You should see the new item in the list or the deleted item removed.
+2.  **Check the Operation History:** The operation history in Connect will show the new `ADD_TODO_ITEM` or `DELETE_TODO_ITEM` operation, along with who performed it and when. This provides a complete audit trail of all changes to the document.
 
-Now that we know how to query the state of a document we can start to write to it.
+This ability to programmatically read from and write to documents via the GraphQL API is a powerful feature of Powerhouse. It unlocks countless possibilities for integrating your structured data into other applications, building automated workflows, and creating rich, data-driven user experiences.

package/docs/academy/02-MasteryTrack/04-WorkWithData/04-analytics-processor.md

@@ -7,7 +7,7 @@ An Analytics Processor is an object that can track analytics for operations and
 The `ph-cli` utility can be used to generate the scaffolding for an Analytics Processor.
 
 ```
-npx @powerhousedao/ph-cli generate --processor-type analytics --document-models ./my-document-models
+ph generate -p MyAnalyticsProcessor --processor-type analytics
 ```
 
 This will generate two files: a class that implements `IProcessor` and a `ProcessorFactory` function that creates an instance of your processor. We can start with the factory.
@@ -340,3 +340,91 @@ export class DriveProcessorProcessor implements IProcessor {
   async onDisconnect() {}
 }
 ```
+
+## Learn by example: Contributor Billing
+
+Here we have documented the entire development process for the contributor billing processor.
+
+First, we setup the repository locally.
+
+```
+$ git clone git@github.com:powerhouse-inc/contributor-billing.git
+$ cd contributor-billing
+~/contributor-billing $ pnpm install
+```
+
+Now we can generate an analytics processor, using default settings.
+
+```
+~/contributor-billing $ ph generate -p LineItemProcessor --processor-type analytics
+```
+
+We can see what was generated:
+
+```
+~/contributor-billing $ tree processors
+processors
+├── index.ts
+└── line-item-processor
+    └── index.ts
+```
+
+> Note that `processors/index.ts` will only be created if it does not already exist. In this case, you will be responsible for adding the processor to the `processorFactory` function.
+
+### `IProcessorFactory`
+
+Let's check out the generated `index.ts` file.
+
+```ts
+/**
+ * This is a scaffold file meant for customization.
+ * Delete the file and run the code generator again to have it reset
+ */
+
+import { ProcessorRecord } from "document-drive/processors/types";
+import { LineItemProcessorProcessor } from "./line-item-processor/index.js";
+
+export const processorFactory =
+  (module: any) =>
+  (driveId: string): ProcessorRecord[] => {
+    return [
+      {
+        processor: new LineItemProcessorProcessor(module.analyticsStore),
+        filter: {
+          branch: ["main"],
+          documentId: ["*"],
+          scope: ["*"],
+          documentType: ["*"],
+        },
+      },
+    ];
+  };
+```
+
+This is described in more detail in the [ProcessorFactory](#processorfactory) section, but for our purposes, we only want our processor to run for our document type, so we should change the filter's `documentType`.
+
+```ts
+filter: {
+  branch: ["main"],
+  documentId: ["*"],
+  scope: ["*"],
+  documentType: ["powerhouse/billing-statement"],
+},
+```
+
+### Data Design
+
+Before we get into the meat of the processor, we need to design the data we're going to be working with.
+
+
+
+### `IProcessor`
+
+Now we can open up `line-item-processor/index.ts` to add the custom logic we're looking for. This will be in the `onStrands` function.
+
+```ts
+
+```
+
+
+

package/docs/academy/04-APIReferences/01-ReactHooks.md

@@ -27,11 +27,6 @@ Hook names must always start with `use` followed by a capital letter (e.g., `use
 
 It's important to note that a function should only be named and treated as a hook if it actually utilizes one or more built-in React hooks. If a function (even if named `useSomething`) doesn't call any built-in hooks, it behaves like a regular JavaScript function, and making it a "hook" offers no specific React advantages.
 
-For more details, see the official documentation and API references of React:
-- [Reusing Logic with Custom Hooks (react.dev)](https://react.dev/learn/reusing-logic-with-custom-hooks)
-- [Rules of Hooks (react.dev)](https://react.dev/reference/rules/rules-of-hooks)
-- [Powerhouse React Hooks API Reference](docs/academy/APIReferences/ReactHooks)
-
 </details>
 
 The idea is to make the usage of our hooks feel as simple and familiar as using `useState`.   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "3.2.0-dev.5",
+  "version": "3.2.0-dev.7",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/src/css/custom.css

@@ -488,14 +488,20 @@ html[data-theme='dark'] .DocSearch-Hits > *:empty {
 }
 
 .image-container {
+  box-sizing: border-box;
   border: 1px solid var(--ifm-color-emphasis-300);
   border-radius: var(--ifm-card-border-radius);
-  padding: 1rem;
+  padding: 0.5rem;
   box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
   margin-bottom: 1.5rem;
+  max-width: calc(var(--ifm-container-width-xl) - 2rem);
+  margin-left: auto;
+  margin-right: auto;
 }
 
 .image-container img {
+  width: 100%;
+  height: auto;
   border-radius: var(--ifm-card-border-radius);
 }