@powerhousedao/academy 5.1.0-dev.1 → 5.1.0-dev.10

package/docs/academy/04-APIReferences/renown-sdk/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Renown SDK",
+  "position": 6,
+  "link": {
+    "type": "generated-index",
+    "description": "Complete documentation for the Renown SDK - authentication and user profile management for React applications."
+  }
+}

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

@@ -1,6 +1,9 @@
 # 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.
+**Vetra is part of the Powerhouse Ecosystem** and acts as the builder platform and builder tooling for scalable network organizations. 
+
+The Powerhouse ecosystem makes use of 4 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:
 
@@ -8,45 +11,10 @@ These five applications are:
 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 modules.
-
-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.
-
-### 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.
+With the help of these host applications Powerhouse is launching 2 platforms that form an example of the infrastructure that can be build with the Powerhouse techstack.
 
-- 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.
+- [Vetra Builder Platform](https://vetra.io/): Sovereign infrastructure for scalable network organizations that is local first, built to scale. 
+- [Achra Decentralized Operations Platform](https://achra.com/): Where open organizations can procure and purchase services. 

package/docs/academy/06-ComponentLibrary/00-DocumentEngineering.md

@@ -112,38 +112,86 @@ While Storybook aims for accuracy, there might occasionally be discrepancies or
 
 ## Implementing a Component
 
-Let's walk through the typical workflow for using a component from the document-engineering system, using the `Checkbox` from the [To-do List editor](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors).
+Let's walk through the typical workflow for using a component from the document-engineering system, using `BooleanField` for a checkbox in the [TodoList editor](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors).
 
-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.
+1.  **Identify the Need:** While building your feature (e.g., the TodoList editor), you determine the need for a standard UI element, like a checkbox to mark items as complete.
 2.  **Consult the Document Engineering Components in Storybook:**
     - Open the Powerhouse Storybook instance. [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
-    - Navigate or search to find the `Checkbox` component.
+    - Navigate or search to find the `BooleanField` component (used for checkboxes).
     - 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:
+    - Examine the "Usage" snippet and the **Props table** to understand the basic implementation and available configuration options (`name`, `value`, `onChange`, etc.).
+3.  **Import the Component:** In your code editor, open the relevant file (e.g., `editors/todo-list-editor/components/Checkbox.tsx`). Add an import statement at the top to bring the component into your file's scope:
     ```typescript
-    import { Checkbox } from "@powerhousedao/document-engineering/scalars";
-    // Or import other components as needed:
-    // import { Checkbox, InputField, Button } from '@powerhousedao/document-engineering/scalars';
+    import { Form, BooleanField } from "@powerhousedao/document-engineering/scalars";
     ```
-    This line instructs the build process to locate the `Checkbox` component within the installed `@powerhousedao/document-engineering/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`:
+    This line instructs the build process to locate the `Form` and `BooleanField` components within the installed `@powerhousedao/document-engineering/scalars` package and make them available for use.
+
+    :::info Form Wrapper Required
+    Scalar components like `BooleanField` must be wrapped in a `Form` component from the same package. This provides built-in validation and form state management.
+    :::
+
+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:
+
+    **Step 4a: Create a reusable Checkbox component**
+    ```typescript
+    // editors/todo-list-editor/components/Checkbox.tsx
+    import { Form, BooleanField } from "@powerhousedao/document-engineering/scalars";
+
+    interface CheckboxProps {
+      value: boolean;
+      onChange: (value: boolean) => void;
+    }
+
+    export const Checkbox = ({ value, onChange }: CheckboxProps) => {
+      return (
+        <Form onSubmit={() => {}}>
+          <BooleanField
+            name="checked"
+            description="Mark as complete"
+            value={value}
+            onChange={onChange}
+          />
+        </Form>
+      );
+    };
+    ```
+
+    **Step 4b: Use it in your Todo component with the document model hook**
     ```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.
-    />
+    // editors/todo-list-editor/components/Todo.tsx
+    import { useSelectedTodoListDocument, updateTodoItem } from "todo-tutorial/document-models/todo-list";
+    import type { TodoItem } from "todo-tutorial/document-models/todo-list";
+    import { Checkbox } from "./Checkbox.js";
+
+    type Props = { todo: TodoItem };
+
+    export function Todo({ todo }: Props) {
+      // Use the hook to get dispatch function
+      const [todoList, dispatch] = useSelectedTodoListDocument();
+
+      if (!todoList) return null;
+
+      return (
+        <div className="flex items-center gap-2">
+          <Checkbox
+            value={todo.checked}
+            onChange={() => {
+              dispatch(updateTodoItem({
+                id: todo.id,
+                checked: !todo.checked,
+              }));
+            }}
+          />
+          <span className={todo.checked ? "line-through" : ""}>
+            {todo.text}
+          </span>
+        </div>
+      );
+    }
     ```
-    You configure the component's appearance and behavior by passing the appropriate values to its props.
+
+    You configure the component's appearance and behavior by passing the appropriate values to its props. Note the use of the `useSelectedTodoListDocument` hook to access the dispatch function.
+
 5.  **Test and Refine:** Run your application (e.g., using `ph connect`) to see the component in context. Verify its appearance and functionality.
 
 ## Usage

package/docs/academy/08-Glossary.md

@@ -13,13 +13,17 @@
 
 ## Software Components
 
+- **Model Context Protocol (MCP)** – A standardized protocol that enables AI agents and external tools to interact with systems through structured operations. Powerhouse uses MCP to provide AI access to document management capabilities.
 - **Reactor** – A storage node for Powerhouse documents and files with multiple storage adapters (local, cloud, decentralized).
+- **Reactor-MCP** – A Model Context Protocol server for the Powerhouse ecosystem that provides AI agents and tools with structured access to document model operations, serving as a bridge between AI systems and Powerhouse document management infrastructure.
 - **Powerhouse Switchboard** – A scalable API service that aggregates and processes document data.
 - **Powerhouse Fusion** – A platform front-end that hosts the public marketplace for SNO interactions.
 - **Powerhouse Renown** – A decentralized authentication system managing contributor reputation.
 - **Powerhouse Academy** – A training platform for onboarding and upskilling SNO contributors.
 - **Connect** – The contributor's public or private workspace, serving as the entry point for individual contributors to install apps and packages for specific business solutions.
 - **Powergrid** – A decentralized network of reactors that sync with each other.
+- **Preview Drive** – A local drive created in `--watch` mode during `ph vetra` development, used for testing local document models and editors without affecting the main synced drive.
+- **Remote Drive** – A Powerhouse drive hosted on a remote server (e.g., Vetra) that syncs across team members, enabling collaborative development on shared documents and document models.
 - **Powerhouse CLI (ph)** – The command-line tool for Powerhouse project initialization, code generation, package management, and running local development environments (Connect Studio). It also manages services, ensuring the terminology aligns with the updated setup guide.
 - **Connect App (Connect Studio)** – The primary Powerhouse application for defining document models, building/testing editors (in Studio mode), and collaborating on documents.
 - **Document Tools** – Built-in features within Powerhouse applications (e.g., Connect) that assist with document management, inspection, and interaction, such as Operations History.
@@ -74,10 +78,13 @@
 - **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.
+- **Vetra** – A Powerhouse platform for hosting remote drives, enabling collaborative development and document synchronization across team members.
+- **Watch Mode (`--watch`)** – A development mode flag for `ph vetra` that enables dynamic loading of local document models and editors, creating a separate Preview Drive for testing changes in real-time.
 
 ## AI & Automation
 
 - **AI Assistants** – AI-powered contributors paired with human contributors to automate tasks and improve productivity.
+- **Document Model Agent** – A specialized AI agent that guides users through creating document models, handling requirements gathering, design confirmation, and implementation using MCP tools for state schema definition, operation creation, and code generation.
 - **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.

package/docs/academy/10-TodoListTutorial/02-ImplementTodoListDocumentModelReducerOperationHandlers.md

@@ -0,0 +1,171 @@
+# Step 2 — Implement the `TodoList` document model reducer operation handlers
+
+## Adding the logic for handling operations with reducers
+
+Your document model update's the state of a given document by applying a set of append-only actions. Once these have been applied to the document, we call them operations.
+
+The document model does this with a reducer — a function which takes the existing state and a given action, and then returns the new state with the action applied.
+
+## What we have so far
+
+The operation handler logic for each module is found in `document-models/SOME-DOCUMENT-MODEL/src/reducers/SOME-MODULE-NAME.ts`.
+
+So for our todos module, we will implement our handler logic in `document-models/todo-list/src/reducers/todos.ts`
+
+When you generated your document model code, we created a boilerplate implementation of the reducer logic for each of the operations we defined in step 1. You will see that there are functions for handling each of the operations, but all they do is throw "not implemented" errors.
+
+```ts
+import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
+
+export const todoListTodosOperations: TodoListTodosOperations = {
+  addTodoItemOperation(state, action) {
+    // TODO: Implement "addTodoItemOperation" reducer
+    throw new Error('Reducer "addTodoItemOperation" not yet implemented');
+  },
+  updateTodoItemOperation(state, action) {
+    // TODO: Implement "updateTodoItemOperation" reducer
+    throw new Error('Reducer "updateTodoItemOperation" not yet implemented');
+  },
+  deleteTodoItemOperation(state, action) {
+    // TODO: Implement "deleteTodoItemOperation" reducer
+    throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
+  },
+};
+```
+
+Let's add the handler logic for each operation in the same order we defined them in the previous step.
+
+To handle the `addTodoItemOperation`, all we need to do is create an `id` for our new operation, and then push an object with that `id` and the rest of the action input into the `items` array in our state.
+
+Update your `addTodoItemOperation` like so:
+
+```typescript
+import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
+
+export const todoListTodosOperations: TodoListTodosOperations = {
+  // removed-start
+  addTodoItemOperation(state, action) {
+    // TODO: Implement "addTodoItemOperation" reducer
+    throw new Error('Reducer "addTodoItemOperation" not yet implemented');
+  },
+  // removed-end
+  // added-start
+  addTodoItemOperation(state, action) {
+    const id = generateId();
+    state.items.push({ ...action.input, id, checked: false });
+  },
+  // added-end
+  updateTodoItemOperation(state, action) {
+    // TODO: Implement "updateTodoItemOperation" reducer
+    throw new Error('Reducer "updateTodoItemOperation" not yet implemented');
+  },
+  deleteTodoItemOperation(state, action) {
+    // TODO: Implement "deleteTodoItemOperation" reducer
+    throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
+  },
+};
+```
+
+Under the hood, we use a library for making the functions always create and return new copies of the state, i.e. they are always _immutable_. This is why you don't actually have to return your new state, the newly created copy of the state is used automatically.
+
+The `updateTodoOperation` works in much the same way, except this time instead of creating a new `id`, we find the item in the items array which has the given id. Then we spread out the rest of the values we get from the action input, same as when creating.
+
+Update your `updateTodoOperation` to be like so:
+
+```typescript
+export const todoListTodosOperations: TodoListTodosOperations = {
+    addTodoItemOperation(state, action) {
+      const id = generateId();
+      state.items.push({ ...action.input, id, checked: false });
+    },
+    // removed-start
+    updateTodoItemOperation(state, action) {
+        // TODO: Implement "updateTodoItemOperation" reducer
+        throw new Error('Reducer "updateTodoItemOperation" not yet implemented');
+    },
+    // removed-end
+    // added-start
+    updateTodoItemOperation(state, action) {
+      const item = state.items.find((item) => item.id === action.input.id);
+      if (!item) return;
+      item.text = action.input.text ?? item.text;
+      item.checked = action.input.checked ?? item.checked;
+    },
+    // added-end
+    deleteTodoItemOperation(state, action) {
+        // TODO: Implement "deleteTodoItemOperation" reducer
+        throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
+    }
+};
+```
+
+The delete operation is the simplest of the three. All we need to do is filter the items array so that it no longer contains the item with the given id.
+
+```typescript
+export const todoListTodosOperations: TodoListTodosOperations = {
+  addTodoItemOperation(state, action) {
+    const id = generateId();
+    state.items.push({ ...action.input, id, checked: false });
+  },
+  updateTodoItemOperation(state, action) {
+    const item = state.items.find((item) => item.id === action.input.id);
+    if (!item) return;
+    item.text = action.input.text ?? item.text;
+    item.checked = action.input.checked ?? item.checked;
+  },
+  // removed-start
+  deleteTodoItemOperation(state, action) {
+    // TODO: Implement "deleteTodoItemOperation" reducer
+    throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
+  },
+  // removed-end
+  // added-start
+  deleteTodoItemOperation(state, action) {
+    state.items = state.items.filter((item) => item.id !== action.input.id);
+  },
+  // added-end
+};
+```
+
+With that all done, your final result should look like this:
+
+```ts
+import { generateId } from "document-model/core";
+import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
+
+export const todoListTodosOperations: TodoListTodosOperations = {
+  addTodoItemOperation(state, action) {
+    const id = generateId();
+    state.items.push({ ...action.input, id, checked: false });
+  },
+  updateTodoItemOperation(state, action) {
+    const item = state.items.find((item) => item.id === action.input.id);
+    if (!item) return;
+    item.text = action.input.text ?? item.text;
+    item.checked = action.input.checked ?? item.checked;
+  },
+  deleteTodoItemOperation(state, action) {
+    state.items = state.items.filter((item) => item.id !== action.input.id);
+  },
+};
+```
+
+## Check your work
+
+To make sure all works as expected, we should:
+
+- check types
+run: `pnpm tsc`
+
+- check linting
+run: `pnpm lint`
+
+- check tests
+run: `pnpm test`
+
+- make sure your code matches the code in the completed step branch
+run: `git diff your-branch-name step-2-complete-implemented-todo-list-document-model-reducer-operation-handlers`
+
+### Up next: tests for our new operation handlers
+
+Up next, you'll implement some custom tests to check the behavior of our new code.