@powerhousedao/academy 3.3.0-dev.13 → 3.3.0-dev.15

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 3.3.0-dev.15 (2025-07-17)
+
+### 🩹 Fixes
+
+- **codegen:** updated subgraph template to deal with undefined return on getDocument ([7b2862a91](https://github.com/powerhouse-inc/powerhouse/commit/7b2862a91))
+- **academy:** update broken links ([cbbfe9b30](https://github.com/powerhouse-inc/powerhouse/commit/cbbfe9b30))
+
+### ❤️ Thank You
+
+- acaldas
+- Callme-T
+
+## 3.3.0-dev.14 (2025-07-17)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
 ## 3.3.0-dev.13 (2025-07-17)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

package/docs/academy/02-MasteryTrack/04-WorkWithData/03-UsingSubgraphs.md

@@ -19,9 +19,9 @@ A subgraph in Powerhouse is a **GraphQL-based modular data component** that exte
 
 ### Subgraphs consist of
 
-- **A schema** – Which defines the GraphQL Queries and Mutations.
-- **Resolvers** – Which handle data fetching and logic.
-- **Context Fields** – Additional metadata that helps in resolving data efficiently.
+- **A schema** — Which defines the GraphQL Queries and Mutations.
+- **Resolvers** — Which handle data fetching and logic.
+- **Context Fields** — Additional metadata that helps in resolving data efficiently.
 
 #### Additionally, context fields allow resolvers to access extra information, such as:
 - **User authentication** (e.g., checking if a user is an admin).
@@ -40,30 +40,30 @@ context: {
 
 ## 1. How to generate a subgraph
 
-Lets start by generating a new subgraph. For our tutorial we will create a new subgraph within our To-do List project.   
+Let's start by generating a new subgraph. For our tutorial we will create a new subgraph within our To-do List project.   
 Open your project and start your terminal.
 The Powerhouse toolkit provides a command-line utility to create new subgraphs easily.   
 
 ```bash title="Run the following command to generate a new subgraph"
-ph generate --subgraph <to-do-list-subgraph>
+ph generate --subgraph to-do-list
 ```
 
 ```bash title="Expected Output"
 Loaded templates: node_modules/@powerhousedao/codegen/dist/codegen/.hygen/templates
-       FORCED: ./subgraphs/to-do-list-subgraph/index.ts
+       FORCED: ./subgraphs/to-do-list/index.ts
      skipped: ./subgraphs/index.ts
       inject: ./subgraphs/index.ts
 ```
 
 ### What happened?
-1. A new subgraph was created in `./subgraphs/to-do-list-subgraph/`
+1. A new subgraph was created in `./subgraphs/to-do-list/`
 2. The subgraph was automatically registered in your project's registry
 3. Basic boilerplate code was generated with an example query
 
 If we now run `ph reactor` we will see the new subgraph being registered during the startup of the Reactor.
   > Registered /todolist subgraph.
 
-Alternatively, when you are running a local reactor with `ph reactor` a series of subgraphs will automatically get registered, amongst those one for the available document models in your Powerhouse project. 
+Alternatively, when you are running a local reactor with `ph reactor`, a series of subgraphs will automatically get registered, among those, one for the available document models in your Powerhouse project. 
 
 ```
 Initializing Subgraph Manager...
@@ -120,30 +120,77 @@ Now let's create a subgraph that provides enhanced querying capabilities for our
 ```typescript
 export const typeDefs = `
   type Query {
+    # Dashboard-style summary query - returns high-level metrics
+    # Similar to ToDoListStats from document model but optimized for quick queries
     todoList: TodoListSummary
+    
+    # Filtered list query - lets you get items by completion status
+    # More flexible than the basic document model - can filter checked/unchecked
     todoItems(checked: Boolean): [TodoItem!]!
+    
+    # Count-only query - when you just need numbers, not full data
+    # Faster than getting full list when you only need totals for dashboards
     todoItemsCount(checked: Boolean): Int!
   }
 
+  # This mirrors ToDoListStats from the document model
+  # But it's a "view" optimized for summary reports and dashboards
   type TodoListSummary {
-    total: Int!
-    checked: Int!
-    unchecked: Int!
+    total: Int!     # Total number of items
+    checked: Int!   # Number of completed items  
+    unchecked: Int! # Number of pending items
   }
 
+  # This matches the ToDoItem from the document model
+  # Same data structure, but accessed through subgraph queries for filtering
   type TodoItem {
-    id: ID!
-    text: String!
-    checked: Boolean!
+    id: ID!          # Unique identifier
+    text: String!    # The task description
+    checked: Boolean! # Completion status
   }
 `;
 ```
 
+
+
+#### Understanding Resolvers
+
+Before diving into the technical implementation, let's understand why these three different query types matter for your product.
+Think of resolvers as custom API endpoints that are automatically created based on what your users actually need to know about your data.
+
+ When someone asks your system a question through GraphQL, the resolver:
+
+1. **Understands the request** - "The customer wants unchecked items"
+2. **Knows where to get the data** - "I need to check the todo_items database table"  
+3. **Applies the right filters** - "Only get items where checked = false"
+4. **Returns the answer** - "Here are the 5 unchecked items"
+
+**The three resolvers serve different business needs:**
+
+- **`todoList` Resolver - The Dashboard**
+  - **Business value**: Perfect for executive dashboards or KPI displays
+  - **Use case**: "We have 150 total tasks, 89 completed, 61 pending"
+  - **Users**: Executives, managers, anyone needing high-level metrics
+
+- **`todoItems` Resolver - The Detailed List**  
+  - **Business value**: Great for operational views where people need to see actual tasks
+  - **Use case**: "Show me all pending tasks" or "Show me everything"
+  - **Users**: Workers, operators, anyone who needs to act on specific items
+
+- **`todoItemsCount` Resolver - The Counter**
+  - **Business value**: Super fast for analytics or when you only need numbers
+  - **Use case**: "How many completed tasks do we have?" → "47"
+  - **Users**: Analysts, automated systems, performance dashboards
+
+**Why this architecture matters:**
+- **Performance**: Count queries are much faster than getting full lists when you only need numbers
+- **User Experience**: Different resolvers serve different user needs efficiently
+- **Flexibility**: Users can ask for exactly what they need, nothing more, nothing less
+
 **Step 2: Create resolvers in `subgraphs/to-do-list/resolvers.ts`:**
 
 ```typescript
 // subgraphs/to-do-list/resolvers.ts
-// subgraphs/to-do-list/resolvers.ts
 interface SubgraphInstance {
   operationalStore: any;
 }
@@ -196,35 +243,48 @@ import { typeDefs } from './schema.js';
 import { createResolvers } from './resolvers.js';
 
 export default class ToDoListSubgraph {
+  // Define the API endpoint where this subgraph will be accessible
+  // Users can query this at: http://localhost:4001/graphql/to-do-list
   path = '/to-do-list';
   
+  // GraphQL schema definition (what queries are available)
   typeDefs = typeDefs;
+  
+  // Query handlers (how to fetch the data)
   resolvers: any;
+  
+  // Database interface (injected by Powerhouse framework)
   operationalStore: any;
   
   constructor() {
+    // Connect the resolvers to this subgraph instance
+    // This gives resolvers access to the database through this.operationalStore
     this.resolvers = createResolvers(this);
   }
 
+  // Called once when the subgraph starts up
   async onSetup() {
     await this.createOperationalTables();
   }
 
+  // Create the database tables we need for storing todo items
   async createOperationalTables() {
     await this.operationalStore.schema.createTableIfNotExists(
-      "todo_items",
+      "todo_items", // Table name
       (table: any) => {
-        table.string("id").primary();
-        table.string("text").notNullable();
-        table.boolean("checked").defaultTo(false);
-        table.timestamp("created_at").defaultTo(this.operationalStore.fn.now());
-        table.timestamp("updated_at").defaultTo(this.operationalStore.fn.now());
+        table.string("id").primary();           // Unique identifier for each todo item
+        table.string("text").notNullable();     // The actual todo task text
+        table.boolean("checked").defaultTo(false); // Completion status (unchecked by default)
+        table.timestamp("created_at").defaultTo(this.operationalStore.fn.now()); // When item was created
+        table.timestamp("updated_at").defaultTo(this.operationalStore.fn.now()); // When item was last modified
       }
     );
   }
 
+  // Event processor: Keeps subgraph data synchronized with document model changes
+  // When users add/update/delete todos in Connect, this method handles the updates
   async process(event: any) {
-    // Handle To-do List document operations
+    // Handle new todo item creation
     if (event.type === "ADD_TODO_ITEM") {
       await this.operationalStore.insert("todo_items", {
         id: event.input.id,
@@ -237,12 +297,13 @@ export default class ToDoListSubgraph {
       console.log(`Added todo item: ${event.input.text}`);
     }
     
+    // Handle todo item updates (text changes, checking/unchecking)
     if (event.type === "UPDATE_TODO_ITEM") {
       const updateData: any = {
-        updated_at: new Date()
+        updated_at: new Date() // Always update the timestamp
       };
       
-      // Only update fields that were provided
+      // Only update fields that were actually changed
       if (event.input.text !== undefined) {
         updateData.text = event.input.text;
       }
@@ -257,6 +318,7 @@ export default class ToDoListSubgraph {
       console.log(`Updated todo item: ${event.input.id}`);
     }
     
+    // Handle todo item deletion
     if (event.type === "DELETE_TODO_ITEM") {
       await this.operationalStore.delete("todo_items")
         .where("id", event.input.id);
@@ -267,11 +329,6 @@ export default class ToDoListSubgraph {
 }
 ```
 
-**What this schema provides:**
-- `todoList`: Returns statistics about all to-do items (total, checked, unchecked counts)
-- `todoItems`: Returns a list of to-do items, optionally filtered by checked status
-- `todoItemsCount`: Returns just the count of items, optionally filtered by checked status
-
 ### 2.3 Understanding the Implementation
 
 **What this multi-file approach provides:**
@@ -287,70 +344,72 @@ export default class ToDoListSubgraph {
 - Resolvers that fetch and filter todo items from the operational store
 - Event processing to keep the subgraph data synchronized with document model changes
 
-### 2.4 Connect to Document Model Events (Processor Integration)
+### 2.4 Understanding the Document Model Event Integration
 
-To make our subgraph truly useful, we need to connect it to the actual To-do List document model events. This ensures that when users interact with To-do List documents through Connect, the subgraph data stays synchronized.
+Notice that our `index.ts` file already includes a `process` method - this is the **processor integration** that keeps our subgraph synchronized with To-do List document model events. When users interact with To-do List documents through Connect, this method automatically handles the updates.
 
-Add this processor integration to your subgraph:
+**How the existing processor integration works:**
 
+The `process` method in our `index.ts` file handles three types of document model events:
+
+**1. Adding new todo items:**
 ```typescript
-async process(event) {
-  // Handle To-do List document operations
-  if (event.type === "ADD_TODO_ITEM") {
-    await this.operationalStore.insert("todo_items", {
-      id: event.input.id,
-      text: event.input.text,
-      checked: false,
-      created_at: new Date(),
-      updated_at: new Date()
-    });
-    
-    console.log(`Added todo item: ${event.input.text}`);
-  }
-  
-  if (event.type === "UPDATE_TODO_ITEM") {
-    const updateData = {
-      updated_at: new Date()
-    };
-    
-    // Only update fields that were provided
-    if (event.input.text !== undefined) {
-      updateData.text = event.input.text;
-    }
-    if (event.input.checked !== undefined) {
-      updateData.checked = event.input.checked;
-    }
-    
-    await this.operationalStore.update("todo_items")
-      .where("id", event.input.id)
-      .update(updateData);
-    
-    console.log(`Updated todo item: ${event.input.id}`);
-  }
+if (event.type === "ADD_TODO_ITEM") {
+  await this.operationalStore.insert("todo_items", {
+    id: event.input.id,
+    text: event.input.text,
+    checked: false,
+    created_at: new Date(),
+    updated_at: new Date()
+  });
+}
+```
+
+**2. Updating existing items:**
+```typescript
+if (event.type === "UPDATE_TODO_ITEM") {
+  // Only update fields that were actually changed
+  const updateData = { updated_at: new Date() };
+  if (event.input.text !== undefined) updateData.text = event.input.text;
+  if (event.input.checked !== undefined) updateData.checked = event.input.checked;
   
-  if (event.type === "DELETE_TODO_ITEM") {
-    await this.operationalStore.delete("todo_items")
-      .where("id", event.input.id);
-    
-    console.log(`Deleted todo item: ${event.input.id}`);
-  }
+  await this.operationalStore.update("todo_items")
+    .where("id", event.input.id)
+    .update(updateData);
+}
+```
+
+**3. Deleting items:**
+```typescript
+if (event.type === "DELETE_TODO_ITEM") {
+  await this.operationalStore.delete("todo_items")
+    .where("id", event.input.id);
 }
 ```
 
-**What this processor does:**
-- Listens for document model operations (`ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`)
-- Updates the operational store in real-time when these operations occur
-- Provides console logging for debugging
-- Maintains data consistency between the document model and the subgraph
+**The integration happens automatically:**
+1. **User action**: Someone adds a todo item in Connect
+2. **Document model**: Processes the `ADD_TODO_ITEM` operation  
+3. **Framework routing**: Powerhouse automatically calls your subgraph's `process` method
+4. **Subgraph response**: Your `process` method updates the operational store
+5. **Query availability**: Users can now query the updated data via GraphQL
 
 ### 2.5 Summary of What We've Built
 
-- **Added two main queries**: `todoList` for statistics and `todoItems` for item lists
-- **Created an operational table** `todo_items` to store the todo items with proper schema
-- **Added resolvers** to fetch and filter todo items from the operational store
-- **Implemented event processing** to keep the subgraph data synchronized with document model changes
-- **The todoItems query accepts an optional checked parameter** to filter items by their completion status
-- **The todoList query returns the full statistics** including total, checked, and unchecked counts
+Our complete To-do List subgraph includes:
+
+- **GraphQL schema** (`schema.ts`): Defines `todoList`, `todoItems`, and `todoItemsCount` queries
+- **Resolvers** (`resolvers.ts`): Handle data fetching and filtering from the operational store
+- **Main subgraph class** (`index.ts`): Coordinates everything and includes:
+  - **Operational table creation**: Sets up the `todo_items` table with proper schema
+  - **Event processing**: The `process` method keeps subgraph data synchronized with document model changes
+  - **Real-time updates**: Automatically handles `ADD_TODO_ITEM`, `UPDATE_TODO_ITEM`, and `DELETE_TODO_ITEM` events
+
+**Key features:**
+- **Filtering capability**: The `todoItems` query accepts an optional `checked` parameter
+- **Performance optimization**: The `todoItemsCount` query returns just numbers when you don't need full data
+- **Real-time synchronization**: Changes in Connect immediately appear in subgraph queries
+- **Complete statistics**: The `todoList` query returns total, checked, and unchecked counts
 
 ## 3. Testing the To-do List Subgraph
 
@@ -485,7 +544,7 @@ This demonstrates the real-time synchronization between the document model and t
 
 ## 4. Working with the supergraph or gateway
 
-A supergraph is a GraphQL schema that combines multiple underlying GraphQL APIs, known as subgraphs, into a single, unified graph. This architecture allows different teams to work independently on their respective services (subgraphs) while providing a single entry point for clients or users to query all available data
+A supergraph is a GraphQL schema that combines multiple underlying GraphQL APIs, known as subgraphs, into a single, unified graph. This architecture allows different teams to work independently on their respective services (subgraphs) while providing a single entry point for clients or users to query all available data.
 
 ### 4.1 Key concepts
 
@@ -503,7 +562,7 @@ A supergraph is a GraphQL schema that combines multiple underlying GraphQL APIs,
 
 ### 4.3 Use the Powerhouse supergraph
 
-The Powerhouse supergraph for any given remote drive or reactor can be found under `http://localhost:4001/graphql`. The gateway / supergraph available on `/graphql` combines all the subgraphs, except for the drive subgraph (which is accessible via `/d/:driveId`). To get to the endpoint open your localhost by starting the reactor and adding `graphql` to the end of the url. The following commands explain how you can test & try the supergraph. 
+The Powerhouse supergraph for any given remote drive or reactor can be found under `http://localhost:4001/graphql`. The gateway / supergraph available on `/graphql` combines all the subgraphs, except for the drive subgraph (which is accessible via `/d/:driveId`). To access the endpoint, start the reactor and navigate to the URL with `graphql` appended. The following commands explain how you can test & try the supergraph. 
 
 - Start the reactor:
 
@@ -517,7 +576,7 @@ The Powerhouse supergraph for any given remote drive or reactor can be found und
   http://localhost:4001/graphql
   ```
 
-The supergraph allows to both query & mutate data from the same endpoint. 
+The supergraph allows you to both query & mutate data from the same endpoint. 
 
 **Example: Using the supergraph with To-do List documents**
 
@@ -639,7 +698,7 @@ To integrate with them, register them via the Reactor API.
 
 ### Future enhancements
 
-Bridge Processors and Subgraphs – Currently, there's a gap in how processors and subgraphs interact. Powerhouse might improve this in future updates.
+Bridge Processors and Subgraphs — Currently, there's a gap in how processors and subgraphs interact. Powerhouse might improve this in future updates.
 
 
 

package/docs/academy/02-MasteryTrack/04-WorkWithData/07-OperationalDbProcessorTutorial/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "RelationalDb Processor",
+  "position": 6,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn how to make use of a RelationalDb Processor in this tutorial!"
+  }
+}

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

@@ -50,6 +50,42 @@ const updateInvoiceName = useUpdateDocumentField('docId', 'name')
 // Combined read + write (like useState)
 const [invoiceName, updateInvoiceName] = useDocumentField('docId', 'name')
 ```
+Initial documentation about the hooks can be found [here](https://github.com/powerhouse-inc/powerhouse/blob/main/packages/common/state/README.md)
+
+### Temporary use of new hooks on custom drive editors. 
+
+
+To use the new hooks in custom components or editors today, devs must:
+
+1. Pass in the existing Reactor instance as a prop (createReactor).
+2. Call useInitializeReactor(props.createReactor, false) in the custom component.
+3. Optionally wrap dispatch() to trigger a refresh manually, using:
+
+const refresh = useSyncDrivesAndDocumentsWithReactor();
+
+For maximum compatibility, consider passing data and set functions (drives, documents, etc.) directly as props instead of using the hooks inside the custom editor..
+
+Example: 
+
+```
++import { AtomStoreProvider } from "@powerhousedao/common";
+
+export default function Editor(props: IProps) {
+  return (
++    <AtomStoreProvider reactor={props.context.reactor}> 
+      <DriveContextProvider value={props.context}>
+        <WagmiContext>
+          <BaseEditor {...props} />
+        </WagmiContext>
+      </DriveContextProvider>
++    </AtomStoreProvider>
+  );
+}
+```
+
+Until the hooks are fully integrated and event handling is granular, the team will need to handle some of this manually or limit their use to experimental side projects and internal demos.
+
+
 
 
 ## An overview of currently available hooks

package/docs/academy/04-APIReferences/04-RelationalDatabase.md

@@ -7,11 +7,11 @@ This page covers the relational database tools available in Powerhouse applicati
 The relational database layer gives you powerful tools to work with data in your Powerhouse applications. You get type-safe queries, real-time updates, and a simple API that feels familiar to React developers.
 
 **Key Benefits:**
-- 🔒 **Type-safe queries** with full TypeScript support
-- 🔄 **Live query capabilities** with real-time updates  
-- ⚡ **Automatic optimization** to prevent infinite re-renders
-- 🎯 **Simple API** that abstracts away complexity
-- 🧠 **Smart memoization** for parameters and queries
+- **Type-safe queries** with full TypeScript support
+- **Live query capabilities** with real-time updates  
+- **Automatic optimization** to prevent infinite re-renders
+- **Simple API** that abstracts away complexity
+- **Smart memorization** for parameters and queries
 
 ## Quick Start
 
@@ -40,23 +40,26 @@ type MyDatabase = {
 
 ```typescript
 import { createProcessorQuery } from '@powerhousedao/reactor-browser/relational';
+import { MyProcessor } from './processors/my-processor';
 
-const useTypedQuery = createProcessorQuery<MyDatabase>();
+// Create a typed query hook for your processor
+const useTypedQuery = createProcessorQuery(MyProcessor);
 ```
 
 ### Step 3: Use it in your component
 
 ```typescript
 // Simple query - no parameters needed
-export function useUserList() {
-  return useTypedQuery(db => {
+export function useUserList(driveId: string) {
+  return useTypedQuery(driveId, db => {
     return db.selectFrom('users').selectAll().compile();
   });
 }
 
 // Query with parameters
-export function useUserById(userId: number) {
+export function useUserById(driveId: string, userId: number) {
   return useTypedQuery(
+    driveId,
     (db, params) => {
       return db
         .selectFrom('users')
@@ -72,8 +75,8 @@ export function useUserById(userId: number) {
 ### Step 4: Use in your React component
 
 ```typescript
-function UserList() {
-  const { isLoading, error, result } = useUserList();
+function UserList({ driveId }: { driveId: string }) {
+  const { isLoading, error, result } = useUserList(driveId);
 
   if (isLoading) return <div>Loading...</div>;
   if (error) return <div>Error: {error.message}</div>;
@@ -98,40 +101,40 @@ function UserList() {
 ### 1. createProcessorQuery()
 
 <details>
-<summary>`createProcessorQuery<Schema>()`: Creates a typed query hook for your database schema</summary>
+<summary>`createProcessorQuery(ProcessorClass)`: Creates a typed query hook factory for your processor</summary>
 
-### Hook Name and Signature
+### Function Name and Signature
 
 ```typescript
-function createProcessorQuery<Schema>(): TypedQueryHook<Schema>
+function createProcessorQuery<Schema>(
+  ProcessorClass: RelationalDbProcessorClass<Schema>
+): TypedQueryHook<Schema>
 ```
 
 ### Description
 
-Creates a typed query hook that provides type-safe database operations with live query capabilities. This is the main hook you'll use for most relational database operations in your components.
+Creates a typed query hook factory for a specific processor class. This is the main function you'll use to create hooks for querying your relational database.
 
 ### Usage Example
 
 ```typescript
 import { createProcessorQuery } from '@powerhousedao/reactor-browser/relational';
+import { MyProcessor } from './processors/my-processor';
 
-type AppDatabase = {
-  users: { id: number; name: string; email: string };
-  posts: { id: number; title: string; author_id: number };
-};
-
-const useTypedQuery = createProcessorQuery<AppDatabase>();
+// Create a typed query hook for your processor
+const useTypedQuery = createProcessorQuery(MyProcessor);
 
-// Static query (no parameters)
-function useAllUsers() {
-  return useTypedQuery(db => {
+// Use it to create specific query hooks
+export const useUsers = (driveId: string) => {
+  return useTypedQuery(driveId, (db) => {
     return db.selectFrom('users').selectAll().compile();
   });
-}
+};
 
-// Dynamic query with parameters
-function useUsersByStatus(status: string) {
+// With parameters
+export const useUsersByStatus = (driveId: string, status: string) => {
   return useTypedQuery(
+    driveId,
     (db, params) => {
       return db
         .selectFrom('users')
@@ -141,41 +144,32 @@ function useUsersByStatus(status: string) {
     },
     { status }
   );
-}
+};
 ```
 
 ### Parameters
 
-The returned hook has two overloads:
-
-**Static queries (no parameters):**
-- `queryCallback: (db: EnhancedKysely<Schema>) => QueryCallbackReturnType` - Function that receives the database instance and returns a query
-
-**Parameterized queries:**
-- `queryCallback: (db: EnhancedKysely<Schema>, parameters: TParams) => QueryCallbackReturnType` - Function that receives the database instance and parameters
-- `parameters: TParams` - Parameters for the query (automatically memoized)
+The returned hook accepts:
+- `driveId`: The ID of the drive
+- `queryCallback`: Function that receives the database instance and optional parameters
+- `parameters`: Optional parameters for the query
 
 ### Return Value
 
 ```typescript
 {
-  isLoading: boolean;    // True while query is loading
-  error: Error | null;   // Any error that occurred
-  result: LiveQueryResults<T> | null; // Query results with real-time updates
+  isLoading: boolean;      // True while loading or retrying
+  error: Error | null;     // Any error that occurred
+  result: LiveQueryResults<T> | null;  // Query results with live updates
 }
 ```
 
 ### Notes / Caveats
 
-- Parameters are automatically memoized using deep comparison
-- Queries update in real-time when the database changes
-- The callback must return an object with `sql` and optional `parameters` properties
-- Use `.compile()` on Kysely queries to get the required format
-
-### Related Hooks
-
-- [`useOperationalStore`](#useoperationalstore) - For direct database access
-- [`useOperationalQuery`](#useoperationalquery) - Lower-level query hook
+- Create one `useTypedQuery` hook per processor
+- The hook includes automatic retry logic for common errors
+- Parameters are automatically memoized
+- Queries are live and will update automatically when data changes
 
 </details>
 
@@ -246,8 +240,8 @@ function DatabaseOperations() {
 
 ### Related Hooks
 
-- [`createProcessorQuery`](#createProcessorQuery) - For optimized queries
-- [`useOperationalQuery`](#useoperationalquery) - For manual query control
+- [`createProcessorQuery`](#1-createprocessorquery) - For optimized queries
+- [`useOperationalQuery`](#3-useoperationalquery) - For manual query control
 
 </details>
 
@@ -314,8 +308,8 @@ function UserCount() {
 
 ### Related Hooks
 
-- [`createProcessorQuery`](#createProcessorQuery) - Recommended higher-level API
-- [`useOperationalStore`](#useoperationalstore) - For direct database access
+- [`createProcessorQuery`](#1-createprocessorquery) - Recommended higher-level API
+- [`useOperationalStore`](#2-useoperationalstore) - For direct database access
 
 </details>
 

package/docs/academy/04-APIReferences/05-PHDocumentMigrationGuide.md

@@ -1,12 +1,12 @@
-# PHDocument Migration Guide (v3.3.0)
+# PHDocument Migration Guide
 
 :::tip
-This guide covers the **breaking changes** introduced in Powerhouse v3.3.0 related to PHDocument structure changes. If you're upgrading from v3.2.0 or earlier, **this migration is required** and document models must be regenerated.
+This guide covers the **breaking changes** introduced in Powerhouse v4.0.0 related to PHDocument structure changes. If you're upgrading from v3.2.0 or earlier, **this migration is required** and document models must be regenerated.
 :::
 
 ## Overview
 
-Version 3.3.0 introduced a significant refactor of the `PHDocument` structure that consolidates document metadata into a `header` field. This change enables signed and unsigned documents with cryptographic verification capabilities, but requires updating all code that accesses document properties.
+Version 4.0.0 introduced a significant refactor of the `PHDocument` structure that consolidates document metadata into a `header` field. This change enables signed and unsigned documents with cryptographic verification capabilities, but requires updating all code that accesses document properties.
 
 ## What Changed
 
@@ -28,7 +28,7 @@ const document = {
 }
 ```
 
-**After (v3.3.0):**
+**After (v4.0.0):**
 ```javascript
 const document = {
   header: {
@@ -328,11 +328,10 @@ describe('Document Migration', () => {
 
 ## Related Documentation
 
-- [PHDocument Architecture](../05-Architecture/PHDocument.md)
-- [Document Model Creation](../02-MasteryTrack/DocumentModelCreation/WhatIsADocumentModel.md)
-- [GraphQL API Reference](./02-ReactorAPI.md)
-- [React Hooks](./01-ReactHooks.md)
+- [PHDocument Architecture](/academy/Architecture/PowerhouseArchitecture)
+- [Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel)
+- [React Hooks](/academy/APIReferences/ReactHooks)
 
 ---
 
-*This migration guide covers the major changes in v3.3.0. For additional technical details, refer to the [RELEASE-NOTES.md](https://github.com/powerhouse-dao/powerhouse/blob/main/RELEASE-NOTES.md) in the main repository.* 
+*This migration guide covers the major changes in v4.0.0. For additional technical details, refer to the [RELEASE-NOTES.md](https://github.com/powerhouse-dao/powerhouse/blob/main/RELEASE-NOTES.md) in the main repository.* 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "3.3.0-dev.13",
+  "version": "3.3.0-dev.15",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/docs/academy/02-MasteryTrack/04-WorkWithData/05-AnalyticsProcessorTutorial/05-AnalyticsTutorial

@@ -1,4 +0,0 @@
-## Start the Reactor & Connect
-
-## Use the analytics modal / Explain the modal
-