powervetra

name

powervetra

description

Build document models, editors, processors, subgraphs, and drive-apps for the Powerhouse/Vetra ecosystem. Use when Claude needs to (1) create or modify document models with GraphQL schemas and operations, (2) build React-based document editors with dispatch hooks, (3) work with Reactor-MCP tools for document and drive management, (4) implement pure synchronous reducers, (5) use the Powerhouse CLI (ph vetra, ph generate, ph connect), (6) design GraphQL state and input schemas with Powerhouse scalar types, (7) create subgraphs or processors, (8) deploy or publish Powerhouse packages, or any Powerhouse/Vetra development task. Triggers on mentions of: Powerhouse, Vetra, document model, reactor, MCP reactor, ph vetra, ph generate, switchboard, Connect Studio, drive, PHID, OID, document-engineering, reducer, dispatch, addActions.

PowerVetra

Comprehensive skill for building within the Powerhouse/Vetra ecosystem — document models, editors, processors, subgraphs, and drive-apps.

Core Concepts

• Document Model: Template defining schema and allowed operations for a document type (like a class)
• Document: Instance of a model containing actual data, modified via operations (like an object)
• Drive: Collection of documents and folders (type powerhouse/document-drive)
• Action: Proposed change (JSON with action name + input); dispatched via addActions
• Operation: Completed action with metadata (index, timestamp, hash)
• Reactor: Network node storing documents, resolving conflicts, verifying event histories
• Reactor-MCP: Bridge between AI agents and Powerhouse document management

Architecture: Documents use event sourcing — every change is stored as an operation, building a complete audit trail. Operations must be replayable to reconstruct state, which is why reducers must be pure and deterministic.

Example: A "Todo List" document model defines:

• State: { todos: [{ id, title, completed }] }
• Operations: ADD_TODO, TOGGLE_TODO, DELETE_TODO
• Reducer for ADD_TODO: reads action.input.id and action.input.title, pushes new todo onto state

Document Model Structure

A document model is composed of:

• Metadata: id, name, extension, description, author (name + website)
• Specifications: Versioned specs with version, changeLog, state (global/local with schema, initialValue, examples)
• Modules: Logical groupings of related operations (e.g., a "todo" module containing ADD_TODO, TOGGLE_TODO, DELETE_TODO)

MCP Tool Rules (MANDATORY)

The reactor-mcp must be used for all document/drive operations.

1. Never set document IDs manually — auto-generated by createDocument
2. Batch multiple actions in a single addActions call
3. Always call getDocumentModelSchema before addActions
4. Add document models/editors to vetra-{hash} drive
5. If MCP unavailable, ask user to run ph vetra in a separate terminal

See mcp-tools.md for full tool reference and GraphQL API.

Document Model Workflow

1. Plan

MANDATORY: Present proposed structure (state schema, modules, operations) to user. NEVER proceed with implementation without explicit user approval. When in doubt, ask for clarification. Break complex models into logical modules and operations.

2. Check Schema

getDocumentModelSchema({ type: "powerhouse/document-model" })

Review input requirements for operations. Include all required params (id, scope).

3. Implement via MCP

Use addActions to create modules, operations, state schema, reducers. Batch actions.

4. Implement Reducer Stubs

Generated files in document-models/<name>/src/reducers/<module-name>.ts contain placeholder stubs that throw "not implemented" errors:

export const todoTodoOperations: TodoTodoOperations = {
  addTodoOperation(state, action) {
    throw new Error("Reducer for 'addTodoOperation' not implemented.");
  },
};

You MUST replace these stubs with actual reducer logic. Reducer code also goes into SET_OPERATION_REDUCER action (no function header needed). External imports go at the beginning of the actual reducer file in src/.

5. Quality Assurance

npm run tsc && npm run lint:fix

See document-models.md for all 37 operations, reducer rules, error handling, and testing patterns.

Reducer Rules (Critical)

Reducers must be pure synchronous functions. Wrapped with Mutative (direct state mutation OK).

Forbidden: crypto.randomUUID(), Math.random(), Date.now(), new Date(), API calls, async

Required: All dynamic values from action.input:

// GOOD
const item = { id: action.input.id, createdAt: action.input.createdAt };

// BAD
const item = { id: crypto.randomUUID(), createdAt: new Date() };

Nullable handling: InputMaybe<T> → use || null or || [] for state assignment.

Errors: Reference by name (auto-imported). Names must be globally unique across operations.

throw new UpdateTodoNotFoundError("Not found");  // GOOD - auto-imported
throw new Error("Not found");                     // BAD - generic

See document-models.md for full reducer guidelines.

GraphQL Schema Design

State type naming (CRITICAL):

type TodoListState { ... }          # CORRECT (global)
type TodoListLocalState { ... }     # CORRECT (local)
type TodoListGlobalState { ... }    # WRONG - causes TS errors

Arrays must be mandatory: [ObjectType!]! with id: OID! on each object.

Available scalars: String, Int, Float, Boolean, OID, PHID, OLabel, Amount, Amount_Tokens, Amount_Money, Amount_Fiat, Amount_Currency, Amount_Crypto, Amount_Percentage, EthereumAddress, EmailAddress, Date, DateTime, URL, Currency

See graphql-schema.md for full schema rules and custom scalar creation.

Editor Creation

1. Check if the document editor already exists — if so, ask user whether to create a new one or reimplement the existing one
2. Create editor document (type powerhouse/document-editor) on vetra drive
3. Set name and document types
4. CRITICAL: Confirm with SET_EDITOR_STATUS status: "CONFIRMED" — code gen only runs for confirmed docs
5. Editor generated in editors/ folder — inspect hooks in editors/hooks/, read the document model schema to know how to interact with it
6. Use hooks pattern:

import { useSelectedTodoListDocument } from "../hooks/useTodoDocument.js";
import { addTodo } from "../../document-models/todo/gen/creators.js";

const [document, dispatch] = useSelectedTodoListDocument();
dispatch(addTodo({ id: generateId(), title: "New" }));

• Keep <DocumentToolbar /> unless user asks to remove
• Create modular components for UI elements on separate files; separate business logic from presentation
• Style with Tailwind or scoped style tags
• Centralize CSS imports in styles.css (not directly in .tsx)
• Use TypeScript for type safety — avoid any and type casting
• Consider using components from @powerhousedao/design-system and @powerhousedao/document-engineering
• Never edit files in gen/ folders

See editors.md for full editor patterns, drive-apps, and styling. See react-hooks.md for all available hooks from @powerhousedao/reactor-browser. See component-library.md for @powerhousedao/document-engineering components.

Document Confirmation Table

Document Type	Confirmation Action
powerhouse/document-editor	SET_EDITOR_STATUS with status: "CONFIRMED"
powerhouse/app	SET_APP_STATUS with status: "CONFIRMED"
powerhouse/processor	SET_PROCESSOR_STATUS with status: "CONFIRMED"
powerhouse/subgraph	SET_SUBGRAPH_STATUS with status: "CONFIRMED"

Two-Step Modification Rule

For ANY document model changes, always do BOTH:

1. Update via MCP (addActions with SET_OPERATION_SCHEMA, SET_OPERATION_REDUCER, etc.)
2. Manually update source files in src/ folder

Forgetting step 2 means future code generations still contain bugs.

Generated Files

Never edit files in gen/ folders — auto-generated, will be overwritten.

Drive Types

• Vetra Drive (vetra-{hash}): Source documents (models, editors) for development
• Preview Drive (preview-{hash}): Demo/test document instances

Always check drive schema before operations:

getDocumentModelSchema({ type: "powerhouse/document-drive" })

Drive operations: ADD_FILE, ADD_FOLDER, DELETE_NODE (not DELETE_FILE), UPDATE_NODE, MOVE_NODE

CLI Quick Reference

ph init <name>                    # New project
ph vetra --interactive --watch    # Recommended dev mode
ph generate --editor <name> --document-types <type>
ph generate --subgraph <name>
ph generate --drive-editor <name>
npm run tsc && npm run lint:fix   # Quality checks
pnpm build                        # Production build
npm publish --access public       # Publish package

See cli-reference.md for full CLI documentation.

Additional References

• subgraphs-processors.md — Subgraph schema/resolvers, processors, relational DB hooks
• deployment.md — Publishing packages, server setup, Docker, version history
• glossary.md — Ecosystem terminology