@powerhousedao/academy 0.1.0-dev.3 → 0.1.0-dev.5

package/docs/academy/04-APIReferences/01-ReactHooks.md

@@ -0,0 +1,16 @@
+# React Hooks (WIP)
+
+### Hook Name and Signature   
+The name of the hook and its TypeScript (or JavaScript) signature.
+### Description
+A brief explanation of what the hook does and when to use it.
+### Usage Example   
+A code snippet showing how to use the hook in a real-world scenario.
+### Parameters
+A table or list describing each parameter, its type, and its purpose.
+### Return Value   
+A description (and sometimes a table) of what the hook returns.
+### Notes / Caveats   
+Any important details, gotchas, or best practices.
+### Related Hooks
+Links to other relevant hooks or documentation.

package/docs/academy/04-APIReferences/02-ReactorAPI.md

@@ -0,0 +1 @@
+# Reactor API (WIP)

package/docs/academy/04-APIReferences/03-Configuration.md

@@ -0,0 +1,64 @@
+# Configuration (WIP)
+
+This section describes the configuration options and feature flags available in the application. These settings allow you to customize the behavior of the app for your environment.
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [How to Configure](#how-to-configure)
+3. [Configuration Options](#configuration-options)
+4. [Feature Flags](#feature-flags)
+5. [Best Practices](#best-practices)
+
+---
+
+## Introduction
+
+Configuration options and feature flags allow administrators and developers to enable, disable, or customize features in the application. They can be set via environment variables, configuration files, or the admin dashboard.
+
+## How to Configure
+
+- **Environment Variables:** Set in your `.env` file or deployment environment.
+- **Config File:** Edit `config.json` in the root directory.
+- **Admin UI:** Navigate to Settings > Advanced.
+
+Changes may require a server restart to take effect.
+
+## Configuration Options
+
+| Name                | Description                        | Default | Possible Values      | Example                |
+|---------------------|------------------------------------|---------|---------------------|------------------------|
+| `APP_PORT`          | Port the server listens on          | `3000`  | Any valid port      | `APP_PORT=8080`        |
+| `LOG_LEVEL`         | Logging verbosity                   | `info`  | `debug`, `info`, `warn`, `error` | `LOG_LEVEL=debug`      |
+| `ENABLE_SIGNUP`     | Allow new user registrations        | `true`  | `true`, `false`     | `ENABLE_SIGNUP=false`  |
+
+## Feature Flags
+
+| Flag Name           | Description                        | Default | Example             |
+|---------------------|------------------------------------|---------|---------------------|
+| `FEATURE_BETA_UI`   | Enable the new beta user interface | `false` | `FEATURE_BETA_UI=true` |
+| `FEATURE_XYZ`       | Enable experimental XYZ feature    | `false` | `FEATURE_XYZ=true`  |
+
+## Best Practices
+
+- Only enable experimental features in staging environments.
+- Document any changes to configuration for your team.
+- Review security implications before enabling/disabling features.
+
+---
+
+###Introduction
+What are configuration options/toggles/flags?
+How are they set (e.g., environment variables, config files, admin UI)?
+###List of Options
+Name
+Description
+Default value
+Possible values
+Example usage
+(Optional) Who should use it (admin, developer, etc.)
+###How to Change
+Where/how to set them (UI, .env, config file, etc.)
+When changes take effect (immediately, after restart, etc.)
+###Best Practices / Warnings
+Security, performance, or stability notes

package/docs/academy/{04-ComponentLibrary/01-PowerhouseDesignSystem.md → 06-ComponentLibrary/00-DocumentEngineering.md}

@@ -1,8 +1,8 @@
-# Document-Engineering System
+# Document-Engineering
 
-The reusable components are a set of of front-end components based on graphQL scalars. 
+The reusable components in the Document-Engineering design 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 system** with the help of storybook & the Academy documentation. 
+These components are offered through the **Powerhouse Document-Engineering design 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. 
 
@@ -51,7 +51,7 @@ We use Storybook as an interactive catalog for our design system components. It
 
 ## Implementing a Component
 
-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](/docs/academy/GetStarted/ToDoList/BuildToDoListEditor).
+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:**
@@ -61,11 +61,11 @@ Let's walk through the typical workflow for using a component from the document-
     *   Examine the "Usage" snippet and the **Props table** to understand the basic implementation and available configuration options (`label`, `value`, `onChange`, etc.).
 3.  **Import the Component:** In your code editor, open the relevant file (e.g., `editors/to-do-list/editor.tsx`). Add an import statement at the top to bring the component into your file's scope:
     ```typescript
-    import { Checkbox } from '@powerhousedao/design-system/scalars';
+    import { Checkbox } from '@powerhousedao/document-engineering/scalars';
     // Or import other components as needed:
-    // import { Checkbox, InputField, Button } from '@powerhousedao/design-system/scalars';
+    // import { Checkbox, InputField, Button } from '@powerhousedao/document-engineering/scalars';
     ```
-    This line instructs the build process to locate the `Checkbox` component within the installed `@powerhousedao/design-system/scalars` package and make it available for use.
+    This line instructs the build process to locate the `Checkbox` component within the installed `@powerhousedao/document-engineering/scalars` package and make it available for use.
 4.  **Use and Configure the Component:** Place the component tag in your JSX where needed. Use the information from Storybook (usage snippet and props table) as a guide, but adapt the props to your specific requirements within `editor.tsx`:
     ```typescript
     // Example from the To-do List Editor:
@@ -87,7 +87,7 @@ Let's walk through the typical workflow for using a component from the document-
 
 **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/design-system/scalars` package).
+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. 

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

@@ -23,10 +23,10 @@ type MyType {
 
 ## React Component Implementation in the Frontend
 
-All of our reusable components are available in the design system library or package.
+All of our reusable components are available in the Document-Engineering design system library or package.
 This package comes as a dependency in your project when creating a new document model project.
 ````
-import PHIDField from 'design-system'
+import PHIDField from 'document-engineering'
 const reactComponent = () => {
 
 return (

package/docs/academy/{04-ComponentLibrary → 06-ComponentLibrary}/03-Scalar-Components/01-phid-field.mdx

@@ -61,7 +61,7 @@ Additionally, you'll find various **stories of the components in different state
   marginBottom: '20px',
 }}>
   <iframe
-    src="https://storybook.powerhouse.academy/iframe.html?id=document-engineering-scalars-phid-field&viewMode=story"
+    src="https://storybook.powerhouse.academy/iframe.html?id=scalars-phid-field--readme&viewMode=story"
     style={{
       width: '100%',
       height: '4500px',

package/docs/academy/{06-Cookbook.md → 07-Cookbook.md}

@@ -1,6 +1,7 @@
 # Cookbook
 
 ## Powerhouse CLI Recipes
+This section covers recipes related to the `ph-cmd`, the command-line tool for Powerhouse project initialization, code generation, package management, and running local development environments.
 
 <details id="installing-ph-cmd">
 <summary>Installing 'ph-cmd'</summary>
@@ -53,7 +54,7 @@ pnpm install -g ph-cmd@<version>
 - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration)
 
 ## Further Reading
-- [Powerhouse Builder Tools](/docs/academy/AdvancedTutorial/Create/BuilderTools)
+- [Powerhouse Builder Tools](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
 </details>
 
 <details id="uninstalling-ph-cmd">
@@ -94,8 +95,8 @@ rm -rf ~/.ph
 - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration)
 
 ## Further Reading
-- [Powerhouse Builder Tools](/docs/academy/AdvancedTutorial/Create/BuilderTools)
-- [Create A New Powerhouse Project](/docs/academy/GetStarted/ToDoList/CreateNewPowerhouseProject)
+- [Powerhouse Builder Tools](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
+- [Create A New Powerhouse Project](/academy/GetStarted/CreateNewPowerhouseProject)
 </details>
 
 <details id="setting-up-or-resetting-the-global-powerhouse-configuration">
@@ -153,8 +154,8 @@ ph use staging
 - [Using Different Branches in Powerhouse](#using-different-branches-in-powerhouse)
 
 ## Further Reading
-- [Powerhouse Builder Tools](/docs/academy/AdvancedTutorial/Create/BuilderTools)
-- [GraphQL Schema Best Practices](/docs/academy/AdvancedTutorial/WorkWithData/GraphQLAtPowerhouse)
+- [Powerhouse Builder Tools](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
+- [GraphQL Schema Best Practices](/academy/MasteryTrack/WorkWithData/GraphQLAtPowerhouse)
 </details>
 
 <details id="using-different-branches-in-powerhouse">
@@ -232,7 +233,7 @@ ph use prod
 - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration)
 
 ## Further Reading
-- [Powerhouse Builder Tools](/docs/academy/AdvancedTutorial/Create/BuilderTools)
+- [Powerhouse Builder Tools](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
 </details>
 
 <details id="using-different-package-managers-with-powerhouse">
@@ -331,12 +332,13 @@ ph init --package-manager pnpm
 - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration)
 
 ## Further Reading
-- [Powerhouse Builder Tools](/docs/academy/AdvancedTutorial/Create/BuilderTools)
+- [Powerhouse Builder Tools](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
 - [Yarn Global Installation Guide](https://classic.yarnpkg.com/lang/en/docs/cli/global/)
 - [Bun Installation Guide](https://bun.sh/docs/installation#how-to-add-your-path)
 </details>
 
 ## Powerhouse Project Recipes
+This section focuses on creating, configuring, and managing Powerhouse projects, which are collections of document models, editors, and other resources.
 
 <details id="initializing-a-new-project-and-document-model">
 <summary>Initializing a New Project & Document Model</summary>
@@ -402,8 +404,8 @@ 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](/docs/domain-modeling)
-- [GraphQL Schema Best Practices](/docs/academy/AdvancedTutorial/WorkWithData/GraphQLAtPowerhouse)
+- [Domain Modeling Guide](/domain-modeling)
+- [GraphQL Schema Best Practices](/academy/MasteryTrack/WorkWithData/GraphQLAtPowerhouse)
 </details>
 
 <details id="generating-reducers-from-a-document-model-file">
@@ -450,7 +452,7 @@ The command will output the generated reducer scaffolding code in the designated
 - Generating a Document Editor
 
 ## Further Reading
-- [Domain Modeling Guide](/docs/domain-modeling)
+- [Domain Modeling Guide](/domain-modeling)
 
 </details>
 
@@ -543,12 +545,13 @@ You might encounter a browser warning about the self-signed certificate; you may
 - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model)
 
 ## Further Reading
-- [Powerhouse Builder Tools](/docs/academy/AdvancedTutorial/Create/BuilderTools)
-- [GraphQL Schema Best Practices](/docs/academy/AdvancedTutorial/WorkWithData/GraphQLAtPowerhouse)
+- [Powerhouse Builder Tools](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
+- [GraphQL Schema Best Practices](/academy/MasteryTrack/WorkWithData/GraphQLAtPowerhouse)
 </details>
 
 
 ## Document & Drive Editor recipes
+This section provides guidance on generating and customizing editors for Document Models and custom interfaces for Drives.
 
 <details id="generating-a-document-editor">
 <summary>Generating a Document Editor</summary>
@@ -591,7 +594,7 @@ ph generate --editor <ModelName> --document-types <docType>
 - [Generating a Custom Drive Explorer](#generating-a-custom-drive-explorer)
 
 ## Further Reading
-- [Build a Todo-list Editor](/docs/academy/GetStarted/ToDoList/BuildToDoListEditor)
+- [Build a Todo-list Editor](/academy/GetStarted/BuildToDoListEditor)
 </details>
 
 <details id="generating-a-custom-drive-explorer">
@@ -633,7 +636,7 @@ ph generate --drive-editor <drive-app-name>
 - [Generating a Document Editor](#generating-a-document-editor)
 
 ## Further Reading
-- [Build a Drive-Explorer](/docs/academy/AdvancedTutorial/BuildingUserExperiences/BuildingADriveExplorer)
+- [Build a Drive-Explorer](/academy/MasteryTrack/BuildingUserExperiences/BuildingADriveExplorer)
 </details>
 
 <details id="adding-a-new-drive-via-graphql-mutation">
@@ -709,17 +712,18 @@ Use the constructed URL to add or access the drive in your Connect environment.
 - The drive can be managed or accessed using the generated URL.
 
 ## Related Recipes
-- [Configuring Drives](/docs/academy/AdvancedTutorial/BuildingUserExperiences/ConfiguringDrives)
+- [Configuring Drives](/academy/MasteryTrack/BuildingUserExperiences/ConfiguringDrives)
 - [Initializing a New Project & Document Model](#initializing-a-new-project-and-document-model)
 
 ## Further Reading
 - [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/testing/graphql-playground/)
-- [Powerhouse Builder Tools](/docs/academy/AdvancedTutorial/Create/BuilderTools)
+- [Powerhouse Builder Tools](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
 
 </details>
 
 
 ## Reactor Recipes
+Learn how to manage the Powerhouse Reactor, the local service for processing document model operations and state.
 
 <details id="starting-the-reactor">
 <summary>Starting the Reactor</summary>
@@ -767,6 +771,7 @@ ph reactor
 </details>
 
 ## Package Development Recipes
+These recipes guide you through creating, installing, and managing Powerhouse Packages, which are reusable collections of document models and editors.
 
 <details id="installing-a-custom-powerhouse-package">
 <summary>Installing a Custom Powerhouse Package</summary>
@@ -917,12 +922,13 @@ You need to understand and manage different types of dependencies in your Powerh
 - [Setting up or Resetting the Global Powerhouse Configuration](#setting-up-or-resetting-the-global-powerhouse-configuration)
 
 ## Further Reading
-- [Powerhouse Builder Tools](/docs/academy/AdvancedTutorial/Create/BuilderTools)
-- [GraphQL Schema Best Practices](/docs/academy/AdvancedTutorial/WorkWithData/GraphQLAtPowerhouse)
+- [Powerhouse Builder Tools](/academy/MasteryTrack/BuilderEnvironment/BuilderTools)
+- [GraphQL Schema Best Practices](/academy/MasteryTrack/WorkWithData/GraphQLAtPowerhouse)
 
 </details>
 
 ## Data Synchronisation Recipes
+This section helps troubleshoot and understand data synchronization within the Powerhouse ecosystem, including interactions between different services and components.
 
 <details id="troubleshooting-document-syncing">
 <summary>Troubleshooting Document Syncing: Supergraph vs. Drive Endpoints</summary>

package/docs/academy/08-Glossary.md

@@ -0,0 +1,82 @@
+# Glossary
+
+## General Terms
+- **Powerhouse** – A network organization that provides open-source software and services to support decentralized operations for other network organizations.
+- **Scalable Network Organization (SNO)** – A network organization structured according to the Powerhouse framework, designed for sustainable and scalable growth.
+- **Powerhouse Ecosystem** – The overall environment of Powerhouse tools, applications (like Connect), concepts (document models, packages), and services.
+
+## Technology & Framework
+- **CQRS (Command Query Responsibility Segregation)** – A pattern that separates read and write operations to improve scalability.
+- **Event Sourcing** – A method of storing system state as a sequence of immutable events rather than modifying a single record.
+
+## Software Components
+- **Reactor** – A storage node for Powerhouse documents and files with multiple storage adapters (local, cloud, decentralized).
+- **Powerhouse Switchboard** – A scalable API service that aggregates and processes document data.
+- **Powerhouse Fusion** – A platform front-end that hosts the public marketplace for SNO interactions.
+- **Powerhouse Renown** – A decentralized authentication system managing contributor reputation.
+- **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).
+- **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.
+- **Studio mode** – The local development mode of the Connect App (`ph connect`), for real-time document model definition, editor building, and testing.
+- **Renown (Login Flow)** – The Powerhouse decentralized login process using an Ethereum wallet signature to generate/retrieve a user's DID for secure, pseudonymous actions.
+- **Powerhouse Switchboard (Verifier Role)** – A function of Powerhouse Switchboard that validates DIDs and credentials for operations submitted via Connect, ensuring they are authorized.
+
+## Development & Data Modeling
+- **Action Creators (for Document Operations)** – Auto-generated helper functions creating structured "action" objects for dispatching operations to a document model's reducer.
+- **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.
+- **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.
+- **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.
+- **Document Models** – Structured data models that define how Powerhouse documents store and process information.
+- **Document State** – The current data held by a document instance, structured according to its Document Model.
+- **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.
+- **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.
+- **Host Applications** – Applications that use the Powerhouse framework to create and manage documents and data.
+- **Input Types (GraphQL for Document Operations)** – Custom data structures in SDL detailing parameters for document operations (e.g., `AddTodoItemInput`).
+- **Model-Driven Development (MDD)** – A software approach that uses high-level models to generate system logic and configurations.
+- **Modules (in Document Model Editor)** – An organizational feature in Connect Studio's model editor for grouping related operations.
+- **Operations (Document Operations)** – Named commands (e.g., `ADD_TODO_ITEM`) in a Document Model representing all ways to change its state, forming its event log.
+- **Powerhouse Document (`.phd` file)** – Standard file extension for an exported Powerhouse document instance, containing its data and history.
+- **Powerhouse Package** – A collection of document models, document model editors, and other resources that are published as a package and can be used in any of the host applications.
+- **Powerhouse Project** – A collection of document models, document model editors, and other resources being build in Connect Studio.
+- **Pure Functions (for Reducers)** – Principle that document model reducers must be pure (output depends only on input, no side effects) for predictable state transitions.
+- **Reducers (Document Model Reducers)** – Functions implementing a Document Model's logic; for each operation, a reducer takes current state and an action, returning new state.
+- **Replay Events** – The process of re-applying recorded events from a document's Event History to reconstruct or restore its state, a core capability of Event Sourcing.
+- **Scalars (Design System Components)** – Reusable UI building blocks (e.g., `Checkbox`, `InputField`) from `@powerhousedao/document-engineering/scalars`, used in editors (distinct from GraphQL scalars).
+- **State (Global State in Document Model)** – The primary, persisted, shared data of a document instance, managed by its reducers.
+- **State (Local State in Editor)** – Temporary, UI-specific data within an editor (e.g., form inputs), not persisted in the global document state.
+- **State Schema** – The component of a Document Model that defines the structure of the document, including its fields, data types, and validation rules, typically using a GraphQL-like syntax. It serves as a blueprint for how data is stored and validated.
+- **Storybook (for Powerhouse Design System)** – Interactive environment for browsing and testing Powerhouse Design System UI components.
+- **Strands** – A single synchronization channel that connects exactly one unit of synchronization to another, with all four parameters (drive_url, doc_id, scope, branch) set to fixed values. This allows synchronization between two distinct points of instances of a document or document drive.
+- **Tailwind CSS (in Connect Studio)** – Utility CSS framework integrated into Connect Studio for styling document editors.
+- **Time Travel Debugging** – A debugging technique, enabled by a document's Event History, that allows developers to reconstruct and inspect past states of the document by replaying events up to a specific point in time.
+- **Type Safety (in Document Modeling)** – Powerhouse's use of auto-generated TypeScript definitions from a model's schema (SDL) to prevent data type errors in development.
+- **Version Control (for Document Models)** – A planned feature for Document Models in Connect that will allow tracking of changes, comparison of different versions, and maintenance of data integrity over time, similar to version control systems for source code.
+
+## AI & Automation
+- **AI Assistants** – AI-powered contributors paired with human contributors to automate tasks and improve productivity.
+- **AI Contributor Modes** – Configurable states that determine the AI assistant's behavior, permissions, and task focus.
+- **Task Automation & Scaling** – The use of AI to streamline repetitive tasks, improve communications, and enhance decision-making.
+- **Decentralized Identifier (DID)** – A user-controlled, globally unique ID, used in Renown to link a user's blockchain key to actions pseudonymously.
+- **Immutable Updates** – A principle where data is never altered in place; operations create new data versions, vital for Powerhouse's event sourcing.
+- **Type Safety (in Document Modeling)** – Powerhouse's use of auto-generated TypeScript definitions from a model's schema (SDL) to prevent data type errors in development.
+
+## Organizational Concepts
+- **Ceramic** – A decentralized network for storing verifiable data, used by Powerhouse Renown for secure credential management.
+- **Decentralized Identifier (DID)** – A user-controlled, globally unique ID, used in Renown to link a user's blockchain key to actions pseudonymously.
+- **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.
+- **Event-Driven Architecture (EDA)** – A software design approach where system flows are determined by events that trigger actions asynchronously.
+- **Immutable Updates** – A principle where data is never altered in place; operations create new data versions, vital for Powerhouse's event sourcing.
+- **Network Organization** – A group of independent contributors and teams working together towards a common purpose, relying on decentralization and resource sharing.
+

package/docusaurus.config.ts

@@ -37,9 +37,8 @@ const config: Config = {
       'classic',
       {
         docs: {
+          routeBasePath: '/',
           sidebarPath: './sidebars.ts',
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
           editUrl:
             'https://github.com/powerhouse-inc/powerhouse-docs/tree/dev',
           showLastUpdateTime: false,
@@ -81,6 +80,7 @@ const config: Config = {
         alt: 'My Site Logo',
         src: 'img/Powerhouse-main.svg',
         srcDark: 'img/Powerhouse-main-light.svg',
+        href: '/',
       },
       items: [
         {
@@ -89,13 +89,6 @@ const config: Config = {
           position: 'left',
           label: 'Academy',
         },
-        {
-          type: 'docSidebar',
-          sidebarId: 'bookofpowerhouseSidebar',
-          position: 'left',
-          label: 'Book of Powerhouse',
-        },
-        {to: '/blog', label: 'Blog', position: 'left'},
         {
           href: 'https://github.com/powerhouse-inc/powerhouse-docs',
           label: 'GitHub',
@@ -111,23 +104,23 @@ const config: Config = {
           items: [
             {
               label: 'Connect',
-              to: 'docs/academy/Architecture/PowerhouseArchitecture',
+              to: 'academy/Architecture/PowerhouseArchitecture',
             },
             {
               label: 'Reactor',
-              to: 'docs/academy/Architecture/PowerhouseArchitecture',
+              to: 'academy/Architecture/PowerhouseArchitecture',
             },
             {
               label: 'Switchboard',
-              to: 'docs/academy/Architecture/PowerhouseArchitecture',
+              to: 'academy/Architecture/PowerhouseArchitecture',
             },
             {
               label: 'Renown',
-              to: 'docs/academy/Architecture/PowerhouseArchitecture',
+              to: 'academy/Architecture/PowerhouseArchitecture',
             },
             {
               label: 'FAQ',
-              to: 'docs/academy/Architecture/PowerhouseArchitecture',
+              to: 'academy/Architecture/PowerhouseArchitecture',
             },
             {
               label: "Blog",

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "0.1.0-dev.3",
+  "version": "0.1.0-dev.5",
   "homepage": "https://powerhouse.academy",
   "dependencies": {
     "@codesandbox/sandpack-react": "^2.14.4",
-    "@docusaurus/core": "^3.6.3",
-    "@docusaurus/preset-classic": "^3.6.3",
-    "@docusaurus/theme-search-algolia": "^3.7.0",
+    "@docusaurus/core": "^3.8.0",
+    "@docusaurus/plugin-content-docs": "^3.8.0",
+    "@docusaurus/preset-classic": "^3.8.0",
+    "@docusaurus/theme-search-algolia": "^3.8.0",
     "@mdx-js/react": "^3.0.0",
     "@powerhousedao/design-system": "^1.6.0",
     "clsx": "^2.0.0",
@@ -15,9 +16,10 @@
     "react-dom": "^18.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.6.3",
-    "@docusaurus/tsconfig": "^3.6.3",
-    "@docusaurus/types": "^3.6.3",
+    "@docusaurus/module-type-aliases": "^3.8.0",
+    "@docusaurus/tsconfig": "^3.8.0",
+    "@docusaurus/types": "^3.8.0",
+    "tsx": "^4.19.4",
     "typescript": "^5.7.3"
   },
   "browserslist": {
@@ -35,7 +37,7 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus serve",
-    "dev": "docusaurus start",
+    "dev": "docusaurus start --no-open",
     "build": "NODE_OPTIONS=--max_old_space_size=2048 docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
@@ -44,6 +46,7 @@
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
+    "generate:cli-docs": "tsx ./scripts/generate-combined-cli-docs.ts",
     "heroku-postbuild": "npm run build"
   }
 }

package/scripts/generate-combined-cli-docs.ts

@@ -0,0 +1,80 @@
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Generates combined CLI documentation from ph-cli and ph-cmd COMMANDS.md files
+ * and injects it into the main 00-PowerhouseCLI.md documentation file.
+ */
+async function generateCombinedCliDocs() {
+  try {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+
+    // Define paths
+    const academyDocsDir = path.resolve(__dirname, "..", "docs", "academy", "04-APIReferences");
+    const targetDocFile = path.join(academyDocsDir, "00-PowerhouseCLI.md");
+
+    const phCliCommandsPath = path.resolve(__dirname, "..", "..", "..", "clis", "ph-cli", "COMMANDS.md");
+    const phCmdCommandsPath = path.resolve(__dirname, "..", "..", "..", "clis", "ph-cmd", "COMMANDS.md");
+
+    // Read COMMANDS.md files
+    const phCliCommandsContent = fs.readFileSync(phCliCommandsPath, "utf8");
+    const phCmdCommandsContent = fs.readFileSync(phCmdCommandsPath, "utf8");
+
+    // Extract content after "## Table of Contents"
+    const extractCommands = (content: string, cliName: string): string => {
+      const tocHeader = "## Table of Contents";
+      const tocIndex = content.indexOf(tocHeader);
+      if (tocIndex === -1) {
+        console.warn(`Warning: "## Table of Contents" not found in ${cliName} COMMANDS.md. Including entire file.`);
+        return content;
+      }
+      let commandsSection = content.substring(tocIndex + tocHeader.length).trim();
+      
+      // Remove the auto-generation footer
+      const footerRegex = /---\\n\\n\\\*This document was automatically generated from the help text in the codebase\\\.\\\*\\n?$/m;
+      commandsSection = commandsSection.replace(footerRegex, "").trim();
+      return commandsSection;
+    };
+
+    const phCliDocs = extractCommands(phCliCommandsContent, "ph-cli");
+    const phCmdDocs = extractCommands(phCmdCommandsContent, "ph-cmd");
+
+    // Prepare the combined markdown
+    let combinedDocs = `### ph-cmd Commands\\n\\n${phCmdDocs}\\n\\n### ph-cli Commands\\n\\n${phCliDocs}`;
+
+    // Read the target documentation file
+    let targetDocContent = fs.readFileSync(targetDocFile, "utf8");
+
+    // Replace the placeholder with the combined docs
+    const startPlaceholder = "<!-- AUTO-GENERATED-CLI-COMMANDS-START -->";
+    const endPlaceholder = "<!-- AUTO-GENERATED-CLI-COMMANDS-END -->";
+    const startIndex = targetDocContent.indexOf(startPlaceholder);
+    const endIndex = targetDocContent.indexOf(endPlaceholder);
+
+    if (startIndex === -1 || endIndex === -1) {
+      console.error(`Error: Placeholders not found in ${targetDocFile}. Please ensure the file contains:\\n${startPlaceholder}\\n...\\n${endPlaceholder}`);
+      process.exit(1);
+    }
+
+    targetDocContent = 
+      targetDocContent.substring(0, startIndex + startPlaceholder.length) +
+      "\\n<!-- This content is automatically generated. Do not edit directly. -->\\n" +
+      combinedDocs +
+      "\\n" +
+      targetDocContent.substring(endIndex);
+
+    // Write the updated content back to the target file
+    fs.writeFileSync(targetDocFile, targetDocContent);
+
+    console.log(`✅ Combined CLI documentation has been generated at ${targetDocFile}`);
+
+  } catch (error) {
+    console.error("Failed to generate combined CLI documentation:", error);
+    process.exit(1);
+  }
+}
+
+// Run the script
+generateCombinedCliDocs();