@powerhousedao/academy 2.5.0-dev.2 → 2.5.0-dev.21

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

@@ -1,8 +1,8 @@
 # Document-Engineering
 
-The reusable components in the Document-Engineering design system are a set of of front-end components based on graphQL scalars. 
+The reusable components in the Document-Engineering system are a set of of front-end components based on graphQL scalars. 
 Powerhouse also has a set of custom scalars that are not part of the graphQL standard but are specific to the web3 ecosystem.
-These components are offered through the **Powerhouse Document-Engineering design system** with the help of storybook & the Academy documentation. 
+These components are offered through the **Powerhouse Document-Engineering system** with the help of storybook & the Academy documentation. 
 
 It provides a collection of pre-built, reusable UI components designed for consistency and efficiency across Powerhouse applications and editors. Think of it as a toolkit of standard UI elements like buttons, inputs, and checkboxes with many of these components based on graphql scalars. 
 
@@ -19,29 +19,19 @@ In the next few chapters of our documentation, we will start with the simplest s
 
 ## **3 types of components**
 
-1. **Simple Component** has a scalar value as input 
+1. **Scalar Component** has a simple scalar value as input 
     - Component, Composition of smaller UI controls (e.g. Scalar component)
-    
 2. **Complex Component** has an object/array value 
     - Group of components (e.g. sidebar tree view)
-    
 3. **Layout Component** will contain other components 
     - Containers for other components, Sections (e.g. list of other components, color layouts, etc.)
+4. **fragments Component** 
 
-The documentation of each of the reusable components in the Academy documentation will be structured as follows:
-
-1. **Component Context**
-2. **Scalar Definition**
-3. **Component Storybook Base Example**
-    - Component Code
-    - Component Default Props
-4. **Component Storybook Usage Examples**
+For each of these components an implementation example will be given in our documentation. 
 
 ## Exploring Components with Storybook
 
-We use Storybook as an interactive catalog for our design system components. It allows you to visually explore each component, interact with different states, and understand how to integrate them into your projects.
-
-[https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
+We use Storybook as an interactive catalog for our design system components. It allows you to visually explore each component, interact with different states, and understand how to integrate them into your projects. [https://storybook.powerhouse.academy](https://storybook.powerhouse.academy)
 
 **Understanding the Storybook Interface:**
 
@@ -54,8 +44,8 @@ We use Storybook as an interactive catalog for our design system components. It
 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/GetStarted/BuildToDoListEditor).
 
 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.
-2.  **Consult the Resuable Components in Academy or in Storybook:**
-    *   Open the Powerhouse Storybook instance.
+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.
     *   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.).
@@ -85,10 +75,66 @@ Let's walk through the typical workflow for using a component from the document-
     You configure the component's appearance and behavior by passing the appropriate values to its props.
 5.  **Test and Refine:** Run your application (e.g., using `ph connect`) to see the component in context. Verify its appearance and functionality.
 
-**Storybook vs. Source Code:**
+## Usage
+
+The Document Engineering package provides several entry points for different use cases in your powerhouse project:
+
+### Main Package
+
+```typescript
+import { ... } from '@powerhousedao/document-engineering';
+```
+
+### UI Components
+
+```typescript
+import { ... } from '@powerhousedao/document-engineering/ui';
+```
+
+### Scalars
+
+For data manipulation and transformation utilities:
+
+```typescript
+import { ... } from '@powerhousedao/document-engineering/scalars';
+```
+
+### GraphQL
+
+For GraphQL related utilities and schema definitions:
+
+```typescript
+import { ... } from '@powerhousedao/document-engineering/graphql';
+```
+
+### Styles
+
+To include the package's styles:
+
+```typescript
+import '@powerhousedao/document-engineering/style.css';
+```
+
+## Import Maps
+
+Within the project, the following import maps are available:
+
+- `#assets` - Assets utilities and components
+- `#scalars` - Scalar transformations and utilities
+- `#ui` - UI components 
+- `#graphql` - GraphQL related utilities
+
+
+## **Storybook vs. Source Code:**
 
 Storybook serves as essential documentation and a usage guide. Our developers write Storybook "stories" to demonstrate components and document their common props. However, the **ultimate source of truth** for a component's capabilities is its actual source code (e.g., the `.tsx` file within the `@powerhousedao/document-engineering/scalars` package).
 While Storybook aims for accuracy, there might occasionally be discrepancies or undocumented props.
 
-Please don't hesitate to reach out in our discord channels with any questions. 
-Happy designing! 
+Please don't hesitate to reach out in our discord channels with any questions.    
+Happy designing! 
+
+### Up next: Create Custom Scalars
+
+You can learn how to do so in our guide on [Creating Custom Scalars](/academy/ComponentLibrary/CreateCustomScalars).
+
+

package/docs/academy/06-ComponentLibrary/02-CreateCustomScalars.md

@@ -0,0 +1,403 @@
+# Step 1: Create Custom Scalars
+
+This tutorial provides step-by-step instructions for creating custom scalars & components, and to contributing to the document-engineering project.
+The github repo for the Document-Engineering can be found [here](https://github.com/powerhouse-inc/document-engineering/tree/main)
+
+:::info
+When contributing as an open source developer please submit a pull request to the Powerhouse team. 
+Although a design or UI for your scalar is not mandatory, it definitely helps reviewers if there's a visual reference. 
+That said, not all scalars require a dedicated UI component. 
+Some scalars, like scalar Title or scalar Description, might both map to a string and use the same UI, in this case scalars plays more semantic role than a type definition.
+:::
+
+## Table of Contents
+
+- [Creating New GraphQL Scalars](#creating-new-graphql-scalars)
+  - [Step 1: Create the Scalar File](#step-1-create-the-scalar-file)
+    - [Key Components to Update](#key-components-to-update)
+  - [Step 2: Register the Scalar in scalars.ts](#step-2-register-the-scalar-in-scalarts)
+    - [2.1 Add Namespace Import](#21-add-namespace-import)
+    - [2.2 Add Type Export](#22-add-type-export)
+    - [2.3 Add to Export Object](#23-add-to-export-object)
+    - [2.4 Add to Custom Scalars](#24-add-to-custom-scalars)
+    - [2.5 Add to Resolvers](#25-add-to-resolvers)
+    - [2.6 Add to Type Definitions](#26-add-to-type-definitions)
+    - [2.7 Add to Generator Type Definitions](#27-add-to-generator-type-definitions)
+    - [2.8 Add to Validation Schema](#28-add-to-validation-schema)
+  - [Step 3: Create Tests for Your Scalar](#step-3-create-tests-for-your-scalar)
+    - [Required Test Cases](#required-test-cases)
+    - [Testing Best Practices](#testing-best-practices)
+    - [Example Edge Cases for Different Scalar Types](#example-edge-cases-for-different-scalar-types)
+  - [Step 4: Validate Your Implementation](#step-4-validate-your-implementation)
+  - [Common Scalar Types](#common-scalar-types)
+  - [Tips](#tips)
+
+## Creating New GraphQL Scalars
+
+GraphQL scalars are custom data types that define how data is validated, serialized, and parsed. This guide will walk you through creating a new scalar in the `src/scalars/graphql/` directory.
+
+### Step 1: Create the Scalar File
+
+Create a new TypeScript file in `src/scalars/graphql/` for your scalar. Use `EmailAddress.ts` as a reference.
+
+**Example: Creating a `PhoneNumber.ts` scalar**
+
+```typescript
+import { GraphQLError, GraphQLScalarType, type GraphQLScalarTypeConfig, Kind } from 'graphql'
+import { z } from 'zod'
+
+export interface ScalarType {
+  input: string
+  output: string
+}
+
+export const type = 'string' // TS type in string form
+
+export const typedef = 'scalar PhoneNumber'
+
+export const schema = z.string().regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number format')
+
+export const stringSchema = 'z.string().regex(/^\\+?[1-9]\\d{1,14}$/, "Invalid phone number format")'
+
+const phoneValidation = (value: unknown): string => {
+  if (typeof value !== 'string') {
+    throw new GraphQLError(`Value is not string: ${JSON.stringify(value)}`)
+  }
+
+  const result = schema.safeParse(value)
+
+  if (result.success) return result.data
+  throw new GraphQLError(result.error.message)
+}
+
+export const config: GraphQLScalarTypeConfig<string, string> = {
+  name: 'PhoneNumber',
+  description: 'A field whose value conforms to international phone number format.',
+  serialize: phoneValidation,
+  parseValue: phoneValidation,
+  parseLiteral: (value) => {
+    if (value.kind !== Kind.STRING) {
+      throw new GraphQLError(`Can only validate strings as phone numbers but got a: ${value.kind}`, { nodes: value })
+    }
+
+    return phoneValidation(value.value)
+  },
+}
+
+export const scalar = new GraphQLScalarType(config)
+```
+
+#### Key Components to Update:
+
+1. **`type`**: The TypeScript type (usually `'string'` for text-based scalars)
+2. **`typedef`**: The GraphQL type definition (e.g., `'scalar PhoneNumber'`)
+3. **`schema`**: Zod validation schema for your data type
+4. **`stringSchema`**: String representation of the zod schema (used for code generation)
+5. **Validation function**: Custom validation logic for your scalar
+6. **`config.name`**: The name of your scalar (must match the typedef)
+7. **`config.description`**: Human-readable description of the scalar
+
+### Step 2: Register the Scalar in `scalars.ts`
+
+After creating your scalar file, you need to register it in `src/scalars/graphql/scalars.ts`. This involves updating multiple sections of the file.
+The github repo for the Document-Engineering can be found [here](https://github.com/powerhouse-inc/document-engineering/tree/main)
+
+#### 2.1 Add Namespace Import
+
+Add your scalar to the namespace imports section (around line 2):
+
+```typescript
+// namespace imports -- DO NOT REMOVE OR EDIT THIS COMMENT
+import * as Amount from './Amount.js'
+import * as AmountCrypto from './AmountCrypto.js'
+// ... other imports ...
+import * as PhoneNumber from './PhoneNumber.js' // ADD THIS LINE
+import * as URLScalar from './URL.js'
+```
+
+#### 2.2 Add Type Export
+
+Add the type export (around line 22):
+
+```typescript
+// export types -- DO NOT REMOVE OR EDIT THIS COMMENT
+export type { ScalarType as AmountScalarType } from './Amount.js'
+// ... other type exports ...
+export type { ScalarType as PhoneNumberScalarType } from './PhoneNumber.js' // ADD THIS LINE
+export type { ScalarType as URLScalarType } from './URL.js'
+```
+
+#### 2.3 Add to Export Object
+
+Add your scalar to the main export object (around line 40):
+
+```typescript
+export {
+  Amount,
+  AmountCrypto,
+  // ... other exports ...
+  PhoneNumber, // ADD THIS LINE
+  URLScalar,
+}
+```
+
+#### 2.4 Add to Custom Scalars
+
+Add your scalar to the `customScalars` object (around line 54):
+
+```typescript
+export const customScalars: Record<string, BasePHScalar<any>> = {
+  // ... other scalars ...
+  PhoneNumber, // ADD THIS LINE
+  URLScalar,
+} as const
+```
+
+#### 2.5 Add to Resolvers
+
+Add your scalar to the `resolvers` object (around line 74):
+
+```typescript
+export const resolvers = {
+  // export resolvers -- DO NOT REMOVE OR EDIT THIS COMMENT
+  AmountTokens: AmountTokens.scalar,
+  // ... other resolvers ...
+  PhoneNumber: PhoneNumber.scalar, // ADD THIS LINE
+  Amount: Amount.scalar,
+}
+```
+
+#### 2.6 Add to Type Definitions
+
+Add your typedef to the `typeDefs` array (around line 90):
+
+```typescript
+export const typeDefs = [
+  // export typedefs -- DO NOT REMOVE OR EDIT THIS COMMENT
+  AmountTokens.typedef,
+  // ... other typedefs ...
+  PhoneNumber.typedef, // ADD THIS LINE
+  Amount.typedef,
+]
+```
+
+#### 2.7 Add to Generator Type Definitions
+
+Add your scalar to the `generatorTypeDefs` object (around line 105):
+
+```typescript
+export const generatorTypeDefs = {
+  // export generator typedefs -- DO NOT REMOVE OR EDIT THIS COMMENT
+  [AmountTokens.config.name]: AmountTokens.type,
+  // ... other entries ...
+  [PhoneNumber.config.name]: PhoneNumber.type, // ADD THIS LINE
+  [Amount.config.name]: Amount.type,
+}
+```
+
+#### 2.8 Add to Validation Schema
+
+Add your scalar to the `validationSchema` object (around line 120):
+
+```typescript
+export const validationSchema = {
+  // export validation schema -- DO NOT REMOVE OR EDIT THIS COMMENT
+  [AmountTokens.config.name]: AmountTokens.stringSchema,
+  // ... other entries ...
+  [PhoneNumber.config.name]: PhoneNumber.stringSchema, // ADD THIS LINE
+  [Amount.config.name]: Amount.stringSchema,
+}
+```
+
+### Step 3: Create Tests for Your Scalar
+
+Every scalar must have comprehensive tests to ensure it works correctly. Create a test file in `src/scalars/graphql/test/` following the naming convention `YourScalar.test.ts`.
+
+**Example: Creating `PhoneNumber.test.ts`**
+
+```typescript
+import { Kind } from 'graphql'
+import { scalar } from '../PhoneNumber.js'
+
+describe('PhoneNumber Scalar', () => {
+  it('should serialize a phone number', () => {
+    const phoneNumber = '+1234567890'
+
+    expect(scalar.serialize(phoneNumber)).toBe(phoneNumber)
+  })
+
+  it('should throw an error if the value is not a string', () => {
+    const phoneNumber = 123
+
+    expect(() => scalar.serialize(phoneNumber)).toThrow()
+  })
+
+  it('should throw an error if the value is not a valid phone number', () => {
+    const phoneNumber = 'invalid-phone'
+
+    expect(() => scalar.serialize(phoneNumber)).toThrow()
+  })
+
+  it('should parse a valid phone number', () => {
+    const phoneNumber = '+1234567890'
+
+    expect(scalar.parseValue(phoneNumber)).toBe(phoneNumber)
+  })
+
+  it('should throw an error if parse a value that is not a valid phone number', () => {
+    const phoneNumber = 'invalid-phone'
+
+    expect(() => scalar.parseValue(phoneNumber)).toThrow()
+  })
+
+  it('should throw an error if parse a value that is not a string', () => {
+    const phoneNumber = 123
+
+    expect(() => scalar.parseValue(phoneNumber)).toThrow()
+  })
+
+  it('should parse a valid phone number from a literal', () => {
+    const phoneNumber = '+1234567890'
+
+    expect(
+      scalar.parseLiteral({
+        kind: Kind.STRING,
+        value: phoneNumber,
+      })
+    ).toBe(phoneNumber)
+  })
+
+  it('should throw an error if parse a literal that is not a valid phone number', () => {
+    const phoneNumber = 'invalid-phone'
+
+    expect(() =>
+      scalar.parseLiteral({
+        kind: Kind.STRING,
+        value: phoneNumber,
+      })
+    ).toThrow()
+  })
+
+  it('should throw an error if parse a literal that is not a string', () => {
+    const phoneNumber = '+1234567890'
+
+    expect(() =>
+      scalar.parseLiteral({
+        kind: Kind.INT,
+        value: phoneNumber,
+      })
+    ).toThrow()
+  })
+})
+```
+
+#### Required Test Cases
+
+Your scalar tests should cover these essential scenarios:
+
+##### Serialization Tests
+
+- ✅ **Valid values**: Test that valid inputs are serialized correctly
+- ❌ **Invalid types**: Test that non-string inputs throw errors
+- ❌ **Invalid format**: Test that strings not matching your validation throw errors
+
+##### Parse Value Tests
+
+- ✅ **Valid values**: Test that valid inputs are parsed correctly
+- ❌ **Invalid format**: Test that invalid strings throw errors
+- ❌ **Invalid types**: Test that non-string inputs throw errors
+
+##### Parse Literal Tests
+
+- ✅ **Valid STRING literals**: Test that valid string literals are parsed correctly
+- ❌ **Invalid STRING literals**: Test that invalid string literals throw errors
+- ❌ **Non-STRING literals**: Test that non-string literal kinds (INT, FLOAT, etc.) throw errors
+
+#### Testing Best Practices
+
+1. **Test edge cases**: Include boundary values and common invalid inputs
+2. **Test multiple valid formats**: If your scalar accepts different valid formats, test them all
+3. **Use descriptive test names**: Make it clear what each test is validating
+4. **Follow the naming convention**: `YourScalar.test.ts` in the `test/` directory
+
+#### Example Edge Cases for Different Scalar Types
+
+**String-based scalars (like PhoneNumber):**
+
+```typescript
+// Test empty string
+expect(() => scalar.parseValue('')).toThrow()
+
+// Test too long/short values
+expect(() => scalar.parseValue('123')).toThrow()
+expect(() => scalar.parseValue('+' + '1'.repeat(20))).toThrow()
+
+// Test special characters
+expect(() => scalar.parseValue('+1-234-567-890')).not.toThrow()
+```
+
+**Number-based scalars:**
+
+```typescript
+// Test zero
+expect(scalar.parseValue(0)).toBe(0)
+
+// Test negative numbers
+expect(() => scalar.parseValue(-1)).toThrow()
+
+// Test decimal numbers
+expect(scalar.parseValue(123.45)).toBe(123.45)
+```
+
+**Date-based scalars:**
+
+```typescript
+// Test valid ISO date
+expect(scalar.parseValue('2023-12-25T00:00:00Z')).toBe('2023-12-25T00:00:00Z')
+
+// Test invalid date format
+expect(() => scalar.parseValue('25/12/2023')).toThrow()
+```
+
+### Step 4: Validate Your Implementation
+
+After implementing your scalar and tests, make sure to:
+
+1. **Run the tests** to ensure they all pass
+2. **Build the project** to ensure there are no TypeScript errors
+3. **Test GraphQL queries** that use your new scalar
+4. **Verify code generation** works with your new scalar
+
+### Common Scalar Types
+
+Here are some common patterns for different types of scalars:
+
+#### String-based Scalars
+
+```typescript
+export const type = 'string'
+export const schema = z.string().min(1).max(100)
+```
+
+#### Number-based Scalars
+
+```typescript
+export const type = 'number'
+export const schema = z.number().positive()
+```
+
+#### Date-based Scalars
+
+```typescript
+export const type = 'string'
+export const schema = z.string().datetime()
+```
+
+### Tips
+
+- Always follow the naming convention: use PascalCase for scalar names
+- Include meaningful validation in your Zod schema
+- Write clear, descriptive error messages
+- Keep the `stringSchema` in sync with your `schema` definition
+- Test edge cases in your validation function
+- Update all required sections in `scalars.ts`

package/docs/academy/06-ComponentLibrary/{02-BuildingWithScalars.md → 02-ScalarComponent.mdx}

@@ -1,4 +1,6 @@
-# Build with Scalars
+import { Tabs, TabItem } from '@theme/Tabs';
+
+# Scalar Component Example
 
 Scalars are here to help you define custom fields in your document model schema and speed up the development process.
 There are two applications of scalar components in the document model workflow:
@@ -10,20 +12,13 @@ There are two applications of scalar components in the document model workflow:
 
 As you might know, the document model schema defines the structure of the document and serves as the backbone of the document model. The GraphQL state schema defines how data is captured with the help of types & scalars. When you define a scalar in the document model schema, you are essentially defining a new field that can be used in the document model to capture data.
 
-In the Document Model Editor, you can find all the custom scalar types available in our documentation under the 'Scalars' section.
-
-Insert image of the feature. 
+In the Document Model Editor, you can find all the custom scalar types available under the 'Scalars' section.
 
-````
-scalar PHID <-- imported from the design system library? not sure
-type MyType {
-  myScalar: PHID
-}   
-````
+Insert image of the feature. @callme-t
 
 ## React Component Implementation in the Frontend
 
-All of our reusable components are available in the Document-Engineering design system library or package.
+All of our reusable components are available in the Document-Engineering system package.
 This package comes as a dependency in your project when creating a new document model project.
 ````
 import PHIDField from 'document-engineering'
@@ -51,4 +46,7 @@ return (
 To make your life easier, Powerhouse has defined all useful scalars with a set of reusable code and UI components.
 The reusable components are essentially a set of front-end components based on GraphQL scalars. Powerhouse also has a set of custom scalars that are not part of the GraphQL standard but are specific to the web3 ecosystem.
 
-Read the next chapter to get familiar with our reusable components. 
+Read the next chapter to get familiar with our reusable components. 
+
+# PHID Field Implementation Example
+

package/docs/academy/06-ComponentLibrary/{04-Complex-Components/01-sidebar.mdx → 03-ComplexComponent.mdx}

@@ -1,6 +1,8 @@
 import { Tabs, TabItem } from '@theme/Tabs';
 
-# Sidebar
+# Complex Component Example
+
+## Sidebar
 
 ### **Scalar Definition**
 

package/docs/academy/06-ComponentLibrary/03-IntegrateIntoAReactComponent.md

@@ -0,0 +1 @@
+# Integrate your Scalar into a React Component

package/docs/academy/06-ComponentLibrary/04-LayoutComponent.mdx

@@ -0,0 +1,5 @@
+import { Tabs, TabItem } from '@theme/Tabs';
+
+# Layout Component Example
+
+## PHID Field Example

package/docs/academy/06-ComponentLibrary/05-FragmentsComponent.mdx

@@ -0,0 +1,5 @@
+import { Tabs, TabItem } from '@theme/Tabs';
+
+# Fragment Component Example 
+
+## PHID Field Example

package/docs/academy/07-Cookbook.md

@@ -404,7 +404,6 @@ In the "New Document" section at the bottom of the page, click the `DocumentMode
 - Implementing Document Model Reducers (Details to be added)
 
 ## Further Reading
-- [Domain Modeling Guide](/domain-modeling)
 - [GraphQL Schema Best Practices](/academy/MasteryTrack/WorkWithData/GraphQLAtPowerhouse)
 </details>
 
@@ -451,9 +450,6 @@ The command will output the generated reducer scaffolding code in the designated
 - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model)
 - Generating a Document Editor
 
-## Further Reading
-- [Domain Modeling Guide](/domain-modeling)
-
 </details>
 
 <details id="updating-your-powerhouse-project-dependencies">

package/docs/academy/08-Glossary.md

@@ -17,7 +17,7 @@
 - **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.
-- **ph-cmd (Powerhouse CLI)** – The command-line tool for Powerhouse project initialization, code generation, package management, and running local development environments (Connect Studio).
+- **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.
 - **Operations History** – A Document Tool in Connect providing a chronological, immutable log of all operations on a document for traceability.
@@ -30,7 +30,9 @@
 - **Actions (Document Actions)** – Typed objects representing an intent to change a document's state, dispatched to reducers, containing an operation type and input data.
 - **API Integration (for Document Models)** – The capability of Document Models to connect with Switchboard API or external APIs, facilitating data exchange between Powerhouse applications and other systems.
 - **Boilerplate (Powerhouse Project)** – The `ph init` command's initial project structure, providing a standard starting point for new Powerhouse packages.
+- **Connect Build** – The output of the `ph connect build` command, which packages a Connect project into a distributable format. This build includes all necessary local/external packages, assets, and styles, and can be previewed locally with `ph connect preview` or deployed.
 - **Data Analysis (with Document Models)** – Leveraging the structured data within Document Models, often via read models, to extract insights, generate reports, and perform analytics on operational and historical data.
+- **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.
 - **Dispatch (in Document Models)** – The act of sending an action (representing an operation) to a document model's reducer to trigger a state update.
 - **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.
 - **Document Model Specification** – The formal definition of a document model (state, operations), created in Connect Studio (using GraphQL SDL) and exported (e.g., `.phdm.zip`) for code generation.
@@ -39,6 +41,7 @@
 - **Document Type** – A unique string identifier (e.g., `powerhouse/todolist`) for a Document Model, used by host apps to select the correct editor/logic.
 - **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.
+- **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).
 - **Event History (Append-Only Log)** – An immutable, append-only log where every operation applied to a Powerhouse document is stored as an event. It provides a transparent audit trail and enables features like time travel debugging and state reconstruction.
 - **GraphQL Scalars** – Data types used in Powerhouse document modeling (e.g., `String`, `Int`, `Currency`, `OID` for unique object IDs).
 - **GraphQL Schema Definition Language (SDL) (for Document Models)** – Language used in Connect Studio to define a Document Model's data structure (state) and operations.

package/docs/academy/09-AIResources

@@ -0,0 +1,23 @@
+# AI Resources
+
+We have a couple of AI resources to help you with your daily work.
+
+## Deepwiki
+A searchable/queriable wiki to understand our growing mono repo better.
+https://deepwiki.com/powerhouse-inc/powerhouse
+
+:::info
+What is DeepWiki?
+DeepWiki provides up-to-date documentation you can talk to, for every repo in the world. Think Deep Research for GitHub.
+:::
+
+## Context7
+The Powerhouse Academy is also available as context through the context7 MCP Server. 
+https://context7.com/powerhouse-inc/powerhouse
+
+:::info
+What is Context7?
+LLMs rely on outdated or generic information about the libraries you use.
+
+Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM. Get better answers, no hallucinations and an AI that actually understands your stack.
+:::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "2.5.0-dev.2",
+  "version": "2.5.0-dev.21",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",