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

package/docs/academy/02-MasteryTrack/05-Launch/02-PublishYourProject.md

@@ -1,78 +1,56 @@
 # Publish your package
 
-This tutorial is a step by step guide tackling the following topics:
-
-1. the process of **building a powerhouse project**
-2. the process of **publishing it as a package**
+:::warning
+**This guide assumes familiarity with building document models in Vetra Studio.**  
+Please start with the **'Get Started'** chapter or **'Document Model Creation'** section if you are new to building document models.
+:::
 
-:::info
-Let's start with some **key concepts** that will help you understand the process we're going to go through in this tutorial.
+This guide covers the process of **building** and **publishing** a Powerhouse package to NPM.
 
-- **Powerhouse Project**: The construction site of your package: A project is built with document models and editors which you will publish to NPM as a package with modules.
-- **Powerhouse Modules**: The modules that are part of your project, such as the document models, editors, processors or scripts.
-- **Powerhouse Drive Apps**: Customized drive interfaces that function as a drive add and enhance or augment the functionality of your documents and workflows within the drive.
-- **Powerhouse Package**: A package is a collection of modules that are published to NPM and can be installed on a server instance or locally on your machine with help of the host apps such as Connect, Switchboard & Fusion. Organizations build packages for specific purposes or workflows.
+:::info Key Concepts
+- **Powerhouse Package**: A collection of modules published to NPM that can be installed on a server instance or locally. Organizations build packages for specific purposes or workflows.
+- **Powerhouse Modules**: The building blocks of your package—document models, editors, processors, or scripts.
+- **Vetra Studio**: The development hub where you assemble specifications for your package. Each module is defined through specification documents that drive code generation.
+- **Powerhouse Drive-apps**: Customized drive interfaces that enhance document functionality and workflows within a drive.
 
 ![Key Concepts](images/keyconcepts.png)
 :::
 
 ## 1. Building your project
 
-To start building your project with it's dedicated document models and editors we'll run the following command:
+### 1.1. Initialize your project
+
+Start by initializing a new Powerhouse project:
 
 ```bash
- ph init
+ph init
 ```
 
+You'll be prompted to name your project, which will become the package name when published to NPM.
+
 <details>
-<summary> Command not working? Did you install `ph-cmd`? </summary>
+<summary>Command not working? Did you install `ph-cmd`?</summary>
 
-The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. You can get access to the Powerhouse Ecosystem tools by installing them globally using:
+The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. Install it globally using:
 
 ```bash
 pnpm install -g ph-cmd
 ```
 
-For experimental features, use --version [version] which allows selecting a specific branch of our document-model-boilerplate. There are --dev and --staging options. Select `ph init --dev` to use the latest development version. Please be aware that this version can contain bugs and experimental features that aren't fully tested.
-
 Key commands include:
 
-- `ph connect` for running the Connect application locally
+- `ph vetra` for launching Vetra Studio
+- `ph connect` for running Connect locally (alternative)
 - `ph switchboard` or `ph reactor` for starting the API service
-- `ph init` to start a new project and build a document model
-- `ph help` to get an overview of all the available commands
-
-This tool will be fundamental on your journey when creating, building, and running document models
-
-</details>
-
-<details>
-<summary> Got `ph-cmd` installed, but command not working? Reset your package manager cache</summary>
-
-If you need to reset your package manager, you can run the following commands for your package manager: (pnpm, npm, yarn)
-
-```bash
-pnpm cache verify
-pnpm store prune
-pnpm cache clean --force
-
-npx clear-npx-cache
-
-npm cache verify
-npm cache clean --force
-npm cache verify
-
-yarn cache list
-yarn cache clean --force
-yarn cache list
-```
+- `ph init` to start a new project
+- `ph help` to get an overview of all available commands
 
 </details>
 
 <details>
-<summary> How to make use of different branches? </summary>
+<summary>How to use different branches?</summary>
 
-When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches. These branches contain more experimental features then the latest stable release the PH CLI uses by default. They can be used to get access to a bugfix or features under development.
+When using the Powerhouse CLI, you can access dev & staging branches for experimental features or bugfixes under development.
 
 | Command                            | Description                                           |
 | ---------------------------------- | ----------------------------------------------------- |
@@ -90,84 +68,90 @@ Please be aware that these versions can contain bugs and experimental features t
 
 </details>
 
-### 1.1. Specifying your project details
-
-When you are creating your own project, you will be asked to name your project.
-Which will also become the package name when someone else wants to install it in a cloud environment via npm in the future.
+### 1.2. Launch Vetra Studio
 
-Please feel free to navigate to the package.json file and fill in all the other available fields such as `name`, `version`, `author`, `license` and `main`.
+Launch Vetra Studio in interactive watch mode for development:
 
 ```bash
-{
-"name": "@your-org-ph/package-name",  #Your organization name with the -ph suffix to indicate it's a powerhouse related organization & package.
-"version": "1.0.0",
-"author": "Your Name",
-"license": "AGPL-3.0-only",
-"main": "index.js"
-}
+ph vetra --interactive --watch
 ```
 
-Now that you've created your powerhouse project you are ready to generate the necessary directory and file structure to add your document models.
+This mode provides:
+- **Interactive confirmations** before code generation
+- **Dynamic reloading** for document-models and editors
+- **Live preview** of your changes in Vetra Studio
+
+<details>
+<summary>Alternatively: Use Connect</summary>
+
+You can also use Connect for local development:
 
 ```bash
-ph generate
+ph connect
 ```
 
-The **generate** command will start the configuration of your powerhouse project and generates a directory with the necessary files and folders to build your project.
-These include:
+This opens Connect in your browser at `http://localhost:3000/`, providing a local Reactor for testing.
+
+</details>
 
-- `document-models`: A folder containing the document models schemas you've defined in Connect Studio Mode.
-- `editors`: A folder containing the editors you've defined in react, potentially making use of the reusable components.
-- `processors`: A folder containing the processors you might be running on your document models later on.
-- `scripts`: A folder containing the scripts you might use.
-- `tests`: A folder containing your unit tests.
+### 1.3. Configure package details
 
-### 1.2. Adding document models, editors and unit tests
+In Vetra Studio, navigate to the **Package Details** section of your Vetra Studio drive to configure:
 
-Now that you've set up your directory.
-Go ahead and add the document models you'd like to add by going through the standard document model building flow:
+- **Package name**: Use the format `@your-org-ph/package-name` (the `-ph` suffix identifies Powerhouse ecosystem packages)
+- **Description**: A meaningful description of your package
+- **Keywords**: Search terms for discoverability
+- **Version**: Following semantic versioning (e.g., `1.0.0`)
+- **Author** and **License** information
 
-:::info
-These steps are explained more in depth in any of our tutorials. Follow along with one of the tutorials that matches your project the most.
-:::
+These details are stored in your `package.json` and a `manifest.json` file is automatically generated from this configuration.
+
+```json
+{
+  "name": "@your-org-ph/package-name",
+  "version": "1.0.0",
+  "author": "Your Name",
+  "license": "AGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
 
-1. Defining your Document Model **GraphQL Schema** in the document model document editor by launching the document model editor in Connect Studio Mode with the `ph connect` command.
-2. Defining your Document Model **Operations** in the document model document operations editor and their graphQL counterparts.
-3. Generating the scaffolding code by **exporting** the Zip file from connect and **importing** it into your project. (Save it in the directory you've created in the previous step) Run `ph generate <zipfile>`.
-4. Implementing the **reducer code** and unit tests of your document models reducers.
-5. Implementing the **document editors** to visualize and interact with your document models.
-6. Run **unit tests** and verify the editor functionality via `ph connect` for local testing.
-7. Add a **manifest file** to your project and updating your index.js file to export your modules.
+### 1.4. Build your modules
 
-### 1.3. Verifying your project
+With Vetra Studio running, build your package modules:
 
-Now that we've completed our directory with the reducers, tests and editors, and your project is populated with modules we'll verify the build output and see if everything is working correctly.
+1. **Document Models**: Define your document model specifications in Vetra Studio. The state schema and operations are automatically generated into code.
+2. **Editors**: Create editor specifications linked to your document models. Vetra generates the scaffolding code.
+3. **Reducers**: Implement the state transition logic in the generated reducer files.
+4. **Unit Tests**: Write tests for your reducer logic in the `tests/` directory.
 
-Let's **verify the package build output** with the following command:
+Run tests to verify your implementation:
 
 ```bash
-pnpm build
+pnpm run test
 ```
 
-This command will **build** the project and create a build directory with the output. The code gets optimized and minified. It optimizes the code for production and distribution so different environments can use it as a package.
+### 1.5. Verify your build
 
-This command will **start a local server** and serve the build output.
-Inspect the build output and verify that the document models are working correctly.
-Instead of `pnpm serve`, we'll be using:
+Build your project to verify everything compiles correctly:
 
 ```bash
-ph connect
+pnpm build
 ```
 
-### 1.4 Storing your project in a git repository
+This creates an optimized build output ready for distribution. Test the build locally:
+
+```bash
+ph vetra --interactive --watch
+```
 
-Now that you've verified your project is working correctly, you can store your project in a git repository.
-Why?
+Create documents of your defined types and verify all functionality works as expected.
 
-- So you can track the changes of your project in a remote repository and benefit from the collaboration features of git.
-- So you can publish your project to the npm registry and install it on a server instance or locally on your machine.
+### 1.6. Store in version control
 
-If you stick to the layout generated by the `ph init` command, where its folders for document models and editors, you should later be able to install your package with `ph install @<your-org/package-name>` once it's published to the npm registry.
+Initialize a git repository to track changes:
 
 ```bash
 git init
@@ -175,145 +159,95 @@ git add .
 git commit -m "Initial commit"
 ```
 
-This will initialize a git repository and add all the files to the repository.
-
 ## 2. Publishing your project
 
-For this step you'll need to register your organization on npm.
-If you haven't already registered your organization on npm, you can do so by running the following command:
-
-```bash
-pnpm adduser
-```
+### 2.1. Set up NPM organization
 
-Create an organization on [NPM](https://www.npmjs.com/) using the naming convention: `@yourorganization-ph`
+Create an organization on [NPM](https://www.npmjs.com/) using the naming convention `@yourorganization-ph`:
 
-- The `-ph` suffix indicates its a Powerhouse ecosystem package to help you and others identify it from regular NPM packages.
+- The `-ph` suffix identifies Powerhouse ecosystem packages
 - Example: `@acme-ph`
 
-To make sure you can differentiate between Powerhouse ecosystem packages and other packages we recommend setting up a separate npm account for your organization with the -ph suffix. **example: @yourorg-ph**
-We advise you to **use a dedicated npm account for your organization and not your personal account**.
+We recommend using a **dedicated NPM account** for your organization rather than a personal account.
 
-Once you've registered your organization on npm, you can now publish your project to the npm registry.
-Log in via the command line:
+### 2.2. Log in to NPM
 
 ```bash
 npm login
 ```
 
-You'll be prompted for your username, password, and email in a separate browser window.
-
-Once you've logged in, you can configure your package.json for npm before publishing.
-If you're publishing a package under a scope (like @your-org/my-package), you might need to add the `publishConfig` to ensure it's public, otherwise scoped packages default to private:
-
-```json
-{
-  "name": "@your-org/my-package",
-  "version": "1.0.0",
-  "main": "index.js",
-  "publishConfig": {
-    "access": "public"
-  }
-}
-```
-
-### 2.1 Versioning, tagging, and publishing your package
-
-Before publishing, it's crucial to version your package correctly and tag the release in your Git repository. This helps track changes and allows users to depend on specific versions.
+Follow the prompts in your terminal or browser to authenticate.
 
-#### 1. Versioning with pnpm
+### 2.3. Version your package
 
-Use the `pnpm version` command to update your package version according to semantic versioning rules (`patch` for bugfixes, `minor` for new features, `major` for breaking changes). This command will:
-
-- Update the `version` in your `package.json`.
-- Create a Git commit for the version change.
-- Create a Git tag for the new version (e.g., `v1.0.1`).
+Use semantic versioning to update your package version. The `pnpm version` command will:
+- Update the `version` in `package.json`
+- Create a Git commit for the version change
+- Create a Git tag (e.g., `v1.0.1`)
 
 ```bash
-# For a patch release (e.g., from 1.0.0 to 1.0.1)
+# Patch release (1.0.0 → 1.0.1) - bugfixes
 pnpm version patch
 
-# For a minor release (e.g., from 1.0.1 to 1.1.0)
+# Minor release (1.0.1 → 1.1.0) - new features
 pnpm version minor
 
-# For a major release (e.g., from 1.1.0 to 2.0.0)
+# Major release (1.1.0 → 2.0.0) - breaking changes
 pnpm version major
 ```
 
-Take note of the new version tag created (e.g., `v1.0.1`), as you'll need it in the next step.
-
-#### 2. Pushing changes to Git
+### 2.4. Push to Git
 
-Next, push your commits and the new version tag to your remote Git repository:
+Push your commits and version tag to your remote repository:
 
 ```bash
-# Push your current branch (e.g., main or master)
-# Replace 'main' with your default branch name if different
 git push origin main
-
-# Push the specific tag created by pnpm version
-# Replace vX.Y.Z with the actual tag name (e.g., v1.0.1)
-git push origin vX.Y.Z
-```
-
-The specific tag name (e.g., `v1.0.1`) is usually output by the `pnpm version` command. Pushing the specific tag is recommended to avoid unintentionally pushing other local tags.
-
-Alternatively, to push all new local tags (use with caution):
-
-```bash
-# git push --tags
+git push origin vX.Y.Z  # Replace with your actual tag
 ```
 
-#### 3. Understanding Git tags vs. npm distributor tags
-
-It's important to distinguish between Git tags and NPM distributor tags (dist-tags):
-
-- **Git Tags**: These are markers in your Git repository's history. They are primarily for developers to pinpoint specific release versions in the codebase (e.g., `v1.0.0`, `v1.0.1`). The `pnpm version` command creates these.
-- **NPM Distributor Tags (dist-tags)**: These are labels used by the NPM registry to point to specific published versions of your package. Common NPM tags include:
-  - `latest`: This is the default tag. When someone runs `pnpm install my-package`, NPM installs the version tagged as `latest`.
-  - `beta`, `next`, `alpha`: Often used for pre-release versions.
-    When you publish a package without specifying an NPM tag, it usually gets the `latest` tag by default.
-
-#### 4. Publishing to npm
-
-Now you are ready to publish your package to the NPM registry. Ensure you are logged into NPM (the `npm login` command shown in previous steps should be used, or `pnpm login` which is an alias).
+### 2.5. Publish to NPM
 
 ```bash
 pnpm publish
 ```
 
-This command will publish the version of your package that is currently specified in your `package.json`. By default, this will also set the `latest` NPM dist-tag for this version.
-
-If your package is scoped (e.g., `@your-org/my-package`) and intended to be public, ensure your `package.json` includes the `publishConfig` shown earlier. If this is not set in `package.json` (and your package is scoped), you might need to use:
+For scoped packages intended to be public, ensure your `package.json` includes the `publishConfig` shown earlier, or use:
 
 ```bash
 pnpm publish --access public
 ```
 
-You can also publish a version to a specific NPM dist-tag. For example, to publish a beta version:
+To publish a pre-release version:
 
 ```bash
-# Ensure your package.json version reflects the beta (e.g., 1.1.0-beta.0)
+# Ensure your version reflects the pre-release (e.g., 1.1.0-beta.0)
 pnpm publish --tag beta
 ```
 
-This is useful for testing releases before making them `latest`.
-
-Now let's verify that the package(s) get published in the package repository, next to pre-existing packages that you might have been publishing before.
-
-## 3. Deploying the host apps and project
+:::info Git Tags vs NPM Tags
+- **Git Tags**: Markers in your repository history (e.g., `v1.0.0`) created by `pnpm version`
+- **NPM Dist-Tags**: Labels pointing to published versions (`latest`, `beta`, `next`). When publishing without a tag, the version gets the `latest` tag by default.
+:::
 
-Now that we've installed all the necessary services on our server instance, we can start deploying the host apps & our packaged project from npm.
+## 3. Installing your package
 
-Install your project package we've published earlier on your local connect (`ph connect`) instance by running the following command:
+Once published, install your package in any Powerhouse environment:
 
 ```bash
-ph install @<your-org/package-name>
+ph install @your-org-ph/package-name
 ```
 
-Alternatively you can also install the package in the settings of Connect in the 'package manager' section. (Not available yet)
-Where you'll be able to use the same package name as you've used in the `package.json` file and install it at the click of a button.
+This makes your document models and editors available within that Powerhouse instance.
+
+<details>
+<summary>Future: Package Manager UI</summary>
+
+A visual package manager is planned for Connect's settings, allowing installation at the click of a button.
 
 ![package manager](images/homedesign.png)
 
-Got this far? Congratulations on publishing your first package!
+</details>
+
+---
+
+**Congratulations on publishing your package!** Your document models and editors are now available for installation across the Powerhouse ecosystem.

package/docs/academy/02-MasteryTrack/05-Launch/03-SetupEnvironment.md

@@ -1,4 +1,4 @@
-# Environment setup guide
+# Setup your environment
 
 ## Introduction
 

package/docs/academy/02-MasteryTrack/05-Launch/05-DockerDeployment.md

@@ -1,4 +1,4 @@
-# Docker Deployment Guide
+# Docker deployment guide
 
 ## Introduction
 

package/docs/academy/02-MasteryTrack/_category_.json

@@ -2,6 +2,6 @@
   "label": "Mastery track",
   "link": {
     "type": "generated-index",
-    "description": "A set of tutorials that support the creation of more complex Powerhouse documents, drive apps and packages."
+    "description": "A set of tutorials that support the creation of more complex Powerhouse documents, drive-apps and packages."
   }
 }

package/docs/academy/03-ExampleUsecases/00-Overview.mdx

@@ -0,0 +1,60 @@
+---
+title: Example use-cases
+sidebar_class_name: category-index-page
+---
+
+import styles from "../01-GetStarted/styles.module.css";
+
+# Example use-cases
+
+Explore real-world examples of applications built with the Powerhouse ecosystem. Each use-case provides a complete walkthrough from project setup to a fully functional application.
+
+<div className={styles.learningPath} style={{ gridTemplateColumns: 'repeat(3, 1fr)' }}>
+
+<div className={styles.pathCard}>
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img src="/img/academy/icons/Editor.svg" alt="" className={styles.titleIcon} />
+      Chatroom
+    </h3>
+  </div>
+  <div className={styles.cardContent}>
+    <p style={{ fontSize: '0.9rem', color: 'var(--ifm-color-content-secondary)', marginBottom: '1rem' }}>
+      Build a real-time chat application with message posting and emoji reactions. Learn document models, reducers, and real-time synchronization.
+    </p>
+    <a href="/academy/ExampleUsecases/Chatroom/CreateNewPowerhouseProject" className="path-button">Start tutorial</a>
+  </div>
+</div>
+
+<div className={styles.pathCard}>
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img src="/img/academy/icons/Editor.svg" alt="" className={styles.titleIcon} />
+      Todo List
+    </h3>
+  </div>
+  <div className={styles.cardContent}>
+    <p style={{ fontSize: '0.9rem', color: 'var(--ifm-color-content-secondary)', marginBottom: '1rem' }}>
+      Create a complete todo list application with document models, editors, and a custom drive explorer.
+    </p>
+    <a href="/academy/ExampleUsecases/TodoList/GetTheStarterCode" className="path-button">Start tutorial</a>
+  </div>
+</div>
+
+<div className={styles.pathCard}>
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img src="/img/academy/icons/Data.svg" alt="" className={styles.titleIcon} />
+      Vetra Package Library
+    </h3>
+  </div>
+  <div className={styles.cardContent}>
+    <p style={{ fontSize: '0.9rem', color: 'var(--ifm-color-content-secondary)', marginBottom: '1rem' }}>
+      Explore the Vetra package library and learn how to leverage existing packages in your projects.
+    </p>
+    <a href="/academy/ExampleUsecases/VetraPackageLibrary/VetraPackageLibrary" className="path-button">Explore library</a>
+  </div>
+</div>
+
+</div>
+

package/docs/academy/03-ExampleUsecases/Chatroom/02-CreateNewPowerhouseProject.md

@@ -75,14 +75,6 @@ A Powerhouse project primarily consists of a document model and its editor. The
 
 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)
@@ -115,7 +107,41 @@ Navigate to the newly created project directory:
 cd ChatRoom
 ```
 
-## Develop your document model in Connect
+## Develop your document model in Vetra Studio
+
+**Vetra Studio** is the builder's orchestration hub for assembling all specifications needed for your package. It provides a **Vetra Studio Drive** to access, manage, and share document model specifications, editors, and data integrations—all through a visual interface. For deeper coverage, see the [Vetra Studio documentation](/academy/MasteryTrack/BuilderEnvironment/VetraStudio).
+
+Once in the project directory, run the `ph vetra` command to start a Vetra Studio Drive where you'll be defining your specifications.
+
+```bash
+ph vetra
+```
+
+The host application for Vetra Studio will start and you will see the following output:
+
+```bash
+ℹ [reactor-api] [package-manager] Loading packages: @powerhousedao/vetra
+ℹ [reactor-api] [server] WebSocket server attached at /graphql/subscriptions
+ℹ [reactor-api] [graphql-manager] Registered /graphql/system subgraph.
+ℹ [reactor-api] [graphql-manager] Registered /graphql supergraph
+ℹ [reactor-api] [server] MCP server available at http://localhost:4001/mcp
+Switchboard initialized
+   ➜ Drive URL: http://localhost:4001/d/vetra-bac239dd
+  ➜  Local:   http://localhost:3000/
+  ➜  Network: use --host to expose
+  ➜  press h + enter to show help
+```
+
+A new browser window will open when visiting localhost and you will see the Vetra Studio Drive. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser.
+
+Create a new document model by clicking the Document Models **'Add new specification'** button. Name your document `ChatRoom` (PascalCase, no spaces or hyphens).
+
+**Pay close attention to capitalization, as it influences code generation.**
+
+If you've followed the steps correctly, you'll have an empty `ChatRoom` document where you can define the **'Document Specifications'**.
+
+<details>
+<summary>Alternatively: Develop a single document model in Connect</summary>
 
 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.
 
@@ -138,14 +164,10 @@ If your local drive is not present, navigate to Settings in the bottom left corn
 Clear the storage of your localhost application as it might have 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. Name your document `ChatRoom` (PascalCase, no spaces or hyphens).
-
-   **Pay close attention to capitalization, as it influences code generation.**
+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. Name your document `ChatRoom` (PascalCase, no spaces or hyphens).
 
-![Create New Document Model](./images/ChatRoomConnectApp.gif)
-
-If you've followed the steps correctly, you'll have an empty `ChatRoom` document where you can define the **'Document Specifications'**.
+</details>
 
 ## Verify your setup