@powerhousedao/academy 5.1.0-dev.14 → 5.1.0-dev.17

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/{02-StandardDocumentModelWorkflow.md → 03-CreateAPackageWithVetra.md}

@@ -1,4 +1,4 @@
-# Create Powerhouse packages
+# Create a package with Vetra
 
 :::warning
 **This tutorial is a summary for builders that are already familiar with building document models**.  
@@ -12,9 +12,8 @@ Please start with the '**Get Started**' Chapter or '**Document Model Creation**'
 
 - `pnpm install -g ph-cmd` or `npm install -g ph-cmd`: Installs the Powerhouse CLI globally.
 - `ph init`: Initializes a new Powerhouse project or sets up the local environment.
-- `ph connect`: Runs Connect in Studio Mode for local development and testing.
-- `ph generate <YourModelName.phdm.zip>`: Generates scaffolding code from an exported document model specification.
-- `ph generate --editor YourModelName --document-types powerhouse/YourModelName`: Generates an editor template for a document model.
+- `ph vetra --interactive`: Launches Vetra Studio in interactive mode for package development.
+- `ph vetra --interactive --watch`: Launches Vetra Studio with dynamic reloading for document-models and editors.
 - `pnpm build` or `npm run build`: Builds the project for production.
 - `pnpm run test` or `npm test`: Runs unit tests.
 - `npm login`: Logs into your NPM account.
@@ -45,7 +44,7 @@ See the [Prerequisites](/academy/MasteryTrack/BuilderEnvironment/Prerequisites)
 
 ### 1.2. Initialize your project environment
 
-Before creating a specific project, or if you're setting up your environment for the first time to use Connect Studio Mode, initialize the Powerhouse environment. This command prepares your local setup, including a local Reactor configuration.
+Before creating a specific project, or if you're setting up your environment for the first time, initialize the Powerhouse environment. This command prepares your local setup, including a local Reactor configuration.
 
 ```bash
 ph init
@@ -74,7 +73,45 @@ Please be aware that these versions can contain bugs and experimental features t
 
 </details>
 
-### 1.3. Launch Connect in studio mode
+### 1.3. Launch Vetra Studio
+
+You can launch Vetra Studio in two modes:
+
+#### Interactive Mode (Recommended for Development)
+```bash
+ph vetra --interactive
+```
+In interactive mode:
+- You'll receive confirmation prompts before any code generation
+- Changes require explicit confirmation before being processed
+- Provides better control and visibility over document changes
+
+#### Watch Mode 
+
+```bash
+ph vetra --interactive --watch
+```
+In watch mode:
+
+- Adding `--watch` to your command enables dynamic loading for document-models and editors in Vetra studio and switchboard. 
+- When enabled, the system will watch for changes in these directories and reload them dynamically.
+
+:::warning Be Aware
+When you are building your document model the code can break the Vetra Studio environment. 
+A full overview of the Vetra Studio commands can be found in the [Powerhouse CLI](/academy/APIReferences/PowerhouseCLI#vetra)
+:::
+
+#### Standard Mode
+```bash
+ph vetra
+```
+In standard mode:
+- Changes are processed automatically with 1-second debounce
+- Multiple changes are batched and processed together
+- Uses the latest document state for processing
+
+<details>
+<summary>Alternatively: Use Connect</summary>
 
 Connect is your local development hub. Running it in Studio Mode spins up a local instance with a local Reactor, allowing you to define, build, and test document models.
 
@@ -88,17 +125,113 @@ This command typically opens Connect in your browser at `http://localhost:3000/`
 **Powerhouse Reactors** are essential nodes in the Powerhouse network. They store documents, manage versions, resolve conflicts, and verify document operation histories by rerunning them. Reactors can be configured for local storage (as in Studio Mode), centralized cloud storage, or decentralized storage networks.
 :::
 
-## Phase 2: Document model specification
+</details>
+
+### 1.4. 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. 
+
+<details>
+<summary>Explainer: Specification Driven AI</summary>
+
+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. 
+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 through **specification driven AI control**.
+
+- Communicate your solution and intent through a structured specification framework designed for AI collaboration.
+- Specifications enable precise, iterative edits, since all our specification documents are machine-readable and executable.
+
+</details>
+
+<details>
+<summary> Reactor MCP Overview</summary>
+
+#### Key Reactor MCP Features
+
+**Reactor-mcp** is a Model Context Protocol (MCP) server that bridges AI agents with Powerhouse document operations.
+
+- It supports automatic document model creation from natural language descriptions
+- It implements a smart editor based on the underlying document models
+- It automatically triggers code generation when documents reach valid state
+- The MCP server enables the agent to work with both existing and newly created document models
+- Vetra supports integration with custom remote drives, allowing users to create, share and manage documents within these drives
+
+**Document Operations:**
+- `createDocument` / `getDocument` / `deleteDocument` - Manage documents
+- `addActions` - Modify document state through operations
+
+**Drive Operations:**
+- `getDrives` / `addDrive` / `getDrive` - Manage document drives
+- `addRemoteDrive` - Connect to remote drives
+
+**Document Model Operations:**
+- `getDocumentModels` - List available document model types
+- `getDocumentModelSchema` - Get schema for specific models
+
+**Document Model Agent:**
+A specialized AI agent that guides users through document model creation with requirements gathering, design confirmation, and implementation including state schema definition, operation creation, and code generation.
+
+</details>
+
+#### 1. Start the Reactor MCP:
+
+Make sure you are in the same directory as your project. 
+Claude will automatically recognize the necessary files and MCP tools. 
+
+```bash
+claude
+```
+
+Since you're interacting with a llm it has a high capacit for interpretating your intentions. 
+Any commands in the same trend will do the job. 
+
+```bash
+connect to the reactor mcp
+```
+
+#### 2. Verify MCP connection:
+- Check that the Reactor MCP is available. 
+- Confirm Vetra Studio shows "Connected to Reactor MCP"
+
+```bash
+Connected to MCP successfully! I can see there's a
+  "vetra-4de7fa45" drive available. The reactor-mcp server is
+  running and ready for document model operations.
+```
+
+## Phase 2: Package Creation
+
+### 2.1. Set Package Description (Required)
+1. Provide a name for your package
+2. Add a meaningful description
+3. Add keywords to add search terms to your package
+4. Confirm changes when prompted in interactive mode
 
-### 2.1. Define the document model schema
+### 2.2. Define Document Model (Required)
+
+You can create document models in two ways:
+
+#### Manual Creation
+- 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](/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
+
+#### Using MCP (AI-Assisted)
+- Describe your document needs in natural language in great detail.
+- Claude will:
+  - Generate an appropriate schema
+  - Create the necessary operations
+  - Implement the required reducers
+  - Place the document in the Vetra drive
+
+<details>
+<summary>Alternatively: Use Connect</summary>
 
 Within Connect Studio Mode, navigate to the Document Model Editor. Here, you'll specify the structure of your document model using GraphQL Schema Definition Language (SDL).
 
 - **State Schema:** Describes the data fields and types within your document (e.g., `ToDoItem` with `id`, `text`, `checked` fields).
 - This schema is the blueprint for your document model's data.
 
-### 2.2. Define document model operations
-
 In the same editor, specify the operations (state transitions) for your document model. These are also defined using GraphQL, specifically input types.
 
 - **Operations Schema:** Specifies the actions that can be performed on the document (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`, `DeleteTodoItemInput`).
@@ -108,15 +241,14 @@ In the same editor, specify the operations (state transitions) for your document
   - Use GraphQL input types for operation parameters.
   - Ensure operations reflect user intent for a clean API.
 
-### 2.3. Export document model specification
-
 Once your schema and operations are defined in Connect, export the specification. This will download a `.phdm.zip` file (e.g., `YourModelName.phdm.zip`). Save this file in the root of your Powerhouse project directory.
 
-## Phase 3: Implementation and testing
+</details>
 
-### 3.1. Generate scaffolding code
+<details>
+<summary>Alternatively: Generate command</summary>
 
-Use the Powerhouse CLI to process the exported `.phdm.zip` file and generate the necessary boilerplate code for your document model.
+Use the Powerhouse CLI to process an exported `.phdm.zip` file and generate the necessary boilerplate code for your document model.
 
 ```bash
 ph generate YourModelName.phdm.zip
@@ -129,7 +261,46 @@ This command creates a new directory under `document-models/YourModelName/` cont
 - A `gen/` folder with autogenerated TypeScript types, action creators, and utility functions based on your schema.
 - A `src/` folder where you'll implement your custom logic (reducers, utils).
 
-### 3.2. Implement reducer logic
+</details>
+
+### 2.3. Add Document Editor (Required)
+
+#### Manual Creation
+- Select your target document model
+- Configure the currently limited editor properties
+- Add the editor specification to Vetra Studio drive
+- The system will generate scaffolding code
+
+#### Using MCP (AI-Assisted)
+- 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
+  - Create required UI elements
+
+<details>
+<summary>Alternatively: Generate command</summary>
+
+A document editor provides the user interface for interacting with your document model. Generate an editor template:
+
+```bash
+ph generate --editor YourModelName --document-types powerhouse/YourModelName
+```
+
+- The `--editor YourModelName` flag specifies the document model this editor is for.
+- The `--document-types powerhouse/YourModelName` flag links the editor to the specific document type defined in your model specification.
+
+This creates a template file, typically at `editors/your-model-name/editor.tsx`.
+
+- Customize this React component to build your UI.
+- You can use standard HTML, Tailwind CSS (available in Connect), or import custom CSS.
+- Utilize components from `@powerhousedao/document-engineering` for consistency and rapid development. Learn more at [Document-Engineering](/academy/ComponentLibrary/DocumentEngineering)
+
+</details>
+
+## Phase 3: Implementation and testing
+
+### 3.1. Implement reducer logic
 
 Reducers are pure functions that implement the state transition logic for each operation defined in your schema. Navigate to `document-models/YourModelName/src/reducers/to-do-list.ts` (or similar, based on your model name).
 
@@ -137,7 +308,7 @@ Reducers are pure functions that implement the state transition logic for each o
 - These functions take the current state and an action (containing input data) and return the new state.
 - Powerhouse handles immutability behind the scenes.
 
-### 3.3. Write unit tests for reducers
+### 3.2. Write unit tests for reducers
 
 It's crucial to test your reducer logic. Write unit tests in the `document-models/YourModelName/src/reducers/tests/` directory.
 
@@ -155,24 +326,12 @@ Or with npm:
 npm test
 ```
 
-### 3.4. Implement the document editor
-
-A document editor provides the user interface for interacting with your document model in Connect. Generate an editor template:
+### 3.3. Test the editor
 
-```bash
-ph generate --editor YourModelName --document-types powerhouse/YourModelName
-```
+Test your editor in Vetra Studio by creating a new document of your defined type. Interact with your editor, test all functionalities, and ensure it correctly dispatches actions to the reducers and reflects state changes.
 
-- The `--editor YourModelName` flag specifies the document model this editor is for.
-- The `--document-types powerhouse/YourModelName` flag links the editor to the specific document type defined in your model specification (ensure this matches what you set in Connect).
-
-This creates a template file, typically at `editors/your-model-name/editor.tsx`.
-
-- Customize this React component to build your UI.
-- You can use standard HTML, Tailwind CSS (available in Connect), or import custom CSS.
-- Utilize components from `@powerhousedao/document-engineering` for consistency and rapid development. Learn more at [Document-Engineering](/academy/ComponentLibrary/DocumentEngineering)
-
-### 3.5. Test the editor
+<details>
+<summary>Alternatively: Use Connect</summary>
 
 Run Connect locally to see your editor in action:
 
@@ -182,6 +341,16 @@ ph connect
 
 Create a new document of your defined type. Interact with your editor, test all functionalities, and ensure it correctly dispatches actions to the reducers and reflects state changes.
 
+</details>
+
+### Best Practices
+
+**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. 
+- Always double-check proposed next actions
+
 ## Phase 4: Packaging and publishing
 
 Once your document model and editor are implemented and tested, you can package them for distribution. A Powerhouse Package is a modular unit that can group document models, editors, scripts, and processors.

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/{03-BuilderTools.md → BuilderTools}

@@ -245,7 +245,7 @@ Handles client-side interactions
 
 Manages local storage and offline functionality
 
-### Drive app
+### drive-app
 
 Handles document organization and storage management, but can also be customized to offer specific functionality, categorization, or tailored interfaces for your documents.
 

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

@@ -34,11 +34,11 @@ A reactor allows you to store multiple documents and host **drives** and Drive E
 
 A drive uses a reactor and its underlying storage layer. A reactor is the low-level component that enables the synchronization of documents and drives.
 
-### Drive apps
+### drive-apps
 
-**Drive Explorers** (also known as Drive Apps) are specialized interfaces that enhance how users interact with documents within a drive. As mentioned, a drive is technically just another document containing a list of other documents. This means you can create a custom editor for your drive document.
+**Drive Explorers** (also known as drive-apps) are specialized interfaces that enhance how users interact with documents within a drive. As mentioned, a drive is technically just another document containing a list of other documents. This means you can create a custom editor for your drive document.
 
-These customized editors are called Drive Explorers or Drive Apps. They provide custom views, organization tools, and interactive features tailored to specific use cases. For example, a Drive Explorer might present data as a Kanban board, provide aggregated insights, or offer specialized widgets for data processing.
+These customized editors are called Drive Explorers or drive-apps. They provide custom views, organization tools, and interactive features tailored to specific use cases. For example, a Drive Explorer might present data as a Kanban board, provide aggregated insights, or offer specialized widgets for data processing.
 
 To learn more about building and customizing Drive Explorers, check out our [Building a Drive Explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer) guide.
 
@@ -53,7 +53,7 @@ To create a new drive in Powerhouse, follow these steps:
 
 1. Click the "**Create New Drive**" button in the Connect interface or the **+** icon in the Connect sidebar.
 2. In the modal that appears, enter a name for your drive in the "**Drive Name**" field.
-3. Select the desired Drive App (such as the Generic Drive Explorer, or any other Drive App you've installed).
+3. Select the desired drive-app (such as the Generic Drive Explorer, or any other drive-app you've installed).
 4. Choose the location for your drive: **Local** (only available to you), **Cloud** (available to people in this drive), or **Public** (available to everyone).
 5. (Optional) Enable the "Make available offline" toggle if you want to keep a local backup of your drive.
 6. Once all options are set, click the "Create new drive" button to finalize and create your drive.

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

@@ -1,43 +1,43 @@
-# Build a drive explorer
+# Build a drive-app
 
-**Drive Explorers (or Drive Apps)** enhance how contributors and organizations interact with document models.
+**Drive explorers or drive-apps** enhance how contributors and organizations interact with document models.
 They create an 'app-like' experience by providing a **custom interface** for exploring and interacting with the contents of a drive.
-:::tip What is a Drive Explorer or Drive App?
-A Drive Explorer or Drive App offers a tailored application designed around its document models.
-Think of a Drive Explorer as a specialized lens—it offers **different ways to visualize, organize, and interact with** the data stored within a drive, making it more intuitive and efficient for specific use cases.
+:::tip What is a drive explorer or drive-app?
+A drive explorer or drive-app offers a tailored application designed around its document models.
+Think of a drive explorer as a specialized lens—it offers **different ways to visualize, organize, and interact with** the data stored within a drive, making it more intuitive and efficient for specific use cases.
 :::
 
-### Drive explorers are purpose-built
+### Drive-apps are purpose-built
 
-Organizations typically build Drive Explorers for specific use cases, often packaging them with a corresponding document model. This allows for customized user experiences, streamlined workflows, and maximized efficiency for contributors.
+Organizations typically build drive explorers for specific use cases, often packaging them with a corresponding document model. This allows for customized user experiences, streamlined workflows, and maximized efficiency for contributors.
 
-Drive Explorers or Drive Apps **bridge the gap between raw data and usability**, unlocking the full potential of document models within the Powerhouse framework.
+drive explorers or drive-apps **bridge the gap between raw data and usability**, unlocking the full potential of document models within the Powerhouse framework.
 
-### Key features of drive apps
+### Key features of drive-apps
 
-- **Custom Views & Organization** – Drive Apps can present data in formats like Kanban boards, list views, or other structured layouts to suit different workflows.
+- **Custom Views & Organization** – drive-apps can present data in formats like Kanban boards, list views, or other structured layouts to suit different workflows.
 - **Aggregated Insights** – They can provide high-level summaries of important details across document models, enabling quick decision-making.
-- **Enhanced Interactivity** – Drive Apps can include widgets, data processors, or read models to process and display document data dynamically.
+- **Enhanced Interactivity** – drive-apps can include widgets, data processors, or read models to process and display document data dynamically.
 
-## Build a drive app
+## Build a drive-app
 
-Drive Apps provide custom interfaces for interacting with the contents of a drive.
-Let's start with a **quick overview** of the three steps for building a Drive App. We will then apply these steps to create our **To-do List Drive App**.
+drive-apps provide custom interfaces for interacting with the contents of a drive.
+Let's start with a **quick overview** of the three steps for building a drive-app. We will then apply these steps to create our **To-do List drive-app**.
 
 ### Step 1. Generate the scaffolding code
 
-Use the `generate drive editor` command to create the basic template structure for your Drive App:
+Use the `generate drive editor` command to create the basic template structure for your drive-app:
 
 ```bash
-ph generate --drive-editor <Drive App>
+ph generate --drive-editor <drive-app>
 ```
 
 ### Step 2. Update the manifest file
 
-After creating your Drive App, you need to update its `manifest.json` file.
+After creating your drive-app, you need to update its `manifest.json` file.
 This file identifies your project and its components within the Powerhouse ecosystem.
 
-### Step 3. Customize the drive app
+### Step 3. Customize the drive-app
 
 Review the generated template and modify it to better suit your document model:
 
@@ -45,7 +45,7 @@ Review the generated template and modify it to better suit your document model:
 2. Add custom views specific to your data model
 3. Implement specialized interactions for your use case
 
-### About the drive app template
+### About the drive-app template
 
 The default template provides a solid foundation. It contains:
 
@@ -56,9 +56,9 @@ The default template provides a solid foundation. It contains:
 But the real power comes from tailoring the interface to your specific document models.
 Now, let's implement a specific example for the to-do list we've been working on throughout this guide.
 
-## Implementation example: To-do drive explorer
+## Implementation example: To-do drive-app
 
-This example demonstrates how to create a To-do Drive Explorer application using the Powerhouse platform.
+This example demonstrates how to create a To-do drive-app application using the Powerhouse platform.
 The application allows users to create and manage to-do lists with a visual progress indicator.
 
 :::warning Heads-up!
@@ -101,9 +101,9 @@ ph generate --editor ToDoList --document-types powerhouse/todolist
 </details>
 :::
 
-## Generate the drive explorer app
+## Generate the drive-app
 
-### 1. Generate a drive explorer app:
+### 1. Generate a drive-app:
 
 ```bash
 ph generate --drive-editor todo-drive-explorer
@@ -111,12 +111,12 @@ ph generate --drive-editor todo-drive-explorer
 
 ### 2. Update the `powerhouse.manifest.json` file:
 
-- The manifest file contains metadata for your package that is displayed when other users install it. Update the manifest to register your new Drive App:
+- The manifest file contains metadata for your package that is displayed when other users install it. Update the manifest to register your new drive-app:
 
 ```json
 {
   "name": "To-do List Package",
-  "description": "A simple todo list with a dedicated Drive Explorer App",
+  "description": "A simple todo list with a dedicated drive-app",
   "category": "Productivity",
   "publisher": {
     "name": "Powerhouse",
@@ -138,7 +138,7 @@ ph generate --drive-editor todo-drive-explorer
   "apps": [
     {
       "id": "todo-drive-explorer",
-      "name": "To-do Drive App",
+      "name": "To-do drive-app",
       "driveEditor": "todo-drive-explorer"
     }
   ],
@@ -158,14 +158,14 @@ rm -rf editors/todo-drive-explorer/components/FolderItemsGrid.tsx
 rm -rf editors/todo-drive-explorer/components/FolderTree.tsx
 ```
 
-### 4. Create custom components for your drive explorer:
+### 4. Create custom components for your drive-app:
 
-- Next, create the following files. These will define the data types for our to-do items and provide the custom React components for our Drive Explorer.
+- Next, create the following files. These will define the data types for our to-do items and provide the custom React components for our drive-app.
 
 <details>
 <summary>Create `editors/todo-drive-explorer/types/todo.ts`</summary>
 
-     This file defines the TypeScript type `ToDoState`. It specifies the shape of to-do document data within the Drive Explorer, combining the document's revision information with its global state. This ensures that our components work with a predictable and strongly-typed data structure.
+     This file defines the TypeScript type `ToDoState`. It specifies the shape of to-do document data within the drive-app, combining the document's revision information with its global state. This ensures that our components work with a predictable and strongly-typed data structure.
 
      ```typescript
      import { type ToDoListDocument} from "../../../document-models/to-do-list/index.js"
@@ -226,7 +226,7 @@ rm -rf editors/todo-drive-explorer/components/FolderTree.tsx
    <details>
    <summary>Update `editors/todo-drive-explorer/components/DriveExplorer.tsx`</summary>
 
-This is the main component of our Drive Explorer. It fetches all `powerhouse/todo` documents from the drive, displays them in a table with their progress, and allows a user to click on a document to open it in the `EditorContainer`. It also includes a button to create new documents.
+This is the main component of our drive-app. It fetches all `powerhouse/todo` documents from the drive, displays them in a table with their progress, and allows a user to click on a document to open it in the `EditorContainer`. It also includes a button to create new documents.
 
 ```typescript
 import { useCallback, useState, useRef, useEffect, useMemo } from "react";
@@ -556,19 +556,19 @@ return showRevisionHistory ? (
 
 ### 3. Run the application:
 
-- With the code for our Drive App in place, it's time to see it in action. Run Connect in Studio mode:
+- With the code for our drive-app in place, it's time to see it in action. Run Connect in Studio mode:
 
   ```bash
   ph connect
   ```
 
-  ![Todo Drive Explorer Demo](https://raw.githubusercontent.com/powerhouse-inc/todo-drive-explorer/9a87871e61460e73ddf8635fd756a0cd991306d6/demo.gif)
+  ![Todo drive explorer Demo](https://raw.githubusercontent.com/powerhouse-inc/todo-drive-explorer/9a87871e61460e73ddf8635fd756a0cd991306d6/demo.gif)
 
 ### Now it's your turn!
 
-Start building your own drive apps, explorers or experiences.
+Start building your own drive-apps, explorers or experiences.
 Congratulations on completing this tutorial!
-You've successfully built a custom Drive Explorer, enhancing the way users interact with document models.
+You've successfully built a custom drive explorer, enhancing the way users interact with document models.
 
 Now, take a moment to think about the possibilities!