@powerhousedao/academy 5.0.0-staging.8 → 5.0.1-staging.2

package/docs/academy/01-GetStarted/05-VetraStudio.md

@@ -0,0 +1,164 @@
+# Tool: Vetra Studio 
+
+This chapter introduces you to one of the most powerfull features of the Powerhouse development framework: Specification Driven AI-control.  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. 
+
+:::tip Important
+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**. 
+:::
+
+## Vision: Specification Driven AI
+
+At Powerhouse we are embracing the progress of AI assisted coding while unlocking the next level of AI control 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.
+- Specifications offer the ability to update exact parameters and properties as your specs evolve in lock-step with your agent. 
+- Specifications turn fragile sandcastles into solid, editable, and maintainable functionality with predictable results.
+
+This approach allows for the creation of editable specifications, enabling business analysts to modify details and instruct the AI to generate code based on updated specifications.
+It results in composable, maintainable, and scalable functionality.
+
+## Introducing Vetra Studio
+
+**Vetra Studio** serves as a centralized hub for developers to access and manage specifications. 
+It allows developers to open packages (Git repositories with metadata) from a Vetra package library, providing access to a remote Vetra drive where all specifications are stored. 
+
+This setup ensures that all necessary documentation and project requirements are in one accessible location, streamlining communication and agreement on requirements and operations. Additionally, **Vetra Studio** 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 specification document can be created in **Vetra Studio**. 
+
+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. 
+
+<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>
+
+## 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
+
+#### 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. 
+
+#### 1. Start the Reactor MCP:
+```bash
+ph mcp
+```
+
+#### 2. Verify MCP connection:
+- Check that the Reactor MCP is available. 
+- Confirm Vetra Studio shows "Connected to Reactor MCP"
+
+-  To learn what is a [Reactor] itself read (apps/academy/docs/academy/Architecture/WorkingWithTheReactor)
+-  To learn more about the [Reactor MCP] read (apps/academy/docs/academy/GetStarted/ReactorMCP)
+
+#### Key Reactor MCP Features:
+- Automatic document model creation from natural language descriptions
+- Smart editor generation based on document models
+- Automatically triggers code generation when documents reach valid state
+
+The powerhouse config includes a vetra URL for consistent project configuration across different environments.
+
+:::tip
+- Vetra supports integration with custom remote drives, allowing users to create, share and manage documents within these drives.
+- The MCP server enables the agent to work with both existing and newly created document models.
+:::
+
+### 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/01-GetStarted/06-ReactorMCP.md

@@ -0,0 +1,58 @@
+# Tool: Reactor MCP
+
+**Reactor-mcp** is a Model Context Protocol (MCP) server for the Powerhouse ecosystem that provides AI agents and tools with structured access to document model operations. 
+It serves as a bridge between AI systems and the Powerhouse document management infrastructure.
+
+## Main Functions of the Reactor-mcp
+
+**Document Operations**:
+- createDocument - Create new documents
+- getDocument - Retrieve documents by ID
+- addActions - Add actions to modify document state
+- deleteDocument - Remove documents
+
+**Drive Operations**:
+- getDrives - List all document drives
+- addDrive - Create new drives
+- getDrive - Retrieve specific drives
+- addRemoteDrive - Connect to remote drives
+
+**Document Model Operations**:
+- getDocumentModels - List available document model types
+- getDocumentModelSchema - Get schema for specific document models
+
+<details>
+<summary>Architecture Context</summary>
+
+Within the broader Powerhouse ecosystem:
+
+- Document Model: Defines structure and operations for document types
+- Document Drive: Manages collections of documents with sync capabilities
+- Reactor-MCP: Provides AI/tool access to document operations
+- Connect/Switchboard: User interfaces and synchronization servers
+
+The reactor-mcp essentially makes the sophisticated document model system accessible to AI agents and external tools through a standardized protocol, enabling programmatic document creation, modification, and management within the Powerhouse ecosystem.
+
+</details>
+
+### Document Model Agent
+
+Alongside the MCP is a **specialized AI agent** for document model creation:
+
+- Purpose: Guide users through creating document models
+- Workflow: Requirements gathering → Design confirmation → Implementation
+- Tools: Comprehensive set of MCP tools for model management
+- Capabilities: 
+    - State schema definition
+    - Operation creation
+    - Module organization
+    - Code generation
+
+:::tip Supports with:
+
+1. **AI-Assisted Document Model Creation**: AI agents can use the MCP tools to help users create and modify document models
+2. **Automated Document Management**: Programmatic creation and management of documents and drives
+3. **Integration with AI Tools**: Claude, GPT, or other AI systems can use this as an MCP server to interact with Powerhouse
+4. **Development Tooling**: CLI and development server for working with document models locally
+:::
+

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

@@ -4,9 +4,9 @@ slug: /
 sidebar_class_name: category-index-page
 ---
 
-import React from 'react';
-import styles from './styles.module.css';
-import BrowserOnly from '@docusaurus/BrowserOnly';
+import React from "react";
+import styles from "./styles.module.css";
+import BrowserOnly from "@docusaurus/BrowserOnly";
 
 <div className={styles.learningPath}>
   {/* Get Started Card - Full Width */}
@@ -44,108 +44,203 @@ import BrowserOnly from '@docusaurus/BrowserOnly';
     </div>
   </div>
 
-  {/* Row 1: [Empty Placeholder], Create, [Empty Placeholder] */}
-  <div></div> {/* Placeholder for the deleted "New Link" card */}
+{/* Row 1: [Empty Placeholder], Create, [Empty Placeholder] */}
 
-  <div className={styles.pathCard} style={{ border: '1px solid #4FC86F' }}>
-    <div className={styles.cardHeader}>
-      <h3 className="card-title">
-        <img src="/img/academy/icons/Flash.svg" alt="" className={styles.titleIcon} />
-        Get started
-      </h3>
-    </div>
-    <div className={styles.cardContent}>
-      <a href="/academy/GetStarted/CreateNewPowerhouseProject" className="path-button">Build a todo-list document model</a>
-    </div>
+<div></div> {/* Placeholder for the deleted "New Link" card */}
+
+<div className={styles.pathCard} style={{ border: "1px solid #4FC86F" }}>
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img
+        src="/img/academy/icons/Flash.svg"
+        alt=""
+        className={styles.titleIcon}
+      />
+      Get started
+    </h3>
+  </div>
+  <div className={styles.cardContent}>
+    <a
+      href="/academy/GetStarted/CreateNewPowerhouseProject"
+      className="path-button"
+    >
+      Build a todo-list document model
+    </a>
   </div>
+</div>
 
-  <div></div> {/* Placeholder for the deleted "Document Model Theory" card */}
+<div></div> {/* Placeholder for the deleted "Document Model Theory" card */}
 
-  {/* Row 2: Build User Experiences, Builder Track Image, Work with Data */}
-  <div className={styles.pathCard} style={{ border: '1px solid #4FC86F' }}>
-    <div className={styles.cardHeader}>
-      <h3 className="card-title">
-        <img src="/img/academy/icons/Editor.svg" alt="" className={styles.titleIcon} />
-        Build user experiences
-      </h3>
-    </div>
-    <div className={styles.cardContent}>
-      <a href="/academy/GetStarted/BuildToDoListEditor" className="path-button">Build a todo-list editor</a>
-      <a href="/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors" className="path-button">Build document editors</a>
-      <a href="/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer" className="path-button">Build custom drive explorers</a>
-      <a href="/academy/ComponentLibrary/DocumentEngineering" className="path-button">Component library</a>
-    </div>
+{/* Row 2: Build User Experiences, Builder Track Image, Work with Data */}
+
+<div className={styles.pathCard} style={{ border: "1px solid #4FC86F" }}>
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img
+        src="/img/academy/icons/Editor.svg"
+        alt=""
+        className={styles.titleIcon}
+      />
+      Build user experiences
+    </h3>
   </div>
+  <div className={styles.cardContent}>
+    <a href="/academy/GetStarted/BuildToDoListEditor" className="path-button">
+      Build a todo-list editor
+    </a>
+    <a
+      href="/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors"
+      className="path-button"
+    >
+      Build document editors
+    </a>
+    <a
+      href="/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer"
+      className="path-button"
+    >
+      Build custom drive explorers
+    </a>
+    <a
+      href="/academy/ComponentLibrary/DocumentEngineering"
+      className="path-button"
+    >
+      Component library
+    </a>
+  </div>
+</div>
 
-  <div className={styles.middleColumn} style={{
-    display: 'flex',
-    justifyContent: 'center',
-    alignItems: 'flex-start',
-    paddingTop: '-20px',
-    position: 'relative'
-  }}>
-    <img src="/img/Union.svg" alt="Powerhouse Union" width="250" />
-    <div className={styles.masteryTrackTitle}>
-      <h3 className="card-title" style={{ margin: 0 }}>Mastery track</h3>
-    </div>
+<div
+  className={styles.middleColumn}
+  style={{
+    display: "flex",
+    justifyContent: "center",
+    alignItems: "flex-start",
+    paddingTop: "-20px",
+    position: "relative",
+  }}
+>
+  <img src="/img/Union.svg" alt="Powerhouse Union" width="250" />
+  <div className={styles.masteryTrackTitle}>
+    <h3 className="card-title" style={{ margin: 0 }}>
+      Mastery track
+    </h3>
   </div>
+</div>
 
-  <div className={styles.pathCard} style={{ border: '1px solid #4FC86F' }}>
-    <div className={styles.cardHeader}>
-      <h3 className="card-title">
-        <img src="/img/academy/icons/Data.svg" alt="" className={styles.titleIcon} />
-        Work with data
-      </h3>
-    </div>
-    <div className={styles.cardContent}>
-      <a href="/academy/MasteryTrack/WorkWithData/UsingTheAPI" className="path-button">Read & write through the API</a>
-      <a href="/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs" className="path-button">Create your own subgraph</a>
-      <a href="/academy/MasteryTrack/WorkWithData/Analytics-Engine/intro" className="path-button">Use the analytics engine</a>
-    </div>
+<div className={styles.pathCard} style={{ border: "1px solid #4FC86F" }}>
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img
+        src="/img/academy/icons/Data.svg"
+        alt=""
+        className={styles.titleIcon}
+      />
+      Work with data
+    </h3>
+  </div>
+  <div className={styles.cardContent}>
+    <a
+      href="/academy/MasteryTrack/WorkWithData/UsingTheAPI"
+      className="path-button"
+    >
+      Read & write through the API
+    </a>
+    <a
+      href="/academy/MasteryTrack/WorkWithData/WorkingWithSubgraphs"
+      className="path-button"
+    >
+      Create your own subgraph
+    </a>
+    <a
+      href="/academy/MasteryTrack/WorkWithData/Analytics-Engine/intro"
+      className="path-button"
+    >
+      Use the analytics engine
+    </a>
   </div>
+</div>
 
-  {/* Launch Card - Full Width with 3 column buttons - RE-INSERTED */}
-  <div className={`${styles.pathCard} ${styles.fullWidth}`}>
-    <div className={styles.cardHeader}>
-      <h3 className="card-title">
-        <img src="/img/academy/icons/Launch.svg" alt="" className={styles.titleIcon} />
-        Launch
-      </h3>
-    </div>
-    <div className={styles.cardContent}>
-      <div className={styles.buttonContainer}>
-        <a href="/academy/MasteryTrack/Launch/IntroductionToPackages" className="path-button">Intro to packages</a>
-        <a href="/academy/MasteryTrack/Launch/PublishYourProject" className="path-button">Publish your project</a>
-        <a href="/academy/MasteryTrack/Launch/SetupEnvironment" className="path-button">Set-up a cloud environment</a>
-      </div>
+{/* Launch Card - Full Width with 3 column buttons - RE-INSERTED */}
+
+<div className={`${styles.pathCard} ${styles.fullWidth}`}>
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img
+        src="/img/academy/icons/Launch.svg"
+        alt=""
+        className={styles.titleIcon}
+      />
+      Launch
+    </h3>
+  </div>
+  <div className={styles.cardContent}>
+    <div className={styles.buttonContainer}>
+      <a
+        href="/academy/MasteryTrack/Launch/IntroductionToPackages"
+        className="path-button"
+      >
+        Intro to packages
+      </a>
+      <a
+        href="/academy/MasteryTrack/Launch/PublishYourProject"
+        className="path-button"
+      >
+        Publish your project
+      </a>
+      <a
+        href="/academy/MasteryTrack/Launch/SetupEnvironment"
+        className="path-button"
+      >
+        Set-up a cloud environment
+      </a>
     </div>
   </div>
+</div>
 
-  {/* Row 3: Cookbook, Use-cases, Advanced Topics */}
-  <div className={styles.pathCard}>
-    <div className={styles.cardHeader}>
-      <h3 className="card-title">
-        <img src="/img/academy/icons/Cookbook.svg" alt="" className={styles.titleIcon} />
-        Cookbook
-      </h3>
-    </div>
-    <div className={styles.cardContent}>
-      <a href="/academy/Cookbook" className="path-button">Powerhouse recipes</a>
-    </div>
+{/* Row 3: Cookbook, Use-cases, Advanced Topics */}
+
+<div className={styles.pathCard}>
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img
+        src="/img/academy/icons/Cookbook.svg"
+        alt=""
+        className={styles.titleIcon}
+      />
+      Cookbook
+    </h3>
   </div>
+  <div className={styles.cardContent}>
+    <a href="/academy/Cookbook" className="path-button">
+      Powerhouse recipes
+    </a>
+  </div>
+</div>
 
-  {/* Ensure this Use-cases Card block is clean */}
-  <div className={styles.pathCard}> {/* New Use-cases Card */}
-    <div className={styles.cardHeader}>
-      <h3 className="card-title">
-        <img src="/img/academy/icons/Cookbook.svg" alt="Use-cases Icon" className={styles.titleIcon} />
-        Use-cases
-      </h3>
-    </div>
-    <div className={styles.cardContent}>
-      <a href="/academy/ExampleUsecases/Chatroom/SetupBuilderEnvironment" className="path-button">Explore use-cases</a>
-    </div>
+{/* Ensure this Use-cases Card block is clean */}
+
+<div className={styles.pathCard}>
+  {" "}
+  {/* New Use-cases Card */}
+  <div className={styles.cardHeader}>
+    <h3 className="card-title">
+      <img
+        src="/img/academy/icons/Cookbook.svg"
+        alt="Use-cases Icon"
+        className={styles.titleIcon}
+      />
+      Use-cases
+    </h3>
+  </div>
+  <div className={styles.cardContent}>
+    <a
+      href="/academy/ExampleUsecases/Chatroom/SetupBuilderEnvironment"
+      className="path-button"
+    >
+      Explore use-cases
+    </a>
   </div>
+</div>
 
   <div className={styles.pathCard}>
     <div className={styles.cardHeader}>
@@ -158,4 +253,4 @@ import BrowserOnly from '@docusaurus/BrowserOnly';
       <a href="/academy/Architecture/PowerhouseArchitecture" className="path-button">Learn more</a>
     </div>
   </div>
-</div>
+</div>

package/docs/academy/01-GetStarted/styles.module.css

@@ -101,23 +101,23 @@
   top: 18px;
 }
 
-:global([data-theme='dark']) .masteryTrackTitle {
+:global([data-theme="dark"]) .masteryTrackTitle {
   background-color: var(--ifm-card-background-color);
   border: 1px solid var(--ifm-color-emphasis-200);
 }
 
-:global([data-theme='dark']) .pathCard {
+:global([data-theme="dark"]) .pathCard {
   background: var(--ifm-card-background-color);
   border: 1px solid var(--ifm-color-emphasis-200);
 }
 
-:global([data-theme='dark']) :global(.path-button) {
+:global([data-theme="dark"]) :global(.path-button) {
   background: var(--ifm-color-emphasis-100);
   border-color: var(--ifm-color-emphasis-200);
   color: var(--ifm-font-color-primary);
 }
 
-:global([data-theme='dark']) :global(.path-button:hover) {
+:global([data-theme="dark"]) :global(.path-button:hover) {
   background: var(--ifm-color-emphasis-200);
   border-color: var(--ifm-color-emphasis-300);
-}
+}