@powerhousedao/academy 0.1.0-dev.5 → 2.5.0-dev.0

package/CHANGELOG.md

@@ -1,3 +1,57 @@
+## 2.5.0-dev.0 (2025-06-04)
+
+### 🚀 Features
+
+- **academy:** centralize husky & auto-update cli docs ([8c92e0bb1](https://github.com/powerhouse-inc/powerhouse/commit/8c92e0bb1))
+- **ph-cli:** added setup-service command ([dfa082aa6](https://github.com/powerhouse-inc/powerhouse/commit/dfa082aa6))
+- **scripts:** updated setup scripts ([9f7fa7644](https://github.com/powerhouse-inc/powerhouse/commit/9f7fa7644))
+- enforce conventional commits ([faa49da40](https://github.com/powerhouse-inc/powerhouse/commit/faa49da40))
+- removed scalars package ([d6f7059a7](https://github.com/powerhouse-inc/powerhouse/commit/d6f7059a7))
+- enabled switchboard command ([5a9c467bf](https://github.com/powerhouse-inc/powerhouse/commit/5a9c467bf))
+- removed scalars dependencies ([596aedbd5](https://github.com/powerhouse-inc/powerhouse/commit/596aedbd5))
+- **builder-tools:** handle recursive objects in initial state generator ([c9eedcc43](https://github.com/powerhouse-inc/powerhouse/commit/c9eedcc43))
+- **monorepo:** bump graphql lib ([ba9d5d338](https://github.com/powerhouse-inc/powerhouse/commit/ba9d5d338))
+- **monorepo:** handle updating monorepo build deps ([db2ac2316](https://github.com/powerhouse-inc/powerhouse/commit/db2ac2316))
+- **monorepo:** regenerate lockfile ([a6c390b4e](https://github.com/powerhouse-inc/powerhouse/commit/a6c390b4e))
+- **builder-tools:** fix wrong value used for field id ([a6c6142e0](https://github.com/powerhouse-inc/powerhouse/commit/a6c6142e0))
+- **reactor-api,reactor-local:** updated analytics dependencies ([cbeace573](https://github.com/powerhouse-inc/powerhouse/commit/cbeace573))
+
+### 🩹 Fixes
+
+- **academy:** docker build ([58e83be09](https://github.com/powerhouse-inc/powerhouse/commit/58e83be09))
+- **academy:** lockfile issue second time' ([6208fe614](https://github.com/powerhouse-inc/powerhouse/commit/6208fe614))
+- **academy:** fix frozen lockfile issue' ([80f18ec73](https://github.com/powerhouse-inc/powerhouse/commit/80f18ec73))
+- **academy:** fix frozen lockfile issue ([bfc3dcd21](https://github.com/powerhouse-inc/powerhouse/commit/bfc3dcd21))
+- **pre-commit:** use bash syntax and shebang ([da00ff581](https://github.com/powerhouse-inc/powerhouse/commit/da00ff581))
+- added missing dep to academy ([4ec6c8278](https://github.com/powerhouse-inc/powerhouse/commit/4ec6c8278))
+- **academy:** clean up husky script ([e18e26cd8](https://github.com/powerhouse-inc/powerhouse/commit/e18e26cd8))
+- **academy:** deployment ([36e5f194d](https://github.com/powerhouse-inc/powerhouse/commit/36e5f194d))
+- **switchboard:** docker build ([7052e39e1](https://github.com/powerhouse-inc/powerhouse/commit/7052e39e1))
+- docker build with PH_PACKAGES ([856ac1187](https://github.com/powerhouse-inc/powerhouse/commit/856ac1187))
+- **document-drive:** fix type issue on browser storage ([240a78b41](https://github.com/powerhouse-inc/powerhouse/commit/240a78b41))
+- **ph-cli:** ph add does not remove installed packages ([aedfbf56e](https://github.com/powerhouse-inc/powerhouse/commit/aedfbf56e))
+- remove .env and add to .gitignore ([0d2d48684](https://github.com/powerhouse-inc/powerhouse/commit/0d2d48684))
+- **switchboard,reactor-local:** latest version of sky atlas was not being installed ([72bf72fd4](https://github.com/powerhouse-inc/powerhouse/commit/72bf72fd4))
+
+### ❤️ Thank You
+
+- acaldas @acaldas
+- Benjamin Jordan
+- Callme-T
+- Frank
+- Guillermo Puente @gpuente
+- ryanwolhuter @ryanwolhuter
+
+## 0.1.0-dev.6 (2025-06-04)
+
+### 🩹 Fixes
+
+- **academy:** docker build ([58e83be09](https://github.com/powerhouse-inc/powerhouse/commit/58e83be09))
+
+### ❤️ Thank You
+
+- Frank
+
 ## 0.1.0-dev.5 (2025-06-03)
 
 ### 🩹 Fixes

package/Dockerfile

@@ -11,7 +11,7 @@ ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
 WORKDIR /app
 COPY . .
 RUN chmod +x entrypoint.sh
-RUN pnpm install --frozen-lockfile
+RUN pnpm install
 RUN pnpm build
 ENV PORT=3000
 EXPOSE $PORT

package/docs/academy/01-GetStarted/00-ExploreDemoPackage.md

@@ -33,6 +33,13 @@ This command downloads and sets up the Contributor Billing package, making its f
 
 You have now successfully installed `ph-cmd` and added your first package! 
 
+:::info 
+WORK IN PROGRESS @callmet
+Let's explore what exactly you can do with this package
+- Document model
+- Drive App
+:::
+
 ## Step 3: Run the Connect App in Studio mode
 To run the package locally in Connect Studio (our collaboration and contributor app), run the `ph connect` command. 
 
@@ -40,7 +47,6 @@ To run the package locally in Connect Studio (our collaboration and contributor
 
 Renown is Powerhouse's decentralized identity and reputation system designed to address the challenge of trust within DAOs, where contributors often operate under pseudonyms. In traditional organizations, personal identity and reputation are key to establishing trust and accountability. Renown replicates this dynamic in the digital space, allowing contributors to earn experience and build reputation without revealing their real-world identities.
 
-
 :::tip
 When signing in with Renown, use an Ethereum or blockchain address that can function as your \'identity\', as this address will accrue more experience and history over time.
 :::

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

@@ -1,7 +1,7 @@
-# Create a new ToDoList Document
+# Create a ToDoList Document
 
 ## Overview
-This tutorial guides you through creating a 'Powerhouse project' for a ToDoList. A Powerhouse project primarily consists of a document model and its editor. You'll be using Connect locally, known as 'Studio mode'.
+This tutorial guides you through creating a 'Powerhouse project' for a **ToDoList**. A Powerhouse project primarily consists of a document model and its editor. You'll be using Connect locally, known as 'Studio mode'.
 
 ## Prerequisites
 - Powerhouse CLI installed: `pnpm install -g ph-cmd`

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

@@ -1,22 +1,21 @@
 # Define the ToDoList document specification 
 
-In this tutorial, you will learn how to define the specifications for a `ToDoList` document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
+In this tutorial, you will learn how to define the specifications for a **ToDoList** document model within the Connect application using its GraphQL schema, and then export the resulting document model specification document for your Powerhouse project.
 If you don't have a document specification file created yet, have a look at the previous step of this tutorial to create a new document specification.
 
 Before you start, make sure you have the Connect application running locally with the command `ph connect`
 
 ## ToDoList Document Specification
 
-Likely you have called your project 'ToDoList'. If you've used a different name, please create a new document specification named 'ToDoList'. Pay close attention to capitalization, as it influences our code.
+Likely you have called your project 'ToDoList'. If you've used a different name, please create a new document specification named 'ToDoList'. **Pay close attention to capitalization, as it influences our code.**  
+
 We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model. Below, you can see the SDL for the `ToDoList` document model.
 
 :::info
 This schema defines the **data structure** of the document model and the types involved in its operations, which are detailed further as input types.
-Documents in Powerhouse leverage **event sourcing principles**, where every state transition is represented by an operation. GraphQL input types describe operations, ensuring that user intents are captured effectively. These operations detail the parameters needed for state transitions. The use of GraphQL aligns these transitions with explicit, validated, and reproducible commands, supporting **CQRS** (Command Query Responsibility Segregation) patterns.
+Documents in Powerhouse leverage **event sourcing principles**, where every state transition is represented by an operation. GraphQL input types describe operations, ensuring that user intents are captured effectively. These operations detail the parameters needed for state transitions. The use of GraphQL aligns these transitions with explicit, validated, and reproducible commands.
 :::
 
-
-
 <details>
 <summary>State Schema of our ToDoList</summary>
 

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

@@ -6,24 +6,12 @@ To export the document model specification, follow the steps in the [Define ToDo
 
 ## Understanding Reducers in Document Models
 
-Reducers are a core concept in Powerhouse document models. They implement the state transition logic for each operation defined in your schema:
+Reducers are a core concept in Powerhouse document models. They implement the state transition logic for each operation defined in your schema.
 
-1. **Connection to Schema Definition Language (SDL)**: The reducers directly implement the operations you defined in your SDL. Remember how we defined `AddTodoItemInput`, `UpdateTodoItemInput`, and `DeleteTodoItemInput` in our schema? The reducers provide the actual implementation of what happens when those operations are performed.
+**Connection to Schema Definition Language (SDL)**: The reducers directly implement the operations you defined in your SDL. Remember how we defined `AddTodoItemInput`, `UpdateTodoItemInput`, and `DeleteTodoItemInput` in our schema?   
+The reducers provide the actual implementation of what happens when those operations are performed.
 
-2. **Event Sourcing Pattern**: Document models in Powerhouse follow event sourcing principles, where each operation is recorded in the document's history. The current state of the document is derived by applying all operations in sequence.
-
-3. **Immutable Updates**: While the reducer code appears to modify the state directly, Powerhouse handles immutability behind the scenes. Each operation produces a new document state without modifying the previous one.
-
-4. **Type Safety**: Powerhouse generates TypeScript types from your SDL, ensuring that your reducers and operations are type-safe.
-
-5. **Pure Functions**: Reducers should be pure functions that depend only on the current state and the operation input, making them predictable and testable.
-
-Let's see how these concepts are implemented in our **ToDoList** document model.
-
-## Importing the Document Model Specification and Generating Code
-
-To import the document model specification into your Powerhouse project, you can either:
- 
+To import the document model specification into your Powerhouse project, you can either: 
 - Copy and paste the file directly into the root of your Powerhouse project.
 - Or drag and drop the file into the Powerhouse project directory in the VSCode editor as seen in the image below:
 

package/docs/academy/01-GetStarted/home.mdx

@@ -71,7 +71,7 @@ import BrowserOnly from '@docusaurus/BrowserOnly';
     </div>
     <div className={styles.cardContent}>
       <a href="/docs/academy/GetStarted/BuildToDoListEditor" className="path-button">Building a Todo-list Editor</a>
-      <a href="/docs/academy/BuildingUserExperiences/BuildingBeautifulDocumentEditors" className="path-button">Building Document Editors</a>
+      <a href="/docs/academy/BuildingUserExperiences/BuildingDocumentEditors" className="path-button">Building Document Editors</a>
       <a href="/docs/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer" className="path-button">Building Custom Drive Explorers</a>
       <a href="/docs/academy/ComponentLibrary/DocumentEngineering" className="path-button">Component Library</a>
     </div>

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/03-BuilderTools.md

@@ -1,6 +1,7 @@
 # Powerhouse Builder Tooling
 
 This page provides an overview of all the builder tooling offered by the Powerhouse ecosystem.
+This list will be maintained and updated as our toolkit grows.
 
 ## Powerhouse Command Line Interface
 ___

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

@@ -181,7 +181,7 @@ Document Models offer a range of features that can be leveraged to create sophis
 
 - **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 Analysi**s**: 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). 
+- **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.
 

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

@@ -1,7 +1,7 @@
 {
     "label": "Document Model Creation",
     "link": {
-      "type": "generated-index",
-      "description": "This tutorial will guide you through the process of creating an advanced to-do list document model in Powerhouse, while getting you familiar with the Powerhouse document model framework."
+      "type": "doc",
+      "id": "academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel"
     }
   }

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

@@ -0,0 +1,233 @@
+# Build Document Editors
+
+## Build with React on Powerhouse
+
+At Powerhouse, frontend development for document editors follows a simple and familiar flow, leveraging the power and flexibility of React.
+
+### 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).
+
+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.
+- **Automatic Build Processes**: Tailwind CSS is installed by default and fully managed by Connect Studio. There's no need to manually configure or run Tailwind or other build processes during development. Connect Studio handles CSS generation and other necessary build steps automatically, especially when you publish a package.
+- **Styling Flexibility**: You are not limited to Tailwind. Regular CSS (`.css` files), inline styles, and any React-compatible styling method work exactly as you would expect.
+
+Powerhouse aims to keep your developer experience clean, familiar, and focused:
+- Build React components as you normally would.
+- Use styling approaches you're comfortable with.
+- Trust Connect Studio to handle the setup and build processes for you.
+
+### 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.
+
+For example, to generate an editor for a `ToDoList` document model with a document type `powerhouse/todolist`:
+```bash
+ph generate --editor ToDoList --document-types powerhouse/todolist
+```
+This will create the template in the `editors/to-do-list/editor.tsx` folder.
+
+### Styling Your Editor
+
+You have several options for styling your editor components:
+
+1.  **Default HTML Styling**: Standard HTML tags (`<h1>`, `<p>`, `<button>`, etc.) will render with default browser styles or any base styling provided by the Connect environment. This is suitable for basic structure and quick prototyping.
+
+2.  **Tailwind CSS**: Connect Studio comes with Tailwind CSS integrated. You can directly use Tailwind utility classes in your JSX for rapid and consistent styling without writing separate CSS files.
+    *Example (from the ToDoList Editor):*
+    ```typescript
+    <div className="container mx-auto p-4 max-w-md">
+        <h1 className="text-2xl font-bold mb-4">To-do List</h1>
+        {/* ... more Tailwind styled elements */}
+    </div>
+    ```
+
+3.  **Custom CSS Files**: You can import traditional CSS files (`.css`) to apply custom styles or integrate existing style libraries.
+    *Create an `editor.css` file in your editor's directory:*
+    ```css
+    /* editors/your-editor/editor.css */
+    .editor-container {
+        padding: 1rem;
+        border: 1px solid #ccc;
+    }
+    .editor-title {
+        color: navy;
+        font-size: 1.8rem;
+    }
+    ```
+    *Import and use it in your `editor.tsx`:*
+    ```typescript
+    import './editor.css'; // Import the CSS file
+
+    export default function Editor(props: IProps) {
+        return (
+            <div className="editor-container">
+                <h1 className="editor-title">My Document Title</h1>
+                {/* ... */}
+            </div>
+        );
+    }
+    ```
+
+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:
+
+*   **`document`**: This object contains the entire document structure, including its current state. You'll typically access the global document state via `document.state.global`.
+*   **`dispatch`**: This function is your gateway to modifying the document's state. You call `dispatch` with an action object (usually created by action creators from your document model's generated code) to signal an intended change.
+
+**Local vs. Global State:**
+*   **Local Component State**: For UI-specific state that doesn't need to be part of the persisted document model (e.g., the current text in an input field before submission, visibility of a dropdown), use React's `useState` hook.
+    ```typescript
+    const [inputValue, setInputValue] = useState('');
+    // ...
+    <input value={inputValue} onChange={(e) => setInputValue(e.target.value)} />
+    ```
+*   **Global Document State**: For data that is part of the document itself and should be saved (e.g., the items in a to-do list), you modify it by dispatching actions. The `document.state.global` object provides read-only access to this state within your editor.
+
+**Dispatching Actions:**
+Your document model's generated code (e.g., in `document-models/your-model/index.js` or `document-models/your-model/gen/operations.js`) will provide action creators.
+```typescript
+// Assuming 'actions' are imported from your document model
+// import { actions } from '../../document-models/to-do-list/index.js';
+
+// Inside your editor component:
+// function Editor({ document, dispatch }: IProps) {
+//   ...
+//   const handleAddItem = () => {
+//     if (todoItem.trim()) {
+//       dispatch(actions.addTodoItem({ // Dispatch action to add item.
+//         id: Math.random().toString(), // Generate a simple unique ID
+//         text: todoItem,
+//       }));
+//       setTodoItem(''); // Clear local input state
+//     }
+//   };
+// }
+```
+The actual state modification logic resides in your document model's reducers, ensuring that all changes are consistent and follow the defined operations.
+
+## Powerhouse Component Library
+
+Powerhouse provides a rich set of reusable UI components through the **`@powerhousedao/document-engineering/scalars`** package. These components are designed for consistency, efficiency, and seamless integration with the Powerhouse ecosystem, with many based on GraphQL scalar types.
+
+### Exploring Components
+You can explore available components, see usage examples, and understand their properties (props) using our Storybook instance:
+[https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
+
+Storybook allows you to:
+*   Visually inspect each component.
+*   Interact with different states and variations.
+*   View code snippets for basic implementation.
+*   Consult the props table for detailed configuration options.
+
+### Using Components
+1.  **Import**: Add an import statement at the top of your editor file:
+    ```typescript
+    import { Checkbox, StringField, Form } from '@powerhousedao/document-engineering/scalars';
+    ```
+2.  **Implement**: Use the component in your JSX, configuring it with props:
+    ```typescript
+    // Example using StringField for an input
+    <Form onSubmit={() => { /* Handle submission */ }}>
+      <StringField
+        name="taskName"
+        label="New Task"
+        value={taskText} // From local state
+        onChange={(e) => setTaskText(e.target.value)}
+      />
+    </Form>
+    ```
+
+### Creating Local Wrapper Components
+Sometimes, you might want to create local wrapper components in your editor's project to encapsulate specific configurations or behaviors for library components. This was demonstrated in the "Build a ToDoList Editor" tutorial with `Checkbox.tsx` and `InputField.tsx` components, which internally used `BooleanField` and `StringField` from the `@powerhousedao/document-engineering/scalars` library.
+
+**Example: Local `Checkbox` Wrapper (conceptual)**
+```typescript
+// editors/to-do-list/components/checkbox.tsx
+import { Form, BooleanField } from "@powerhousedao/document-engineering/scalars";
+
+interface CustomCheckboxProps {
+  value: boolean;
+  onChange: (value: boolean) => void;
+  label?: string; // Added custom prop or passed through
+}
+
+export const Checkbox = ({ value, onChange, label }: CustomCheckboxProps) => {
+  return (
+    <Form onSubmit={() => { /* May not be needed for simple checkbox */ }}>
+      <BooleanField 
+        name="customChecked" // Internal name for the form field
+        description={label || "Toggle state"} // Use label for description
+        value={value}
+        onChange={onChange}
+      />
+    </Form>
+  );
+};
+```
+This pattern helps keep your main editor file cleaner and allows for more complex compositions.
+
+## Conceptual Example: Building a ToDoList Editor
+
+Let's consider key aspects of building an editor like the `ToDoList` example:
+
+1.  **Input for New Items**:
+    *   Use a local `useState` to manage the text of the new to-do item.
+    *   Use an `InputField` (or a `StringField` from the library) for text entry.
+    *   On "Add" button click or "Enter" key press, `dispatch` an `addTodoItem` action with the current input value.
+
+2.  **Displaying List Items**:
+    *   Map over `document.state.global.items`.
+    *   For each item, display its `text` and a `Checkbox`.
+    *   The `Checkbox` `value` should be bound to `item.checked`.
+    *   Its `onChange` handler should `dispatch` an `updateTodoItem` action to toggle the `checked` status.
+
+3.  **Editing Items**:
+    *   Implement local state (`editingItemId`, `editedText`) to manage which item is being edited and its current text.
+    *   Conditionally render either the item text (display mode) or an input field (edit mode).
+    *   When entering edit mode, populate `editedText` with the item's current text.
+    *   On saving the edit (e.g., "Enter" key in the input), `dispatch` an `updateTodoItem` action with the new text.
+
+4.  **Deleting Items**:
+    *   Provide a delete button/icon next to each item.
+    *   Its `onClick` handler should `dispatch` a `deleteTodoItem` action with the item's `id`.
+
+By combining local React state for UI control with dispatched actions for document state mutations, and leveraging the Powerhouse Component Library, you can build powerful and interactive document editors. Always refer to your document model's defined operations and state schema as the source of truth for how data should be structured and modified.

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

@@ -1,8 +1,7 @@
 {
-    "label": "Build User Experiences",
-    "position": 4,
-    "link": {
-      "type": "generated-index",
-      "description": "Learn how to build beautiful document editors and drive-apps in Connect."
-    }
-  }
+  "label": "Building User Experiences",
+  "link": {
+    "type": "doc",
+    "id": "academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors"
+  }
+}

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

@@ -6,67 +6,36 @@ Powerhouse is a powerful platform that helps you manage and deploy your applicat
 ## 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.
 
-## 1. Installing Powerhouse CLI
+## 1. Setting up a new cloud environment
 
-The `install-tools.sh` 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.
+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. Download the setup script:
-```bash
-curl -O https://raw.githubusercontent.com/powerhouse-inc/powerhouse/refs/heads/main/scripts/install-tools.sh
-```
-
-2. Make the script executable:
-```bash
-chmod +x install-tools.sh
-```
 
-3. Run the script:
+### Installation Steps:
+1. Run the setup script:
 ```bash
-./install-tools.sh
+curl -fsSL https://apps.powerhouse.io/install | bash # for macOS, Linux, and WSL
 ```
 
-4. Choose a version when prompted:
-   - `dev`: Development version - Use this for testing new features or development work
-   - `staging`: Staging version - Use this for pre-production testing
-   - RECOMMENDED: `latest`: Latest stable version - Recommended for production environments
-   - Press Enter to go ahead with the latest version
-
-5. After installation, source your shell configuration:
+2. After installation, source your shell configuration:
 ```bash
 source ~/.bashrc  # or source ~/.zshrc if using zsh
 ```
 
-6. Verify the installation:
+3. Verify the installation:
 ```bash
 ph --version
 ```
 
-## 2. Configuring Your Machine
-
-Download the setup script:
-```bash
-curl -O  https://raw.githubusercontent.com/powerhouse-inc/powerhouse/refs/heads/main/scripts/setup-environment.sh
-```
-
-The `setup-environment.sh` script is a comprehensive tool that 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.
+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
 
-### Configuration Steps:
-
-1. Make the script executable:
-```bash
-chmod +x setup-environment.sh
-```
-
-2. Run the script:
-```bash
-./setup-environment.sh
-```
-
-3. Follow the interactive prompts:
+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 `@sky-ph/atlas` 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.
+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. 
@@ -138,7 +107,7 @@ It will take a minute or two for your Droplet to be provisioned. Once it's ready
 
 To log in via SSH:
 
-1. Open a terminal (on macOS/Linux) or an SSH client like PuTTY (on Windows).
+1. Open a terminal (on macOS/Linux) or an SSH client like PuTTY (on Windows). You can also use Digital Ocean's web 'Console'. 
 2. Use one of these commands:
    ```bash
    # If using password authentication
@@ -154,7 +123,7 @@ To log in via SSH:
 3. If you used a password, you'll be prompted to enter it.
 4. If it's your first time logging in, you might be asked to change the root password.
 
-Now your Droplet is running! You'll likely want to install and configure a web server (like Nginx or Apache) and your application or website files. This part is beyond the scope of just creating the Droplet but is crucial for it to do anything useful.
+Now your Droplet is running! Now you can continue with the Powerhouse tutorial or any next steps.
 
 ### DNS Configuration
 
@@ -165,7 +134,7 @@ Now your Droplet is running! You'll likely want to install and configure a web s
    - Enter your domain name (e.g., `yourdomain.com`)
    - Click "Add Domain"
 
-2. **Update Nameservers at Your Domain Registrar:**
+2. **Start with Updating Nameservers at Your Domain Registrar:**
    - Log in to your domain registrar
    - Update nameservers to:
      ```
@@ -187,9 +156,9 @@ Now your Droplet is running! You'll likely want to install and configure a web s
      - **WILL DIRECT TO:** Your Droplet's IP
      - **TTL:** 3600
 
-#### Option B: Using Your Existing Nameservers
+#### Option B: Using Your Existing Nameservers (NS locked)
 
-1. **Create DNS Records at Your Registrar:**
+1. **Just Create DNS Records at Your Registrar:**
    - **Root Domain (A Record):**
      - **TYPE:** A
      - **HOSTNAME:** @
@@ -324,10 +293,16 @@ Security is a top priority in the setup process. The script implements automatic
 
 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:
+1. Check service status of switchboard & connect:
+```bash
+ph service status
+```
+You can also use
+
 ```bash
-pm2 status
+ph service start | stop | restart 
 ```
+- to start | stop | restart switchboard and connect
 
 2. View Nginx configuration:
 ```bash
@@ -390,12 +365,12 @@ ph update <package-name>
 
 ### Restarting Services:
 ```bash
-pm2 restart all
+ph service restart
 ```
 
 ### Viewing Logs:
 ```bash
-pm2 logs
+ph service status
 ```
 
 ## 7. Security Notes

package/docs/academy/04-APIReferences/01-ReactHooks.md

@@ -1,5 +1,87 @@
 # React Hooks (WIP)
 
+The idea is to make this feel as simple and familiar as using useState.
+Happy Path would look something like this: 
+
+```js
+// in a component that only needs to read a value, you can use
+const invoiceName = useReadDocumentField('myInvoiceDocumentId', 'name') // returns a string which is the `name`
+// and for documents that need to update data as well, you would have
+const updateInvoiceName = useUpdateDocumentField('myInvoiceDocumentId', 'name') // returns a function that takes a new string for the new name and dispatches the update
+// finally, we can combine these into a single hook which works like react's useState hook returning both the value and updater function
+const [invoiceName, updateInvoiceName] = useDocumentField('myInvoiceDocumentId', 'name')
+
+
+// Read-only value
+const invoiceName = useReadDocumentField('docId', 'name')
+
+// Write-only updater
+const updateInvoiceName = useUpdateDocumentField('docId', 'name')
+
+// Combined read + write (like useState)
+const [invoiceName, updateInvoiceName] = useDocumentField('docId', 'name')
+```
+
+Request	Translation
+Global access to drive state: A top-level, possibly context-based, way to introspect and interact with any document and its state tree without manually passing things around.
+Global dispatcher access: A utility or API (probably a hook or service function) where they give a document ID and get back all the relevant dispatch functions — kind of like a command palette for document ops.
+Time spent wiring > time spent building	Frustration with current DX (developer experience) — they want abstractions and helpers to just do the thing.
+
+Core Hooks & Patterns	
+- useDocumentField
+- useReadDocumentField
+- useUpdateDocumentField
+- useDocumentDispatch(docId):  updateX, delete, ... 
+
+Global Drive Access	
+- How to access and manipulate the global document tree
+- How to inspect children from parent context
+- Tree traversal utilities (if any)
+
+Convenience APIs	
+- Utility functions like getDispatchFunctions(docId)
+- “Quick Start” to manipulate any document like a pro
+
+Working with Context	
+- DriveContext: what lives there, how to use it
+- Example: using context to get current doc, sibling docs
+
+Best Practices & Patterns	
+- When to use useDocumentField vs getDispatch
+- Composing document fields into custom logic
+
+<details>
+<summary>Refresher on React Hooks</summary>
+
+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>
+
 ### Hook Name and Signature   
 The name of the hook and its TypeScript (or JavaScript) signature.
 ### Description

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "0.1.0-dev.5",
+  "version": "2.5.0-dev.0",
   "homepage": "https://powerhouse.academy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/powerhouse-inc/powerhouse"
+  },
   "dependencies": {
     "@codesandbox/sandpack-react": "^2.14.4",
     "@docusaurus/core": "^3.8.0",

package/sidebars.ts

@@ -10,7 +10,7 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
 
  Create as many sidebars as you want.
  */
-const sidebars: SidebarsConfig = {
+const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   academySidebar: [
     {
@@ -49,9 +49,18 @@ const sidebars: SidebarsConfig = {
           type: 'category',
           label: 'Document Model Creation',
           link: {
-            type: 'generated-index',
+            type: 'doc',
+            id: "academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel"
           },
-          items: [{type: 'autogenerated', dirName: 'academy/02-MasteryTrack/02-DocumentModelCreation'}]
+          items: [
+            'academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel',
+            'academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema',
+            'academy/MasteryTrack/DocumentModelCreation/SpecifyDocumentOperations',
+            'academy/MasteryTrack/DocumentModelCreation/UseTheDocumentModelGenerator',
+            'academy/MasteryTrack/DocumentModelCreation/ImplementDocumentReducers',
+            'academy/MasteryTrack/DocumentModelCreation/ImplementDocumentModelTests',
+            'academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository',
+          ]
         },
         {
           type: 'category',
@@ -59,7 +68,27 @@ const sidebars: SidebarsConfig = {
           link: {
             type: 'generated-index',
           },
-          items: [{type: 'autogenerated', dirName: 'academy/02-MasteryTrack/03-BuildingUserExperiences'}]
+          items: [
+            'academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors',
+            'academy/MasteryTrack/BuildingUserExperiences/ConfiguringDrives',
+            'academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer',
+          ]
+        },
+        {
+          type: 'category',
+          label: 'Document Tools',
+          link: {
+            type: 'generated-index',
+          },
+          items: [{ type: 'autogenerated', dirName: 'academy/02-MasteryTrack/03-BuildingUserExperiences/07-DocumentTools' }]
+        },
+        {
+          type: 'category',
+          label: 'Authorization',
+          link: {
+            type: 'generated-index',
+          },
+          items: [{ type: 'autogenerated', dirName: 'academy/02-MasteryTrack/03-BuildingUserExperiences/08-Authorization' }]
         },
         {
           type: 'category',

package/src/components/HomepageFeatures/index.tsx

@@ -164,7 +164,7 @@ export default function HomepageFeatures() {
             </div>
             <div className={styles.cardContent}>
               <a href="/docs/academy/GetStarted/BuildToDoListEditor" className={styles.pathButton}>Building a Todo-list Editor</a>
-              <a href="/docs/academy/BuildingUserExperiences/BuildingBeautifulDocumentEditors" className={styles.pathButton}>Building Beautiful Document Editors</a>
+              <a href="/docs/academy/BuildingUserExperiences/BuildingDocumentEditors" className={styles.pathButton}>Building Beautiful Document Editors</a>
               <a href="/docs/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer" className={styles.pathButton}>Building Custom Drive Explorers</a>
             </div>
           </div>

package/src/css/custom.css

@@ -459,3 +459,8 @@ html[data-theme='dark'] .DocSearch-Hits > *:empty {
 .doc-card-list-item {
   width: 100%; /* Ensure items take full width */
 }
+
+/* Attempt to hide icons in DocCard titles */
+.doc-card-list .card h2 svg {
+  display: none !important;
+}

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

@@ -1,109 +0,0 @@
-# Build Document Editors
-
-*Placeholder for a tutorial about building beautiful document editors.*
-
-## Build with React on Powerhouse
-
-At Powerhouse, frontend development follows a simple and familiar flow. Tailwind CSS is installed by default and fully managed by Connect Studio — you can use Tailwind classes freely, but you’re not required to. Regular CSS, inline styles, and any React-compatible styling method work exactly as you would expect in a standard React project. There is no need to manually configure or run Tailwind or build processes; **Connect Studio automatically handles everything during development.**
-
-For component visualization and testing, **Connect Studio replaces the need for Storybook**. Please do not use Storybook by default — Connect Studio provides a dynamic, local environment where you can define and preview your document models and editors live. If you still wish to set up Storybook on your own, you may, but it is unsupported and discouraged.
-
-During normal development, simply run Connect Studio with `ph connect`. Manual build commands are only needed when you publish a package, at which point the necessary build steps (including CSS generation) are handled automatically.
-
-Powerhouse aims to keep your developer experience clean, familiar, and focused.
-- Build React components as you would in any project.
-- Use styling approaches you're comfortable with.
-- Trust Connect Studio to handle the setup for you.
-
-### Building with react hooks
-
-What are React Hooks?
-
-From the React docs:
-
-"Hooks let you use different React features from your components. You can either use the built-in Hooks or combine them to build your own."
-https://react.dev/reference/react/hooks
-
-The "combine them to build your own" part is key here. A so-called "custom hook" is just a function that uses these built-in hooks.
-
-There are several types of built-in hooks which are used to solve different problems.
-
-For example:
-
-State lets a component “remember” information like user input. 
-
-Effects let a component connect to and synchronize with external systems.
-
-Context lets a component receive information from distant parents without passing it as props.
-
-Details about custom hooks are provided here: https://react.dev/learn/reusing-logic-with-custom-hooks
-
-In summary, there are three reasons to use custom hooks:
-
-To re-use logic that calls multiple hooks.
-To abstract away the complexity of multiple hooks.
-To isolate the side effects of the useEffect hook.
-
-Hook names must start with use followed by a capital letter, like useState (built-in) or useOnlineStatus (custom, like earlier on the page). Hooks may return arbitrary values.
-
-https://react.dev/learn/reusing-logic-with-custom-hooks#hook-names-always-start-with-use
-
-When you use any function that starts with "use", react will treat it as a hook and expect it to follow the rules of hooks.
-
-Rules of Hooks
-https://react.dev/reference/rules/rules-of-hooks
-
-Hooks are defined using JavaScript functions, but they represent a special type of reusable UI logic with restrictions on where they can be called.
-
-Only call Hooks at the top level
-Only call Hooks from React functions
-
-React needs these rules to ensure that the state is properly managed and that the component behaves as expected.
-
-So it is indeed possible to create a "hook" like so:
-
-```
-function useCurrentTime() {
-  const currentTime = new Date().toLocaleTimeString();
-
-  return currentTime;
-}
-```
-
-And this is technically a hook, but making it a hook is pointless because it doesn't use any of the built-in hooks.
-
-There is no reason that this could not just be:
-
-```
-function getCurrentTime() {
-  return new Date().toLocaleTimeString();
-}
-```
-
-Because in a component, both hooks and normal functions are called on every render.
-
-So if your component looks like this:
-
-```
-function MyComponent() {
-  const currentTimeFromFunc = getCurrentTime();
-}
-```
-
-or this:
-
-```
-function MyComponent() {
-  const currentTimeFromHook = useCurrentTime();
-}
-```
-
-The end result would be the same. The function would be called on every render.
-
-So in summary, the only reason a function should be a hook is if it uses one or more built-in hooks.
-
-In general, you will not want to take a normal function and turn it into a hook, because your normal function should not have been trying to use react hooks in the first place.
-
-## Powerhouse Component Library
-
-TBD