@powerhousedao/academy 0.1.0-dev.0

package/docs/academy/04-ComponentLibrary/01-PowerhouseDesignSystem.md

@@ -0,0 +1,94 @@
+# Powerhouse Design System
+
+The reusable components are a set of 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.
+These components are offered through the **Powerhouse Design System** with the help of storybook & the Academy documentation. 
+
+It provides a collection of pre-built, reusable UI components designed for consistency and efficiency across Powerhouse applications and editors. Think of it as a toolkit of standard UI elements like buttons, inputs, and checkboxes with many of these components based on graphql scalars. 
+
+:::info
+A GraphQL scalar is essentially a primitive, indivisible value in the GraphQL type system. 
+Here are the key points to understand:
+
+- **Basic Building Blocks:** Scalars are the basic data types—like String, Int, Float, Boolean, and ID—that represent atomic values.
+- **Leaf Nodes:** Scalars are the "leaves" of a GraphQL query. They can't have any sub-fields, meaning once you hit a scalar in a query, that's the final value.
+- **Custom Scalars:** Besides the built-in scalars, you can define custom scalars (e.g., a Date type) if you need to handle more specific formats or validations. Powerhouse does this specific for the web3 ecosystem. 
+:::
+
+In the next few chapters of our documentation, we will start with the simplest scalar components first, then move on to more complex, Powerhouse-specific components, and combine these in the Layout components.
+
+## **3 types of components**
+
+1. **Simple Component** has a scalar value as input 
+    - Component, Composition of smaller UI controls (e.g. Scalar component)
+    
+2. **Complex Component** has an object/array value 
+    - Group of components (e.g. sidebar tree view)
+    
+3. **Layout Component** will contain other components 
+    - Containers for other components, Sections (e.g. list of other components, color layouts, etc.)
+
+The documentation of each of the reusable components in the Academy documentation will be structured as follows:
+
+1. **Component Context**
+2. **Scalar Definition**
+3. **Component Storybook Base Example**
+    - Component Code
+    - Component Default Props
+4. **Component Storybook Usage Examples**
+
+## Exploring Components with Storybook
+
+We use Storybook as an interactive catalog for our design system components. It allows you to visually explore each component, interact with different states, and understand how to integrate them into your projects.
+
+[https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
+
+**Understanding the Storybook Interface:**
+
+1.  **Visual Demo:** The main panel shows the rendered component (e.g., a `Checkbox`). You can interact with it directly to see different states (checked, unchecked, disabled).
+2.  **Usage Snippet:** Below the demo, you'll typically find a basic code example demonstrating how to include the component in your code (e.g., `<Checkbox defaultValue label="Accept terms and conditions" />`). This provides a starting point for implementation.
+3.  **Props Table:** Further down, a table lists the properties (`props`) the component accepts. Props are like settings or configuration options. For the `Checkbox`, this table would show props like `label`, `defaultValue`, `value`, `onChange`, etc., often with descriptions of what they control.
+
+## Implementing a Design System Component
+
+Let's walk through the typical workflow for using a component from the design system, using the `Checkbox` from the [To-do List editor](/docs/academy/GetStarted/ToDoList/BuildToDoListEditor).
+
+1.  **Identify the Need:** While building your feature (e.g., the To-do List editor in `editor.tsx`), you determine the need for a standard UI element, like a checkbox.
+2.  **Consult the Resuable Components in Academy or in Storybook:**
+    *   Open the Powerhouse Storybook instance.
+    *   Navigate or search to find the `Checkbox` component.
+    *   Review the visual examples and interactive demo.
+    *   Examine the "Usage" snippet and the **Props table** to understand the basic implementation and available configuration options (`label`, `value`, `onChange`, etc.).
+3.  **Import the Component:** In your code editor, open the relevant file (e.g., `editors/to-do-list/editor.tsx`). Add an import statement at the top to bring the component into your file's scope:
+    ```typescript
+    import { Checkbox } from '@powerhousedao/design-system/scalars';
+    // Or import other components as needed:
+    // import { Checkbox, InputField, Button } from '@powerhousedao/design-system/scalars';
+    ```
+    This line instructs the build process to locate the `Checkbox` component within the installed `@powerhousedao/design-system/scalars` package and make it available for use.
+4.  **Use and Configure the Component:** Place the component tag in your JSX where needed. Use the information from Storybook (usage snippet and props table) as a guide, but adapt the props to your specific requirements within `editor.tsx`:
+    ```typescript
+    // Example from the To-do List Editor:
+    <Checkbox
+        // Bind the checked state to data within editor.tsx
+        value={item.checked} 
+        // Provide a function from editor.tsx to handle changes
+        onChange={() => { 
+            dispatch(actions.updateTodoItem({
+                id: item.id,
+                checked: !item.checked,
+            }));
+        }}
+        // Other props like 'label' might be omitted or added as needed.
+    />
+    ```
+    You configure the component's appearance and behavior by passing the appropriate values to its props.
+5.  **Test and Refine:** Run your application (e.g., using `ph connect`) to see the component in context. Verify its appearance and functionality.
+
+**Storybook vs. Source Code:**
+
+Storybook serves as essential documentation and a usage guide. Our developers write Storybook "stories" to demonstrate components and document their common props. However, the **ultimate source of truth** for a component's capabilities is its actual source code (e.g., the `.tsx` file within the `@powerhousedao/design-system/scalars` package).
+While Storybook aims for accuracy, there might occasionally be discrepancies or undocumented props.
+
+Please don't hesitate to reach out in our discord channels with any questions. 
+Happy designing! 

package/docs/academy/04-ComponentLibrary/02-BuildingWithScalars.md

@@ -0,0 +1,54 @@
+# Build with Scalars
+
+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:
+
+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
+
+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.
+
+In the Document Model Editor, you can find all the custom scalar types available in our documentation under the 'Scalars' section.
+
+Insert image of the feature. 
+
+````
+scalar PHID <-- imported from the design system library? not sure
+type MyType {
+  myScalar: PHID
+}   
+````
+
+## React Component Implementation in the Frontend
+
+All of our reusable components are available in the design system library or package.
+This package comes as a dependency in your project when creating a new document model project.
+````
+import PHIDField from 'design-system'
+const reactComponent = () => {
+
+return (
+  <div>
+    <PHIDField
+      fetchOptionsCallback={function Js(){}}
+      fetchSelectedOptionCallback={function Js(){}}
+      label="PHID field"
+      name="phid-field"
+      placeholder="phd:"
+    />
+
+  </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. 

package/docs/academy/04-ComponentLibrary/03-Scalar-Components/01-phid-field.mdx

@@ -0,0 +1,72 @@
+---
+sidebar_label: 'PHID Field'
+sidebar_position: 1
+---
+
+import { Tabs, TabItem } from '@theme/Tabs';
+
+# PHID Field Example
+
+### **Scalar Definition**
+
+- **Name:** `PHID` (Powerhouse ID)
+- **Purpose:** Represents a unique identifier pointing to a document, branch, scope, or data object within the Powerhouse system.
+
+
+<details>
+<summary>**Formatting of the component:**</summary>
+    - **Basic Notation:** `phd:<documentID>`
+        - **Branch and Scope:** Optional components appended using colons `:`.
+        - **Full Notation:** `phd:<documentID>:<branch>:<scope>`
+            - **Branch:** Defaults to `main` if omitted.
+            - **Scope:** Defaults to `public` if omitted.
+    - **Data Object Reference:** `phd:<documentID>/<dataObjectID>`
+    - **URL Format:** `phd://<domain>/<documentID>`
+        - Example: `phd://switchboard.powerhouse.xyz/baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
+
+**Examples of the component formatting:**
+    - **Basic PHID:** `phd:baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
+    - **With Branch:** `phd:baefc2a4...:draft`
+    - **With Scope:** `phd:baefc2a4...::local`
+    - **With Branch and Scope:** `phd:baefc2a4...:draft:local`
+    - **With Data Object ID:** `phd:baefc2a4.../3cf05e40...`
+</details>
+
+<details>
+<summary>**Validation of the Component:**</summary>
+    - **Validate each format:**
+        1. **PHID only:** Ensure the document ID is a valid UUID.
+        2. **PHID with data element (OID):** Validate both the document ID and the data object ID.
+        3. **PHID with branch:** Validate the document ID and check if the branch is properly formatted.
+        4. **PHID with scope:** Validate the document ID and check if the scope is valid.
+        5. **PHID with branch and scope:** Validate all three components: document ID, branch, and scope.
+    - **Error Message Example:** "Invalid PHID format. Please check the document ID, branch, or scope."
+</details>
+
+The following is a the UI component for the PHID field and scalar in a storybook.
+We use Storybook as our component development environment. 
+It allows us to build and test UI components in isolation, making it easier to develop, test, and document reusable components.
+In our stories you'll find first find a basic UI implementation example of the component, followed by the component's properties, events, and validation options.
+
+- A list of the **default properties** and their descriptions, and a list of the available events that can be triggered.
+- A list of the **component's specific properties** and attributes based on the components functionality. 
+- A list of **validation options**, or ways to validate the component's desired input values.
+
+Additionally, you'll find various **stories of the components in different states**.
+
+<div style={{ 
+  border: '1px solid #E5E7EB', 
+  borderRadius: '8px', 
+  padding: '16px',
+  marginBottom: '20px',
+}}>
+  <iframe
+    src="https://storybook.powerhouse.academy/iframe.html?id=document-engineering-scalars-phid-field&viewMode=story"
+    style={{
+      width: '100%',
+      height: '4500px',
+      border: 'none',
+    }}
+    title="PhidField Component Demo"
+  />
+</div>

package/docs/academy/04-ComponentLibrary/04-Complex-Components/01-sidebar.mdx

@@ -0,0 +1,36 @@
+import { Tabs, TabItem } from '@theme/Tabs';
+
+# Sidebar
+
+### **Scalar Definition**
+
+- **Name:** `Sidebar`
+- **Purpose:** The Sidebar component can be used within a page layout to provide a sidebar navigation. It provided a tree structure of nodes that can be used to navigate the application offering customization, search and more.
+
+
+<details>
+<summary>**Formatting of the component:**</summary>
+    
+</details>
+
+<details>
+<summary>**Validation of the Component:**</summary>
+   
+</details>
+
+<div style={{ 
+  border: '1px solid #E5E7EB', 
+  borderRadius: '8px', 
+  padding: '16px',
+  marginBottom: '20px',
+}}>
+  <iframe
+    src="https://dspot-scalars-storybook.vercel.app/iframe.html?args=&id=document-engineering-complex-components-sidebar--readme&viewMode=story"
+    style={{
+      width: '100%',
+      height: '2000px',
+      border: 'none',
+    }}
+    title="Sidebar Component Demo"
+  />
+</div>

package/docs/academy/04-ComponentLibrary/05-Layout-Components/01-test-toupdate.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_label: 'PHID Field'
+sidebar_position: 1
+---
+
+import { Tabs, TabItem } from '@theme/Tabs';
+
+# PHID Field Example
+
+### **Scalar Definition**
+
+- **Name:** `PHID` (Powerhouse ID)
+- **Purpose:** Represents a unique identifier pointing to a document, branch, scope, or data object within the Powerhouse system.
+
+
+<details>
+<summary>**Formatting of the component:**</summary>
+    - **Basic Notation:** `phd:<documentID>`
+        - **Branch and Scope:** Optional components appended using colons `:`.
+        - **Full Notation:** `phd:<documentID>:<branch>:<scope>`
+            - **Branch:** Defaults to `main` if omitted.
+            - **Scope:** Defaults to `public` if omitted.
+    - **Data Object Reference:** `phd:<documentID>/<dataObjectID>`
+    - **URL Format:** `phd://<domain>/<documentID>`
+        - Example: `phd://switchboard.powerhouse.xyz/baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
+
+**Examples of the component formatting:**
+    - **Basic PHID:** `phd:baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
+    - **With Branch:** `phd:baefc2a4...:draft`
+    - **With Scope:** `phd:baefc2a4...::local`
+    - **With Branch and Scope:** `phd:baefc2a4...:draft:local`
+    - **With Data Object ID:** `phd:baefc2a4.../3cf05e40...`
+</details>
+
+<details>
+<summary>**Validation of the Component:**</summary>
+    - **Validate each format:**
+        1. **PHID only:** Ensure the document ID is a valid UUID.
+        2. **PHID with data element (OID):** Validate both the document ID and the data object ID.
+        3. **PHID with branch:** Validate the document ID and check if the branch is properly formatted.
+        4. **PHID with scope:** Validate the document ID and check if the scope is valid.
+        5. **PHID with branch and scope:** Validate all three components: document ID, branch, and scope.
+    - **Error Message Example:** "Invalid PHID format. Please check the document ID, branch, or scope."
+</details>
+
+<div style={{ 
+  border: '1px solid #E5E7EB', 
+  borderRadius: '8px', 
+  padding: '16px',
+  marginBottom: '20px',
+}}>
+  <iframe
+    src="https://dspot-scalars-storybook.vercel.app/iframe.html?args=name:amount-field;placeholder:test;label:Enter%20Amount%20and%20Select%20Currency;type:Amount;placeholderSelect:CUR;allowedTokens:!null;tokenIcons.Sol:1;value.amount:3454564564;value.currency:BTC&id=document-engineering-simple-components-phid-field--readme&viewMode=story"
+    style={{
+      width: '100%',
+      height: '4500px',
+      border: 'none',
+    }}
+    title="PhidField Component Demo"
+  />
+</div>

package/docs/academy/04-ComponentLibrary/06-Fragments/01-test-toupdate.mdx

@@ -0,0 +1,61 @@
+---
+sidebar_label: 'PHID Field'
+sidebar_position: 1
+---
+
+import { Tabs, TabItem } from '@theme/Tabs';
+
+# PHID Field Example
+
+### **Scalar Definition**
+
+- **Name:** `PHID` (Powerhouse ID)
+- **Purpose:** Represents a unique identifier pointing to a document, branch, scope, or data object within the Powerhouse system.
+
+
+<details>
+<summary>**Formatting of the component:**</summary>
+    - **Basic Notation:** `phd:<documentID>`
+        - **Branch and Scope:** Optional components appended using colons `:`.
+        - **Full Notation:** `phd:<documentID>:<branch>:<scope>`
+            - **Branch:** Defaults to `main` if omitted.
+            - **Scope:** Defaults to `public` if omitted.
+    - **Data Object Reference:** `phd:<documentID>/<dataObjectID>`
+    - **URL Format:** `phd://<domain>/<documentID>`
+        - Example: `phd://switchboard.powerhouse.xyz/baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
+
+**Examples of the component formatting:**
+    - **Basic PHID:** `phd:baefc2a4-f9a0-4950-8161-fd8d8cc7dea9`
+    - **With Branch:** `phd:baefc2a4...:draft`
+    - **With Scope:** `phd:baefc2a4...::local`
+    - **With Branch and Scope:** `phd:baefc2a4...:draft:local`
+    - **With Data Object ID:** `phd:baefc2a4.../3cf05e40...`
+</details>
+
+<details>
+<summary>**Validation of the Component:**</summary>
+    - **Validate each format:**
+        1. **PHID only:** Ensure the document ID is a valid UUID.
+        2. **PHID with data element (OID):** Validate both the document ID and the data object ID.
+        3. **PHID with branch:** Validate the document ID and check if the branch is properly formatted.
+        4. **PHID with scope:** Validate the document ID and check if the scope is valid.
+        5. **PHID with branch and scope:** Validate all three components: document ID, branch, and scope.
+    - **Error Message Example:** "Invalid PHID format. Please check the document ID, branch, or scope."
+</details>
+
+<div style={{ 
+  border: '1px solid #E5E7EB', 
+  borderRadius: '8px', 
+  padding: '16px',
+  marginBottom: '20px',
+}}>
+  <iframe
+    src="https://dspot-scalars-storybook.vercel.app/iframe.html?args=name:amount-field;placeholder:test;label:Enter%20Amount%20and%20Select%20Currency;type:Amount;placeholderSelect:CUR;allowedTokens:!null;tokenIcons.Sol:1;value.amount:3454564564;value.currency:BTC&id=document-engineering-simple-components-phid-field--readme&viewMode=story"
+    style={{
+      width: '100%',
+      height: '4500px',
+      border: 'none',
+    }}
+    title="PhidField Component Demo"
+  />
+</div>

package/docs/academy/04-ComponentLibrary/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Component Library",
+    "position": 4,
+    "link": {
+      "type": "generated-index",
+      "description": "An overview of the components in the Powerhouse Component Library."
+    }
+  }

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

@@ -0,0 +1,50 @@
+# Powerhouse Architecture
+
+The Powerhouse ecosystem is built on five core host applications that together form a modular, scalable operating system for decentralized organizations. Each application serves a distinct role, yet they are interdependent, working as a unified system to streamline operations, enhance collaboration, and drive automation.
+
+These five applications are:
+
+1. **Connect** – The contributor's public or private workspace.
+2. **Switchboard** – The data infrastructure and API engine.
+3. **Fusion** – The public-facing collaboration hub.
+4. **Renown** – The decentralized reputation and identity system.
+5. **Academy** – The onboarding and learning platform.
+
+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.
+
+## 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.
+
+### 1. Connect: The Contributor's Workspace and Data Capture Point
+
+Connect is the entry point for individual contributors, where they install apps and packages tailored to specific business solutions, enabling collaboration in public or private settings.
+
+- All work in Connect is captured as document models, ensuring that data is structured, traceable, and immediately available for processing.
+- This structured data flows into Switchboard, making it accessible for analytics, automation, and API-driven integrations.
+- Fusion then utilizes this data to generate dashboards, summaries, and insights for decision-making.
+- Renown serves as the authentication and access gateway, ensuring that contributors can securely interact with the system.
+
+### 2. Switchboard: The Data Processing and Automation Engine
+
+Switchboard acts as the central nervous system, ensuring that data flows efficiently between applications and powers real-time coordination.
+
+- It ingests structured data from Connect and makes it available for further analysis, automation, and integrations.
+- The API interface allows developers and data engineers to fuel the broader system, providing insights and feeding data-driven workflows.
+- The processed data is then transmitted to Fusion, where it is transformed into dashboards, analytics, and key performance indicators (KPIs).
+
+### 3. Fusion: The Public Collaboration and Data Visualization Layer
+
+Fusion serves as the public-facing marketplace and collaboration hub, allowing contributors and organizations to interact with structured data captured from Connect and processed through Switchboard.
+
+- Fusion structures, summarizes, and visualizes key metrics, enabling users to make data-driven decisions.
+- It pulls relevant operational insights, helping stakeholders navigate and act on real-time data.
+- Users can directly access work completed in Connect, viewing reports, summaries, and discussions within Fusion's public and private environments.
+
+### 4. Renown: Authentication, Reputation, and Access Control
+
+Renown is the trust and identity layer, ensuring security, reputation tracking, and access control across the ecosystem.
+
+- It acts as the authentication gateway, determining who has permission to view, edit, or execute specific operations within the system.
+- Every action performed in Connect is tracked in the document history, making it fully auditable through Switchboard.
+- Fusion utilizes Renown to verify contributor credibility, ensuring that data-driven decisions are based on trusted and authenticated inputs.

package/docs/academy/05-Architecture/01-WorkingWithTheReactor.md

@@ -0,0 +1,48 @@
+# Working with the Reactor
+
+:::tip
+Document models are the common design pattern that is used for all documents and files.  
+DocSync is a decentralized synchronization protocol that is storage agnostic.  
+
+**Document Models** are _what_ is synced and **DocSync** is _how_ document models are synced.  
+But who is doing the syncing?  
+
+We call these participants **Reactors**.
+:::
+
+### Powerhouse Reactors 
+
+**What is a Reactor?**
+Powerhouse Reactors are the nodes in the network that store documents, resolve conflicts and rerun operations to verify document event histories. Reactors can be configured for local storage, centralized cloud storage or on a decentralized storage network. A Reactor is essentially a storage node used in Powerhouse's framework to handle documents and traditional files. It supports multiple storage solutions, including:
+
+- **Local Storage**: For offline or on-device access.
+- **Cloud Storage**: For centralized, scalable data management.
+- **Decentralized Storage**: Such as Ceramic or IPFS, enabling distributed and blockchain-based storage options.
+
+### Core Functions of Reactors
+- **Data Synchronization**: Reactors ensure that all data, whether local or distributed, remains up-to-date and consistent across the system.
+- **Modular Storage Adapters**: They support integration with different storage backends depending on organizational needs.
+- **Collaboration Support**: Reactors facilitate document sharing and peer-to-peer collaboration across contributors within the network.
+
+:::tip
+The DocSync protocol *sends updates from one reactor to another* - **smashing document operations into one another** - to ensure all data is synced.
+:::
+
+A **reactor** is responsible for storing data and resolving merge conflicts.  
+Editing data and submitting new operations must be done through Powerhouse's native applications (Connect, Switchboard, Fusion). Each instance of these applications contains a Reactor that is responsible for storing data and syncing data through DocSync. In other words, Powerhouse applications are how Reactors can be accessed, manipulated, steered, visualized and modified. A local Connect desktop application's reactor can therefore sync with the Reactor of a remote drive (e.g. Switchboard instance). 
+
+<img src="/img/Powerhouse Website Drive.png" alt="Powerhouse Storage Layer"/>
+
+### Why Are Reactors Important?
+They are key to ensuring the scalability and resilience of decentralized operations.
+By acting as the backbone for document models in the Powerhouse framework, they enable seamless version control and event-driven updates.
+Reactors provide the foundation for advanced features like real-time collaboration, history tracking, and decentralized audits.
+This modular, flexible infrastructure enables organizations to build efficient and robust decentralized systems, tailored for modern network organizations
+
+## Configuring your reactor
+ 
+In addition to the choice of storage, Reactors also have other configurations. 
+- The **operational data** and **read models** associated with the document models inside a reactor allow to query the gathered data inside a document model or quickly visualize the crucial insights at a glance. 
+- **Listeners**, which continuously listen to any changes in a document model, help us to connect additional tools such as codegenerators and scripts to the reactors and the document models it holds
+
+> Jump to: Configure a listener for your reactor and add a codegenerator

package/docs/academy/05-Architecture/02-ReferencingMonorepoPackages

@@ -0,0 +1,65 @@
+# Referencing Monorepo Packages
+
+## **Context**
+
+In scenarios where a project is not part of the monorepo but needs to reference monorepo packages (e.g., using `@powerhousedeao/ph-cli`), there's a streamlined approach that avoids duplicating dependencies and maintains consistency with monorepo versions.
+
+---
+
+## **Approach**
+
+### **1. Using `link:` in `package.json`**
+
+Instead of manually copying dependencies or trying complex build setups, you can use the `link:` protocol to create a symlink to the monorepo package.
+
+```json
+{
+  "dependencies": {
+    "@powerhousedeao/ph-cli": "link:../monorepo/clis/ph-cli"
+  }
+}
+```
+
+This approach creates a symlink under the node_modules directory, linking directly to the specified monorepo package.
+
+### **2. Running the Linked CLI**
+
+After linking, you can run the CLI tool using pnpm:
+
+```bash
+pnpm install
+pnpm run ../powerhouse/clis/ph-cli
+```
+
+Alternatively, use the command through the linked CLI:
+
+```bash
+ph connect
+```
+
+This will invoke the connect package from the monorepo.
+
+### **3. Building Dependencies**
+
+To ensure all dependencies are correctly built:
+
+```bash
+nx run @powerhousedeao/ph-cli
+```
+
+This command will build all necessary dependencies within the monorepo.
+
+### **4. Key Insights**
+
+- **Symlink Simplicity:** The link: protocol is the least disruptive, as it avoids version conflicts and unnecessary duplication.
+- **Development Workflow:** Changes made to the connect code in the monorepo will be picked up automatically when using the linked CLI, as ph-cli defers calls to the respective packages.
+
+### **5. Troubleshooting**
+
+If dependencies aren't picked up correctly: Ensure the symlink path is accurate relative to the project root.
+
+For isolated package builds: Use nx run to trigger specific package builds when needed.
+
+### **6. Conclusion**
+Using link: is an effective, developer-friendly method to reference monorepo packages in external boilerplate projects. It supports efficient development workflows, reduces redundancy, and ensures consistency across environments.
+

package/docs/academy/05-Architecture/04-MovingBeyondCRUD

@@ -0,0 +1,61 @@
+# Moving Beyond CRUD
+
+Powerhouse uses "single field operations" as granular actions that go beyond traditional CRUD (Create, Read, Update, Delete) operations.   
+In a basic CRUD framework, the focus is on making entire objects or records editable as a whole, often leading to oversimplified data management that can't easily handle complex workflows or state transitions.
+
+## What Are Single Field Operations?
+These are focused, granular updates to individual fields within a document rather than treating the document as a whole. This approach allows for precise control and tracking of changes. For example:
+
+- Setting a Document Number (simple string input)
+- Changing Master Status (an enum dropdown selection)
+
+Each of these operations targets only one field and has a corresponding form that collects and submits the new value.
+
+## Why go beyond CRUD?
+
+### Granular State Tracking:
+Powerhouse's system emphasizes understanding how documents transition from one state to another in fine detail. By breaking down actions into specific field-level operations, it allows for tracking the exact sequence of changes, which is crucial for things like auditing, version control, and complex workflows.
+
+### Operational Focus:
+The system is designed around the idea of operations themselves—not just the data they manipulate. While traditional CRUD frameworks might treat each field as independently updatable without any logic or process attached, Powerhouse assigns specific operations that can enforce business rules and state transitions.
+
+### Customization & Flexibility:
+CRUD frameworks are often too rigid for real-world applications that need more nuanced behaviors. Powerhouse offers both the simplicity of CRUD for standard operations and the ability to go deeper, defining more complex, field-specific operations when needed. This hybrid approach ensures flexibility without sacrificing systematic structure.
+
+### Automation Potential:
+Even though creating these granular operations might seem tedious, the goal is to build a system where standard CRUD operations can eventually be auto-generated, leaving developers to focus only on defining the exceptional, non-standard behaviors.
+
+### Improved Permissions and User Intent:
+By having specific operations tied to individual fields, it becomes easier to manage permissions (e.g., who can change the master status but not the content) and to capture user intent more precisely, which is valuable in complex collaborative environments.
+
+
+## Understanding the Code Example
+
+![Alt text for the image](./images/image.png)
+
+| `SetDocNumberForm.tsx` (StringField) | `SetMasterStatusForm.tsx` (EnumField) |
+|-------------------------------------|---------------------------------------|
+| **Purpose:** To update the document number (a string field).<br /><br />**How it works:**<br />- A form is rendered with a StringField input<br />- The defaultValue comes from the document model (props.defaultValue.docNo)<br />- On submit (or onBlur), the new document number is dispatched via the dispatch function<br />- It uses a generic onSubmit handler that processes the collected input and triggers the document update<br /><br />**Key takeaway:**<br />- This is a simple, single field form that maps a scalar string to a reusable component (StringField)<br />- The form structure is systematic: label, name, placeholder, and onBlur event handler | **Purpose:** To update the master status (an enum field).<br /><br />**How it works:**<br />- A form is rendered with an EnumField dropdown<br />- The dropdown options are enum values like "APPROVED", "DEFERRED", etc.<br />- The default value is pre-filled from props.defaultValue.masterStatus<br />- On change, the form dispatches the updated status<br /><br />**Key takeaway:**<br />- This form uses an EnumField component, showcasing how different scalar types (in this case, enums) map to different input components<br />- Options are provided systematically, meaning they could potentially be auto-generated from the document model |
+
+
+
+## Why Is This Granular Approach Important?    
+1. **Systematic Yet Customizable:**
+Even we are manually building these forms now, the structure is simple and repeatable:
+- Identify the scalar type (string, enum, etc.).
+- Map it to a reusable component.
+- Use a standardized form structure with an onSubmit handler and a dispatch function.
+2. **Auto-Generation Potential:**
+The systematic nature of these forms means they could be automatically generated in the future.
+- For example, if a field is identified as a string, the system could auto-generate a form using a StringField.
+- For enums, it could auto-generate the EnumField with all valid options.
+
+
+## How to implement single field operations
+
+### At the schema definition level
+
+### At the frontend level
+
+
+