@powerhousedao/academy 2.5.0-dev.2 → 2.5.0-dev.21

package/docs/academy/02-MasteryTrack/03-BuildingUserExperiences/01-BuildingDocumentEditors.md

@@ -1,4 +1,4 @@
-# Build Document Editors
+# Build Document Editors (WIP)
 
 ## Build with React on Powerhouse
 
@@ -6,7 +6,8 @@ At Powerhouse, frontend development for document editors follows a simple and fa
 
 ### Development Environment
 
-Connect Studio is your primary tool for development. When you run `ph connect`, it provides a dynamic, local environment where you can define and preview your document models and their editors live. This replaces the need for tools like Storybook for editor development, though Storybook remains invaluable for exploring the [Powerhouse Component Library](#powerhouse-component-library).
+Connect Studio is your primary tool for development.   
+When you run `ph connect`, it provides a dynamic, local environment where you can define and preview your document models and their editors live. This replaces the need for tools like Storybook for editor development, though Storybook remains invaluable for exploring the [Powerhouse Component Library](#powerhouse-component-library).
 
 Key aspects of the Powerhouse development environment:
 - **React Foundation**: Build your editor UIs using React components, just as you would in any standard React project.
@@ -20,7 +21,8 @@ Powerhouse aims to keep your developer experience clean, familiar, and focused:
 
 ### Generating Your Editor Template
 
-To kickstart your editor development, Powerhouse provides a command to generate a basic editor template. This command reads your document model definition and creates the initial `editor.tsx` file.
+To kickstart your editor development, Powerhouse provides a command to generate a basic editor template. This command reads your document model specifications and creates the initial `editor.tsx` file.
+If you want a refresher on how to define your document model specification please read the chapter on [specifying the State Schema](/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
 
 For example, to generate an editor for a `ToDoList` document model with a document type `powerhouse/todolist`:
 ```bash
@@ -72,40 +74,6 @@ You have several options for styling your editor components:
 
 Choose the method or combination of methods that best suits your project needs and team preferences. Connect Studio (`ph connect`) will allow you to see your styles applied in real-time.
 
-<details>
-<summary>Refresher on React Hooks</summary>
-
-All of the Powerhouse React Hooks can be found here: [Powerhouse React Hooks API Reference](docs/academy/APIReferences/ReactHooks)
-
-React Hooks allow you to use various React features directly within your functional components. You can use built-in Hooks or combine them to create your own custom Hooks.
-
-**What are Custom Hooks?**
-A custom hook is a JavaScript function whose name starts with "use" and that calls other Hooks. They are used to:
-- Reuse stateful logic between components.
-- Abstract complex logic into a simpler interface.
-- Isolate side effects, particularly those managed by `useEffect`.
-
-**Key Built-in Hooks Examples:**
-- `useState`: Lets a component "remember" information (state).
-- `useEffect`: Lets a component perform side effects (e.g., data fetching, subscriptions, manually changing the DOM).
-- `useContext`: Lets a component receive information from distant parent components without explicitly passing props through every level of the component tree.
-
-**Naming Convention:**
-Hook names must always start with `use` followed by a capital letter (e.g., `useState`, `useOnlineStatus`).
-
-**Rules of Hooks:**
-1.  **Only Call Hooks at the Top Level**: Don't call Hooks inside loops, conditions, or nested functions.
-2.  **Only Call Hooks from React Functions**: Call Hooks from React functional components or from custom Hooks.
-
-It's important to note that a function should only be named and treated as a hook if it actually utilizes one or more built-in React hooks. If a function (even if named `useSomething`) doesn't call any built-in hooks, it behaves like a regular JavaScript function, and making it a "hook" offers no specific React advantages.
-
-For more details, see the official documentation and our API reference:
-- [Reusing Logic with Custom Hooks (react.dev)](https://react.dev/learn/reusing-logic-with-custom-hooks)
-- [Rules of Hooks (react.dev)](https://react.dev/reference/rules/rules-of-hooks)
-- [Powerhouse React Hooks API Reference](docs/academy/APIReferences/ReactHooks)
-
-</details>
-
 ### State Management in Editors
 
 When you build an editor in Powerhouse, your main editor component receives `EditorProps`. These props are crucial for interacting with the document:

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

@@ -145,9 +145,10 @@ This command will **build** the project and create a build directory with the ou
 
 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: 
 
 ```bash
-pnpm serve (Not working yet)
+ph connect
 ```
 
 ### 1.4 Storing your project in a git repository
@@ -202,15 +203,79 @@ If you're publishing a package under a scope (like @your-org/my-package), you mi
 }
 ```
 
-For the actual publishing step, run the following command to publish your project to the npm registry:
+### 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.
+
+**1. Versioning with PNPM**
+
+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`).
+
+```bash
+# For a patch release (e.g., from 1.0.0 to 1.0.1)
+pnpm version patch
+
+# For a minor release (e.g., from 1.0.1 to 1.1.0)
+pnpm version minor
+
+# For a major release (e.g., from 1.1.0 to 2.0.0)
+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**
+
+Next, push your commits and the new version tag to your remote Git 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
+```
+
+**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).
+
+```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:
 ```bash
-npm publish
+pnpm publish --access public
 ```
 
-Optionally, if you are publishing a scoped package and you want it public, run:
+You can also publish a version to a specific NPM dist-tag. For example, to publish a beta version:
 ```bash
-npm publish --access public
+# Ensure your package.json version reflects the beta (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.
 

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

@@ -1,62 +1,23 @@
-# Powerhouse Setup Guide (WIP)
+# Powerhouse Setup Guide
 
 ## Introduction
-Powerhouse is a powerful platform that helps you manage and deploy your applications efficiently. This guide will walk you through the process of setting up both the Powerhouse CLI and configuring your server machine to run Powerhouse services. Whether you're setting up a development environment or preparing for production deployment, this guide provides all the necessary steps and considerations.
+Powerhouse is a powerful platform that helps you manage and deploy your applications efficiently.   
+This guide will walk you through the process of setting up both the Powerhouse CLI and configuring your server machine to run Powerhouse services. Whether you're setting up a development environment or preparing for production deployment, this guide provides all the necessary steps and considerations.
 
 ## Prerequisites
-Before you begin, ensure you have a Linux-based system (Ubuntu or Debian recommended), sudo privileges, and a stable internet connection. These are essential for the installation and configuration process. The system should have at least 1GB of RAM and 10GB of free disk space for optimal performance. While these are minimum requirements, more resources will provide better performance, especially when running multiple services.
+Before you begin, ensure you have a Linux-based system (Ubuntu or Debian recommended), sudo privileges, and a stable internet connection.   
+These are essential for the installation and configuration process. 
+The system should have at least 1GB of RAM and 10GB of free disk space for optimal performance. 
+While these are minimum requirements, more resources will provide better performance, especially when running multiple services.
 
-## 1. Setting up a new cloud environment
-
-The `install` script provides a streamlined way to install the Powerhouse CLI tool and all its necessary dependencies. This script handles the installation of node.js 22, pnpm, Powerhouse CLI itself and the services. It's designed to work across different Linux distributions, though it's optimized for Ubuntu and Debian-based systems. It also prepares your machine for running Powerhouse services. It handles everything from package installation to service configuration, making the setup process straightforward and automated. This script is particularly useful for setting up new servers or reconfiguring existing ones.
-
-
-### Installation Steps:
-1. Run the setup script:
-```bash
-curl -fsSL https://apps.powerhouse.io/install | bash # for macOS, Linux, and WSL
-```
-
-2. After installation, source your shell configuration:
-```bash
-source ~/.bashrc  # or source ~/.zshrc if using zsh
-```
-
-3. Verify the installation:
-```bash
-ph --version
-```
-
-4. You will see ph-cli is not yet installed. But it will get installed automatically in the next step. 
-If you are a builder that wants to make use of the dev releases use `ph use dev` before going to the next step. 
-   - `ph use dev`: Development version - Use this for testing new features or development work
-   - `ph use staging`: Staging version - Use this for pre-production testing
-
-5. Follow the interactive prompts:
-
-### Step 1: Package Installation
-During the package installation phase, you'll be prompted to enter package names that you want to install. For example, you might want to install `@powerhousedao/todo-demo-package` or other Powerhouse packages. This step is crucial for adding the specific functionality you need to your Powerhouse installation. You can press Enter to skip this step if you don't need to install any packages immediately, but you can always install packages later using the `ph install` command.
-
-### Step 2: Database Configuration
-The script offers two options for database configuration. 
-
-**Option 1:** Sets up a local PostgreSQL database, which is ideal for development or small deployments. It automatically creates a database user with a secure random password and configures the database to accept local connections. This option is perfect for getting started quickly or for development environments. 
-
-**Option 2:** Allows you to connect to a remote PostgreSQL database by providing a connection URL in the format `postgres://user:password@host:port/db`. This is recommended for production environments where you might want to use a managed database service or a dedicated database server.
-
-### Step 3: SSL Configuration
-For SSL configuration, you have two choices. 
-
-**Option 1:** The **Let's Encrypt** option is recommended for production environments. It requires you to provide a base domain (like `powerhouse.xyz`) and optional subdomains for your services. The script will automatically obtain and configure SSL certificates for your domains, ensuring secure communication between your services and clients. 
-
-**Option 2:** The self-signed certificate option is suitable for development or testing environments. It uses your machine's hostname and generates a self-signed certificate, configuring the services with appropriate base paths. While this option is convenient for development, browsers will show security warnings, which is why it's not recommended for production use.
+Also make sure you have your preferred domain registered and created subdomains for your Connect & Switchboard instances.
 
 <details>
-<summary>Setting up a domain in DigitalOcean</summary>
+<summary>**Setting up a Droplet (Digital Ocean) instance and connecting your domain**</summary>
 
 This tutorial will guide you through the process of creating a new virtual private server (called a "Droplet") on DigitalOcean and then pointing your custom domain name to it. This will allow users to access your server using a memorable URL like `www.yourdomain.com`.
 
-**Current Date:** May 15, 2025
+**Current Date:** May 15, 2024
 
 ## Part 1: Setting Up Your DigitalOcean Droplet
 
@@ -156,6 +117,18 @@ Now your Droplet is running! Now you can continue with the Powerhouse tutorial o
      - **WILL DIRECT TO:** Your Droplet's IP
      - **TTL:** 3600
 
+   - **Connect Subdomain (A Record):**
+     - **TYPE:** A
+     - **HOSTNAME:** connect
+     - **WILL DIRECT TO:** Your Droplet's IP
+     - **TTL:** 3600
+
+   - **Switchboard Subdomain (A Record):**
+     - **TYPE:** A
+     - **HOSTNAME:** switchboard
+     - **WILL DIRECT TO:** Your Droplet's IP
+     - **TTL:** 3600
+
 #### Option B: Using Your Existing Nameservers (NS locked)
 
 1. **Just Create DNS Records at Your Registrar:**
@@ -171,6 +144,18 @@ Now your Droplet is running! Now you can continue with the Powerhouse tutorial o
      - **VALUE:** Your Droplet's IP
      - **TTL:** 3600
 
+   - **Connect Subdomain (A Record):**
+     - **TYPE:** A
+     - **HOSTNAME:** connect
+     - **VALUE:** Your Droplet's IP
+     - **TTL:** 3600
+
+   - **Switchboard Subdomain (A Record):**
+     - **TYPE:** A
+     - **HOSTNAME:** switchboard
+     - **VALUE:** Your Droplet's IP
+     - **TTL:** 3600
+
 **Note:** DNS changes may take up to 48 hours to propagate globally.
 
 ### Verify Configuration
@@ -179,20 +164,43 @@ Now your Droplet is running! Now you can continue with the Powerhouse tutorial o
    ```bash
    dig +short yourdomain.com
    dig +short www.yourdomain.com
+   dig +short connect.yourdomain.com
+   dig +short switchboard.yourdomain.com
    ```
 
-2. Both should return your Droplet's IP address
+2. All should return your Droplet's IP address
 
 **Congratulations!** You have successfully set up your DigitalOcean Droplet and configured your domain. Your server is now ready to host your Powerhouse services.
 
 </details>
 
 <details>
-<summary>Setting up a domain with AWS EC2</summary>
+<summary> **Setting up an EC2 instance and connecting your domain** </summary>
 
 This tutorial will guide you through the process of assigning a static IP (Elastic IP) to your EC2 instance and configuring your domain to point to it.
 
-**Current Date:** May 15, 2025
+**Current Date:** May 15, 2024
+
+   - Make sure your region is set to eu-west-1 (Ireland)
+   - Name your instance something like `cloud-server` or your project's name
+   - Select Ubuntu 24.04 LTS
+   - Architecture 64-bit (x86)
+   - Scroll down to Instance type and select t2.medium (recommended)
+      - 2 vCPUs and 4 GiB of memory are the recommended minimum specs
+      - For larger projects or higher load, consider t2.large or t2.xlarge
+   - Create a new key pair and save it in a secure location from which you can connect to your instance with the SSH client later.
+   - Configure the security group to allow inbound traffic:
+      - SSH (Port 22) from your IP address
+      - HTTP (Port 80) from anywhere
+      - HTTPS (Port 443) from anywhere
+      - Custom TCP (Port 8442) for Connect
+      - Custom TCP (Port 8441) for Switchboard
+   - **Launch the instance**
+
+   :::warning
+   Make sure to keep your key pair file (.pem) secure and never share it. Without it, you won't be able to access your instance. Also, consider setting up AWS IAM roles and policies for better security management.
+   :::
+
 
 ## Part 1: Assigning a Static IP to EC2 Instance
 
@@ -247,6 +255,18 @@ This tutorial will guide you through the process of assigning a static IP (Elast
      - **VALUE:** Your Elastic IP
      - **TTL:** 3600
 
+   - **Connect Subdomain (A Record):**
+     - **TYPE:** A
+     - **HOSTNAME:** connect
+     - **VALUE:** Your Elastic IP
+     - **TTL:** 3600
+
+   - **Switchboard Subdomain (A Record):**
+     - **TYPE:** A
+     - **HOSTNAME:** switchboard
+     - **VALUE:** Your Elastic IP
+     - **TTL:** 3600
+
 ### Option B: Using Your Existing Nameservers
 
 1. **Create DNS Records at Your Registrar:**
@@ -262,6 +282,18 @@ This tutorial will guide you through the process of assigning a static IP (Elast
      - **VALUE:** Your Elastic IP
      - **TTL:** 3600
 
+   - **Connect Subdomain (A Record):**
+     - **TYPE:** A
+     - **HOSTNAME:** connect
+     - **VALUE:** Your Elastic IP
+     - **TTL:** 3600
+
+   - **Switchboard Subdomain (A Record):**
+     - **TYPE:** A
+     - **HOSTNAME:** switchboard
+     - **VALUE:** Your Elastic IP
+     - **TTL:** 3600
+
 1. **Set Up DNS First:**
    - Create A records for all subdomains before running the setup script
    - Point them to your EC2 instance's public IP address
@@ -273,27 +305,80 @@ This tutorial will guide you through the process of assigning a static IP (Elast
    ```bash
    dig +short yourdomain.com
    dig +short www.yourdomain.com
+   dig +short connect.yourdomain.com
+   dig +short switchboard.yourdomain.com
    ```
 
-2. Both should return your Elastic IP address
+2. All should return your Elastic IP address
 
 **Congratulations!** You have successfully set up your EC2 instance with a static IP and configured your domain. Your server is now ready to host your Powerhouse services.
 
 </details>
 
-### Step 4: Service Configuration
+## 1. Setting up a new cloud environment
+
+The `install` script provides a streamlined way to install the Powerhouse CLI tool and all its necessary dependencies. This script handles the installation of Node.js 22, pnpm, and the Powerhouse CLI itself. It's designed to work across different Linux distributions, though it's optimized for Ubuntu and Debian-based systems. It also prepares your machine for running Powerhouse services. It handles everything from package installation to service configuration, making the setup process straightforward and automated. This script is particularly useful for setting up new servers or reconfiguring existing ones.
+
+### Installation
+
+1.  Run the setup script:
+    ```bash
+    curl -fsSL https://apps.powerhouse.io/install | bash # for macOS, Linux, and WSL
+    ```
+
+2.  After installation, source your shell configuration:
+    ```bash
+    source ~/.bashrc  # or source ~/.zshrc if using zsh
+    ```
+
+3.  Verify that the Powerhouse CLI is ready to be installed in the next step:
+    ```bash
+    ph --version
+    ```
+    You will see that `ph-cli` is not yet installed. This is expected, as it will be installed by the service setup command.
+
+4. Create a project with `ph-init <projectname>`. After creation, move into the project with `cd <projectname>`. 
+   Up next is the configurations of your services. 
+
+### Service Configuration
+
+Next, run `ph service setup` and follow the interactive prompts. This command installs the Powerhouse services (Connect and Switchboard) and guides you through their configuration.
+
+:::info
+**What does `ph service setup` do?**
+The script takes care of all the necessary service configuration automatically.
+It installs and configures **Nginx** as a reverse proxy, sets up SSL certificates, and configures the proxy settings for optimal performance.
+It also installs **PM2** for process management and starts your services with the appropriate configuration based on your SSL choice.
+The Nginx configuration includes optimizations for **WebSocket connections**, static file serving, and security headers.
+PM2 is configured to automatically restart services if they crash and to start them on system boot.
+:::
+
+The setup command will prompt you for the following information:
+
+#### Package Installation
+During this phase, you can enter package names that you want to install. For example, you might want to `ph install @powerhousedao/todo-demo-package` or other Powerhouse packages. This step is crucial for adding the specific functionality you need. You can also press Enter to skip this step and install packages later using the `ph install` command.
+
+#### Database Configuration
+The script offers two options for database configuration:
+*   **Option 1: Local Database** Sets up a local PostgreSQL database, which is ideal for development or small deployments. It automatically creates a database user with a secure random password and configures the database to accept local connections. This option is perfect for getting started quickly.
+*   **Option 2: Remote Database** Allows you to connect to a remote PostgreSQL database by providing a connection URL in the format `postgres://user:password@host:port/db`. This is recommended for production environments.
 
-The script takes care of all the necessary service configuration automatically. It installs and configures **Nginx** as a reverse proxy, sets up SSL certificates, and configures the proxy settings for optimal performance. It also installs **PM2** for process management and starts your services with the appropriate configuration based on your SSL choice. The Nginx configuration includes optimizations for **WebSocket connections**, static file serving, and security headers. PM2 is configured to automatically restart services if they crash and to start them on system boot.
+#### SSL Configuration
+For SSL configuration, you have two choices:
+*   **Option 1: Let's Encrypt (Recommended for Production)** This option requires you to provide a base domain (e.g., `powerhouse.xyz`) and subdomains for your services. The script will automatically obtain and configure SSL certificates for your domains.
+*   **Option 2: Self-signed Certificate** This is suitable for development or testing. It uses your machine's hostname and generates a self-signed certificate. Browsers will show security warnings with this option.
 
-### Step 5: Security Features
-Security is a top priority in the setup process. The script implements automatic SSL certificate management, generates secure database passwords, and configures security headers in Nginx. It also sets up proper proxy settings to support WebSocket connections securely. The security headers include protection against common web vulnerabilities, and the SSL configuration uses modern cipher suites and protocols. The script also ensures that sensitive files and directories have appropriate permissions.
+#### Domain Setup
+You will be asked to enter your `connect` and `switchboard` subdomains to complete the setup. If you need more information, revisit the cloud provider setup sections at the beginning of this guide.
 
+#### Security Features
+Security is a top priority. The script implements automatic SSL certificate management, generates secure database passwords, and configures security headers in Nginx, and sets up proper proxy settings to support WebSocket connections securely.
 
-## 3. Verifying the Setup
+## 2. Verifying the Setup
 
 After the installation is complete, it's important to verify that everything is working correctly. You can check the status of your services using PM2, verify the Nginx configuration, and ensure your SSL certificates are properly installed. This step is crucial for identifying any potential issues before they affect your users.
 
-1. Check service status of switchboard & connect:
+1. Check service status of switchboard and connect:
 ```bash
 ph service status
 ```
@@ -302,7 +387,7 @@ You can also use
 ```bash
 ph service start | stop | restart 
 ```
-- to start | stop | restart switchboard and connect
+to start | stop | restart switchboard and connect
 
 2. View Nginx configuration:
 ```bash
@@ -314,9 +399,10 @@ sudo nginx -t
 sudo certbot certificates  # if using Let's Encrypt
 ```
 
-## 4. Accessing Services
+## 3. Accessing the Services
 
-Once everything is set up, you can access your services through the configured domains. If you chose Let's Encrypt, your services will be available at their respective subdomains. With a self-signed certificate, you'll access the services through your machine's hostname with the appropriate base paths. The services are configured to use HTTPS by default, ensuring secure communication.
+Once everything is set up, you can access your services through the configured domains.   
+If you chose Let's Encrypt, your services will be available at their respective subdomains. With a self-signed certificate, you'll access the services through your machine's hostname with the appropriate base paths. The services are configured to use HTTPS by default, ensuring secure communication.
 
 ### With Let's Encrypt:
 - Connect: `https://connect.yourdomain.com`
@@ -326,18 +412,18 @@ Once everything is set up, you can access your services through the configured d
 - Connect: `https://your-hostname/connect`
 - Switchboard: `https://your-hostname/switchboard`
 
-## 5. Troubleshooting
+## 4. Troubleshooting
 
 When issues arise, there are several common problems you might encounter. 
-- The "ph: command not found" error usually means you need to source your shell configuration file. 
+- The "`ph`: command not found" error usually means you need to source your shell configuration file. 
 - Nginx configuration errors can be investigated through the error logs, and service issues can be diagnosed using PM2 logs. 
 - SSL certificate problems often relate to DNS settings or certificate paths. Understanding these common issues and their solutions will help you maintain a stable Powerhouse installation.
 
 ### Common Issues:
-1. **"ph: command not found"**
+1. **"`ph`: command not found"**
    - Run `source ~/.bashrc` or restart your terminal
-   - Verify that the PNPM_HOME environment variable is set correctly
-   - Check if the ph binary exists in the PNPM_HOME directory
+   - Verify that the `PNPM_HOME` environment variable is set correctly
+   - Check if the `ph` binary exists in the `PNPM_HOME` directory
 
 2. **Nginx configuration errors**
    - Check logs: `sudo tail -f /var/log/nginx/error.log`
@@ -354,7 +440,7 @@ When issues arise, there are several common problems you might encounter.
    - Check certificate paths in Nginx config
    - Ensure that the certificate files are readable by Nginx
 
-## 6. Maintenance
+## 5. Maintenance
 
 Regular maintenance is crucial for keeping your Powerhouse installation running smoothly. You can update services using the Powerhouse CLI, restart services through PM2, and monitor logs to ensure everything is functioning correctly. Regular maintenance helps prevent issues and ensures that your services are running with the latest security patches and features.
 
@@ -368,16 +454,16 @@ ph update <package-name>
 ph service restart
 ```
 
-### Viewing Logs:
+### Checking Service Status and Logs:
 ```bash
 ph service status
 ```
 
-## 7. Security Notes
+## 6. Security Notes
 
 Maintaining security is an ongoing process. It's essential to keep your database credentials secure and regularly update your SSL certificates. Regular monitoring of system logs helps identify potential security issues, and keeping your system and packages updated ensures you have the latest security patches. Consider implementing additional security measures such as firewall rules, intrusion detection systems, and regular security audits.
 
-## 8. Backup
+## 7. Backup
 
 Regular backups are crucial for data safety. The database can be backed up using pg_dump, and your configuration files can be archived using tar. These backups should be stored securely and tested regularly to ensure they can be restored if needed. Consider implementing an automated backup schedule and storing backups in multiple locations for redundancy.
 
@@ -391,7 +477,7 @@ pg_dump -U powerhouse -d powerhouse > backup.sql
 sudo tar -czf powerhouse-config.tar.gz /etc/powerhouse/
 ```
 
-## 9. Best Practices
+## 8. Best Practices
 
 To get the most out of your Powerhouse installation, follow these best practices:
 
@@ -401,7 +487,7 @@ To get the most out of your Powerhouse installation, follow these best practices
 4. **Testing**: Test your backup and restore procedures regularly.
 5. **Security**: Regularly review and update your security measures.
 
-## 10. Getting Help
+## 9. Getting Help
 
 If you encounter issues or need assistance, there are several resources available:
 

package/docs/academy/02-MasteryTrack/05-Launch/{03-RunOnACloudServer.md → _03-RunOnACloudServer}

@@ -17,7 +17,8 @@ Let's have a look at how to set up Connect & Switchboard apps on a cloud server.
 Ask your IT provider to get access to the AWS environment to set up a server.
 Launch a new server instance for Connect and Switchboard with the specific specs that fit your project.
 
-The steps to create an EC2 instance:
+<details>
+<summary> **The steps to create an EC2 instance** </summary>
    - Make sure your region is set to eu-west-1 (Ireland)
    - Name your instance something like `cloud-server` or your project's name
    - Select Ubuntu 24.04 LTS
@@ -34,13 +35,15 @@ The steps to create an EC2 instance:
       - Custom TCP (Port 8441) for Switchboard
    - **Launch the instance**
 
+   :::warning
+   Make sure to keep your key pair file (.pem) secure and never share it. Without it, you won't be able to access your instance. Also, consider setting up AWS IAM roles and policies for better security management.
+   :::
+
+</details>
+
 Now click on your instance ID, which will open a new window with the instance details. Hit the 'Connect' button to get the connection details.
 Within the instance details, you'll find the public IP address of your server instance. We'll use this to connect to our server instance later.
 
-:::warning
-Make sure to keep your key pair file (.pem) secure and never share it. Without it, you won't be able to access your instance. Also, consider setting up AWS IAM roles and policies for better security management.
-:::
-
 ### 1.2. Setting up your SSH connection
 
 Once you've generated your key pairs and added them to the designated folder, you can set up the SSH connections to start the process.

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

@@ -2,10 +2,12 @@
 
 ### Installing the Powerhouse CLI 
 :::tip
-The **Powerhouse CLI tool** is the only essential tool to install on this page. Install it with the command below. 
+The **Powerhouse CLI tool** is the only essential tool to install on this page. Install it with the command below.    
+
 You can find all of the commands on this page, similar to what would displayed when using ph --help or ph *command* --help. 
-Use the table of content or the search function to find what you are looking for.
-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:
+Use the table of content or the search function to find what you are looking for.   
+
+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.
 
 ```bash
 pnpm install -g ph-cmd
@@ -208,7 +210,7 @@ Examples:
 
 ---
 
-*This document was automatically generated from the help text in the codebase.*\n\n### ph-cli Commands\n\n- [Connect Build](#connect-build)
+- [Connect Build](#connect-build)
 - [Connect Preview](#connect-preview)
 - [Connect Studio](#connect-studio)
 - [Dev](#dev)
@@ -702,39 +704,4 @@ Notes:
 
 ---
 
-*This document was automatically generated from the help text in the codebase.*\n<!-- AUTO-GENERATED-CLI-COMMANDS-END -->
-
-<details>
-<summary> How to make use of 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.
-
-| Command | Description |
-|---------|-------------|
-| **pnpm install -g ph-cmd** | Install latest stable version |
-| **pnpm install -g ph-cmd@dev** | Install development version |
-| **pnpm install -g ph-cmd@staging** | Install staging version |
-| **ph init** | Use latest stable version of the boilerplate |
-| **ph init --dev** | Use development version of the boilerplate |
-| **ph init --staging** | Use staging version of the boilerplate |
-| **ph use** | Switch all dependencies to latest production versions |
-| **ph use dev** | Switch all dependencies to development versions |
-| **ph use prod** | Switch all dependencies to production versions |
-
-Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
-</details>
-
-
-the ph connect command now uses three subcommands:
-
-studio (default) — runs connect studio. since this is the default argument, running ph connect still has the same behavior as before,
-
-build — bundles the project's local and external model/editor code and injects the js/css into the already-built connect bundle for deployment,
-
-preview — runs the vite preview server with the output of build for testing purposes,
-
-running ph connect --help now lists the sub-commands. Running ph connect studio --help now shows the help for the studio command, likewise for the other new commands.
-
-This approach avoids redundant build/compilation which is great for minimizing server resource use. The only compilation that runs is the esbuild of the project code (does not need tsc as that is handled separately) and then tailwind for the local project styles. The whole thing takes less than a second, albeit on my macbook.
-
-This should just work with the current boilerplate since these are just new arguments to the existing ph-cli connect command. 
+*This document was automatically generated from the help text in the codebase.* <!-- AUTO-GENERATED-CLI-COMMANDS-END -->