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

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 5.1.0-dev.17 (2025-12-11)
+
+### 🩹 Fixes
+
+- **ph-cli:** auth with access-token ([df48be6e9](https://github.com/powerhouse-inc/powerhouse/commit/df48be6e9))
+
+### ❤️ Thank You
+
+- Frank
+
+## 5.1.0-dev.16 (2025-12-11)
+
+### 🚀 Features
+
+- **ph-cli:** added access-token command ([e48181df6](https://github.com/powerhouse-inc/powerhouse/commit/e48181df6))
+- **ph-cli:** added login command ([3dbccd06a](https://github.com/powerhouse-inc/powerhouse/commit/3dbccd06a))
+- **codegen:** update zod schema generation library ([#2129](https://github.com/powerhouse-inc/powerhouse/pull/2129))
+- integrate visibility tools for remotes and pglite instance ([#2122](https://github.com/powerhouse-inc/powerhouse/pull/2122))
+
+### ❤️ Thank You
+
+- Frank
+- Guillermo Puente Sandoval @gpuente
+- Ryan Wolhuter @ryanwolhuter
+
+## 5.1.0-dev.15 (2025-12-09)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
 ## 5.1.0-dev.14 (2025-12-08)
 
 ### 🚀 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 Vetra builder platform 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 containing a document model, 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
 
@@ -80,23 +80,23 @@ This command downloads and sets up the `@powerhousedao/todo-demo`, making its fe
 
 You have now successfully installed `ph-cmd`, initalized a product project and added your first package!
 
-## Step 4: Run the connect app in studio mode
+## Step 4: Run the connect host application.
 
-To run the package locally in Connect Studio (our collaboration and contributor app), run:
+To run the package locally in Connect (our collaboration and contributor app), run:
 
 ```bash
 ph connect
 ```
 
-Click the returned localhost URL and you should see Connect Studio appear in your browser.
+Click the returned localhost URL and you should see Connect appear in your browser.
 
 <figure className="image-container">
   <img src={require("./images/Connect.png").default} alt="Connect Home" />
-  <figcaption>The Powerhouse Connect Studio interface.</figcaption>
+  <figcaption>The Powerhouse Connect interface.</figcaption>
 </figure>
 
 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`, which contains not only a **Document Model** and its accompanying editor but also a **Drive App** specific to the to-do document model.
+Here, you'll see that you've installed the `@powerhousedao/todo-demo`, 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">
   <img
@@ -111,7 +111,7 @@ Here, you'll see that you've installed the `@powerhousedao/todo-demo`, which con
 ## Step 5: Create a todo list document
 
 :::tip What is a 'drive' at Powerhouse?
-A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized 'Drive Apps' for your documents. Think of a Drive App 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. To learn more, visit [Building A Drive App](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
+A **drive** is a folder to store and organize your documents in. Powerhouse offers the ability to build customized 'drive-apps' for your documents. Think of a drive-app 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. To learn more, visit [Building A drive-app](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
 :::
 
 ### 5.1 Create a local todolist app drive
@@ -119,7 +119,7 @@ A **drive** is a folder to store and organize your documents in. Powerhouse offe
 First, let's create a dedicated drive for your to-do lists:
 
 - Click the new drive icon in the interface
-- In the **Drive App** field, select 'To-do Drive App'
+- In the **drive-app** field, select 'To-do drive-app'
 - This creates a specialized drive that's optimized for to-do list documents
 
 ### 5.2 Create a todolist document
@@ -133,11 +133,11 @@ Now move into the drive you've just created:
 
 - Add a few to-dos that are on your mind
 - 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
+- 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**.   
+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).
+Read more about drive-apps in the Mastery Track: [drive-apps](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer).
 
 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.
 

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

@@ -158,12 +158,29 @@ Once in the project directory, run the `ph vetra` command to start a Vetra Studi
 The host application for Vetra Studio will start and you will see the following output:
 
     ```bash
-      ➜  Local:   http://localhost:3000/
-      ➜  Network: http://192.168.5.110:3000/
-      ➜  press h + enter to show help
+ℹ [reactor-api] [package-manager] Loading packages: @powerhousedao/vetra                                                                                                        14:44:19
+ℹ [reactor-api] [server] WebSocket server attached at /graphql/subscriptions                                                                                                    14:44:22
+ℹ [reactor-api] [graphql-manager] Registered /graphql/system subgraph.                                                                                                          14:44:22
+ℹ [reactor-api] [graphql-manager] Registered /graphql/analytics subgraph.                                                                                                       14:44:22
+ℹ [reactor-api] [graphql-manager] Registered /d/:drive subgraph.                                                                                                                14:44:22
+ℹ [reactor-api] [graphql-manager] Registered /graphql supergraph                                                                                                                14:44:23
+ℹ [reactor-api] [graphql-manager] Registered /graphql/document-editor subgraph.                                                                                                 14:44:23
+ℹ [reactor-api] [graphql-manager] Registered /graphql/vetra-package subgraph.                                                                                                   14:44:23
+ℹ [reactor-api] [graphql-manager] Registered /graphql/subgraph-module subgraph.                                                                                                 14:44:23
+ℹ [reactor-api] [graphql-manager] Registered /graphql/processor-module subgraph.                                                                                                14:44:23
+ℹ [reactor-api] [graphql-manager] Registered /graphql/app-module subgraph.                                                                                                      14:44:23
+ℹ [reactor-api] [graphql-manager] Registered /graphql/vetra-read-model subgraph.                                                                                                14:44:23
+ℹ [reactor-api] [server] MCP server available at http://localhost:4001/mcp                                                                                                      14:44:24
+Switchboard initialized                                                                                                                                                         14:44:24
+   ➜ Drive URL: http://localhost:4001/d/vetra-bac239dd                                                                                                                          14:44:24
+2:44:24 PM [vite] (client) Re-optimizing dependencies because vite config has changed                                                                                           14:44:24
+Port 3000 is in use, trying another one...                                                                                                                                      14:44:24
+  ➜  Local:   http://localhost:3000/                                                                                                                                            14:44:24
+  ➜  Network: use --host to expose                                                                                                                                              14:44:24
+  ➜  press h + enter to show help               
     ```
 
-A new browser window will open and you will see the Vetra Studio. 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 when visiting localhost and you will see the Vetra Studio Drive
 
 
 <figure className="image-container">
@@ -175,7 +192,7 @@ A new browser window will open and you will see the Vetra Studio. If it doesn't
 </figure>
 
 
-Create a new document model by clicking the Document Modesl 'Add new specification' button. Name your document TodoList (PascalCase, no spaces or hyphens). If you've followed the steps correctly, you'll have an empty TodoList document where you can define the 'Document Specifications' in the next step.
+Create a new document model by clicking the Document Models 'Add new specification' button. Name your document TodoList (PascalCase, no spaces or hyphens). If you've followed the steps correctly, you'll have an empty TodoList document where you can define the 'Document Specifications' in the next step.
 
 <details>
 <summary>Alternatively: Develop a single document model in Connect</summary>

package/docs/academy/01-GetStarted/02-DefineToDoListDocumentModel.md

@@ -52,25 +52,8 @@ See step 1 for detailed GitHub Desktop instructions.
 In this tutorial, you will learn how to define the specifications for a **To-do List** document model within Vetra Studio 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 Vetra Studio running locally with the command:
-
-```bash
-ph vetra
-```
-
-Vetra Studio will start and you will see the following output:
-
-```bash
-  ➜  Local:   http://localhost:3000/
-  ➜  Network: http://192.168.5.110:3000/
-  ➜  press h + enter to show help
-```
-
 ## TodoList document specification
 
-Make sure you have named your document model `TodoList` (PascalCase, no spaces or hyphens).  
-**Pay close attention to capitalization, as it influences our code generation.**
-
 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 `TodoList` document model.
 
@@ -127,8 +110,6 @@ input DeleteTodoItemInput {
 
 ## Define the document model specification
 
-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 Vetra Studio, click on **'document model'** to open the document model specification editor.
@@ -152,7 +133,8 @@ To be able to define the document model, you need to open the document model edi
 
 8. Repeat the process from step 7 for the other input operations: `UPDATE_TODO_ITEM` and `DELETE_TODO_ITEM`. You may have noticed that you only need to add the name of the operation (e.g., `UPDATE_TODO_ITEM`, `DELETE_TODO_ITEM`) without the `Input` suffix. It will then be generated once you press enter.
 
-9. Once you have added all the input operations, click the `Export` button at the top right of the editor to save the document model specification document to your local machine. Ideally, you should save your file in the root of your Powerhouse project on your machine.
+9. In the meantime Vetra has been keeping an eye on your inputs and started code generation in your directory.
+In your terminal you will also find any validation errors that help you to identify missing specifications. 
 
 Check below screenshot for the complete implementation:
 

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

@@ -42,13 +42,12 @@ git reset --hard tutorial/step-3-implement-reducer-operation-handlers
 
 </details>
 
-In this section, we will implement the operation reducers for the **To-do List** document model. In the previous step Vetra imported our document specification and scaffolded our directory through code generation. If not, you can revisit the [Define TodoList Document Model](/academy/GetStarted/DefineToDoListDocumentModel) section.
+In this section, we will implement the operation reducers for the **To-do List** document model. In the previous step Vetra imported our document specification and scaffolded our code and directory through live code generation.
 
-## Understanding reducers in document models
+:::info
 
 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?  
 The reducers provide the actual implementation of what happens when those operations are performed.
 :::

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

@@ -6,7 +6,7 @@
 - **Complete Editor UI**: [step-6-add-basic-todo-editor-ui-components](https://github.com/powerhouse-inc/todo-tutorial/tree/step-6-add-basic-todo-editor-ui-components)
 
 This tutorial covers two steps:
-1. **Step 5**: Generating the editor template with `ph generate --editor`
+1. **Step 5**: Generating the editor template with Vetra Studio
 2. **Step 6**: Building a complete, interactive UI with components for adding, editing, and deleting todos
 
 Compare implementations: `git diff step-5-generate-todo-list-document-editor step-6-add-basic-todo-editor-ui-components`
@@ -520,8 +520,8 @@ pnpm lint
 # Run tests
 pnpm test
 
-# Test in Connect Studio
-ph connect
+# Test in Vetra Studio 
+ph vetra --watch
 
 # Compare with reference implementation
 git diff tutorial/step-6-add-basic-todo-editor-ui-components -- editors/todo-list-editor/
@@ -553,5 +553,5 @@ 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/home.mdx

@@ -20,8 +20,10 @@ import BrowserOnly from "@docusaurus/BrowserOnly";
     <div className={styles.cardContent}>
       <div style={{ maxWidth: '960px', margin: '0 auto', textAlign: 'center' }}>
         <div style={{ marginBottom: '1.5rem' }}>
-          <p style={{ fontSize: '1.1rem', marginBottom: '1rem' }}><strong>Welcome to Powerhouse Vetra!</strong></p>
-          <p style={{ lineHeight: '1.6', color: '#444' }}>As a developer, you're about to dive into a <strong>unique ecosystem built to empower decentralized organizations</strong>. Powerhouse Vetra provides the software, infrastructure, and frameworks that enable scalable network organizations to operate efficiently.</p>
+          <p style={{ lineHeight: '1.6' }}>
+            Vetra is part of the Powerhouse Ecosystem and acts as the builder platform for creating an independent, open-source and decentralized back-end for any SaaS, ERP, CMS or CRM needs.<br />
+            For a deeper dive into the architecture, see the <a href="/academy/Architecture/PowerhouseArchitecture">Powerhouse Architecture</a> page.
+          </p>
         </div>
         <div style={{ margin: '20px 0', textAlign: 'center' }}>
           <iframe
@@ -48,7 +50,7 @@ import BrowserOnly from "@docusaurus/BrowserOnly";
 
 <div></div> {/* Placeholder for the deleted "New Link" card */}
 
-<div className={styles.pathCard} style={{ border: "1px solid #4FC86F" }}>
+<div className={styles.pathCard}>
   <div className={styles.cardHeader}>
     <h3 className="card-title">
       <img
@@ -60,20 +62,15 @@ import BrowserOnly from "@docusaurus/BrowserOnly";
     </h3>
   </div>
   <div className={styles.cardContent}>
-    <a
-      href="/academy/GetStarted/CreateNewPowerhouseProject"
-      className="path-button"
-    >
-      Build a todo-list document model
-    </a>
+    <a href="/academy/GetStarted/CreateNewPowerhouseProject" className="path-button">Build a todo-list document model</a>
   </div>
 </div>
 
 <div></div> {/* Placeholder for the deleted "Document Model Theory" card */}
 
-{/* Row 2: Build User Experiences, Builder Track Image, Work with Data */}
+{/* Row 2: Build User Experiences, Launch, Work with Data */}
 
-<div className={styles.pathCard} style={{ border: "1px solid #4FC86F" }}>
+<div className={styles.pathCard}>
   <div className={styles.cardHeader}>
     <h3 className="card-title">
       <img
@@ -85,27 +82,10 @@ import BrowserOnly from "@docusaurus/BrowserOnly";
     </h3>
   </div>
   <div className={styles.cardContent}>
-    <a href="/academy/GetStarted/BuildToDoListEditor" className="path-button">
-      Build a todo-list editor
-    </a>
-    <a
-      href="/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors"
-      className="path-button"
-    >
-      Build document editors
-    </a>
-    <a
-      href="/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer"
-      className="path-button"
-    >
-      Build custom drive explorers
-    </a>
-    <a
-      href="/academy/ComponentLibrary/DocumentEngineering"
-      className="path-button"
-    >
-      Component library
-    </a>
+    <a href="/academy/GetStarted/BuildToDoListEditor" className="path-button">Build a todo-list editor</a>
+    <a href="/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors" className="path-button">Build document editors</a>
+    <a href="/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer" className="path-button">Build custom drive explorers</a>
+    <a href="/academy/MasteryTrack/BuilderEnvironment/CreateAPackageWithVetra" className="path-button">Create a package with Vetra</a>
   </div>
 </div>
 
@@ -113,21 +93,38 @@ import BrowserOnly from "@docusaurus/BrowserOnly";
   className={styles.middleColumn}
   style={{
     display: "flex",
-    justifyContent: "center",
-    alignItems: "flex-start",
-    paddingTop: "-20px",
+    flexDirection: "column",
+    justifyContent: "space-between",
+    alignItems: "center",
     position: "relative",
+    height: "100%",
   }}
 >
-  <img src="/img/Union.svg" alt="Powerhouse Union" width="250" />
-  <div className={styles.masteryTrackTitle}>
-    <h3 className="card-title" style={{ margin: 0 }}>
-      Mastery track
-    </h3>
+  <div style={{ position: "relative", display: "flex", justifyContent: "center", alignItems: "flex-start", paddingTop: "1rem" }}>
+    <img src="/img/Union.svg" alt="Powerhouse Union" width="200" />
+    <div className={styles.masteryTrackTitle}>
+      <h3 className="card-title" style={{ margin: 0 }}>Mastery track</h3>
+    </div>
+  </div>
+  <div className={styles.pathCard} style={{ width: "100%", padding: "1rem", marginTop: "auto" }}>
+    <div className={styles.cardHeader} style={{ marginBottom: "0.5rem" }}>
+      <h3 className="card-title">
+        <img
+          src="/img/academy/icons/Launch.svg"
+          alt=""
+          className={styles.titleIcon}
+        />
+        Launch
+      </h3>
+    </div>
+    <div className={styles.cardContent}>
+      <a href="/academy/MasteryTrack/Launch/PublishYourProject" className="path-button" style={{ padding: "0.75rem", margin: "0.25rem 0" }}>Publish your project</a>
+      <a href="/academy/MasteryTrack/Launch/SetupEnvironment" className="path-button" style={{ padding: "0.75rem", margin: "0.25rem 0" }}>Set-up a cloud environment</a>
+    </div>
   </div>
 </div>
 
-<div className={styles.pathCard} style={{ border: "1px solid #4FC86F" }}>
+<div className={styles.pathCard}>
   <div className={styles.cardHeader}>
     <h3 className="card-title">
       <img
@@ -139,63 +136,12 @@ import BrowserOnly from "@docusaurus/BrowserOnly";
     </h3>
   </div>
   <div className={styles.cardContent}>
-    <a
-      href="/academy/MasteryTrack/WorkWithData/UsingTheAPI"
-      className="path-button"
-    >
-      Read & write through the API
-    </a>
-    <a
-      href="/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs"
-      className="path-button"
-    >
-      Create your own subgraph
-    </a>
-    <a
-      href="/academy/MasteryTrack/WorkWithData/Analytics-Engine/intro"
-      className="path-button"
-    >
-      Use the analytics engine
-    </a>
+    <a href="/academy/MasteryTrack/WorkWithData/UsingTheAPI" className="path-button">Read & write through the API</a>
+    <a href="/academy/MasteryTrack/WorkWithData/UsingSubgraphs" className="path-button">Create your own subgraph</a>
+    <a href="/academy/MasteryTrack/WorkWithData/Analytics-Engine/intro" className="path-button">Use the analytics engine</a>
   </div>
 </div>
 
-{/* Launch Card - Full Width with 3 column buttons - RE-INSERTED */}
-
-<div className={`${styles.pathCard} ${styles.fullWidth}`}>
-  <div className={styles.cardHeader}>
-    <h3 className="card-title">
-      <img
-        src="/img/academy/icons/Launch.svg"
-        alt=""
-        className={styles.titleIcon}
-      />
-      Launch
-    </h3>
-  </div>
-  <div className={styles.cardContent}>
-    <div className={styles.buttonContainer}>
-      <a
-        href="/academy/MasteryTrack/Launch/IntroductionToPackages"
-        className="path-button"
-      >
-        Intro to packages
-      </a>
-      <a
-        href="/academy/MasteryTrack/Launch/PublishYourProject"
-        className="path-button"
-      >
-        Publish your project
-      </a>
-      <a
-        href="/academy/MasteryTrack/Launch/SetupEnvironment"
-        className="path-button"
-      >
-        Set-up a cloud environment
-      </a>
-    </div>
-  </div>
-</div>
 
 {/* Row 3: Cookbook, Use-cases, Advanced Topics */}
 
@@ -211,9 +157,7 @@ import BrowserOnly from "@docusaurus/BrowserOnly";
     </h3>
   </div>
   <div className={styles.cardContent}>
-    <a href="/academy/Cookbook" className="path-button">
-      Powerhouse recipes
-    </a>
+    <a href="/academy/Cookbook" className="path-button">Vetra recipes</a>
   </div>
 </div>
 
@@ -233,12 +177,7 @@ import BrowserOnly from "@docusaurus/BrowserOnly";
     </h3>
   </div>
   <div className={styles.cardContent}>
-    <a
-      href="/academy/ExampleUsecases/Chatroom/SetupBuilderEnvironment"
-      className="path-button"
-    >
-      Explore use-cases
-    </a>
+    <a href="/academy/ExampleUsecases/Overview" className="path-button">Explore use-cases</a>
   </div>
 </div>
 

package/docs/academy/01-GetStarted/styles.module.css

@@ -84,11 +84,27 @@
   font-weight: 500;
   text-align: center;
   transition: background 0.2s ease-in-out;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  outline: none;
+  box-shadow: none;
 }
 
 :global(.path-button:hover) {
   background: #ffffff;
   border-color: #d1d5db;
+  color: #111827;
+  text-decoration: none;
+}
+
+:global(.path-button:visited),
+:global(.path-button:active),
+:global(.path-button:focus) {
+  color: #111827;
+  text-decoration: none;
+  outline: none;
+  box-shadow: none;
 }
 
 .masteryTrackTitle {
@@ -111,13 +127,21 @@
   border: 1px solid var(--ifm-color-emphasis-200);
 }
 
-:global([data-theme="dark"]) :global(.path-button) {
-  background: var(--ifm-color-emphasis-100);
-  border-color: var(--ifm-color-emphasis-200);
-  color: var(--ifm-font-color-primary);
+:global([data-theme="dark"]) :global(.path-button),
+:global([data-theme="dark"]) :global(.path-button:visited),
+:global([data-theme="dark"]) :global(.path-button:active),
+:global([data-theme="dark"]) :global(.path-button:focus) {
+  background: #374151;
+  border: none !important;
+  color: #ffffff !important;
+  outline: none !important;
+  box-shadow: none !important;
+  text-decoration: none !important;
 }
 
 :global([data-theme="dark"]) :global(.path-button:hover) {
-  background: var(--ifm-color-emphasis-200);
-  border-color: var(--ifm-color-emphasis-300);
+  background: #4b5563;
+  color: #ffffff !important;
+  border: none !important;
+  text-decoration: none !important;
 }

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/02-VetraStudio.md

@@ -0,0 +1,95 @@
+---
+toc_max_heading_level: 3
+
+
+---
+
+
+# Vetra Studio
+
+## Introducing Vetra Studio
+
+- **Vetra Studio Drive**: Serves as a hub for developers to access, manage & share specification through a remote Vetra drive. It 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  
+- **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) 
+
+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 the specification documents 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)
+
+<details>
+<summary>📦 Vetra Remote Drive Commands</summary>
+
+Remote drives enable collaborative development by syncing specifications across team members.
+
+**Key Commands:**
+- `ph init --remote-drive <url>` - Create a NEW project connected to a remote drive
+- `ph checkout --remote-drive <url>` - Clone an EXISTING project from a remote drive  
+- `ph vetra --watch` - Start development with a preview drive for testing local changes
+
+**Workflows:**
+- **Project Owner**: `ph init --remote-drive` → Create GitHub repo → Push → `ph vetra` to configure
+- **Collaborator**: `ph checkout --remote-drive` → `ph vetra` to start developing
+
+**Preview Drive (`--watch` mode):**
+- Main "Vetra" drive syncs with remote and contains stable package configuration
+- "Vetra Preview" drive is created locally for testing document models before syncing
+- When restarting Vetra always use `vetra --watch` so it loads local documents & editors. 
+
+→ [Full Vetra Remote Drive Reference](/academy/APIReferences/VetraRemoteDrive)
+
+</details>