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

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 3.2.0-dev.9 (2025-07-02)
+
+### 🩹 Fixes
+
+- updated processor generator and added codegen test for it ([6af3bbcf7](https://github.com/powerhouse-inc/powerhouse/commit/6af3bbcf7))
+- added test to generate and compile a generated document-model ([17bbca3bb](https://github.com/powerhouse-inc/powerhouse/commit/17bbca3bb))
+
+### ❤️ Thank You
+
+- Benjamin Jordan (@thegoldenmule)
+
+## 3.2.0-dev.8 (2025-07-01)
+
+### 🚀 Features
+
+- **academy:** add Drive Analytics documentation and examples ([daedc28a3](https://github.com/powerhouse-inc/powerhouse/commit/daedc28a3))
+
+### ❤️ Thank You
+
+- Guillermo Puente @gpuente
+
 ## 3.2.0-dev.7 (2025-06-28)
 
 ### 🚀 Features

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

@@ -1,18 +1,5 @@
 # Explore the demo package
 
-<details>
-<summary>How long will this tutorial take?</summary>
-
-We've designed this "Get Started" track to be as smooth as possible. The time it takes will vary based on your familiarity with modern web development tools.
-
-- **For Experienced Developers** (familiar with TypeScript, React, and CLIs), you can expect to complete the entire four-part tutorial in approximately **1 to 1.5 hours**.
-- **For Developers New to This Stack**, we recommend setting aside **3.5 to 4.5 hours**. This allows for time to understand not just the steps, but the core concepts behind them.
-
-This is just a guideline. The goal is to learn comfortably and build a solid foundation with Powerhouse!
-
-A more theoretical and advanced version of this tutorial can also be found in [Mastery Track - Document Model Creation](../MasteryTrack/DocumentModelCreation/WhatIsADocumentModel).
-</details>
-
 ## Let's get started
 
 To give you a quick idea of how the Powerhouse ecosystem operates on document models and packages, why don't you try installing a package? 
@@ -109,7 +96,55 @@ Here, you'll see that you've installed the `@powerhousedao/todo-demo-package`, w
   <figcaption>The Package Manager showing the installed todo-demo-package.</figcaption>
 </figure>
 
-## Step 4: Log in with Renown
+## Step 4: Create a todo list document
+
+:::tip What is a 'drive' at Powerhouse?
+A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized 'Drive Apps' for your documents. Think of a Drive App as a specialized lens—it offers **different ways to visualize, organize, and interact with** the data stored within a drive, making it more intuitive and efficient for specific use cases. To learn more, visit [Building A Drive App](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
+:::
+
+### 4.1 Create a local todolist app drive
+
+First, let's create a dedicated drive for your to-do lists:
+
+- Click the new drive icon in the interface
+- In the **Drive App** field, select 'To-do Drive App'
+- This creates a specialized drive that's optimized for to-do list documents
+
+### 4.2 Create a todolist document
+
+Now move into the drive you've just created:
+
+- Click the button at the bottom of the page to create a new to-do list document
+- This opens the to-do list editor where you can start managing your tasks
+
+### 4.3 Add a few todos and inspect the document history
+
+- Add a few to-dos that are on your mind
+- You'll see a statistics widget that counts the open to-dos
+- After closing the document, look at the To-do Drive App interface—you'll see that it tracks your tasks and displays a progress bar
+
+<figure className="image-container">
+  <img src={require("./images/TodoDriveApp.png").default} alt="Todo Drive App" />
+  <figcaption>A list of todo's in the custom todo drive app. </figcaption>
+</figure>
+
+A key feature you get with Connect is the **Operations History**. Every change to a document is stored as an individual operation, creating an immutable and replayable history. This provides complete auditability and transparency, as you can inspect each revision, its details, and any associated signatures. For example, you can see a chronological list of all modifications, along with who made them and when.
+
+<figure className="image-container">
+  <img src={require("./images/OperationsHistoryButton.png").default} alt="Operations History Button" />
+  <figcaption> You can find the button to visit the operations history in the document model toolbar </figcaption>
+</figure>
+
+<figure className="image-container">
+  <img src={require("./images/OperationsHistory.png").default} alt="Operations History" />
+  <figcaption>Example of the operations history for a document, showing all modifications made to it in a list. </figcaption>
+</figure>
+
+Learn more about the [Operations History](../MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free.
+
+This is the power of Drive Apps. They offer a customized interface that works well with the different documents inside your drive. Read more about drive apps in the Mastery Track: [Drive Apps and Drive Explorers](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
+
+## Step 5: Enable operation signing and verification through Renown
 
 Renown is Powerhouse's **decentralized identity and reputation system** designed to address the challenge of trust within open organizations, where contributors often operate under pseudonyms. In traditional organizations, personal identity and reputation are key to establishing trust and accountability. Renown replicates this dynamic in the digital space, allowing contributors to earn experience and build reputation without revealing their real-world identities.
 
@@ -117,16 +152,18 @@ Renown is Powerhouse's **decentralized identity and reputation system** designed
 When signing in with Renown, use an Ethereum or blockchain address that can function as your 'identity', as this address will accrue more experience and history over time.
 :::
 
-### Login flow
-"**Log in with Renown**" is a decentralized authentication flow that enables you to log into applications by signing a credential with your Ethereum wallet. Upon signing in, a Decentralized Identifier (DID) is created based on your Ethereum key. 
+### 5.1 Click the renown icon and connect your eth identity
+
+"**Log in with Renown**" is a decentralized authentication flow that enables you to log into applications by signing a credential with your Ethereum wallet. Upon signing in, a Decentralized Identifier (DID) is created based on your Ethereum key.
 
 <figure className="image-container">
   <img src={require("./images/RenownLogin.png").default} alt="Renown Login" />
   <figcaption>The Renown login screen, prompting for a signature from a wallet.</figcaption>
 </figure>
 
-### Generate a DID to sign operations in Connect
-This DID is then associated with a credential that authorizes a specific Connect instance to act on your behalf. That credential is stored securely on Ceramic, a decentralized data network. When you perform actions through the Powerhouse Connect interface, those operations are signed with the DID and transmitted to Switchboard, which serves as the verifier. 
+### 5.2 Authorize Connect to sign document edits on your behalf
+
+This DID is then associated with a credential that authorizes a specific Connect instance to act on your behalf. That credential is stored securely on Ceramic, a decentralized data network. When you perform actions through the Powerhouse Connect interface, those operations are signed with the DID and transmitted to Switchboard, which serves as the verifier.
 
 <figure className="image-container">
   <img src={require("./images/ConnectAddress.png").default} alt="Connect Address for DID" />
@@ -138,45 +175,17 @@ This DID is then associated with a credential that authorizes a specific Connect
   <figcaption>Confirmation of a successful login with Renown.</figcaption>
 </figure>
 
-### Verifying signatures
-**Switchboard**, our (remote & local) data processing engine, acts as a verifier in the Renown authentication flow. Switchboard checks the validity of the DID and credential, ensuring the operation request is legitimate. This flow is designed to offer a verifiable, cryptographically secure login system that replaces traditional password-based authentication with decentralized identity and signature-based trust.
+### 5.3 Verify the signatures of new operations in the todo list
 
-## Step 5: Create a to-do list and explore the document operations history
-
-<figure className="image-container">
-  <img src={require("./images/OperationsHistory.png").default} alt="Operations History" />
-  <figcaption>Example of the operations history for a document, showing all modifications made to it in a list. </figcaption>
-</figure>
+By leveraging this system, every operation or modification made to a document is cryptographically signed by the contributor's Renown identity. This ensures that each change is verifiable, traceable, and attributable to a specific pseudonymous user, providing a robust audit trail for all document activity.
 
-By leveraging this system, every operation or modification made to a document is cryptographically signed by the contributor's Renown identity. This ensures that each change is verifiable, traceable, and attributable to a specific pseudonymous user, providing a robust audit trail for all document activity. 
-
-A key feature you get with Connect is the **Operations History**. Every change to a document is stored as an individual operation, creating an immutable and replayable history. This provides complete auditability and transparency, as you can inspect each revision, its details, and any associated signatures. For example, you can see a chronological list of all modifications, along with who made them and when. This ensures every action is traceable and verifiable.
-Learn more about the [Operations History](../MasteryTrack/BuildingUserExperiences/DocumentTools/OperationHistory) and other document tools you get for free.
-
-
-### 5.1 Create a to-do list
-
-Now, move back to your local drive and create a to-do list. Add a few to-dos that are on your mind. You'll see a statistics widget that counts the open to-dos.
-
-### 5.2 Create a specific to-do drive app
-
-:::tip What is a 'drive' at Powerhouse?
-A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized 'Drive Apps' for your documents. Think of a Drive App as a specialized lens—it offers **different ways to visualize, organize, and interact with** the data stored within a drive, making it more intuitive and efficient for specific use cases. To learn more, visit [Building A Drive App](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
-:::
-
-Since your previous to-do list was created inside a local drive with a general-purpose drive explorer, it didn't look particularly special.
-
-- Now let's create a new drive by clicking the new drive icon. In the **Drive App** field, select 'To-do Drive App'.  
-- Now move into the drive you've just created and create a new to-do list by clicking the button at the bottom of the page. 
-- Add a new set of random to-dos
-- After closing the document, look at the To-do Drive App interface. You'll see that it tracks your tasks and displays a progress bar.
+Now, return to your to-do list and make some additional changes. You'll notice that these operations are now signed with your Renown identity, making every action traceable and verifiable in the operations history.
 
 <figure className="image-container">
-  <img src={require("./images/TodoDriveApp.png").default} alt="Operations History" />
-  <figcaption>A list of todo's in the custom todo drive app. </figcaption>
+  <img src={require("./images/OperationsHistorySignature.png").default} alt="Operation History Signature" />
+  <figcaption>Your DID is now signing the operations that are being added to the history.</figcaption>
 </figure>
 
-This is the power of Drive Apps. They offer a customized interface that works well with the different documents inside your drive. Read more about drive apps in the Mastery Track: [Drive Apps and Drive Explorers](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
 ## Step 6: Export a document
 
 Export the document as a `.phd` (Powerhouse Document) file using the export button in the document toolbar at the top. In this toolbar, you will find all available functionality for your documents. The `.phd` file can be sent through any of your preferred channels to other users on your network. 

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

@@ -1,4 +1,4 @@
-# Create a to-do list document
+# Create a new to-do list document
 
 ## Overview
 This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **To-do List**.   
@@ -18,52 +18,32 @@ Create a new Powerhouse project with a single command:
 ```bash
 ph init
 ```
-<details>
-<summary>How to use different branches</summary>
-
-When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches.   
-These branches contain more experimental features then the latest stable release the PH CLI uses by default.   
-They can be used to get access to a bugfix or features under development.
-
-| Command | Description |
-|---------|-------------|
-| **pnpm install -g ph-cmd** | Install latest stable version |
-| **pnpm install -g ph-cmd@dev** | Install development version |
-| **pnpm install -g ph-cmd@staging** | Install staging version |
-| **ph init** | Use latest stable version of the boilerplate |
-| **ph init --dev** | Use development version of the boilerplate |
-| **ph init --staging** | Use staging version of the boilerplate |
-| **ph use** | Switch all dependencies to latest production versions |
-| **ph use dev** | Switch all dependencies to development versions |
-| **ph use prod** | Switch all dependencies to production versions |
-
-Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
-</details>
 
 ## Before you begin
 1. Open your terminal (either your system terminal or IDE's integrated terminal)
-2. Navigate to your desired project directory using:
+2. Optionally, create a folder first to keep your Powerhouse projects:
 
    ```bash
-   cd your-directory
+   mkdir ph-projects
+   cd ph-projects
    ```
 3. Ensure you're in the correct directory before running the `ph init` command.  
 In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter.
    ```bash
-    you@yourmachine:~/Powerhouse$ ph init
+    you@yourmachine:~/ph-projects % ph init
 
-    ? What is the project name? ‣ <ToDoList>
+    ? What is the project name? ‣ getting-started
     ```	
 
     Once the project is created, you will see the following output:
     ```bash
-    Initialized empty Git repository in /Users/yourmachine/<ToDoList>/.git/
+    Initialized empty Git repository in /Users/you/ph-projects/getting-started/.git/
     The installation is done! 
     ```
 
     Navigate to the newly created project directory:
     ```bash
-    cd <yourprojectname>
+    cd getting-started
     ```
     Once in the project directory, run the `ph connect` command to start a local instance of the Connect application. This allows you to start your document model specification document.
     Run the following command to start the Connect application:

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

@@ -1,4 +1,4 @@
-# Define the to-do list document specification 
+# Write the document specification 
 
 In this tutorial, you will learn how to define the specifications for a **To-do List** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
 If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification.

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

@@ -401,7 +401,7 @@ export const processorFactory =
   };
 ```
 
-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`.
+This is described in more detail in the [ProcessorFactory](#processorfactory) section, but for our purposes, we only want our processor to run on our document type, so we should update the filter accordingly.
 
 ```ts
 filter: {
@@ -412,15 +412,207 @@ filter: {
 },
 ```
 
-### Data Design
+### Dimension Design
 
-Before we get into the meat of the processor, we need to design the data we're going to be working with.
+Before we get into the meat of the processor, we should be sure to spend some upfront time designing the data we want to query. One way to do this is to start at the end: what do we want to see? In the case of billing statements, we will want to be able to generate reports that show:
 
+- Total spent on headcount vs non-headcount
+- Total spent across all budgets
+- Stacked bar chart of total spent each month, grouped by budget
+- Stacked bar chart of total spent each month, grouped by expense category
+- Total spent each year across all budgets
+- Total spent each year, grouped by budget
+- Total spent per month, grouped by budget
+- Total spent last 30 days, grouped by budget
 
+From here, we can deconstruct the different criteria we would like to group data across:
+
+- time period
+- budget
+- category
+- contributor
+
+The analytics engine gives us a good way to bucket based on time period, so we can focus on the other criteria, which we will specify as _dimensions_. Let's use these dimentions to stub out some of the queries we would want to run, using the `useAnalyticsQuery` hook.
+
+### Query Design
+
+Let's start with "Total spent on headcount vs non-headcount". First, we need to define the time-based criteria.
+
+> Time and Dates can be very confusing. This is why we use the `DateTime` class from `luxon`-- see the [luxon docs](https://moment.github.io/luxon/#/math) for a quickstart.
+
+```ts
+// easy way to get the start and end of the current year
+const start = DateTime.now().startOf("year");
+const end = DateTime.now().endOf("year");
+
+// this means we'll aggregate results across the entire time period
+const granularity = "total";
+```
+
+Next, we want to define the metrics we want to analyze. These are the numerical values we will be aggregating over.
+
+```ts
+// the two numerical values we want to analyze are cash and powt, which are declared separately in the document model
+const metrics = ["Cash", "Powt"];
+```
+
+Now, we can define the dimensions we want to group by. We can imagine that we will have a `contributor` dimension, which will tell us whether or not the contributor is headcount: `/billing-statement/contributor/headcount` or `/billing-statement/contributor/non-headcount`.
+
+> It's best practice to namespace dimensions so that we are sure our data is not colliding with other processors. In this case, we will prepend the `billing-statement` namespace, which is simply a prefix we made up.
+
+```ts
+const totalSpendOnHeadcount = useAnalyticsQuery({
+  start, end, granularity, metrics,
+  select: {
+    contributor: "/billing-statement/contributor"
+  },
+  lod: {
+    contributor: 3,
+  },
+});
+```
+
+It is very important to note that the `lod` parameter is used to specify the level of detail we want to see. In this case, we want to see results grouped by contributor, so we set `lod` to `3`. This means we will get separate metric results for `/billing-statement/contributor/headcount` and `/billing-statement/contributor/non-headcount`.
+
+We can use these same strategies to create queries for the other criteria we want to group by.
+
+```ts
+const totalSpend = useAnalyticsQuery({
+  start,
+  end,
+  granularity: "total", // <--- this means we'll get results for the entire time period
+  metrics: ["Cash", "Powt"],
+  select: {
+    budget: "/billing-statement"
+  },
+  lod: {
+    budget: 0, // <--- this means we'll get all results lumped together
+  },
+});
+
+const monthlySpendByBudget = useAnalyticsQuery({
+  start,
+  end,
+  granularity: "monthly", // <--- this means we'll get results grouped by month
+  metrics: ["Cash", "Powt"],
+  select: {
+    budget: "/billing-statement/budget"
+  },
+  lod: {
+    budget: 3, // <--- this means we'll get results grouped by "/billing-statement/budget/budget1", "/billing-statement/budget/budget2", etc.
+  },
+});
+
+const monthlySpendByCategory = useAnalyticsQuery({
+  start,
+  end,
+  granularity: "monthly", // <--- this means we'll get results grouped by month
+  metrics: ["Cash", "Powt"],
+  select: {
+    category: "/billing-statement/category"
+  },
+  lod: {
+    category: 3, // <--- this means we'll get results grouped by "/billing-statement/category/category1", "/billing-statement/category/category2", etc.
+  },
+});
+
+const yearlySpendByBudget = useAnalyticsQuery({
+  start: DateTime.fromObject({ year: 2022 }),
+  end: DateTime.now().endOf("year"),
+  granularity: "yearly", // <--- this means we'll get results grouped by year
+  metrics: ["Cash", "Powt"],
+  select: {
+    budget: "/billing-statement/budget"
+  },
+  lod: {
+    budget: 3, // <--- this means we'll get results grouped by "/billing-statement/budget/budget1", "/billing-statement/budget/budget2", etc.
+  },
+});
+
+const monthlySpendByBudget = useAnalyticsQuery({
+  start,
+  end,
+  granularity: "monthly", // <--- this means we'll get results grouped by month
+  metrics: ["Cash", "Powt"],
+  select: {
+    budget: "/billing-statement/budget"
+  },
+  lod: {
+    budget: 3, // <--- this means we'll get results grouped by "/billing-statement/budget/budget1", "/billing-statement/budget/budget2", etc.
+  },
+});
+
+const last30DaysSpendByBudget = useAnalyticsQuery({
+  start: DateTime.now().minus({ days: 30 }),
+  end: DateTime.now(),
+  granularity: "day", // <--- this means we'll get results grouped by day
+  metrics: ["Cash", "Powt"],
+  select: {
+    budget: "/billing-statement/budget"
+  },
+  lod: {
+    budget: 3, // <--- this means we'll get results grouped by "/billing-statement/budget/budget1", "/billing-statement/budget/budget2", etc.
+  },
+});
+```
+
+### Source Design
+
+The final consideration is the source design. While dimensions and sources both use path syntax, _the paths are unrelated_. That is, a path used in an AnalyticsSeries `source` does not affect a path used in a `dimension`, and vice versa. The `source` attribute of an analytics series is a composable mechanism to track down _where the data came from_.
+
+This turns out to be an important consideration, as when we query data, we will likely also want to subscribe to a set of sources to later update the data.
+
+For instance, say we take our monthly spend by category query:
+
+```ts
+const monthlySpendByCategory = useAnalyticsQuery({
+  start,
+  end,
+  granularity: "monthly", 
+  metrics: ["Cash", "Powt"],
+  select: {
+    category: "/billing-statement/category"
+  },
+  lod: {
+    category: 3,
+  },
+});
+```
+
+This gives us the results we're looking for but, by design, there may be many different `AnalyticsSeries` objects that relate to affect this query. Thus, the hook does not know what to listen to. This is where our `source` design comes in. Generally, we will want to relate analytics by drive and/or document.
+
+```ts
+// this source will match all analytics updates from any document in the drive
+const driveSource = AnalyticsPath.fromString(`billing-statement/${drive.header.id}`);
+
+// this source will match all analytics updates from a specific document in a drive
+const documentSource = AnalyticsPath.fromString(`billing-statement/${drive.header.id}/${document.header.id}`);
+```
+
+```ts
+const { state, data: drive } = useSelectedDrive();
+
+const results = useAnalyticsQuery({
+  start, end,
+  granularity: "monthly", 
+  metrics: ["Cash", "Powt"],
+  select: {
+    category: "/billing-statement/category"
+  },
+  lod: {
+    category: 3,
+  },
+},
+{
+  sources: [
+   `/billing-statement/${drive.header.id}/` 
+  ],
+});
+```
 
 ### `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.
+Now that we have designed out our data, 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/02-MasteryTrack/04-WorkWithData/05-AnalyticsProcessorTutorial/02-CreateNewPowerhouseProject.md

@@ -16,7 +16,7 @@ Let's start with step 1 & 2 in the next section of the tutorial!
 
 To create a new Powerhouse Document Model Library project, you can use the `ph init` command in your terminal. This command will create a new project in the current directory.
 
-## Create new Powerhouse document model library project
+## Create new Powerhouse document model project
 
 :::info
 This command will create a new project in the current directory.
@@ -24,8 +24,10 @@ You can run the command in the terminal window of your OS or you open the newly
 You will need VSCode later in the tutorial once you have generated the document model.
 Make sure the terminal reflects the directory where you want to create the new project.
 To open a directory in a terminal, you use the cd command to change your current directory. The cd command takes an argument, usually the name of the folder you want to move to, so the full command is 
+
 ```bash
-cd your-directory
+mkdir ph-projects
+cd ph-projects
 ```
 This essentially opens that folder and places you in it.
 :::

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

@@ -0,0 +1,467 @@
+# Drive Analytics
+
+Drive Analytics provides automated monitoring and insights into document drive operations within Powerhouse applications. This system tracks user interactions, document modifications, and drive activity to help developers understand usage patterns and system performance.
+
+## Overview
+
+The Drive Analytics system consists of two specialized processors that automatically collect metrics from document drives:
+
+1. **Drive Analytics Processor**: Tracks file and folder operations (creation, deletion, moves, etc.)
+2. **Document Analytics Processor**: Tracks document content changes and state modifications
+
+These processors run in the background, converting operations into structured time-series data that can be queried and visualized in real-time.
+
+## Available Metrics in Connect
+
+Connect applications have Drive Analytics enabled by default through the `ReactorAnalyticsProvider`. When enabled, the system automatically tracks:
+
+### Drive Operations Metrics
+- **File Creation**: New documents added to drives
+- **Folder Creation**: New directories created  
+- **File Updates**: Document content modifications
+- **Node Updates**: Metadata changes
+- **File Moves**: Documents relocated between folders
+- **File Copies**: Document duplication
+- **File Deletions**: Documents removed from drives
+
+### Document Operations Metrics
+- **State Changes**: Document model state modifications
+
+## Data Sources and Structure
+
+Drive Analytics organizes data using hierarchical source paths that allow precise querying of different analytics contexts:
+
+### Drive Analytics Sources
+Pattern: `ph/drive/{driveId}/{branch}/{scope}`
+- **driveId**: Unique identifier for the document drive
+- **branch**: Branch name (e.g., "main", "dev")  
+- **scope**: Operation scope ("global" for shared operations, "local" for device-specific)
+
+Example: `ph/drive/abc123/main/global`
+
+### Document Analytics Sources  
+Pattern: `ph/doc/{driveId}/{documentId}/{branch}/{scope}`
+- **driveId**: Drive containing the document
+- **documentId**: Specific document identifier
+- **branch**: Branch name
+- **scope**: Operation scope
+
+Example: `ph/doc/abc123/doc456/main/global`
+
+## Available Metrics
+
+### DriveOperations
+Tracks file system operations within drives:
+- **Value**: Always 1 (counter metric)
+- **Purpose**: Count drive-level operations like file creation, deletion, moves
+- **Source Pattern**: `ph/drive/*`
+
+### DocumentOperations  
+Tracks document content and state changes:
+- **Value**: Always 1 (counter metric)
+- **Purpose**: Count document-specific operations like state changes
+- **Source Pattern**: `ph/doc/*`
+
+## Complete Dimensions Reference
+
+### Drive Analytics Dimensions
+
+#### 1. Drive Dimension
+**Pattern**: `ph/drive/{driveId}/{branch}/{scope}/{revision}`
+**Purpose**: Identifies the drive context with revision information
+```tsx
+// Examples
+"ph/drive/abc123/main/global/42"
+"ph/drive/my-drive/feature-branch/local/15"
+```
+
+#### 2. Operation Dimension
+**Pattern**: `ph/drive/operation/{operationType}/{operationIndex}`
+**Purpose**: Identifies specific operation types and their sequence
+
+**Available Operation Types**:
+- **ADD_FILE**: Create new file
+- **ADD_FOLDER**: Create new folder  
+- **UPDATE_FILE**: Modify file content
+- **UPDATE_NODE**: Modify node metadata
+- **MOVE_NODE**: Move file/folder to different location
+- **COPY_NODE**: Duplicate existing file/folder
+- **DELETE_NODE**: Remove file/folder
+
+```tsx
+// Examples
+"ph/drive/operation/ADD_FILE/5"
+"ph/drive/operation/DELETE_NODE/23"
+"ph/drive/operation/MOVE_NODE/12"
+```
+
+#### 3. Target Dimension
+**Pattern**: `ph/drive/target/{targetType}/{targetId}`
+**Purpose**: Identifies what was targeted by the operation
+
+**Target Types**:
+- **DRIVE**: Operation affects the drive itself
+- **NODE**: Operation affects a specific file/folder
+
+```tsx
+// Examples
+"ph/drive/target/DRIVE/abc123"
+"ph/drive/target/NODE/file456"
+"ph/drive/target/NODE/folder789"
+```
+
+#### 4. Action Type Dimension
+**Pattern**: `ph/drive/actionType/{actionType}/{targetId}`
+**Purpose**: Categorizes operations by their effect
+
+**Action Types**:
+- **CREATED**: New items added (ADD_FILE, ADD_FOLDER)
+- **DUPLICATED**: Items copied (COPY_NODE)
+- **UPDATED**: Existing items modified (UPDATE_FILE, UPDATE_NODE)
+- **MOVED**: Items relocated (MOVE_NODE)
+- **REMOVED**: Items deleted (DELETE_NODE)
+
+```tsx
+// Examples
+"ph/drive/actionType/CREATED/file123"
+"ph/drive/actionType/MOVED/folder456" 
+"ph/drive/actionType/REMOVED/doc789"
+```
+
+### Document Analytics Dimensions
+
+#### 1. Drive Dimension
+**Pattern**: `ph/doc/drive/{driveId}/{branch}/{scope}/{revision}`
+**Purpose**: Drive context for document operations
+```tsx
+// Examples
+"ph/doc/drive/abc123/main/global/42"
+```
+
+#### 2. Operation Dimension  
+**Pattern**: `ph/doc/operation/{operationType}/{operationIndex}`
+**Purpose**: Document-specific operation identification
+```tsx
+// Examples (document model operations vary by document type)
+"ph/doc/operation/SET_STATE/15"
+"ph/doc/operation/ADD_ITEM/8"
+"ph/doc/operation/UPDATE_PROPERTY/22"
+```
+
+#### 3. Target Dimension
+**Pattern**: `ph/doc/target/{driveId}/{targetType}/{documentId}`
+**Purpose**: Document target identification
+
+**Target Types**:
+- **DRIVE**: Document is the drive document itself (driveId === documentId)
+- **NODE**: Document is a regular document within the drive
+
+```tsx
+// Examples
+"ph/doc/target/abc123/DRIVE/abc123"  // Drive document
+"ph/doc/target/abc123/NODE/doc456"   // Regular document
+```
+
+## Query Parameters
+
+### Time Range
+- **start**: DateTime object for query start time
+- **end**: DateTime object for query end time
+- **granularity**: Time bucketing (Total, Hourly, Daily, Weekly, Monthly)
+
+### Filtering with Select
+
+Use the `select` parameter to filter by specific dimension values:
+
+```tsx
+select: {
+  // Filter by specific drives
+  drive: [
+    AnalyticsPath.fromString("ph/drive/abc123"),
+    AnalyticsPath.fromString("ph/drive/xyz789")
+  ],
+  
+  // Filter by operation types
+  operation: [
+    AnalyticsPath.fromString("ph/drive/operation/ADD_FILE"),
+    AnalyticsPath.fromString("ph/drive/operation/UPDATE_FILE")
+  ],
+  
+  // Filter by action types  
+  actionType: [
+    AnalyticsPath.fromString("ph/drive/actionType/CREATED"),
+    AnalyticsPath.fromString("ph/drive/actionType/UPDATED")
+  ],
+  
+  // Filter by targets
+  target: [
+    AnalyticsPath.fromString("ph/drive/target/NODE")
+  ]
+}
+```
+
+### Level of Detail (LOD)
+
+Control how deeply dimensions are grouped:
+
+```tsx
+lod: {
+  drive: 1,      // Group by drive only (ignore branch/scope/revision)
+  operation: 1,  // Group by operation type only (ignore index)
+  actionType: 1, // Group by action type only (ignore target ID)
+  target: 1      // Group by target type only (ignore target ID)
+}
+```
+
+## Querying Analytics Data
+
+### Using the useAnalyticsQuery Hook
+
+The primary way to access drive analytics is through the `useAnalyticsQuery` hook:
+
+```tsx
+import { useAnalyticsQuery, AnalyticsGranularity, AnalyticsPath, DateTime } from '@powerhousedao/reactor-browser/analytics';
+
+function DriveUsageChart({ driveId }: { driveId: string }) {
+  const { data, isLoading } = useAnalyticsQuery({
+    start: DateTime.now().minus({ days: 7 }),
+    end: DateTime.now(),
+    granularity: AnalyticsGranularity.Daily,
+    metrics: ["DriveOperations"],
+    select: {
+      drive: [AnalyticsPath.fromString(`ph/drive/${driveId}`)],
+      actionType: [
+        AnalyticsPath.fromString("ph/drive/actionType/CREATED"),
+        AnalyticsPath.fromString("ph/drive/actionType/UPDATED"),
+        AnalyticsPath.fromString("ph/drive/actionType/REMOVED")
+      ]
+    },
+    lod: {
+      drive: 1,
+      actionType: 1
+    }
+  });
+
+  if (isLoading) return <div>Loading analytics...</div>;
+
+  return (
+    <div>
+      {/* Render your chart using the analytics data */}
+      {data?.rows.map(row => (
+        <div key={row.metric}>
+          {row.metric}: {row.value}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Using the useDriveAnalytics Hook
+
+For common drive analytics queries, use the specialized `useDriveAnalytics` hook:
+
+```tsx
+import { useDriveAnalytics } from '@powerhousedao/common/drive-analytics';
+import { AnalyticsGranularity } from '@powerhousedao/reactor-browser/analytics';
+
+function DriveInsights({ driveIds }: { driveIds: string[] }) {
+  const analytics = useDriveAnalytics({
+    filters: {
+      driveId: driveIds,
+      operation: ["ADD_FILE", "UPDATE_FILE", "DELETE_NODE"],
+      actionType: ["CREATED", "UPDATED", "REMOVED"]
+    },
+    from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days ago
+    to: new Date().toISOString(),
+    granularity: AnalyticsGranularity.Daily,
+    levelOfDetail: { drive: 1, operation: 1 }
+  });
+
+  if (analytics.isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h3>Drive Activity Summary</h3>
+      {analytics.data?.rows.map((row, index) => (
+        <div key={index}>
+          <strong>{row.dimensions.find(d => d.name === 'actionType')?.path}</strong>: {row.value}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Using the useDocumentAnalytics Hook
+
+For document-specific analytics queries, use the `useDocumentAnalytics` hook:
+
+```tsx
+import { useDocumentAnalytics } from '@powerhousedao/common/drive-analytics';
+import { AnalyticsGranularity } from '@powerhousedao/reactor-browser/analytics';
+
+function DocumentInsights({ driveId, documentIds }: { driveId: string, documentIds: string[] }) {
+  const analytics = useDocumentAnalytics({
+    filters: {
+      driveId: [driveId],
+      documentId: documentIds,
+      target: ["NODE"], // Focus on document nodes vs drive documents
+      branch: ["main"],
+      scope: ["global"]
+    },
+    from: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(), // 24 hours ago
+    to: new Date().toISOString(),
+    granularity: AnalyticsGranularity.Hourly,
+    levelOfDetail: { 
+      drive: 1, 
+      operation: 1,
+      target: 1 
+    }
+  });
+
+  if (analytics.isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h3>Document Activity Summary</h3>
+      {analytics.data?.rows.map((row, index) => (
+        <div key={index}>
+          Document Operations: {row.value}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Advanced Query Examples
+
+### Filter by Multiple Criteria
+
+```tsx
+// Get file creations and updates for specific drives in the last 24 hours
+const { data } = useAnalyticsQuery({
+  start: DateTime.now().minus({ hours: 24 }),
+  end: DateTime.now(),
+  granularity: AnalyticsGranularity.Hourly,
+  metrics: ["DriveOperations"],
+  select: {
+    drive: [
+      AnalyticsPath.fromString("ph/drive/project-a"),
+      AnalyticsPath.fromString("ph/drive/project-b")
+    ],
+    operation: [
+      AnalyticsPath.fromString("ph/drive/operation/ADD_FILE"),
+      AnalyticsPath.fromString("ph/drive/operation/UPDATE_FILE")
+    ],
+    target: [
+      AnalyticsPath.fromString("ph/drive/target/NODE")
+    ]
+  },
+  lod: {
+    drive: 1,
+    operation: 1
+  }
+});
+```
+
+### Compare Document vs Drive Operations
+
+```tsx
+// Using the specialized hooks for easier comparison
+const driveOps = useDriveAnalytics({
+  filters: { driveId: [driveId] },
+  from: DateTime.now().minus({ days: 1 }).toISO(),
+  to: DateTime.now().toISO(),
+  granularity: AnalyticsGranularity.Total
+});
+
+const docOps = useDocumentAnalytics({
+  filters: { driveId: [driveId] },
+  from: DateTime.now().minus({ days: 1 }).toISO(),
+  to: DateTime.now().toISO(),
+  granularity: AnalyticsGranularity.Total
+});
+
+// Or using useAnalyticsQuery directly
+const driveOpsQuery = useAnalyticsQuery({
+  start: DateTime.now().minus({ days: 1 }),
+  end: DateTime.now(),
+  granularity: AnalyticsGranularity.Total,
+  metrics: ["DriveOperations"],
+  select: {
+    drive: [AnalyticsPath.fromString(`ph/drive/${driveId}`)]
+  }
+});
+
+const docOpsQuery = useAnalyticsQuery({
+  start: DateTime.now().minus({ days: 1 }),
+  end: DateTime.now(),
+  granularity: AnalyticsGranularity.Total,
+  metrics: ["DocumentOperations"],
+  select: {
+    drive: [AnalyticsPath.fromString(`ph/doc/drive/${driveId}`)]
+  }
+});
+```
+
+### Real-time Activity Monitoring
+
+```tsx
+// Monitor specific drive for real-time updates
+const { data } = useAnalyticsQuery(
+  {
+    start: DateTime.now().minus({ minutes: 10 }),
+    end: DateTime.now(),
+    granularity: AnalyticsGranularity.Total,
+    metrics: ["DriveOperations"],
+    select: {
+      drive: [AnalyticsPath.fromString(`ph/drive/${driveId}`)]
+    }
+  },
+  {
+    sources: [AnalyticsPath.fromString(`ph/drive/${driveId}`)],
+    refetchInterval: 5000 // Poll every 5 seconds
+  }
+);
+```
+
+## Real-time Updates
+
+Analytics queries can automatically update when new data is available by specifying sources:
+
+```tsx
+const { data } = useAnalyticsQuery(
+  {
+    start: DateTime.now().minus({ hours: 1 }),
+    end: DateTime.now(),
+    granularity: AnalyticsGranularity.Total,
+    metrics: ["DriveOperations"]
+  },
+  {
+    sources: [AnalyticsPath.fromString(`ph/drive/${driveId}`)]
+  }
+);
+
+// This query will automatically refetch when new operations occur in the specified drive
+```
+
+
+## Configuration in Connect
+
+Drive Analytics is automatically enabled in Connect applications through feature flags:
+
+```tsx
+// In apps/connect/src/context/reactor-analytics.tsx
+export function ReactorAnalyticsProvider({ children }: PropsWithChildren) {
+  return (
+    <AnalyticsProvider options={{ databaseName: "connect:analytics" }}>
+      {connectConfig.analytics.driveAnalyticsEnabled && (
+        <DriveAnalyticsProcessor />
+      )}
+      {children}
+    </AnalyticsProvider>
+  );
+}
+```

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

@@ -13,7 +13,8 @@ To create a new Powerhouse Document Model Library project, you can use the `ph i
 This command will create a new project in the current directory. You can run the command in the terminal window of your OS or you open the newly installed VSCode and run the command in the terminal window of VSCode.Make sure the terminal reflects the directory where you want to create the new project.
 
 ```bash
-cd your-directory
+mkdir ph-projects
+cd ph-projects
 ```
 This essentially opens that folder and places you in it.
 

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

@@ -15,6 +15,22 @@ Here are the key points to understand:
 - **Custom Scalars:** Besides the built-in scalars, you can define custom scalars (e.g., a Date type) if you need to handle more specific formats or validations. Powerhouse does this specific for the web3 ecosystem. 
 :::
 
+## What are Components?
+
+In the context of Powerhouse Builder platform, components can be thought of as reusable elements, or ready-to-use building blocks that help builders implement **document editors & viewers** with little to no effort. An important utility aspect of a component is that it serves its users as a **data input field**, providing structured ways to enter and manipulate information within your document models.
+
+## Document Editors vs Document Viewers
+
+Understanding the relationship between document editors and viewers is crucial for component usage:
+
+**Document Editor**: A specific document type that is used by one or more users to make data entries and update its state. Key utility is the ability to enter data in a structured format, making it a great tool for collaboration within a group of authorized users.
+
+**Document Viewer**: Does not allow modifications. It's a great way to inform about the state of the document type, making it a great tool for providing a broader group or public with transparent insights. Document viewers do not have to match the view of the editor one-to-one - the data presented could be framed as a specific selection, or filtered to provide desired insights.
+
+:::tip Component Behavior in Different Contexts
+The same component that will be used in a document viewer will have a **disabled state** (not allowed to edit documents). Document editors precede document viewers - you would start by creating a document editor and then, if needed, decide which viewer format is useful.
+:::
+
 ## Scalars vs. General UI Components
 
 ### Scalar Components
@@ -39,6 +55,42 @@ This category includes a broader range of UI elements such as simplified version
 **Location:** @powerhousedao/document-engineering/ui   
 https://github.com/powerhouse-inc/document-engineering
 
+## Component Types Classification
+
+Inspired by atomic design methodology, Powerhouse classifies components into the following categories:
+
+### Fragment
+The smallest element that combined together makes up a scalar or other simple component.
+**Examples:** Character counter, Checkbox field, Label
+
+### Scalar (Simple Component)
+The simplest component that contains the basic input field for one-dimensional data type (single value).
+**Examples:** Integer, Boolean, String, Powerhouse ID (PHID)
+
+### Complex Component
+Compound component that has an object/array value. It's made up of multiple scalars combined to serve a specific function.
+**Examples:** Sidebar (tree structure navigation component with content-style navigation for hierarchical data)
+
+### Layout Component
+Purpose-specific container for other components like lists of other components, color layouts, sections, etc.
+**Examples:** Homepage section layout
+
+:::info Component Library Philosophy
+The Powerhouse team is building a Component library with a wide range of components embedding best UX practices & key functionality. This library establishes standards and best practices for building documents while fast-tracking the building process through facilitation of the most basic & useful component types.
+:::
+
+## Component Behavior & UX Principles
+
+Besides the ability to input data, components have another crucial utility: they describe the mechanism of user interaction through implementing a defined set of behavior rules. 
+
+**Best Practices for Component Behavior:**
+- Implementing behaviors at a component level is much more efficient than at the document level
+- Good component behavior feels natural to the user and is easily understood
+- Components should be intuitive and not require additional tutorials or explanations
+- Start with the most simple/basic behaviors first, then layer additional behaviors on top
+- Keep behaviors as simple as needed - less is more
+
+
 ## Exploring Components with Storybook
 
 We use Storybook as an interactive catalog for our design system components. It allows you to visually explore each component, interact with different states, and understand how to integrate them into your projects. [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)

package/docs/academy/07-Cookbook.md

@@ -14,7 +14,7 @@ You need to install the Powerhouse CLI (`ph-cmd`) to create and manage Powerhous
 
 ## Prerequisites
 - node.js 22 installed
-- pnpm package manager installed
+- pnpm package manager 10 installed
 - Terminal or command prompt access
 
 ## Solution
@@ -169,7 +169,7 @@ You need to access experimental features, bugfixes, or development versions of P
 
 ## Prerequisites
 - Terminal or command prompt access
-- pnpm package manager installed
+- pnpm package manager 10 installed
 - Node.js 22 installed
 
 ## Solution

package/package.json

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

package/src/css/custom.css

@@ -157,6 +157,21 @@ a {
   color: #003d7a; /* darker blue on hover */
 }
 
+/* Dark mode specific styles for better readability */
+[data-theme='dark'] .docs-doc-page .theme-doc-markdown a,
+[data-theme='dark'] .markdown a,
+[data-theme='dark'] details a,
+[data-theme='dark'] .theme-doc-markdown details a {
+  color: #66b3ff !important; /* lighter blue for dark mode */
+}
+
+[data-theme='dark'] .docs-doc-page .theme-doc-markdown a:hover,
+[data-theme='dark'] .markdown a:hover,
+[data-theme='dark'] details a:hover,
+[data-theme='dark'] .theme-doc-markdown details a:hover {
+  color: #99ccff !important; /* even lighter blue on hover for dark mode */
+}
+
 /* Reset styling for navigation elements, category pages, and utility links */
 .breadcrumbs a,
 .pagination-nav a,