@powerhousedao/academy 4.1.0-dev.58 → 4.1.0-dev.60

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+## 4.1.0-dev.60 (2025-10-08)
+
+### 🚀 Features
+
+- **vetra:** added read model to fetch vetra packages ([23c55364d](https://github.com/powerhouse-inc/powerhouse/commit/23c55364d))
+- **monorepo:** use latest versions of react related deps ([#1905](https://github.com/powerhouse-inc/powerhouse/pull/1905))
+- **monorepo:** remove global storybook installs ([#1903](https://github.com/powerhouse-inc/powerhouse/pull/1903))
+- **monorepo:** update to react 19 ([#1902](https://github.com/powerhouse-inc/powerhouse/pull/1902))
+- **vetra:** enabled HMR in dev mode ([8cf19757e](https://github.com/powerhouse-inc/powerhouse/commit/8cf19757e))
+- **vetra:** new connect build setup on vetra ([8dd11a849](https://github.com/powerhouse-inc/powerhouse/commit/8dd11a849))
+- **monorepo:** revert package versions ([8a1a02628](https://github.com/powerhouse-inc/powerhouse/commit/8a1a02628))
+- **monorepo:** update eslint config ([ac97af97d](https://github.com/powerhouse-inc/powerhouse/commit/ac97af97d))
+- adding feature flags to reactor-mcp ([fe4f2f683](https://github.com/powerhouse-inc/powerhouse/commit/fe4f2f683))
+- stubbing out feature flag + reactor setup in connect and deleting unused code in reactor-browser ([793bbd7af](https://github.com/powerhouse-inc/powerhouse/commit/793bbd7af))
+- syncing feature flag behavior between switchboard and reactor-local ([e45dc2bf7](https://github.com/powerhouse-inc/powerhouse/commit/e45dc2bf7))
+- added initial pieces of the kysely operation store implementation ([3fbece162](https://github.com/powerhouse-inc/powerhouse/commit/3fbece162))
+- **connect,builder-tools:** build rework ([#1871](https://github.com/powerhouse-inc/powerhouse/pull/1871))
+- **codegen:** updated editor boilerplate with document state and example setName dispatch ([3e7c51cc3](https://github.com/powerhouse-inc/powerhouse/commit/3e7c51cc3))
+- restructure document model to avoid circular imports ([#1874](https://github.com/powerhouse-inc/powerhouse/pull/1874))
+- added watch-packages option to vetra command and disabled dynamic package loading by default ([#1875](https://github.com/powerhouse-inc/powerhouse/pull/1875))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+- Benjamin Jordan (@thegoldenmule)
+- Frank
+- Guillermo Puente @gpuente
+- Guillermo Puente Sandoval @gpuente
+- Ryan Wolhuter @ryanwolhuter
+- ryanwolhuter @ryanwolhuter
+
+## 4.1.0-dev.59 (2025-09-24)
+
+### 🚀 Features
+
+- **monorepo:** rename tsc to tsc:build ([c1385418b](https://github.com/powerhouse-inc/powerhouse/commit/c1385418b))
+
+### 🩹 Fixes
+
+- **builder-tools:** declare @storybook/preview-api dependency ([705ac8da1](https://github.com/powerhouse-inc/powerhouse/commit/705ac8da1))
+- lots of type fixes for modules ([8f4cf02fe](https://github.com/powerhouse-inc/powerhouse/commit/8f4cf02fe))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+- Benjamin Jordan (@thegoldenmule)
+- ryanwolhuter @ryanwolhuter
+
 ## 4.1.0-dev.58 (2025-09-18)
 
 ### 🚀 Features

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

@@ -3,7 +3,7 @@
 ## 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?
-We will show you how to install the Powerhouse command-line tool `ph-cmd` and then use it to install a pre-built demo package with a document models, an editor and a drive-app.
+We will show you how to install the Powerhouse command-line tool `ph-cmd` and then use it to install a pre-built demo package containing a document model, an editor, and a drive app.
 
 ## Step 1: Install the Powerhouse CLI
 
@@ -90,7 +90,7 @@ Click the returned localhost URL and you should see Connect Studio appear in you
   <figcaption>The Powerhouse Connect Studio interface.</figcaption>
 </figure>
 
-When you move to the settingswheel in the bottom right corner you'll get access to the **Package Manager**.
+When you click the settings wheel in the bottom right corner, you'll get access to the **Package Manager**.
 Here, you'll see that you've installed the `@powerhousedao/todo-demo-package`, which contains not only a **Document Model** and its accompanying editor but also a **Drive App** specific to the to-do document model.
 
 <figure className="image-container">
@@ -130,15 +130,19 @@ Now move into the drive you've just created:
 - 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
 
+This is an example of the **usefulness and impact 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).
+
 <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>
+  <figcaption>A list of todos 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.
+A key feature of 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
@@ -146,9 +150,7 @@ A key feature you get with Connect is the **Operations History**. Every change t
     alt="Operations History Button"
   />
   <figcaption>
-    {" "}
-    You can find the button to visit the operations history in the document
-    model toolbar{" "}
+You can find the button to visit the operations history in the document model toolbar
   </figcaption>
 </figure>
 
@@ -165,8 +167,6 @@ A key feature you get with Connect is the **Operations History**. Every change t
 
 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.
@@ -175,7 +175,7 @@ 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.
 :::
 
-### 5.1 Click the renown icon and connect your eth identity
+### 5.1 Click the renown icon and connect your Ethereum 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.
 

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

@@ -3,8 +3,10 @@
 ## Overview
 
 This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **To-do List**.  
-A Powerhouse project primarily consists of a document model and its editor.  
-For this purpose, you'll be using Connect, our use-centric collaboration tool, locally, known as Connect in 'Studio mode'.
+A Powerhouse project primarily consists of a document model and its editor. 
+As your projects use-case expands you can add data-integrations or a specific drive-app as seen in the demo package. 
+
+For todays purpose, you'll be using Connect, our user-centric collaboration tool and Vetra Studio, the builder tooling through which developers can access and manage specifications of their project. 
 
 ## Prerequisites
 
@@ -53,6 +55,9 @@ Navigate to the newly created project directory:
     ```bash
     cd getting-started
     ```
+
+## Develop a single document model in Connect
+
 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:
 
@@ -79,6 +84,10 @@ Clear the storage of your localhost application as it might has an old session c
 
 If you've followed the steps correctly, you'll have an empty document where you can define the **'Document Specifications'**.
 
+## Develop a package in Vetra Studio
+
+
+
 ## Up next
 
 In the next tutorials, you will learn how to specify, add code and build an editor for your document model and export it to be used in your Powerhouse package.

package/docs/academy/01-GetStarted/{05-SpecDrivenAI.md → 05-VetraStudio.md}

@@ -1,12 +1,12 @@
-# Vetra Studio: Specification Driven AI 
+# Tool: Vetra Studio 
 
 This chapter introduces you to one of the most powerfull features of the Powerhouse development framework: Specification Driven AI-control.  In the **'Get Started'** chapter we've been making use of strict schema definition principles to communicate the intended use case of our reactive documents. 
 
-:::tip
+:::tip Important
 The **schema definition language**, is a not only a shared language that bridges the gap between developer, designer and analyst but also the gap between **builder and AI-agent**. 
 :::
 
-## Vision
+## Vision: Specification Driven AI
 
 At Powerhouse we are embracing the progress of AI assisted coding while unlocking the next level of AI control through **specification driven AI control**.
 
@@ -25,20 +25,37 @@ It allows developers to open packages (Git repositories with metadata) from a Ve
 
 This setup ensures that all necessary documentation and project requirements are in one accessible location, streamlining communication and agreement on requirements and operations. Additionally, **Vetra Studio** functions as the orchestration hub where you as a builder assemble all the necessary specifications for your intended use-case, software solution or package. For each of the different **modules** that together form a package a specification document can be created in **Vetra Studio**. 
 
-As Vetra Studio matures each of these specification documents will offer an interface by which you as a builder get more control over the modules that make up your package. These modules are divided in 3 categories. 
+As Vetra Studio matures each of these specification documents will offer an interface by which you as a builder get more control over the modules that make up your package. 
+
+<figure className="image-container">
+  <img
+    src={require("./images/Modules.png").default}
+    alt="Modules"
+  />
+  <figcaption>The list of available modules color coded according to the 3 categories.</figcaption>
+</figure>
+
+### Module Categories
 
-### 1. Document Models 
+#### 1. Document Models 
 - **Document model specification**: Defines the structure and operations of a document model using GraphQL SDL, ensuring consistent data management and processing.
 
-### 2. User Experiences
+#### 2. User Experiences
 - **Editor specification**: Outlines the interface and functionalities of a document model editor, allowing users to interact with and modify document data.
 - **Drive-app specification**: Specifies the UI and interactions for managing documents within a Drive, providing tailored views and functionalities.
 
-### 3. Data integrations
+#### 3. Data integrations
 - **Subgraph specification**: Details the connections and relationships within a subgraph, facilitating efficient data querying and manipulation.
 - **Codegen Processor Specification**: Describes the process for automatically generating code from document model specifications, ensuring alignment with intended architecture.
 - **RelationalDb Processor Specification**: Defines how relational databases are structured and queried, supporting efficient data management and retrieval.
 
+<figure className="image-container">
+  <img
+    src={require("./images/VetraStudioDrive.png").default}
+    alt="Vetra Studio Drive"
+  />
+  <figcaption>The Vetra Studio Drive, a builder app that collects all of the specification of a package.</figcaption>
+</figure>
 
 ## Vetra Studio Workflow
 
@@ -64,29 +81,31 @@ In standard mode:
 - Multiple changes are batched and processed together
 - Uses the latest document state for processing
 
-### 2. Launch Claude with MCP
+### 2. Launch Claude with Reactor-MCP
 
 Vetra Studio integrates deeply with Claude through MCP (Model Control Protocol). This is where AI comes into the mix and you get the chance to have greater control and direction over what your llm is coding for you. 
 
-#### 1. Start the MCP reactor:
+#### 1. Start the Reactor MCP:
 ```bash
 ph mcp
 ```
 
 #### 2. Verify MCP connection:
-- Check that the reactor MCP is available
-- Confirm Vetra Studio shows "Connected to reactor MCP"
+- Check that the Reactor MCP is available. 
+- Confirm Vetra Studio shows "Connected to Reactor MCP"
 
-#### Key MCP Features:
+-  To learn what is a [Reactor] itself read (apps/academy/docs/academy/Architecture/WorkingWithTheReactor)
+-  To learn more about the [Reactor MCP] read (apps/academy/docs/academy/GetStarted/ReactorMCP)
+
+#### Key Reactor MCP Features:
 - Automatic document model creation from natural language descriptions
 - Smart editor generation based on document models
-- Uses reactor recipes for consistent code generation
 - Automatically triggers code generation when documents reach valid state
 
 The powerhouse config includes a vetra URL for consistent project configuration across different environments.
 
 :::tip
-- Vetra supports integration with custom remote drives, allowing users to create and manage documents within these drives.
+- Vetra supports integration with custom remote drives, allowing users to create, share and manage documents within these drives.
 - The MCP server enables the agent to work with both existing and newly created document models.
 :::
 
@@ -95,28 +114,29 @@ The powerhouse config includes a vetra URL for consistent project configuration
 #### A. Set Package Description (Required)
 1. Provide a name for your package
 2. Add a meaningful description
-3. Confirm changes when prompted in interactive mode
+3. Add keywords to add search terms to your package
+4. Confirm changes when prompted in interactive mode
 
 #### B. Define Document Model (Required)
 You can create document models in two ways:
 
 1. **Using MCP (AI-Assisted)**
-   - Describe your document needs in natural language
+   - Describe your document needs in natural language in great detail.
    - Claude will:
-     - Generate appropriate schema
-     - Create necessary operations
-     - Implement required reducers
+     - Generate an appropriate schema
+     - Create the necessary operations
+     - Implement the required reducers
      - Place the document in the Vetra drive
 
 2. **Manual Creation**
-   - Define document schema with fields and types
-   - Create necessary operations
-   - Add required modules
-   - The document model creation chapter in the Mastery track provides support [here](apps/academy/docs/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
+   - Define document schema with fields and types as in the **'Get Started'**
+   - Create the necessary operations
+   - Add the required modules to your package
+   - The document model creation chapter in the Mastery track provides in depth support [here](apps/academy/docs/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
 
 #### C. Add Document Editor (Required)
 1. **Using MCP (AI-Assisted)**
-   - Request Claude to create an editor for your document
+   - Request Claude to create an editor for your document. Do this with the help of a detailed description of the user interface, user experience and logic that you wish to generate. Make sure to reference operations from the document model to get the best results
    - Claude will:
      - Generate editor components
      - Implement necessary hooks
@@ -124,8 +144,8 @@ You can create document models in two ways:
 
 2. **Manual Creation**
    - Select your target document model
-   - Add editor specification to Vetra Studio drive
-   - Configure editor properties
+   - Configure the currently limited editor properties
+   - Add the editor specification to Vetra Studio drive
    - The system will generate scaffolding code
 
 #### D. Data Integrations (Coming Soon)
@@ -136,15 +156,9 @@ Support for:
 
 ### Best Practices
 
-1. **Working with MCP and claude**
+**Working with MCP and claude**
    - Provide clear, specific instructions and ask for clarifying questions to be answered before code generation.
    - Review generated schemas before confirmation and work in layers instead of 'one-shotting' your code. 
    - Verify implementation details in generated code before continuing. 
-
-2. **General Tips**
-   - Use interactive mode during development
-   - Review changes before confirmation
-   - Double-check proposed next actions
-   - Ask clarifying questions and double check if the task is understood correctly when needed.
-
+   - Always double-check proposed next actions
 

package/docs/academy/01-GetStarted/06-ReactorMCP.md

@@ -0,0 +1,58 @@
+# Tool: Reactor MCP
+
+**Reactor-mcp** is a Model Context Protocol (MCP) server for the Powerhouse ecosystem that provides AI agents and tools with structured access to document model operations. 
+It serves as a bridge between AI systems and the Powerhouse document management infrastructure.
+
+## Main Functions of the Reactor-mcp
+
+**Document Operations**:
+- createDocument - Create new documents
+- getDocument - Retrieve documents by ID
+- addActions - Add actions to modify document state
+- deleteDocument - Remove documents
+
+**Drive Operations**:
+- getDrives - List all document drives
+- addDrive - Create new drives
+- getDrive - Retrieve specific drives
+- addRemoteDrive - Connect to remote drives
+
+**Document Model Operations**:
+- getDocumentModels - List available document model types
+- getDocumentModelSchema - Get schema for specific document models
+
+<details>
+<summary>Architecture Context</summary>
+
+Within the broader Powerhouse ecosystem:
+
+- Document Model: Defines structure and operations for document types
+- Document Drive: Manages collections of documents with sync capabilities
+- Reactor-MCP: Provides AI/tool access to document operations
+- Connect/Switchboard: User interfaces and synchronization servers
+
+The reactor-mcp essentially makes the sophisticated document model system accessible to AI agents and external tools through a standardized protocol, enabling programmatic document creation, modification, and management within the Powerhouse ecosystem.
+
+</details>
+
+### Document Model Agent
+
+Alongside the MCP is a **specialized AI agent** for document model creation:
+
+- Purpose: Guide users through creating document models
+- Workflow: Requirements gathering → Design confirmation → Implementation
+- Tools: Comprehensive set of MCP tools for model management
+- Capabilities: 
+    - State schema definition
+    - Operation creation
+    - Module organization
+    - Code generation
+
+:::tip Supports with:
+
+1. **AI-Assisted Document Model Creation**: AI agents can use the MCP tools to help users create and modify document models
+2. **Automated Document Management**: Programmatic creation and management of documents and drives
+3. **Integration with AI Tools**: Claude, GPT, or other AI systems can use this as an MCP server to interact with Powerhouse
+4. **Development Tooling**: CLI and development server for working with document models locally
+:::
+

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

@@ -756,6 +756,10 @@ Options:
                             will prompt for user confirmation before generating code. This is useful
                             for development when you want control over when code regeneration happens.
 
+  --watch-packages           Enable dynamic loading for document-models and editors in connect-studio
+                            and switchboard. When enabled, the system will watch for changes in these
+                            directories and reload them dynamically. Default is disabled for better performance.
+
 Examples:
   $ ph vetra                                              # Start Vetra environment with defaults
   $ ph vetra --switchboard-port 5000 --connect-port 3001 # Use custom ports
@@ -765,6 +769,7 @@ Examples:
   $ ph vetra --remote-drive http://localhost:4001/d/docs  # Connect to remote drive
   $ ph vetra --disable-connect                            # Start only backend services
   $ ph vetra --interactive                                # Enable interactive code generation mode
+  $ ph vetra --watch-packages                             # Enable dynamic loading for development
   $ ph vetra --https-key-file key.pem --https-cert-file cert.pem  # Use HTTPS
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "4.1.0-dev.58",
+  "version": "4.1.0-dev.60",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",
@@ -16,15 +16,17 @@
     "@powerhousedao/design-system": "^1.6.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.8.0",
-    "@docusaurus/tsconfig": "^3.8.0",
-    "@docusaurus/types": "^3.8.0",
+    "@docusaurus/module-type-aliases": "^3.9.1",
+    "@docusaurus/tsconfig": "^3.9.1",
+    "@docusaurus/types": "^3.9.1",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
     "tsx": "^4.20.3",
-    "typescript": "^5.7.3"
+    "typescript": "^5.9.3"
   },
   "browserslist": {
     "production": [

package/sidebars.ts

@@ -24,7 +24,8 @@ const sidebars = {
         "academy/GetStarted/DefineToDoListDocumentModel",
         "academy/GetStarted/ImplementOperationReducers",
         "academy/GetStarted/BuildToDoListEditor",
-        "academy/GetStarted/SpecDrivenAI",
+        "academy/GetStarted/VetraStudio",
+        "academy/GetStarted/ReactorMCP",
       ],
     },
     {

package/src/pages/_archive-homepage.tsx

@@ -1,10 +1,10 @@
-import clsx from "clsx";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
-import useBaseUrl from "@docusaurus/useBaseUrl";
-import Layout from "@theme/Layout";
 import HomepageFeatures from "@site/src/components/HomepageFeatures";
 import Heading from "@theme/Heading";
+import Layout from "@theme/Layout";
+import clsx from "clsx";
 import styles from "./index.module.css";
+import type { JSX } from "react";
 
 function HomepageHeader() {
   const { siteConfig } = useDocusaurusContext();

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./babel.config.js","./docusaurus.config.ts","./sidebars.ts","./scripts/generate-combined-cli-docs.ts","./src/components/HomepageFeatures/index.tsx","./src/pages/_archive-homepage.tsx","./src/theme/DocCardList/index.tsx"],"version":"5.9.2"}
+{"root":["./babel.config.js","./docusaurus.config.ts","./sidebars.ts","./scripts/generate-combined-cli-docs.ts","./src/components/HomepageFeatures/index.tsx","./src/pages/_archive-homepage.tsx","./src/theme/DocCardList/index.tsx"],"version":"5.9.3"}