@powerhousedao/academy 4.1.0-dev.12 → 4.1.0-dev.120

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

@@ -1,25 +1,32 @@
 # Create a new to-do list document
 
 ## Overview
-This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **To-do List**.   
-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'.
+
+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. 
+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
-- Powerhouse CLI installed: `pnpm install -g ph-cmd`
-- node.js 22 and pnpm installed
+
+- Powerhouse CLI installed: `pnpm install -g ph-cmd` or `npm install -g ph-cmd --legacy-peer-deps`
+- node.js 22 and a package manager (pnpm or npm) installed
 - Visual Studio Code (or your preferred IDE)
 - Terminal/Command Prompt access
 
 If you need help with installing the prerequisites you can visit our page [prerequisites](/academy/MasteryTrack/BuilderEnvironment/Prerequisites)
 
 ## Quick start
+
 Create a new Powerhouse project with a single command:
+
 ```bash
 ph init
 ```
 
 ## Before you begin
+
 1. Open your terminal (either your system terminal or IDE's integrated terminal)
 2. Optionally, create a folder first to keep your Powerhouse projects:
 
@@ -27,32 +34,38 @@ ph init
    mkdir ph-projects
    cd ph-projects
    ```
+
 3. Ensure you're in the correct directory before running the `ph init` command.  
-In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter.
-   ```bash
+   In the terminal, you will be asked to enter the project name. Fill in the project name and press Enter.
+
+   ````bash
     you@yourmachine:~/ph-projects % ph init
 
     ? What is the project name? ‣ getting-started
-    ```	
+    ```
 
-    Once the project is created, you will see the following output:
+
+Once the project is created, you will see the following output:
     ```bash
     Initialized empty Git repository in /Users/you/ph-projects/getting-started/.git/
-    The installation is done! 
+    The installation is done!
     ```
 
-    Navigate to the newly created project directory:
+Navigate to the newly created project directory:
     ```bash
     cd getting-started
     ```
-    Once in the project directory, run the `ph connect` command to start a local instance of the Connect application. This allows you to start your document model specification document.
-    Run the following command to start the Connect application:
+
+## 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:
 
     ```bash
     ph connect
     ```
 
-    The Connect application will start and you will see the following output:
+The Connect application will start and you will see the following output:
 
     ```bash
       ➜  Local:   http://localhost:3000/
@@ -60,17 +73,21 @@ In the terminal, you will be asked to enter the project name. Fill in the projec
       ➜  press h + enter to show help
     ```
 
-    A new browser window will open and you will see the Connect application. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser.
+A new browser window will open and you will see the Connect application. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser.
 
-    You will see your local drive and a button to create a new drive.    
-    If you local drive is not present navigate into Settings in the bottom left corner. Settings > Danger Zone > Clear Storage.    
-    Clear the storage of your localhost application as it might has an old session cached.   
+You will see your local drive and a button to create a new drive.
+If you local drive is not present navigate into Settings in the bottom left corner. Settings > Danger Zone > Clear Storage.
+Clear the storage of your localhost application as it might has an old session cached.
 
-4. Move into your local drive.   
-Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page. 
+4. Move into your local drive.  
+   Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page.
 
 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. 
+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/02-DefineToDoListDocumentModel.md

@@ -1,12 +1,14 @@
-# Write the document specification 
+# Write the document specification
 
 In this tutorial, you will learn how to define the specifications for a **To-do List** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
 If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification.
 
 Before you start, make sure you have the Connect application running locally with the command:
+
 ```bash
 ph connect
 ```
+
 The Connect application will start and you will see the following output:
 
 ```bash
@@ -17,11 +19,11 @@ The Connect application will start and you will see the following output:
 
 ## To-do list document specification
 
-Likely you have called your project 'ToDoList'.   
-If you've used a different name, please create a new document specification named 'ToDoList'.   
-**Pay close attention to capitalization, as it influences our code.**  
+Likely you have called your project 'ToDoList'.  
+If you've used a different name, please create a new document specification named 'ToDoList'.  
+**Pay close attention to capitalization, as it influences our code.**
 
-We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model.   
+We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model.  
 Below, you can see the SDL for the `To-do List` document model.
 
 :::info
@@ -45,9 +47,8 @@ type ToDoItem {
   checked: Boolean!
 }
 ```
-</details>
-
 
+</details>
 
 <details>
 <summary>Operations schema of our simplified to-do list</summary>
@@ -59,34 +60,37 @@ input AddTodoItemInput {
 }
 
 # Defines a GraphQL input type for updating a to-do item
+
 input UpdateTodoItemInput {
-  id: ID!
-  text: String
-  checked: Boolean
+id: ID!
+text: String
+checked: Boolean
 }
 
 # Defines a GraphQL input type for deleting a to-do item
+
 input DeleteTodoItemInput {
-  id: ID!
+id: ID!
 }
-```
+
+````
 </details>
 
 ## Define the document model specification
 
-To be able to define the document model, you need to open the document model editor in Connect. 
+To be able to define the document model, you need to open the document model editor in Connect.
 
 ### The steps below show you how to do this:
 
 1. In the Connect application, click on **'document model'** to open the document model specification editor.
-2. Name your document model '**ToDoList**' in the Connect application, paying close attention to capitalization. 
-3. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields. 
+2. Name your document model '**ToDoList**' in the Connect application, paying close attention to capitalization.
+3. You'll be presented with a form to fill in metadata about the document model. Fill in the details in the respective fields.
 
     In the **Document Type** field, type `powerhouse/todolist`. This defines the new type of document that will be created with this document model specification.
-    
+
     ![ToDoList Document Model Form Metadata](./images/DocumentModelHeader.png)
 
-4. In the code editor, you can see the SDL for the document model. Replace the existing SDL template with the SDL defined in the [State Schema](#state-schema) section. Only copy and paste the types, leaving the inputs for the next step. You can, however, already press the 'Sync with schema' button to set the initial state of your document model specification based on your Schema Definition Language. 
+4. In the code editor, you can see the SDL for the document model. Replace the existing SDL template with the SDL defined in the [State Schema](#state-schema) section. Only copy and paste the types, leaving the inputs for the next step. You can, however, already press the 'Sync with schema' button to set the initial state of your document model specification based on your Schema Definition Language.
 5. Below the editor, find the input field `Add module`. You'll use this to create and name a module for organizing your input operations. In this case, we will name the module `to_do_list`. Press enter.
 6. Now there is a new field, called `Add operation`. Here you will have to add each input operation to the module, one by one.
 7. Inside the `Add operation` field, type `ADD_TODO_ITEM` and press enter. A small editor will appear underneath it, with an empty input type that you have to fill. Copy the first input type from the [Operations Schema](#operations-schema) section and paste it in the editor. The editor should look like this:
@@ -106,6 +110,7 @@ Check below screenshot for the complete implementation:
 
 ![ToDoList Document Model](./images/DocumentModelOperations.png)
 
-### Up next: reducers 
+### Up next: reducers
+
+Up next, you'll learn how to implement the runtime logic and components that will use the `ToDoList` document model specification you've just created and exported.
 
-Up next, you'll learn how to implement the runtime logic and components that will use the `ToDoList` document model specification you've just created and exported. 

package/docs/academy/01-GetStarted/03-ImplementOperationReducers.md

@@ -1,6 +1,6 @@
 # Implement the document model
 
-In this section, we will implement and test the operation reducers for the **To-do List** document model. For this, you have to export the document model specification from the Connect application and import it into your Powerhouse project directory. 
+In this section, we will implement and test the operation reducers for the **To-do List** document model. For this, you have to export the document model specification from the Connect application and import it into your Powerhouse project directory.
 
 To export the document model specification, follow the steps in the [Define ToDoList Document Model](/academy/GetStarted/DefineToDoListDocumentModel) section.
 
@@ -9,11 +9,12 @@ To export the document model specification, follow the steps in the [Define ToDo
 Reducers are a core concept in Powerhouse document models. They implement the state transition logic for each operation defined in your schema.
 
 :::info
-**Connection to schema definition language (SDL)**: The reducers directly implement the operations you defined in your SDL. Remember how we defined `AddTodoItemInput`, `UpdateTodoItemInput`, and `DeleteTodoItemInput` in our schema?   
+**Connection to schema definition language (SDL)**: The reducers directly implement the operations you defined in your SDL. Remember how we defined `AddTodoItemInput`, `UpdateTodoItemInput`, and `DeleteTodoItemInput` in our schema?  
 The reducers provide the actual implementation of what happens when those operations are performed.
 :::
 
-To import the document model specification into your Powerhouse project, you can either: 
+To import the document model specification into your Powerhouse project, you can either:
+
 - Copy and paste the file directly into the root of your Powerhouse project.
 - Or drag and drop the file into the Powerhouse project directory in the VSCode editor as seen in the image below:
 
@@ -23,8 +24,7 @@ Either step will import the document model specification into your Powerhouse pr
 
 ## In your project directory
 
-The next steps will take place in the VSCode editor. Make sure to have it open and the terminal window inside VSCode open as well. 
-
+The next steps will take place in the VSCode editor. Make sure to have it open and the terminal window inside VSCode open as well.
 
 To write the operation reducers of the **To-do List** document model, you need to generate the document model code from the document model specification file you have exported into the Powerhouse project directory.
 
@@ -45,7 +45,6 @@ Open the `to-do-list.ts` file and you should see the code that needs to be fille
 1. Copy and paste the code below into the `to-do-list.ts` file in the `reducers` folder.
 2. Save the file.
 
-
 <details>
 <summary>Operation Reducers</summary>
 ```typescript
@@ -54,31 +53,31 @@ import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
 // REMARKS: This is our main reducer object that implements all operations defined in the schema.
 // The ToDoListToDoListOperations type is auto-generated from our SDL and ensures type safety.
 export const reducer: ToDoListToDoListOperations = {
-  // REMARKS: The addTodoItemOperation adds a new item to our todolist.
-  // - state: The current document state that we can modify
-  // - action: Contains the operation type and input data from the client
-  // - dispatch: Function to trigger additional operations (not used here)
-  addTodoItemOperation(state, action, dispatch) {
-    // REMARKS: While this looks like we're directly mutating state, Powerhouse
-    // handles immutability behind the scenes, creating a new state object.
-    state.items.push({
-      id: action.input.id,      // Using the client-provided ID
-      text: action.input.text,  // Setting the todo text from input
-      checked: false,           // New items always start unchecked
-    });
-  },
-
-  // REMARKS: The updateTodoItemOperation modifies an existing todo item.
-  // It handles partial updates, allowing only specific fields to be updated.
-  updateTodoItemOperation(state, action, dispatch) {
-    // REMARKS: First find the item we want to update by its ID
-    const item = state.items.find(item => item.id === action.input.id);
-    
+// REMARKS: The addTodoItemOperation adds a new item to our todolist.
+// - state: The current document state that we can modify
+// - action: Contains the operation type and input data from the client
+// - dispatch: Function to trigger additional operations (not used here)
+addTodoItemOperation(state, action, dispatch) {
+// REMARKS: While this looks like we're directly mutating state, Powerhouse
+// handles immutability behind the scenes, creating a new state object.
+state.items.push({
+id: action.input.id, // Using the client-provided ID
+text: action.input.text, // Setting the todo text from input
+checked: false, // New items always start unchecked
+});
+},
+
+// REMARKS: The updateTodoItemOperation modifies an existing todo item.
+// It handles partial updates, allowing only specific fields to be updated.
+updateTodoItemOperation(state, action, dispatch) {
+// REMARKS: First find the item we want to update by its ID
+const item = state.items.find(item => item.id === action.input.id);
+
     // REMARKS: Proper error handling if item doesn't exist
     if (!item) {
       throw new Error(`Item with id ${action.input.id} not found`);
     }
-    
+
     // REMARKS: We only update fields that were included in the input
     // This allows for partial updates (only update what was provided)
     if (action.input.text) {
@@ -87,17 +86,19 @@ export const reducer: ToDoListToDoListOperations = {
     if (typeof action.input.checked === 'boolean') {
       item.checked = action.input.checked;
     }
-  },
-
-  // REMARKS: The deleteTodoItemOperation removes an item from the list.
-  // This showcases functional programming with array filters for immutable updates.
-  deleteTodoItemOperation(state, action, dispatch) {
-    // REMARKS: Create a new array containing only items that don't match the ID
-    // This is a common pattern for immutable array updates in JavaScript
-    state.items = state.items.filter(item => item.id !== action.input.id);
-  },
+
+},
+
+// REMARKS: The deleteTodoItemOperation removes an item from the list.
+// This showcases functional programming with array filters for immutable updates.
+deleteTodoItemOperation(state, action, dispatch) {
+// REMARKS: Create a new array containing only items that don't match the ID
+// This is a common pattern for immutable array updates in JavaScript
+state.items = state.items.filter(item => item.id !== action.input.id);
+},
 };
-```
+
+````
 </details>
 
 ## Write the operation reducers tests
@@ -131,7 +132,7 @@ describe('Todolist Operations', () => {
     it('should handle addTodoItem operation', () => {
         // REMARKS: We create an input object matching our AddTodoItemInput schema
         const input = { id: '1', text: 'Buy milk' };
-        
+
         // REMARKS: We apply the operation to get a new document state
         // Note how we use the creators to generate the operation action
         const updatedDocument = reducer(document, creators.addTodoItem(input));
@@ -174,7 +175,8 @@ describe('Todolist Operations', () => {
         expect(updatedDocument.state.global.items).toHaveLength(0);
     });
 });
-```
+````
+
 </details>
 
 Now you can run the tests to make sure the operation reducers are working as expected.
@@ -192,7 +194,8 @@ Output should be as follows:
    Duration  417ms (transform 79ms, setup 0ms, collect 174ms, tests 12ms, environment 0ms, prepare 158ms)
 ```
 
-If you got the same output, you have successfully implemented the operation reducers and tests for the **To-do List** document model. Congratulations, you've successfully set up the backbone for a simple **To-do List** document. 
+If you got the same output, you have successfully implemented the operation reducers and tests for the **To-do List** document model. Congratulations, you've successfully set up the backbone for a simple **To-do List** document.
 
 ## Up next: To-do list editor
-In the next chapter of this introduction track you will learn how to implement an editor for your document model so you can see a simple user interface for the **To-do List** document model in action.
+
+In the next chapter of this introduction track you will learn how to implement an editor for your document model so you can see a simple user interface for the **To-do List** document model in action.

package/docs/academy/01-GetStarted/04-BuildToDoListEditor.md

@@ -4,7 +4,7 @@ In this chapter we will continue with the interface or editor implementation of
 
 ## Generate the editor template
 
-Run the command below to generate the editor template for the **To-do List** document model.   
+Run the command below to generate the editor template for the **To-do List** document model.  
 This command reads the **To-do List** document model definition from the `document-models` folder and generates the editor template in the `editors/to-do-list` folder as `editor.tsx`.
 
 Notice the `--editor` flag which specifies the **To-do List** document model, and the `--document-types` flag defines the document type `powerhouse/todolist`.
@@ -15,16 +15,15 @@ ph generate --editor ToDoList --document-types powerhouse/todolist
 
 Once complete, navigate to the `editors/to-do-list/editor.tsx` file and open it in your editor.
 
-
 ### Editor implementation options
 
 When building your editor component within the Powerhouse ecosystem, you have several options for styling, allowing you to leverage your preferred methods:
 
-1.  **Default HTML Styling:** Standard HTML tags (`<h1>`, `<p>`, `<button>`, etc.) will render with default styles offered through the boilerplate. 
+1.  **Default HTML Styling:** Standard HTML tags (`<h1>`, `<p>`, `<button>`, etc.) will render with default styles offered through the boilerplate.
 2.  **Tailwind CSS:** Connect Studio comes with Tailwind CSS integrated. You can directly use Tailwind utility classes for rapid, consistent styling without writing separate CSS files.
 3.  **Custom CSS Files:** You can import traditional CSS files (`.css`) to apply custom styles or integrate existing style libraries.
 
-Connect Studio provides a dynamic local environment, by running `ph connect` to visualize your components instantly as you build them, regardless of the styling method you choose.    
+Connect Studio provides a dynamic local environment, by running `ph connect` to visualize your components instantly as you build them, regardless of the styling method you choose.  
 Manual build steps are typically only needed when publishing packages.
 
 ## To-do List editor
@@ -189,6 +188,7 @@ export default function Editor(props: IProps) {
     );
 }
 ```
+
 </details>
 
 Now you can run the Connect app and see the **To-do List** editor in action.
@@ -197,22 +197,22 @@ Now you can run the Connect app and see the **To-do List** editor in action.
 ph connect
 ```
 
-In Connect, in the bottom right corner you'll find a new Document Model that you can create: **To-do List**.    
+In Connect, in the bottom right corner you'll find a new Document Model that you can create: **To-do List**.  
 Click on it to create a new To-do List document.
 
 :::info
-The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Connect Studio. 
+The editor will update dynamically, so you can play around with your editor styling while seeing your results appear in Connect Studio.
 :::
 
 Congratulations!
-If you managed to follow this tutorial until this point, you have successfully implemented the **To-do List** document model with its reducer operations and editor. 
+If you managed to follow this tutorial until this point, you have successfully implemented the **To-do List** document model with its reducer operations and editor.
 
 ### Up next: Mastery Track
 
 In the [Mastery Track chapther: Document Model Creation](/academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel) we guide you through the theoretics of the previous steps while created a more advanced version of the To-do List.
 
-You will learn: 
+You will learn:
+
 - The in's & out's of a document model.
 - How to use UI & Scalar components from the Document Engineering system.
-- How to build Custom Drive Apps or Drive Explorers. 
-
+- How to build Custom Drive Apps or Drive Explorers.

package/docs/academy/01-GetStarted/05-VetraStudio.md

@@ -0,0 +1,213 @@
+# Tool: Vetra Studio 
+
+:::tip Important
+
+## Vision: Specification Driven AI
+
+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.
+:::
+
+## Introducing Vetra Studio
+
+**Vetra Studio Drive**: Serves as a hub for developers to access, manage & share specification through a remote Vetra drive.   
+**Vetra Package Library**: Store, publish and fork git repositories of packages in the Vetra Package Library.    
+Visit the [Vetra Package Library here](https://vetra.io/packages)
+
+**Vetra Studio Drive** 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 Drive. 
+
+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. 
+For now they offer you a template for code generation. 
+
+<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 
+- **Document model specification**: Defines the structure and operations of a document model using GraphQL SDL, ensuring consistent data management and processing.
+
+### 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
+- **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>
+
+### Configure a Vetra drive in your project
+
+You can connect to a remote vetra drive instead of using the local one auto-generated when you run `ph vetra`
+If you run Vetra without the `--remote-drive` option: Vetra will create a Vetra drive for you that is local and lives in your local environment / local browser storage. 
+If you provide the remote drive with `--remote-drive` argument: Vetra will use this drive instead of creating a local one. the remote drive can be hosted whatever you want.
+The powerhouse config includes a Vetra URL for consistent project configuration across different environments.
+
+```vetra: {
+    driveId: string;
+    driveUrl: string;
+};
+```
+
+Imagine you are a builder and want to work on, or continue with a set of specifications from your team mates. 
+You could then add the specific remote Vetra drive to your powerhouse configuration in the `powerhouse.config.json`file to get going. 
+
+```
+"vetra": {
+    "driveId": "bai-specifications",
+    "driveUrl": "https://switchboard.staging.vetra.io/d/bai-specifications"
+  }
+```
+
+An example of a builder team building on the Powerhouse Vetra Ecosystem and it's complementary Vetra Studio Drive specifications for the different packages be found [here](https://vetra.io/builders/bai)
+
+## Vetra Studio Workflow
+
+### 1. 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
+
+### 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 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.
+```
+
+-  To learn what is a [Reactor](apps/academy/docs/academy/Architecture/WorkingWithTheReactor) read the reactor article
+-  To learn more about the [Reactor MCP](apps/academy/docs/academy/GetStarted/ReactorMCP) read the reactor MCP article
+
+### Key Reactor MCP Features
+
+- 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.
+
+
+### 3. Vetra Studio Package Creation Workflow
+
+#### A. 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
+
+#### 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 in great detail.
+   - Claude will:
+     - 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 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. 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
+
+2. **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
+
+#### D. Data Integrations (Coming Soon)
+Support for:
+- Subgraph integration
+- Code generation processors
+- Relational database processors
+
+### 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
+