@powerhousedao/academy 2.5.0-dev.23 → 2.5.0-dev.25

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 2.5.0-dev.25 (2025-06-13)
+
+### 🚀 Features
+
+- start dependent services with switchboard ([188c82c6a](https://github.com/powerhouse-inc/powerhouse/commit/188c82c6a))
+
+### 🩹 Fixes
+
+- **docker:** request write permissions ([29d4d3fd7](https://github.com/powerhouse-inc/powerhouse/commit/29d4d3fd7))
+
+### ❤️ Thank You
+
+- Frank
+
+## 2.5.0-dev.24 (2025-06-13)
+
+### 🚀 Features
+
+- added hostnames in docker compose ([a590eea17](https://github.com/powerhouse-inc/powerhouse/commit/a590eea17))
+- **docker-compose:** work with published images ([9f31b70fb](https://github.com/powerhouse-inc/powerhouse/commit/9f31b70fb))
+- **ci:** build and publish docker images on newly created tags ([ee930c4a4](https://github.com/powerhouse-inc/powerhouse/commit/ee930c4a4))
+
+### ❤️ Thank You
+
+- Frank
+
 ## 2.5.0-dev.23 (2025-06-13)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/01-WhatIsADocumentModel.md

@@ -5,7 +5,13 @@ This chapter on **Document Model Creation** will help you with an in depth pract
 If you have completed the Get Started tutorial you will revisit familiar topics. 
 :::
 
-A Document Model is: 
+:::info **Definition: What is a Document Model?**
+A Document Model is a programmable document structure that defines how data is stored, changed, and interpreted in a decentralized system. It acts like a living blueprint—capturing state, tracking changes, and enabling interaction through defined operations.
+:::
+
+For instance, an invoice document model might define fields like issuer, lineItems, and status, with operations such as AddLineItem and MarkAsPaid.
+
+A Document Model can be understood as: 
 - A structured software framework that represents and **manages business logic** within a digital environment. 
 - A sophisticated template that **encapsulates the essential aspects of a digital process or a set of data**. 
 - A blueprints that define how data is **captured, manipulated, and visualised** within a system. 
@@ -184,14 +190,16 @@ This removes the need for **complex database joins** and allows for **fast, stru
 
 Document Models offer a range of features that can be leveraged to create sophisticated, automated, and data-driven solutions:
 
-- **API Integration**: Document Models can be integrated with Switchboard API or external APIs, allowing for the exchange of data between Connect and other systems or services.
-
-- **Data Analysis**: The structured nature of Document Models makes them ideal for data analysis and reporting. Users can extract insights and generate reports based on the data captured within the models which is accessible through read models. (Operational data + Analytics data which takes into account time series of the data). 
-
-- **Version Control**: Similar to how Git manages changes to source code, Document Models in Connect will support version control, enabling users to track changes, compare different versions, and ensure data integrity over time.
+- **Automation**: Automate workflows using consistent, structured document logic.
+- **Auditability**: Maintain a full history of changes for compliance and transparency.
+- **API Integration**: Seamlessly connect with Switchboard or external APIs for data exchange.
+- **Data Analysis**: Enable real-time and historical insights through structured read models.
+- **Version Control**: Track and compare document states over time, similar to Git.
+- **Collaboration**: Empower decentralized teams to build, modify, and share documents asynchronously.
+- **Extensibility**: Add new fields, operations, and integrations over time without rewriting logic.
 
 Document Models are a powerful primitive within the Powerhouse vision, offering a flexible, structured, and efficient way to manage business logic and data. 
 
 ### Up Next: How to build a Document Model
 
-In the next chapters, we'll teach you how to build a ToDoList document model while explaining all of the theory that is involved. 
+In the next chapters, we'll teach you how to build a ToDoList document model while explaining all of the theory that is involved. d

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/03-SpecifyDocumentOperations.md

@@ -114,6 +114,6 @@ export const reducer: ToDoListToDoListOperations = {
 
 ## Conclusion
 
-Specifying document operations is a foundational step in building robust and predictable document models in Powerhouse. By clearly defining the "what" (the operation and its input) before implementing the "how" (the reducer logic), you create a clear contract for state transitions. This approach enhances type safety, testability, and the overall maintainability of your document model.
+Specifying document operations is a foundational step in building robust and predictable document models in Powerhouse. By clearly defining the **"what" (the operation and its input)** before implementing the **"how" (the reducer logic)**, you create a clear contract for state transitions. This approach enhances type safety, testability, and the overall maintainability of your document model.
 
 In the next section, we will dive deeper into the implementation of the reducer functions for these specified operations.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/07-ExampleToDoListRepository.md

@@ -1 +1,41 @@
-# Example: ToDoList Repo
+# Example: ToDo Demo Package
+
+:::info
+
+The ToDo Demo package is maintained by the Powerhouse Team and serves as a reference for testing and introducing new features. It will be continuously updated alongside the accompanying documentation.
+
+https://github.com/powerhouse-inc/todo-demo-package
+:::
+
+There are several ways to explore this package:
+
+### Option 1: Rebuild the ToDo Demo Package
+
+The ToDo Demo package and repository are your main reference points during the Mastery Track.  
+Follow the steps in the "Mastery Track – Document Model Creation" chapters to build along with the examples.
+
+### Option 2: Clone and Run the Code Locally
+
+The package includes:  
+- The Document Model  
+- Reducer Code  
+- Reducer Tests  
+- Editor Code  
+- Drive Explorer Code  
+
+You can clone the repository and run Connect Studio to see all the code in action:
+
+```bash
+ph connect
+```
+
+### Option 3: Install the ToDo Demo Package in a (Local) Host App
+
+Alternatively, you can install this package in a Powerhouse project or in your deployed host apps:
+
+```bash
+ph install @powerhousedao/todo-demo-package
+```
+
+
+

package/docs/academy/05-Architecture/00-PowerhouseArchitecture.md

@@ -12,6 +12,9 @@ These five applications are:
 
 Each application is designed to be modular yet complementary, ensuring smooth data flows, structured collaboration, and scalable automation. The functionality of the four host apps offers an integrated experience for running decentralized operations.
 
+![Powerhouse Host Apps Interaction](./images/PowerhouseArchitecture.png)
+
+
 ## How the Five Applications Work Together
 
 The Powerhouse ecosystem functions as a decentralized operating system, where each of the four core applications works in synergy to ensure seamless collaboration, structured data management, and automated workflows. Each application has a distinct purpose, yet their interconnectivity is what makes the system powerful.

package/docs/academy/06-ComponentLibrary/04-ScalarVsUIComponents.md

@@ -1,6 +1,6 @@
 import { Tabs, TabItem } from '@theme/Tabs';
 
-# Scalar Component Example
+# Scalar vs. UI component
 
 Scalars are here to help you define custom fields in your document model schema and speed up the development process.
 There are two applications of scalar components in the document model workflow:
@@ -8,45 +8,21 @@ There are two applications of scalar components in the document model workflow:
 1. At the **schema definition** level where you build your schema and write your GraphQL state schema.
 2. At the **frontend / react** level where you import it and place it in your UI to represent the scalar field
 
-## Scalar Definition in the Document Model Schema
+## Overview
+The Document Engineering library provides two main categories of components.
 
-As you might know, the document model schema defines the structure of the document and serves as the backbone of the document model. The GraphQL state schema defines how data is captured with the help of types & scalars. When you define a scalar in the document model schema, you are essentially defining a new field that can be used in the document model to capture data.
+https://github.com/powerhouse-inc/document-engineering
 
-In the Document Model Editor, you can find all the custom scalar types available under the 'Scalars' section.
+### Scalar Components
 
-Insert image of the feature. @callme-t
+These are specialized form components, each corresponding to a GraphQL scalar type (e.g., String, Number, Boolean, Currency, PHID). They are built on top of react-hook-form, offering out-of-the-box validation but must be wrapped with a Form component in order to work properly.
 
-## React Component Implementation in the Frontend
+Location: @powerhousedao/document-engineering/scalars
 
-All of our reusable components are available in the Document-Engineering system package.
-This package comes as a dependency in your project when creating a new document model project.
-````
-import PHIDField from 'document-engineering'
-const reactComponent = () => {
+**Key Feature**: Must be used within a Form component provided by this library.
 
-return (
-  <div>
-    <PHIDField
-      fetchOptionsCallback={function Js(){}}
-      fetchSelectedOptionCallback={function Js(){}}
-      label="PHID field"
-      name="phid-field"
-      placeholder="phd:"
-    />
+### General-Purpose UI Components
 
-  </div>
-  
-  )
-
-}
-````
-
-## Scalars & Reusable Components
-
-To make your life easier, Powerhouse has defined all useful scalars with a set of reusable code and UI components.
-The reusable components are essentially a set of front-end components based on GraphQL scalars. Powerhouse also has a set of custom scalars that are not part of the GraphQL standard but are specific to the web3 ecosystem.
-
-Read the next chapter to get familiar with our reusable components. 
-
-# PHID Field Implementation Example
+This category includes a broader range of UI elements such as simplified versions of the Scalar components (which don't require a Form wrapper but lack built-in validation), as well as other versatile components like Dropdown, Tooltip, Sidebar, ObjectSetTable and more. These are designed for crafting diverse and complex user interfaces.
 
+Location: @powerhousedao/document-engineering/ui

package/docs/academy/07-Cookbook.md

@@ -337,6 +337,75 @@ ph init --package-manager pnpm
 - [Bun Installation Guide](https://bun.sh/docs/installation#how-to-add-your-path)
 </details>
 
+## Powerhouse Environment Recipes
+This section covers recipes for setting up and managing Powerhouse environments, from local development to production servers.
+
+<details id="setting-up-a-production-environment">
+<summary>Setting up a Production Environment</summary>
+
+## How to Set Up a Production Powerhouse Environment
+---
+
+## Problem Statement
+You need to set up a new production-ready server to host and run your Powerhouse services (Connect and Switchboard).
+
+## Prerequisites
+- A Linux-based server (Ubuntu or Debian recommended) with `sudo` privileges.
+- A registered domain name.
+- DNS `A` records for your `connect` and `switchboard` subdomains pointing to your server's public IP address.
+
+## Solution
+
+### Step 1: Install Powerhouse Services
+SSH into your server and run the universal installation script. This will install Node.js, pnpm, and prepare the system for Powerhouse services.
+```bash
+curl -fsSL https://apps.powerhouse.io/install | bash
+```
+
+### Step 2: Reload Your Shell
+After the installation, reload your shell's configuration to recognize the new commands.
+```bash
+source ~/.bashrc  # Or source ~/.zshrc if using zsh
+```
+
+### Step 3: Initialize a Project
+Create a project directory for your services. The `ph-init` command sets up the basic structure. Move into the directory after creation.
+```bash
+ph-init my-powerhouse-services
+cd my-powerhouse-services
+```
+
+### Step 4: Configure Services
+Run the interactive setup command. This will guide you through configuring Nginx, PM2, databases, and SSL.
+```bash
+ph service setup
+```
+During the setup, you will be prompted for:
+-   **Packages to install:** You can pre-install any Powerhouse packages you need. (Optional)
+-   **Database:** Choose between a local PostgreSQL setup or connecting to a remote database.
+-   **SSL Certificate:** Select Let's Encrypt for a production setup. You will need to provide your domain and subdomains.
+
+## Expected Outcome
+- Powerhouse Connect and Switchboard services are installed, configured, and running on your server.
+- Nginx is set up as a reverse proxy with SSL certificates from Let's Encrypt.
+- Services are managed by PM2 and will restart automatically on boot or if they crash.
+- You can access your services securely at `https://connect.yourdomain.com` and `https://switchboard.yourdomain.com`.
+
+## Common Issues and Solutions
+- **Issue:** `ph: command not found`
+  - **Solution:** Ensure you have reloaded your shell with `source ~/.bashrc` or have restarted your terminal session.
+- **Issue:** Let's Encrypt SSL certificate creation fails.
+  - **Solution:** Verify that your domain's DNS records have fully propagated and are pointing to the correct server IP. This can take some time.
+- **Issue:** Services fail to start.
+  - **Solution:** Check the service logs for errors using `ph service logs` or `pm2 logs`.
+
+## Related Recipes
+- [Installing a Custom Powerhouse Package](#installing-a-custom-powerhouse-package)
+
+## Further Reading
+- [Full Setup Guide](/academy/MasteryTrack/Launch/SetupEnvironment)
+</details>
+
 ## Powerhouse Project Recipes
 This section focuses on creating, configuring, and managing Powerhouse projects, which are collections of document models, editors, and other resources.
 
@@ -923,6 +992,80 @@ You need to understand and manage different types of dependencies in your Powerh
 
 </details>
 
+<details id="packaging-and-publishing-a-powerhouse-project">
+<summary>Packaging and Publishing a Powerhouse Project</summary>
+
+## How to Package and Publish a Powerhouse Project
+---
+
+## Problem Statement
+You have created a collection of document models, editors, or other components and want to share it as a reusable package on a public or private npm registry. Publishing a package allows other projects to install and use your creations easily.
+
+## Prerequisites
+- A completed Powerhouse project that you are ready to share.
+- An account on [npmjs.com](https://www.npmjs.com/) (or a private registry).
+- Your project's `package.json` should have a unique name and correct version.
+- You must be logged into your npm account via the command line.
+
+## Solution
+
+### Step 1: Build the Project
+First, compile your project to create a production-ready build in the `dist/` or `build/` directory.
+
+```bash
+pnpm build
+```
+
+### Step 2: Log In to npm
+If you aren't already, log in to your npm account. You will be prompted for your username, password, and one-time password.
+
+```bash
+npm login
+```
+
+### Step 3: Version Your Package
+Update the package version according to semantic versioning. This command updates `package.json` and creates a new Git tag.
+
+```bash
+# Choose one depending on the significance of your changes
+pnpm version patch   # For bug fixes (e.g., 1.0.0 -> 1.0.1)
+pnpm version minor   # For new features (e.g., 1.0.1 -> 1.1.0)
+pnpm version major   # For breaking changes (e.g., 1.1.0 -> 2.0.0)
+```
+
+### Step 4: Publish the Package
+Publish your package to the npm registry. If it's your first time publishing a scoped package (e.g., `@your-org/your-package`), you may need to add the `--access public` flag.
+
+```bash
+npm publish --access public
+```
+
+### Step 5: Push Git Commits and Tags
+Push your new version commit and tag to your remote repository to keep it in sync.
+
+```bash
+# Push your current branch
+git push
+
+# Push the newly created version tag
+git push --tags
+```
+
+## Expected Outcome
+- Your Powerhouse project is successfully published to the npm registry.
+- Other developers can now install your package into their projects using `ph install @your-org/your-package-name`.
+- Your Git repository is updated with the new version information.
+
+## Common Issues and Solutions
+- **Issue**: "403 Forbidden" or "You do not have permission" error on publish.
+  - **Solution**: Ensure your package name is unique and not already taken on npm. If it's a scoped package (`@scope/name`), make sure the organization exists and you have permission to publish to it. For public scoped packages, you must include `--access public`.
+
+## Related Recipes
+- [Installing a Custom Powerhouse Package](#installing-a-custom-powerhouse-package)
+- [Managing Powerhouse Dependencies and Versions](#managing-powerhouse-dependencies-and-versions)
+
+</details>
+
 ## Data Synchronisation Recipes
 This section helps troubleshoot and understand data synchronization within the Powerhouse ecosystem, including interactions between different services and components.
 
@@ -988,3 +1131,69 @@ Understanding the different GraphQL endpoints in Powerhouse is crucial for effec
     -   **Solution:** Consider cleaning the global Powerhouse setup by removing `~/.ph`
     
 </details>
+
+<details id="clearing-package-manager-caches">
+<summary>Clearing Package Manager Caches</summary>
+
+## How to Clear Package Manager Caches
+---
+
+## Problem Statement
+You are encountering unexpected issues with dependencies, `ph-cmd` installation, or package resolution. Corrupted or outdated caches for your package manager (pnpm, npm, yarn) can often be the cause. Clearing the cache forces the package manager to refetch packages, which can resolve these problems.
+
+## Prerequisites
+- Terminal or command prompt access
+- A package manager (pnpm, npm, or yarn) installed
+
+## Solution
+
+Choose the commands corresponding to the package manager you are using.
+
+### For pnpm
+`pnpm` has a robust set of commands to manage its content-addressable store.
+
+```bash
+# Verify the integrity of the cache
+pnpm cache verify
+
+# Remove orphaned packages from the store
+pnpm store prune
+```
+
+### For npm
+`npm` provides commands to clean and verify its cache.
+
+```bash
+# Verify the contents of the cache folder, which can fix some issues
+npm cache verify
+
+# If verification doesn't solve the issue, force clean the cache
+npm cache clean --force
+```
+
+### For Yarn (v1 Classic)
+Yarn Classic allows you to list and clean the cache.
+
+```bash
+# List the contents of the cache
+yarn cache list
+
+# Clean the cache
+yarn cache clean --force
+```
+
+## Expected Outcome
+- The package manager's cache is cleared or verified.
+- Subsequent installations will fetch fresh versions of packages, potentially resolving dependency-related errors.
+- Your system is in a cleaner state for managing Powerhouse project dependencies.
+
+## Common Issues and Solutions
+- **Issue**: Problems persist after clearing the cache.
+  - **Solution**: The issue might not be cache-related. Consider completely removing `node_modules` and lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`) and running `pnpm install` (or equivalent) again.
+
+## Related Recipes
+- [Installing 'ph-cmd'](#installing-ph-cmd)
+- [Uninstalling 'ph-cmd'](#uninstalling-ph-cmd)
+- [Managing Powerhouse Dependencies and Versions](#managing-powerhouse-dependencies-and-versions)
+
+</details>

package/docs/academy/08-Glossary.md

@@ -25,61 +25,60 @@
 - **Renown (Login Flow)** – The Powerhouse decentralized login process using an Ethereum wallet signature to generate/retrieve a user's DID for secure, pseudonymous actions.
 - **Powerhouse Switchboard (Verifier Role)** – A function of Powerhouse Switchboard that validates DIDs and credentials for operations submitted via Connect, ensuring they are authorized.
 
-## Development & Data Modeling
+## Document Modeling
 - **Action Creators (for Document Operations)** – Auto-generated helper functions creating structured "action" objects for dispatching operations to a document model's reducer.
 - **Actions (Document Actions)** – Typed objects representing an intent to change a document's state, dispatched to reducers, containing an operation type and input data.
 - **API Integration (for Document Models)** – The capability of Document Models to connect with Switchboard API or external APIs, facilitating data exchange between Powerhouse applications and other systems.
-- **Boilerplate (Powerhouse Project)** – The `ph init` command's initial project structure, providing a standard starting point for new Powerhouse packages.
-- **Connect Build** – The output of the `ph connect build` command, which packages a Connect project into a distributable format. This build includes all necessary local/external packages, assets, and styles, and can be previewed locally with `ph connect preview` or deployed.
 - **Data Analysis (with Document Models)** – Leveraging the structured data within Document Models, often via read models, to extract insights, generate reports, and perform analytics on operational and historical data.
-- **Development Environment (Powerhouse)** – A local setup for developing Powerhouse applications, typically initiated with the `ph dev` command. It runs essential backend services like the Powerhouse Switchboard to enable real-time document model processing, code generation, and live updates, separate from the front-end Connect Studio.
 - **Dispatch (in Document Models)** – The act of sending an action (representing an operation) to a document model's reducer to trigger a state update.
-- **Document Model Editors** – An interface or UI to a document model that allows users to create and modify the data captured by the document models.
 - **Document Model Specification** – The formal definition of a document model (state, operations), created in Connect Studio (using GraphQL SDL) and exported (e.g., `.phdm.zip`) for code generation.
 - **Document Models** – Structured data models that define how Powerhouse documents store and process information.
 - **Document State** – The current data held by a document instance, structured according to its Document Model.
 - **Document Type** – A unique string identifier (e.g., `powerhouse/todolist`) for a Document Model, used by host apps to select the correct editor/logic.
-- **Drive** – A logical container in Powerhouse for storing, organizing, and managing collections of documents.
-- **Drive App (Custom Drive Explorer)** – A UI application, often custom, providing tailored views and interactions with documents in a Drive.
-- **Environments (Powerhouse Environments)** – Pre-defined configurations for a project's Powerhouse dependencies, such as `dev` (development), `prod` (production/latest), and `local`. The Powerhouse CLI (`ph use` command) allows developers to easily switch between these environments to use different versions of packages (e.g., bleeding-edge, stable, or from a local monorepo).
 - **Event History (Append-Only Log)** – An immutable, append-only log where every operation applied to a Powerhouse document is stored as an event. It provides a transparent audit trail and enables features like time travel debugging and state reconstruction.
 - **GraphQL Scalars** – Data types used in Powerhouse document modeling (e.g., `String`, `Int`, `Currency`, `OID` for unique object IDs).
 - **GraphQL Schema Definition Language (SDL) (for Document Models)** – Language used in Connect Studio to define a Document Model's data structure (state) and operations.
-- **Host Applications** – Applications that use the Powerhouse framework to create and manage documents and data.
+- **Immutable Updates** – A principle where data is never altered in place; operations create new data versions, vital for Powerhouse's event sourcing.
 - **Input Types (GraphQL for Document Operations)** – Custom data structures in SDL detailing parameters for document operations (e.g., `AddTodoItemInput`).
 - **Model-Driven Development (MDD)** – A software approach that uses high-level models to generate system logic and configurations.
-- **Modules (in Document Model Editor)** – An organizational feature in Connect Studio's model editor for grouping related operations.
 - **Operations (Document Operations)** – Named commands (e.g., `ADD_TODO_ITEM`) in a Document Model representing all ways to change its state, forming its event log.
 - **Powerhouse Document (`.phd` file)** – Standard file extension for an exported Powerhouse document instance, containing its data and history.
-- **Powerhouse Package** – A collection of document models, document model editors, and other resources that are published as a package and can be used in any of the host applications.
-- **Powerhouse Project** – A collection of document models, document model editors, and other resources being build in Connect Studio.
 - **Pure Functions (for Reducers)** – Principle that document model reducers must be pure (output depends only on input, no side effects) for predictable state transitions.
 - **Reducers (Document Model Reducers)** – Functions implementing a Document Model's logic; for each operation, a reducer takes current state and an action, returning new state.
 - **Replay Events** – The process of re-applying recorded events from a document's Event History to reconstruct or restore its state, a core capability of Event Sourcing.
-- **Scalars (Design System Components)** – Reusable UI building blocks (e.g., `Checkbox`, `InputField`) from `@powerhousedao/document-engineering/scalars`, used in editors (distinct from GraphQL scalars).
 - **State (Global State in Document Model)** – The primary, persisted, shared data of a document instance, managed by its reducers.
-- **State (Local State in Editor)** – Temporary, UI-specific data within an editor (e.g., form inputs), not persisted in the global document state.
 - **State Schema** – The component of a Document Model that defines the structure of the document, including its fields, data types, and validation rules, typically using a GraphQL-like syntax. It serves as a blueprint for how data is stored and validated.
-- **Storybook (for Powerhouse Design System)** – Interactive environment for browsing and testing Powerhouse Design System UI components.
 - **Strands** – A single synchronization channel that connects exactly one unit of synchronization to another, with all four parameters (drive_url, doc_id, scope, branch) set to fixed values. This allows synchronization between two distinct points of instances of a document or document drive.
-- **Tailwind CSS (in Connect Studio)** – Utility CSS framework integrated into Connect Studio for styling document editors.
 - **Time Travel Debugging** – A debugging technique, enabled by a document's Event History, that allows developers to reconstruct and inspect past states of the document by replaying events up to a specific point in time.
 - **Type Safety (in Document Modeling)** – Powerhouse's use of auto-generated TypeScript definitions from a model's schema (SDL) to prevent data type errors in development.
 - **Version Control (for Document Models)** – A planned feature for Document Models in Connect that will allow tracking of changes, comparison of different versions, and maintenance of data integrity over time, similar to version control systems for source code.
 
+## Development & Tooling
+- **Boilerplate (Powerhouse Project)** – The `ph init` command's initial project structure, providing a standard starting point for new Powerhouse packages.
+- **Connect Build** – The output of the `ph connect build` command, which packages a Connect project into a distributable format. This build includes all necessary local/external packages, assets, and styles, and can be previewed locally with `ph connect preview` or deployed.
+- **Development Environment (Powerhouse)** – A local setup for developing Powerhouse applications, typically initiated with the `ph dev` command. It runs essential backend services like the Powerhouse Switchboard to enable real-time document model processing, code generation, and live updates, separate from the front-end Connect Studio.
+- **Document Model Editors** – An interface or UI to a document model that allows users to create and modify the data captured by the document models.
+- **Drive** – A logical container in Powerhouse for storing, organizing, and managing collections of documents.
+- **Drive App (Custom Drive Explorer)** – A UI application, often custom, providing tailored views and interactions with documents in a Drive.
+- **Environments (Powerhouse Environments)** – Pre-defined configurations for a project's Powerhouse dependencies, such as `dev` (development), `prod` (production/latest), and `local`. The Powerhouse CLI (`ph use` command) allows developers to easily switch between these environments to use different versions of packages (e.g., bleeding-edge, stable, or from a local monorepo).
+- **Host Applications** – Applications that use the Powerhouse framework to create and manage documents and data.
+- **Modules (in Document Model Editor)** – An organizational feature in Connect Studio's model editor for grouping related operations.
+- **Powerhouse Package** – A collection of document models, document model editors, and other resources that are published as a package and can be used in any of the host applications.
+- **Powerhouse Project** – A collection of document models, document model editors, and other resources being build in Connect Studio.
+- **Scalars (Design System Components)** – Reusable UI building blocks (e.g., `Checkbox`, `InputField`) from `@powerhousedao/document-engineering/scalars`, used in editors (distinct from GraphQL scalars).
+- **State (Local State in Editor)** – Temporary, UI-specific data within an editor (e.g., form inputs), not persisted in the global document state.
+- **Storybook (for Powerhouse Design System)** – Interactive environment for browsing and testing Powerhouse Design System UI components.
+- **Tailwind CSS (in Connect Studio)** – Utility CSS framework integrated into Connect Studio for styling document editors.
+
 ## AI & Automation
 - **AI Assistants** – AI-powered contributors paired with human contributors to automate tasks and improve productivity.
 - **AI Contributor Modes** – Configurable states that determine the AI assistant's behavior, permissions, and task focus.
 - **Task Automation & Scaling** – The use of AI to streamline repetitive tasks, improve communications, and enhance decision-making.
 - **Decentralized Identifier (DID)** – A user-controlled, globally unique ID, used in Renown to link a user's blockchain key to actions pseudonymously.
-- **Immutable Updates** – A principle where data is never altered in place; operations create new data versions, vital for Powerhouse's event sourcing.
-- **Type Safety (in Document Modeling)** – Powerhouse's use of auto-generated TypeScript definitions from a model's schema (SDL) to prevent data type errors in development.
 
 ## Organizational Concepts
 - **Ceramic** – A decentralized network for storing verifiable data, used by Powerhouse Renown for secure credential management.
 - **Decentralized Identifier (DID)** – A user-controlled, globally unique ID, used in Renown to link a user's blockchain key to actions pseudonymously.
-- **Event History (Append-Only Log)** – An immutable, append-only log where every operation applied to a Powerhouse document is stored as an event. It provides a transparent audit trail and enables features like time travel debugging and state reconstruction.
 - **Event-Driven Architecture (EDA)** – A software design approach where system flows are determined by events that trigger actions asynchronously.
-- **Immutable Updates** – A principle where data is never altered in place; operations create new data versions, vital for Powerhouse's event sourcing.
 - **Network Organization** – A group of independent contributors and teams working together towards a common purpose, relying on decentralization and resource sharing.
 

package/docs/academy/09-AIResources.md

@@ -2,8 +2,130 @@
 
 We have a couple of AI resources to help you with your daily work or exploring our ecosystem. 
 
+:::warning
+- Be aware that AI tooling can make mistakes.    
+- Documentation can be out of date or code can be work in progress.    
+- Always verify your coding agent's suggestions. 
+:::
+
+
 | Tool | Description |
 |---|---|
-| [**Deepwiki**](https://deepwiki.com/powerhouse-inc/powerhouse) | A searchable/queriable wiki to understand our growing mono repo better. <br /> DeepWiki provides up-to-date documentation you can talk to, for every repo in the world. Think Deep Research for GitHub. |
-| [**Context7**](https://context7.com/powerhouse-inc/powerhouse) | The Powerhouse Academy is also available as context through the context7 MCP Server. <br /> LLMs rely on outdated or generic information about the libraries you use. <br /> Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. <br /> Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM. |
+| [**Deepwiki**](https://deepwiki.com/powerhouse-inc/powerhouse) | A searchable/queriable wiki to understand our growing Powerhouse **Monorepository** better. <br /> DeepWiki provides up-to-date documentation you can talk to, for every repo in the world. Think Deep Research for GitHub. |
+| [**Context7**](https://context7.com/powerhouse-inc/powerhouse) | The Powerhouse **Academy Documentation** is also available as context through the context7 MCP Server. <br /> LLMs rely on outdated or generic information about the libraries you use. <br /> Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. <br /> Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM. <br /> The official repository can be found [here](https://github.com/upstash/context7). |
+
+
+### Context7 Installation
+
+<details>
+<summary><b>Install in Cursor</b></summary>
+
+Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
+
+Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder.
+
+**Cursor Local Server Connection**
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in VS Code</b></summary>
+
+Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
+
+**VS Code Local Server Connection**
+
+```json
+"mcp": {
+  "servers": {
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}
+```
+</details>
+
+For other editors, please refer to the [official documentation](https://github.com/upstash/context7#%-installation).
+
+### Context7 Troubleshooting
+
+<details>
+<summary><b>MCP, Documentation or Module Not Found Errors</b></summary>
+
+If you encounter `ERR_MODULE_NOT_FOUND`, try using `bunx` instead of `npx`:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "bunx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}
+```
+
+This often resolves module resolution issues in environments where `npx` doesn't properly install or resolve packages.
+
+</details>
+
+<details>
+<summary><b>ESM Resolution Issues</b></summary>
+
+For errors like `Error: Cannot find module 'uriTemplate.js'`, try the `--experimental-vm-modules` flag:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>TLS/Certificate Issues</b></summary>
+
+Use the `--experimental-fetch` flag to bypass TLS-related problems:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>General MCP Client Errors</b></summary>
+
+1. Try adding `@latest` to the package name
+2. Use `bunx` as an alternative to `npx`
+3. Consider using `deno` as another alternative
+4. Ensure you're using Node.js v18 or higher for native fetch support
+
+</details>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "2.5.0-dev.23",
+  "version": "2.5.0-dev.25",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",