@powerhousedao/academy 4.1.0-dev.2 → 4.1.0-dev.20

package/CHANGELOG.md

@@ -1,3 +1,143 @@
+## 4.1.0-dev.20 (2025-08-15)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 4.1.0-dev.19 (2025-08-14)
+
+### 🩹 Fixes
+
+- **academy:** subgraph example ([ae3e24458](https://github.com/powerhouse-inc/powerhouse/commit/ae3e24458))
+
+### ❤️ Thank You
+
+- Frank
+
+## 4.1.0-dev.18 (2025-08-14)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 4.1.0-dev.17 (2025-08-12)
+
+### 🚀 Features
+
+- refactor vetra command and remove vetra deps in connect and reactor ([#1753](https://github.com/powerhouse-inc/powerhouse/pull/1753))
+
+### ❤️ Thank You
+
+- Guillermo Puente Sandoval @gpuente
+
+## 4.1.0-dev.16 (2025-08-12)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 4.1.0-dev.15 (2025-08-12)
+
+### 🚀 Features
+
+- **reactor-mcp,reactor-api,reactor-local,switchboard,ph-cli:** run mcp on express app ([d51fa590e](https://github.com/powerhouse-inc/powerhouse/commit/d51fa590e))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+
+## 4.1.0-dev.14 (2025-08-11)
+
+### 🚀 Features
+
+- update document engineering dep ([54dcee90d](https://github.com/powerhouse-inc/powerhouse/commit/54dcee90d))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+
+## 4.1.0-dev.13 (2025-08-09)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 4.1.0-dev.12 (2025-08-08)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 4.1.0-dev.11 (2025-08-07)
+
+### 🚀 Features
+
+- **switchboard,reactor-local,reactor-api:** moved vite loader to reactor-api package ([c84f0a2a3](https://github.com/powerhouse-inc/powerhouse/commit/c84f0a2a3))
+- vetra package documents and app integration ([0e4053302](https://github.com/powerhouse-inc/powerhouse/commit/0e4053302))
+- **vetra:** added vetra drive editor ([4ebafd143](https://github.com/powerhouse-inc/powerhouse/commit/4ebafd143))
+- **ph-cli:** added verbose option to vetra command ([7310ec06c](https://github.com/powerhouse-inc/powerhouse/commit/7310ec06c))
+- integrate package documents into reactor system ([939fe8e80](https://github.com/powerhouse-inc/powerhouse/commit/939fe8e80))
+- **connect:** integrate Vetra package documents and editors ([2ecb9bd15](https://github.com/powerhouse-inc/powerhouse/commit/2ecb9bd15))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+- Guillermo Puente @gpuente
+- Guillermo Puente Sandoval @gpuente
+
+## 4.1.0-dev.10 (2025-08-07)
+
+### 🚀 Features
+
+- **builder-tools,codegen,design-system,reactor-api:** updated document-engineering version ([e74068b43](https://github.com/powerhouse-inc/powerhouse/commit/e74068b43))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+
+## 4.1.0-dev.9 (2025-08-07)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 4.1.0-dev.8 (2025-08-06)
+
+### 🚀 Features
+
+- **switchboard,config,reactor-api:** handle auth in reactor-api ([f33c921ee](https://github.com/powerhouse-inc/powerhouse/commit/f33c921ee))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+
+## 4.1.0-dev.7 (2025-08-06)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 4.1.0-dev.6 (2025-08-06)
+
+### 🚀 Features
+
+- **reactor-mcp:** load local document models and reload when they change ([0408a017c](https://github.com/powerhouse-inc/powerhouse/commit/0408a017c))
+- **reactor-local,reactor-api,document-drive:** reload local document models when they change ([5d9af3951](https://github.com/powerhouse-inc/powerhouse/commit/5d9af3951))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+
+## 4.1.0-dev.5 (2025-08-05)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
+## 4.1.0-dev.4 (2025-08-02)
+
+### 🚀 Features
+
+- ts morph integration ([#1729](https://github.com/powerhouse-inc/powerhouse/pull/1729))
+
+### ❤️ Thank You
+
+- Guillermo Puente Sandoval @gpuente
+
+## 4.1.0-dev.3 (2025-08-01)
+
+### 🚀 Features
+
+- **reactor-mcp:** setup of modular reactor tools ([ceab98b08](https://github.com/powerhouse-inc/powerhouse/commit/ceab98b08))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+
 ## 4.1.0-dev.2 (2025-07-31)
 
 ### 🚀 Features

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

@@ -74,6 +74,29 @@ You have several options for styling your editor components:
 
 Choose the method or combination of methods that best suits your project needs and team preferences. Connect Studio (`ph connect`) will allow you to see your styles applied in real-time.
 
+:::warning  **Best practices for consistent reliable styles**
+
+In any package the styles are being generated through the styles.css file with the help of the tailwindcss/cli package. 
+
+**1. Centralize style imports**
+
+- Do not import styles directly in .tsx files.
+- This works in development mode but will not be picked up in static production builds.
+- Move all style imports into your main styles.css file.
+
+**2. Use file imports instead of URL imports**
+
+- @import url("...") → **Incorrect**, Ignored by tailwindcss/cli
+- @import "..." → **Correct**, resolves from local files or node_modules
+- Always prefer the file import syntax.
+
+**Using `ph install` includes package styles automatically**
+
+- When installing a package with `ph install` on any instance, package styles are automatically added to styles.css. This ensures production builds always include the required package styles.
+:::
+
+
+
 ### State management in editors
 
 When you build an editor in Powerhouse, your main editor component receives `EditorProps`. These props are crucial for interacting with the document:

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

@@ -29,41 +29,40 @@ A subgraph in Powerhouse is a **GraphQL-based modular data component** that exte
 
 
 
-```typescript title="Example of a context field"
-context: {
-  admin: async (session) => {
-    const admins = await operationalStore.get("admins");
-    return admins.includes(session.user);
-  }
-}
-```
+## Example: Implement a search subgraph based on data from the reactor
+
+In this example we implement a subgraph which allows to search through todo-list documents in a specific document drive. 
 
-## 1. How to generate a subgraph
+First we will generate the subgraph with the help of the ph cli, then we will define the GraphQL schema and implement the resolvers and finally we will start the reactor and execute a query through the GraphQL Gateway.
+
+### 1. Generate the subgraph
 
 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
+ph generate --subgraph search-todos
 ```
 
 ```bash title="Expected Output"
-Loaded templates: node_modules/@powerhousedao/codegen/dist/codegen/.hygen/templates
-       FORCED: ./subgraphs/to-do-list/index.ts
+Loaded templates: /projects/powerhouse/powerhouse/packages/codegen/dist/src/codegen/.hygen/templates
+       FORCED: ./subgraphs/search-todos/index.ts
      skipped: ./subgraphs/index.ts
       inject: ./subgraphs/index.ts
+
+Loaded templates: /projects/powerhouse/powerhouse/packages/codegen/dist/src/codegen/.hygen/templates
+       FORCED: ./subgraphs/search-todos/resolvers.ts
+       FORCED: ./subgraphs/search-todos/schema.ts
 ```
 
 ### What happened?
-1. A new subgraph was created in `./subgraphs/to-do-list/`
+1. A new subgraph was created in `./subgraphs/search-todos/`
 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, among those, one for the available document models in your Powerhouse project. 
+  > Registered /graphql/search-todos subgraph.
 
 ```
 Initializing Subgraph Manager...
@@ -73,345 +72,69 @@ Initializing Subgraph Manager...
 > Registered /d/:drive subgraph.
 > Updating router
 > Registered /graphql supergraph 
-> Registered /graphql/to-do-list subgraph. 
+> Registered /graphql/search-todos subgraph. 
 > Updating router
 > Registered /graphql supergraph 
   ➜  Reactor:   http://localhost:4001/d/powerhouse
 ```
 
-## 2. Building a to-do list subgraph
-
-Now that we've generated our subgraph, let's build a complete To-do List subgraph that extends the functionality of our To-do List document model. This subgraph will provide additional querying capabilities and demonstrate how subgraphs work with document models.
-
-### 2.1 Understanding the to-do list document model
-
-Before building our subgraph, let's recall the structure of our To-do List document model from the [DocumentModelCreation tutorial](/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema):
-
-```graphql
-type ToDoListState {
-  items: [ToDoItem!]!
-  stats: ToDoListStats!
-}
-
-type ToDoItem {
-  id: ID!
-  text: String!
-  checked: Boolean!
-}
-
-type ToDoListStats {
-  total: Int!
-  checked: Int!
-  unchecked: Int
-}
-```
-
-The document model has these operations:
-- `ADD_TODO_ITEM`: Adds a new to-do item
-- `UPDATE_TODO_ITEM`: Updates an existing to-do item
-- `DELETE_TODO_ITEM`: Deletes a to-do item
-
-### 2.2 Define the subgraph schema
+## 2. Building a search subgraph
 
-Now let's create a subgraph that provides enhanced querying capabilities for our To-do List documents. 
+Now that we've generated our subgraph its tome to define the GraphQL schema and implement the resolvers.
 
-**Step 1: Define the schema in `subgraphs/to-do-list/schema.ts` by creating the file:**
+**Step 1: Define the schema in `subgraphs/search-todos/schema.ts` by creating the file:**
 
 ```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!     # 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!          # Unique identifier
-    text: String!    # The task description
-    checked: Boolean! # Completion status
-  }
-}`
-```
-
-
-<details>
-<summary> #### Understanding resolvers </summary>
+import { gql } from "graphql-tag";
+import type { DocumentNode } from "graphql";
 
-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.
+export const schema: DocumentNode = gql`
+"""
+Subgraph definition
+"""
 
- When someone asks your system a question through GraphQL, the resolver:
-
-1. **Understands the request** - "The user 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
-
-</details>
-
-**Step 2: Create resolvers in `subgraphs/to-do-list/resolvers.ts`:**
-
-```typescript
-// subgraphs/to-do-list/resolvers.ts
-interface SubgraphInstance {
-  operationalStore: any;
+type Query {
+    searchTodos(driveId: String!, searchTerm: String!): [String!]!
 }
 
-export const createResolvers = (subgraphInstance: SubgraphInstance) => ({
-  Query: {
-    todoList: async () => {
-      const items = await subgraphInstance.operationalStore.getAll("todo_items");
-      const total = items.length;
-      const checked = items.filter((item: any) => item.checked).length;
-      const unchecked = total - checked;
-      
-      return {
-        total,
-        checked,
-        unchecked
-      };
-    },
-    
-    todoItems: async (parent: any, { checked }: any) => {
-      let query = subgraphInstance.operationalStore.select("*").from("todo_items");
-      
-      if (checked !== undefined) {
-        query = query.where("checked", checked);
-      }
-      
-      const items = await query.orderBy("created_at", "asc");
-      return items;
-    },
-    
-    todoItemsCount: async (parent: any, { checked }: any) => {
-      let query = subgraphInstance.operationalStore.count("* as count").from("todo_items");
-      
-      if (checked !== undefined) {
-        query = query.where("checked", checked);
-      }
-      
-      const result = await query.first();
-      return result?.count || 0;
-    }
-  }
-});
-```
-
-**Step 3: Implement the main class in `subgraphs/to-do-list/index.ts`:**
+`;
 
-```typescript
-// subgraphs/to-do-list/index.ts
-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", // Table name
-      (table: any) => {
-        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 new todo item creation
-    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}`);
-    }
-    
-    // Handle todo item updates (text changes, checking/unchecking)
-    if (event.type === "UPDATE_TODO_ITEM") {
-      const updateData: any = {
-        updated_at: new Date() // Always update the timestamp
-      };
-      
-      // Only update fields that were actually changed
-      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}`);
-    }
-    
-    // Handle todo item deletion
-    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}`);
-    }
-  }
-}
 ```
 
-### 2.3 Understanding the implementation
-
-**What this multi-file approach provides:**
-
-1. **Schema separation** (`schema.ts`): Clean GraphQL type definitions
-2. **Resolver isolation** (`resolvers.ts`): Business logic separated from structure  
-3. **Main orchestration** (`index.ts`): Combines everything and handles lifecycle methods
-
-**Key features implemented:**
-- A `todo_items` operational table to store individual to-do items
-- Fields that match our document model structure
-- Timestamps for tracking when items were created and updated
-- 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 Understanding the document model event integration
-
-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.
-
-**How the existing processor integration works:**
+**Step 2: Create resolvers in `subgraphs/search-todos/resolvers.ts`:**
 
-The `process` method in our `index.ts` file handles three types of document model events:
-
-**1. Adding new todo items:**
-```typescript
-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;
-  
-  await this.operationalStore.update("todo_items")
-    .where("id", event.input.id)
-    .update(updateData);
-}
-```
+// subgraphs/search-todos/resolvers.ts
+import { type Subgraph } from "@powerhousedao/reactor-api";
+import { type ToDoListDocument } from "document-models/to-do-list/index.js";
+
+export const getResolvers = (subgraph: Subgraph) => {
+  const reactor = subgraph.reactor;
+
+  return {
+    Query: {
+      searchTodos: async (parent: unknown, args: { driveId: string, searchTerm: string }) => {
+        const documents = await reactor.getDocuments(args.driveId);
+        const todoItems: string[] = [];
+        for (const docId of documents) {
+          const doc: ToDoListDocument = await reactor.getDocument(docId);
+          if (doc.header.documentType !== "powerhouse/todolist") {
+            continue;
+          }
+
+          const amountEntries = doc.state.global.items.filter(e => e.text.includes(args.searchTerm)).length;
+          if (amountEntries > 0) {
+            todoItems.push(docId);
+          }
+        }
+        return todoItems;
+      },
+    },
+  };
+};
 
-**3. Deleting items:**
-```typescript
-if (event.type === "DELETE_TODO_ITEM") {
-  await this.operationalStore.delete("todo_items")
-    .where("id", event.input.id);
-}
 ```
 
-**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
-
-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
 
@@ -421,21 +144,21 @@ To activate the subgraph, run:
 ```bash
 ph reactor
 ```
-Or, for full system startup:
-
-```bash title="Start the Reactor & Connect in Studio or Locally"
-ph dev 
-```
 
 You should see the subgraph being registered in the console output:
 ```
-> Registered /graphql/to-do-list subgraph.
+> Registered /graphql/search-todos subgraph.
 ```
 
 ### 3.2. Create some test data
 Before testing queries, let's create some To-do List documents with test data:
 
-1. Open Connect at `http://localhost:3001` in another terminal
+1. Start Connect 
+```bash
+ph connect
+```
+
+1. Open Connect at `http://localhost:3000` in the browser
 2. Add the 'remote' drive that is running locally via the (+) 'Add Drive' button. Add 'http://localhost:4001/d/powerhouse'
 3. Create a new To-do List document
 4. Add some test items:
@@ -447,92 +170,21 @@ Before testing queries, let's create some To-do List documents with test data:
 Open your browser and go to:
 
 ```bash
-http://localhost:4001/graphql/to-do-list
+http://localhost:4001/graphql
 ```
 
 ### 3.4. Test the queries
 
-**Query 1: Get To-do List statistics**
+**Query 1: Search for Todos **
 ```graphql
 query {
-  todoList {
-    total
-    checked
-    unchecked
-  }
+  searchTodos(driveId: "powerhouse", searchTerm: "Test")
 }
 ```
 
-**Query 2: Get all to-do items**
-```graphql
-query {
-  todoItems {
-    id
-    text
-    checked
-  }
-}
-```
+You should get a list of the document Ids which contain the search term "Test".
 
-**Query 3: Get only unchecked items**
-```graphql
-query {
-  todoItems(checked: false) {
-    id
-    text
-    checked
-  }
-}
-```
-
-**Query 4: Get count of completed items**
-```graphql
-query {
-  todoItemsCount(checked: true)
-}
-```
-
-### 3.5. Expected responses
-
-**For the statistics query:**
-```json
-{
-  "data": {
-    "todoList": {
-      "total": 3,
-      "checked": 1,
-      "unchecked": 2
-    }
-  }
-}
-```
-
-**For the items query:**
-```json
-{
-  "data": {
-    "todoItems": [
-      {
-        "id": "item-1",
-        "text": "Learn about subgraphs",
-        "checked": false
-      },
-      {
-        "id": "item-2",
-        "text": "Build a To-do List subgraph",
-        "checked": true
-      },
-      {
-        "id": "item-3",
-        "text": "Test the subgraph",
-        "checked": false
-      }
-    ]
-  }
-}
-```
-
-### 3.6. Test real-time updates
+### 3.5. Test real-time updates
 
 To verify that your subgraph stays synchronized with document changes:
 
@@ -544,9 +196,10 @@ To verify that your subgraph stays synchronized with document changes:
 
 This demonstrates the real-time synchronization between the document model and the subgraph through event processing.
 
-## 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.
+## 4. Working with the GraphQL Gateway
+
+The GraphQL Gateway 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
 

package/docs/academy/02-MasteryTrack/04-WorkWithData/05-RelationalDbProcessor.md

@@ -268,19 +268,41 @@ A subgraph is a GraphQL schema that exposes your processed data to clients. It:
 
 ### Configure the Subgraph
 
-Open `./subgraphs/todo/index.ts` and configure the resolvers:
+Open `./subgraphs/todo/schema.ts`and configure the schema:
 
 ```ts
-import { Subgraph } from "@powerhousedao/reactor-api";
 import { gql } from "graphql-tag";
+import type { DocumentNode } from "graphql";
+
+export const schema: DocumentNode = gql`
+
+# Define the structure of a todo item as returned by GraphQL
+type ToDoListEntry {
+  task: String!     # The task description (! means required/non-null)
+  status: Boolean!  # The completion status (true = done, false = pending)
+}
+
+# Define available queries
+type Query {
+  todos(driveId: ID!): [ToDoListEntry]  # Get array of todos for a specific drive
+}
+`;
+
+```
+
+Open `./subgraphs/todo/resolvers.ts` and configure the resolvers:
+
+```ts
+// subgraphs/search-todos/resolvers.ts
+import { type Subgraph } from "@powerhousedao/reactor-api";
+import { type ToDoListDocument } from "document-models/to-do-list/index.js";
 import { TodoIndexerProcessor } from "../../processors/todo-indexer/index.js";
 
-export class TodoSubgraph extends Subgraph {
-  // Human-readable name for this subgraph
-  name = "Todos";
+export const getResolvers = (subgraph: Subgraph) => {
+  const reactor = subgraph.reactor;
+  const relationalDb = subgraph.relationalDb;
 
-  // GraphQL resolvers - functions that fetch data for each field
-  resolvers = {
+  return {
     Query: {
       todos: {
         // Resolver function for the "todos" query
@@ -288,7 +310,7 @@ export class TodoSubgraph extends Subgraph {
         resolve: async (_: any, args: {driveId: string}) => {
           // Query the database using the processor's static query method
           // This gives us access to the namespaced database for the specific drive
-          const todos = await TodoIndexerProcessor.query(args.driveId, this.relationalDb)
+          const todos = await TodoIndexerProcessor.query(args.driveId, relationalDb)
             .selectFrom("todo")        // Select from the "todo" table
             .selectAll()              // Get all columns
             .execute();               // Execute the query
@@ -302,29 +324,10 @@ export class TodoSubgraph extends Subgraph {
       },
     },
   };
-
-  // GraphQL schema definition using GraphQL Schema Definition Language (SDL)
-  typeDefs = gql`
-
-  # Define the structure of a todo item as returned by GraphQL
-  type ToDoListEntry {
-    task: String!     # The task description (! means required/non-null)
-    status: Boolean!  # The completion status (true = done, false = pending)
-  }
-
-  # Define available queries
-  type Query {
-    todos(driveId: ID!): [ToDoListEntry]  # Get array of todos for a specific drive
-  }
-  `;
-
-  // Cleanup method called when the subgraph disconnects
-  async onDisconnect() {
-    // Add any cleanup logic here if needed
-  }
-}
+};
 ```
 
+
 ## Now query the data via the supergraph.
 
 **Understanding the Supergraph**

package/docs/academy/04-APIReferences/00-PowerhouseCLI.md

@@ -709,42 +709,50 @@ Notes:
 
 ```
 Command Overview:
-  The vetra command sets up a complete Vetra development environment for working with Vetra projects.
-  It starts three coordinated services: a Vetra Switchboard, a Local Reactor, and Connect Studio,
-  enabling full document collaboration and real-time processing with a "Vetra" drive.
+  The vetra command sets up a Vetra development environment for working with Vetra projects.
+  It starts a Vetra Switchboard and optionally Connect Studio, enabling document collaboration 
+  and real-time processing with a "Vetra" drive or connection to remote drives.
 
   This command:
   1. Starts a Vetra Switchboard with a "Vetra" drive for document storage
-  2. Starts a Local Reactor that connects to the Vetra Switchboard as a remote drive
-  3. Starts Connect Studio pointing to the Local Reactor for user interaction
-  4. Enables real-time updates, collaboration, and code generation across all services
+  2. Optionally connects to remote drives instead of creating a local drive
+  3. Starts Connect Studio pointing to the Switchboard for user interaction (unless disabled)
+  4. Enables real-time updates, collaboration, and code generation
 
 Options:
-  --generate               Generate code automatically when document models are updated.
-                          This keeps your code in sync with model changes across all services.
+  --logs                     Enable verbose logging for all services. This provides detailed
+                            output from Switchboard and Connect during startup and operation.
                         
-  --switchboard-port <port> Specify the port to use for the Vetra Switchboard service.
-                          Default is 4001. The Switchboard handles document storage.
+  --switchboard-port <port>  Specify the port to use for the Vetra Switchboard service.
+                            Default is 4001. The Switchboard handles document storage.
                         
-  --reactor-port <port>    Specify the port to use for the Local Reactor service.
-                          Default is 4002. The Reactor provides the main API and connects to switchboard.
+  --connect-port <port>      Specify the port to use for Connect Studio.
+                            Default is 3000. Connect provides the user interface.
                         
-  --https-key-file <path>  Path to the SSL key file if using HTTPS for secure connections.
+  --https-key-file <path>    Path to the SSL key file if using HTTPS for secure connections.
                         
-  --https-cert-file <path> Path to the SSL certificate file if using HTTPS.
+  --https-cert-file <path>   Path to the SSL certificate file if using HTTPS.
                         
-  --config-file <path>     Path to the powerhouse.config.js file. This allows you to
-                          customize the behavior of all services in the Vetra development environment.
+  --config-file <path>       Path to the powerhouse.config.js file. This allows you to
+                            customize the behavior of the Vetra development environment.
                         
-  -w, --watch              Watch for local changes to document models and processors,
-                          and automatically update both the Switchboard and Reactor accordingly.
+  -w, --watch                Watch for local changes to document models and processors,
+                            and automatically update the Switchboard accordingly.
+                        
+  --remote-drive <url>       URL of remote drive to connect to. When specified, the switchboard
+                            connects to this remote drive instead of creating a local Vetra drive.
+                        
+  --disable-connect          Skip Connect initialization (only start switchboard and reactor).
+                            Use this when you only need the backend services running.
 
 Examples:
-  $ ph vetra                                           # Start complete Vetra environment with defaults
-  $ ph vetra --generate                                # Auto-generate code on model changes
-  $ ph vetra --switchboard-port 5000 --reactor-port 5001  # Use custom ports
-  $ ph vetra --config-file custom.powerhouse.config.js # Use custom configuration
-  $ ph vetra --watch                                   # Watch for changes and auto-update
+  $ ph vetra                                              # Start Vetra environment with defaults
+  $ ph vetra --switchboard-port 5000 --connect-port 3001 # Use custom ports
+  $ ph vetra --config-file custom.powerhouse.config.js   # Use custom configuration
+  $ ph vetra --watch                                      # Watch for changes and auto-update
+  $ ph vetra --logs                                       # Enable detailed logging
+  $ ph vetra --remote-drive http://localhost:4001/d/docs  # Connect to remote drive
+  $ ph vetra --disable-connect                            # Start only backend services
   $ ph vetra --https-key-file key.pem --https-cert-file cert.pem  # Use HTTPS
 ```
 

package/docs/academy/TUTORIAL_VERIFICATION_ARCHITECTURE

@@ -0,0 +1,325 @@
+# Tutorial Verification System - Technical Architecture
+
+## Overview
+
+This document outlines the technical architecture for an automated tutorial verification system that ensures the Powerhouse Academy tutorials remain accurate and functional as the codebase evolves.
+
+## System Architecture
+
+### 1. Test Execution Environment
+
+```
+┌─────────────────────────────────────────┐
+│  GitHub Actions Runner (Ubuntu)         │
+│  ┌─────────────────────────────────────┐ │
+│  │  Isolated Docker Container          │ │
+│  │  ├── Node.js 22                    │ │
+│  │  ├── pnpm                          │ │
+│  │  ├── Powerhouse CLI (ph-cli)       │ │
+│  │  ├── Playwright browsers           │ │
+│  │  └── Temporary filesystem          │ │
+│  └─────────────────────────────────────┘ │
+└─────────────────────────────────────────┘
+```
+
+**Execution Environments:**
+- **Development**: Local machine (`pnpm test:e2e`)
+- **CI/CD**: GitHub Actions runners (automatically on PRs)
+- **Scheduled**: Nightly runs to catch regressions
+
+### 2. Tutorial Agent Architecture
+
+The "agent" is a test orchestrator that processes tutorials through a structured workflow:
+
+```typescript
+// packages/tutorial-verifier/src/tutorial-agent.ts
+class TutorialAgent {
+  async verifyTutorial(tutorialPath: string) {
+    // 1. Parse tutorial markdown
+    const steps = await this.parseTutorialSteps(tutorialPath);
+    
+    // 2. Create isolated environment
+    const sandbox = await this.createSandbox();
+    
+    // 3. Execute each step sequentially
+    for (const step of steps) {
+      await this.executeStep(step, sandbox);
+      await this.verifyStepOutcome(step, sandbox);
+    }
+    
+    // 4. Generate report
+    return this.generateReport();
+  }
+}
+```
+
+## Component Integration
+
+### 3. E2E Test Framework Integration
+
+**Extends existing Playwright E2E infrastructure:**
+
+```typescript
+// test/connect-e2e/tests/tutorial-get-started.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('Tutorial: Create new to-do list document', async ({ page }) => {
+  const agent = new TutorialAgent();
+  
+  // Phase 1: CLI Commands (no browser needed)
+  await agent.executeCliStep('ph init my-todo-project');
+  await agent.verifyFileExists('my-todo-project/package.json');
+  
+  // Phase 2: Browser Automation (uses Playwright)
+  await agent.startConnect(); // Starts ph connect in background
+  await page.goto('http://localhost:3000');
+  
+  // Phase 3: UI Verification (Playwright E2E)
+  await page.click('text=Local Drive');
+  await page.click('button:has-text("DocumentModel")');
+  await expect(page.locator('text=Document Model Editor')).toBeVisible();
+  
+  // Phase 4: Cleanup
+  await agent.cleanup();
+});
+```
+
+### 4. Playwright Browser Automation
+
+**UI automation for Connect Studio interactions:**
+
+```typescript
+// UI automation for Connect Studio
+class ConnectUIAgent {
+  constructor(private page: Page) {}
+  
+  async createDocumentModel(name: string) {
+    // Navigate to document creation
+    await this.page.click('button:has-text("DocumentModel")');
+    
+    // Fill in model details
+    await this.page.fill('input[placeholder="Document Name"]', name);
+    await this.page.fill('input[placeholder="Document Type"]', `powerhouse/${name.toLowerCase()}`);
+    
+    // Define schema in code editor
+    await this.page.click('.monaco-editor');
+    await this.page.keyboard.type(`
+      type ${name}State {
+        items: [TodoItem!]!
+      }
+    `);
+    
+    // Save and verify
+    await this.page.click('button:has-text("Save")');
+    await expect(this.page.locator(`text=${name}.phdm.zip`)).toBeVisible();
+  }
+}
+```
+
+## Execution Flow
+
+### 5. Tutorial Processing Pipeline
+
+```
+Tutorial Markdown File
+        ↓
+   [Tutorial Parser]
+        ↓
+   ┌─────────────────┐
+   │  Execution Steps │
+   ├─────────────────┤
+   │ 1. CLI Commands │ ← Uses child_process.spawn()
+   │ 2. File Checks  │ ← Uses fs.existsSync()
+   │ 3. UI Actions   │ ← Uses Playwright page.click()
+   │ 4. Verifications│ ← Custom assertion logic
+   └─────────────────┘
+        ↓
+   [Report Generator]
+        ↓
+   Test Results + Screenshots
+```
+
+### 6. Step-by-Step Processing Example
+
+**Tutorial Markdown:**
+```markdown
+## Quick start
+Create a new Powerhouse project with a single command:
+```bash
+ph init
+```
+
+Then start Connect:
+```bash
+ph connect
+```
+
+Navigate to http://localhost:3000 and click on "Local Drive".
+```
+
+**Agent Processing:**
+
+```typescript
+// 1. Tutorial Parser extracts executable steps
+const steps = [
+  { type: 'cli', command: 'ph init', expectedFiles: ['package.json'] },
+  { type: 'cli', command: 'ph connect', background: true },
+  { type: 'browser', action: 'navigate', url: 'http://localhost:3000' },
+  { type: 'browser', action: 'click', selector: 'text=Local Drive' }
+];
+
+// 2. Agent executes each step
+for (const step of steps) {
+  switch (step.type) {
+    case 'cli':
+      const result = execSync(step.command);
+      if (step.expectedFiles) {
+        for (const file of step.expectedFiles) {
+          assert(existsSync(file), `Expected file ${file} not found`);
+        }
+      }
+      break;
+      
+    case 'browser':
+      if (step.action === 'navigate') {
+        await page.goto(step.url);
+      } else if (step.action === 'click') {
+        await page.click(step.selector);
+      }
+      break;
+  }
+}
+```
+
+## Deployment Architecture
+
+### 7. Runtime Environment Distribution
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  GitHub Actions Runner                                  │
+│                                                         │
+│  ┌─────────────────┐  ┌─────────────────────────────────┐ │
+│  │ Tutorial Agent  │  │  Sandbox Environment           │ │
+│  │ (Node.js)       │  │                                 │ │
+│  │                 │  │  ┌─────────────┐               │ │
+│  │ • Parse MD      │  │  │ ph connect  │ :3000         │ │
+│  │ • Execute CLI   │  │  └─────────────┘               │ │
+│  │ • Control tests │  │                                 │ │
+│  └─────────────────┘  │  ┌─────────────┐               │ │
+│                       │  │ Playwright  │               │ │
+│  ┌─────────────────┐  │  │ Browser     │               │ │
+│  │ Report Gen      │  │  └─────────────┘               │ │
+│  │ • Screenshots   │  │                                 │ │
+│  │ • Error logs    │  │  /tmp/tutorial-test-xyz/        │ │
+│  │ • Success rates │  │  ├── my-todo-project/           │ │
+│  └─────────────────┘  │  │   ├── package.json          │ │
+│                       │  │   └── ...                   │ │
+│                       └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 8. Integration with Existing Test Suite
+
+**File Structure Extension:**
+
+```
+Your Current E2E Tests:
+test/connect-e2e/tests/
+├── todo-document.spec.ts     ← Existing
+├── drive.spec.ts            ← Existing
+└── app.spec.ts              ← Existing
+
+Added Tutorial Tests:
+test/connect-e2e/tests/tutorials/
+├── get-started.spec.ts      ← New: Tests "Get Started" tutorial
+├── mastery-track.spec.ts    ← New: Tests "Mastery Track" tutorials
+└── cookbook.spec.ts         ← New: Tests "Cookbook" recipes
+```
+
+**No changes to existing code** - just additional test files that run alongside current tests.
+
+## Performance & Timing
+
+### 9. Execution Timeline
+
+```
+0s    │ Start test
+2s    │ ├── Parse tutorial markdown
+4s    │ ├── Create temp directory
+6s    │ ├── Run 'ph init'
+15s   │ ├── Verify project structure  
+20s   │ ├── Start 'ph connect' (background)
+35s   │ ├── Wait for Connect to be ready
+40s   │ ├── Launch Playwright browser
+45s   │ ├── Navigate to localhost:3000
+50s   │ ├── Perform UI interactions
+55s   │ ├── Verify expected elements
+60s   │ ├── Take screenshots
+65s   │ ├── Cleanup (kill processes, delete files)
+70s   │ └── Generate report
+```
+
+## Implementation Phases
+
+### Phase 1: Proof of Concept (1-2 days)
+- Single tutorial verification (Get Started)
+- Basic CLI command execution
+- Simple file existence checks
+- Integration with existing Playwright setup
+
+### Phase 2: Core Features (1-2 weeks)
+- Tutorial markdown parser
+- Comprehensive step execution engine
+- Browser automation for Connect Studio
+- Error reporting and screenshots
+
+### Phase 3: Advanced Features (2-3 weeks)
+- Multiple tutorial support
+- Parallel execution
+- Detailed reporting dashboard
+- Integration with CI/CD pipeline
+
+### Phase 4: Intelligence Layer (2-3 weeks)
+- Failure pattern analysis
+- Automated suggestion generation
+- Historical trend tracking
+- LLM-powered issue diagnosis
+
+## Key Technical Decisions
+
+### Technology Stack
+- **Test Framework**: Playwright (existing)
+- **Runtime**: Node.js 22 + TypeScript
+- **CLI Execution**: child_process.spawn()
+- **File Operations**: Node.js fs module
+- **Browser Automation**: Playwright
+- **CI/CD**: GitHub Actions (existing)
+
+### Design Principles
+- **Isolation**: Each test runs in isolated environment
+- **Repeatability**: Tests can run multiple times with same results
+- **Extensibility**: Easy to add new tutorials
+- **Integration**: Builds on existing infrastructure
+- **Cleanup**: Automatic resource cleanup after tests
+
+## Success Metrics
+
+- **Tutorial Success Rate**: % of tutorials that pass verification
+- **Time to Detection**: How quickly outdated tutorials are identified
+- **False Positive Rate**: % of failures due to test issues vs actual problems
+- **Coverage**: Number of tutorial steps automatically verified
+- **Developer Confidence**: Reduced manual testing effort
+
+## Risk Mitigation
+
+### Technical Risks
+- **Flaky Tests**: Use retry mechanisms and wait strategies
+- **Environment Dependencies**: Containerized execution environments
+- **Resource Cleanup**: Comprehensive cleanup in finally blocks
+- **Process Management**: Proper process lifecycle management
+
+### Operational Risks
+- **Maintenance Overhead**: Gradual rollout with proven patterns
+- **CI/CD Load**: Efficient test execution and parallel processing
+- **Team Adoption**: Clear documentation and training materials 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "4.1.0-dev.2",
+  "version": "4.1.0-dev.20",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",