@powerhousedao/academy 5.1.0-dev.14 → 5.1.0-dev.17

package/docs/academy/08-Glossary.md

@@ -68,7 +68,7 @@
 - **Development Environment (Powerhouse)** – A local setup for developing Powerhouse applications, typically initiated with the `ph dev` command. It runs essential backend services like the Powerhouse Switchboard to enable real-time document model processing, code generation, and live updates, separate from the front-end Connect Studio.
 - **Document Model Editors** – An interface or UI to a document model that allows users to create and modify the data captured by the document models.
 - **Drive** – A logical container in Powerhouse for storing, organizing, and managing collections of documents.
-- **Drive App (Custom Drive Explorer)** – A UI application, often custom, providing tailored views and interactions with documents in a Drive.
+- **drive-app (Custom Drive Explorer)** – A UI application, often custom, providing tailored views and interactions with documents in a Drive.
 - **Environments (Powerhouse Environments)** – Pre-defined configurations for a project's Powerhouse dependencies, such as `dev` (development), `prod` (production/latest), and `local`. The Powerhouse CLI (`ph use` command) allows developers to easily switch between these environments to use different versions of packages (e.g., bleeding-edge, stable, or from a local monorepo).
 - **Host Applications** – Applications that use the Powerhouse framework to create and manage documents and data.
 - **Modules (in Document Model Editor)** – An organizational feature in Connect Studio's model editor for grouping related operations.

package/docusaurus.config.ts

@@ -86,12 +86,6 @@ const config: Config = {
         href: "/",
       },
       items: [
-        {
-          type: "docSidebar",
-          sidebarId: "academySidebar",
-          position: "left",
-          label: "Academy",
-        },
         {
           href: "https://github.com/powerhouse-inc/powerhouse-docs",
           label: "GitHub",
@@ -106,28 +100,12 @@ const config: Config = {
           title: "Docs",
           items: [
             {
-              label: "Connect",
-              to: "academy/Architecture/PowerhouseArchitecture",
-            },
-            {
-              label: "Reactor",
-              to: "academy/Architecture/PowerhouseArchitecture",
-            },
-            {
-              label: "Switchboard",
-              to: "academy/Architecture/PowerhouseArchitecture",
-            },
-            {
-              label: "Renown",
-              to: "academy/Architecture/PowerhouseArchitecture",
-            },
-            {
-              label: "FAQ",
+              label: "Powerhouse Architecture",
               to: "academy/Architecture/PowerhouseArchitecture",
             },
             {
-              label: "Blog",
-              to: "/blog",
+              label: "Cookbook",
+              to: "academy/Cookbook",
             },
           ],
         },
@@ -136,7 +114,7 @@ const config: Config = {
           items: [
             {
               label: "Discord",
-              href: "https://discord.gg/h7GKvqDyDP",
+              href: "https://discord.gg/pwQJwgaQKd",
             },
             {
               label: "X",
@@ -162,21 +140,21 @@ const config: Config = {
       magicComments: [
         // Default highlight
         {
-          className: 'theme-code-block-highlighted-line',
-          line: 'highlight-next-line',
-          block: { start: 'highlight-start', end: 'highlight-end' },
+          className: "theme-code-block-highlighted-line",
+          line: "highlight-next-line",
+          block: { start: "highlight-start", end: "highlight-end" },
         },
         // Green for additions
         {
-          className: 'code-block-added-line',
-          line: 'added-line',
-          block: { start: 'added-start', end: 'added-end' },
+          className: "code-block-added-line",
+          line: "added-line",
+          block: { start: "added-start", end: "added-end" },
         },
         // Red for deletions
         {
-          className: 'code-block-removed-line',
-          line: 'removed-line',
-          block: { start: 'removed-start', end: 'removed-end' },
+          className: "code-block-removed-line",
+          line: "removed-line",
+          block: { start: "removed-start", end: "removed-end" },
         },
       ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "5.1.0-dev.14",
+  "version": "5.1.0-dev.17",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/sidebars.ts

@@ -40,8 +40,8 @@ const sidebars = {
           },
           items: [
             "academy/MasteryTrack/BuilderEnvironment/Prerequisites",
-            "academy/MasteryTrack/BuilderEnvironment/StandardDocumentModelWorkflow",
             "academy/MasteryTrack/BuilderEnvironment/VetraStudio",
+            "academy/MasteryTrack/BuilderEnvironment/CreateAPackageWithVetra",
           ],
         },
         {
@@ -118,18 +118,9 @@ const sidebars = {
             "academy/ExampleUsecases/Chatroom/DefineChatroomDocumentModel",
             "academy/ExampleUsecases/Chatroom/ImplementOperationReducers",
             "academy/ExampleUsecases/Chatroom/ImplementChatroomEditor",
-            "academy/ExampleUsecases/Chatroom/LaunchALocalReactor",
           ],
         },
-        {
-          type: "category",
-          label: "Vetra Package Library",
-          link: {
-            type: "doc",
-            id: "academy/ExampleUsecases/VetraPackageLibrary/VetraPackageLibrary",
-          },
-          items: [],
-        },
+
         {
           type: "category",
           label: "Todo List Tutorial",
@@ -149,6 +140,15 @@ const sidebars = {
             "academy/ExampleUsecases/TodoList/AddSharedComponentForShowingTodoListStats",
           ],
         },
+        {
+          type: "category",
+          label: "Vetra Package Library",
+          link: {
+            type: "doc",
+            id: "academy/ExampleUsecases/VetraPackageLibrary/VetraPackageLibrary",
+          },
+          items: [],
+        },
       ],
     },
     {

package/src/css/custom.css

@@ -303,41 +303,18 @@ article > a,
 
 /* Dark mode adjustments */
 [data-theme="dark"] .path-button {
-  background-color: #1f1f20;
-  border: none; /* Remove default border */
-  position: relative; /* For pseudo-element positioning */
-  isolation: isolate; /* Ensures proper layering */
-}
-
-/* Gradient border effect - dark mode only */
-[data-theme="dark"] .path-button::before {
-  content: "";
-  position: absolute;
-  top: 0;
-  right: 0;
-  bottom: 0;
-  left: 0;
-  border-radius: 8px;
-  padding: 1px; /* Border width */
-  background: linear-gradient(90deg, #4633eb, #7a5cff);
-  -webkit-mask:
-    linear-gradient(#fff 0 0) content-box,
-    linear-gradient(#fff 0 0);
-  mask:
-    linear-gradient(#fff 0 0) content-box,
-    linear-gradient(#fff 0 0);
-  -webkit-mask-composite: xor;
-  mask-composite: exclude;
-  pointer-events: none;
+  background-color: #374151;
+  border: none !important;
+  color: #ffffff !important;
+  text-decoration: none !important;
 }
 
 /* Hover effects - dark mode */
 [data-theme="dark"] .path-button:hover {
+  background-color: #4b5563;
   transform: translateY(-2px);
-}
-
-[data-theme="dark"] .path-button:hover::before {
-  box-shadow: 0 0 15px rgba(74, 51, 235, 0.3); /* Subtle blue glow */
+  color: #ffffff !important;
+  text-decoration: none !important;
 }
 
 .path-card {
@@ -553,3 +530,24 @@ html[data-theme="dark"] .DocSearch-Hits > *:empty {
   background-color: rgba(248, 81, 73, 0.25);
 }
 
+/* Sidebar item count badge */
+.sidebar-item-count {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-left: 8px;
+  padding: 0 6px;
+  min-width: 20px;
+  height: 18px;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--ifm-color-emphasis-700);
+  background-color: var(--ifm-color-emphasis-200);
+  border-radius: 10px;
+}
+
+[data-theme="dark"] .sidebar-item-count {
+  color: var(--ifm-color-emphasis-300);
+  background-color: var(--ifm-color-emphasis-700);
+}
+

package/src/theme/DocSidebarItem/Category/index.tsx

@@ -0,0 +1,47 @@
+import type { PropSidebarItem } from "@docusaurus/plugin-content-docs";
+import type { WrapperProps } from "@docusaurus/types";
+import Category from "@theme-original/DocSidebarItem/Category";
+import type CategoryType from "@theme/DocSidebarItem/Category";
+import React from "react";
+
+type Props = WrapperProps<typeof CategoryType>;
+
+// Count only immediate children (docs, links, and categories)
+function countItems(items: PropSidebarItem[]): number {
+  let count = 0;
+  for (const item of items) {
+    if (
+      // @ts-expect-error TODO: check this type
+      item.type === "doc" ||
+      item.type === "link" ||
+      item.type === "category"
+    ) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+export default function CategoryWrapper(props: Props): React.JSX.Element {
+  const { item, level } = props;
+
+  // Only show count on top-level categories (level 1)
+  if (level !== 1) {
+    return <Category {...props} />;
+  }
+
+  const itemCount = countItems(item.items);
+
+  // Clone the item with a modified label that includes the count
+  const modifiedItem = {
+    ...item,
+    label: (
+      <>
+        {item.label}
+        <span className="sidebar-item-count">{itemCount}</span>
+      </>
+    ) as unknown as string,
+  };
+
+  return <Category {...props} item={modifiedItem} />;
+}

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./babel.config.js","./docusaurus.config.ts","./sidebars.ts","./scripts/generate-combined-cli-docs.ts","./src/components/HomepageFeatures/index.tsx","./src/pages/_archive-homepage.tsx","./src/theme/DocCardList/index.tsx"],"version":"5.9.3"}
+{"root":["./babel.config.js","./docusaurus.config.ts","./sidebars.ts","./scripts/generate-combined-cli-docs.ts","./src/components/HomepageFeatures/index.tsx","./src/pages/_archive-homepage.tsx","./src/theme/DocCardList/index.tsx","./src/theme/DocSidebarItem/Category/index.tsx"],"version":"5.9.3"}

package/docs/academy/02-MasteryTrack/01-BuilderEnvironment/05-VetraStudio.md

@@ -1,253 +0,0 @@
-# Vetra Studio 
-
-## Introducing Vetra Studio
-
-- **Vetra Studio Drive**: Serves as a hub for developers to access, manage & share specification through a remote Vetra drive. It functions as the orchestration hub where you as a builder assemble all the necessary specifications for your intended use-case, software solution or package. For each of the different **modules** that together form a package a  
-- **Vetra Package Library**: Store, publish and fork git repositories of packages in the Vetra Package Library.    
-Visit the [Vetra Package Library here](https://vetra.io/packages) 
-
-As Vetra Studio matures each of these specification documents will offer an interface by which you as a builder get more control over the modules that make up your package. 
-For now the specification documents offer you a template for code generation. 
-
-<figure className="image-container">
-  <img
-    src={require("./images/Modules.png").default}
-    alt="Modules"
-  />
-  <figcaption>The list of available modules color coded according to the 3 categories.</figcaption>
-</figure>
-
-### Module Categories
-
-### 1. Document Models 
-- **Document model specification**: Defines the structure and operations of a document model using GraphQL SDL, ensuring consistent data management and processing.
-
-### 2. User Experiences
-- **Editor specification**: Outlines the interface and functionalities of a document model editor, allowing users to interact with and modify document data.
-- **Drive-app specification**: Specifies the UI and interactions for managing documents within a Drive, providing tailored views and functionalities.
-
-### 3. Data integrations
-- **Subgraph specification**: Details the connections and relationships within a subgraph, facilitating efficient data querying and manipulation.
-- **Codegen Processor Specification**: Describes the process for automatically generating code from document model specifications, ensuring alignment with intended architecture.
-- **RelationalDb Processor Specification**: Defines how relational databases are structured and queried, supporting efficient data management and retrieval.
-
-<figure className="image-container">
-  <img
-    src={require("./images/VetraStudioDrive.png").default}
-    alt="Vetra Studio Drive"
-  />
-  <figcaption>The Vetra Studio Drive, a builder app that collects all of the specification of a package.</figcaption>
-</figure>
-
-### Configure a Vetra drive in your project
-
-You can connect to a remote vetra drive instead of using the local one auto-generated when you run `ph vetra`
-If you run Vetra without the `--remote-drive` option: Vetra will create a Vetra drive for you that is local and lives in your local environment / local browser storage. 
-If you provide the remote drive with `--remote-drive` argument: Vetra will use this drive instead of creating a local one. the remote drive can be hosted whatever you want.
-The powerhouse config includes a Vetra URL for consistent project configuration across different environments.
-
-```vetra: {
-    driveId: string;
-    driveUrl: string;
-};
-```
-
-Imagine you are a builder and want to work on, or continue with a set of specifications from your team mates. 
-You could then add the specific remote Vetra drive to your powerhouse configuration in the `powerhouse.config.json`file to get going. 
-
-```
-"vetra": {
-    "driveId": "bai-specifications",
-    "driveUrl": "https://switchboard.staging.vetra.io/d/bai-specifications"
-  }
-```
-
-An example of a builder team building on the Powerhouse Vetra Ecosystem and it's complementary Vetra Studio Drive specifications for the different packages be found [here](https://vetra.io/builders/bai)
-
-<details>
-<summary>📦 Vetra Remote Drive Commands</summary>
-
-Remote drives enable collaborative development by syncing specifications across team members.
-
-**Key Commands:**
-- `ph init --remote-drive <url>` - Create a NEW project connected to a remote drive
-- `ph checkout --remote-drive <url>` - Clone an EXISTING project from a remote drive  
-- `ph vetra --watch` - Start development with a preview drive for testing local changes
-
-**Workflows:**
-- **Project Owner**: `ph init --remote-drive` → Create GitHub repo → Push → `ph vetra` to configure
-- **Collaborator**: `ph checkout --remote-drive` → `ph vetra` to start developing
-
-**Preview Drive (`--watch` mode):**
-- Main "Vetra" drive syncs with remote and contains stable package configuration
-- "Vetra Preview" drive is created locally for testing document models before syncing
-
-→ [Full Vetra Remote Drive Reference](/academy/APIReferences/VetraRemoteDrive)
-
-</details>
-
-## Vetra Studio Workflow
-
-### 1. Launch Vetra Studio
-
-You can launch Vetra Studio in two modes:
-
-#### Interactive Mode (Recommended for Development)
-```bash
-ph vetra --interactive
-```
-In interactive mode:
-- You'll receive confirmation prompts before any code generation
-- Changes require explicit confirmation before being processed
-- Provides better control and visibility over document changes
-
-#### Watch Mode 
-
-```bash
-ph vetra --interactive --watch
-```
-In watch mode:
-
-- Adding `--watch` to your command enables dynamic loading for document-models and editors in Vetra studio and switchboard. 
-- When enabled, the system will watch for changes in these directories and reload them dynamically.
-
-:::warning Be Aware
-When you are building your document model the code can break the Vetra Studio environment. 
-A full overview of the Vetra Studio commands can be found in the [Powerhouse CLI](/academy/APIReferences/PowerhouseCLI#vetra)
-:::
-
-#### Standard Mode
-```bash
-ph vetra
-```
-In standard mode:
-- Changes are processed automatically with 1-second debounce
-- Multiple changes are batched and processed together
-- Uses the latest document state for processing
-
-### 2. Launch Claude with Reactor-MCP
-
-Vetra Studio integrates deeply with Claude through MCP (Model Control Protocol). This is where AI comes into the mix and you get the chance to have greater control and direction over what your llm is coding for you. 
-
-<details>
-<summary>**Specification Driven AI**</summary>
-
-In the **'Get Started'** chapter we've been making use of strict schema definition principles to communicate the intended use case of our reactive documents. 
-The **schema definition language**, is a not only a shared language that bridges the gap between developer, designer and analyst but also the gap between builder and AI-agent through **specification driven AI control**.
-
-- Communicate your solution and intent through a structured specification framework designed for AI collaboration.
-- Specifications enable precise, iterative edits, since all our specification documents are machine-readable and executable.
-
-</details>
-
-#### 1. Start the Reactor MCP:
-
-Make sure you are in the same directory as your project. 
-Claude will automatically recognize the necessary files and MCP tools. 
-
-```bash
-claude
-```
-
-Since you're interacting with a llm it has a high capacit for interpretating your intentions. 
-Any commands in the same trend will do the job. 
-
-```bash
-connect to the reactor mcp
-```
-
-#### 2. Verify MCP connection:
-- Check that the Reactor MCP is available. 
-- Confirm Vetra Studio shows "Connected to Reactor MCP"
-
-```bash
-Connected to MCP successfully! I can see there's a
-  "vetra-4de7fa45" drive available. The reactor-mcp server is
-  running and ready for document model operations.
-```
-
-<details>
-<summary>🤖 Reactor MCP Overview</summary>
-
-### Key Reactor MCP Features
-
-**Reactor-mcp** is a Model Context Protocol (MCP) server that bridges AI agents with Powerhouse document operations.
-
-- It supports automatic document model creation from natural language descriptions
-- It implements a smart editor based on the underlying document models
-- It automatically triggers code generation when documents reach valid state
-- The MCP server enables the agent to work with both existing and newly created document models
-- Vetra supports integration with custom remote drives, allowing users to create, share and manage documents within these drives
-
-**Document Operations:**
-- `createDocument` / `getDocument` / `deleteDocument` - Manage documents
-- `addActions` - Modify document state through operations
-
-**Drive Operations:**
-- `getDrives` / `addDrive` / `getDrive` - Manage document drives
-- `addRemoteDrive` - Connect to remote drives
-
-**Document Model Operations:**
-- `getDocumentModels` - List available document model types
-- `getDocumentModelSchema` - Get schema for specific models
-
-**Document Model Agent:**
-A specialized AI agent that guides users through document model creation with requirements gathering, design confirmation, and implementation including state schema definition, operation creation, and code generation.
-
-</details>
-
-
-### 3. Vetra Studio Package Creation Workflow
-
-#### A. Set Package Description (Required)
-1. Provide a name for your package
-2. Add a meaningful description
-3. Add keywords to add search terms to your package
-4. Confirm changes when prompted in interactive mode
-
-#### B. Define Document Model (Required)
-You can create document models in two ways:
-
-1. **Using MCP (AI-Assisted)**
-   - Describe your document needs in natural language in great detail.
-   - Claude will:
-     - Generate an appropriate schema
-     - Create the necessary operations
-     - Implement the required reducers
-     - Place the document in the Vetra drive
-
-2. **Manual Creation**
-   - Define document schema with fields and types as in the **'Get Started'**
-   - Create the necessary operations
-   - Add the required modules to your package
-   - The document model creation chapter in the Mastery track provides in depth support [here](apps/academy/docs/academy/MasteryTrack/DocumentModelCreation/SpecifyTheStateSchema)
-
-#### C. Add Document Editor (Required)
-1. **Using MCP (AI-Assisted)**
-   - Request Claude to create an editor for your document. Do this with the help of a detailed description of the user interface, user experience and logic that you wish to generate. Make sure to reference operations from the document model to get the best results
-   - Claude will:
-     - Generate editor components
-     - Implement necessary hooks
-     - Create required UI elements
-
-2. **Manual Creation**
-   - Select your target document model
-   - Configure the currently limited editor properties
-   - Add the editor specification to Vetra Studio drive
-   - The system will generate scaffolding code
-
-#### D. Data Integrations (Coming Soon)
-Support for:
-- Subgraph integration
-- Code generation processors
-- Relational database processors
-
-### Best Practices
-
-**Working with MCP and claude**
-   - Provide clear, specific instructions and ask for clarifying questions to be answered before code generation.
-   - Review generated schemas before confirmation and work in layers instead of 'one-shotting' your code. 
-   - Verify implementation details in generated code before continuing. 
-   - Always double-check proposed next actions
-
-

package/docs/academy/02-MasteryTrack/05-Launch/01-IntroductionToPackages.md

@@ -1,78 +0,0 @@
-# Introduction to packages
-
-Packages of document models are a core structuring mechanism in the Powerhouse framework, allowing developers to group and manage related document models efficiently. These packages serve as modular collections of document definitions, ensuring consistency, scalability, and reusability across different applications.
-
-By packaging document models together, developers can create well-organized, interoperable sets of data structures that capture the specific needs of various operational processes. Whether used for financial operations, governance, or contributor management, these packages streamline development and integration within Powerhouse's decentralized framework.
-
-### Key features of packages
-
-- **Modular Structure** – Packages encapsulate related document models, making it easier to manage and deploy them as a cohesive unit.
-- **Standardized Definitions** – Each document model within a package follows Powerhouse's structured schema approach, ensuring consistency in data representation.
-- **Reusability and Extensibility** – Packages can be shared across different projects or extended with additional models as needed.
-- **Dependency Management** – Developers can define dependencies between document models, ensuring proper relationships and data flows between interconnected components.
-- **Automated Schema Evolution** – Versioning mechanisms allow document models within a package to evolve over time without breaking existing functionality.
-
-### Example use cases of packages
-
-- **Finance Package** – A set of document models handling invoices, payments, budgets, and financial reporting. link
-- **Contributor Billing Package** – Defines document models for tracking work, invoicing, and facilitating payments (in both fiat and crypto) for contributors in decentralized organizations. link
-- **Governance Package** – Models for proposals, voting, contributor agreements, and decision-making processes. link
-- **People Ops Package** – Documents managing contributor profiles, roles, task assignments, and reputation tracking. link
-- **Project Management Package** – Models for task tracking, milestones, resource allocation, and deliverables. link
-
-  A **Powerhouse Package** is a **modular unit** that defines and automates **data structures and workflows** within the Powerhouse ecosystem. Each package includes several components that work together to ensure **seamless interaction, data processing, and automation** for different areas of decentralized operations.
-
-Packages follow a **scoped naming convention** based on the organization that owns them or created the package:
-
-- `@powerhousedao` The organization behind Powerhouse.
-- `@sky-ph` The Sky / MakerDAO organization with a -ph suffix to indicate it concerns Powerhouse ecosystem packages.
-- `@myorg-ph` Your organization with the -ph suffix included.
-
-Within a package, you'll find **several key modules**, each serving a distinct role in structuring and processing data.
-
----
-
-## Modules of a Powerhouse package
-
-### 1. Document model
-
-The **core component** of any package, defining how data is structured and manipulated.
-
-- Specifies **schemas** (data structures) and **state transitions** (operations).
-- Serves as the foundation for decentralized workflows.
-- **Example:** An **Invoice** document model might define fields like `issuer`, `recipient`, `amount`, and operations like `ADD_LINE_ITEM` or `MARK_AS_PAID`.
-
-### 2. Document model editor
-
-A **UI component** that allows users to **interact with document models visually**.
-
-- Enables users to **create, modify, and manage** documents without coding.
-- Supports multiple editors for a single document model, offering different **UI experiences** tailored to specific roles.
-
-### 3. Scripts
-
-**Automated actions** that run on demand or on a schedule.
-
-- Executes **one-time or recurring tasks** within a package.
-- Not continuously running—activated manually or at predefined intervals.
-- **Example:** A script that **generates a weekly financial report** from invoice data.
-
-### 4. Processors
-
-**Event-driven background tasks** that react to document changes.
-
-- Subscribes to **document operations or system events** and processes data automatically.
-- Supports real-time **data updates, analytics, and workflow automation**.
-- **Example:** A processor that **monitors new invoices** and updates an **analytics dashboard** in real-time.
-
-### 5. Drive-apps
-
-**Custom interfaces** that provide enhanced ways to interact with a package's document models.
-
-- Allows **visualization, sorting, and organization** of drive contents (e.g., **Kanban boards, list views**).
-- Can aggregate data and display **key insights** from document models.
-- **Example:** A Drive-App for **People Ops** might show a **dashboard of contributor profiles, role assignments, and activity logs**.
-
----
-
-Each of these modules plays a crucial role in making **Powerhouse Packages extensible, reusable, and efficient**, allowing developers and organizations to **streamline operations and automate workflows** within decentralized environments.