@powerhousedao/academy 4.1.0-dev.117 → 4.1.0-dev.118

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.1.0-dev.118 (2025-11-14)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
 ## 4.1.0-dev.117 (2025-11-13)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

package/docs/academy/00-EthereumArgentinaHackathon.md

@@ -0,0 +1,183 @@
+---
+id: EthereumArgentinaHackathon
+title: Ethereum Argentina Hackathon
+---
+
+# Ethereum Argentina Hackathon
+
+**November 19-20, 2024**
+
+Welcome to the Vetra hacker page for the Ethereum Argentina Hackathon! We're excited to support developers building with Powerhouse during this event.
+
+## Overview
+
+Join us for two days of intensive development support as you build decentralized applications using the Powerhouse framework. Our team will be available online and at the mentor's table to help you navigate the platform, answer questions, and guide you through best practices.
+
+## 📅 Event Details
+
+- **Dates**: November 19-20, 2024
+- **Format**: Online & IRL Developer Support
+- **Time Zone**: Argentina Time (ART)
+- **Support Hours at Mentor Table @ la Rural**: TBD
+- **Hackathon informations**: https://taikai.network/ethargentina/hackathons/tierra-de-buidlers-2025/overview
+- Discord: [Join our server](#)
+
+## 🚀 Getting Started
+
+<details>
+<summary> Vetra Introduction & Follow Along Demo </summary>
+
+Here you will soon find our follow along introduction Demo Video
+
+### Before the Hackathon
+
+1. **Set Up Your Environment**
+   - Install the Powerhouse CLI
+   - Set up your development environment
+   - Review the [Get Started Guide](./01-GetStarted/home.mdx)
+
+2. **Explore the Platform**
+   - Check out the [Demo Package](./01-GetStarted/00-ExploreDemoPackage.mdx)
+   - Familiarize yourself with [Document Models](./02-MasteryTrack/02-DocumentModelCreation/01-WhatIsADocumentModel.md)
+
+3. **Join Our Community**
+   - Discord: [Join our server](#)
+
+
+</details>
+
+
+
+## **Example Project Ideas**
+
+Powerhouse is perfect for building:
+
+- **Real World Use-cases**: Every document can act as a mini ledger/blockchain. 
+- **Decentralized Applications**: Create apps with built-in version control and collaboration
+- **Document-Based Systems**: Build structured data applications
+- **Collaborative Tools**: Enable real-time multi-user editing
+- **Data Management Platforms**: Create systems with queryable, structured data
+
+### Coordination & DAO Design
+
+- 🧩 **What if** DAOs weren't chaotic? What documents would you need to make them coordinate like space X and ship like stripe?
+- 🎯 **What if** making decisions as a group felt like playing a co-op strategy game. With a clearly aligned vision, instant dashboards and a way to capture hard won knowledge in expertise into custom software for the Dao?
+
+:::tip IDEA
+The ultimate DAO Template toolkit where vision & mission documents influence guidelines & onboarding for contributors.
+:::
+
+---
+
+### GovTech & Public Infrastructure
+
+- 🗳 **What if** local governments had to reach consensus with residents before making a decision? How would that look like?
+- 🚧 **What if** you could submit pothole fixes or transit complaints into a civic DAO, and track the response like GitHub issues?
+- 🧾 **What if** municipal budgets were editable public documents with community feedback loops?
+
+:::tip IDEA
+An Open Source Enterprise Resource Planning-suite for municipalities & governments
+:::
+
+---
+
+### Education & Group Work
+
+- 📝 **What if** your group project auto-divided work, tracked contributions, and paid out in real-time?
+- 👾 **What if** "homework" was a multiplayer quest, and grades came from the DAO?
+- 🏫 **What if** we DAO-ified a classroom and let the students vote on rules, roles, and rewards?
+
+:::tip IDEA
+The remote classroom SAAS back-end that fosters connection, gives purpose to bullies and empowers younger generation to dream big again.
+:::
+
+---
+
+### 💸 Grants, Crypto, and Incentive Design
+
+- 💰 **What if** grant tooling felt like bounty hunting across a galaxy of projects?
+- 📊 **What if** every grant had a live budget dashboard, contributor feed, and impact score?
+- 🎮 **What if** you could stake on coordination itself, betting that people will work together well?
+
+:::tip IDEA
+The future of grant platforms that dares to imagine grants in new ways. With follow up, tracking and impact visualisations of teams, time, risk & resources invested.
+:::
+
+---
+
+### 💸 Lawmaking, Legislation & Legal
+
+- 🧑‍⚖️ **What if** any government or DAO could fork a legal template, customize it, and track changes in a public, composable way?
+- 🎨 **What if** legislation could be transparently co-created by citizens, NGOs, and governments all with aligned incentives?
+- 💻 **What if** legislation, contracts & templates could exist on an open-source market place like software?
+- 🤖 **What if** a network agent could create a legal vehicle by simply inputing  set of requirements and risk preferences (in non legalese)?
+- 🤝 **What if** 2 agents in a network could negotiate terms of an agreement according to predefined functions and risk parameters, without lawyers?
+
+:::tip IDEA
+Build a Decentralized Lawmaking Engine using Reactive Document Models
+:::
+
+
+## 🛠️ Resources
+
+### Documentation
+
+- [Quick Start Guide](./01-GetStarted/home.mdx)
+- [Create a New Project](./01-GetStarted/01-CreateNewPowerhouseProject.md)
+- [Define Document Models](./01-GetStarted/02-DefineToDoListDocumentModel.md)
+- [Build Editors](./01-GetStarted/04-BuildToDoListEditor.md)
+- [API References](./04-APIReferences/00-PowerhouseCLI.md)
+
+### Tutorials
+
+- [To-Do List Example](./01-GetStarted/02-DefineToDoListDocumentModel.md)
+- [Chatroom Use Case](./03-ExampleUsecases/Chatroom/02-CreateNewPowerhouseProject.md)
+
+## 🏆 Judging Criteria
+
+Projects will be evaluated based on:
+
+- **Usefulness & Impact**: How well does it solve a certain job or problem?
+- **Composability/Structure**: How are the different document models and / or drive apps collaborating?
+- **Clarity of the developer or user experience**: Did you unlock the secret sauce of UX & reactive documents?
+- **Alignment with Vetra/Powerhouse principles**: Local-first, auditable, usefull for common good. 
+
+## 📋 Submission Guidelines
+
+### What to Submit
+
+- GitHub repository with your code
+- (Video) presentation (2-3 minutes)
+- README with:
+  - Project description
+  - Setup instructions
+  - Screenshots/demos
+  - Technologies used
+
+The Powerhouse team will add you as a builder on the Vetra platform and host your application and drive. 
+
+
+## Tips for Success
+
+### Development Tips
+
+1. **Start Simple**: Begin with a basic implementation and iterate
+2. **Use Templates**: Leverage existing examples and templates
+3. **Ask Questions**: Don't hesitate to reach out for help
+4. **Test Early**: Test your application frequently during development
+5. **Document**: Keep notes on your decisions and implementations
+
+### Presentation Tips
+
+1. **Show, Don't Tell**: Live demos are more impactful than slides
+2. **Tell a Story**: Explain the problem you're solving
+3. **Highlight Innovation**: Show what makes your solution unique
+4. **Be Concise**: Respect the time limits for presentations
+5. **Prepare Backup**: Have screenshots/video in case of technical issues
+
+---
+
+**Good luck, and happy hacking! 🚀**
+
+*Last updated: November 13, 2024*
+

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

@@ -1,31 +1,26 @@
 # 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**.
+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.
-- 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. 
+**Vetra Studio Drive**: Serves as a hub for developers to access, manage & share specification through a remote Vetra drive.   
+**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)
 
-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**. 
+**Vetra Studio Drive** 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 Drive. 
 
 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 they offer you a template for code generation. 
 
 <figure className="image-container">
   <img
@@ -37,14 +32,14 @@ As Vetra Studio matures each of these specification documents will offer an inte
 
 ### Module Categories
 
-#### 1. Document Models 
+### 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
+### 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
+### 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.
@@ -57,6 +52,31 @@ As Vetra Studio matures each of these specification documents will offer an inte
   <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)
+
 ## Vetra Studio Workflow
 
 ### 1. Launch Vetra Studio
@@ -72,6 +92,21 @@ In interactive mode:
 - 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
@@ -86,28 +121,42 @@ In standard mode:
 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:
+
+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
-ph mcp
+connect to the reactor 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)
+```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.
+```
 
-#### 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
+-  To learn what is a [Reactor](apps/academy/docs/academy/Architecture/WorkingWithTheReactor) read the reactor article
+-  To learn more about the [Reactor MCP](apps/academy/docs/academy/GetStarted/ReactorMCP) read the reactor MCP article
 
-The powerhouse config includes a vetra URL for consistent project configuration across different environments.
+### Key Reactor MCP Features
 
-:::tip
-- Vetra supports integration with custom remote drives, allowing users to create, share and manage documents within these drives.
+- 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.
+
 
 ### 3. Vetra Studio Package Creation Workflow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "4.1.0-dev.117",
+  "version": "4.1.0-dev.118",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/sidebars.ts

@@ -11,6 +11,14 @@
 const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   academySidebar: [
+    {
+      type: "doc",
+      id: "academy/EthereumArgentinaHackathon",
+      label: "ETH Argentina Hackathon",
+      customProps: {
+        icon: "/img/ethereum-logo.jpg",
+      },
+    },
     {
       type: "category",
       label: "Get started",

package/src/css/custom.css

@@ -525,3 +525,23 @@ html[data-theme="dark"] .DocSearch-Hits > *:empty {
   margin-top: 0.5rem;
   font-style: italic;
 }
+
+/* Ethereum Argentina Hackathon sidebar icon */
+.menu__link[href*="EthereumArgentinaHackathon"] {
+  display: flex !important;
+  align-items: center !important;
+  gap: 8px !important;
+}
+
+.menu__link[href*="EthereumArgentinaHackathon"]::before {
+  content: "" !important;
+  display: inline-block !important;
+  width: 24px !important;
+  height: 24px !important;
+  min-width: 24px !important;
+  background-image: url("/img/ethereum-logo.jpeg") !important;
+  background-size: cover !important;
+  background-position: center !important;
+  border-radius: 50% !important;
+  flex-shrink: 0 !important;
+}

package/docs/academy/09-AIResources

@@ -1,131 +0,0 @@
-# AI Resources
-
-We have a couple of AI resources to help you with your daily work or exploring our ecosystem. 
-
-:::warning
-- Be aware that AI tooling can make mistakes.    
-- Documentation can be out of date or code can be work in progress.    
-- Always verify your coding agent's suggestions. 
-:::
-
-
-| Tool | Description |
-|---|---|
-| [**Deepwiki**](https://deepwiki.com/powerhouse-inc/powerhouse) | A searchable/queriable wiki to understand our growing Powerhouse **Monorepository** better. <br /> DeepWiki provides up-to-date documentation you can talk to, for every repo in the world. Think Deep Research for GitHub. |
-| [**Context7**](https://context7.com/powerhouse-inc/powerhouse) | The Powerhouse **Academy Documentation** is also available as context through the context7 MCP Server. <br /> LLMs rely on outdated or generic information about the libraries you use. <br /> Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. <br /> Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM. <br /> The official repository can be found [here](https://github.com/upstash/context7). |
-
-
-### Context7 Installation
-
-<details>
-<summary><b>Install in Cursor</b></summary>
-
-Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`
-
-Pasting the following configuration into your Cursor `~/.cursor/mcp.json` file is the recommended approach. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder.
-
-**Cursor Local Server Connection**
-
-```json
-{
-  "mcpServers": {
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Install in VS Code</b></summary>
-
-Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
-
-**VS Code Local Server Connection**
-
-```json
-"mcp": {
-  "servers": {
-    "context7": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@upstash/context7-mcp"]
-    }
-  }
-}
-```
-</details>
-
-For other editors, please refer to the [official documentation](https://github.com/upstash/context7#%-installation).
-
-### Context7 Troubleshooting
-
-<details>
-<summary><b>MCP, Documentation or Module Not Found Errors</b></summary>
-
-If you encounter `ERR_MODULE_NOT_FOUND`, try using `bunx` instead of `npx`:
-
-```json
-{
-  "mcpServers": {
-    "context7": {
-      "command": "bunx",
-      "args": ["-y", "@upstash/context7-mcp"]
-    }
-  }
-}
-```
-
-This often resolves module resolution issues in environments where `npx` doesn't properly install or resolve packages.
-
-</details>
-
-<details>
-<summary><b>ESM Resolution Issues</b></summary>
-
-For errors like `Error: Cannot find module 'uriTemplate.js'`, try the `--experimental-vm-modules` flag:
-
-```json
-{
-  "mcpServers": {
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>TLS/Certificate Issues</b></summary>
-
-Use the `--experimental-fetch` flag to bypass TLS-related problems:
-
-```json
-{
-  "mcpServers": {
-    "context7": {
-      "command": "npx",
-      "args": ["-y", "--node-options=--experimental-fetch", "@upstash/context7-mcp"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>General MCP Client Errors</b></summary>
-
-1. Try adding `@latest` to the package name
-2. Use `bunx` as an alternative to `npx`
-3. Consider using `deno` as another alternative
-4. Ensure you're using Node.js v18 or higher for native fetch support
-
-</details>
-

package/docs/academy/TUTORIAL_VERIFICATION_ARCHITECTURE

@@ -1,325 +0,0 @@
-# Tutorial Verification System - Technical Architecture
-
-## Overview
-
-This document outlines the technical architecture for an automated tutorial verification system that ensures the Powerhouse Academy tutorials remain accurate and functional as the codebase evolves.
-
-## System Architecture
-
-### 1. Test Execution Environment
-
-```
-┌─────────────────────────────────────────┐
-│  GitHub Actions Runner (Ubuntu)         │
-│  ┌─────────────────────────────────────┐ │
-│  │  Isolated Docker Container          │ │
-│  │  ├── Node.js 22                    │ │
-│  │  ├── pnpm                          │ │
-│  │  ├── Powerhouse CLI (ph-cli)       │ │
-│  │  ├── Playwright browsers           │ │
-│  │  └── Temporary filesystem          │ │
-│  └─────────────────────────────────────┘ │
-└─────────────────────────────────────────┘
-```
-
-**Execution Environments:**
-- **Development**: Local machine (`pnpm test:e2e`)
-- **CI/CD**: GitHub Actions runners (automatically on PRs)
-- **Scheduled**: Nightly runs to catch regressions
-
-### 2. Tutorial Agent Architecture
-
-The "agent" is a test orchestrator that processes tutorials through a structured workflow:
-
-```typescript
-// packages/tutorial-verifier/src/tutorial-agent.ts
-class TutorialAgent {
-  async verifyTutorial(tutorialPath: string) {
-    // 1. Parse tutorial markdown
-    const steps = await this.parseTutorialSteps(tutorialPath);
-    
-    // 2. Create isolated environment
-    const sandbox = await this.createSandbox();
-    
-    // 3. Execute each step sequentially
-    for (const step of steps) {
-      await this.executeStep(step, sandbox);
-      await this.verifyStepOutcome(step, sandbox);
-    }
-    
-    // 4. Generate report
-    return this.generateReport();
-  }
-}
-```
-
-## Component Integration
-
-### 3. E2E Test Framework Integration
-
-**Extends existing Playwright E2E infrastructure:**
-
-```typescript
-// test/connect-e2e/tests/tutorial-get-started.spec.ts
-import { test, expect } from '@playwright/test';
-
-test('Tutorial: Create new to-do list document', async ({ page }) => {
-  const agent = new TutorialAgent();
-  
-  // Phase 1: CLI Commands (no browser needed)
-  await agent.executeCliStep('ph init my-todo-project');
-  await agent.verifyFileExists('my-todo-project/package.json');
-  
-  // Phase 2: Browser Automation (uses Playwright)
-  await agent.startConnect(); // Starts ph connect in background
-  await page.goto('http://localhost:3000');
-  
-  // Phase 3: UI Verification (Playwright E2E)
-  await page.click('text=Local Drive');
-  await page.click('button:has-text("DocumentModel")');
-  await expect(page.locator('text=Document Model Editor')).toBeVisible();
-  
-  // Phase 4: Cleanup
-  await agent.cleanup();
-});
-```
-
-### 4. Playwright Browser Automation
-
-**UI automation for Connect Studio interactions:**
-
-```typescript
-// UI automation for Connect Studio
-class ConnectUIAgent {
-  constructor(private page: Page) {}
-  
-  async createDocumentModel(name: string) {
-    // Navigate to document creation
-    await this.page.click('button:has-text("DocumentModel")');
-    
-    // Fill in model details
-    await this.page.fill('input[placeholder="Document Name"]', name);
-    await this.page.fill('input[placeholder="Document Type"]', `powerhouse/${name.toLowerCase()}`);
-    
-    // Define schema in code editor
-    await this.page.click('.monaco-editor');
-    await this.page.keyboard.type(`
-      type ${name}State {
-        items: [TodoItem!]!
-      }
-    `);
-    
-    // Save and verify
-    await this.page.click('button:has-text("Save")');
-    await expect(this.page.locator(`text=${name}.phdm.zip`)).toBeVisible();
-  }
-}
-```
-
-## Execution Flow
-
-### 5. Tutorial Processing Pipeline
-
-```
-Tutorial Markdown File
-        ↓
-   [Tutorial Parser]
-        ↓
-   ┌─────────────────┐
-   │  Execution Steps │
-   ├─────────────────┤
-   │ 1. CLI Commands │ ← Uses child_process.spawn()
-   │ 2. File Checks  │ ← Uses fs.existsSync()
-   │ 3. UI Actions   │ ← Uses Playwright page.click()
-   │ 4. Verifications│ ← Custom assertion logic
-   └─────────────────┘
-        ↓
-   [Report Generator]
-        ↓
-   Test Results + Screenshots
-```
-
-### 6. Step-by-Step Processing Example
-
-**Tutorial Markdown:**
-```markdown
-## Quick start
-Create a new Powerhouse project with a single command:
-```bash
-ph init
-```
-
-Then start Connect:
-```bash
-ph connect
-```
-
-Navigate to http://localhost:3000 and click on "Local Drive".
-```
-
-**Agent Processing:**
-
-```typescript
-// 1. Tutorial Parser extracts executable steps
-const steps = [
-  { type: 'cli', command: 'ph init', expectedFiles: ['package.json'] },
-  { type: 'cli', command: 'ph connect', background: true },
-  { type: 'browser', action: 'navigate', url: 'http://localhost:3000' },
-  { type: 'browser', action: 'click', selector: 'text=Local Drive' }
-];
-
-// 2. Agent executes each step
-for (const step of steps) {
-  switch (step.type) {
-    case 'cli':
-      const result = execSync(step.command);
-      if (step.expectedFiles) {
-        for (const file of step.expectedFiles) {
-          assert(existsSync(file), `Expected file ${file} not found`);
-        }
-      }
-      break;
-      
-    case 'browser':
-      if (step.action === 'navigate') {
-        await page.goto(step.url);
-      } else if (step.action === 'click') {
-        await page.click(step.selector);
-      }
-      break;
-  }
-}
-```
-
-## Deployment Architecture
-
-### 7. Runtime Environment Distribution
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  GitHub Actions Runner                                  │
-│                                                         │
-│  ┌─────────────────┐  ┌─────────────────────────────────┐ │
-│  │ Tutorial Agent  │  │  Sandbox Environment           │ │
-│  │ (Node.js)       │  │                                 │ │
-│  │                 │  │  ┌─────────────┐               │ │
-│  │ • Parse MD      │  │  │ ph connect  │ :3000         │ │
-│  │ • Execute CLI   │  │  └─────────────┘               │ │
-│  │ • Control tests │  │                                 │ │
-│  └─────────────────┘  │  ┌─────────────┐               │ │
-│                       │  │ Playwright  │               │ │
-│  ┌─────────────────┐  │  │ Browser     │               │ │
-│  │ Report Gen      │  │  └─────────────┘               │ │
-│  │ • Screenshots   │  │                                 │ │
-│  │ • Error logs    │  │  /tmp/tutorial-test-xyz/        │ │
-│  │ • Success rates │  │  ├── my-todo-project/           │ │
-│  └─────────────────┘  │  │   ├── package.json          │ │
-│                       │  │   └── ...                   │ │
-│                       └─────────────────────────────────┘ │
-└─────────────────────────────────────────────────────────┘
-```
-
-### 8. Integration with Existing Test Suite
-
-**File Structure Extension:**
-
-```
-Your Current E2E Tests:
-test/connect-e2e/tests/
-├── todo-document.spec.ts     ← Existing
-├── drive.spec.ts            ← Existing
-└── app.spec.ts              ← Existing
-
-Added Tutorial Tests:
-test/connect-e2e/tests/tutorials/
-├── get-started.spec.ts      ← New: Tests "Get Started" tutorial
-├── mastery-track.spec.ts    ← New: Tests "Mastery Track" tutorials
-└── cookbook.spec.ts         ← New: Tests "Cookbook" recipes
-```
-
-**No changes to existing code** - just additional test files that run alongside current tests.
-
-## Performance & Timing
-
-### 9. Execution Timeline
-
-```
-0s    │ Start test
-2s    │ ├── Parse tutorial markdown
-4s    │ ├── Create temp directory
-6s    │ ├── Run 'ph init'
-15s   │ ├── Verify project structure  
-20s   │ ├── Start 'ph connect' (background)
-35s   │ ├── Wait for Connect to be ready
-40s   │ ├── Launch Playwright browser
-45s   │ ├── Navigate to localhost:3000
-50s   │ ├── Perform UI interactions
-55s   │ ├── Verify expected elements
-60s   │ ├── Take screenshots
-65s   │ ├── Cleanup (kill processes, delete files)
-70s   │ └── Generate report
-```
-
-## Implementation Phases
-
-### Phase 1: Proof of Concept (1-2 days)
-- Single tutorial verification (Get Started)
-- Basic CLI command execution
-- Simple file existence checks
-- Integration with existing Playwright setup
-
-### Phase 2: Core Features (1-2 weeks)
-- Tutorial markdown parser
-- Comprehensive step execution engine
-- Browser automation for Connect Studio
-- Error reporting and screenshots
-
-### Phase 3: Advanced Features (2-3 weeks)
-- Multiple tutorial support
-- Parallel execution
-- Detailed reporting dashboard
-- Integration with CI/CD pipeline
-
-### Phase 4: Intelligence Layer (2-3 weeks)
-- Failure pattern analysis
-- Automated suggestion generation
-- Historical trend tracking
-- LLM-powered issue diagnosis
-
-## Key Technical Decisions
-
-### Technology Stack
-- **Test Framework**: Playwright (existing)
-- **Runtime**: Node.js 22 + TypeScript
-- **CLI Execution**: child_process.spawn()
-- **File Operations**: Node.js fs module
-- **Browser Automation**: Playwright
-- **CI/CD**: GitHub Actions (existing)
-
-### Design Principles
-- **Isolation**: Each test runs in isolated environment
-- **Repeatability**: Tests can run multiple times with same results
-- **Extensibility**: Easy to add new tutorials
-- **Integration**: Builds on existing infrastructure
-- **Cleanup**: Automatic resource cleanup after tests
-
-## Success Metrics
-
-- **Tutorial Success Rate**: % of tutorials that pass verification
-- **Time to Detection**: How quickly outdated tutorials are identified
-- **False Positive Rate**: % of failures due to test issues vs actual problems
-- **Coverage**: Number of tutorial steps automatically verified
-- **Developer Confidence**: Reduced manual testing effort
-
-## Risk Mitigation
-
-### Technical Risks
-- **Flaky Tests**: Use retry mechanisms and wait strategies
-- **Environment Dependencies**: Containerized execution environments
-- **Resource Cleanup**: Comprehensive cleanup in finally blocks
-- **Process Management**: Proper process lifecycle management
-
-### Operational Risks
-- **Maintenance Overhead**: Gradual rollout with proven patterns
-- **CI/CD Load**: Efficient test execution and parallel processing
-- **Team Adoption**: Clear documentation and training materials