opusdocs-complete.patch

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..7d62a24d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Build and Run
+- **Development**: `npm start` - Runs the app with Vite
+- **Build**: `npm run build` - TypeScript check and Vite build
+- **Legacy Builds**: `npm run start:legacy` or `npm run build:legacy` - Uses craco with OpenSSL legacy provider
+
+### Testing
+- **Jest Tests**: `npm test` - Runs Jest tests (*.test.tsx, *.test.ts)
+- **Vitest Tests**: `npm run test:vitest` - Runs Vitest tests (*.vitest.tsx, *.vitest.ts)
+- **Single Test**: `npm test -- --testNamePattern="test name"`
+
+### Code Quality
+- **Lint**: `npm run lint` - ESLint check
+- **Lint Fix**: `npm run lint:fix` - Auto-fix ESLint issues
+- **Format**: `npm run code-format:fix` - Prettier formatting
+- **Format Check**: `npm run code-format:validate` - Check Prettier formatting
+
+### Mock Generation
+- **Generate Mocks**: `BUILD_MOCKS=true npm test -- --watchAll=false src/app-sandbox/index.test.tsx`
+
+## Architecture Overview
+
+### Redux-Based Architecture
+The application follows a Redux-Saga architecture with normalized state management:
+- **Components**: Presentational React components in `/src/components/`
+- **Connected Components**: Container components with Redux connections
+- **Redux Store**: State management in `/src/store/` with feature-based organization
+- **Sagas**: Side effects handled by redux-saga
+- **Normalizr**: Entity normalization for consistent state shape
+
+### Key Directories
+- **`/src/apps/`**: Core application modules (feed, messenger, wallet, staking, etc.)
+- **`/src/store/`**: Redux state management, organized by feature
+- **`/src/lib/`**: Shared utilities and hooks
+- **`/src/components/`**: Reusable UI components
+- **`/src/authentication/`**: Auth flows and components
+
+### External App Integration
+Apps can be integrated as external components using the ExternalApp wrapper:
+1. Create folder in `/src/apps/your-app/`
+2. Add to AppRouter in `/src/apps/app-router.tsx`
+3. Add navigation in AppBar component
+
+### Matrix Integration
+The app uses Matrix for chat functionality:
+- Matrix client configuration in `/src/lib/chat/matrix/`
+- Home server URL configured via `REACT_APP_MATRIX_HOME_SERVER_URL`
+- Sliding sync support for improved performance
+
+### Web3 Integration
+- **Wagmi & RainbowKit**: Wallet connection and management
+- **Thirdweb**: Additional Web3 functionality
+- **Chains**: Multi-chain support configured in `/src/lib/web3/`
+
+### Testing Approach
+- **Jest**: Used for unit tests with Enzyme (legacy)
+- **Vitest**: Modern test runner for newer tests
+- **Test Utils**: Testing utilities in `/src/test-utils.tsx`
+- **Redux Testing**: redux-saga-test-plan for saga testing
+
+### Build Configuration
+- **Vite**: Primary build tool with React SWC plugin
+- **Craco**: Legacy build support for compatibility
+- **Environment Variables**: Prefixed with `REACT_APP_`
+- **Node Polyfills**: Enabled for Web3 compatibility
+
+## Key Patterns
+
+### Component Structure
+```typescript
+// Presentational component
+const Component = ({ prop }) => <div>{prop}</div>;
+
+// Connected component (container)
+const Container = connect(mapStateToProps, mapDispatchToProps)(Component);
+```
+
+### Redux-Saga Pattern
+```typescript
+function* saga() {
+  yield takeEvery(ACTION_TYPE, function* (action) {
+    try {
+      const result = yield call(api.method, action.payload);
+      yield put(successAction(result));
+    } catch (error) {
+      yield put(errorAction(error));
+    }
+  });
+}
+```
+
+### Normalized State
+Entities are normalized using normalizr schemas for consistent access patterns.
+
+### Module CSS
+Components use CSS modules (*.module.scss) for scoped styling.
+
+## Agent Communication Guidelines
+
+### Inter-Agent Communication
+- **`./agents-only/`**: Designated directory for semaphores, control flows, job requests, and any form of inter-agent communication
+- **Flexibility**: Agents are free to create any necessary communication artifacts in this directory, including codes.
+
+## Deliverables Management
+- **Opus Docs Location**: Use `./opusdocs/` as the production location for deliverables
+- **Named Versions**: Multiple named versions of files are permitted
+
+## Development Naming Conventions
+- Don't capitalize filenames, use standard naming conventions
+- Always use lowercase for file and directory names
+- Prefer kebab-case or snake_case for multi-word filenames
+
+## Workspace Guides
+- **Opus Docs Usage**: 
+  - USE `./opusdocs/new-recruits/` to generate necessary and requested files (documentation, prompts, notes, dev-logs) for new developers who are already coding full stack web apps
diff --git a/opusdocs/architecture-overview.md b/opusdocs/architecture-overview.md
new file mode 100644
index 00000000..b756a084
--- /dev/null
+++ b/opusdocs/architecture-overview.md
@@ -0,0 +1,414 @@
+# zOS Architecture Overview
+
+## System Overview
+
+zOS (Zero Operating System) is a sophisticated web application built around a **Redux-Saga-Normalizr** pattern that creates a decentralized, Matrix-protocol-based social platform with Web3 integration. The architecture prioritizes real-time communication, normalized data management, and modular application design.
+
+### High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         zOS Application                         │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
+│  │   Feed      │ │ Messenger   │ │   Wallet    │ │   Staking   ││
+│  │    App      │ │     App     │ │     App     │ │     App     ││
+│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│
+├─────────────────────────────────────────────────────────────────┤
+│                      App Router                                 │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
+│  │   Redux     │ │   Sagas     │ │ Normalized  │ │   Matrix    ││
+│  │   Store     │ │ Middleware  │ │   State     │ │   Client    ││
+│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│
+├─────────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│
+│  │   Matrix    │ │    Web3     │ │  Cloudinary │ │   Thirdweb  ││
+│  │  Protocol   │ │  Wallets    │ │   Images    │ │    APIs     ││
+│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Core Technology Stack
+
+- **Frontend Framework**: React 18 with TypeScript
+- **State Management**: Redux Toolkit + Redux-Saga
+- **Data Normalization**: Normalizr for entity management
+- **Real-time Communication**: Matrix Protocol (matrix-js-sdk)
+- **Web3 Integration**: Wagmi + RainbowKit + Thirdweb
+- **Styling**: SCSS with CSS Modules
+- **Build Tool**: Vite
+- **Testing**: Vitest + Jest
+
+## Main Architectural Patterns
+
+### 1. Redux-Saga-Normalizr Pattern
+
+The application follows a sophisticated state management pattern that combines:
+
+- **Redux Toolkit**: Modern Redux with createSlice for reducers
+- **Redux-Saga**: Side effect management for async operations
+- **Normalizr**: Entity normalization for relational data
+
+#### Why This Pattern?
+
+- **Redux-Saga over alternatives**: Provides powerful async flow control with cancellation, racing, and complex orchestration
+- **Normalized state benefits**: Eliminates data duplication, ensures consistency, and simplifies updates
+- **Matrix protocol integration**: Sagas handle complex Matrix event flows and real-time synchronization
+
+### 2. Modular Application Architecture
+
+Each major feature is organized as a self-contained "app" within the `/src/apps/` directory:
+
+```
+apps/
+├── feed/           # Social media feed functionality
+├── messenger/      # Real-time chat application
+├── wallet/         # Web3 wallet management
+├── staking/        # DeFi staking interface
+├── profile/        # User profile management
+├── notifications/  # Notification system
+└── explorer/       # External app integration
+```
+
+## Data Flow Architecture
+
+### Redux Store Structure
+
+```
+rootState: {
+  // Core entities (normalized)
+  normalized: {
+    users: { [id]: User },
+    channels: { [id]: Channel },
+    messages: { [id]: Message }
+  },
+  
+  // Feature slices
+  authentication: AuthState,
+  chat: ChatState,
+  web3: Web3State,
+  posts: PostsState,
+  
+  // UI state
+  panels: PanelsState,
+  dialogs: DialogsState,
+  background: BackgroundState
+}
+```
+
+### Saga Flow Pattern
+
+```mermaid
+graph TD
+    A[UI Action] --> B[Saga Watcher]
+    B --> C[Saga Worker]
+    C --> D[Matrix API Call]
+    C --> E[REST API Call]
+    C --> F[Web3 Transaction]
+    D --> G[Normalize Response]
+    E --> G
+    F --> G
+    G --> H[Dispatch to Store]
+    H --> I[UI Update]
+```
+
+### Normalizr Entity Management
+
+The application uses Normalizr to manage relational data:
+
+```typescript
+// Schema definitions
+const userSchema = new schema.Entity('users');
+const channelSchema = new schema.Entity('channels');
+const messageSchema = new schema.Entity('messages', {
+  sender: userSchema,
+  channel: channelSchema
+});
+
+// Normalization happens in sagas
+const normalizedData = normalize(apiResponse, [messageSchema]);
+dispatch(receive(normalizedData.entities));
+```
+
+## Matrix Protocol Integration
+
+### Architecture Overview
+
+zOS is built on the Matrix protocol for decentralized communication:
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   zOS Client    │◄──►│  Matrix Client   │◄──►│ Matrix Server   │
+│                 │    │   (matrix-js-sdk)│    │  (Homeserver)   │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+         │                       │                       │
+         │                       │                       │
+    ┌────▼────┐             ┌────▼────┐             ┌────▼────┐
+    │ Redux   │             │ Event   │             │ Room    │
+    │ Sagas   │             │Handler  │             │ State   │
+    └─────────┘             └─────────┘             └─────────┘
+```
+
+### Key Matrix Integration Points
+
+1. **Authentication**: JWT-based login with Matrix homeserver
+2. **Real-time Events**: Matrix events flow through sagas to Redux store
+3. **End-to-End Encryption**: Built-in E2EE with key backup/restore
+4. **Room Management**: Channels are Matrix rooms with custom metadata
+5. **File Uploads**: Encrypted file handling through Matrix media API
+
+### Matrix Client Wrapper
+
+The `MatrixClient` class (`/src/lib/chat/matrix-client.ts`) provides:
+
+- Connection management and authentication
+- Event processing and normalization
+- Message sending/receiving with encryption
+- Room creation and management
+- File upload/download with caching
+
+## Module Architecture
+
+### App Module Structure
+
+Each app follows a consistent structure:
+
+```
+apps/[app-name]/
+├── index.tsx                 # Main app component
+├── components/              # App-specific components
+├── lib/                     # Business logic and hooks
+│   ├── types.ts            # TypeScript interfaces
+│   ├── useAppLogic.ts      # Custom hooks
+│   └── utils.ts            # Utility functions
+└── styles.module.scss      # Scoped styles
+```
+
+### Component Hierarchy
+
+```
+App
+├── AppRouter               # Route-based app switching
+│   ├── MessengerApp       # Real-time chat
+│   ├── FeedApp            # Social media feed
+│   ├── WalletApp          # Web3 wallet
+│   └── [Other Apps]
+├── AppBar                 # Global navigation
+├── DialogManager          # Modal management
+└── Sidekick              # Context-aware sidebar
+```
+
+### State Management Per Feature
+
+Each feature manages its state through:
+
+1. **Slice**: Redux slice with actions and reducers
+2. **Saga**: Side effect management and async operations
+3. **Selectors**: Memoized state access patterns
+4. **Hooks**: React hooks for component integration
+
+Example pattern:
+```typescript
+// Slice (actions + reducer)
+const slice = createSlice({
+  name: 'feature',
+  initialState,
+  reducers: { /* sync actions */ }
+});
+
+// Saga (async operations)
+function* featureSaga() {
+  yield takeEvery('feature/action', handleAction);
+}
+
+// Selectors (memoized state access)
+const selectFeatureData = createSelector(
+  (state) => state.feature,
+  (feature) => feature.data
+);
+```
+
+## Web3 Architecture
+
+### Integration Strategy
+
+zOS integrates Web3 functionality through multiple layers:
+
+1. **Wagmi**: React hooks for Ethereum interaction
+2. **RainbowKit**: Wallet connection UI
+3. **Thirdweb**: Additional Web3 utilities and APIs
+4. **Custom Hooks**: App-specific Web3 logic
+
+### Web3 State Management
+
+```typescript
+interface Web3State {
+  status: ConnectionStatus;
+  value: {
+    chainId: number;
+    address: string;
+    connectorId: string;
+    error: string;
+  };
+}
+```
+
+### Wallet Integration Points
+
+- **Authentication**: Web3 login alongside Matrix authentication
+- **Staking**: DeFi protocol interactions
+- **NFT Management**: Token display and transfers
+- **Transaction History**: On-chain activity tracking
+
+## Essential Concepts for Developers
+
+### 1. Why Redux-Saga?
+
+**Advantages:**
+- **Testability**: Sagas are pure functions, easy to test
+- **Cancellation**: Built-in support for cancelling async operations
+- **Flow Control**: Complex async orchestration with racing, forking
+- **Integration**: Perfect for handling Matrix protocol events
+
+**Common Pattern:**
+```typescript
+function* handleMessageSend(action) {
+  try {
+    // Send via Matrix
+    const result = yield call(matrixClient.sendMessage, action.payload);
+    
+    // Update optimistic message
+    yield put(updateOptimisticMessage(result));
+    
+    // Record analytics
+    yield fork(recordMessageSent, result);
+  } catch (error) {
+    yield put(setError(error));
+  }
+}
+```
+
+### 2. Normalized State Benefits
+
+**Problem Solved:**
+- Data duplication across components
+- Inconsistent updates
+- Complex nested state updates
+
+**Solution:**
+```typescript
+// Instead of nested data
+{
+  channels: [
+    { id: 1, name: "General", messages: [/* full message objects */] }
+  ]
+}
+
+// Use normalized structure
+{
+  channels: { 1: { id: 1, name: "General", messageIds: [101, 102] } },
+  messages: { 
+    101: { id: 101, text: "Hello", senderId: 5 },
+    102: { id: 102, text: "World", senderId: 3 }
+  },
+  users: {
+    3: { id: 3, name: "Alice" },
+    5: { id: 5, name: "Bob" }
+  }
+}
+```
+
+### 3. Matrix Protocol Benefits
+
+**Decentralization**: No single point of failure
+**Interoperability**: Standards-based communication
+**Security**: End-to-end encryption by default
+**Scalability**: Federation across multiple servers
+
+### 4. Component Integration Patterns
+
+**Using Selectors:**
+```typescript
+const MyComponent = () => {
+  const messages = useSelector(selectChannelMessages(channelId));
+  const users = useSelector(selectUsers);
+  
+  return (
+    <div>
+      {messages.map(message => (
+        <Message 
+          key={message.id} 
+          message={message}
+          user={users[message.senderId]}
+        />
+      ))}
+    </div>
+  );
+};
+```
+
+**Dispatching Actions:**
+```typescript
+const dispatch = useDispatch();
+
+const handleSendMessage = (text: string) => {
+  dispatch(sendMessage({ 
+    channelId, 
+    text, 
+    optimisticId: generateId() 
+  }));
+};
+```
+
+## Common Pitfalls and Solutions
+
+### 1. **Async State Race Conditions**
+**Problem**: Multiple async operations updating the same state
+**Solution**: Use saga patterns like `takeLatest` or request cancellation
+
+### 2. **Normalized State Complexity**
+**Problem**: Difficulty accessing related entities
+**Solution**: Use memoized selectors to join normalized data
+
+### 3. **Matrix Event Ordering**
+**Problem**: Out-of-order event processing
+**Solution**: Event sequencing in sagas with proper error handling
+
+### 4. **Memory Leaks in Real-time Apps**
+**Problem**: Event listeners not cleaned up
+**Solution**: Proper cleanup in useEffect hooks and saga cancellation
+
+## Getting Started: Developer Mental Model
+
+### 1. **Data Flow Understanding**
+1. User interacts with UI component
+2. Component dispatches Redux action
+3. Saga intercepts action and handles side effects
+4. API responses are normalized and stored
+5. Selectors provide normalized data to components
+6. UI updates reactively
+
+### 2. **Adding New Features**
+1. Define normalized schema if needed
+2. Create Redux slice with actions
+3. Implement saga for async operations
+4. Create selectors for data access
+5. Build UI components with hooks
+6. Connect everything through the app router
+
+### 3. **Matrix Integration**
+1. Understand rooms as channels
+2. Events flow through the MatrixClient wrapper
+3. Sagas process Matrix events into Redux actions
+4. UI components react to normalized state changes
+
+### 4. **Web3 Integration**
+1. Use Wagmi hooks for blockchain interactions
+2. Handle wallet connection state
+3. Integrate with existing Redux patterns
+4. Consider gas optimization and error handling
+
+---
+
+This architecture enables zOS to be a scalable, real-time, decentralized social platform that seamlessly integrates Web3 functionality while maintaining a clean separation of concerns and robust state management.
\ No newline at end of file
diff --git a/opusdocs/blockchain-integration.md b/opusdocs/blockchain-integration.md
new file mode 100644
index 00000000..70799559
--- /dev/null
+++ b/opusdocs/blockchain-integration.md
@@ -0,0 +1,872 @@
+# Blockchain Integration Guide for zOS
+
+This guide provides comprehensive patterns and examples for integrating blockchain functionality into zOS applications, with special focus on wallet connections, transactions, and smart contract interactions that support Haven Protocol's creator economy features.
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Wallet Connection Patterns](#wallet-connection-patterns)
+3. [Transaction Handling](#transaction-handling)
+4. [Smart Contract Interactions](#smart-contract-interactions)
+5. [State Management Integration](#state-management-integration)
+6. [Error Handling & User Experience](#error-handling--user-experience)
+7. [Security Best Practices](#security-best-practices)
+8. [Creator Economy Patterns](#creator-economy-patterns)
+9. [Testing Strategies](#testing-strategies)
+10. [Troubleshooting](#troubleshooting)
+
+## Architecture Overview
+
+zOS uses a modern Web3 stack built around **RainbowKit**, **Wagmi**, and **Viem** for blockchain interactions. The architecture separates concerns between UI components, Redux state management, and blockchain operations.
+
+### Core Technologies
+
+- **RainbowKit**: Wallet connection UI and management
+- **Wagmi**: React hooks for Ethereum interactions
+- **Viem**: TypeScript library for Ethereum operations
+- **React Query**: Caching and synchronization for blockchain data
+- **Redux Toolkit**: Global state management for Web3 state
+
+### Supported Networks
+
+```typescript
+// From /src/lib/web3/wagmi-config.ts
+const supportedChains = [
+  1,          // Ethereum Mainnet
+  11155111,   // Sepolia Testnet
+  43113,      // Avalanche Fuji Testnet
+  1417429182  // Zephyr Test Net (custom chain)
+];
+```
+
+## Wallet Connection Patterns
+
+### Basic Wallet Provider Setup
+
+The foundation of zOS's Web3 integration starts with the `RainbowKitProvider`:
+
+```tsx
+// /src/lib/web3/rainbowkit/provider.tsx
+import { WagmiProvider } from 'wagmi';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { RainbowKitProvider as RKProvider, darkTheme } from '@rainbow-me/rainbowkit';
+import { getWagmiConfig } from '../wagmi-config';
+
+const queryClient = new QueryClient();
+
+export const RainbowKitProvider = ({ children }) => {
+  return (
+    <WagmiProvider config={getWagmiConfig()}>
+      <QueryClientProvider client={queryClient}>
+        <RKProvider theme={darkTheme()} modalSize='compact'>
+          {children}
+        </RKProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  );
+};
+```
+
+### Connection State Management
+
+zOS implements a comprehensive connection monitoring system:
+
+```tsx
+// /src/lib/web3/rainbowkit/connect.tsx
+import { watchAccount } from '@wagmi/core';
+import { ConnectionStatus } from '..';
+
+export class Container extends React.Component<Properties> {
+  watchConnection() {
+    this.unwatch = watchAccount(getWagmiConfig(), {
+      onChange: (account, prevAccount) => {
+        this.props.setChain(account.chainId);
+        
+        if (!account.isConnected) {
+          this.props.setConnectionStatus(ConnectionStatus.Disconnected);
+        } else if (!this.isSupportedChain(account.chainId)) {
+          this.props.setConnectionStatus(ConnectionStatus.NetworkNotSupported);
+        } else {
+          this.props.setConnectionStatus(ConnectionStatus.Connected);
+          
+          // Handle address changes for wallet switching
+          if (account.address && prevAccount?.address !== account.address) {
+            this.props.setAddress(account.address);
+          }
+        }
+      },
+    });
+  }
+
+  isSupportedChain(chainId: number | undefined): boolean {
+    if (!chainId) return false;
+    const supportedChains = [1, 11155111, 43113]; // mainnet, sepolia, avalanche fuji
+    return supportedChains.includes(chainId);
+  }
+}
+```
+
+### Connection State in Redux
+
+```typescript
+// /src/store/web3/index.ts
+export enum ConnectionStatus {
+  Disconnected = 'disconnected',
+  Connected = 'connected',
+  NetworkNotSupported = 'network-not-supported'
+}
+
+export interface Web3State {
+  status: ConnectionStatus;
+  value: {
+    chainId: Chains;
+    address: string;
+    connectorId: Connector['id'] | '';
+    error: string;
+  };
+}
+```
+
+### User Authentication with Web3
+
+zOS integrates Web3 authentication seamlessly with traditional auth:
+
+```tsx
+// /src/authentication/web3-login/index.tsx
+export class Web3Login extends React.Component<Web3LoginProperties> {
+  render() {
+    const { error, isConnecting, isWalletConnected, onSelect } = this.props;
+
+    return (
+      <div>
+        <RainbowKitConnectButton isDisabled={isConnecting} />
+        {isWalletConnected && (
+          <Button isDisabled={isConnecting} onPress={onSelect}>
+            Sign In
+          </Button>
+        )}
+        {error && (
+          <Alert variant='error'>
+            {error === Web3LoginErrors.PROFILE_NOT_FOUND
+              ? 'The wallet you connected is not associated with a ZERO account'
+              : error}
+          </Alert>
+        )}
+      </div>
+    );
+  }
+}
+```
+
+## Transaction Handling
+
+### Token Transfer Pattern
+
+zOS uses a hybrid approach combining client-side preparation with server-side execution for security:
+
+```typescript
+// /src/apps/wallet/queries/transferTokenRequest.ts
+export const transferTokenRequest = async (
+  address: string,
+  to: string,
+  amount: string,
+  tokenAddress: string
+): Promise<TransferTokenResponse> => {
+  const response = await post(`/api/wallet/${address}/transactions/transfer-token`).send({
+    to,
+    amount,
+    tokenAddress,
+  });
+
+  return response.body as TransferTokenResponse;
+};
+```
+
+### NFT Transfer Implementation
+
+```typescript
+// /src/apps/wallet/queries/transferNFTRequest.ts
+export const transferNFTRequest = async (
+  address: string,
+  to: string,
+  tokenId: string,
+  nftAddress: string
+): Promise<TransferNFTResponse> => {
+  const response = await post(`/api/wallet/${address}/transactions/transfer-nft`).send({
+    to,
+    tokenId,
+    nftAddress,
+  });
+
+  return response.body as TransferNFTResponse;
+};
+```
+
+### Transaction Receipt Monitoring
+
+```typescript
+// Pattern for monitoring transaction status
+const waitForTransactionReceipt = async (hash: string) => {
+  const receiptResponse = await get(`/api/wallet/transaction/${hash}/receipt`).send();
+  
+  if (receiptResponse.body.status === 'confirmed') {
+    return { success: true, receipt: receiptResponse.body };
+  } else if (receiptResponse.body.status === 'failed') {
+    throw new Error('Transaction failed');
+  }
+  
+  // Continue polling for pending transactions
+  return null;
+};
+```
+
+## Smart Contract Interactions
+
+### Staking Contract Integration
+
+zOS implements a comprehensive staking system with proper error handling and state management:
+
+```typescript
+// /src/apps/staking/lib/useStaking.ts
+export const useStaking = () => {
+  const { address: userAddress } = useSelector(selectedWalletSelector);
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: async ({ poolAddress, amount, lockDuration }: StakingParams) => {
+      if (!userAddress) {
+        throw new Error('User not connected');
+      }
+
+      let response;
+      try {
+        response = await post(`/api/wallet/${userAddress}/transactions/stake${lockDuration ? '-with-lock' : ''}`).send({
+          poolAddress,
+          amount,
+          lockDuration,
+        });
+      } catch (e) {
+        console.error(e);
+        throw new Error('Failed to stake tokens, please try again.');
+      }
+
+      if (response.body?.transactionHash) {
+        const receiptResponse = await get(`/api/wallet/transaction/${response.body.transactionHash}/receipt`).send();
+
+        if (receiptResponse.body.status === 'confirmed') {
+          return { success: true, hash: response.body.transactionHash, receipt: receiptResponse.body };
+        } else {
+          throw new Error('Transaction failed');
+        }
+      }
+    },
+    onSuccess: (_, { poolAddress }) => {
+      // Invalidate relevant queries to refresh UI
+      queryClient.invalidateQueries({
+        queryKey: ['userStakingBalance'],
+      });
+      queryClient.invalidateQueries({
+        queryKey: ['userStakingInfo', poolAddress],
+      });
+    },
+  });
+
+  const executeStake = async (poolAddress: string, amount: string, lockDuration?: string) => {
+    try {
+      const result = await mutation.mutateAsync({ poolAddress, amount, lockDuration });
+      return result;
+    } catch (err: any) {
+      const errorMessage = err.message || 'Staking failed';
+      return { success: false, error: errorMessage };
+    }
+  };
+
+  return {
+    stakeWithLock: (poolAddress: string, amount: string, lockDuration: string) => 
+      executeStake(poolAddress, amount, lockDuration),
+    stakeWithoutLock: (poolAddress: string, amount: string) => 
+      executeStake(poolAddress, amount),
+    isStaking: mutation.isPending,
+    error: mutation.error?.message || null,
+  };
+};
+```
+
+### Token Approval Pattern
+
+```typescript
+// /src/apps/staking/lib/useTokenApproval.ts
+export const useTokenApproval = () => {
+  const { address: userAddress } = useSelector(selectedWalletSelector);
+
+  const mutation = useMutation({
+    mutationFn: async ({ tokenAddress, spender, amount }: ApprovalParams) => {
+      if (!userAddress) {
+        throw new Error('User not connected');
+      }
+
+      const response = await post(`/api/wallet/${userAddress}/transactions/approve`).send({
+        tokenAddress,
+        spender,
+        amount,
+      });
+
+      if (response.body?.transactionHash) {
+        // Wait for confirmation
+        const receiptResponse = await get(`/api/wallet/transaction/${response.body.transactionHash}/receipt`).send();
+        
+        if (receiptResponse.body.status === 'confirmed') {
+          return { success: true, hash: response.body.transactionHash };
+        } else {
+          throw new Error('Approval transaction failed');
+        }
+      }
+    },
+  });
+
+  return {
+    approveToken: mutation.mutateAsync,
+    isApproving: mutation.isPending,
+    error: mutation.error?.message || null,
+  };
+};
+```
+
+## State Management Integration
+
+### Web3 State Structure
+
+```typescript
+// /src/store/web3/index.ts
+export interface Web3State {
+  status: ConnectionStatus;
+  value: {
+    chainId: Chains;
+    address: string;
+    connectorId: Connector['id'] | '';
+    error: string;
+  };
+}
+
+const slice = createSlice({
+  name: 'web3',
+  initialState,
+  reducers: {
+    setConnectionStatus: (state, action: PayloadAction<ConnectionStatus>) => {
+      state.status = action.payload;
+    },
+    setWalletAddress: (state, action: PayloadAction<string>) => {
+      state.value.address = action.payload;
+    },
+    setChain: (state, action: PayloadAction<Chains>) => {
+      state.value.chainId = action.payload;
+    },
+    setWalletConnectionError: (state, action: PayloadAction<string>) => {
+      state.value.error = action.payload;
+    },
+  },
+});
+```
+
+### Wallet State Management
+
+```typescript
+// /src/store/wallet/selectors.ts
+export const selectedWalletSelector = (state: RootState) => {
+  return {
+    address: state.web3.value.address,
+    chainId: state.web3.value.chainId,
+    status: state.web3.status,
+    connectorId: state.web3.value.connectorId,
+  };
+};
+```
+
+## Error Handling & User Experience
+
+### Connection Error Handling
+
+```typescript
+// Comprehensive error handling pattern
+const handleWeb3Error = (error: Error): string => {
+  if (error.message.includes('User denied transaction')) {
+    return 'Transaction was cancelled by user';
+  }
+  
+  if (error.message.includes('insufficient funds')) {
+    return 'Insufficient funds for transaction';
+  }
+  
+  if (error.message.includes('network')) {
+    return 'Network error. Please check your connection and try again';
+  }
+  
+  return 'An unexpected error occurred. Please try again';
+};
+```
+
+### Loading States and User Feedback
+
+```tsx
+// Pattern for showing transaction progress
+const TransactionButton = ({ onExecute, children }) => {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleClick = async () => {
+    setIsLoading(true);
+    setError(null);
+    
+    try {
+      await onExecute();
+    } catch (err) {
+      setError(handleWeb3Error(err as Error));
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return (
+    <>
+      <Button 
+        isLoading={isLoading} 
+        onPress={handleClick}
+        isDisabled={isLoading}
+      >
+        {children}
+      </Button>
+      {error && <Alert variant="error">{error}</Alert>}
+    </>
+  );
+};
+```
+
+## Security Best Practices
+
+### 1. Address Validation
+
+```typescript
+const isValidAddress = (address: string): boolean => {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+};
+
+const validateRecipient = (to: string) => {
+  if (!isValidAddress(to)) {
+    throw new Error('Invalid recipient address');
+  }
+  
+  if (to.toLowerCase() === userAddress.toLowerCase()) {
+    throw new Error('Cannot send to yourself');
+  }
+};
+```
+
+### 2. Amount Validation
+
+```typescript
+const validateAmount = (amount: string, balance: string, decimals: number) => {
+  const amountBN = parseUnits(amount, decimals);
+  const balanceBN = parseUnits(balance, decimals);
+  
+  if (amountBN <= 0n) {
+    throw new Error('Amount must be greater than 0');
+  }
+  
+  if (amountBN > balanceBN) {
+    throw new Error('Insufficient balance');
+  }
+};
+```
+
+### 3. Network Validation
+
+```typescript
+const requireSupportedNetwork = (chainId: number) => {
+  const supportedChains = [1, 11155111, 43113, 1417429182];
+  
+  if (!supportedChains.includes(chainId)) {
+    throw new Error('Please switch to a supported network');
+  }
+};
+```
+
+### 4. Transaction Signing Security
+
+```typescript
+// Always validate transaction parameters before signing
+const prepareTransaction = (params: TransactionParams) => {
+  validateRecipient(params.to);
+  validateAmount(params.amount, params.balance, params.decimals);
+  requireSupportedNetwork(params.chainId);
+  
+  return {
+    to: params.to,
+    value: parseUnits(params.amount, params.decimals),
+    data: params.data || '0x',
+  };
+};
+```
+
+## Creator Economy Patterns
+
+### Content Monetization Integration
+
+```typescript
+// Pattern for integrating blockchain payments with content
+const useContentPayment = () => {
+  const { address } = useSelector(selectedWalletSelector);
+  
+  const payForContent = async (
+    contentId: string, 
+    creatorAddress: string, 
+    amount: string
+  ) => {
+    // Validate creator and content
+    const content = await validateContent(contentId);
+    if (content.creator !== creatorAddress) {
+      throw new Error('Creator address mismatch');
+    }
+    
+    // Execute payment
+    const result = await transferTokenRequest(
+      address,
+      creatorAddress,
+      amount,
+      PAYMENT_TOKEN_ADDRESS
+    );
+    
+    if (result.transactionHash) {
+      // Update content access permissions
+      await grantContentAccess(contentId, address);
+      return { success: true, hash: result.transactionHash };
+    }
+    
+    throw new Error('Payment failed');
+  };
+  
+  return { payForContent };
+};
+```
+
+### NFT Minting for Creators
+
+```typescript
+// Pattern for creator NFT minting
+const useCreatorNFT = () => {
+  const { address } = useSelector(selectedWalletSelector);
+  
+  const mintCreatorNFT = async (
+    metadata: NFTMetadata,
+    royaltyPercentage: number
+  ) => {
+    // Validate creator permissions
+    if (!await isVerifiedCreator(address)) {
+      throw new Error('Only verified creators can mint NFTs');
+    }
+    
+    const response = await post(`/api/wallet/${address}/transactions/mint-nft`).send({
+      metadata,
+      royalty: royaltyPercentage,
+      creator: address,
+    });
+    
+    if (response.body?.transactionHash) {
+      const receipt = await waitForTransactionReceipt(response.body.transactionHash);
+      
+      if (receipt.success) {
+        return {
+          success: true,
+          tokenId: receipt.receipt.logs[0].topics[3], // Extract token ID from logs
+          hash: response.body.transactionHash,
+        };
+      }
+    }
+    
+    throw new Error('NFT minting failed');
+  };
+  
+  return { mintCreatorNFT };
+};
+```
+
+### Revenue Sharing Implementation
+
+```typescript
+// Pattern for automated revenue sharing
+const useRevenueSharing = () => {
+  const distributeRevenue = async (
+    totalAmount: string,
+    recipients: Array<{ address: string; percentage: number }>
+  ) => {
+    // Validate percentages sum to 100
+    const totalPercentage = recipients.reduce((sum, r) => sum + r.percentage, 0);
+    if (totalPercentage !== 100) {
+      throw new Error('Percentages must sum to 100');
+    }
+    
+    const distributions = recipients.map(recipient => ({
+      to: recipient.address,
+      amount: (parseFloat(totalAmount) * recipient.percentage / 100).toString(),
+    }));
+    
+    // Execute batch transfers
+    const results = await Promise.all(
+      distributions.map(dist => 
+        transferTokenRequest(address, dist.to, dist.amount, REVENUE_TOKEN_ADDRESS)
+      )
+    );
+    
+    return results.map(r => r.transactionHash);
+  };
+  
+  return { distributeRevenue };
+};
+```
+
+## Testing Strategies
+
+### Mock Web3 Provider for Testing
+
+```typescript
+// /src/lib/web3/__mocks__/provider.tsx
+export const MockRainbowKitProvider = ({ children }) => {
+  const mockWagmiConfig = {
+    chains: [mockChain],
+    connectors: [mockConnector],
+  };
+  
+  return (
+    <WagmiProvider config={mockWagmiConfig}>
+      <QueryClientProvider client={testQueryClient}>
+        <RKProvider>
+          {children}
+        </RKProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  );
+};
+```
+
+### Testing Transaction Flows
+
+```typescript
+// Example test for staking functionality
+describe('useStaking', () => {
+  it('should handle successful staking', async () => {
+    const mockResponse = {
+      body: { transactionHash: '0x123...' }
+    };
+    
+    jest.mocked(post).mockReturnValue({
+      send: jest.fn().mockResolvedValue(mockResponse)
+    });
+    
+    const { result } = renderHook(() => useStaking(), {
+      wrapper: MockRainbowKitProvider,
+    });
+    
+    const stakeResult = await result.current.stakeWithoutLock('0xpool...', '100');
+    
+    expect(stakeResult.success).toBe(true);
+    expect(stakeResult.hash).toBe('0x123...');
+  });
+  
+  it('should handle staking errors', async () => {
+    jest.mocked(post).mockImplementation(() => {
+      throw new Error('Network error');
+    });
+    
+    const { result } = renderHook(() => useStaking(), {
+      wrapper: MockRainbowKitProvider,
+    });
+    
+    const stakeResult = await result.current.stakeWithoutLock('0xpool...', '100');
+    
+    expect(stakeResult.success).toBe(false);
+    expect(stakeResult.error).toContain('Failed to stake tokens');
+  });
+});
+```
+
+### Integration Testing Pattern
+
+```typescript
+// Pattern for end-to-end Web3 integration tests
+const testWeb3Integration = async () => {
+  // 1. Connect wallet
+  await connectWallet('MetaMask');
+  expect(getConnectionStatus()).toBe(ConnectionStatus.Connected);
+  
+  // 2. Switch to correct network
+  await switchChain(1); // Mainnet
+  expect(getCurrentChain()).toBe(1);
+  
+  // 3. Execute transaction
+  const result = await transferTokens('0xrecipient...', '10');
+  expect(result.success).toBe(true);
+  expect(result.hash).toMatch(/^0x[a-fA-F0-9]{64}$/);
+  
+  // 4. Verify state updates
+  expect(getTransactionHistory()).toContain(result.hash);
+};
+```
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### 1. Wallet Connection Issues
+
+**Problem**: Wallet fails to connect or connection is lost
+```typescript
+// Debug connection issues
+const debugConnection = () => {
+  console.log('Web3 State:', {
+    status: store.getState().web3.status,
+    address: store.getState().web3.value.address,
+    chainId: store.getState().web3.value.chainId,
+    connectorId: store.getState().web3.value.connectorId,
+  });
+  
+  // Check if wallet is installed
+  if (!window.ethereum) {
+    console.error('No wallet detected. Please install MetaMask or another Web3 wallet.');
+    return;
+  }
+  
+  // Check network
+  window.ethereum.request({ method: 'eth_chainId' })
+    .then(chainId => console.log('Current chain:', parseInt(chainId, 16)))
+    .catch(console.error);
+};
+```
+
+**Solution**:
+- Ensure wallet extension is installed and unlocked
+- Check network configuration in `wagmi-config.ts`
+- Verify RPC endpoints are accessible
+- Clear browser cache and localStorage
+
+#### 2. Transaction Failures
+
+**Problem**: Transactions fail or remain pending
+```typescript
+// Debug transaction issues
+const debugTransaction = async (hash: string) => {
+  try {
+    const receipt = await publicClient.getTransactionReceipt({ hash });
+    console.log('Transaction receipt:', receipt);
+    
+    if (receipt.status === 'reverted') {
+      console.error('Transaction reverted. Check contract conditions.');
+    }
+  } catch (error) {
+    console.error('Transaction not found or still pending:', error);
+  }
+};
+```
+
+**Solutions**:
+- Check gas price and gas limit settings
+- Verify contract addresses and ABIs
+- Ensure sufficient token balance for gas fees
+- Check network congestion and adjust gas price
+
+#### 3. State Synchronization Issues
+
+**Problem**: UI state doesn't reflect blockchain state
+```typescript
+// Force refresh blockchain data
+const refreshWeb3State = () => {
+  // Invalidate all Web3-related queries
+  queryClient.invalidateQueries({ queryKey: ['balance'] });
+  queryClient.invalidateQueries({ queryKey: ['allowance'] });
+  queryClient.invalidateQueries({ queryKey: ['transactions'] });
+  
+  // Re-fetch wallet connection state
+  window.location.reload(); // Last resort
+};
+```
+
+**Solutions**:
+- Implement proper query invalidation after transactions
+- Use React Query's staleTime and cacheTime appropriately
+- Handle connection changes with event listeners
+- Implement retry logic for failed queries
+
+#### 4. Network Switching Issues
+
+**Problem**: Users can't switch networks or app doesn't recognize network changes
+```typescript
+// Handle network switching
+const handleNetworkSwitch = async (targetChainId: number) => {
+  try {
+    await window.ethereum.request({
+      method: 'wallet_switchEthereumChain',
+      params: [{ chainId: `0x${targetChainId.toString(16)}` }],
+    });
+  } catch (switchError: any) {
+    // Network doesn't exist, add it
+    if (switchError.code === 4902) {
+      await addCustomNetwork(targetChainId);
+    } else {
+      console.error('Failed to switch network:', switchError);
+    }
+  }
+};
+```
+
+### Performance Optimization
+
+#### 1. Query Optimization
+
+```typescript
+// Optimize blockchain queries with proper caching
+const useOptimizedBalance = (address: string, tokenAddress: string) => {
+  return useQuery({
+    queryKey: ['balance', address, tokenAddress],
+    queryFn: () => getTokenBalance(address, tokenAddress),
+    staleTime: 30 * 1000, // 30 seconds
+    cacheTime: 5 * 60 * 1000, // 5 minutes
+    refetchOnWindowFocus: false,
+    retry: 3,
+  });
+};
+```
+
+#### 2. Batch Operations
+
+```typescript
+// Batch multiple contract calls
+const useBatchedContractReads = (calls: ContractCall[]) => {
+  return useQuery({
+    queryKey: ['batchRead', calls],
+    queryFn: async () => {
+      const results = await multicall({
+        contracts: calls,
+      });
+      return results;
+    },
+    enabled: calls.length > 0,
+  });
+};
+```
+
+### Debugging Tools
+
+```typescript
+// Development debugging helpers
+if (process.env.NODE_ENV === 'development') {
+  // Expose Web3 debugging tools to window
+  window.debugWeb3 = {
+    getState: () => store.getState().web3,
+    getWagmiConfig,
+    queryClient,
+    refreshAllQueries: () => queryClient.invalidateQueries(),
+  };
+}
+```
+
+This comprehensive guide provides the foundation for building robust blockchain integrations in zOS. The patterns shown here emphasize security, user experience, and maintainability while supporting the creator economy features that Haven Protocol enables.
+
+For additional support, refer to the [Integration Guide](/opusdocs/integration-guide.md) for broader integration patterns, or consult the [Developer Reference](/opusdocs/developer-reference/) for specific component and hook documentation.
\ No newline at end of file
diff --git a/opusdocs/developer-reference/components.md b/opusdocs/developer-reference/components.md
new file mode 100644
index 00000000..748efa98
--- /dev/null
+++ b/opusdocs/developer-reference/components.md
@@ -0,0 +1,608 @@
+# zOS Component Library Reference
+
+This reference documents the key React components in zOS. All components are TypeScript-based and follow modern React patterns.
+
+## Avatar Component
+
+**Location:** `/src/components/avatar/index.tsx`
+
+A flexible avatar component that displays user profile images with fallback icons, status indicators, and badge support.
+
+### TypeScript Interface
+
+```typescript
+export interface AvatarProps {
+  imageURL?: string;
+  size: 'extra small' | 'small' | 'regular' | 'medium';
+  badgeContent?: string;
+  statusType?: 'active' | 'idle' | 'busy' | 'offline' | 'unread';
+  isActive?: boolean;
+  isRaised?: boolean;
+  tabIndex?: number;
+  isGroup?: boolean;
+}
+```
+
+### Basic Usage
+
+```tsx
+import { Avatar } from '@/components/avatar';
+
+// Simple avatar with image
+<Avatar
+  size="regular"
+  imageURL="https://example.com/avatar.jpg"
+/>
+
+// Avatar with status indicator
+<Avatar
+  size="regular"
+  imageURL="https://example.com/avatar.jpg"
+  statusType="active"
+/>
+
+// Group avatar with badge
+<Avatar
+  size="medium"
+  isGroup={true}
+  badgeContent="5"
+/>
+```
+
+### Advanced Usage
+
+```tsx
+// Interactive avatar with all features
+<Avatar
+  size="regular"
+  imageURL="https://example.com/avatar.jpg"
+  statusType="active"
+  badgeContent="3"
+  isActive={true}
+  isRaised={true}
+  tabIndex={0}
+/>
+
+// Fallback avatar (no image provided)
+<Avatar
+  size="regular"
+  statusType="offline"
+  isGroup={false}
+/>
+```
+
+### Features
+
+- **Image Loading:** Graceful fallback to default icons when image fails to load
+- **Status Indicators:** Visual status dots for online presence
+- **Badges:** Notification badges for unread counts
+- **Accessibility:** Proper tabIndex support for keyboard navigation
+- **Group Support:** Special styling and icons for group avatars
+- **Performance:** Memoized rendering for optimal performance
+
+### Size Chart
+
+| Size | Icon Size | Use Case |
+|------|-----------|----------|
+| extra small | 12px | Compact lists, mentions |
+| small | 16px | Message threads, notifications |
+| regular | 24px | Standard UI elements |
+| medium | 16px | Profile cards, headers |
+
+## Modal Component
+
+**Location:** `/src/components/modal/index.tsx`
+
+A flexible modal dialog component built on zUI with customizable actions and styling.
+
+### TypeScript Interface
+
+```typescript
+export interface Properties {
+  className?: string;
+  children?: React.ReactNode;
+  title: string;
+  primaryText?: string;
+  primaryVariant?: Variant;
+  primaryColor?: Color;
+  primaryDisabled?: boolean;
+  secondaryText?: string;
+  secondaryVariant?: Variant;
+  secondaryColor?: Color;
+  secondaryDisabled?: boolean;
+  isProcessing?: boolean;
+  onClose: () => void;
+  onPrimary?: () => void;
+  onSecondary?: () => void;
+}
+
+export enum Variant {
+  Primary = 'primary',
+  Secondary = 'secondary',
+}
+
+export enum Color {
+  Red = 'red',
+  Greyscale = 'greyscale',
+  Highlight = 'highlight',
+}
+```
+
+### Basic Usage
+
+```tsx
+import { Modal } from '@/components/modal';
+
+// Simple confirmation modal
+<Modal
+  title="Confirm Action"
+  primaryText="Confirm"
+  secondaryText="Cancel"
+  onClose={handleClose}
+  onPrimary={handleConfirm}
+  onSecondary={handleClose}
+>
+  <p>Are you sure you want to perform this action?</p>
+</Modal>
+```
+
+### Advanced Usage
+
+```tsx
+// Complex modal with custom styling and processing state
+<Modal
+  title="Delete Account"
+  className="danger-modal"
+  primaryText="Delete"
+  primaryColor={Color.Red}
+  primaryVariant={Variant.Primary}
+  secondaryText="Cancel"
+  secondaryColor={Color.Greyscale}
+  isProcessing={isDeleting}
+  primaryDisabled={!canDelete}
+  onClose={handleClose}
+  onPrimary={handleDelete}
+  onSecondary={handleClose}
+>
+  <div className="warning-content">
+    <h4>This action cannot be undone</h4>
+    <p>All your data will be permanently deleted.</p>
+    <input
+      type="text"
+      placeholder="Type 'DELETE' to confirm"
+      onChange={handleConfirmationInput}
+    />
+  </div>
+</Modal>
+```
+
+### Features
+
+- **Automatic Focus Management:** Built on Radix UI for accessibility
+- **Keyboard Navigation:** ESC to close, proper focus trapping
+- **Loading States:** Built-in processing indicators
+- **Flexible Actions:** Support for primary and secondary actions
+- **Custom Styling:** Full className and variant support
+- **Pointer Events Fix:** Handles Radix UI pointer event issues
+
+### Common Patterns
+
+```tsx
+// Information modal (no actions)
+<Modal title="Information" onClose={handleClose}>
+  <p>This is an informational message.</p>
+</Modal>
+
+// Processing modal
+<Modal
+  title="Saving Changes"
+  isProcessing={true}
+  primaryDisabled={true}
+  onClose={handleClose}
+>
+  <p>Please wait while we save your changes...</p>
+</Modal>
+```
+
+## Button Components
+
+### FollowButton Component
+
+**Location:** `/src/components/follow-button/index.tsx`
+
+An animated button for following/unfollowing users with loading states.
+
+#### TypeScript Interface
+
+```typescript
+interface FollowButtonProps {
+  targetUserId: string;
+  className?: string;
+}
+```
+
+#### Usage
+
+```tsx
+import { FollowButton } from '@/components/follow-button';
+
+// Basic follow button
+<FollowButton targetUserId="user123" />
+
+// With custom styling
+<FollowButton
+  targetUserId="user123"
+  className="custom-follow-btn"
+/>
+```
+
+#### Features
+
+- **Smooth Animations:** Framer Motion transitions
+- **Loading States:** Skeleton loading indicators
+- **Hover Effects:** Scale animation on hover
+- **State Management:** Integrated with follow/unfollow logic
+
+### Wallet Button Component
+
+**Location:** `/src/apps/wallet/components/button/button.tsx`
+
+A general-purpose button component for wallet-related actions.
+
+#### TypeScript Interface
+
+```typescript
+interface ButtonProps {
+  children: ReactNode;
+  icon?: ReactNode;
+  onClick: () => void;
+  disabled?: boolean;
+  variant?: 'primary' | 'secondary';
+}
+```
+
+#### Usage
+
+```tsx
+import { Button } from '@/apps/wallet/components/button/button';
+import { IconWallet } from '@zero-tech/zui/icons';
+
+// Basic button
+<Button onClick={handleClick}>
+  Connect Wallet
+</Button>
+
+// Button with icon
+<Button
+  onClick={handleConnect}
+  icon={<IconWallet />}
+  variant="primary"
+>
+  Connect Wallet
+</Button>
+
+// Disabled state
+<Button
+  onClick={handleClick}
+  disabled={isConnecting}
+  variant="secondary"
+>
+  {isConnecting ? 'Connecting...' : 'Connect'}
+</Button>
+```
+
+## ProfileCard Component
+
+**Location:** `/src/components/profile-card/index.tsx`
+
+A comprehensive user profile card with avatar, follow actions, and user statistics.
+
+### TypeScript Interface
+
+```typescript
+export interface ProfileCardProps {
+  userId: string;
+}
+```
+
+### Usage
+
+```tsx
+import { ProfileCard } from '@/components/profile-card';
+
+// Basic profile card
+<ProfileCard userId="user123" />
+```
+
+### Features
+
+- **Matrix Avatar Integration:** Uses MatrixAvatar component
+- **Follow/Unfollow Actions:** Integrated follow button
+- **Chat Integration:** Direct message button
+- **Zero Pro Badge:** Shows subscription status
+- **Follower/Following Counts:** Live statistics
+- **Loading States:** Skeleton text during data fetch
+- **Own Profile Detection:** Hides actions for current user
+
+### Integrated Components
+
+The ProfileCard uses several sub-components:
+- `MatrixAvatar` for profile images
+- `ZeroProBadge` for subscription indicators
+- `SkeletonText` for loading states
+- zUI `Button` and `IconButton` components
+
+## Tooltip Component
+
+**Location:** `/src/components/tooltip/index.tsx`
+
+A wrapper around rc-tooltip for consistent tooltip behavior across the app.
+
+### TypeScript Interface
+
+```typescript
+export interface Properties extends TooltipProps {
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import Tooltip from '@/components/tooltip';
+
+// Basic tooltip
+<Tooltip overlay="This is a tooltip">
+  <button>Hover me</button>
+</Tooltip>
+
+// Custom positioning
+<Tooltip
+  overlay="Custom tooltip"
+  placement="topLeft"
+  className="custom-tooltip"
+>
+  <div>Hover target</div>
+</Tooltip>
+```
+
+### Features
+
+- **Conditional Rendering:** Only shows when overlay content exists
+- **Custom Delays:** Optimized enter/leave delays
+- **Auto Cleanup:** Destroys tooltip on hide for performance
+- **Full rc-tooltip API:** Supports all rc-tooltip properties
+
+## Lightbox Component
+
+**Location:** `/src/components/lightbox/index.tsx`
+
+A full-screen image viewer with navigation, download, and copy functionality.
+
+### TypeScript Interface
+
+```typescript
+export interface LightboxProps {
+  items: Media[];
+  startingIndex?: number;
+  hasActions?: boolean;
+  onClose?: (e?: React.MouseEvent) => void;
+  provider: {
+    fitWithinBox: (media: any) => any;
+    getSource: (options: { src: string; options: any }) => string;
+  };
+}
+```
+
+### Usage
+
+```tsx
+import { Lightbox } from '@/components/lightbox';
+
+const mediaItems = [
+  { type: 'image', url: 'image1.jpg', name: 'Image 1' },
+  { type: 'image', url: 'image2.jpg', name: 'Image 2' },
+];
+
+// Basic lightbox
+<Lightbox
+  items={mediaItems}
+  onClose={handleClose}
+  provider={imageProvider}
+/>
+
+// Start at specific image
+<Lightbox
+  items={mediaItems}
+  startingIndex={1}
+  hasActions={true}
+  onClose={handleClose}
+  provider={imageProvider}
+/>
+```
+
+### Features
+
+- **Keyboard Navigation:** Arrow keys for navigation, ESC to close
+- **Image Actions:** Copy to clipboard, download functionality
+- **GIF Support:** Special handling for animated GIFs
+- **Responsive Design:** Adapts to different screen sizes
+- **Canvas Fallback:** Fallback copy method for compatibility
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| ← | Previous image |
+| → | Next image |
+| ESC | Close lightbox |
+
+## HoverCard Component
+
+**Location:** `/src/components/hover-card/index.tsx`
+
+A hover-triggered card component built on Radix UI primitives.
+
+### TypeScript Interface
+
+```typescript
+export interface ZeroProBadgeProps {
+  className?: string;
+  iconTrigger: React.ReactNode;
+  content: React.ReactNode;
+  onClick?: () => void;
+}
+```
+
+### Usage
+
+```tsx
+import { HoverCard } from '@/components/hover-card';
+
+// Basic hover card
+<HoverCard
+  iconTrigger={<IconInfo />}
+  content={<div>Additional information</div>}
+/>
+
+// With click handler
+<HoverCard
+  iconTrigger={<IconHelp />}
+  content={<div>Help content</div>}
+  onClick={handleHelpClick}
+  className="help-hover-card"
+/>
+```
+
+### Features
+
+- **Radix UI Integration:** Built on reliable primitives
+- **Click Support:** Optional click handling
+- **Portal Rendering:** Renders outside DOM hierarchy
+- **Customizable Delays:** Quick hover response
+- **Arrow Indicator:** Visual connection to trigger
+
+## LoadingScreen Component
+
+**Location:** `/src/components/loading-screen/index.tsx`
+
+A full-screen loading component with progress indication and contextual messages.
+
+### TypeScript Interface
+
+```typescript
+interface Properties {
+  progress: number;
+}
+```
+
+### Usage
+
+```tsx
+import { LoadingScreenContainer } from '@/components/loading-screen';
+
+// Connected to Redux state
+<LoadingScreenContainer />
+```
+
+### Features
+
+- **Progress Visualization:** Animated progress bar
+- **Contextual Messages:** Different messages based on progress
+- **Redux Integration:** Automatically connected to chat loading state
+- **Visual Polish:** Progress bar appears full at 90% for UX
+
+## ErrorBoundary Component
+
+**Location:** `/src/components/error-boundary/index.tsx`
+
+A Sentry-integrated error boundary for graceful error handling.
+
+### TypeScript Interface
+
+```typescript
+export interface Properties {
+  children: any;
+  boundary: string;
+}
+```
+
+### Usage
+
+```tsx
+import { ErrorBoundary } from '@/components/error-boundary';
+
+// Wrap components that might error
+<ErrorBoundary boundary="user-profile">
+  <UserProfileComponent />
+</ErrorBoundary>
+
+// App-level error boundary
+<ErrorBoundary boundary="main-app">
+  <App />
+</ErrorBoundary>
+```
+
+### Features
+
+- **Sentry Integration:** Automatic error reporting
+- **Context Tagging:** Application boundary and name tags
+- **Route Detection:** Automatic app detection from pathname
+- **Graceful Degradation:** Prevents entire app crashes
+
+## Performance Tips
+
+1. **Avatar Component:** Images are lazy-loaded with fallbacks
+2. **Modal Component:** Uses React.memo for re-render optimization
+3. **Lightbox Component:** Keyboard event cleanup prevents memory leaks
+4. **ProfileCard Component:** Skeleton loading improves perceived performance
+5. **All Components:** TypeScript provides compile-time optimization
+
+## Common Patterns
+
+### Loading States
+
+```tsx
+// Using skeleton loading
+<SkeletonText asyncText={{ text: userName, isLoading }} />
+
+// Using conditional rendering
+{isLoading ? <Skeleton /> : <ActualContent />}
+```
+
+### Error Handling
+
+```tsx
+// Wrap error-prone components
+<ErrorBoundary boundary="feature-name">
+  <FeatureComponent />
+</ErrorBoundary>
+```
+
+### Modal Patterns
+
+```tsx
+// Controlled modal state
+const [isOpen, setIsOpen] = useState(false);
+
+{isOpen && (
+  <Modal
+    title="Dialog Title"
+    onClose={() => setIsOpen(false)}
+    onPrimary={handleAction}
+  >
+    <ModalContent />
+  </Modal>
+)}
+```
+
+### Responsive Components
+
+```tsx
+// Using CSS modules with responsive classes
+<div className={`${styles.Container} ${isMobile ? styles.Mobile : ''}`}>
+  <ResponsiveContent />
+</div>
+```
+
+This reference covers the most commonly used components in the zOS application. Each component is designed with accessibility, performance, and developer experience in mind.
\ No newline at end of file
diff --git a/opusdocs/developer-reference/hooks.md b/opusdocs/developer-reference/hooks.md
new file mode 100644
index 00000000..9a59a115
--- /dev/null
+++ b/opusdocs/developer-reference/hooks.md
@@ -0,0 +1,522 @@
+# zOS Custom Hooks Reference
+
+This reference documents all custom React hooks available in zOS. These hooks provide powerful abstractions for common patterns and are essential for building features efficiently.
+
+## Table of Contents
+- [useMatrixMedia](#usematrixmedia) - Handle Matrix media with encryption
+- [useMatrixImage](#usematriximage) - Optimized image handling
+- [useDebounce](#usedebounce) - Debounce values and callbacks
+- [useLinkPreview](#uselinkpreview) - Generate link previews
+- [useScrollPosition](#usescrollposition) - Track scroll position
+- [usePrevious](#useprevious) - Access previous render values
+- [useUserWallets](#useuserwallets) - Manage user Web3 wallets
+- [useOwnedZids](#useownedzids) - Track user's Zer0 IDs
+
+---
+
+## useMatrixMedia
+
+Handles Matrix media content with automatic encryption/decryption and caching.
+
+### Import
+```typescript
+import { useMatrixMedia } from '@/lib/hooks/useMatrixMedia';
+```
+
+### Basic Usage
+```typescript
+function MediaDisplay({ media }) {
+  const { data: mediaUrl, isPending, isError } = useMatrixMedia({
+    url: media.url,
+    type: MediaType.Image,
+    name: media.name
+  });
+
+  if (isPending) return <LoadingSpinner />;
+  if (isError) return <ErrorIcon />;
+  
+  return <img src={mediaUrl} alt={media.name} />;
+}
+```
+
+### Advanced Usage - Encrypted Files
+```typescript
+function EncryptedDocument({ encryptedFile }) {
+  const { data: fileUrl, isPending } = useMatrixMedia({
+    file: {
+      url: encryptedFile.url,
+      key: encryptedFile.key,
+      iv: encryptedFile.iv,
+      hashes: encryptedFile.hashes
+    },
+    type: MediaType.File,
+    mimetype: 'application/pdf'
+  });
+
+  return fileUrl ? (
+    <a href={fileUrl} download>Download PDF</a>
+  ) : (
+    <span>Decrypting...</span>
+  );
+}
+```
+
+### Thumbnail Support
+```typescript
+function ImageThumbnail({ image }) {
+  const { data: thumbnailUrl } = useMatrixMedia(
+    { url: image.url, type: MediaType.Image },
+    { isThumbnail: true }
+  );
+  
+  return <img src={thumbnailUrl} className="thumbnail" />;
+}
+```
+
+### TypeScript Interface
+```typescript
+interface UseMatrixMediaOptions {
+  isThumbnail?: boolean;
+}
+
+interface Media {
+  url?: string;
+  file?: EncryptedFile;
+  type: MediaType;
+  name?: string;
+  mimetype?: string;
+  width?: number;
+  height?: number;
+}
+
+function useMatrixMedia(
+  media: Media | undefined,
+  options?: UseMatrixMediaOptions
+): {
+  data: string | null;
+  isPending: boolean;
+  isError: boolean;
+  error: Error | null;
+}
+```
+
+### Performance Tips
+- Cached for 24 hours automatically
+- Requests are deduplicated
+- Use thumbnails for large images
+- Handle loading states to prevent UI flicker
+
+---
+
+## useMatrixImage
+
+Specialized hook for Matrix images with optimized handling.
+
+### Import
+```typescript
+import { useMatrixImage } from '@/lib/hooks/useMatrixImage';
+```
+
+### Usage
+```typescript
+function UserAvatar({ user }) {
+  const imageUrl = useMatrixImage(user.avatarUrl);
+  
+  return (
+    <img 
+      src={imageUrl || '/default-avatar.png'} 
+      alt={user.name}
+      className="avatar"
+    />
+  );
+}
+```
+
+### With Size Options
+```typescript
+function ProfileBanner({ bannerUrl }) {
+  const imageUrl = useMatrixImage(bannerUrl, {
+    width: 1200,
+    height: 400,
+    method: 'scale'
+  });
+  
+  return <div style={{ backgroundImage: `url(${imageUrl})` }} />;
+}
+```
+
+### TypeScript Interface
+```typescript
+interface ImageOptions {
+  width?: number;
+  height?: number;
+  method?: 'crop' | 'scale';
+}
+
+function useMatrixImage(
+  mxcUrl: string | undefined,
+  options?: ImageOptions
+): string | null
+```
+
+---
+
+## useDebounce
+
+Debounces values or callbacks to limit update frequency.
+
+### Import
+```typescript
+import { useDebounce } from '@/lib/hooks/useDebounce';
+```
+
+### Debounce Values
+```typescript
+function SearchInput() {
+  const [search, setSearch] = useState('');
+  const debouncedSearch = useDebounce(search, 300);
+  
+  useEffect(() => {
+    if (debouncedSearch) {
+      // Perform search API call
+      searchAPI(debouncedSearch);
+    }
+  }, [debouncedSearch]);
+  
+  return (
+    <input
+      value={search}
+      onChange={(e) => setSearch(e.target.value)}
+      placeholder="Search..."
+    />
+  );
+}
+```
+
+### Debounce Callbacks
+```typescript
+function AutoSaveEditor({ onSave }) {
+  const [content, setContent] = useState('');
+  
+  const debouncedSave = useDebounce(() => {
+    onSave(content);
+  }, 1000);
+  
+  const handleChange = (newContent) => {
+    setContent(newContent);
+    debouncedSave();
+  };
+  
+  return <Editor value={content} onChange={handleChange} />;
+}
+```
+
+### TypeScript Interface
+```typescript
+function useDebounce<T>(value: T, delay: number): T
+```
+
+---
+
+## useLinkPreview
+
+Generates rich link previews for URLs.
+
+### Import
+```typescript
+import { useLinkPreview } from '@/lib/hooks/useLinkPreview';
+```
+
+### Usage
+```typescript
+function LinkCard({ url }) {
+  const { preview, loading, error } = useLinkPreview(url);
+  
+  if (loading) return <SkeletonCard />;
+  if (error || !preview) return <SimpleLink href={url} />;
+  
+  return (
+    <div className="link-preview">
+      <img src={preview.image} alt="" />
+      <div>
+        <h3>{preview.title}</h3>
+        <p>{preview.description}</p>
+        <span>{preview.site_name}</span>
+      </div>
+    </div>
+  );
+}
+```
+
+### TypeScript Interface
+```typescript
+interface LinkPreview {
+  title: string;
+  description: string;
+  image: string;
+  site_name: string;
+  url: string;
+}
+
+function useLinkPreview(url: string): {
+  preview: LinkPreview | null;
+  loading: boolean;
+  error: Error | null;
+}
+```
+
+---
+
+## useScrollPosition
+
+Tracks scroll position with performance optimization.
+
+### Import
+```typescript
+import { useScrollPosition } from '@/lib/hooks/useScrollPosition';
+```
+
+### Basic Usage
+```typescript
+function ScrollIndicator() {
+  const { scrollY, scrollDirection } = useScrollPosition();
+  
+  return (
+    <div className={`header ${scrollDirection === 'down' ? 'hidden' : ''}`}>
+      <div className="progress" style={{ width: `${scrollY}%` }} />
+    </div>
+  );
+}
+```
+
+### With Threshold
+```typescript
+function BackToTop() {
+  const { scrollY } = useScrollPosition({ threshold: 100 });
+  const showButton = scrollY > 300;
+  
+  return showButton ? (
+    <button onClick={() => window.scrollTo(0, 0)}>
+      Back to Top
+    </button>
+  ) : null;
+}
+```
+
+### TypeScript Interface
+```typescript
+interface ScrollPositionOptions {
+  threshold?: number;
+  delay?: number;
+}
+
+function useScrollPosition(options?: ScrollPositionOptions): {
+  scrollY: number;
+  scrollX: number;
+  scrollDirection: 'up' | 'down' | null;
+}
+```
+
+---
+
+## usePrevious
+
+Access the previous value of a prop or state.
+
+### Import
+```typescript
+import { usePrevious } from '@/lib/hooks/usePrevious';
+```
+
+### Usage
+```typescript
+function Counter({ count }) {
+  const prevCount = usePrevious(count);
+  
+  return (
+    <div>
+      <p>Current: {count}</p>
+      <p>Previous: {prevCount ?? 'N/A'}</p>
+      <p>Change: {count - (prevCount ?? 0)}</p>
+    </div>
+  );
+}
+```
+
+### Animation Example
+```typescript
+function AnimatedValue({ value }) {
+  const prevValue = usePrevious(value);
+  const isIncreasing = prevValue !== undefined && value > prevValue;
+  
+  return (
+    <span className={isIncreasing ? 'pulse-green' : 'pulse-red'}>
+      {value}
+    </span>
+  );
+}
+```
+
+### TypeScript Interface
+```typescript
+function usePrevious<T>(value: T): T | undefined
+```
+
+---
+
+## useUserWallets
+
+Manages user's Web3 wallets and addresses.
+
+### Import
+```typescript
+import { useUserWallets } from '@/lib/hooks/useUserWallets';
+```
+
+### Usage
+```typescript
+function WalletList() {
+  const { wallets, loading, primaryWallet } = useUserWallets();
+  
+  if (loading) return <LoadingSpinner />;
+  
+  return (
+    <div>
+      <h3>Your Wallets</h3>
+      {wallets.map(wallet => (
+        <WalletItem 
+          key={wallet.address}
+          wallet={wallet}
+          isPrimary={wallet.address === primaryWallet?.address}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+### TypeScript Interface
+```typescript
+interface Wallet {
+  address: string;
+  publicAddress: string;
+  type: 'metamask' | 'walletconnect' | 'coinbase';
+}
+
+function useUserWallets(): {
+  wallets: Wallet[];
+  primaryWallet: Wallet | null;
+  loading: boolean;
+  error: Error | null;
+}
+```
+
+---
+
+## useOwnedZids
+
+Tracks user's owned Zer0 IDs (zIDs).
+
+### Import
+```typescript
+import { useOwnedZids } from '@/lib/hooks/useOwnedZids';
+```
+
+### Usage
+```typescript
+function ZidSelector() {
+  const { zids, loading, activeZid, setActiveZid } = useOwnedZids();
+  
+  return (
+    <select 
+      value={activeZid?.id} 
+      onChange={(e) => setActiveZid(e.target.value)}
+      disabled={loading}
+    >
+      <option value="">Select a zID</option>
+      {zids.map(zid => (
+        <option key={zid.id} value={zid.id}>
+          {zid.name} ({zid.domain})
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### TypeScript Interface
+```typescript
+interface Zid {
+  id: string;
+  name: string;
+  domain: string;
+  owner: string;
+}
+
+function useOwnedZids(): {
+  zids: Zid[];
+  activeZid: Zid | null;
+  setActiveZid: (id: string) => void;
+  loading: boolean;
+  error: Error | null;
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Handle Loading States
+```typescript
+const { data, isPending } = useHook();
+if (isPending) return <LoadingComponent />;
+```
+
+### 2. Handle Errors Gracefully
+```typescript
+const { data, error } = useHook();
+if (error) return <ErrorFallback error={error} />;
+```
+
+### 3. Use TypeScript
+```typescript
+// Leverage type inference
+const result = useHook<ExpectedType>(params);
+```
+
+### 4. Memoize Dependencies
+```typescript
+const options = useMemo(() => ({
+  width: 200,
+  height: 200
+}), []);
+
+const result = useHook(url, options);
+```
+
+### 5. Clean Up Effects
+```typescript
+useEffect(() => {
+  const cleanup = hookWithCleanup();
+  return cleanup;
+}, []);
+```
+
+## Performance Considerations
+
+- **useDebounce**: Essential for search inputs and auto-save
+- **useScrollPosition**: Throttled by default for performance
+- **useMatrixMedia**: Caches results for 24 hours
+- **useLinkPreview**: Caches preview data to avoid repeated fetches
+
+## Integration Tips for Haven Protocol
+
+These hooks provide patterns that will be valuable for Haven Protocol:
+- **useMatrixMedia**: Handle encrypted artist media and NFT assets
+- **useLinkPreview**: Rich previews for artist portfolios
+- **useUserWallets**: Multi-wallet support for creators
+- **useDebounce**: Optimize real-time features in creator tools
+
+---
+
+*This documentation is part of the zOS developer reference. For contribution guidelines, see the [Contribution Guide](/opusdocs/new-recruits/contribution-guide.md).*
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/00-introduction.md b/opusdocs/hitchhiker/00-introduction.md
new file mode 100644
index 00000000..85b89e3a
--- /dev/null
+++ b/opusdocs/hitchhiker/00-introduction.md
@@ -0,0 +1,127 @@
+# The Hitchhiker's Guide to zOS
+*An Educational Journey Through Advanced Patterns for Young, Hungry Developers*
+
+---
+
+## Don't Panic
+
+In the beginning, React created components. This made a lot of developers happy and has been widely regarded as a good move. Then Redux came along, and with it, a whole universe of state management patterns, side effects, and architectural decisions that would make even Deep Thought pause for recalculation.
+
+You're about to embark on a journey through one of the most sophisticated web applications ever built - zOS. This isn't your typical todo app tutorial. This is the real deal: a production-grade, decentralized, Matrix-protocol-based social platform with Web3 integration that serves real users in the wild. Think of it as the Babel Fish of modern web development - it translates complex patterns into something your brain can actually understand.
+
+## Why This Guide Exists
+
+Every developer eventually reaches a point where basic tutorials feel like being told how to make toast when you're trying to understand molecular gastronomy. You want to see the real patterns, the clever solutions, the architectural decisions that separate the pros from the weekend warriors. You want to understand how to build something that scales to millions of users without falling apart at the first sign of complexity.
+
+zOS is that molecular gastronomy kitchen. It's where Redux-Saga-Normalizr patterns dance together in perfect harmony, where Matrix protocol events flow through carefully orchestrated sagas, where Web3 integrations happen seamlessly without turning your app into a gas fee nightmare. It's the application that answers the question: "How do you build something this sophisticated without losing your sanity?"
+
+## What You'll Learn
+
+By the time you finish this guide, you'll understand:
+
+- **The Redux-Saga-Normalizr Trinity**: Why these three technologies form the backbone of sophisticated applications and how they work together like a well-rehearsed orchestra
+- **Matrix Protocol Mastery**: How to build real-time, decentralized communication that would make the creators of The Matrix proud
+- **Web3 Without the Hype**: Practical blockchain integration patterns that actually solve real problems
+- **Performance at Scale**: The techniques that keep zOS running smoothly even when the universe throws chaos at it
+- **Testing the Untestable**: How to test complex async flows, real-time systems, and user interactions that span multiple dimensions of state
+
+## Your Journey Map
+
+### Chapter 1: Don't Panic - Introduction to the zOS Universe
+We'll start with the big picture - understanding the architecture, the philosophy, and why every decision was made the way it was. No hand-waving, no "it just works" - you'll understand the reasoning behind every architectural choice.
+
+### Chapter 2: The Redux Galaxy - Understanding State Management at Scale
+Dive deep into how Redux, Redux Toolkit, and normalized state work together to create a state management system that can handle anything the universe throws at it.
+
+### Chapter 3: Saga Odyssey - Async Patterns That Will Blow Your Mind
+Explore the world of Redux-Saga, where async operations are tamed, side effects are managed, and complex flows become as elegant as poetry.
+
+### Chapter 4: The Matrix Has You - Real-time Decentralized Communication
+Journey into the Matrix protocol integration, where messages flow in real-time, encryption happens automatically, and decentralization isn't just a buzzword.
+
+### Chapter 5: Web3 Wonderland - Blockchain Integration Without the Hype
+Learn how to integrate Web3 functionality that actually enhances user experience rather than creating barriers.
+
+### Chapter 6: Component Cosmos - Building Blocks of the Future
+Understand the component architecture that makes complex UIs manageable and reusable.
+
+### Chapter 7: Testing the Universe - How to Know Your Code Actually Works
+Master the testing strategies that give you confidence in systems so complex they make the Infinite Improbability Drive look predictable.
+
+### Chapter 8: The Developer's Towel - Essential Tools and Workflows
+Discover the tools, patterns, and workflows that keep developers productive and sane in a complex codebase.
+
+## Who This Guide Is For
+
+This guide is written for developers who:
+- Have mastered the basics of React and want to see how it's used in the real world
+- Understand Redux conceptually but want to see advanced patterns in action
+- Are curious about how modern, complex applications are actually built
+- Want to level up from tutorial projects to production-grade architecture
+- Appreciate a good metaphor and don't mind learning while laughing
+
+## What You Need to Know
+
+Before you begin, you should be comfortable with:
+- React hooks and component patterns
+- Basic Redux concepts (actions, reducers, store)
+- TypeScript (don't worry, we'll explain the advanced bits)
+- Modern JavaScript (async/await, destructuring, modules)
+- Git basics (for exploring the codebase)
+
+## How to Use This Guide
+
+Each chapter follows a consistent structure:
+
+1. **The Hook** - An engaging introduction that sets the stage
+2. **The Promise** - What you'll learn and why it matters
+3. **The Journey** - The main content with code examples and explanations
+4. **The Workshop** - Hands-on exercises to cement your understanding
+5. **The Portal** - Connection to the next chapter
+
+You can read this guide cover to cover, or jump to specific chapters based on your interests. Cross-references and "Deep Dive" sections let you explore topics at whatever depth suits your current needs.
+
+## A Note on Humor
+
+This guide takes inspiration from Douglas Adams' writing style - technical concepts explained with wit, wisdom, and the occasional absurdist observation. The humor isn't just for entertainment (though hopefully you'll be entertained). It's a learning aid. When you can laugh at complexity, you've begun to master it.
+
+Every joke, metaphor, and reference serves a purpose: to make difficult concepts memorable and approachable. If you find yourself smiling while learning, that's the point. The universe is already confusing enough without making documentation boring too.
+
+## Ready to Begin?
+
+Take a deep breath. Check that you have your towel (every good developer needs a good towel). Maybe grab a cup of coffee - you'll need the fuel for this journey.
+
+Remember: Don't panic. Every expert was once a beginner. Every complex system started as a simple idea. And every developer who has ever looked at a massive codebase and felt overwhelmed has been exactly where you are now.
+
+The only difference is that they had the courage to dive in and start exploring.
+
+Welcome to zOS. Welcome to the real world of advanced web development.
+
+The answer to the ultimate question of modern web architecture might not be 42, but by the end of this guide, you'll know exactly what the right questions are.
+
+---
+
+*"The Guide is definitive. Reality is frequently inaccurate." - Douglas Adams*
+
+*"But this guide about zOS is both definitive AND accurate. Mostly." - The Editors*
+
+---
+
+## Quick Navigation
+
+**Next Chapter**: [Chapter 1: Don't Panic - The zOS Universe](./chapters/01-dont-panic.md)
+
+**Jump to Topic**: 
+- [Redux Galaxy](./chapters/02-redux-galaxy.md) - State management patterns
+- [Saga Odyssey](./chapters/03-saga-odyssey.md) - Async flow control
+- [Matrix Integration](./chapters/04-matrix-has-you.md) - Real-time communication
+- [Web3 Wonderland](./chapters/05-web3-wonderland.md) - Blockchain integration
+- [Component Cosmos](./chapters/06-component-cosmos.md) - UI architecture
+- [Testing Universe](./chapters/07-testing-universe.md) - Quality assurance
+- [Developer's Towel](./chapters/08-developers-towel.md) - Tools and workflows
+
+**Resources**:
+- [Pattern Library](./patterns/) - Reusable code patterns
+- [Workshops](./workshops/) - Hands-on exercises
+- [Visual Diagrams](./diagrams/) - Architecture visualizations
+- [Quick Reference](./reference/) - Cheat sheets and glossary
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/chapters/02-redux-galaxy-integrated.md b/opusdocs/hitchhiker/chapters/02-redux-galaxy-integrated.md
new file mode 100644
index 00000000..b3424a96
--- /dev/null
+++ b/opusdocs/hitchhiker/chapters/02-redux-galaxy-integrated.md
@@ -0,0 +1,738 @@
+# Chapter 2: The Redux Galaxy - Understanding State Management at Scale
+*An Integrated Guide to Normalized State, Saga Orchestration, and Performance Mastery*
+
+*"In the beginning, Redux created the store. This made a lot of developers angry and has been widely regarded as a bad move. They were wrong."*
+
+---
+
+## Table of Contents
+1. [The Hook: A Cosmic Perspective on State](#the-hook-a-cosmic-perspective-on-state)
+2. [The Promise: What You'll Discover](#the-promise-what-youll-discover)
+3. [The Journey: Exploring the Redux Galaxy](#the-journey-exploring-the-redux-galaxy)
+4. [Visual Navigation: Redux Galaxy Patterns](#visual-navigation-redux-galaxy-patterns)
+5. [Hands-On Mastery: Workshop Challenges](#hands-on-mastery-workshop-challenges)
+6. [The Payoff: Understanding the Cosmic Architecture](#the-payoff-understanding-the-cosmic-architecture)
+7. [The Portal: What's Next](#the-portal-whats-next)
+
+---
+
+## The Hook: A Cosmic Perspective on State
+
+Picture this: You're an air traffic controller at the universe's busiest spaceport. Thousands of spaceships (actions) are arriving every second, each carrying precious cargo (data) that needs to be sorted, stored, and delivered to exactly the right destination. Some ships carry passengers (user data), others haul freight (API responses), and a few are carrying highly volatile materials (real-time events) that could explode if handled incorrectly.
+
+Now imagine trying to manage all of this with a clipboard and a walkie-talkie. That's what building a complex application feels like without proper state management. You'll lose cargo, crash ships, and probably cause an interdimensional incident that makes the Hitchhiker's Guide editors very unhappy.
+
+Welcome to the Redux Galaxy, where state management isn't just organized—it's orchestrated like a cosmic symphony that would make Deep Thought weep with algorithmic joy.
+
+---
+
+## The Promise: What You'll Discover
+
+By the end of this integrated journey, you'll understand how zOS creates a state management system so elegant and powerful that it handles millions of real-time events without breaking a sweat. You'll master:
+
+- **The Normalized Universe**: How zOS structures state to eliminate data duplication and enable lightning-fast lookups
+- **The Selector Constellation**: Advanced patterns for efficiently extracting and computing derived state  
+- **The Merge-First Methodology**: Why zOS chooses deep merging over replacement and how it prevents data loss
+- **The TypeScript Typing Galaxy**: How to maintain complete type safety across complex state relationships
+- **Saga Flow Orchestration**: Visual understanding of async patterns through interactive diagrams
+- **Performance Optimization**: Hands-on workshops that scale to millions of entities
+
+This isn't your typical Redux tutorial. This is the advanced course that shows you how to build state management that scales to real-world complexity, complete with visual guides and practical workshops.
+
+---
+
+## The Journey: Exploring the Redux Galaxy
+
+### 1. The Normalizr Nebula: Flattening the Universe
+
+Let's start with a fundamental truth that many developers learn the hard way: nested data is the enemy of performance. When your state looks like a Russian nesting doll, every update becomes an expensive operation that cascades through your entire component tree like a cosmic shockwave.
+
+zOS solves this with what we'll call the "Normalizr Nebula" - a sophisticated system that transforms deeply nested API responses into a flat, normalized structure that makes both computers and developers happy.
+
+#### 🎯 Visual Guide: Normalization Flow
+
+Before diving into code, let's visualize how this transformation works:
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                    NORMALIZATION UNIVERSE                       │
+│                                                                 │
+│  INPUT: Nested API Response                                     │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ {                                                   │       │
+│  │   channels: [{                                      │       │
+│  │     id: "room1",                                    │       │
+│  │     messages: [{                                    │       │
+│  │       id: "msg1",                                   │       │
+│  │       author: { id: "user1", name: "Alice" }       │       │
+│  │     }]                                              │       │
+│  │   }]                                                │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              NORMALIZER ENGINE                      │       │
+│  │                                                     │       │
+│  │  1. Schema Validation    ┌──────────────────┐      │       │
+│  │     - Check __denormalized flag             │      │       │
+│  │     - Prevent infinite loops                │      │       │
+│  │                                             │      │       │
+│  │  2. Entity Extraction    ┌──────────────────┐      │       │
+│  │     - Flatten nested objects               │      │       │
+│  │     - Create relationship tables          │      │       │
+│  │                                             │       │      │
+│  │  3. Reference Mapping    ┌──────────────────┐      │       │
+│  │     - Generate entity IDs                  │      │       │
+│  │     - Build lookup tables                 │      │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  OUTPUT: Normalized State                                       │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ entities: {                                         │       │
+│  │   users: {                                          │       │
+│  │     "user1": { id: "user1", name: "Alice" }        │       │
+│  │   },                                                │       │
+│  │   messages: {                                       │       │
+│  │     "msg1": { id: "msg1", author: "user1" }        │       │
+│  │   },                                                │       │
+│  │   channels: {                                       │       │
+│  │     "room1": { id: "room1", messages: ["msg1"] }   │       │
+│  │   }                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+*For a complete visual breakdown of normalization patterns, see [Redux Galaxy Visuals Guide](../diagrams/redux-galaxy-visuals.md)*
+
+#### The Problem: Nested Chaos
+
+Consider a typical chat application's state. Without normalization, it might look like this:
+
+```typescript
+// 😱 The Nested Nightmare
+interface BadChatState {
+  channels: {
+    id: string;
+    name: string;
+    messages: {
+      id: string;
+      content: string;
+      author: {
+        id: string;
+        name: string;
+        avatar: string;
+      };
+      replies: {
+        id: string;
+        content: string;
+        author: {
+          id: string;
+          name: string;
+          avatar: string;
+        };
+      }[];
+    }[];
+  }[];
+}
+```
+
+This structure is like a house of cards built during an earthquake. Update one user's name, and you need to hunt through every channel, every message, and every reply to make sure the change propagates. It's inefficient, error-prone, and makes developers cry into their coffee.
+
+#### The Solution: The Unified Normalization Engine
+
+zOS implements what the pattern library calls the "Unified Normalization Engine" - a sophisticated system that would make database architects proud:
+
+```typescript
+// 🌟 The Normalized Universe
+interface NormalizedState {
+  channels: Record<string, Channel>;
+  messages: Record<string, Message>;
+  users: Record<string, User>;
+  
+  // Relationship tables - like a cosmic phone book
+  channelMessages: Record<string, string[]>;
+  messageReplies: Record<string, string[]>;
+}
+```
+
+The magic happens in the `Normalizer` class, which acts like a cosmic customs officer, processing incoming data and ensuring everything ends up in the right place:
+
+```typescript
+// From the zOS pattern library - slightly simplified for clarity
+export class Normalizer {
+  private _schema: nSchema.Entity;
+  private _listSchema: Schema;
+
+  public normalize = (item) => {
+    // Like a cosmic dance, the normalizer handles both 
+    // individual items and entire fleets
+    if (Array.isArray(item)) {
+      return this.normalizeMany(item);
+    }
+    return this.normalizeSingle(item);
+  };
+
+  // 🛡️ The Safety Net: Prevents infinite loops from denormalized objects
+  private throwIfInvalid(items) {
+    items.forEach((item) => {
+      if (item.__denormalized) {
+        throw new Error(
+          'Tried to normalize an object that was previously denormalized from the store. ' +
+          'This is like trying to fold a towel that is already folded - it creates paradoxes.'
+        );
+      }
+    });
+  }
+}
+```
+
+#### 🧠 Quick Workshop: Normalize Your First Data Structure
+
+*Ready to practice? Let's build your understanding step by step.*
+
+**Challenge**: Design a normalized state structure for a simple blog application:
+
+```typescript
+// 🎯 EXERCISE: Complete this normalized structure
+interface BlogState {
+  // TODO: Create normalized entity tables
+  posts: Record<string, NormalizedPost>;
+  users: Record<string, NormalizedUser>;
+  comments: Record<string, NormalizedComment>;
+  
+  // TODO: Create relationship mappings
+  postComments: Record<string, string[]>; // postId -> commentIds[]
+  userPosts: Record<string, string[]>;     // userId -> postIds[]
+}
+
+// Define your normalized entities here:
+interface NormalizedPost {
+  id: string;
+  title: string;
+  content: string;
+  authorId: string;  // Reference, not nested object
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+*Solution and advanced patterns available in the [complete workshop guide](#hands-on-mastery-workshop-challenges)*
+
+#### The Genius: The `__denormalized` Flag
+
+One of the most clever patterns in zOS is the `__denormalized` flag. When you denormalize data (convert it back from the flat structure to nested objects for UI consumption), zOS marks it with this flag. If someone accidentally tries to normalize already-denormalized data, the system catches this and prevents infinite loops.
+
+It's like having a cosmic customs stamp that prevents smuggling data back through the same checkpoint twice. Brilliant in its simplicity, essential for stability.
+
+### 2. The Merge-First Update Strategy: Partial Updates in a Chaotic Universe
+
+Here's where zOS makes a decision that separates the pros from the amateurs. Instead of replacing entities wholesale, zOS implements a "merge-first" strategy that preserves data integrity during partial updates:
+
+#### 🎯 Visual Guide: Merge Strategy Flow
+
+```mermaid
+graph TD
+    A[Incoming Data] --> B{Data Type}
+    B -->|Full Entity| C[Deep Merge]
+    B -->|Partial Update| D[Smart Merge]
+    B -->|New Entity| E[Direct Insert]
+    
+    C --> F{Existing Data?}
+    D --> F
+    
+    F -->|Yes| G[Preserve Existing Fields]
+    F -->|No| H[Create New Record]
+    
+    G --> I[Merge New Fields]
+    I --> J[Update Reference Tables]
+    H --> J
+    E --> J
+    
+    J --> K[Validate Relationships]
+    K --> L[Commit to State]
+    
+    style A fill:#e3f2fd
+    style C fill:#e8f5e8
+    style D fill:#fff3e0
+    style G fill:#f1f8e9
+    style I fill:#e0f2f1
+```
+
+*For complete merge strategy diagrams, see [Redux Galaxy Visuals Guide](../diagrams/redux-galaxy-visuals.md)*
+
+```typescript
+// The Merge-First Methodology - from the zOS pattern library
+const receiveNormalized = (state, action: PayloadAction<any>) => {
+  const tableNames = Object.keys(action.payload);
+  const newState = { ...state };
+
+  for (const tableName of tableNames) {
+    const newTableState = action.payload[tableName];
+    const existingTableState = state[tableName] || {};
+    const mergedTableState = { ...existingTableState };
+
+    // 🪄 Deep merge each entity - like cosmic healing
+    for (const entityId of Object.keys(newTableState)) {
+      mergedTableState[entityId] = {
+        ...existingTableState[entityId],
+        ...newTableState[entityId],
+      };
+    }
+    newState[tableName] = mergedTableState;
+  }
+  return newState;
+};
+```
+
+#### Why Merge Instead of Replace?
+
+Imagine you have a user entity with 20 properties, but an API endpoint only returns 3 of them. With a replacement strategy, you'd lose the other 17 properties. With merge-first, you keep everything and only update what's new.
+
+This becomes critical in real-time applications where different data sources provide partial information about the same entities. A message might arrive with just content and timestamp, while user presence updates provide activity status. The merge-first strategy ensures no data is lost in the cosmic shuffle.
+
+### 3. The Selector Constellation: Navigating the Data Universe
+
+Raw normalized state is like having all the books in the universe organized by ISBN - incredibly efficient for storage, but not very useful for actually reading. You need selectors to transform this flat universe back into the shaped data your components need.
+
+zOS implements what we'll call the "Selector Constellation" - a network of interconnected selectors that work together to efficiently compute derived state:
+
+#### 🎯 Visual Guide: Selector Architecture
+
+```mermaid
+graph TD
+    A[makeGetEntityById Factory] --> B[Create Selector Instance]
+    B --> C[Memoization Cache]
+    
+    D[Input: State + ID] --> B
+    E[Reselect Library] --> C
+    
+    C --> F{Cache Hit?}
+    F -->|Yes| G[Return Cached Result]
+    F -->|No| H[Compute New Result]
+    
+    H --> I[Extract Entity]
+    I --> J[Transform Data]
+    J --> K[Cache Result]
+    K --> L[Return Result]
+    
+    subgraph "Performance Optimization"
+        M[Stable References]
+        N[Shallow Equality]
+        O[Instance Isolation]
+    end
+    
+    C --> M
+    G --> N
+    B --> O
+    
+    style A fill:#e3f2fd
+    style C fill:#e8f5e8
+    style F fill:#fff3e0
+    style M fill:#f3e5f5
+    style N fill:#f3e5f5
+    style O fill:#f3e5f5
+```
+
+*For complete selector constellation patterns, see [Redux Galaxy Visuals Guide](../diagrams/redux-galaxy-visuals.md)*
+
+#### Basic Selectors: The Foundation Stars
+
+```typescript
+// Basic entity selectors - the building blocks of the constellation
+export const channelSelector = (channelId: string) => (state: RootState): Channel | null => {
+  return state.normalized.channels[channelId] || null;
+};
+
+export const messageSelector = (messageId: string) => (state: RootState): Message | null => {
+  return state.normalized.messages[messageId] || null;
+};
+```
+
+#### Memoized Selector Factories: The Performance Supernovas
+
+The real magic happens with memoized selector factories. These create reusable, performance-optimized selectors that prevent unnecessary recalculations:
+
+```typescript
+// The Memoized Selector Factory Pattern - cosmic performance optimization
+export const makeGetChannelById = () => {
+  return createSelector(
+    [
+      (state: RootState) => state.normalized.channels, 
+      (_state: RootState, channelId: string) => channelId
+    ],
+    (allChannels, channelId) => {
+      if (!allChannels || !channelId) return null;
+      return allChannels[channelId] as NormalizedChannel | null;
+    }
+  );
+};
+
+// Usage in hooks - creating stable selector instances
+export const useChannelSelector = (id: string) => {
+  const selectChannelByIdInstance = useMemo(() => makeGetChannelById(), []);
+  const channelSelector = useCallback(
+    (state: RootState) => selectChannelByIdInstance(state, id),
+    [selectChannelByIdInstance, id]
+  );
+  return useSelector(channelSelector);
+};
+```
+
+#### 🧠 Interactive Workshop: Build Advanced Selectors
+
+*Let's put your understanding to the test with increasingly complex scenarios.*
+
+**Challenge**: Create a memoized selector factory for retrieving posts with their author information:
+
+```typescript
+// 🎯 INTERMEDIATE CHALLENGE
+export const makeGetPostWithAuthor = () => {
+  return createSelector(
+    [
+      // TODO: Add input selectors here
+      // HINT: You need the post, the author, and potentially comment count
+    ],
+    (post, author, commentCount) => {
+      // TODO: Return enriched post object with author nested
+      // TODO: Handle cases where author might not exist
+      // TODO: Include computed engagement metrics
+    }
+  );
+};
+```
+
+*Complete solution and advanced challenges in the [workshop section](#hands-on-mastery-workshop-challenges)*
+
+### 4. Saga Flow Orchestration: The Async Symphony
+
+While selectors handle data retrieval, Redux-Saga orchestrates the complex async flows that keep your normalized universe in sync. Let's visualize how these flows work:
+
+#### 🎯 Visual Guide: Message Send Flow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Component
+    participant S as Saga
+    participant N as Normalizer
+    participant A as API
+    participant R as Store
+
+    U->>C: Types message & hits send
+    C->>R: dispatch(sendMessage)
+    
+    Note over R: Optimistic Update
+    R->>C: Show pending message
+    
+    R->>S: Saga intercepts action
+    S->>N: Create optimistic entity
+    N->>R: Update normalized state
+    
+    S->>A: POST /messages
+    
+    alt Success Path
+        A->>S: 200 + message data
+        S->>N: Normalize response
+        N->>R: Merge final state
+        R->>C: Update UI with real data
+    else Error Path
+        A->>S: Error response
+        S->>R: Remove optimistic update
+        S->>R: dispatch(showError)
+        R->>C: Show error state
+    end
+    
+    C->>U: Updated message list
+```
+
+*For complete saga flow diagrams including authentication, file uploads, and error handling, see [Redux-Saga Flow Diagrams](../diagrams/redux-saga-flows.md)*
+
+#### The Optimistic Update Pattern
+
+One of the most sophisticated patterns in zOS is optimistic updates. When a user sends a message, the UI immediately shows it as "sending" while the API call happens in the background:
+
+```typescript
+// Optimistic update with rollback capability
+export const sendMessageOptimistically = (
+  state: ChatState,
+  message: Omit<NormalizedMessage, 'id' | 'timestamp' | 'syncStatus' | 'version'>
+): ChatState => {
+  const optimisticId = `optimistic_${Date.now()}_${Math.random()}`;
+  const timestamp = Date.now();
+  
+  const optimisticMessage: NormalizedMessage = {
+    ...message,
+    id: optimisticId,
+    timestamp,
+    syncStatus: 'pending',
+    version: 1,
+    optimisticId
+  };
+  
+  return {
+    ...state,
+    messages: {
+      ...state.messages,
+      [optimisticId]: optimisticMessage
+    },
+    channelMessages: {
+      ...state.channelMessages,
+      [message.channelId]: [
+        ...(state.channelMessages[message.channelId] || []),
+        optimisticId
+      ]
+    },
+    messagesPendingSync: {
+      ...state.messagesPendingSync,
+      [optimisticId]: optimisticMessage
+    }
+  };
+};
+```
+
+#### 🧠 Advanced Workshop: Real-Time Sync System
+
+*Ready for the ultimate challenge? Build a production-ready real-time chat system.*
+
+**Advanced Challenge**: Implement optimistic updates with conflict resolution for a collaborative editing system:
+
+```typescript
+// 🎯 EXPERT LEVEL CHALLENGE
+export const resolveMessageConflict = (
+  localMessage: NormalizedMessage,
+  serverMessage: NormalizedMessage
+): { resolved: NormalizedMessage; strategy: 'local' | 'server' | 'merge' } => {
+  // TODO: Implement sophisticated conflict resolution
+  // Consider: version numbers, edit timestamps, user permissions
+  // Handle: content conflicts, reaction conflicts, metadata conflicts
+};
+```
+
+*Complete implementation and testing strategies in the [advanced workshop](#hands-on-mastery-workshop-challenges)*
+
+---
+
+## Visual Navigation: Redux Galaxy Patterns
+
+Throughout this journey, we've used visual guides to illuminate complex concepts. Here's your complete visual reference for mastering Redux Galaxy patterns:
+
+### Core Architecture Diagrams
+
+**🗺️ Complete State Architecture**
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                        DATA FLOW COSMOS                         │
+│                                                                 │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
+│  │   UI LAYER  │    │ SAGA LAYER  │    │ API LAYER   │         │
+│  │─────────────│    │─────────────│    │─────────────│         │
+│  │ Components  │───▶│ Watchers    │───▶│ HTTP Calls  │         │
+│  │ Hooks       │    │ Workers     │    │ WebSockets  │         │
+│  │ Selectors   │◄───│ Effects     │◄───│ Responses   │         │
+│  └─────────────┘    └─────────────┘    └─────────────┘         │
+│          │                  │                  │               │
+│          ▼                  ▼                  ▼               │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
+│  │   ACTIONS   │    │ NORMALIZER  │    │   CACHE     │         │
+│  │─────────────│    │─────────────│    │─────────────│         │
+│  │ User Events │───▶│ Schema Val. │───▶│ Entity Store│         │
+│  │ API Events  │    │ Entity Ext. │    │ Relationships        │
+│  │ System Evts │    │ Ref Mapping │    │ Indexes     │         │
+│  └─────────────┘    └─────────────┘    └─────────────┘         │
+│          │                  │                  │               │
+│          └──────────────────┼──────────────────┘               │
+│                             ▼                                  │
+│                    ┌─────────────┐                             │
+│                    │   REDUCER   │                             │
+│                    │─────────────│                             │
+│                    │ Merge Logic │                             │
+│                    │ State Trees │                             │
+│                    │ Immutability│                             │
+│                    └─────────────┘                             │
+│                             │                                  │
+│                             ▼                                  │
+│                    ┌─────────────┐                             │
+│                    │   STORE     │                             │
+│                    │─────────────│                             │
+│                    │ Normalized  │                             │
+│                    │ Subscriptions                            │
+│                    │ DevTools    │                             │
+│                    └─────────────┘                             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Interactive Flow References
+
+For hands-on exploration of these patterns:
+
+- 📊 **[Complete Visual Guide](../diagrams/redux-galaxy-visuals.md)** - All architecture diagrams with interactive elements
+- 🔀 **[Saga Flow Diagrams](../diagrams/redux-saga-flows.md)** - Step-by-step async flow visualization  
+- 🎯 **[Performance Patterns](../diagrams/redux-galaxy-visuals.md#performance-optimization-flows)** - Optimization strategies visualized
+
+---
+
+## Hands-On Mastery: Workshop Challenges
+
+Theory becomes mastery through practice. The Redux Galaxy workshops are designed as a progressive skill-building journey:
+
+### 🟢 Towel Level: "Don't Panic About Normalization"
+*Duration: 1-2 hours | Focus: Core concepts*
+
+Build your first normalized store with basic selectors and updates. Perfect for developers new to advanced Redux patterns.
+
+**Key Learning**: Understand why normalization matters and how to implement basic normalized schemas.
+
+### 🟡 Babel Fish: "Advanced Selector Orchestration"  
+*Duration: 2-3 hours | Focus: Performance optimization*
+
+Create a high-performance social media feed that demonstrates advanced selector patterns. Learn memoization, instance isolation, and complex derived state.
+
+**Key Learning**: Master performance-optimized data access patterns that scale to thousands of entities.
+
+### 🟠 Improbability Drive: "Real-Time Normalized Synchronization"
+*Duration: 3-4 hours | Focus: Production patterns*
+
+Implement a production-ready real-time chat system with optimistic updates, conflict resolution, and advanced error handling.
+
+**Key Learning**: Build systems that handle real-world complexity with data consistency guarantees.
+
+### 🔴 Deep Thought: "Architecting the Ultimate State Machine"
+*Duration: 4-6 hours | Focus: System architecture*
+
+Design and implement a complete multi-tenant collaboration platform with operational transforms, offline support, and enterprise-scale performance.
+
+**Key Learning**: Create production-grade state management systems suitable for real SaaS applications.
+
+### 🚀 Workshop Quick Start
+
+Ready to begin? Choose your path:
+
+```typescript
+// 🎯 Start with the basics
+interface BlogState {
+  posts: Record<string, NormalizedPost>;
+  users: Record<string, NormalizedUser>;
+  // Your normalized structure here
+}
+
+// 🎯 Or jump to advanced patterns
+export const makeSelectUserFeed = () => {
+  return createSelector([
+    // Complex selector composition challenge
+  ], (/* inputs */) => {
+    // Your advanced implementation here
+  });
+};
+
+// 🎯 Or tackle the ultimate challenge
+class OperationalTransform {
+  public transform(op1: Operation, op2: Operation): [Operation, Operation] {
+    // Production-grade operational transform implementation
+  }
+}
+```
+
+**📚 [Complete Workshop Guide →](../workshops/redux-galaxy-workshops.md)**
+
+Every workshop includes:
+- ✅ Step-by-step challenges with increasing complexity
+- ✅ Complete solutions with detailed explanations  
+- ✅ Performance testing and validation
+- ✅ Extension challenges for deeper mastery
+- ✅ Real-world application examples
+
+---
+
+## The Payoff: Understanding the Cosmic Architecture
+
+If you've made it this far, you now understand something that many developers never grasp: how to build state management that scales to real-world complexity. You've seen how zOS:
+
+1. **Normalizes ruthlessly** to eliminate data duplication and enable efficient updates
+2. **Memoizes religiously** to prevent unnecessary recalculations and re-renders
+3. **Merges carefully** to preserve data integrity during partial updates
+4. **Types completely** to catch errors before they reach production
+5. **Orchestrates elegantly** to handle complex async flows with grace
+6. **Visualizes clearly** to make complex patterns understandable and debuggable
+
+These aren't just clever programming tricks - they're architectural decisions that enable zOS to handle millions of real-time events without breaking a sweat.
+
+### The Integration Mastery Checklist
+
+✅ **Conceptual Understanding**: Can explain normalization benefits and trade-offs  
+✅ **Implementation Skills**: Can build normalized schemas with proper relationships  
+✅ **Performance Mastery**: Can create memoized selectors that scale to millions of entities  
+✅ **Visual Fluency**: Can read and create diagrams of complex Redux flows  
+✅ **Practical Application**: Can implement optimistic updates with error handling  
+✅ **System Architecture**: Can design production-grade state management systems
+
+### Performance Benchmarks You Should Hit
+
+After mastering these patterns, your implementations should achieve:
+
+- 🚀 **Sub-100ms selector performance** with 10,000+ entities
+- 🚀 **Stable component references** preventing unnecessary re-renders  
+- 🚀 **Efficient state updates** through merge-first strategies
+- 🚀 **Type-safe operations** with zero runtime type errors
+- 🚀 **Graceful error handling** with automatic recovery patterns
+
+---
+
+## The Portal: What's Next
+
+The Redux Galaxy is vast and beautiful, but it's just the foundation. In our next chapter, "Saga Odyssey," we'll explore how zOS manages the complex async flows that make this normalized universe dance in perfect harmony.
+
+You'll discover:
+
+🔮 **Advanced Saga Patterns**: How Redux-Saga transforms chaotic side effects into elegant orchestrations  
+🔮 **Optimistic Update Mastery**: Build async patterns so sophisticated they make other developers question their life choices  
+🔮 **Real-Time Synchronization**: Handle millions of concurrent events without losing a single message  
+🔮 **Error Recovery Systems**: Build fault-tolerant systems that recover gracefully from any failure  
+
+The universe of advanced patterns is vast and full of wonders. Pack your towel - we're going deeper.
+
+---
+
+## Quick Reference: Redux Galaxy Mastery
+
+### Essential Patterns
+- **Normalized State**: Flat entity storage for efficient updates
+- **Memoized Selectors**: Cached computations with stable references  
+- **Merge-First Updates**: Preserve data during partial updates
+- **Instance Isolation**: Each component gets its own selector instance
+- **Optimistic Updates**: Immediate UI feedback with rollback capability
+
+### Performance Tips
+- Use `makeGetEntityById()` factories for memoized selectors
+- Prefer normalized selectors over denormalized ones
+- Create selector instances in useMemo, not on every render
+- Implement batched updates for high-frequency events
+- Document expensive selectors to guide other developers
+
+### Common Gotchas
+- Don't normalize already denormalized data (watch for `__denormalized` flags)
+- Don't create new selector instances on every render
+- Don't denormalize unless you absolutely need nested structure
+- Don't forget to handle null/undefined cases in selectors
+- Don't skip conflict resolution in real-time systems
+
+### Integration Resources
+
+- 📊 **[Visual Guide](../diagrams/redux-galaxy-visuals.md)**: Complete architecture diagrams
+- 🔀 **[Saga Flows](../diagrams/redux-saga-flows.md)**: Step-by-step async patterns
+- 🧪 **[Workshop Challenges](../workshops/redux-galaxy-workshops.md)**: Hands-on skill building
+- 📖 **[Glossary](../../shared/glossary.md)**: Technical term definitions
+- 🎯 **[Pattern Library](../../shared/pattern-library.md)**: Reusable implementation patterns
+
+---
+
+*"In space, no one can hear you console.log. But in the Redux Galaxy, every state update is observable, every selector is memoized, and every entity has its place in the normalized universe."*
+
+---
+
+**Previous Chapter**: [Chapter 1: Don't Panic](./01-dont-panic.md)  
+**Next Chapter**: [Chapter 3: Saga Odyssey](./03-saga-odyssey.md)  
+**Complete Workshop Guide**: [Redux Galaxy Workshops](../workshops/redux-galaxy-workshops.md)  
+**Visual Reference**: [Redux Galaxy Diagrams](../diagrams/redux-galaxy-visuals.md)
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/chapters/02-redux-galaxy.md b/opusdocs/hitchhiker/chapters/02-redux-galaxy.md
new file mode 100644
index 00000000..e19f9530
--- /dev/null
+++ b/opusdocs/hitchhiker/chapters/02-redux-galaxy.md
@@ -0,0 +1,410 @@
+# Chapter 2: The Redux Galaxy - Understanding State Management at Scale
+
+*"In the beginning, Redux created the store. This made a lot of developers angry and has been widely regarded as a bad move. They were wrong."*
+
+---
+
+## The Hook: A Cosmic Perspective on State
+
+Picture this: You're an air traffic controller at the universe's busiest spaceport. Thousands of spaceships (actions) are arriving every second, each carrying precious cargo (data) that needs to be sorted, stored, and delivered to exactly the right destination. Some ships carry passengers (user data), others haul freight (API responses), and a few are carrying highly volatile materials (real-time events) that could explode if handled incorrectly.
+
+Now imagine trying to manage all of this with a clipboard and a walkie-talkie. That's what building a complex application feels like without proper state management. You'll lose cargo, crash ships, and probably cause an interdimensional incident that makes the Hitchhiker's Guide editors very unhappy.
+
+Welcome to the Redux Galaxy, where state management isn't just organized—it's orchestrated like a cosmic symphony that would make Deep Thought weep with algorithmic joy.
+
+## The Promise: What You'll Discover
+
+By the end of this chapter, you'll understand how zOS creates a state management system so elegant and powerful that it handles millions of real-time events without breaking a sweat. You'll learn:
+
+- **The Normalized Universe**: How zOS structures state to eliminate data duplication and enable lightning-fast lookups
+- **The Selector Constellation**: Advanced patterns for efficiently extracting and computing derived state
+- **The Merge-First Methodology**: Why zOS chooses deep merging over replacement and how it prevents data loss
+- **The TypeScript Typing Galaxy**: How to maintain complete type safety across complex state relationships
+
+This isn't your typical Redux tutorial. This is the advanced course that shows you how to build state management that scales to real-world complexity.
+
+## The Journey: Exploring the Redux Galaxy
+
+### 1. The Normalizr Nebula: Flattening the Universe
+
+Let's start with a fundamental truth that many developers learn the hard way: nested data is the enemy of performance. When your state looks like a Russian nesting doll, every update becomes an expensive operation that cascades through your entire component tree like a cosmic shockwave.
+
+zOS solves this with what we'll call the "Normalizr Nebula" - a sophisticated system that transforms deeply nested API responses into a flat, normalized structure that makes both computers and developers happy.
+
+#### The Problem: Nested Chaos
+
+Consider a typical chat application's state. Without normalization, it might look like this:
+
+```typescript
+// 😱 The Nested Nightmare
+interface BadChatState {
+  channels: {
+    id: string;
+    name: string;
+    messages: {
+      id: string;
+      content: string;
+      author: {
+        id: string;
+        name: string;
+        avatar: string;
+      };
+      replies: {
+        id: string;
+        content: string;
+        author: {
+          id: string;
+          name: string;
+          avatar: string;
+        };
+      }[];
+    }[];
+  }[];
+}
+```
+
+This structure is like a house of cards built during an earthquake. Update one user's name, and you need to hunt through every channel, every message, and every reply to make sure the change propagates. It's inefficient, error-prone, and makes developers cry into their coffee.
+
+#### The Solution: The Unified Normalization Engine
+
+zOS implements what the pattern library calls the "Unified Normalization Engine" - a sophisticated system that would make database architects proud:
+
+```typescript
+// 🌟 The Normalized Universe
+interface NormalizedState {
+  channels: Record<string, Channel>;
+  messages: Record<string, Message>;
+  users: Record<string, User>;
+  
+  // Relationship tables - like a cosmic phone book
+  channelMessages: Record<string, string[]>;
+  messageReplies: Record<string, string[]>;
+}
+```
+
+The magic happens in the `Normalizer` class, which acts like a cosmic customs officer, processing incoming data and ensuring everything ends up in the right place:
+
+```typescript
+// From the zOS pattern library - slightly simplified for clarity
+export class Normalizer {
+  private _schema: nSchema.Entity;
+  private _listSchema: Schema;
+
+  public normalize = (item) => {
+    // Like a cosmic dance, the normalizer handles both 
+    // individual items and entire fleets
+    if (Array.isArray(item)) {
+      return this.normalizeMany(item);
+    }
+    return this.normalizeSingle(item);
+  };
+
+  // 🛡️ The Safety Net: Prevents infinite loops from denormalized objects
+  private throwIfInvalid(items) {
+    items.forEach((item) => {
+      if (item.__denormalized) {
+        throw new Error(
+          'Tried to normalize an object that was previously denormalized from the store. ' +
+          'This is like trying to fold a towel that is already folded - it creates paradoxes.'
+        );
+      }
+    });
+  }
+}
+```
+
+#### The Genius: The `__denormalized` Flag
+
+One of the most clever patterns in zOS is the `__denormalized` flag. When you denormalize data (convert it back from the flat structure to nested objects for UI consumption), zOS marks it with this flag. If someone accidentally tries to normalize already-denormalized data, the system catches this and prevents infinite loops.
+
+It's like having a cosmic customs stamp that prevents smuggling data back through the same checkpoint twice. Brilliant in its simplicity, essential for stability.
+
+### 2. The Dynamic Schema Factory: Building Universes on Demand
+
+Creating normalized slices by hand is like hand-crafting each spaceship when you need to build a fleet. zOS automates this with the "Dynamic Schema Factory" pattern:
+
+```typescript
+// The Factory Pattern: Creating consistent normalized slices
+public createNormalizedListSlice = (config: NormalizedListSliceConfig) => {
+  const normalizer = new Normalizer(config.schema);
+  const receive = createNormalizedReceiveAction(config.name, normalizer.normalize);
+
+  return {
+    actions: { ...listSlice.actions, receive },
+    reducer: listSlice.reducer,
+    normalize: normalizer.normalize,
+    denormalize: normalizer.denormalize,
+  };
+};
+```
+
+This factory is like having a spaceship manufacturing plant that produces consistently designed vessels, each equipped with:
+- **Standardized Actions**: Every slice gets the same set of actions
+- **Type-Safe Receivers**: Actions that automatically handle normalization
+- **Bound Methods**: Pre-configured normalize and denormalize functions
+- **Redux Toolkit Integration**: Seamless compatibility with modern Redux patterns
+
+### 3. The Merge-First Update Strategy: Partial Updates in a Chaotic Universe
+
+Here's where zOS makes a decision that separates the pros from the amateurs. Instead of replacing entities wholesale, zOS implements a "merge-first" strategy that preserves data integrity during partial updates:
+
+```typescript
+// The Merge-First Methodology - from the zOS pattern library
+const receiveNormalized = (state, action: PayloadAction<any>) => {
+  const tableNames = Object.keys(action.payload);
+  const newState = { ...state };
+
+  for (const tableName of tableNames) {
+    const newTableState = action.payload[tableName];
+    const existingTableState = state[tableName] || {};
+    const mergedTableState = { ...existingTableState };
+
+    // 🪄 Deep merge each entity - like cosmic healing
+    for (const entityId of Object.keys(newTableState)) {
+      mergedTableState[entityId] = {
+        ...existingTableState[entityId],
+        ...newTableState[entityId],
+      };
+    }
+    newState[tableName] = mergedTableState;
+  }
+  return newState;
+};
+```
+
+#### Why Merge Instead of Replace?
+
+Imagine you have a user entity with 20 properties, but an API endpoint only returns 3 of them. With a replacement strategy, you'd lose the other 17 properties. With merge-first, you keep everything and only update what's new.
+
+This becomes critical in real-time applications where different data sources provide partial information about the same entities. A message might arrive with just content and timestamp, while user presence updates provide activity status. The merge-first strategy ensures no data is lost in the cosmic shuffle.
+
+### 4. The Selector Constellation: Navigating the Data Universe
+
+Raw normalized state is like having all the books in the universe organized by ISBN - incredibly efficient for storage, but not very useful for actually reading. You need selectors to transform this flat universe back into the shaped data your components need.
+
+zOS implements what we'll call the "Selector Constellation" - a network of interconnected selectors that work together to efficiently compute derived state:
+
+#### Basic Selectors: The Foundation Stars
+
+```typescript
+// Basic entity selectors - the building blocks of the constellation
+export const channelSelector = (channelId: string) => (state: RootState): Channel | null => {
+  return state.normalized.channels[channelId] || null;
+};
+
+export const messageSelector = (messageId: string) => (state: RootState): Message | null => {
+  return state.normalized.messages[messageId] || null;
+};
+```
+
+#### Memoized Selector Factories: The Performance Supernovas
+
+The real magic happens with memoized selector factories. These create reusable, performance-optimized selectors that prevent unnecessary recalculations:
+
+```typescript
+// The Memoized Selector Factory Pattern - cosmic performance optimization
+export const makeGetChannelById = () => {
+  return createSelector(
+    [
+      (state: RootState) => state.normalized.channels, 
+      (_state: RootState, channelId: string) => channelId
+    ],
+    (allChannels, channelId) => {
+      if (!allChannels || !channelId) return null;
+      return allChannels[channelId] as NormalizedChannel | null;
+    }
+  );
+};
+
+// Usage in hooks - creating stable selector instances
+export const useChannelSelector = (id: string) => {
+  const selectChannelByIdInstance = useMemo(() => makeGetChannelById(), []);
+  const channelSelector = useCallback(
+    (state: RootState) => selectChannelByIdInstance(state, id),
+    [selectChannelByIdInstance, id]
+  );
+  return useSelector(channelSelector);
+};
+```
+
+#### The Performance Magic
+
+This pattern creates what we call "Instance Isolation" - each component gets its own selector instance with its own memoization cache. It's like giving each spaceship its own navigation computer instead of making them all share one. The benefits:
+
+- **Memoization**: Results are cached until inputs change
+- **Reference Stability**: Same inputs always return the same reference
+- **Isolated Caching**: Each component's selector cache doesn't interfere with others
+
+#### Complex Selectors: The Constellation Connections
+
+The real power emerges when selectors combine to create complex derived state:
+
+```typescript
+// Complex selector composition - connecting the constellation
+export const makeGetChannelWithLastMessage = () => {
+  const getChannel = makeGetChannelById();
+  const getLastMessage = makeGetLastMessageForChannel();
+  
+  return createSelector(
+    [
+      (state: RootState, channelId: string) => getChannel(state, channelId),
+      (state: RootState, channelId: string) => getLastMessage(state, channelId),
+    ],
+    (channel, lastMessage) => {
+      if (!channel) return null;
+      
+      return {
+        ...channel,
+        lastMessage,
+        hasUnread: lastMessage && !lastMessage.isRead,
+        previewText: lastMessage?.content || 'No messages yet',
+      };
+    }
+  );
+};
+```
+
+### 5. The Smart Denormalization Strategy: When to Expand the Universe
+
+While normalized state is efficient for storage and updates, components often need nested data structures. zOS implements a "smart denormalization" strategy that carefully controls when and how data is expanded:
+
+```typescript
+/**
+ * 🚨 Selector for getting a denormalized channel by ID.
+ * Use this sparingly as denormalization causes new references to be created for each render.
+ * useChannelSelector is typically a better choice - like using a bicycle instead of a rocket
+ * when you just need to go to the corner store.
+ */
+export const channelSelector = (channelId: string) => (state: RootState): Channel | null => {
+  return denormalize(channelId, state);
+};
+```
+
+The documentation itself tells the story - denormalization is powerful but expensive. zOS provides it when needed but actively guides developers toward more efficient alternatives.
+
+### 6. TypeScript: The Universal Translator
+
+One of the most impressive aspects of zOS's Redux implementation is how it maintains complete type safety across the entire system. It's like having a universal translator that works not just for languages, but for data structures:
+
+```typescript
+// Complete type safety across the normalized universe
+interface RootState {
+  normalized: {
+    channels: Record<string, NormalizedChannel>;
+    messages: Record<string, NormalizedMessage>;
+    users: Record<string, NormalizedUser>;
+  };
+  channelsList: ChannelsListState;
+  authentication: AuthenticationState;
+  // ... other slices
+}
+
+// Type-safe selectors with full IntelliSense support
+export const useTypedSelector: TypedUseSelectorHook<RootState> = useSelector;
+
+// Generic selector factories with preserved typing
+export const makeEntitySelector = <T>(entityType: keyof RootState['normalized']) => {
+  return (entityId: string) => (state: RootState): T | null => {
+    return (state.normalized[entityType] as Record<string, T>)[entityId] || null;
+  };
+};
+```
+
+The type system acts like a cosmic safety net, catching errors at compile time that would otherwise crash spaceships in production.
+
+## The Workshop: Building Your Own Galaxy
+
+Let's build a simplified version of zOS's normalized state system to cement your understanding:
+
+### Exercise 1: Create a Normalized Schema
+
+Design a normalized state structure for a social media application with users, posts, and comments:
+
+```typescript
+// Your mission: Design this normalized structure
+interface SocialMediaState {
+  // TODO: Create normalized entities
+  // TODO: Create relationship mappings
+  // TODO: Add loading and error states
+}
+```
+
+### Exercise 2: Implement a Selector Factory
+
+Create a memoized selector factory for retrieving posts with their author information:
+
+```typescript
+// Your challenge: Implement this selector factory
+export const makeGetPostWithAuthor = () => {
+  // TODO: Use createSelector to combine post and user data
+  // TODO: Handle cases where author might not exist
+  // TODO: Return a consistent shape with author nested in post
+};
+```
+
+### Exercise 3: Build a Smart Update Function
+
+Implement a merge-first update function that safely updates entities:
+
+```typescript
+// Your quest: Build a safe update mechanism
+export const mergeEntities = <T>(
+  existing: Record<string, T>,
+  updates: Record<string, Partial<T>>
+): Record<string, T> => {
+  // TODO: Implement merge-first logic
+  // TODO: Handle undefined values appropriately  
+  // TODO: Preserve existing data when updates are partial
+};
+```
+
+## The Payoff: Understanding the Cosmic Architecture
+
+If you've made it this far, you now understand something that many developers never grasp: how to build state management that scales to real-world complexity. You've seen how zOS:
+
+1. **Normalizes ruthlessly** to eliminate data duplication and enable efficient updates
+2. **Memoizes religiously** to prevent unnecessary recalculations and re-renders
+3. **Merges carefully** to preserve data integrity during partial updates
+4. **Types completely** to catch errors before they reach production
+5. **Documents clearly** to guide developers toward efficient patterns
+
+These aren't just clever programming tricks - they're architectural decisions that enable zOS to handle millions of real-time events without breaking a sweat.
+
+## The Portal: What's Next
+
+The Redux Galaxy is vast and beautiful, but it's just the foundation. In our next chapter, "Saga Odyssey," we'll explore how zOS manages the complex async flows that make this normalized universe dance in perfect harmony.
+
+You'll discover how Redux-Saga transforms chaotic side effects into elegant orchestrations, how optimistic updates work without losing data when things go wrong, and how to build async patterns so sophisticated they make other developers question their life choices.
+
+The universe of advanced patterns is vast and full of wonders. Pack your towel - we're going deeper.
+
+---
+
+## Quick Reference: Redux Galaxy Patterns
+
+### Essential Patterns
+- **Normalized State**: Flat entity storage for efficient updates
+- **Memoized Selectors**: Cached computations with stable references  
+- **Merge-First Updates**: Preserve data during partial updates
+- **Instance Isolation**: Each component gets its own selector instance
+
+### Performance Tips
+- Use `makeGetEntityById()` factories for memoized selectors
+- Prefer normalized selectors over denormalized ones
+- Create selector instances in useMemo, not on every render
+- Document expensive selectors to guide other developers
+
+### Common Gotchas
+- Don't normalize already denormalized data (watch for `__denormalized` flags)
+- Don't create new selector instances on every render
+- Don't denormalize unless you absolutely need nested structure
+- Don't forget to handle null/undefined cases in selectors
+
+---
+
+*"In space, no one can hear you console.log. But in the Redux Galaxy, every state update is observable, every selector is memoized, and every entity has its place in the normalized universe."*
+
+---
+
+**Previous Chapter**: [Chapter 1: Don't Panic](./01-dont-panic.md)
+**Next Chapter**: [Chapter 3: Saga Odyssey](./03-saga-odyssey.md)
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/chapters/README.md b/opusdocs/hitchhiker/chapters/README.md
new file mode 100644
index 00000000..91604edf
--- /dev/null
+++ b/opusdocs/hitchhiker/chapters/README.md
@@ -0,0 +1,152 @@
+# The Hitchhiker's Guide to zOS - Chapters
+
+This directory contains all the main chapters of The Hitchhiker's Guide to zOS. Each chapter is a self-contained educational journey while building upon previous concepts.
+
+## Chapter Structure
+
+Each chapter follows the consistent structure:
+
+1. **The Hook** (1-2 paragraphs) - Engaging opening that sets the stage
+2. **The Promise** (1 paragraph) - What the reader will learn and why it matters  
+3. **The Journey** (Main content) - Progressive disclosure with checkpoints
+4. **The Payoff** (Exercises/Examples) - Hands-on proof of understanding
+5. **The Portal** (What's next) - Connection to the next chapter
+
+## Reading Path
+
+### Linear Path (Recommended for First-Time Readers)
+1. [Chapter 1: Don't Panic](./01-dont-panic.md) - Introduction to the zOS universe
+2. [Chapter 2: The Redux Galaxy](./02-redux-galaxy.md) - State management at scale
+3. [Chapter 3: Saga Odyssey](./03-saga-odyssey.md) - Async patterns that will blow your mind
+4. [Chapter 4: The Matrix Has You](./04-matrix-has-you.md) - Real-time decentralized communication
+5. [Chapter 5: Web3 Wonderland](./05-web3-wonderland.md) - Blockchain integration without the hype
+6. [Chapter 6: Component Cosmos](./06-component-cosmos.md) - Building blocks of the future
+7. [Chapter 7: Testing the Universe](./07-testing-universe.md) - How to know your code actually works
+8. [Chapter 8: The Developer's Towel](./08-developers-towel.md) - Essential tools and workflows
+
+### Skill-Based Paths
+
+#### **Backend/State Management Focus**
+- Chapter 1 → Chapter 2 → Chapter 3 → Chapter 7 → Chapter 8
+
+#### **Real-time Communication Focus** 
+- Chapter 1 → Chapter 3 → Chapter 4 → Chapter 7
+
+#### **Web3 Development Focus**
+- Chapter 1 → Chapter 2 → Chapter 5 → Chapter 7
+
+#### **Frontend/UI Focus**
+- Chapter 1 → Chapter 6 → Chapter 7 → Chapter 8
+
+## Chapter Status
+
+| Chapter | Status | Word Count | Exercises | Diagrams |
+|---------|--------|------------|-----------|----------|
+| [01-dont-panic.md](./01-dont-panic.md) | 📋 PENDING | 0 | 0 | 0 |
+| [02-redux-galaxy.md](./02-redux-galaxy.md) | 📋 PENDING | 0 | 0 | 0 |
+| [03-saga-odyssey.md](./03-saga-odyssey.md) | 📋 PENDING | 0 | 0 | 0 |
+| [04-matrix-has-you.md](./04-matrix-has-you.md) | 📋 PENDING | 0 | 0 | 0 |
+| [05-web3-wonderland.md](./05-web3-wonderland.md) | 📋 PENDING | 0 | 0 | 0 |
+| [06-component-cosmos.md](./06-component-cosmos.md) | 📋 PENDING | 0 | 0 | 0 |
+| [07-testing-universe.md](./07-testing-universe.md) | 📋 PENDING | 0 | 0 | 0 |
+| [08-developers-towel.md](./08-developers-towel.md) | 📋 PENDING | 0 | 0 | 0 |
+
+## Cross-Chapter Concepts
+
+These concepts span multiple chapters and are worth understanding as recurring themes:
+
+### **Type Safety** 
+- Introduced: Chapter 1
+- Advanced: Chapter 2 (Redux typing)
+- Applied: All subsequent chapters
+- Mastered: Chapter 8 (development workflow)
+
+### **Performance Optimization**
+- Introduced: Chapter 1 (architectural decisions)
+- State-level: Chapter 2 (selector optimization)
+- Async-level: Chapter 3 (saga optimization)
+- Component-level: Chapter 6 (React optimization)
+- System-level: Chapter 8 (monitoring and profiling)
+
+### **Error Handling**
+- Basic patterns: Chapter 1
+- State management: Chapter 2 (reducer error states)
+- Async operations: Chapter 3 (saga error handling)
+- Real-time systems: Chapter 4 (connection resilience)
+- User experience: Chapter 6 (error boundaries)
+- Testing strategies: Chapter 7 (error scenario testing)
+
+### **Real-time Systems**
+- Architecture: Chapter 1 (event-driven design)
+- State synchronization: Chapter 2 (optimistic updates)
+- Flow orchestration: Chapter 3 (saga coordination)
+- Matrix integration: Chapter 4 (real-time communication)
+- UI responsiveness: Chapter 6 (component updates)
+
+## Prerequisites by Chapter
+
+### Chapter 1: Don't Panic
+- **Required**: Basic React and JavaScript knowledge
+- **Helpful**: Redux concepts, TypeScript basics
+
+### Chapter 2: The Redux Galaxy  
+- **Required**: Chapter 1, Redux fundamentals
+- **Helpful**: Functional programming concepts
+
+### Chapter 3: Saga Odyssey
+- **Required**: Chapters 1-2, async JavaScript (Promises)
+- **Helpful**: Generator functions, functional programming
+
+### Chapter 4: The Matrix Has You
+- **Required**: Chapters 1-3
+- **Helpful**: WebSocket concepts, cryptography basics
+
+### Chapter 5: Web3 Wonderland
+- **Required**: Chapters 1-2
+- **Helpful**: Blockchain basics, cryptocurrency concepts
+
+### Chapter 6: Component Cosmos
+- **Required**: Chapters 1-2
+- **Helpful**: Advanced React patterns, design systems
+
+### Chapter 7: Testing the Universe
+- **Required**: Chapters 1-6 (focuses on testing the patterns learned)
+- **Helpful**: Testing philosophy, TDD/BDD concepts
+
+### Chapter 8: The Developer's Towel
+- **Required**: All previous chapters
+- **Helpful**: DevOps concepts, CI/CD experience
+
+## Learning Objectives Summary
+
+By completing all chapters, readers will be able to:
+
+### **Architectural Understanding**
+- Design scalable Redux applications with normalized state
+- Implement complex async flows with Redux-Saga
+- Integrate real-time communication systems
+- Build type-safe, maintainable codebases
+
+### **Practical Skills**
+- Build production-grade React applications
+- Implement robust error handling and recovery
+- Optimize application performance at all levels
+- Test complex, interconnected systems
+
+### **Advanced Patterns**
+- Master the Redux-Saga-Normalizr trinity
+- Implement decentralized communication protocols
+- Integrate blockchain functionality seamlessly
+- Build sophisticated UI component systems
+
+### **Professional Development**
+- Establish effective development workflows
+- Implement comprehensive testing strategies
+- Monitor and debug production applications
+- Collaborate effectively on complex codebases
+
+---
+
+*"Space is big. Really big. You just won't believe how vastly, hugely, mind-bogglingly big it is." - Douglas Adams*
+
+*"Code is complex. Really complex. You just won't believe how vastly, hugely, mind-bogglingly complex it is. But with the right guide, you can navigate it." - The Editors*
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/diagrams/README.md b/opusdocs/hitchhiker/diagrams/README.md
new file mode 100644
index 00000000..73ecb6a8
--- /dev/null
+++ b/opusdocs/hitchhiker/diagrams/README.md
@@ -0,0 +1,308 @@
+# The Hitchhiker's Guide to zOS - Visual Diagrams
+
+*"A picture is worth a thousand words. A good diagram is worth a thousand debugging sessions."*
+
+This directory contains visual explanations for complex zOS concepts. Because sometimes the best way to understand how something works is to see it in action.
+
+## Diagram Categories
+
+### 🏗️ System Architecture
+High-level views of how zOS components fit together.
+
+- **[Overall System Architecture](./architecture/system-overview.md)** - The big picture
+- **[Application Structure](./architecture/app-structure.md)** - How apps are organized
+- **[Data Flow Overview](./architecture/data-flow.md)** - Information flow through the system
+- **[Technology Stack](./architecture/tech-stack.md)** - How technologies integrate
+
+### 🔄 Redux and State Management
+Visual representations of state management patterns.
+
+- **[Redux Galaxy Visuals](./redux-galaxy-visuals.md)** - Complete Redux-Saga flow, normalization patterns, and state architecture from Chapter 2
+- **[Normalization Patterns](./normalization-patterns.md)** - Detailed ASCII art visualizations of normalization engine and merge-first strategies
+- **[Redux Store Structure](./redux/store-structure.md)** - State tree organization
+- **[Normalized Entities](./redux/normalized-entities.md)** - Entity relationship diagrams
+- **[Action Flow](./redux/action-flow.md)** - How actions flow through the system
+- **[Selector Composition](./redux/selector-composition.md)** - Building complex selectors
+
+### ⚡ Redux-Saga Flows
+Async operation orchestration and side effect management.
+
+- **[Redux-Saga Flows](./redux-saga-flows.md)** - Detailed Mermaid diagrams for authentication, messaging, real-time events, and error handling flows
+- **[Basic Saga Flow](./saga/basic-flow.md)** - Simple async operations
+- **[Complex Orchestration](./saga/complex-orchestration.md)** - Multi-step workflows
+- **[Error Handling](./saga/error-handling.md)** - Robust error management
+- **[Cancellation Patterns](./saga/cancellation.md)** - Cleaning up operations
+
+### 🌐 Matrix Protocol Integration
+Real-time communication and event processing.
+
+- **[Matrix Event Flow](./matrix/event-flow.md)** - How Matrix events are processed
+- **[Room State Management](./matrix/room-state.md)** - Room data synchronization
+- **[Encryption Pipeline](./matrix/encryption.md)** - E2E encryption handling
+- **[Connection Management](./matrix/connection.md)** - Network resilience
+
+### 🔗 Web3 Integration
+Blockchain integration patterns and transaction flows.
+
+- **[Wallet Connection Flow](./web3/wallet-connection.md)** - Multi-wallet support
+- **[Transaction Pipeline](./web3/transaction-flow.md)** - Safe transaction handling
+- **[Smart Contract Integration](./web3/contract-integration.md)** - Contract interaction patterns
+- **[Error Recovery](./web3/error-recovery.md)** - Blockchain error handling
+
+### 🧩 Component Architecture
+React component organization and interaction patterns.
+
+- **[Component Hierarchy](./components/hierarchy.md)** - UI component relationships
+- **[Data Flow in Components](./components/data-flow.md)** - Props and state management
+- **[Event Handling](./components/event-handling.md)** - User interaction patterns
+- **[Performance Optimization](./components/performance.md)** - Rendering optimizations
+
+### 🚀 Performance and Optimization
+Visual guides to performance improvement strategies.
+
+- **[Bundle Structure](./performance/bundle-structure.md)** - Code splitting visualization
+- **[Rendering Pipeline](./performance/rendering-pipeline.md)** - React rendering process
+- **[Memory Management](./performance/memory-management.md)** - Preventing memory leaks
+- **[Network Optimization](./performance/network-optimization.md)** - API and asset loading
+
+## Diagram Formats
+
+### ASCII Art Diagrams
+Terminal-friendly diagrams that work in any environment.
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   User Action   │───▶│   Redux Action   │───▶│   Saga Worker   │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+                                                         │
+                                                         ▼
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   UI Update     │◀───│   State Update   │◀───│   API Response  │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+```
+
+### Mermaid Diagrams
+Rich, interactive diagrams for web viewing.
+
+```mermaid
+graph TD
+    A[User Click] --> B[Dispatch Action]
+    B --> C[Saga Intercepts]
+    C --> D[API Call]
+    D --> E[Update State]
+    E --> F[Component Re-renders]
+```
+
+### Custom Visualizations
+Specialized diagrams for complex concepts.
+
+## Diagram Standards
+
+### Visual Consistency
+- **Colors**: Consistent color scheme across diagrams
+- **Shapes**: Standard shapes for common concepts
+- **Arrows**: Clear directional flow indicators
+- **Labels**: Descriptive, concise labeling
+
+### Common Elements
+- **🔵 User Actions**: Blue circles for user-initiated events
+- **🟢 System Processes**: Green rectangles for automated processes
+- **🟡 External Services**: Yellow diamonds for third-party integrations
+- **🔴 Error States**: Red for error conditions and handling
+
+### Accessibility
+- **High Contrast**: Readable in different lighting conditions
+- **Text Alternatives**: Alt text for all visual elements
+- **Screen Reader Friendly**: Structured markup for assistive technology
+- **Print Friendly**: Black and white versions available
+
+## Interactive Diagrams
+
+### Live System Visualization
+Some diagrams include interactive elements to help understand dynamic behavior:
+
+- **[Live Redux DevTools](./interactive/redux-devtools.md)** - See state changes in real-time
+- **[Matrix Event Inspector](./interactive/matrix-events.md)** - Watch Matrix events flow
+- **[Saga Flow Debugger](./interactive/saga-debugger.md)** - Step through saga execution
+- **[Component Update Tracer](./interactive/component-tracer.md)** - Trace React re-renders
+
+### Simulation Tools
+Educational tools that let you experiment with concepts:
+
+- **[State Management Simulator](./simulations/state-management.md)** - Experiment with different patterns
+- **[Async Flow Designer](./simulations/async-flow.md)** - Design and test saga flows
+- **[Performance Profiler](./simulations/performance.md)** - Visualize performance impact
+
+## Diagram Usage Guidelines
+
+### When to Use Diagrams
+- **Complex Relationships**: When text descriptions become unwieldy
+- **Process Flows**: Multi-step operations with decision points
+- **System Architecture**: Overall structure and component relationships
+- **Debugging**: Visual debugging aids for complex issues
+
+### Creating New Diagrams
+1. **Identify Need**: Clear educational or documentation purpose
+2. **Choose Format**: ASCII for simplicity, Mermaid for interactivity
+3. **Follow Standards**: Use consistent visual language
+4. **Test Clarity**: Ensure diagrams are self-explanatory
+5. **Get Review**: Validate accuracy with subject matter experts
+
+### Maintaining Diagrams
+- **Keep Updated**: Reflect current system state
+- **Version Control**: Track changes over time
+- **Cross-Reference**: Link to related documentation
+- **Regular Review**: Periodic accuracy validation
+
+## Common Diagram Patterns
+
+### Data Flow Diagrams
+```
+Input ──▶ Process ──▶ Output
+  │         │          │
+  ▼         ▼          ▼
+Error ──▶ Handle ──▶ Recovery
+```
+
+### State Machines
+```
+[Initial] ──event──▶ [Processing] ──success──▶ [Complete]
+    │                      │
+    │                      │
+    └──────error───────────┴──▶ [Error] ──retry──▶ [Processing]
+```
+
+### Component Trees
+```
+App
+├── Router
+│   ├── MessengerApp
+│   │   ├── ChannelList
+│   │   └── MessageArea
+│   └── WalletApp
+│       ├── AssetList
+│       └── TransactionHistory
+└── AppBar
+    ├── UserMenu
+    └── Navigation
+```
+
+### Sequence Diagrams
+```
+User    Component    Saga    API    State
+ │         │         │       │       │
+ │ click   │         │       │       │
+ ├────────▶│         │       │       │
+ │         │ action  │       │       │
+ │         ├────────▶│       │       │
+ │         │         │ call  │       │
+ │         │         ├──────▶│       │
+ │         │         │       │ data  │
+ │         │         │◀──────┤       │
+ │         │         │ put   │       │
+ │         │         ├──────────────▶│
+ │         │ update  │       │       │
+ │         │◀──────────────────────────┤
+ │ render  │         │       │       │
+ │◀────────┤         │       │       │
+```
+
+## Diagram Index
+
+### By Complexity Level
+
+#### 🟢 Beginner (Simple Concepts)
+- Basic Redux flow
+- Simple component hierarchy
+- Linear process flows
+
+#### 🟡 Intermediate (Multi-step Processes)
+- Saga orchestration
+- Matrix event processing
+- Component interaction
+
+#### 🟠 Advanced (Complex Systems)
+- Full system architecture
+- Performance optimization flows
+- Error handling strategies
+
+#### 🔴 Expert (Architectural Patterns)
+- Distributed system patterns
+- Advanced optimization techniques
+- System design trade-offs
+
+### By Use Case
+
+#### **Learning** 
+- Educational progression diagrams
+- Concept introduction visuals
+- Step-by-step process guides
+
+#### **Reference**
+- Quick lookup diagrams
+- API flow charts
+- Troubleshooting flowcharts
+
+#### **Debugging**
+- System state visualizations
+- Error flow diagrams
+- Performance bottleneck identification
+
+#### **Architecture Planning**
+- System design blueprints
+- Integration patterns
+- Scalability considerations
+
+## Tools and Software
+
+### Diagram Creation
+- **ASCII Art**: Text-based diagrams for universal compatibility
+- **Mermaid**: Code-based diagrams with interactive features
+- **Excalidraw**: Hand-drawn style diagrams for informal explanations
+- **Graphviz**: Automated layout for complex node graphs
+
+### Integration
+- **GitHub**: Mermaid diagrams render natively
+- **Documentation**: Embedded in markdown files
+- **Presentations**: Export formats for talks and training
+- **Interactive**: Web-based explorable diagrams
+
+---
+
+*"The universe is not only stranger than we imagine, it is stranger than we can imagine." - J.B.S. Haldane*
+
+*"Code is not only more complex than we imagine, it is more complex than we can imagine without good diagrams." - The Editors*
+
+---
+
+## Contributing to Diagrams
+
+### Diagram Requests
+Submit requests for new diagrams by:
+1. Identifying the concept that needs visualization
+2. Describing the target audience and use case
+3. Suggesting the appropriate diagram type
+4. Providing any existing reference materials
+
+### Quality Standards
+- **Accuracy**: Diagrams must reflect actual system behavior
+- **Clarity**: Self-explanatory without extensive external context  
+- **Consistency**: Follow established visual standards
+- **Maintainability**: Easy to update as system evolves
+
+### Review Process
+1. **Technical Review**: Validate accuracy with code experts
+2. **Educational Review**: Test clarity with target audience
+3. **Accessibility Review**: Ensure inclusive design
+4. **Integration Review**: Confirm proper linking and context
+
+## Quick Navigation
+
+- **[Main Guide](../chapters/)** - Full educational content
+- **[Pattern Library](../patterns/)** - Implementation patterns
+- **[Workshops](../workshops/)** - Hands-on exercises
+- **[Quick Reference](../reference/)** - Fast lookup resources
+
+---
+
+*Remember: A good diagram doesn't just show what the system does - it shows why it does it that way.*
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/diagrams/normalization-patterns.md b/opusdocs/hitchhiker/diagrams/normalization-patterns.md
new file mode 100644
index 00000000..1c742a43
--- /dev/null
+++ b/opusdocs/hitchhiker/diagrams/normalization-patterns.md
@@ -0,0 +1,679 @@
+# Normalization Pattern Visualizations
+
+*"Normalization is like Marie Kondo for your state - everything has a place, and everything in its place brings joy to your selectors."*
+
+This document provides detailed ASCII art visualizations of the normalization patterns that make zOS's state management so efficient and maintainable.
+
+---
+
+## Core Normalization Concepts
+
+### 1. Before vs After Normalization
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                      THE GREAT FLATTENING                       │
+│                                                                 │
+│  BEFORE: Nested Nightmare                                       │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ chatApp: {                                          │       │
+│  │   channels: [                                       │       │
+│  │     {                                               │       │
+│  │       id: "room1",                                  │       │
+│  │       name: "General",                              │       │
+│  │       members: [                                    │       │
+│  │         { id: "user1", name: "Alice", ... },       │       │
+│  │         { id: "user2", name: "Bob", ... }          │       │
+│  │       ],                                            │       │
+│  │       messages: [                                   │       │
+│  │         {                                           │       │
+│  │           id: "msg1",                               │       │
+│  │           content: "Hello!",                        │       │
+│  │           author: { id: "user1", name: "Alice" },  │       │
+│  │           replies: [                                │       │
+│  │             {                                       │       │
+│  │               id: "reply1",                         │       │
+│  │               content: "Hi back!",                  │       │
+│  │               author: { id: "user2", name: "Bob" } │       │
+│  │             }                                       │       │
+│  │           ]                                         │       │
+│  │         }                                           │       │
+│  │       ]                                             │       │
+│  │     }                                               │       │
+│  │   ]                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│                    ┌─────────────────┐                         │
+│                    │  NORMALIZATION  │                         │
+│                    │     ENGINE      │                         │
+│                    └─────────────────┘                         │
+│                              │                                 │
+│                              ▼                                 │
+│  AFTER: Normalized Nirvana                                     │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ normalized: {                                       │       │
+│  │   users: {                                          │       │
+│  │     "user1": { id: "user1", name: "Alice", ... },  │       │
+│  │     "user2": { id: "user2", name: "Bob", ... }     │       │
+│  │   },                                                │       │
+│  │   channels: {                                       │       │
+│  │     "room1": {                                      │       │
+│  │       id: "room1",                                  │       │
+│  │       name: "General",                              │       │
+│  │       members: ["user1", "user2"],                 │       │
+│  │       messages: ["msg1"]                            │       │
+│  │     }                                               │       │
+│  │   },                                                │       │
+│  │   messages: {                                       │       │
+│  │     "msg1": {                                       │       │
+│  │       id: "msg1",                                   │       │
+│  │       content: "Hello!",                            │       │
+│  │       author: "user1",                              │       │
+│  │       replies: ["reply1"]                           │       │
+│  │     },                                              │       │
+│  │     "reply1": {                                     │       │
+│  │       id: "reply1",                                 │       │
+│  │       content: "Hi back!",                          │       │
+│  │       author: "user2"                               │       │
+│  │     }                                               │       │
+│  │   }                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+
+Benefits of Normalization:
+├─ Update user1's name → Only one place to change
+├─ Add message to room1 → Just append to messages array
+├─ Find all user2's messages → Single table scan
+└─ Memory efficiency → No duplicated user objects
+```
+
+### 2. Normalization Engine Architecture
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                   NORMALIZATION ENGINE FLOW                     │
+│                                                                 │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
+│  │ RAW API     │────▶│ NORMALIZER  │────▶│ NORMALIZED  │       │
+│  │ RESPONSE    │     │ PROCESSOR   │     │ ENTITIES    │       │
+│  └─────────────┘     └─────────────┘     └─────────────┘       │
+│         │                     │                     │           │
+│         │                     │                     │           │
+│  ┌──────▼──────┐     ┌────────▼────────┐     ┌──────▼──────┐   │
+│  │ Input       │     │ Processing      │     │ Output      │   │
+│  │ Validation  │     │ Pipeline        │     │ Validation  │   │
+│  │─────────────│     │─────────────────│     │─────────────│   │
+│  │ • Check     │     │ 1. Schema       │     │ • Verify    │   │
+│  │   denorm    │     │    Application  │     │   structure │   │
+│  │   flag      │     │ 2. Entity       │     │ • Check     │   │
+│  │ • Validate  │     │    Extraction   │     │   refs      │   │
+│  │   required  │     │ 3. Reference    │     │ • Ensure    │   │
+│  │   fields    │     │    Mapping      │     │   integrity │   │
+│  │ • Type      │     │ 4. Relationship │     │ • Update    │   │
+│  │   checking  │     │    Building     │     │   indexes   │   │
+│  └─────────────┘     └─────────────────┘     └─────────────┘   │
+│         │                     │                     │           │
+│         │                     │                     │           │
+│  ┌──────▼──────┐     ┌────────▼────────┐     ┌──────▼──────┐   │
+│  │ Error       │     │ Transform       │     │ Merge       │   │
+│  │ Handling    │     │ Operations      │     │ Strategy    │   │
+│  │─────────────│     │─────────────────│     │─────────────│   │
+│  │ • Invalid   │     │ • ID Generation │     │ • Deep      │   │
+│  │   data      │     │ • Key Mapping   │     │   merge     │   │
+│  │ • Missing   │     │ • Type Coercion │     │ • Preserve  │   │
+│  │   schemas   │     │ • Date/Time     │     │   existing  │   │
+│  │ • Circular  │     │   Formatting    │     │ • Smart     │   │
+│  │   refs      │     │ • Null Handling │     │   updates   │   │
+│  └─────────────┘     └─────────────────┘     └─────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 3. Schema Definition Patterns
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                      SCHEMA ARCHITECTURE                        │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │                  ENTITY SCHEMAS                     │       │
+│  │                                                     │       │
+│  │  User Schema                                        │       │
+│  │  ┌─────────────────────────────────────────┐       │       │
+│  │  │ new nSchema.Entity('users', {           │       │       │
+│  │  │   follows: [userSchema],  ──────────┐   │       │       │
+│  │  │   followers: [userSchema] ──────────┼───┼──┐    │       │
+│  │  │ }, {                               │   │  │    │       │
+│  │  │   idAttribute: 'id'                │   │  │    │       │
+│  │  │ })                                 │   │  │    │       │
+│  │  └─────────────────────────────────────┼───┼──┼────┘       │
+│  │                                       │   │  │            │       │
+│  │  Channel Schema                       │   │  │            │       │
+│  │  ┌─────────────────────────────────────┼───┼──┼────┐       │       │
+│  │  │ new nSchema.Entity('channels', {   │   │  │    │       │       │
+│  │  │   members: [userSchema], ──────────┘   │  │    │       │       │
+│  │  │   messages: [messageSchema], ──────────┼──┼────┼──┐    │       │
+│  │  │   createdBy: userSchema ───────────────┘  │    │  │    │       │
+│  │  │ })                                        │    │  │    │       │
+│  │  └───────────────────────────────────────────┼────┼──┼────┘       │
+│  │                                              │    │  │            │
+│  │  Message Schema                              │    │  │            │
+│  │  ┌───────────────────────────────────────────┼────┼──┼────┐       │
+│  │  │ new nSchema.Entity('messages', {         │    │  │    │       │
+│  │  │   author: userSchema, ───────────────────┘    │  │    │       │
+│  │  │   replies: [messageSchema], ──────────────────┼──┼────┼──┐    │
+│  │  │   parentMessage: messageSchema ───────────────┘  │    │  │    │
+│  │  │ })                                              │    │  │    │
+│  │  └─────────────────────────────────────────────────┼────┼──┼────┘
+│  │                                                    │    │  │    │
+│  └────────────────────────────────────────────────────┼────┼──┼────┘
+│                                                       │    │  │    │
+│  ┌────────────────────────────────────────────────────┼────┼──┼────┐
+│  │               RELATIONSHIP MAPPING                 │    │  │    │
+│  │                                                    │    │  │    │
+│  │  Self-References (Circular)        ───────────────┘    │  │    │
+│  │  ├─ User follows/followers                             │  │    │
+│  │  └─ Message replies/parent                             │  │    │
+│  │                                                        │  │    │
+│  │  Cross-Entity References          ────────────────────┘  │    │
+│  │  ├─ Channel → Users (members)                            │    │
+│  │  ├─ Channel → Messages                                   │    │
+│  │  └─ Message → User (author)                              │    │
+│  │                                                          │    │
+│  │  Complex Relationships           ───────────────────────┘    │
+│  │  ├─ Many-to-Many (Channel members)                           │
+│  │  ├─ One-to-Many (User messages)                              │
+│  │  └─ Hierarchical (Message threads) ────────────────────────┘
+│  └─────────────────────────────────────────────────────────────┘
+└─────────────────────────────────────────────────────────────────┘
+
+Schema Patterns:
+├─ ──────── = Entity relationships
+├─ ┌──────┐ = Schema definitions
+└─ Circular = Self-referencing entities
+```
+
+---
+
+## Advanced Normalization Patterns
+
+### 4. The Merge-First Strategy
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                    MERGE-FIRST ALGORITHM                        │
+│                                                                 │
+│  SCENARIO: User updates profile picture                         │
+│                                                                 │
+│  EXISTING STATE:                                                │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ users: {                                            │       │
+│  │   "user1": {                                        │       │
+│  │     id: "user1",                                    │       │
+│  │     name: "Alice",                                  │       │
+│  │     email: "alice@example.com",                     │       │
+│  │     avatar: "old-avatar.jpg",                       │       │
+│  │     bio: "Love coding!",                            │       │
+│  │     preferences: { theme: "dark", ... },           │       │
+│  │     lastSeen: "2024-01-01T10:00:00Z"               │       │
+│  │   }                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  INCOMING UPDATE:                                               │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ users: {                                            │       │
+│  │   "user1": {                                        │       │
+│  │     id: "user1",                                    │       │
+│  │     avatar: "new-avatar.jpg",                       │       │
+│  │     lastModified: "2024-01-01T11:00:00Z"           │       │
+│  │   }                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              MERGE ALGORITHM                        │       │
+│  │                                                     │       │
+│  │  for entityId in newEntities:                      │       │
+│  │    existing = state[entityId] || {}                │       │
+│  │    merged = {                                       │       │
+│  │      ...existing,     ← Keep all existing fields   │       │
+│  │      ...newEntity     ← Overlay new/changed fields │       │
+│  │    }                                                │       │
+│  │    state[entityId] = merged                         │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  RESULT STATE:                                                  │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ users: {                                            │       │
+│  │   "user1": {                                        │       │
+│  │     id: "user1",                                    │       │
+│  │     name: "Alice",           ← PRESERVED            │       │
+│  │     email: "alice@example.com", ← PRESERVED         │       │
+│  │     avatar: "new-avatar.jpg",    ← UPDATED          │       │
+│  │     bio: "Love coding!",     ← PRESERVED            │       │
+│  │     preferences: { theme: "dark", ... }, ← PRESERVED│       │
+│  │     lastSeen: "2024-01-01T10:00:00Z", ← PRESERVED   │       │
+│  │     lastModified: "2024-01-01T11:00:00Z" ← ADDED    │       │
+│  │   }                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+
+Merge Benefits:
+├─ No data loss from partial updates
+├─ Graceful handling of concurrent updates  
+├─ Preserved relationships and references
+└─ Optimal for real-time environments
+```
+
+### 5. Denormalization Safety Mechanisms
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                   DENORMALIZATION SAFETY NET                    │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │                SAFE DENORMALIZATION                 │       │
+│  │                                                     │       │
+│  │  1. Extract entity from normalized state            │       │
+│  │     normalized.users["user1"]                       │       │
+│  │                    │                                │       │
+│  │                    ▼                                │       │
+│  │  2. Recursively resolve references                  │       │
+│  │     user.follows → [user2, user3, ...]             │       │
+│  │                    │                                │       │
+│  │                    ▼                                │       │
+│  │  3. Mark as denormalized                            │       │
+│  │     user.__denormalized = true                      │       │
+│  │                    │                                │       │
+│  │                    ▼                                │       │
+│  │  4. Return nested object                            │       │
+│  │     {                                               │       │
+│  │       id: "user1",                                  │       │
+│  │       follows: [                                    │       │
+│  │         { id: "user2", name: "Bob", ... },         │       │
+│  │         { id: "user3", name: "Carol", ... }        │       │
+│  │       ],                                            │       │
+│  │       __denormalized: true                          │       │
+│  │     }                                               │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              SAFETY VALIDATION                      │       │
+│  │                                                     │       │
+│  │  normalize(denormalizedData) {                      │       │
+│  │    if (data.__denormalized) {                       │       │
+│  │      throw new Error(                               │       │
+│  │        "Attempted to normalize denormalized data!"  │       │
+│  │      );                                             │       │
+│  │    }                                                │       │
+│  │    // ... proceed with normalization               │       │
+│  │  }                                                  │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │               ERROR PREVENTION                      │       │
+│  │                                                     │       │
+│  │  Prevents:                                          │       │
+│  │  ├─ Infinite normalization loops                    │       │
+│  │  ├─ Data corruption from re-processing              │       │
+│  │  ├─ Performance degradation                         │       │
+│  │  └─ State inconsistencies                           │       │
+│  │                                                     │       │
+│  │  Example Error Scenario:                            │       │
+│  │  ┌─────────────────────────────────────────┐       │       │
+│  │  │ // BAD: This would cause infinite loop  │       │       │
+│  │  │ const user = denormalize("user1", state)│       │       │
+│  │  │ normalize(user) // ERROR! __denormalized │       │       │       │
+│  │  │ flag prevents this                       │       │       │
+│  │  └─────────────────────────────────────────┘       │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## State Update Patterns
+
+### 6. Batch Processing Pipeline
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                      BATCH PROCESSING FLOW                      │
+│                                                                 │
+│  HIGH-FREQUENCY EVENTS                                          │
+│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐                   │
+│  │Event1│ │Event2│ │Event3│ │Event4│ │Event5│ ...               │
+│  └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘                   │
+│     │        │        │        │        │                       │
+│     ▼        ▼        ▼        ▼        ▼                       │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │               EVENT COLLECTOR                       │       │
+│  │                                                     │       │
+│  │  Buffer: [event1, event2, event3, ...]             │       │
+│  │  Timer: 500ms countdown                             │       │  
+│  │  Size:  Current buffer size                         │       │
+│  │                                                     │       │
+│  │  Triggers:                                          │       │
+│  │  ├─ Buffer full (100 events)                        │       │
+│  │  ├─ Timer expires (500ms)                           │       │
+│  │  └─ Critical event received                         │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              BATCH PROCESSOR                        │       │
+│  │                                                     │       │
+│  │  1. Group by Entity Type                            │       │
+│  │     ┌─────────┐ ┌─────────┐ ┌─────────┐            │       │
+│  │     │ Users   │ │Channels │ │Messages │            │       │
+│  │     │ Events  │ │ Events  │ │ Events  │            │       │
+│  │     └─────────┘ └─────────┘ └─────────┘            │       │
+│  │                                                     │       │
+│  │  2. Deduplicate Updates                             │       │
+│  │     user1: [update1, update2, update3]             │       │
+│  │            ↓                                        │       │
+│  │     user1: merged_update                            │       │
+│  │                                                     │       │
+│  │  3. Normalize All Entities                          │       │
+│  │     Individual → Normalized → Merged               │       │
+│  │                                                     │       │
+│  │  4. Build Single Update Payload                     │       │
+│  │     {                                               │       │
+│  │       users: { ... },                              │       │
+│  │       channels: { ... },                           │       │
+│  │       messages: { ... }                            │       │
+│  │     }                                               │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │           SINGLE STATE UPDATE                       │       │
+│  │                                                     │       │
+│  │  dispatch(normalized.receive(batchPayload))         │       │
+│  │                                                     │       │
+│  │  Result: One Redux update instead of 100+          │       │
+│  │          One re-render cycle instead of 100+       │       │
+│  │          Consistent state across all entities      │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+
+Performance Impact:
+├─ Before: 100 events = 100 updates = 100 re-renders
+└─ After:  100 events = 1 batched update = 1 re-render
+```
+
+### 7. Relationship Integrity Management
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                 RELATIONSHIP INTEGRITY SYSTEM                   │
+│                                                                 │
+│  SCENARIO: User leaves a channel                                │
+│                                                                 │
+│  BEFORE: Broken References                                      │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ channels: {                                         │       │
+│  │   "room1": {                                        │       │
+│  │     members: ["user1", "user2", "user3"] ← STALE   │       │
+│  │   }                                                 │       │
+│  │ },                                                  │       │
+│  │ users: {                                            │       │  
+│  │   "user2": {                                        │       │
+│  │     channels: ["room1", "room2"] ← INCONSISTENT    │       │
+│  │   }                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │           INTEGRITY PROCESSOR                       │       │
+│  │                                                     │       │
+│  │  1. Detect Relationship Change                      │       │
+│  │     ┌───────────────────────────────────────┐       │       │
+│  │     │ Event: user2 left room1               │       │       │
+│  │     │ Impact: channel.members, user.channels│       │       │
+│  │     └───────────────────────────────────────┘       │       │
+│  │                              │                      │       │
+│  │                              ▼                      │       │
+│  │  2. Calculate Cascading Updates                     │       │
+│  │     ┌───────────────────────────────────────┐       │       │
+│  │     │ Update 1: Remove user2 from room1     │       │       │
+│  │     │ Update 2: Remove room1 from user2     │       │       │
+│  │     │ Update 3: Update member count          │       │       │
+│  │     │ Update 4: Update last activity        │       │       │
+│  │     └───────────────────────────────────────┘       │       │
+│  │                              │                      │       │
+│  │                              ▼                      │       │
+│  │  3. Apply Atomic Updates                            │       │
+│  │     ┌───────────────────────────────────────┐       │       │
+│  │     │ Transaction: All updates or none      │       │       │
+│  │     │ Validation: Check constraints          │       │       │
+│  │     │ Rollback: If any update fails         │       │       │
+│  │     └───────────────────────────────────────┘       │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  AFTER: Consistent State                                        │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ channels: {                                         │       │
+│  │   "room1": {                                        │       │
+│  │     members: ["user1", "user3"], ← UPDATED          │       │
+│  │     memberCount: 2 ← UPDATED                        │       │
+│  │   }                                                 │       │
+│  │ },                                                  │       │
+│  │ users: {                                            │       │
+│  │   "user2": {                                        │       │
+│  │     channels: ["room2"] ← UPDATED                   │       │
+│  │   }                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+
+Integrity Guarantees:
+├─ Referential consistency across all entities
+├─ Atomic updates for related changes
+├─ Automatic cascade handling
+└─ Rollback on constraint violations
+```
+
+---
+
+## Performance Optimization Patterns
+
+### 8. Selector Memoization Architecture
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                    SELECTOR MEMOIZATION FLOW                    │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │                COMPONENT TREE                       │       │
+│  │                                                     │       │
+│  │      Component A          Component B               │       │
+│  │      ┌─────────┐          ┌─────────┐               │       │
+│  │      │ useUser │          │ useUser │               │       │
+│  │      │("user1")│          │("user1")│               │       │
+│  │      └────┬────┘          └────┬────┘               │       │
+│  │           │                    │                     │       │
+│  │           ▼                    ▼                     │       │
+│  │      ┌─────────┐          ┌─────────┐               │       │
+│  │      │Selector │          │Selector │               │       │
+│  │      │Instance1│          │Instance2│               │       │
+│  │      └────┬────┘          └────┬────┘               │       │
+│  │           │                    │                     │       │
+│  │           └────────┬───────────┘                     │       │
+│  │                    │                                 │       │
+│  └────────────────────┼─────────────────────────────────┘       │
+│                       │                                         │
+│                       ▼                                         │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              MEMOIZATION LAYER                      │       │
+│  │                                                     │       │
+│  │  Instance 1 Cache:                                  │       │
+│  │  ┌─────────────────────────────────────────┐       │       │
+│  │  │ Input:  (state, "user1")                │       │       │
+│  │  │ Hash:   "abc123..."                     │       │       │
+│  │  │ Output: { id: "user1", name: "Alice" }  │       │       │
+│  │  │ Refs:   Same object reference           │       │       │
+│  │  └─────────────────────────────────────────┘       │       │
+│  │                                                     │       │
+│  │  Instance 2 Cache:                                  │       │
+│  │  ┌─────────────────────────────────────────┐       │       │
+│  │  │ Input:  (state, "user1")                │       │       │
+│  │  │ Hash:   "abc123..."                     │       │       │
+│  │  │ Output: { id: "user1", name: "Alice" }  │       │       │
+│  │  │ Refs:   Same object reference           │       │       │
+│  │  └─────────────────────────────────────────┘       │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                       │                                         │
+│                       ▼                                         │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │               CACHE BEHAVIOR                        │       │
+│  │                                                     │       │
+│  │  State Change: users.user1.name → "Alice Updated"   │       │
+│  │                                                     │       │
+│  │  Cache Miss: New input hash detected               │       │
+│  │  ├─ Instance 1: Recompute & cache                  │       │
+│  │  └─ Instance 2: Recompute & cache                  │       │
+│  │                                                     │       │
+│  │  Result: Both components get new data              │       │
+│  │                                                     │       │
+│  │  Optimization: If user1.email changes (unused)     │       │
+│  │  ├─ Selector doesn't include email                 │       │
+│  │  ├─ Cache hit: Same input hash                     │       │
+│  │  └─ No recomputation needed                        │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+
+Memoization Benefits:
+├─ Instance isolation prevents cache conflicts
+├─ Stable references reduce component re-renders  
+├─ Selective field watching optimizes updates
+└─ Shared computation across component instances
+```
+
+### 9. Update Optimization Patterns
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                    UPDATE OPTIMIZATION FLOW                     │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              INCOMING UPDATE STREAM                 │       │
+│  │                                                     │       │
+│  │  Real-time Events:                                  │       │
+│  │  ┌──────────────────────────────────────────┐      │       │
+│  │  │ 10:01:00 - user1 typing in room1        │      │       │
+│  │  │ 10:01:05 - user1 stopped typing         │      │       │
+│  │  │ 10:01:10 - user2 typing in room1        │      │       │
+│  │  │ 10:01:12 - user1 sent message           │      │       │
+│  │  │ 10:01:13 - user2 stopped typing         │      │       │
+│  │  │ 10:01:15 - user3 joined room1           │      │       │
+│  │  │ 10:01:20 - user1 read message           │      │       │
+│  │  │ ... (hundreds more events)              │      │       │
+│  │  └──────────────────────────────────────────┘      │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │             SMART FILTERING                         │       │
+│  │                                                     │       │
+│  │  1. Event Priority Classification                   │       │
+│  │     ┌───────────────────────────────────────┐       │       │
+│  │     │ High Priority: Messages, Joins        │       │       │
+│  │     │ Med Priority:  Status, Reactions      │       │       │
+│  │     │ Low Priority:  Typing, Read Receipts  │       │       │
+│  │     └───────────────────────────────────────┘       │       │
+│  │                                                     │       │
+│  │  2. Temporal Deduplication                          │       │
+│  │     ┌───────────────────────────────────────┐       │       │
+│  │     │ user1 typing → user1 stopped typing   │       │       │
+│  │     │ Result: Skip both (net zero)          │       │       │
+│  │     └───────────────────────────────────────┘       │       │
+│  │                                                     │       │
+│  │  3. Relevance Filtering                             │       │
+│  │     ┌───────────────────────────────────────┐       │       │
+│  │     │ If user not viewing room1:             │       │       │
+│  │     │ ├─ Skip typing events                  │       │       │
+│  │     │ ├─ Keep message events                 │       │       │
+│  │     │ └─ Queue status updates                │       │       │
+│  │     └───────────────────────────────────────┘       │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              BATCH OPTIMIZATION                     │       │
+│  │                                                     │       │
+│  │  Original: 1000 events → 1000 state updates        │       │
+│  │            ▼                                        │       │
+│  │  Filtered:  200 events → Batch processing          │       │
+│  │            ▼                                        │       │
+│  │  Batched:    10 batches → 10 state updates         │       │
+│  │            ▼                                        │       │
+│  │  Result: 99% reduction in update cycles            │       │
+│  │                                                     │       │
+│  │  Performance Impact:                                │       │
+│  │  ├─ UI: 10 re-renders instead of 1000              │       │
+│  │  ├─ CPU: 90% less processing                       │       │
+│  │  ├─ Memory: 80% less object creation                │       │
+│  │  └─ Battery: Significant power savings             │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Reference: Normalization Symbols
+
+### ASCII Diagram Legend
+```ascii
+Entity Representations:
+┌────────┐ = Entity/Schema definition
+│ Entity │   with properties and methods
+└────────┘
+
+┌─┐ = Compact entity    ◄──── = One-to-many relationship  
+└─┘   reference        ────▶ = Many-to-one relationship
+                       ◄───▶ = Many-to-many relationship
+
+Data Flow Indicators:
+───▶ = Data transformation    ┌─────┐ = Process box
+◄─── = Reverse mapping       │ Proc │   with operations
+▼▲   = Vertical flow         └─────┘
+
+State Representations:
+┌───────────────┐ = State structure
+│ key: value    │   with nested data
+│ nested: {...} │
+└───────────────┘
+
+Performance Indicators:
+├─ = List item/benefit        🟢 = Optimized operation
+└─ = Terminal list item       🔴 = Expensive operation
+```
+
+### Normalization Process Flow
+```ascii
+Raw Data → Validation → Schema → Entities → References → State
+    ▲           ▲          ▲         ▲          ▲         ▲
+    │           │          │         │          │         │
+   JSON      __denorm    Apply     Extract    Build      Merge
+   Input      Check      Rules     Objects    Links      First
+```
+
+---
+
+*"Normalization is not just about flat data structures - it's about creating a universe where every piece of information has exactly one source of truth, and every relationship is a well-maintained highway between entities."*
+
+---
+
+**Related**: [Redux Galaxy Visuals](./redux-galaxy-visuals.md) | [Redux-Saga Flows](./redux-saga-flows.md) | [Chapter 2: Redux Galaxy](../chapters/02-redux-galaxy.md)
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/diagrams/redux-galaxy-visuals.md b/opusdocs/hitchhiker/diagrams/redux-galaxy-visuals.md
new file mode 100644
index 00000000..9f7c7d2e
--- /dev/null
+++ b/opusdocs/hitchhiker/diagrams/redux-galaxy-visuals.md
@@ -0,0 +1,624 @@
+# Redux Galaxy Visual Guide
+
+*"A picture is worth a thousand state updates, and a diagram is worth a million debugging sessions."*
+
+This visual guide transforms the complex Redux-Saga flow, normalization patterns, and state architecture from Chapter 2: The Redux Galaxy into clear, understandable diagrams. Whether you're debugging a flow or learning the patterns, these visuals will be your cosmic map.
+
+---
+
+## Table of Contents
+
+1. [Redux-Saga Flow Architecture](#redux-saga-flow-architecture)
+2. [Normalization Engine Patterns](#normalization-engine-patterns)
+3. [State Architecture Overview](#state-architecture-overview)
+4. [Selector Constellation Patterns](#selector-constellation-patterns)
+5. [Data Flow Sequences](#data-flow-sequences)
+6. [Error Handling & Recovery](#error-handling--recovery)
+
+---
+
+## Redux-Saga Flow Architecture
+
+### 1. Root Saga Orchestration
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                        ROOT SAGA UNIVERSE                       │
+│                                                                 │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐      │
+│  │   Spawn     │────▶│    Spawn    │────▶│    Spawn    │      │
+│  │ Page Load   │     │    Web3     │     │  Channels   │      │
+│  └─────────────┘     └─────────────┘     └─────────────┘      │
+│           │                  │                  │             │
+│           ▼                  ▼                  ▼             │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐      │
+│  │   Spawn     │     │   Spawn     │     │   Spawn     │      │
+│  │ Messages    │     │ Auth Flow   │     │ Chat Events │      │
+│  └─────────────┘     └─────────────┘     └─────────────┘      │
+│           │                  │                  │             │
+│           └──────────────────┼──────────────────┘             │
+│                              │                                │
+│                    ┌─────────▼─────────┐                      │
+│                    │  Error Boundary   │                      │
+│                    │ (Isolated Crash)  │                      │
+│                    └───────────────────┘                      │
+└─────────────────────────────────────────────────────────────────┘
+
+Legend:
+├─ spawn()  = Independent saga process
+├─ ────▶    = Initialization flow
+└─ Error    = Saga-level error isolation
+```
+
+### 2. Saga Lifecycle Patterns
+
+```mermaid
+graph TD
+    A[Action Dispatched] --> B{Saga Watcher}
+    B -->|takeLatest| C[Cancel Previous]
+    B -->|takeEvery| D[Fork New Instance]
+    B -->|takeLeading| E[Ignore if Running]
+    
+    C --> F[Execute Saga]
+    D --> F
+    E --> F
+    
+    F --> G{Side Effect}
+    G -->|API Call| H[call()]
+    G -->|State Update| I[put()]
+    G -->|Data Select| J[select()]
+    G -->|Delay| K[delay()]
+    
+    H --> L{Success?}
+    L -->|Yes| M[Normalize Data]
+    L -->|No| N[Error Handling]
+    
+    M --> O[Dispatch Success]
+    N --> P[Dispatch Error]
+    
+    O --> Q[Update State]
+    P --> Q
+    
+    style A fill:#e1f5fe
+    style F fill:#f3e5f5
+    style M fill:#e8f5e8
+    style N fill:#ffebee
+```
+
+---
+
+## Normalization Engine Patterns
+
+### 1. The Unified Normalization Flow
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                    NORMALIZATION UNIVERSE                       │
+│                                                                 │
+│  INPUT: Nested API Response                                     │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ {                                                   │       │
+│  │   channels: [{                                      │       │
+│  │     id: "room1",                                    │       │
+│  │     messages: [{                                    │       │
+│  │       id: "msg1",                                   │       │
+│  │       author: { id: "user1", name: "Alice" }       │       │
+│  │     }]                                              │       │
+│  │   }]                                                │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              NORMALIZER ENGINE                      │       │
+│  │                                                     │       │
+│  │  1. Schema Validation    ┌──────────────────┐      │       │
+│  │     - Check __denormalized flag             │      │       │
+│  │     - Prevent infinite loops                │      │       │
+│  │                                             │      │       │
+│  │  2. Entity Extraction    ┌──────────────────┐      │       │
+│  │     - Flatten nested objects               │      │       │
+│  │     - Create relationship tables          │      │       │
+│  │                                             │      │       │
+│  │  3. Reference Mapping    ┌──────────────────┐      │       │
+│  │     - Generate entity IDs                  │      │       │
+│  │     - Build lookup tables                 │      │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  OUTPUT: Normalized State                                       │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │ entities: {                                         │       │
+│  │   users: {                                          │       │
+│  │     "user1": { id: "user1", name: "Alice" }        │       │
+│  │   },                                                │       │
+│  │   messages: {                                       │       │
+│  │     "msg1": { id: "msg1", author: "user1" }        │       │
+│  │   },                                                │       │
+│  │   channels: {                                       │       │
+│  │     "room1": { id: "room1", messages: ["msg1"] }   │       │
+│  │   }                                                 │       │
+│  │ }                                                   │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2. Merge-First Update Strategy
+
+```mermaid
+graph TD
+    A[Incoming Data] --> B{Data Type}
+    B -->|Full Entity| C[Deep Merge]
+    B -->|Partial Update| D[Smart Merge]
+    B -->|New Entity| E[Direct Insert]
+    
+    C --> F{Existing Data?}
+    D --> F
+    
+    F -->|Yes| G[Preserve Existing Fields]
+    F -->|No| H[Create New Record]
+    
+    G --> I[Merge New Fields]
+    I --> J[Update Reference Tables]
+    H --> J
+    E --> J
+    
+    J --> K[Validate Relationships]
+    K --> L[Commit to State]
+    
+    style A fill:#e3f2fd
+    style C fill:#e8f5e8
+    style D fill:#fff3e0
+    style G fill:#f1f8e9
+    style I fill:#e0f2f1
+```
+
+### 3. Entity Relationship Diagram
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                    NORMALIZED STATE SCHEMA                      │
+│                                                                 │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
+│  │    USERS    │     │  CHANNELS   │     │  MESSAGES   │       │
+│  │─────────────│     │─────────────│     │─────────────│       │
+│  │ id: string  │◄────┤ id: string  │◄────┤ id: string  │       │
+│  │ name: str   │     │ name: str   │     │ content: str│       │
+│  │ avatar: str │     │ type: enum  │     │ author: ref │──────┐│
+│  │ status: enum│     │ members: []ref     │ timestamp   │      ││
+│  │ lastSeen: ts│     │ messages: []ref    │ parentId: ref      ││
+│  └─────────────┘     │ unreadCount │     │ reactions: {}│      ││
+│         ▲            │ labels: []  │     │ editedAt: ts│      ││
+│         │            └─────────────┘     └─────────────┘      ││
+│         │                   ▲                   │            ││
+│         │                   │                   │            ││
+│         └───────────────────┼───────────────────┘            ││
+│                             │                                ││
+│  ┌─────────────────────────────────────────────────────────────┘│
+│  │                RELATIONSHIP TABLES                          │
+│  │                                                             │
+│  │  channelMembers: {                                          │
+│  │    "room1": ["user1", "user2", "user3"]                    │
+│  │  }                                                          │
+│  │                                                             │
+│  │  channelMessages: {                                         │
+│  │    "room1": ["msg1", "msg2", "msg3"]                       │
+│  │  }                                                          │
+│  │                                                             │
+│  │  messageReplies: {                                          │
+│  │    "msg1": ["reply1", "reply2"]                            │
+│  │  }                                                          │
+│  └─────────────────────────────────────────────────────────────│
+└─────────────────────────────────────────────────────────────────┘
+
+Legend:
+├─ ref      = Reference to another entity
+├─ []ref    = Array of references
+├─ ◄────    = One-to-many relationship
+└─ {}       = Object/Map structure
+```
+
+---
+
+## State Architecture Overview
+
+### 1. Complete Redux Store Structure
+
+```mermaid
+graph TB
+    subgraph "Redux Store"
+        A[RootState]
+        
+        subgraph "Normalized Entities"
+            B[users: Record<string, User>]
+            C[channels: Record<string, Channel>]
+            D[messages: Record<string, Message>]
+        end
+        
+        subgraph "Feature Slices"
+            E[authentication]
+            F[chat]
+            G[channelsList]
+            H[theme]
+            I[notifications]
+        end
+        
+        subgraph "UI State"
+            J[activeConversationId]
+            K[selectedMessages]
+            L[isLoading]
+            M[error]
+        end
+        
+        A --> B
+        A --> C
+        A --> D
+        A --> E
+        A --> F
+        A --> G
+        A --> H
+        A --> I
+        A --> J
+        A --> K
+        A --> L
+        A --> M
+    end
+    
+    style A fill:#e1f5fe
+    style B fill:#e8f5e8
+    style C fill:#e8f5e8
+    style D fill:#e8f5e8
+    style E fill:#fff3e0
+    style F fill:#fff3e0
+```
+
+### 2. Data Flow Architecture
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                        DATA FLOW COSMOS                         │
+│                                                                 │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
+│  │   UI LAYER  │    │ SAGA LAYER  │    │ API LAYER   │         │
+│  │─────────────│    │─────────────│    │─────────────│         │
+│  │ Components  │───▶│ Watchers    │───▶│ HTTP Calls  │         │
+│  │ Hooks       │    │ Workers     │    │ WebSockets  │         │
+│  │ Selectors   │◄───│ Effects     │◄───│ Responses   │         │
+│  └─────────────┘    └─────────────┘    └─────────────┘         │
+│          │                  │                  │               │
+│          ▼                  ▼                  ▼               │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
+│  │   ACTIONS   │    │ NORMALIZER  │    │   CACHE     │         │
+│  │─────────────│    │─────────────│    │─────────────│         │
+│  │ User Events │───▶│ Schema Val. │───▶│ Entity Store│         │
+│  │ API Events  │    │ Entity Ext. │    │ Relationships        │
+│  │ System Evts │    │ Ref Mapping │    │ Indexes     │         │
+│  └─────────────┘    └─────────────┘    └─────────────┘         │
+│          │                  │                  │               │
+│          └──────────────────┼──────────────────┘               │
+│                             ▼                                  │
+│                    ┌─────────────┐                             │
+│                    │   REDUCER   │                             │
+│                    │─────────────│                             │
+│                    │ Merge Logic │                             │
+│                    │ State Trees │                             │
+│                    │ Immutability│                             │
+│                    └─────────────┘                             │
+│                             │                                  │
+│                             ▼                                  │
+│                    ┌─────────────┐                             │
+│                    │   STORE     │                             │
+│                    │─────────────│                             │
+│                    │ Normalized  │                             │
+│                    │ Subscriptions                            │
+│                    │ DevTools    │                             │
+│                    └─────────────┘                             │
+└─────────────────────────────────────────────────────────────────┘
+
+Flow Direction:
+├─ ───▶  = Forward data flow
+├─ ◄───  = Backward data flow
+└─ ▼     = Vertical state flow
+```
+
+---
+
+## Selector Constellation Patterns
+
+### 1. Selector Factory Architecture
+
+```mermaid
+graph TD
+    A[makeGetEntityById Factory] --> B[Create Selector Instance]
+    B --> C[Memoization Cache]
+    
+    D[Input: State + ID] --> B
+    E[Reselect Library] --> C
+    
+    C --> F{Cache Hit?}
+    F -->|Yes| G[Return Cached Result]
+    F -->|No| H[Compute New Result]
+    
+    H --> I[Extract Entity]
+    I --> J[Transform Data]
+    J --> K[Cache Result]
+    K --> L[Return Result]
+    
+    subgraph "Performance Optimization"
+        M[Stable References]
+        N[Shallow Equality]
+        O[Instance Isolation]
+    end
+    
+    C --> M
+    G --> N
+    B --> O
+    
+    style A fill:#e3f2fd
+    style C fill:#e8f5e8
+    style F fill:#fff3e0
+    style M fill:#f3e5f5
+    style N fill:#f3e5f5
+    style O fill:#f3e5f5
+```
+
+### 2. Complex Selector Composition
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                    SELECTOR CONSTELLATION                       │
+│                                                                 │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
+│  │   Basic     │     │  Composed   │     │  Complex    │       │
+│  │ Selectors   │────▶│  Selectors  │────▶│ Selectors   │       │
+│  │─────────────│     │─────────────│     │─────────────│       │
+│  │ getUser     │     │ getUserBy   │     │ getChannel  │       │
+│  │ getChannel  │     │ getChannel  │     │ WithMembers │       │
+│  │ getMessage  │     │ WithAuthor  │     │ AndMessages │       │
+│  └─────────────┘     └─────────────┘     └─────────────┘       │
+│         │                     │                     │           │
+│         ▼                     ▼                     ▼           │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
+│  │ createSel.  │     │ createSel.  │     │ createSel.  │       │
+│  │ + Memo      │     │ + Memo      │     │ + Memo      │       │
+│  │ + Instance  │     │ + Compose   │     │ + Deep Comp │       │
+│  └─────────────┘     └─────────────┘     └─────────────┘       │
+│         │                     │                     │           │
+│         └─────────────────────┼─────────────────────┘           │
+│                               ▼                                 │
+│                     ┌─────────────┐                             │
+│                     │   HOOKS     │                             │
+│                     │─────────────│                             │
+│                     │useSelector  │                             │
+│                     │useCallback  │                             │
+│                     │useMemo      │                             │
+│                     └─────────────┘                             │
+│                               │                                 │
+│                               ▼                                 │
+│                     ┌─────────────┐                             │
+│                     │ COMPONENTS  │                             │
+│                     │─────────────│                             │
+│                     │ Re-render   │                             │
+│                     │ Optimization│                             │
+│                     │ Performance │                             │
+│                     └─────────────┘                             │
+└─────────────────────────────────────────────────────────────────┘
+
+Performance Benefits:
+├─ Memo Cache    = Results cached until inputs change
+├─ Instance Iso. = Each component gets own cache
+├─ Stable Refs   = Same input = same reference
+└─ Compose Chain = Build complex from simple
+```
+
+---
+
+## Data Flow Sequences
+
+### 1. Message Send Sequence
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Component
+    participant S as Saga
+    participant N as Normalizer
+    participant A as API
+    participant R as Store
+
+    U->>C: Types message & hits send
+    C->>R: dispatch(sendMessage)
+    
+    Note over R: Optimistic Update
+    R->>C: Show pending message
+    
+    R->>S: Saga intercepts action
+    S->>N: Create optimistic entity
+    N->>R: Update normalized state
+    
+    S->>A: POST /messages
+    
+    alt Success Path
+        A->>S: 200 + message data
+        S->>N: Normalize response
+        N->>R: Merge final state
+        R->>C: Update UI with real data
+    else Error Path
+        A->>S: Error response
+        S->>R: Remove optimistic update
+        S->>R: dispatch(showError)
+        R->>C: Show error state
+    end
+    
+    C->>U: Updated message list
+```
+
+### 2. Real-time Event Processing
+
+```mermaid
+sequenceDiagram
+    participant M as Matrix Server
+    participant W as WebSocket
+    participant S as Saga
+    participant N as Normalizer
+    participant R as Store
+    participant C as Component
+
+    M->>W: Real-time event
+    W->>S: Forward event to saga
+    
+    S->>S: Route by event type
+    
+    alt Message Event
+        S->>N: Normalize message
+        N->>R: Merge into messages
+    else User Event
+        S->>N: Normalize user
+        N->>R: Merge into users
+    else Channel Event
+        S->>N: Normalize channel
+        N->>R: Merge into channels
+    end
+    
+    R->>C: Notify subscribers
+    C->>C: Re-render with new data
+    
+    Note over S,R: Batch Processing
+    S->>S: Collect events (500ms)
+    S->>N: Batch normalize
+    N->>R: Single state update
+```
+
+---
+
+## Error Handling & Recovery
+
+### 1. Saga Error Boundaries
+
+```ascii
+┌─────────────────────────────────────────────────────────────────┐
+│                    ERROR HANDLING COSMOS                        │
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │                ROOT SAGA SPAWNER                    │       │
+│  │                                                     │       │
+│  │  spawn(sagaA) ───┐                                  │       │
+│  │  spawn(sagaB) ───┼─── try/catch wrapper             │       │
+│  │  spawn(sagaC) ───┘                                  │       │
+│  │                                                     │       │
+│  │  if (error) {                                       │       │
+│  │    console.log(`Saga [${name}] failed`, error)     │       │
+│  │    // Saga dies, others continue                    │       │
+│  │  }                                                  │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              INDIVIDUAL SAGA RECOVERY               │       │
+│  │                                                     │       │
+│  │  try {                                              │       │
+│  │    yield call(apiFunction)                          │       │
+│  │  } catch (error) {                                  │       │
+│  │    if (error.status === 401) {                     │       │
+│  │      yield put(logout())                           │       │
+│  │    } else if (error.status >= 500) {               │       │
+│  │      yield put(showRetryDialog())                  │       │
+│  │    } else {                                         │       │
+│  │      yield put(showErrorMessage(error))            │       │
+│  │    }                                                │       │
+│  │  }                                                  │       │
+│  └─────────────────────────────────────────────────────┘       │
+│                              │                                 │
+│                              ▼                                 │
+│  ┌─────────────────────────────────────────────────────┐       │
+│  │              OPTIMISTIC UPDATE ROLLBACK             │       │
+│  │                                                     │       │
+│  │  1. Store optimistic ID mapping                     │       │
+│  │  2. Apply optimistic state changes                  │       │
+│  │  3. Show loading/pending UI                         │       │
+│  │                                                     │       │
+│  │  On Success:                                        │       │
+│  │    - Replace optimistic with real data              │       │
+│  │    - Update ID mappings                             │       │
+│  │    - Clear loading states                           │       │
+│  │                                                     │       │
+│  │  On Failure:                                        │       │
+│  │    - Remove optimistic entities                     │       │
+│  │    - Restore previous state                         │       │
+│  │    - Show error feedback                            │       │
+│  └─────────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2. State Recovery Patterns
+
+```mermaid
+graph TD
+    A[Error Detected] --> B{Error Type}
+    
+    B -->|Network| C[Retry Logic]
+    B -->|Auth| D[Re-authenticate]
+    B -->|Data| E[Rollback State]
+    B -->|Critical| F[Reset Store]
+    
+    C --> G{Retry Count}
+    G -->|< 3| H[Exponential Backoff]
+    G -->|>= 3| I[Show Manual Retry]
+    
+    H --> J[Attempt Request]
+    J --> K{Success?}
+    K -->|Yes| L[Update State]
+    K -->|No| G
+    
+    D --> M[Clear Auth Token]
+    M --> N[Redirect to Login]
+    
+    E --> O[Remove Optimistic]
+    O --> P[Restore Previous]
+    P --> Q[Notify User]
+    
+    F --> R[Clear All Data]
+    R --> S[Reload Application]
+    
+    style A fill:#ffebee
+    style C fill:#e8f5e8
+    style D fill:#fff3e0
+    style E fill:#f3e5f5
+    style F fill:#ffebee
+```
+
+---
+
+## Quick Reference: Visual Patterns
+
+### ASCII Art Legend
+```ascii
+┌────┐ = Process/Component    ├─ = Connection point
+│    │   boundary            └─ = Terminal connection
+└────┘                       ── = Horizontal line
+                              │  = Vertical line
+───▶ = Data flow direction    ▼  = Downward flow
+◄─── = Reverse flow          ▲  = Upward flow
+┌─┐  = Small component       ●  = Decision point
+```
+
+### Mermaid Chart Types Used
+- **Graph TD**: Top-down flow diagrams
+- **sequenceDiagram**: Time-based interactions
+- **Subgraphs**: Logical groupings
+- **Styling**: Color-coded components
+
+### Performance Indicators
+- 🟢 **Green**: Optimized/cached operations
+- 🟡 **Yellow**: Moderate performance impact
+- 🔴 **Red**: Expensive operations
+- 🔵 **Blue**: User interactions
+- 🟣 **Purple**: System processes
+
+---
+
+*"In space, no one can hear you debug. But with these visual guides, every state update is observable, every selector is mapped, and every saga flow is charted through the Redux Galaxy."*
+
+---
+
+**Related**: [Chapter 2: Redux Galaxy](../chapters/02-redux-galaxy.md) | [Redux Workshops](../workshops/redux-galaxy-workshops.md)
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/diagrams/redux-saga-flows.md b/opusdocs/hitchhiker/diagrams/redux-saga-flows.md
new file mode 100644
index 00000000..a3423b7a
--- /dev/null
+++ b/opusdocs/hitchhiker/diagrams/redux-saga-flows.md
@@ -0,0 +1,445 @@
+# Redux-Saga Flow Diagrams
+
+*"Every great saga has a beginning, middle, and end. These flows just happen to have generators, effects, and state updates."*
+
+This document provides detailed Mermaid diagrams for the most important Redux-Saga flows in zOS, making complex async patterns visually clear and debuggable.
+
+---
+
+## Core Saga Patterns
+
+### 1. Authentication Flow
+
+```mermaid
+graph TD
+    A[User Login Attempt] --> B[dispatch(login.request)]
+    B --> C[Login Saga Watcher]
+    C --> D{takeLatest}
+    D --> E[Cancel Previous Login]
+    E --> F[Execute Login Worker]
+    
+    F --> G[call(validateCredentials)]
+    G --> H{Credentials Valid?}
+    
+    H -->|Yes| I[call(fetchUserProfile)]
+    H -->|No| J[put(login.failure)]
+    
+    I --> K{Profile Fetch Success?}
+    K -->|Yes| L[Normalize User Data]
+    K -->|No| M[put(login.failure)]
+    
+    L --> N[put(normalized.receive)]
+    N --> O[put(login.success)]
+    O --> P[call(redirectToApp)]
+    
+    J --> Q[Update Error State]
+    M --> Q
+    Q --> R[Show Error Message]
+    
+    P --> S[User Authenticated]
+    
+    style A fill:#e3f2fd
+    style F fill:#f3e5f5
+    style L fill:#e8f5e8
+    style J fill:#ffebee
+    style M fill:#ffebee
+```
+
+### 2. Message Send with Optimistic Updates
+
+```mermaid
+graph TD
+    A[User Sends Message] --> B[dispatch(sendMessage)]
+    B --> C[Message Saga Watcher]
+    C --> D{takeEvery}
+    D --> E[Create Optimistic Entity]
+    
+    E --> F[Generate Temp ID]
+    F --> G[put(receiveOptimisticMessage)]
+    G --> H[UI Shows Pending]
+    
+    E --> I[call(sendMessageAPI)]
+    I --> J{API Success?}
+    
+    J -->|Yes| K[Extract Real Message Data]
+    J -->|No| L[call(removeOptimisticMessage)]
+    
+    K --> M[Normalize Response]
+    M --> N[put(normalized.receive)]
+    N --> O[Map Optimistic to Real ID]
+    O --> P[Update Message References]
+    
+    L --> Q[put(showErrorNotification)]
+    Q --> R[Restore Previous State]
+    
+    P --> S[UI Shows Sent Message]
+    R --> T[UI Shows Error State]
+    
+    style E fill:#fff3e0
+    style G fill:#fff3e0
+    style L fill:#ffebee
+    style Q fill:#ffebee
+```
+
+### 3. Real-time Event Processing
+
+```mermaid
+graph TD
+    A[Matrix Event Received] --> B[Event Router Saga]
+    B --> C{Event Type}
+    
+    C -->|m.room.message| D[Message Event Handler]
+    C -->|m.room.member| E[Member Event Handler]
+    C -->|m.presence| F[Presence Event Handler]
+    C -->|m.typing| G[Typing Event Handler]
+    
+    D --> H[Extract Message Data]
+    H --> I[call(mapMessageSenders)]
+    I --> J[Normalize Message]
+    J --> K[Batch Event Processing]
+    
+    E --> L[Extract Member Data]
+    L --> M[Update Channel Members]
+    M --> K
+    
+    F --> N[Extract Presence Data]
+    N --> O[Update User Status]
+    O --> K
+    
+    G --> P[Extract Typing Data]
+    P --> Q[Update Typing Indicators]
+    Q --> K
+    
+    K --> R[delay(BATCH_INTERVAL)]
+    R --> S[put(normalized.receive)]
+    S --> T[Components Re-render]
+    
+    style A fill:#e1f5fe
+    style K fill:#f3e5f5
+    style R fill:#fff3e0
+    style S fill:#e8f5e8
+```
+
+---
+
+## Advanced Flow Patterns
+
+### 4. Channel Creation with Encryption
+
+```mermaid
+graph TD
+    A[Create Channel Request] --> B[Channel Creation Saga]
+    B --> C[select(currentUser)]
+    C --> D[Validate Permissions]
+    
+    D --> E{Encryption Required?}
+    E -->|Yes| F[Generate Room Keys]
+    E -->|No| G[call(createPlainChannel)]
+    
+    F --> H[call(createEncryptedChannel)]
+    H --> I{Channel Created?}
+    G --> I
+    
+    I -->|Yes| J[Normalize Channel Data]
+    I -->|No| K[put(createChannel.failure)]
+    
+    J --> L[Add Creator as Admin]
+    L --> M[Setup Default Permissions]
+    M --> N[put(normalized.receive)]
+    
+    N --> O{Invite Members?}
+    O -->|Yes| P[call(inviteMembers)]
+    O -->|No| Q[put(createChannel.success)]
+    
+    P --> R[Send Invitations]
+    R --> Q
+    
+    K --> S[Show Error Message]
+    Q --> T[Navigate to Channel]
+    
+    style F fill:#f3e5f5
+    style H fill:#f3e5f5
+    style K fill:#ffebee
+    style P fill:#e8f5e8
+```
+
+### 5. File Upload with Progress
+
+```mermaid
+graph TD
+    A[User Selects File] --> B[dispatch(uploadFile)]
+    B --> C[File Upload Saga]
+    C --> D[Validate File]
+    
+    D --> E{File Valid?}
+    E -->|No| F[put(uploadFile.failure)]
+    E -->|Yes| G[Create Upload Progress Tracker]
+    
+    G --> H[Create Uploadable Instance]
+    H --> I[call(uploadToS3)]
+    
+    I --> J[Monitor Upload Progress]
+    J --> K[put(updateUploadProgress)]
+    K --> L{Upload Complete?}
+    
+    L -->|No| J
+    L -->|Yes| M[Extract File Metadata]
+    
+    M --> N[Create Message with File]
+    N --> O[dispatch(sendMessage)]
+    O --> P[Link to Message Saga]
+    
+    F --> Q[Show Upload Error]
+    P --> R[Message Sent with File]
+    
+    style D fill:#fff3e0
+    style G fill:#e8f5e8
+    style J fill:#f3e5f5
+    style F fill:#ffebee
+```
+
+---
+
+## Error Handling Flows
+
+### 6. Network Retry Logic
+
+```mermaid
+graph TD
+    A[API Call Fails] --> B[Extract Error Info]
+    B --> C{Error Type}
+    
+    C -->|Network| D[Network Retry Flow]
+    C -->|Auth| E[Authentication Flow]
+    C -->|Rate Limit| F[Rate Limit Flow]
+    C -->|Server Error| G[Server Error Flow]
+    
+    D --> H[Increment Retry Count]
+    H --> I{Retry Count < MAX}
+    I -->|Yes| J[Exponential Backoff]
+    I -->|No| K[put(networkError)]
+    
+    J --> L[delay(backoffMs)]
+    L --> M[Retry Original Call]
+    M --> N{Success?}
+    N -->|Yes| O[Continue Normal Flow]
+    N -->|No| H
+    
+    E --> P[Clear Auth Tokens]
+    P --> Q[put(logout)]
+    Q --> R[Redirect to Login]
+    
+    F --> S[Extract Retry-After Header]
+    S --> T[delay(retryAfterMs)]
+    T --> U[Retry Original Call]
+    
+    G --> V{Error Code}
+    V -->|500-502| W[Show Retry Dialog]
+    V -->|503| X[Show Maintenance Message]
+    V -->|Other| Y[Show Generic Error]
+    
+    K --> Z[Show Network Error]
+    O --> AA[Success State]
+    
+    style D fill:#fff3e0
+    style E fill:#ffebee
+    style F fill:#f3e5f5
+    style G fill:#ffebee
+    style K fill:#ffebee
+```
+
+### 7. Optimistic Update Rollback
+
+```mermaid
+graph TD
+    A[Optimistic Action] --> B[Store Rollback Info]
+    B --> C[Apply Optimistic State]
+    C --> D[call(apiFunction)]
+    
+    D --> E{API Success?}
+    E -->|Yes| F[Merge Real Data]
+    E -->|No| G[Extract Rollback Info]
+    
+    F --> H[Update ID Mappings]
+    H --> I[Clear Optimistic Flags]
+    I --> J[put(operationSuccess)]
+    
+    G --> K[Remove Optimistic Entities]
+    K --> L[Restore Previous State]
+    L --> M[put(operationFailure)]
+    
+    M --> N[Show User Feedback]
+    N --> O{Retryable?}
+    O -->|Yes| P[Show Retry Option]
+    O -->|No| Q[Show Error Message]
+    
+    J --> R[Success State]
+    P --> S[User Can Retry]
+    Q --> T[Error State]
+    
+    style C fill:#fff3e0
+    style G fill:#f3e5f5
+    style K fill:#ffebee
+    style L fill:#ffebee
+```
+
+---
+
+## Saga Orchestration Patterns
+
+### 8. Multi-Step Workflow
+
+```mermaid
+graph TD
+    A[Complex Workflow Start] --> B[Step 1: Validate Input]
+    B --> C{Valid?}
+    C -->|No| D[put(workflowError)]
+    C -->|Yes| E[Step 2: Fetch Dependencies]
+    
+    E --> F[call(fetchUserData)]
+    F --> G[call(fetchChannelData)]
+    G --> H[call(fetchPermissions)]
+    
+    H --> I[Step 3: Process Data]
+    I --> J[Normalize All Data]
+    J --> K[Validate Relationships]
+    
+    K --> L{Data Consistent?}
+    L -->|No| M[put(dataInconsistency)]
+    L -->|Yes| N[Step 4: Apply Changes]
+    
+    N --> O[call(updateServer)]
+    O --> P{Server Success?}
+    P -->|No| Q[Rollback Changes]
+    P -->|Yes| R[Step 5: Finalize]
+    
+    R --> S[Update Local State]
+    S --> T[Notify Components]
+    T --> U[put(workflowSuccess)]
+    
+    Q --> V[Restore Previous State]
+    V --> W[put(workflowFailure)]
+    
+    D --> X[Error State]
+    M --> X
+    W --> X
+    U --> Y[Success State]
+    
+    style B fill:#e3f2fd
+    style I fill:#f3e5f5
+    style N fill:#e8f5e8
+    style Q fill:#ffebee
+    style X fill:#ffebee
+```
+
+### 9. Concurrent Operations Management
+
+```mermaid
+graph TD
+    A[Multiple Operations Triggered] --> B[Operation Coordinator]
+    B --> C[fork(operation1)]
+    B --> D[fork(operation2)]
+    B --> E[fork(operation3)]
+    
+    C --> F[API Call 1]
+    D --> G[API Call 2]
+    E --> H[API Call 3]
+    
+    F --> I[Success 1]
+    G --> J[Success 2]
+    H --> K[Success 3]
+    
+    F --> L[Error 1]
+    G --> M[Error 2]
+    H --> N[Error 3]
+    
+    I --> O[Result Aggregator]
+    J --> O
+    K --> O
+    
+    L --> P[Error Handler]
+    M --> P
+    N --> P
+    
+    O --> Q{All Successful?}
+    Q -->|Yes| R[Merge All Results]
+    Q -->|No| S[Partial Success Handler]
+    
+    P --> T{Critical Error?}
+    T -->|Yes| U[Cancel All Operations]
+    T -->|No| V[Continue with Others]
+    
+    R --> W[put(allOperationsSuccess)]
+    S --> X[put(partialSuccess)]
+    U --> Y[put(operationsCancelled)]
+    
+    style B fill:#f3e5f5
+    style O fill:#e8f5e8
+    style P fill:#fff3e0
+    style U fill:#ffebee
+```
+
+---
+
+## Performance Optimization Flows
+
+### 10. Batched State Updates
+
+```mermaid
+graph TD
+    A[High-Frequency Events] --> B[Event Buffer]
+    B --> C[Accumulate Events]
+    C --> D{Buffer Full OR Timeout?}
+    
+    D -->|No| C
+    D -->|Yes| E[Process Batch]
+    
+    E --> F[Group by Entity Type]
+    F --> G[Merge Duplicate Updates]
+    G --> H[Normalize Batch]
+    
+    H --> I[Single State Update]
+    I --> J[put(normalized.receive)]
+    J --> K[Components Re-render Once]
+    
+    style B fill:#f3e5f5
+    style E fill:#e8f5e8
+    style I fill:#e8f5e8
+    style K fill:#e8f5e8
+```
+
+---
+
+## Quick Reference: Saga Effect Patterns
+
+### Common Effect Combinations
+
+```mermaid
+graph LR
+    A[takeLatest] --> B[Cancel Previous]
+    C[takeEvery] --> D[Fork All]
+    E[takeLeading] --> F[Ignore New]
+    
+    G[call] --> H[Blocking Call]
+    I[fork] --> J[Non-blocking]
+    K[spawn] --> L[Detached Process]
+    
+    M[put] --> N[Dispatch Action]
+    O[select] --> P[Read State]
+    Q[delay] --> R[Wait Time]
+    
+    style A fill:#e3f2fd
+    style C fill:#e3f2fd
+    style E fill:#e3f2fd
+    style G fill:#f3e5f5
+    style I fill:#f3e5f5
+    style K fill:#f3e5f5
+```
+
+---
+
+*"In the Redux Galaxy, every saga tells a story. These diagrams help you read that story, debug its plot twists, and write sequels that don't crash the universe."*
+
+---
+
+**Related**: [Redux Galaxy Visuals](./redux-galaxy-visuals.md) | [Chapter 2: Redux Galaxy](../chapters/02-redux-galaxy.md)
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/patterns/README.md b/opusdocs/hitchhiker/patterns/README.md
new file mode 100644
index 00000000..fcb989f4
--- /dev/null
+++ b/opusdocs/hitchhiker/patterns/README.md
@@ -0,0 +1,220 @@
+# The Hitchhiker's Guide to zOS - Pattern Library
+
+*"Patterns are like towels - you should always know where yours are."*
+
+This directory contains the comprehensive pattern library for zOS. Each pattern is a reusable solution to common problems, complete with code examples, explanations, and usage guidelines.
+
+## Pattern Categories
+
+### 🏗️ Architectural Patterns
+Fundamental design patterns that shape the overall application structure.
+
+- [Redux-Saga-Normalizr Trinity](./architectural/redux-saga-normalizr-trinity.md) - The core pattern that powers zOS
+- [Event-Driven Architecture](./architectural/event-driven-architecture.md) - How events flow through the system
+- [Modular Application Design](./architectural/modular-app-design.md) - Organizing features as self-contained apps
+- [Normalized State Design](./architectural/normalized-state-design.md) - Structuring relational data in Redux
+
+### 🔄 State Management Patterns
+Patterns for managing application state effectively and predictably.
+
+- [Entity Normalization](./state-management/entity-normalization.md) - Flattening nested data structures
+- [Optimistic Updates](./state-management/optimistic-updates.md) - Immediate UI updates with rollback capability
+- [Selector Composition](./state-management/selector-composition.md) - Building complex selectors from simple ones
+- [Cross-Slice Communication](./state-management/cross-slice-communication.md) - Coordinating between different state slices
+
+### ⚡ Async Flow Patterns
+Patterns for managing asynchronous operations and side effects.
+
+- [Saga Orchestration](./async-flow/saga-orchestration.md) - Coordinating complex async workflows
+- [Error Handling Flows](./async-flow/error-handling-flows.md) - Robust error management in sagas
+- [Cancellation Patterns](./async-flow/cancellation-patterns.md) - Cancelling operations cleanly
+- [Racing Operations](./async-flow/racing-operations.md) - Competitive async operations
+- [Background Tasks](./async-flow/background-tasks.md) - Long-running operations that don't block UI
+
+### 🌐 Real-time Communication Patterns
+Patterns for building responsive, real-time user experiences.
+
+- [Matrix Event Processing](./realtime/matrix-event-processing.md) - Handling Matrix protocol events
+- [Real-time State Sync](./realtime/realtime-state-sync.md) - Keeping client state synchronized
+- [Connection Resilience](./realtime/connection-resilience.md) - Handling network interruptions gracefully
+- [Event Ordering](./realtime/event-ordering.md) - Ensuring proper event sequence
+- [Typing Indicators](./realtime/typing-indicators.md) - Real-time user activity feedback
+
+### 🔗 Web3 Integration Patterns
+Patterns for seamlessly integrating blockchain functionality.
+
+- [Wallet Connection Management](./web3/wallet-connection-management.md) - Multi-wallet support and switching
+- [Transaction Flow Patterns](./web3/transaction-flow-patterns.md) - Safe and user-friendly transaction handling
+- [Smart Contract Interaction](./web3/smart-contract-interaction.md) - Type-safe contract integration
+- [Gas Optimization](./web3/gas-optimization.md) - Minimizing transaction costs
+- [Error Recovery](./web3/error-recovery.md) - Handling blockchain-specific errors
+
+### 🧩 Component Patterns
+Patterns for building reusable, maintainable UI components.
+
+- [Container-Presenter Pattern](./component/container-presenter-pattern.md) - Separating data and presentation logic
+- [Compound Components](./component/compound-components.md) - Building flexible, composable components
+- [Render Props](./component/render-props.md) - Sharing logic between components
+- [Custom Hooks](./component/custom-hooks.md) - Extracting and reusing stateful logic
+- [Error Boundaries](./component/error-boundaries.md) - Graceful error handling in React
+
+### 🚀 Performance Patterns
+Patterns for optimizing application performance at all levels.
+
+- [Memoization Strategies](./performance/memoization-strategies.md) - Preventing unnecessary recalculations
+- [Virtual Scrolling](./performance/virtual-scrolling.md) - Rendering large lists efficiently
+- [Code Splitting](./performance/code-splitting.md) - Loading code on demand
+- [Asset Optimization](./performance/asset-optimization.md) - Optimizing images and media
+- [Bundle Analysis](./performance/bundle-analysis.md) - Understanding and optimizing build output
+
+### 🧪 Testing Patterns
+Patterns for testing complex, interconnected systems.
+
+- [Saga Testing](./testing/saga-testing.md) - Testing async flows and side effects
+- [Component Integration Testing](./testing/component-integration-testing.md) - Testing components with real dependencies
+- [Mock Service Patterns](./testing/mock-service-patterns.md) - Creating reliable test doubles
+- [End-to-End Testing](./testing/e2e-testing.md) - Testing complete user workflows
+- [Performance Testing](./testing/performance-testing.md) - Ensuring performance requirements
+
+### 🔧 Development Workflow Patterns
+Patterns for maintaining high productivity and code quality.
+
+- [Type-Safe Development](./workflow/type-safe-development.md) - Leveraging TypeScript effectively
+- [Error Monitoring](./workflow/error-monitoring.md) - Tracking and resolving production issues
+- [Feature Flag Management](./workflow/feature-flag-management.md) - Safe feature rollouts
+- [Code Review Patterns](./workflow/code-review-patterns.md) - Effective collaboration practices
+- [Debugging Workflows](./workflow/debugging-workflows.md) - Systematic problem-solving approaches
+
+## Pattern Template
+
+Each pattern follows a consistent structure:
+
+```markdown
+# Pattern Name
+
+## Problem
+What specific problem does this pattern solve?
+
+## Solution
+How does the pattern solve the problem?
+
+## Implementation
+Step-by-step code examples and explanations.
+
+## Usage Examples
+Real-world usage from zOS codebase.
+
+## Benefits
+What advantages does this pattern provide?
+
+## Trade-offs
+What are the costs or limitations?
+
+## Related Patterns
+Links to complementary or alternative patterns.
+
+## Testing Strategy
+How to test code that uses this pattern.
+
+## Common Pitfalls
+Mistakes to avoid when implementing this pattern.
+```
+
+## Usage Guidelines
+
+### When to Use Patterns
+- **Problem Recognition**: You encounter a situation the pattern addresses
+- **Code Review**: Patterns provide a shared vocabulary for discussing solutions
+- **Architecture Decisions**: Patterns help evaluate different approaches
+- **Onboarding**: Patterns accelerate learning for new team members
+
+### When NOT to Use Patterns
+- **Over-Engineering**: Don't use complex patterns for simple problems
+- **Pattern Obsession**: Don't force patterns where they don't fit
+- **Premature Optimization**: Use simple solutions first, patterns when needed
+- **Cargo Culting**: Understand WHY a pattern works, not just HOW
+
+### Adaptation Guidelines
+- Patterns are starting points, not rigid rules
+- Adapt patterns to your specific context and constraints
+- Combine patterns thoughtfully when solving complex problems
+- Document your adaptations for future reference
+
+## Pattern Relationships
+
+### Complementary Patterns
+These patterns work well together:
+- **Redux-Saga-Normalizr Trinity** + **Optimistic Updates**
+- **Container-Presenter Pattern** + **Custom Hooks**
+- **Saga Orchestration** + **Error Handling Flows**
+- **Real-time State Sync** + **Connection Resilience**
+
+### Alternative Patterns
+These patterns solve similar problems with different trade-offs:
+- **Render Props** vs **Custom Hooks**
+- **Container-Presenter** vs **Custom Hooks**
+- **Optimistic Updates** vs **Traditional Request-Response**
+
+### Pattern Evolution
+Some patterns build upon others:
+- **Entity Normalization** → **Selector Composition**
+- **Basic Saga Flow** → **Saga Orchestration**
+- **Simple Components** → **Compound Components**
+
+## Contributing to the Pattern Library
+
+### Adding New Patterns
+1. Identify a recurring problem in the codebase
+2. Document the solution using the pattern template
+3. Include real examples from zOS where possible
+4. Test the pattern implementation thoroughly
+5. Review with team for accuracy and clarity
+
+### Updating Existing Patterns
+1. Document new use cases or variations
+2. Add improved examples or implementations
+3. Update related patterns and cross-references
+4. Maintain backward compatibility when possible
+
+### Pattern Quality Standards
+- **Clarity**: Patterns should be easy to understand and follow
+- **Completeness**: Include all necessary information for implementation
+- **Accuracy**: Code examples should work and be tested
+- **Relevance**: Patterns should solve real problems encountered in zOS
+
+## Pattern Evolution and Deprecation
+
+### Evolution Triggers
+- New language or framework features
+- Changed requirements or constraints
+- Better solutions discovered through experience
+- Performance or maintainability improvements
+
+### Deprecation Process
+1. **Mark as Deprecated**: Add deprecation notice with alternatives
+2. **Migration Guide**: Provide clear path to newer patterns
+3. **Gradual Migration**: Update existing code over time
+4. **Final Removal**: Remove pattern after all usage is migrated
+
+---
+
+*"The secret to creativity is knowing how to hide your sources." - Einstein (allegedly)*
+
+*"The secret to maintainable code is knowing which patterns to use and when." - The Editors (definitely)*
+
+---
+
+## Quick Navigation
+
+- **[Introduction](../00-introduction.md)** - Start here if you're new
+- **[Chapters](../chapters/)** - Full educational content
+- **[Workshops](../workshops/)** - Hands-on exercises  
+- **[Diagrams](../diagrams/)** - Visual explanations
+- **[Quick Reference](../reference/)** - Cheat sheets and summaries
+
+## External Resources
+
+- **[Redux Patterns](https://redux.js.org/style-guide/style-guide)** - Official Redux style guide
+- **[React Patterns](https://reactpatterns.com/)** - Common React patterns
+- **[JavaScript Patterns](https://addyosmani.com/resources/essentialjsdesignpatterns/)** - Essential JS design patterns
+- **[Matrix Spec](https://matrix.org/docs/spec/)** - Matrix protocol specification
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/reference/README.md b/opusdocs/hitchhiker/reference/README.md
new file mode 100644
index 00000000..b495ec27
--- /dev/null
+++ b/opusdocs/hitchhiker/reference/README.md
@@ -0,0 +1,348 @@
+# The Hitchhiker's Guide to zOS - Quick Reference
+
+*"A towel, it says, is about the most massively useful thing an interstellar hitchhiker can have. A good quick reference is about the most massively useful thing a developer can have."*
+
+This directory contains quick reference materials, cheat sheets, and lookup resources for zOS development. When you need to find something fast, this is your towel.
+
+## Reference Categories
+
+### 📚 Core References
+Essential lookup materials for daily development.
+
+- **[API Reference](./api-reference.md)** - Complete API documentation
+- **[Pattern Quick Reference](./pattern-quick-reference.md)** - Common patterns at a glance
+- **[TypeScript Cheat Sheet](./typescript-cheat-sheet.md)** - zOS-specific TypeScript patterns
+- **[Redux Flow Diagrams](./redux-flow-diagrams.md)** - Visual flowcharts for state management
+
+### 🔧 Development Tools
+References for development workflow and tooling.
+
+- **[CLI Commands](./cli-commands.md)** - Essential command-line operations
+- **[Debugging Guide](./debugging-guide.md)** - Systematic debugging approaches
+- **[IDE Setup](./ide-setup.md)** - Optimal development environment configuration
+- **[Error Code Reference](./error-code-reference.md)** - Common errors and solutions
+
+### 🌐 Integration References
+Quick guides for external service integration.
+
+- **[Matrix Protocol Reference](./matrix-protocol-reference.md)** - Matrix SDK usage patterns
+- **[Web3 Integration Guide](./web3-integration-guide.md)** - Blockchain integration essentials
+- **[Testing Reference](./testing-reference.md)** - Testing utilities and patterns
+
+### 📋 Cheat Sheets
+One-page references for specific topics.
+
+- **[Redux-Saga Effects](./redux-saga-effects.md)** - All saga effects with examples
+- **[Selector Patterns](./selector-patterns.md)** - Common selector compositions
+- **[Component Patterns](./component-patterns.md)** - React component best practices
+- **[Performance Optimization](./performance-optimization.md)** - Quick performance wins
+
+## Quick Navigation by Task
+
+### "I need to..."
+
+#### State Management
+- **Add new entity type** → [Entity Schema Reference](./entity-schema-reference.md)
+- **Create complex selector** → [Selector Patterns](./selector-patterns.md)
+- **Handle async operation** → [Redux-Saga Effects](./redux-saga-effects.md)
+- **Debug state changes** → [Redux DevTools Guide](./redux-devtools-guide.md)
+
+#### Real-time Features
+- **Send Matrix message** → [Matrix Quick Start](./matrix-quick-start.md)
+- **Handle Matrix events** → [Matrix Event Reference](./matrix-event-reference.md)
+- **Implement typing indicators** → [Real-time Patterns](./realtime-patterns.md)
+- **Debug connection issues** → [Matrix Debugging](./matrix-debugging.md)
+
+#### Web3 Integration
+- **Connect wallet** → [Wallet Connection Guide](./wallet-connection-guide.md)
+- **Send transaction** → [Transaction Patterns](./transaction-patterns.md)
+- **Handle errors** → [Web3 Error Reference](./web3-error-reference.md)
+- **Test blockchain features** → [Web3 Testing Guide](./web3-testing-guide.md)
+
+#### Component Development
+- **Create new component** → [Component Checklist](./component-checklist.md)
+- **Optimize performance** → [Performance Optimization](./performance-optimization.md)
+- **Handle errors** → [Error Boundary Patterns](./error-boundary-patterns.md)
+- **Test components** → [Component Testing Guide](./component-testing-guide.md)
+
+#### Testing
+- **Test saga flows** → [Saga Testing Reference](./saga-testing-reference.md)
+- **Mock external services** → [Mocking Patterns](./mocking-patterns.md)
+- **Write integration tests** → [Integration Testing Guide](./integration-testing-guide.md)
+- **Debug test failures** → [Test Debugging Guide](./test-debugging-guide.md)
+
+#### Production & Deployment
+- **Monitor performance** → [Monitoring Setup](./monitoring-setup.md)
+- **Handle errors** → [Error Tracking Guide](./error-tracking-guide.md)
+- **Deploy features** → [Deployment Checklist](./deployment-checklist.md)
+- **Troubleshoot issues** → [Production Troubleshooting](./production-troubleshooting.md)
+
+## Reference Format
+
+Each reference document follows a consistent format for quick scanning:
+
+### Quick Reference Template
+```markdown
+# Topic Quick Reference
+
+## TL;DR
+The essential information in 2-3 bullets.
+
+## Common Patterns
+Most frequently used patterns with code examples.
+
+## API Summary
+Key functions/methods with signatures and examples.
+
+## Troubleshooting
+Common issues and their solutions.
+
+## See Also
+Links to related references and deeper documentation.
+```
+
+## Glossary and Terminology
+
+### [Complete Glossary](./glossary.md)
+Comprehensive definitions of all terms used in zOS development.
+
+### Quick Term Lookup
+Most commonly referenced terms:
+
+- **Action**: Redux action object describing state changes
+- **Effect**: Redux-Saga instruction for side effects
+- **Entity**: Normalized data object with unique ID
+- **Saga**: Generator function handling async operations
+- **Selector**: Function to extract data from Redux state
+- **Slice**: Redux Toolkit feature-specific state manager
+
+## Keyboard Shortcuts and Commands
+
+### Development Environment
+```bash
+# Start development server
+npm run dev
+
+# Run tests in watch mode
+npm run test:watch
+
+# Type checking
+npm run type-check
+
+# Linting
+npm run lint
+
+# Build for production
+npm run build
+```
+
+### IDE Shortcuts (VSCode)
+- **Go to Definition**: `F12`
+- **Find References**: `Shift+F12`
+- **Refactor**: `F2`
+- **Quick Fix**: `Ctrl+.` (Cmd+. on Mac)
+- **Format Document**: `Alt+Shift+F`
+
+### Redux DevTools
+- **Time Travel**: Click on any action in the log
+- **State Diff**: Toggle diff view to see changes
+- **Trace**: Enable to see component update causes
+- **Persist**: Keep state between page reloads
+
+## Common Code Snippets
+
+### Redux-Saga Patterns
+```typescript
+// Basic saga flow
+function* handleAction(action: PayloadAction<Data>) {
+  try {
+    const result = yield call(api.fetchData, action.payload);
+    yield put(actionSuccess(result));
+  } catch (error) {
+    yield put(actionFailure(error.message));
+  }
+}
+
+// Optimistic update pattern
+function* optimisticUpdate(action: PayloadAction<UpdateData>) {
+  yield put(applyOptimisticUpdate(action.payload));
+  try {
+    const result = yield call(api.update, action.payload);
+    yield put(confirmUpdate(result));
+  } catch (error) {
+    yield put(revertOptimisticUpdate(action.payload));
+    yield put(updateError(error.message));
+  }
+}
+```
+
+### Selector Patterns
+```typescript
+// Basic entity selector
+const selectUser = (state: RootState, userId: string) =>
+  state.normalized.users[userId];
+
+// Memoized derived data
+const selectUserWithChannels = createSelector(
+  [selectUser, selectUserChannels],
+  (user, channels) => ({ ...user, channels })
+);
+
+// Cross-slice selector
+const selectConversationWithUsers = createSelector(
+  [selectConversation, selectUsers],
+  (conversation, users) => ({
+    ...conversation,
+    participants: conversation.participantIds.map(id => users[id])
+  })
+);
+```
+
+### Component Patterns
+```typescript
+// Container component pattern
+const UserProfileContainer = ({ userId }: { userId: string }) => {
+  const user = useSelector(state => selectUser(state, userId));
+  const dispatch = useDispatch();
+  
+  const handleUpdate = useCallback(
+    (updates: UserUpdates) => dispatch(updateUser({ userId, updates })),
+    [dispatch, userId]
+  );
+  
+  return <UserProfile user={user} onUpdate={handleUpdate} />;
+};
+
+// Custom hook pattern
+const useUserProfile = (userId: string) => {
+  const user = useSelector(state => selectUser(state, userId));
+  const dispatch = useDispatch();
+  
+  const updateUser = useCallback(
+    (updates: UserUpdates) => dispatch(updateUserAction({ userId, updates })),
+    [dispatch, userId]
+  );
+  
+  return { user, updateUser };
+};
+```
+
+## File and Directory Structure Reference
+
+### Key Directories
+```
+src/
+├── apps/                 # Feature applications
+├── components/          # Shared components
+├── lib/                 # Utility functions and services
+├── store/               # Redux store and slices
+│   ├── normalized/      # Normalized entity state
+│   ├── [feature]/       # Feature-specific state
+│   └── saga.ts         # Root saga
+├── types/               # TypeScript type definitions
+└── test/                # Test utilities and setup
+```
+
+### Naming Conventions
+- **Components**: PascalCase (`UserProfile`, `MessageList`)
+- **Files**: kebab-case (`user-profile.tsx`, `message-list.scss`)
+- **Hooks**: camelCase starting with 'use' (`useUserProfile`)
+- **Actions**: camelCase (`updateUser`, `sendMessage`)
+- **Selectors**: camelCase starting with 'select' (`selectUser`)
+
+## Environment Configuration
+
+### Development
+```bash
+NODE_ENV=development
+REACT_APP_API_URL=http://localhost:3001
+REACT_APP_MATRIX_HOMESERVER=https://matrix.dev.example.com
+REACT_APP_WEB3_NETWORK=sepolia
+```
+
+### Production
+```bash
+NODE_ENV=production
+REACT_APP_API_URL=https://api.zos.example.com
+REACT_APP_MATRIX_HOMESERVER=https://matrix.zos.example.com
+REACT_APP_WEB3_NETWORK=mainnet
+```
+
+## Performance Benchmarks
+
+### Bundle Size Targets
+- **Initial Bundle**: < 500KB gzipped
+- **Feature Chunks**: < 100KB gzipped
+- **Vendor Chunks**: < 300KB gzipped
+
+### Runtime Performance
+- **First Contentful Paint**: < 1s
+- **Time to Interactive**: < 3s
+- **Component Render**: < 16ms (60fps)
+
+### Memory Usage
+- **Initial Load**: < 50MB
+- **After 30min Usage**: < 100MB
+- **Memory Leaks**: None detected
+
+## Browser Support
+
+### Supported Browsers
+- **Chrome**: 88+
+- **Firefox**: 85+
+- **Safari**: 14+
+- **Edge**: 88+
+
+### Required Features
+- ES2020 support
+- WebAssembly
+- IndexedDB
+- WebRTC (for Matrix calls)
+- Crypto API (for encryption)
+
+## External Dependencies
+
+### Core Dependencies
+```json
+{
+  "react": "^18.0.0",
+  "redux": "^4.2.0",
+  "redux-saga": "^1.2.0",
+  "normalizr": "^3.6.0",
+  "matrix-js-sdk": "^24.0.0"
+}
+```
+
+### Development Dependencies
+```json
+{
+  "typescript": "^4.9.0",
+  "@testing-library/react": "^13.0.0",
+  "vitest": "^0.28.0",
+  "eslint": "^8.0.0"
+}
+```
+
+---
+
+*"Don't Panic" - and when you do panic, check the quick reference first.*
+
+*"Time is an illusion. Lunchtime doubly so. But deadlines are real, so use these references to work efficiently." - The Editors*
+
+---
+
+## Meta Information
+
+**Last Updated**: 2025-07-31
+**Contributors**: Guide Architect, Pattern Explorer, Integration Synthesizer
+**Review Cycle**: Monthly updates, continuous improvement
+**Feedback**: Submit improvements via issues or pull requests
+
+## External Resources
+
+- **[Redux Toolkit RTK Query](https://redux-toolkit.js.org/rtk-query/overview)** - Modern Redux patterns
+- **[React 18 Features](https://reactjs.org/blog/2022/03/29/react-v18.html)** - Latest React capabilities
+- **[Matrix Specification](https://matrix.org/docs/spec/)** - Matrix protocol details
+- **[Web3 Best Practices](https://consensys.github.io/smart-contract-best-practices/)** - Blockchain development
+- **[TypeScript Handbook](https://www.typescriptlang.org/docs/)** - TypeScript reference
+- **[Accessibility Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)** - WCAG 2.1 reference
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/workshops/README.md b/opusdocs/hitchhiker/workshops/README.md
new file mode 100644
index 00000000..729fcec6
--- /dev/null
+++ b/opusdocs/hitchhiker/workshops/README.md
@@ -0,0 +1,326 @@
+# The Hitchhiker's Guide to zOS - Workshops
+
+*"Learning without doing is like reading about swimming while drowning."*
+
+This directory contains hands-on workshops and exercises designed to cement your understanding of zOS patterns through practical implementation. Every concept you learn should be something you can build.
+
+## Workshop Philosophy
+
+### Learn by Building
+Every workshop is built around creating something functional and meaningful. You won't be building contrived examples - you'll be implementing real patterns that power real features in zOS.
+
+### Progressive Complexity
+Workshops are designed with the "towel principle" - start simple enough that you always know where you are, then progressively add complexity as your understanding grows.
+
+### Real-World Context
+All exercises are based on actual patterns used in zOS. When you complete a workshop, you'll understand not just how to implement the pattern, but why it was chosen and when to use it.
+
+## Difficulty Levels
+
+### 🟢 Towel Level (Beginner)
+*"Don't Panic" - You're just getting started*
+- Basic understanding required
+- Step-by-step guidance provided
+- Focus on fundamental concepts
+- Estimated time: 30-60 minutes
+
+### 🟡 Babel Fish (Intermediate) 
+*"Translation in progress" - Converting knowledge to skill*
+- Some experience with the concepts needed
+- High-level guidance with implementation details
+- Focus on practical application
+- Estimated time: 1-2 hours
+
+### 🟠 Improbability Drive (Advanced)
+*"Making the impossible possible" - Complex implementations*
+- Solid understanding of fundamentals required
+- Problem statement with minimal guidance
+- Focus on creative problem-solving
+- Estimated time: 2-4 hours
+
+### 🔴 Deep Thought (Expert)
+*"Computing the ultimate answer" - Architectural challenges*
+- Expert-level understanding required
+- Open-ended problems with multiple solutions
+- Focus on system design and optimization
+- Estimated time: 4+ hours
+
+## Workshop Categories
+
+### 🏗️ Foundation Workshops
+Build your understanding of core zOS patterns.
+
+#### [Setup and Architecture](./foundation/)
+- **Development Environment Setup** (🟢 Towel Level)
+- **Project Structure Deep Dive** (🟢 Towel Level)
+- **Technology Stack Integration** (🟡 Babel Fish)
+
+### 🔄 State Management Workshops
+Master Redux, sagas, and normalized state.
+
+#### [Redux Fundamentals](./state-management/redux-fundamentals/)
+- **Create Your First Normalized Schema** (🟢 Towel Level)
+- **Build Memoized Selectors** (🟡 Babel Fish)
+- **Implement Cross-Slice Communication** (🟠 Improbability Drive)
+
+#### [Saga Mastery](./state-management/saga-mastery/)
+- **Basic Saga Effects** (🟢 Towel Level)
+- **Orchestrate Complex Flows** (🟡 Babel Fish)
+- **Error Handling and Recovery** (🟠 Improbability Drive)
+- **Real-time Data Synchronization** (🔴 Deep Thought)
+
+### 🌐 Real-time Communication Workshops
+Build chat and real-time features.
+
+#### [Matrix Integration](./realtime/matrix-integration/)
+- **Send Your First Matrix Message** (🟢 Towel Level)
+- **Build a Chat Room Interface** (🟡 Babel Fish)
+- **Implement Typing Indicators** (🟠 Improbability Drive)
+- **End-to-End Encryption Handling** (🔴 Deep Thought)
+
+#### [Event-Driven Architecture](./realtime/event-driven/)
+- **Event Processing Pipeline** (🟡 Babel Fish)
+- **Real-time State Synchronization** (🟠 Improbability Drive)
+- **Connection Resilience System** (🔴 Deep Thought)
+
+### 🔗 Web3 Integration Workshops
+Build blockchain features without the complexity.
+
+#### [Wallet Integration](./web3/wallet-integration/)
+- **Connect Your First Wallet** (🟢 Towel Level)
+- **Handle Network Switching** (🟡 Babel Fish)
+- **Multi-Wallet Support System** (🟠 Improbability Drive)
+
+#### [Transaction Patterns](./web3/transactions/)
+- **Safe Token Transfers** (🟡 Babel Fish)
+- **Smart Contract Interactions** (🟠 Improbability Drive)
+- **Gas Optimization Strategies** (🔴 Deep Thought)
+
+### 🧩 Component Architecture Workshops
+Build sophisticated, reusable UI components.
+
+#### [React Patterns](./components/react-patterns/)
+- **Container-Presenter Split** (🟢 Towel Level)
+- **Compound Component Design** (🟡 Babel Fish)
+- **Custom Hook Extraction** (🟠 Improbability Drive)
+
+#### [Performance Optimization](./components/performance/)
+- **Memoization Strategies** (🟡 Babel Fish)
+- **Virtual Scrolling Implementation** (🟠 Improbability Drive)
+- **Bundle Optimization** (🔴 Deep Thought)
+
+### 🧪 Testing Workshops
+Test complex, interconnected systems effectively.
+
+#### [Testing Strategies](./testing/strategies/)
+- **Unit Testing Redux Logic** (🟢 Towel Level)
+- **Integration Testing Sagas** (🟡 Babel Fish)
+- **End-to-End User Flows** (🟠 Improbability Drive)
+
+#### [Advanced Testing](./testing/advanced/)
+- **Mock Service Patterns** (🟡 Babel Fish)
+- **Performance Testing** (🟠 Improbability Drive)
+- **Visual Regression Testing** (🔴 Deep Thought)
+
+### 🔧 Development Workflow Workshops
+Optimize your development process and tooling.
+
+#### [Developer Experience](./workflow/dev-experience/)
+- **IDE Setup and Configuration** (🟢 Towel Level)
+- **Debugging Workflow Mastery** (🟡 Babel Fish)
+- **Error Monitoring Integration** (🟠 Improbability Drive)
+
+#### [Production Readiness](./workflow/production/)
+- **Performance Monitoring** (🟡 Babel Fish)
+- **Feature Flag Implementation** (🟠 Improbability Drive)
+- **Deployment Pipeline Design** (🔴 Deep Thought)
+
+## Workshop Structure
+
+Each workshop follows a consistent format:
+
+### 📋 Workshop Overview
+```markdown
+# Workshop Title
+
+**Difficulty**: 🟡 Babel Fish
+**Duration**: 1-2 hours
+**Prerequisites**: Basic Redux knowledge, Chapter 2 completion
+**Learning Objectives**: What you'll be able to do after completion
+
+## The Challenge
+Real-world problem statement that motivates the exercise.
+
+## The Journey
+Step-by-step implementation with explanations.
+
+## The Validation
+How to test that your implementation works correctly.
+
+## The Extension
+Optional challenges to deepen understanding.
+
+## The Reflection
+Questions to solidify learning and connect to broader concepts.
+```
+
+### 🛠️ Implementation Support
+- **Starter Code**: Pre-configured environment with basic setup
+- **Checkpoints**: Validation points to ensure you're on track
+- **Solution Guide**: Complete implementation with detailed explanations
+- **Troubleshooting**: Common issues and their solutions
+
+### 🎯 Learning Validation
+- **Automated Tests**: Verify your implementation works correctly
+- **Peer Review**: Code review guidelines for collaborative learning
+- **Self-Assessment**: Checklist to validate your understanding
+- **Next Steps**: Connections to related workshops and concepts
+
+## Workshop Progression
+
+### Recommended Learning Paths
+
+#### **Complete Beginner Path**
+1. Development Environment Setup (🟢)
+2. Create Your First Normalized Schema (🟢)
+3. Basic Saga Effects (🟢)
+4. Send Your First Matrix Message (🟢)
+5. Connect Your First Wallet (🟢)
+6. Container-Presenter Split (🟢)
+7. Unit Testing Redux Logic (🟢)
+
+#### **Intermediate Developer Path**
+1. Build Memoized Selectors (🟡)
+2. Orchestrate Complex Flows (🟡)
+3. Build a Chat Room Interface (🟡)
+4. Handle Network Switching (🟡)
+5. Compound Component Design (🟡)
+6. Integration Testing Sagas (🟡)
+7. Performance Monitoring (🟡)
+
+#### **Advanced Practitioner Path**
+1. Implement Cross-Slice Communication (🟠)
+2. Real-time Data Synchronization (🔴)
+3. End-to-End Encryption Handling (🔴)
+4. Gas Optimization Strategies (🔴)
+5. Bundle Optimization (🔴)
+6. Visual Regression Testing (🔴)
+
+### Cross-Workshop Integration
+
+#### **Final Capstone Project** (🔴 Deep Thought)
+Build a complete feature that integrates all learned patterns:
+- Real-time chat with Matrix integration
+- Web3 wallet integration for user identity
+- Normalized Redux state with complex relationships
+- Advanced React patterns for optimal UX
+- Comprehensive testing suite
+- Production-ready development workflow
+
+## Workshop Environment
+
+### Prerequisites
+- **Node.js**: v18 or later
+- **Git**: For version control and starter code
+- **IDE**: VSCode recommended with extensions
+- **Browser**: Chrome or Firefox with dev tools
+
+### Setup Instructions
+```bash
+# Clone the workshop repository
+git clone https://github.com/zos-labs/hitchhiker-workshops.git
+cd hitchhiker-workshops
+
+# Install dependencies
+npm install
+
+# Start development environment
+npm run dev
+
+# Run tests
+npm test
+
+# Check workshop progress
+npm run workshop:status
+```
+
+### Workshop Tools
+- **Workshop CLI**: Navigate and manage workshop progress
+- **Live Reloading**: See changes immediately as you code
+- **Integrated Testing**: Run tests without leaving your development flow
+- **Solution Comparison**: Compare your implementation with provided solutions
+
+## Getting Help
+
+### Self-Help Resources
+1. **Workshop README**: Each workshop has detailed setup and troubleshooting
+2. **Solution Guides**: Reference implementations with explanations
+3. **Pattern Library**: Deep dive into the patterns you're implementing
+4. **Main Guide Chapters**: Theoretical background for practical exercises
+
+### Community Support
+- **Discussion Forum**: Ask questions and help other learners
+- **Code Review**: Get feedback on your implementations
+- **Study Groups**: Find others working through the same workshops
+- **Office Hours**: Weekly sessions with zOS experts
+
+### Debugging Your Implementation
+1. **Read Error Messages**: They usually tell you exactly what's wrong
+2. **Use the Debugger**: Step through your code to understand flow
+3. **Check the Tests**: Failing tests show what needs to be fixed
+4. **Compare with Solutions**: See how your approach differs
+5. **Ask for Help**: Don't struggle alone - the community is here
+
+## Workshop Quality Standards
+
+### Code Quality
+- **Type Safety**: All TypeScript errors must be resolved
+- **Linting**: Code must pass ESLint checks
+- **Testing**: Implementations must pass provided tests
+- **Performance**: Solutions should meet performance benchmarks
+
+### Learning Quality
+- **Understanding**: Complete reflection questions thoughtfully
+- **Application**: Successfully extend workshops with creative additions
+- **Integration**: Connect workshop learnings to broader zOS patterns
+- **Teaching**: Ability to explain your implementation to others
+
+## Contributing Workshops
+
+### New Workshop Ideas
+Workshop proposals should address:
+- **Real Problem**: Based on actual challenges in zOS development
+- **Clear Learning Objective**: Specific skills or understanding gained
+- **Appropriate Difficulty**: Matches prerequisite knowledge level
+- **Practical Application**: Can be applied to real zOS features
+
+### Workshop Development Process
+1. **Proposal**: Outline the workshop concept and learning objectives
+2. **Content Creation**: Develop starter code, instructions, and solutions
+3. **Testing**: Validate that workshop can be completed successfully
+4. **Review**: Get feedback from other developers and educators
+5. **Integration**: Add to the workshop progression and cross-references
+
+---
+
+*"I may not have gone where I intended to go, but I think I have ended up where I needed to be." - Douglas Adams*
+
+*"You may not build what you intended to build, but you'll understand what you needed to understand." - Workshop Philosophy*
+
+---
+
+## Quick Navigation
+
+- **[Start Here](./foundation/development-setup.md)** - Set up your development environment
+- **[Beginner Path](./paths/beginner.md)** - Complete beginner learning sequence
+- **[Pattern Reference](../patterns/)** - Deep dive into the patterns you're implementing
+- **[Main Guide](../chapters/)** - Theoretical background and context
+- **[Quick Reference](../reference/)** - Cheat sheets and API references
+
+## Workshop Statistics
+
+- **Total Workshops**: 50+ hands-on exercises
+- **Estimated Total Time**: 40-60 hours for complete mastery
+- **Skill Levels**: 4 progressive difficulty levels
+- **Success Rate**: Track your progress and completion rates
+- **Community Size**: Join hundreds of developers learning together
\ No newline at end of file
diff --git a/opusdocs/hitchhiker/workshops/redux-galaxy-workshops.md b/opusdocs/hitchhiker/workshops/redux-galaxy-workshops.md
new file mode 100644
index 00000000..8fcc6e6f
--- /dev/null
+++ b/opusdocs/hitchhiker/workshops/redux-galaxy-workshops.md
@@ -0,0 +1,1002 @@
+# Chapter 2 Workshop: The Redux Galaxy - State Management Mastery
+
+*"In the beginning, Redux created the store. This made a lot of developers angry and has been widely regarded as a bad move. They were wrong. Now let's prove it by building something amazing."*
+
+---
+
+## Workshop Overview
+
+**Chapter Focus**: Chapter 2 - The Redux Galaxy  
+**Total Duration**: 8-12 hours across all difficulty levels  
+**Prerequisites**: Completion of Chapter 2, basic TypeScript/React knowledge  
+**Learning Path**: Progress from Towel Level to Deep Thought mastery
+
+### What You'll Master
+
+By completing these workshops, you'll understand and implement:
+- **Normalized State Architecture**: Build scalable, efficient data structures
+- **Advanced Selector Patterns**: Create memoized, type-safe data access layers
+- **Merge-First Update Strategies**: Handle partial updates without data loss
+- **TypeScript Integration**: Maintain complete type safety across complex state
+- **Performance Optimization**: Build selectors that scale to millions of entities
+
+---
+
+## 🟢 Towel Level: "Don't Panic About Normalization"
+
+*Difficulty: Beginner | Duration: 1-2 hours*
+
+### The Challenge: Build Your First Normalized Store
+
+You're tasked with building a simple blog application's state management. Instead of the nested nightmare most developers create, you'll implement the normalized approach that makes zOS scale to millions of entities.
+
+**Learning Objectives:**
+- Understand why normalization matters for performance
+- Implement basic normalized schemas
+- Create simple selectors for flat data structures
+- Experience the "aha!" moment of efficient updates
+
+### The Journey
+
+#### Step 1: Design the Normalized Schema
+
+```typescript
+// 🎯 EXERCISE: Complete this normalized state structure
+interface BlogState {
+  // TODO: Create normalized entity tables
+  posts: Record<string, NormalizedPost>;
+  users: Record<string, NormalizedUser>;
+  comments: Record<string, NormalizedComment>;
+  
+  // TODO: Create relationship mappings
+  postComments: Record<string, string[]>; // postId -> commentIds[]
+  userPosts: Record<string, string[]>;     // userId -> postIds[]
+}
+
+// TODO: Define these normalized entity interfaces
+interface NormalizedPost {
+  id: string;
+  title: string;
+  content: string;
+  authorId: string;  // Reference, not nested object
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface NormalizedUser {
+  // Your implementation here
+}
+
+interface NormalizedComment {
+  // Your implementation here
+}
+```
+
+#### Step 2: Create Basic Selectors
+
+```typescript
+// 🎯 EXERCISE: Implement these basic selectors
+export const selectPost = (postId: string) => (state: BlogState): NormalizedPost | undefined => {
+  // TODO: Return the post by ID from normalized state
+};
+
+export const selectUser = (userId: string) => (state: BlogState): NormalizedUser | undefined => {
+  // TODO: Return the user by ID from normalized state
+};
+
+export const selectPostComments = (postId: string) => (state: BlogState): NormalizedComment[] => {
+  // TODO: Get all comments for a post using the relationship mapping
+  // HINT: Use postComments[postId] to get comment IDs, then map to actual comments
+};
+```
+
+#### Step 3: Implement Basic Updates
+
+```typescript
+// 🎯 EXERCISE: Create update functions that preserve normalization
+export const updatePost = (state: BlogState, postUpdate: Partial<NormalizedPost> & { id: string }): BlogState => {
+  // TODO: Update a post while preserving all other data
+  // HINT: Use spread operator to merge changes
+};
+
+export const addComment = (state: BlogState, comment: NormalizedComment): BlogState => {
+  // TODO: Add a new comment and update the postComments relationship
+  // HINT: You need to update both the comments table AND the postComments mapping
+};
+```
+
+### The Validation
+
+Test your implementation with this scenario:
+
+```typescript
+// Test data
+const initialState: BlogState = {
+  posts: {
+    'post1': { id: 'post1', title: 'Redux Basics', content: '...', authorId: 'user1', createdAt: '2024-01-01', updatedAt: '2024-01-01' }
+  },
+  users: {
+    'user1': { id: 'user1', name: 'Alice', email: 'alice@example.com' }
+  },
+  comments: {},
+  postComments: { 'post1': [] },
+  userPosts: { 'user1': ['post1'] }
+};
+
+// 🧪 TEST: Can you add a comment and retrieve it?
+const newComment = { id: 'comment1', content: 'Great post!', authorId: 'user1', postId: 'post1' };
+const updatedState = addComment(initialState, newComment);
+const postComments = selectPostComments('post1')(updatedState);
+
+console.log('Comments for post1:', postComments); // Should include your new comment
+```
+
+### The Extension
+
+**Bonus Challenge**: Add a `selectPostWithAuthor` selector that combines a post with its author information without denormalizing the entire structure.
+
+### The Reflection
+
+1. Compare updating a user's name in your normalized structure vs. a nested structure. How many operations does each require?
+2. What happens to performance as you add more posts and comments?
+3. How does TypeScript help prevent errors in your normalized structure?
+
+---
+
+## 🟡 Babel Fish: "Advanced Selector Orchestration"
+
+*Difficulty: Intermediate | Duration: 2-3 hours*
+
+### The Challenge: Build a High-Performance Social Feed
+
+Create a sophisticated social media feed that demonstrates advanced selector patterns from zOS. Your feed needs to handle thousands of posts with complex relationships while maintaining 60fps scrolling performance.
+
+**Learning Objectives:**
+- Master memoized selector factories
+- Implement complex derived state computations
+- Understand selector composition patterns
+- Build performance-optimized data access layers
+
+### The Journey
+
+#### Step 1: Design Complex Selectors with Memoization
+
+```typescript
+// 🎯 EXERCISE: Implement these advanced selector patterns from zOS
+import { createSelector } from '@reduxjs/toolkit';
+
+// Factory pattern for memoized selectors - like zOS does it
+export const makeSelectPostWithDetails = () => {
+  return createSelector(
+    [
+      (state: SocialState, postId: string) => state.posts[postId],
+      (state: SocialState, postId: string) => state.users[state.posts[postId]?.authorId],
+      (state: SocialState, postId: string) => selectPostComments(postId)(state),
+      (state: SocialState, postId: string) => selectPostLikesCount(postId)(state),
+    ],
+    (post, author, comments, likesCount) => {
+      if (!post || !author) return null;
+      
+      // TODO: Return enriched post object with:
+      // - All post data
+      // - Author information nested as 'author'
+      // - Comments count
+      // - Likes count
+      // - Computed 'engagement' score (comments + likes)
+      return {
+        // Your implementation here
+      };
+    }
+  );
+};
+
+// TODO: Create a selector factory for the user's personalized feed
+export const makeSelectUserFeed = () => {
+  return createSelector(
+    [
+      (state: SocialState, userId: string) => selectUserFollowing(userId)(state),
+      (state: SocialState) => state.posts,
+      // Add more input selectors as needed
+    ],
+    (following, allPosts /* other inputs */) => {
+      // TODO: Create personalized feed logic:
+      // 1. Get posts from users the current user follows
+      // 2. Sort by engagement score (highest first)
+      // 3. Filter out posts older than 7 days
+      // 4. Limit to 50 posts for performance
+      
+      return []; // Your implementation here
+    }
+  );
+};
+```
+
+#### Step 2: Implement Smart Caching Strategy
+
+```typescript
+// 🎯 EXERCISE: Build a caching layer like zOS uses
+interface SelectorCache {
+  // TODO: Define cache structure for selector instances
+  // HINT: Each component instance should have its own cache
+}
+
+// Hook pattern from zOS - creates stable selector instances
+export const usePostWithDetails = (postId: string) => {
+  // TODO: Implement the zOS pattern:
+  // 1. Create selector instance in useMemo (not on every render!)
+  // 2. Create stable callback with useCallback
+  // 3. Use with useSelector for optimal performance
+  
+  const selectPostInstance = useMemo(() => {
+    // Your implementation here
+  }, []);
+  
+  const postSelector = useCallback(
+    (state: SocialState) => selectPostInstance(state, postId),
+    [selectPostInstance, postId]
+  );
+  
+  return useSelector(postSelector);
+};
+
+export const useUserFeed = (userId: string) => {
+  // TODO: Implement similar pattern for user feed
+  // Follow the same instance isolation pattern
+};
+```
+
+#### Step 3: Complex State Updates with Merge-First Strategy
+
+```typescript
+// 🎯 EXERCISE: Implement zOS-style merge-first updates
+export const updatePostEngagement = (
+  state: SocialState, 
+  updates: { postId: string; likes?: number; shares?: number; comments?: Comment[] }
+): SocialState => {
+  const { postId, likes, shares, comments } = updates;
+  
+  // TODO: Implement merge-first strategy:
+  // 1. Preserve all existing post data
+  // 2. Only update the fields that are provided
+  // 3. Handle comments as both entity updates AND relationship updates
+  // 4. Update computed fields (like engagement score) if needed
+  
+  return {
+    ...state,
+    // Your implementation here
+  };
+};
+
+// Advanced: Batch updates for better performance
+export const batchUpdatePosts = (
+  state: SocialState,
+  updates: Array<{ postId: string; changes: Partial<NormalizedPost> }>
+): SocialState => {
+  // TODO: Efficiently apply multiple post updates in a single state transition
+  // HINT: Use reduce to accumulate changes, avoiding multiple state clones
+};
+```
+
+### The Validation
+
+Performance test your implementation:
+
+```typescript
+// 🧪 PERFORMANCE TEST: Your selectors should handle this efficiently
+const testState = generateSocialState({
+  users: 1000,
+  posts: 10000,
+  comments: 50000,
+  relationships: 5000
+});
+
+// Measure selector performance
+console.time('Select 100 posts with details');
+for (let i = 0; i < 100; i++) {
+  const selector = makeSelectPostWithDetails();
+  const result = selector(testState, `post${i}`);
+}
+console.timeEnd('Select 100 posts with details'); // Should be < 50ms
+
+// Test memoization
+const selector1 = makeSelectPostWithDetails();
+const selector2 = makeSelectPostWithDetails();
+const result1a = selector1(testState, 'post1');
+const result1b = selector1(testState, 'post1'); // Should return same reference
+const result2 = selector2(testState, 'post1');   // Different instance, different reference
+
+console.log('Memoization working:', result1a === result1b); // Should be true
+console.log('Instance isolation working:', result1a !== result2); // Should be true
+```
+
+### The Extension
+
+**Advanced Challenge**: Implement real-time updates where new posts can arrive while maintaining selector performance and not causing unnecessary re-renders.
+
+### The Reflection
+
+1. How does memoization change as your state grows from 100 posts to 100,000 posts?
+2. What happens to component re-renders when you use proper selector instances vs. creating selectors on each render?
+3. How does the merge-first strategy prevent data loss during rapid updates?
+
+---
+
+## 🟠 Improbability Drive: "Real-Time Normalized Synchronization"
+
+*Difficulty: Advanced | Duration: 3-4 hours*
+
+### The Challenge: Build a Real-Time Chat System
+
+Implement a production-ready real-time chat system that demonstrates the most advanced patterns from zOS. Your system must handle message updates, typing indicators, user presence, and read receipts - all while maintaining perfect data consistency and optimal performance.
+
+**Learning Objectives:**
+- Master complex normalized relationships
+- Implement optimistic updates with rollback
+- Handle real-time synchronization conflicts
+- Build advanced debugging and monitoring tools
+
+### The Journey
+
+#### Step 1: Design Advanced Normalized Schema
+
+```typescript
+// 🎯 EXERCISE: Design a complex normalized schema that handles real-time chat
+interface ChatState {
+  // Core entities
+  channels: Record<string, NormalizedChannel>;
+  messages: Record<string, NormalizedMessage>;
+  users: Record<string, NormalizedUser>;
+  
+  // Real-time entities
+  typingIndicators: Record<string, TypingIndicator>; // channelId -> typing users
+  readReceipts: Record<string, ReadReceipt[]>;       // messageId -> read receipts
+  userPresence: Record<string, UserPresence>;        // userId -> presence status
+  
+  // Complex relationships
+  channelMessages: Record<string, string[]>;     // channelId -> messageIds (sorted by time)
+  channelMembers: Record<string, string[]>;      // channelId -> userIds
+  userChannels: Record<string, string[]>;        // userId -> channelIds
+  messageThread: Record<string, string[]>;       // messageId -> reply messageIds
+  
+  // Metadata for synchronization
+  messagesPendingSync: Record<string, PendingMessage>; // Optimistic updates
+  lastSyncTimestamp: Record<string, number>;           // channelId -> last sync time
+  conflictResolution: Record<string, ConflictState>;   // Track and resolve conflicts
+}
+
+// TODO: Define these complex interfaces
+interface NormalizedMessage {
+  id: string;
+  content: string;
+  authorId: string;
+  channelId: string;
+  timestamp: number;
+  edited?: boolean;
+  editedAt?: number;
+  parentMessageId?: string; // For threaded conversations
+  reactions: Record<string, string[]>; // emoji -> userIds[]
+  
+  // Sync metadata
+  syncStatus: 'pending' | 'synced' | 'failed';
+  optimisticId?: string; // For optimistic updates
+  version: number; // For conflict resolution
+}
+
+// TODO: Complete the other complex interfaces
+interface TypingIndicator {
+  // Your implementation
+}
+
+interface ReadReceipt {
+  // Your implementation
+}
+
+interface ConflictState {
+  // Your implementation
+}
+```
+
+#### Step 2: Advanced Selector Orchestration
+
+```typescript
+// 🎯 EXERCISE: Build sophisticated selectors that handle real-time complexity
+export const makeSelectChannelWithLiveData = () => {
+  return createSelector(
+    [
+      (state: ChatState, channelId: string) => state.channels[channelId],
+      (state: ChatState, channelId: string) => selectChannelMessages(channelId, { limit: 50 })(state),
+      (state: ChatState, channelId: string) => state.typingIndicators[channelId],
+      (state: ChatState, channelId: string) => selectChannelMembers(channelId)(state),
+      (state: ChatState, channelId: string) => selectUnreadCount(channelId)(state),
+    ],
+    (channel, messages, typingIndicator, members, unreadCount) => {
+      if (!channel) return null;
+      
+      // TODO: Create comprehensive channel view with:
+      // - All basic channel data
+      // - Recent messages with author information
+      // - Currently typing users (exclude current user)
+      // - Online member count
+      // - Unread message count
+      // - Last activity timestamp
+      
+      return {
+        // Your sophisticated implementation here
+      };
+    }
+  );
+};
+
+// Advanced: Selector for message threads with real-time updates
+export const makeSelectMessageThread = () => {
+  return createSelector(
+    [
+      (state: ChatState, messageId: string) => state.messages[messageId],
+      (state: ChatState, messageId: string) => selectThreadReplies(messageId)(state),
+      (state: ChatState, messageId: string) => selectMessageReadReceipts(messageId)(state),
+    ],
+    (parentMessage, replies, readReceipts) => {
+      if (!parentMessage) return null;
+      
+      // TODO: Create threaded conversation view:
+      // - Parent message with full details
+      // - All replies sorted chronologically
+      // - Read receipt status for each message
+      // - Indicators for optimistic/pending messages
+      
+      return {
+        // Your implementation here
+      };
+    }
+  );
+};
+```
+
+#### Step 3: Optimistic Updates with Rollback
+
+```typescript
+// 🎯 EXERCISE: Implement zOS-style optimistic updates
+export const sendMessageOptimistically = (
+  state: ChatState,
+  message: Omit<NormalizedMessage, 'id' | 'timestamp' | 'syncStatus' | 'version'>
+): ChatState => {
+  const optimisticId = `optimistic_${Date.now()}_${Math.random()}`;
+  const timestamp = Date.now();
+  
+  // TODO: Implement optimistic message sending:
+  // 1. Create optimistic message with temporary ID
+  // 2. Add to messages table with 'pending' sync status
+  // 3. Update channelMessages relationship
+  // 4. Store in messagesPendingSync for potential rollback
+  // 5. Update channel's last activity
+  
+  const optimisticMessage: NormalizedMessage = {
+    // Your implementation here
+  };
+  
+  return {
+    ...state,
+    // Your state updates here
+  };
+};
+
+export const rollbackOptimisticMessage = (
+  state: ChatState,
+  optimisticId: string
+): ChatState => {
+  // TODO: Clean rollback of failed optimistic update:
+  // 1. Remove from messages table
+  // 2. Remove from channelMessages relationship
+  // 3. Remove from messagesPendingSync
+  // 4. Update any computed values that might have changed
+  
+  return {
+    // Your rollback implementation
+  };
+};
+
+export const confirmOptimisticMessage = (
+  state: ChatState,
+  optimisticId: string,
+  serverMessage: NormalizedMessage
+): ChatState => {
+  // TODO: Replace optimistic message with server version:
+  // 1. Update message with server ID and data
+  // 2. Update all relationships to use server ID
+  // 3. Remove from pending sync
+  // 4. Handle any conflicts with server version
+  
+  return {
+    // Your confirmation implementation
+  };
+};
+```
+
+#### Step 4: Conflict Resolution System
+
+```typescript
+// 🎯 EXERCISE: Handle real-time synchronization conflicts
+export const resolveMessageConflict = (
+  localMessage: NormalizedMessage,
+  serverMessage: NormalizedMessage
+): { resolved: NormalizedMessage; strategy: 'local' | 'server' | 'merge' } => {
+  // TODO: Implement conflict resolution strategy:
+  // 1. Compare message versions
+  // 2. Check edit timestamps
+  // 3. Determine resolution strategy:
+  //    - 'local': Keep local changes (user was editing)
+  //    - 'server': Accept server version (other user edited)
+  //    - 'merge': Combine changes (possible for reactions, etc.)
+  
+  // Advanced: Handle different conflict types
+  if (localMessage.content !== serverMessage.content) {
+    // Content conflicts - usually take server version unless local is newer
+  }
+  
+  if (Object.keys(localMessage.reactions).length !== Object.keys(serverMessage.reactions).length) {
+    // Reaction conflicts - usually safe to merge
+  }
+  
+  return {
+    resolved: serverMessage, // Your conflict resolution logic
+    strategy: 'server'
+  };
+};
+
+export const applySyncUpdates = (
+  state: ChatState,
+  updates: {
+    messages: NormalizedMessage[];
+    deletedMessages: string[];
+    channelUpdates: Partial<NormalizedChannel>[];
+  }
+): ChatState => {
+  // TODO: Apply server synchronization updates:
+  // 1. Handle message updates with conflict resolution
+  // 2. Process message deletions
+  // 3. Update channel metadata
+  // 4. Maintain referential integrity
+  // 5. Update sync timestamps
+  
+  return {
+    // Your sync implementation
+  };
+};
+```
+
+### The Validation
+
+Comprehensive testing of your real-time system:
+
+```typescript
+// 🧪 REAL-TIME SYSTEM TEST
+describe('Real-time Chat System', () => {
+  test('Optimistic updates with rollback', async () => {
+    let state = initialChatState;
+    
+    // Send message optimistically
+    state = sendMessageOptimistically(state, {
+      content: 'Hello world!',
+      authorId: 'user1',
+      channelId: 'channel1'
+    });
+    
+    // Message should appear immediately
+    const messages = selectChannelMessages('channel1')(state);
+    expect(messages).toHaveLength(1);
+    expect(messages[0].syncStatus).toBe('pending');
+    
+    // Simulate server failure and rollback
+    const optimisticId = messages[0].optimisticId!;
+    state = rollbackOptimisticMessage(state, optimisticId);
+    
+    // Message should be gone
+    const messagesAfterRollback = selectChannelMessages('channel1')(state);
+    expect(messagesAfterRollback).toHaveLength(0);
+  });
+  
+  test('Conflict resolution', () => {
+    const localMessage = { /* local version */ };
+    const serverMessage = { /* server version */ };
+    
+    const result = resolveMessageConflict(localMessage, serverMessage);
+    
+    // Should handle conflicts intelligently
+    expect(result.strategy).toBeDefined();
+    expect(result.resolved).toBeDefined();
+  });
+  
+  test('Performance under load', () => {
+    // Generate state with thousands of messages
+    const heavyState = generateChatState({
+      channels: 100,
+      messages: 100000,
+      users: 10000
+    });
+    
+    // Selectors should still be fast
+    console.time('Complex selector with heavy state');
+    const selector = makeSelectChannelWithLiveData();
+    const result = selector(heavyState, 'channel1');
+    console.timeEnd('Complex selector with heavy state'); // Should be < 100ms
+    
+    expect(result).toBeDefined();
+  });
+});
+```
+
+### The Extension
+
+**Ultimate Challenge**: Add end-to-end encryption support where messages are encrypted/decrypted in the selectors while maintaining performance and normalization.
+
+### The Reflection
+
+1. How does optimistic updating change the user experience in real-time applications?
+2. What trade-offs do you make between data consistency and performance?
+3. How would you handle partial connectivity where some updates succeed and others fail?
+
+---
+
+## 🔴 Deep Thought: "Architecting the Ultimate State Machine"
+
+*Difficulty: Expert | Duration: 4-6 hours*
+
+### The Challenge: Build a Multi-Tenant Real-Time Collaboration Platform
+
+Create a production-grade state management system for a collaborative platform like Figma or Notion. Your system must handle multiple workspaces, real-time collaboration, operational transforms, conflict resolution, offline support, and performance optimization - all while maintaining perfect data consistency across potentially millions of entities.
+
+**Learning Objectives:**
+- Master enterprise-scale normalized architectures
+- Implement operational transformation for real-time collaboration
+- Build sophisticated caching and synchronization strategies
+- Create advanced debugging and performance monitoring tools
+- Design fault-tolerant distributed state management
+
+### The Challenge
+
+This is an open-ended architectural challenge. You'll design and implement a complete state management system that could power a real SaaS application. The requirements are deliberately complex and may have multiple valid solutions.
+
+#### Core Requirements
+
+1. **Multi-Tenant Architecture**: Support multiple organizations with data isolation
+2. **Real-Time Collaboration**: Multiple users editing the same documents simultaneously
+3. **Operational Transforms**: Handle concurrent edits without conflicts
+4. **Offline Support**: Work without connectivity and sync when reconnected
+5. **Performance**: Handle 10M+ entities with sub-100ms query times
+6. **Type Safety**: Complete TypeScript coverage with zero `any` types
+7. **Testing**: Comprehensive test suite including performance tests
+8. **Monitoring**: Built-in performance and error monitoring
+
+#### The Schema Challenge
+
+```typescript
+// 🎯 EXERCISE: Design this enterprise-scale schema
+interface CollaborationState {
+  // Multi-tenant data isolation
+  tenants: Record<string, Tenant>;
+  
+  // Core collaborative entities
+  workspaces: Record<string, Workspace>;
+  documents: Record<string, Document>;
+  elements: Record<string, DocumentElement>; // Could be millions
+  
+  // Real-time collaboration state
+  operations: Record<string, Operation[]>;        // Pending operations per document
+  cursors: Record<string, UserCursor[]>;          // Real-time cursor positions
+  selections: Record<string, UserSelection[]>;    // User selections
+  
+  // Offline/sync support
+  operationsQueue: Operation[];                   // Queued for sync
+  conflictLog: ConflictResolution[];             // Resolved conflicts
+  syncState: Record<string, SyncMetadata>;       // Per-document sync status
+  
+  // Performance optimization
+  entityCache: Record<string, CachedEntity>;     // Computed/aggregated data
+  queryCache: Record<string, QueryResult>;       // Query result cache
+  
+  // Complex relationships (design these carefully)
+  workspaceDocuments: Record<string, string[]>;
+  documentElements: Record<string, string[]>;
+  elementChildren: Record<string, string[]>;     // For nested elements
+  userWorkspaces: Record<string, string[]>;
+  
+  // Advanced: Your custom relationship mappings
+  [key: string]: any; // Design additional structures as needed
+}
+
+// TODO: Design these complex interfaces
+interface Operation {
+  // Operational transform operation
+  // Should support insert, delete, modify, move operations
+  // Must include vector clocks or similar for ordering
+}
+
+interface ConflictResolution {
+  // How conflicts were resolved
+  // Should include original operations and resolution strategy
+}
+
+interface SyncMetadata {
+  // Track sync state per document
+  // Should handle partial sync, retry logic, etc.
+}
+```
+
+#### The Architecture Challenge
+
+Design and implement these advanced systems:
+
+##### 1. Operational Transform Engine
+
+```typescript
+// 🎯 EXERCISE: Build a production-ready operational transform system
+class OperationalTransform {
+  // Transform operations for concurrent editing
+  public transform(op1: Operation, op2: Operation): [Operation, Operation] {
+    // TODO: Implement operational transform algorithm
+    // Must handle all operation types and maintain convergence
+  }
+  
+  // Apply operations to state with conflict resolution
+  public applyOperation(state: CollaborationState, operation: Operation): CollaborationState {
+    // TODO: Apply operation while maintaining data integrity
+  }
+  
+  // Compose multiple operations for efficiency
+  public composeOperations(operations: Operation[]): Operation {
+    // TODO: Combine multiple operations into one
+  }
+}
+```
+
+##### 2. Advanced Selector Architecture
+
+```typescript
+// 🎯 EXERCISE: Build enterprise-scale selectors
+export const makeSelectDocumentWithCollaborators = () => {
+  return createSelector(
+    [
+      // TODO: Design input selectors for:
+      // - Document data
+      // - All document elements (could be thousands)
+      // - Real-time collaborator data
+      // - Pending operations
+      // - User permissions
+    ],
+    (...inputs) => {
+      // TODO: Build comprehensive document view that includes:
+      // - All document content with real-time updates
+      // - Collaborator presence and cursors
+      // - Pending operation indicators
+      // - Permission-filtered content
+      // - Performance-optimized rendering data
+      
+      // Advanced: Implement virtual rendering for large documents
+      // Advanced: Cache expensive computations
+      // Advanced: Handle partial loading of large element trees
+    }
+  );
+};
+
+// TODO: Build selectors for complex queries like:
+// - Search across all documents in workspace
+// - Activity feed with real-time updates
+// - Performance analytics and monitoring
+// - Conflict resolution history
+```
+
+##### 3. Sophisticated Caching System
+
+```typescript
+// 🎯 EXERCISE: Build multi-layer caching
+class StateCache {
+  private queryCache = new Map<string, { result: any; timestamp: number; dependencies: string[] }>();
+  private entityCache = new Map<string, { entity: any; version: number }>();
+  
+  // TODO: Implement intelligent cache invalidation
+  public invalidateCache(changedEntityIds: string[]): void {
+    // Should invalidate dependent queries efficiently
+  }
+  
+  // TODO: Implement cache warming strategies
+  public warmCache(workspaceId: string): Promise<void> {
+    // Pre-load frequently accessed data
+  }
+  
+  // TODO: Implement cache compression for large datasets
+  public compressCache(): void {
+    // Reduce memory usage for inactive data
+  }
+}
+```
+
+##### 4. Performance Monitoring System
+
+```typescript
+// 🎯 EXERCISE: Build comprehensive monitoring
+class PerformanceMonitor {
+  // Track selector performance
+  public measureSelector<T>(selectorName: string, fn: () => T): T {
+    // TODO: Measure and log selector performance
+    // Should detect performance regressions
+  }
+  
+  // Monitor state size and growth
+  public analyzeStateSize(state: CollaborationState): StateAnalysis {
+    // TODO: Analyze memory usage, entity counts, relationship complexity
+  }
+  
+  // Track user experience metrics
+  public trackUserInteraction(action: string, duration: number): void {
+    // TODO: Monitor real user performance
+  }
+}
+```
+
+### The Implementation Journey
+
+This is your architectural adventure. There's no single correct solution, but here are some guidance principles:
+
+#### Phase 1: Core Architecture (2 hours)
+1. Design your normalized schema with careful attention to relationships
+2. Implement basic CRUD operations with type safety
+3. Create fundamental selectors with memoization
+4. Build basic operational transform support
+
+#### Phase 2: Real-Time Collaboration (1.5 hours)
+1. Implement operational transforms for concurrent editing
+2. Add real-time cursor and selection tracking
+3. Build conflict resolution strategies
+4. Create optimistic update system with rollback
+
+#### Phase 3: Performance Optimization (1.5 hours)
+1. Implement sophisticated caching strategies
+2. Add performance monitoring and analytics
+3. Optimize selectors for large datasets
+4. Build virtual rendering support for huge documents
+
+#### Phase 4: Enterprise Features (1 hour)
+1. Add multi-tenant data isolation
+2. Implement offline support with sync queue
+3. Build comprehensive error handling
+4. Create advanced debugging tools
+
+### The Validation
+
+Your system should pass these enterprise-grade tests:
+
+```typescript
+// 🧪 ENTERPRISE SYSTEM TESTS
+describe('Enterprise Collaboration Platform', () => {
+  test('Handles concurrent editing by 50 users', async () => {
+    // Simulate 50 users making concurrent edits
+    // All operations should be applied without conflicts
+    // Final state should be consistent across all clients
+  });
+  
+  test('Maintains performance with 1M entities', () => {
+    // Generate massive state with 1M+ entities
+    // Selectors should still perform under 100ms
+    // Memory usage should remain reasonable
+  });
+  
+  test('Recovers from network partitions', async () => {
+    // Simulate network disconnection during editing
+    // Should queue operations and sync when reconnected
+    // Should resolve conflicts intelligently
+  });
+  
+  test('Handles malicious inputs safely', () => {
+    // Test with invalid operations, massive operations, etc.
+    // Should maintain data integrity under all conditions
+  });
+});
+```
+
+### The Extensions
+
+Choose one or more of these advanced challenges:
+
+1. **Time Travel Debugging**: Build a system that can replay any sequence of operations
+2. **Real-Time Analytics**: Create live dashboards showing collaboration metrics
+3. **Advanced Permissions**: Implement document-level, element-level, and operation-level permissions
+4. **Plugin Architecture**: Design an extensible system for third-party integrations
+5. **Cross-Platform Sync**: Handle mobile, web, and desktop clients with different capabilities
+
+### The Reflection
+
+This is the culmination of your Redux Galaxy journey. Consider these deep questions:
+
+1. **Architecture**: How do your design decisions change as you scale from 100 users to 100,000 users?
+2. **Trade-offs**: What compromises did you make between consistency, performance, and complexity?
+3. **Innovation**: What novel patterns did you discover that aren't in the zOS codebase?
+4. **Real-World**: How would you deploy and monitor this system in production?
+5. **Evolution**: How would you evolve this architecture as requirements change?
+
+---
+
+## Workshop Completion and Mastery Path
+
+### 🎯 Progress Tracking
+
+#### Towel Level Mastery Checklist
+- [ ] **Schema Design**: Can design normalized schemas that eliminate data duplication
+- [ ] **Basic Selectors**: Can write simple selectors that efficiently access normalized data
+- [ ] **Update Logic**: Can implement updates that preserve data integrity
+- [ ] **Type Safety**: Can maintain TypeScript safety across state operations
+
+#### Babel Fish Mastery Checklist
+- [ ] **Memoized Selectors**: Can build high-performance selector factories with proper memoization
+- [ ] **Complex Queries**: Can compose selectors to create sophisticated derived state
+- [ ] **Performance Optimization**: Can identify and resolve performance bottlenecks
+- [ ] **Real-Time Updates**: Can handle dynamic data with efficient re-computation
+
+#### Improbability Drive Mastery Checklist
+- [ ] **Advanced Normalization**: Can design complex schemas with multiple relationship types
+- [ ] **Optimistic Updates**: Can implement optimistic updates with rollback mechanisms
+- [ ] **Conflict Resolution**: Can handle real-time synchronization conflicts intelligently
+- [ ] **Production Patterns**: Can build systems that handle real-world complexity
+
+#### Deep Thought Mastery Checklist
+- [ ] **System Architecture**: Can design enterprise-scale state management from scratch
+- [ ] **Performance Engineering**: Can build systems that scale to millions of entities
+- [ ] **Innovation**: Can create novel patterns and solutions beyond existing examples
+- [ ] **Production Ready**: Can build systems suitable for real SaaS applications
+
+### 🚀 Next Steps After Mastery
+
+Once you've completed these workshops, you'll have mastered the Redux Galaxy patterns that make zOS so powerful. Consider these advanced paths:
+
+#### **Contribute to zOS**
+- Your deep understanding makes you ready to contribute advanced patterns back to zOS
+- Consider proposing optimizations or new features based on your workshop innovations
+
+#### **Build Your Own Framework**
+- Use your knowledge to create state management libraries for specific use cases
+- Share your innovations with the broader developer community
+
+#### **Teach Others**
+- Create your own workshops based on the patterns you've mastered
+- Mentor other developers in advanced state management concepts
+
+#### **Enterprise Consulting**
+- Help organizations migrate from simple state management to production-scale architectures
+- Design state management systems for complex business domains
+
+---
+
+## Resources and References
+
+### 📚 Study Materials
+- **zOS Source Code**: `/packages/store/` - Real implementation examples
+- **Redux Toolkit Documentation**: Advanced patterns and best practices
+- **Reselect Documentation**: Deep dive into memoization strategies
+- **Normalizr Documentation**: Understanding normalization libraries
+
+### 🛠️ Development Tools
+- **Redux DevTools**: Essential for debugging normalized state
+- **React Developer Tools**: Monitor component re-renders and performance
+- **Performance Profiler**: Measure selector performance under load
+- **TypeScript Compiler**: Catch type errors early in development
+
+### 🎯 Practice Datasets
+- **Small Dataset**: 100 entities for basic testing
+- **Medium Dataset**: 10,000 entities for performance testing
+- **Large Dataset**: 1M+ entities for stress testing
+- **Real-World Dataset**: Export from actual applications for realistic testing
+
+### 🤝 Community Support
+- **zOS Discord**: Get help from other developers learning these patterns
+- **Redux Community**: Broader ecosystem support and advanced discussions
+- **Open Source Projects**: Study other implementations of these patterns
+- **Workshop Study Groups**: Find others working through the same challenges
+
+---
+
+*"The Redux Galaxy is vast and full of wonders. You've learned to navigate its normalized stars, dance with its memoized selectors, and harness the power of merge-first updates. The universe of advanced state management is now yours to explore."*
+
+---
+
+**Previous Workshop**: [Chapter 1: Don't Panic Workshops](./dont-panic-workshops.md)  
+**Next Workshop**: [Chapter 3: Saga Odyssey Workshops](./saga-odyssey-workshops.md)  
+**Back to Main Guide**: [Chapter 2: The Redux Galaxy](../chapters/02-redux-galaxy.md)
\ No newline at end of file
diff --git a/opusdocs/integration-guide.md b/opusdocs/integration-guide.md
new file mode 100644
index 00000000..73e5034b
--- /dev/null
+++ b/opusdocs/integration-guide.md
@@ -0,0 +1,899 @@
+# Matrix Chat Integration Guide for zOS
+
+## Overview
+
+This guide documents how Matrix chat integration works in zOS, providing practical examples and patterns that are particularly useful for Haven Protocol's creator communities. Matrix serves as the real-time communication backbone, enabling encrypted messaging, room management, and event streaming.
+
+## Core Architecture
+
+### Matrix Client Structure
+
+The Matrix integration follows a layered architecture:
+
+```
+┌─────────────────┐
+│   React UI      │ ← Components consume chat state
+├─────────────────┤
+│   Redux Store   │ ← Manages chat state via sagas
+├─────────────────┤
+│   Chat Layer    │ ← Abstracts Matrix complexity
+├─────────────────┤
+│  Matrix Client  │ ← Direct SDK integration
+└─────────────────┘
+```
+
+**Key Files:**
+- `/src/lib/chat/matrix-client.ts` - Core Matrix SDK wrapper
+- `/src/lib/chat/index.ts` - High-level chat API
+- `/src/store/matrix/saga.ts` - State management
+- `/src/lib/chat/matrix/matrix-adapter.ts` - Data transformation
+
+## Setting up Matrix Integration
+
+### Basic Client Initialization
+
+```typescript
+import { MatrixClient } from './lib/chat/matrix-client';
+import { featureFlags } from './lib/feature-flags';
+
+// Initialize the Matrix client
+const client = new MatrixClient();
+
+// Connect with user credentials
+await client.connect(userId, accessToken);
+
+// Wait for sync completion
+await client.waitForConnection();
+```
+
+### Event Handler Setup
+
+```typescript
+// Define event handlers for real-time updates
+const realtimeEvents = {
+  receiveNewMessage: (channelId: string, message: Message) => {
+    // Handle incoming messages
+    console.log(`New message in ${channelId}:`, message);
+  },
+  
+  receiveUnreadCount: (channelId: string, unreadCount: UnreadCount) => {
+    // Update UI badges and notifications
+    updateChannelBadge(channelId, unreadCount);
+  },
+  
+  onUserJoinedChannel: (channelId: string) => {
+    // Handle user joining
+    refreshChannelMembers(channelId);
+  },
+  
+  roomMemberTyping: (roomId: string, userIds: string[]) => {
+    // Show typing indicators
+    showTypingIndicators(roomId, userIds);
+  }
+};
+
+// Initialize event handling
+client.init(realtimeEvents);
+```
+
+## Sending Messages
+
+### Text Messages
+
+```typescript
+// Send a basic text message
+async function sendTextMessage(channelId: string, message: string) {
+  const result = await client.sendMessagesByChannelId(
+    channelId,
+    message,
+    [], // mentionedUserIds
+    null, // parentMessage (for replies)
+    null, // file attachment
+    generateOptimisticId(), // for immediate UI updates
+    false // isSocialChannel
+  );
+  
+  return result;
+}
+
+// Example usage for creator announcements
+await sendTextMessage(
+  'roomId123', 
+  'New artwork drop this Friday! Get ready for "Digital Dreams" collection 🎨'
+);
+```
+
+### Reply Messages
+
+```typescript
+// Reply to a message (useful for community discussions)
+async function replyToMessage(
+  channelId: string, 
+  replyText: string, 
+  originalMessage: Message
+) {
+  const parentMessage = {
+    messageId: originalMessage.id,
+    senderId: originalMessage.senderId,
+    message: originalMessage.message
+  };
+  
+  const result = await client.sendMessagesByChannelId(
+    channelId,
+    replyText,
+    [], // mentions
+    parentMessage,
+    null, // file
+    generateOptimisticId()
+  );
+  
+  return result;
+}
+```
+
+### File Attachments
+
+```typescript
+// Upload and send media (perfect for artwork sharing)
+async function sendMediaMessage(channelId: string, file: File) {
+  try {
+    // Upload file with encryption support
+    const result = await client.uploadFileMessage(
+      channelId,
+      file,
+      '', // rootMessageId
+      generateOptimisticId(),
+      false // isPost
+    );
+    
+    return result;
+  } catch (error) {
+    console.error('Failed to upload media:', error);
+    throw error;
+  }
+}
+
+// Example: Artist sharing work-in-progress
+const artworkFile = document.getElementById('artwork-input').files[0];
+await sendMediaMessage('art-critique-room', artworkFile);
+```
+
+## Room Management
+
+### Creating Rooms
+
+```typescript
+// Create an encrypted conversation (for private artist collaborations)
+async function createPrivateRoom(users: User[], name: string, coverImage?: File) {
+  const chatInstance = chat.get();
+  
+  const room = await chatInstance.createConversation(
+    users,
+    name,
+    coverImage
+  );
+  
+  return room;
+}
+
+// Create unencrypted room (for public galleries/showcases)
+async function createPublicRoom(
+  users: User[], 
+  name: string, 
+  coverImage?: File, 
+  groupType?: string
+) {
+  const chatInstance = chat.get();
+  
+  const room = await chatInstance.createUnencryptedConversation(
+    users,
+    name,
+    coverImage,
+    groupType // 'social' for community rooms
+  );
+  
+  return room;
+}
+
+// Example: Create artist collaboration room
+const collaborators = await searchUsers('artist');
+const room = await createPrivateRoom(
+  collaborators,
+  'Digital Art Collab - Q4 2024',
+  artworkCoverImage
+);
+```
+
+### Room Administration
+
+```typescript
+// Set user as moderator (for community management)
+async function promoteToModerator(roomId: string, userId: string) {
+  await client.setUserAsModerator(roomId, userId);
+}
+
+// Remove moderator privileges
+async function demoteModerator(roomId: string, userId: string) {
+  await client.removeUserAsModerator(roomId, userId);
+}
+
+// Add members to existing room
+async function addArtistsToGallery(roomId: string, artists: User[]) {
+  await client.addMembersToRoom(roomId, artists);
+}
+
+// Update room details
+async function updateGalleryInfo(roomId: string, name: string, iconUrl: string) {
+  await client.editRoomNameAndIcon(roomId, name, iconUrl);
+}
+```
+
+## Event Handling Patterns
+
+### Real-time Message Processing
+
+```typescript
+// Process incoming messages with sender mapping
+function* processIncomingMessage(action) {
+  const { channelId, message } = action.payload;
+  
+  // Map Matrix user to zOS user profile
+  const enrichedMessage = yield call(mapMessageSenders, [message]);
+  
+  // Update UI state
+  yield put(addMessageToChannel(channelId, enrichedMessage[0]));
+  
+  // Handle notifications for Haven creators
+  if (isCreatorMention(message)) {
+    yield call(notifyCreator, message);
+  }
+}
+
+// Custom event types for Haven Protocol
+enum HavenEventType {
+  ARTWORK_DROP = 'haven.artwork.drop',
+  AUCTION_START = 'haven.auction.start',
+  CREATOR_ANNOUNCEMENT = 'haven.creator.announcement'
+}
+```
+
+### Typing Indicators
+
+```typescript
+// Send typing indicators (enhances community feel)
+async function startTyping(roomId: string) {
+  await client.sendTypingEvent(roomId, true);
+  
+  // Auto-stop after timeout
+  setTimeout(() => {
+    client.sendTypingEvent(roomId, false);
+  }, 5000);
+}
+
+// Handle incoming typing events
+function handleTypingIndicator(roomId: string, userIds: string[]) {
+  const typingUsers = userIds.filter(id => id !== currentUserId);
+  
+  if (typingUsers.length > 0) {
+    showTypingIndicator(roomId, typingUsers);
+  } else {
+    hideTypingIndicator(roomId);
+  }
+}
+```
+
+## Media Handling
+
+### Image Processing with Blurhash
+
+```typescript
+// Enhanced image upload with preview generation
+async function uploadArtworkWithPreview(roomId: string, imageFile: File) {
+  const room = client.getRoom(roomId);
+  const isEncrypted = room?.hasEncryptionStateEvent();
+  
+  // Generate dimensions and blurhash for smooth loading
+  const dimensions = await getImageDimensions(imageFile);
+  const blurhash = await generateBlurhash(imageFile);
+  
+  let uploadUrl;
+  if (isEncrypted) {
+    const encryptedFile = await encryptFile(imageFile);
+    uploadUrl = await client.uploadFile(encryptedFile.file);
+  } else {
+    uploadUrl = await client.uploadFile(imageFile);
+  }
+  
+  // Send with rich metadata
+  const result = await client.uploadFileMessage(
+    roomId,
+    imageFile,
+    '', // rootMessageId
+    generateOptimisticId()
+  );
+  
+  return result;
+}
+```
+
+### Batch File Downloads
+
+```typescript
+// Efficiently download multiple artworks for gallery view
+async function loadGalleryImages(imageUrls: string[]) {
+  const downloadedImages = await client.batchDownloadFiles(
+    imageUrls,
+    true, // generate thumbnails
+    10    // batch size for performance
+  );
+  
+  return downloadedImages;
+}
+```
+
+## Reactions and Engagement
+
+### Custom Reactions (MEOW System)
+
+```typescript
+// Send MEOW reaction (zOS's custom appreciation system)
+async function sendMeowReaction(
+  roomId: string, 
+  messageId: string, 
+  ownerId: string, 
+  amount: number
+) {
+  await client.sendMeowReactionEvent(roomId, messageId, ownerId, amount);
+}
+
+// Send emoji reactions
+async function reactWithEmoji(roomId: string, messageId: string, emoji: string) {
+  await client.sendEmojiReactionEvent(roomId, messageId, emoji);
+}
+
+// Get all reactions for a message
+async function getMessageReactions(roomId: string) {
+  const reactions = await client.getMessageEmojiReactions(roomId);
+  return reactions.reduce((acc, reaction) => {
+    if (!acc[reaction.eventId]) acc[reaction.eventId] = [];
+    acc[reaction.eventId].push(reaction);
+    return acc;
+  }, {});
+}
+```
+
+### Post-style Messages
+
+```typescript
+// Send posts (different from regular messages, good for announcements)
+async function createArtistPost(channelId: string, content: string) {
+  const result = await client.sendPostsByChannelId(
+    channelId,
+    content,
+    generateOptimisticId()
+  );
+  
+  return result;
+}
+
+// Get post-specific reactions with amounts
+async function getPostReactions(roomId: string) {
+  return await client.getPostMessageReactions(roomId);
+}
+```
+
+## Read Receipts and Presence
+
+### Managing Read Status
+
+```typescript
+// Mark room as read (important for community management)
+async function markGalleryAsRead(roomId: string) {
+  await client.markRoomAsRead(roomId);
+}
+
+// Set read receipt preferences
+async function setReadReceiptPrivacy(isPrivate: boolean) {
+  const preference = isPrivate ? 'private' : 'public';
+  await client.setReadReceiptPreference(preference);
+}
+
+// Get who has read a specific message
+async function getMessageReadBy(roomId: string, messageId: string) {
+  const receipts = await client.getMessageReadReceipts(roomId, messageId);
+  return receipts.map(receipt => ({
+    userId: receipt.userId,
+    timestamp: receipt.ts
+  }));
+}
+```
+
+## Room Discovery and Management
+
+### Room Aliases and Labels
+
+```typescript
+// Create friendly room aliases (e.g., #digital-art-gallery)
+async function createRoomAlias(roomId: string, alias: string) {
+  // Note: Alias creation requires homeserver admin privileges
+  // This is typically done through room creation options
+  const room = await client.createRoom({
+    room_alias_name: alias,
+    // ... other options
+  });
+  return room;
+}
+
+// Find room by alias
+async function findRoomByAlias(alias: string) {
+  const roomId = await client.getRoomIdForAlias(`#${alias}:${homeServerDomain}`);
+  return roomId;
+}
+
+// Organize rooms with labels (tags)
+async function tagRoom(roomId: string, category: string) {
+  await client.addRoomToLabel(roomId, category);
+}
+
+// Remove room from category
+async function untagRoom(roomId: string, category: string) {
+  await client.removeRoomFromLabel(roomId, category);
+}
+```
+
+## Encryption and Security
+
+### Secure Backup Management
+
+```typescript
+// Generate secure backup for encryption keys
+async function createSecureBackup() {
+  const recoveryKey = await client.generateSecureBackup();
+  
+  // Store recovery key securely (user responsibility)
+  return recoveryKey.encodedPrivateKey;
+}
+
+// Save backup to homeserver
+async function saveBackupToServer(recoveryKey: string) {
+  await client.saveSecureBackup(recoveryKey);
+}
+
+// Restore from backup
+async function restoreFromBackup(
+  recoveryKey: string, 
+  onProgress?: (progress: ImportRoomKeyProgressData) => void
+) {
+  await client.restoreSecureBackup(recoveryKey, onProgress);
+}
+
+// Check backup status
+async function getBackupStatus() {
+  const backup = await client.getSecureBackup();
+  
+  return {
+    exists: !!backup?.trustInfo,
+    trusted: backup?.trustInfo?.trusted || false,
+    crossSigning: backup?.crossSigning || false
+  };
+}
+```
+
+## Error Handling and Debugging
+
+### Connection Management
+
+```typescript
+// Robust connection handling
+class MatrixConnectionManager {
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts = 5;
+  
+  async connectWithRetry(userId: string, accessToken: string) {
+    try {
+      await client.connect(userId, accessToken);
+      this.reconnectAttempts = 0;
+    } catch (error) {
+      console.error('Matrix connection failed:', error);
+      
+      if (this.reconnectAttempts < this.maxReconnectAttempts) {
+        this.reconnectAttempts++;
+        const delay = Math.pow(2, this.reconnectAttempts) * 1000; // Exponential backoff
+        
+        setTimeout(() => {
+          this.connectWithRetry(userId, accessToken);
+        }, delay);
+      } else {
+        throw new Error('Max reconnection attempts exceeded');
+      }
+    }
+  }
+  
+  async handleConnectionLoss() {
+    // Implement graceful degradation
+    // Queue messages while offline
+    // Sync when reconnected
+  }
+}
+```
+
+### Message Validation
+
+```typescript
+// Validate messages before sending
+function validateMessage(message: string, channelId: string): boolean {
+  if (!message.trim()) {
+    throw new Error('Empty message not allowed');
+  }
+  
+  if (message.length > 65536) {
+    throw new Error('Message too long');
+  }
+  
+  if (!channelId) {
+    throw new Error('Channel ID required');
+  }
+  
+  return true;
+}
+
+// Handle send failures gracefully
+async function sendMessageWithRetry(
+  channelId: string, 
+  message: string, 
+  maxRetries = 3
+) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      validateMessage(message, channelId);
+      return await client.sendMessagesByChannelId(channelId, message, []);
+    } catch (error) {
+      if (attempt === maxRetries) {
+        throw error;
+      }
+      
+      // Wait before retry
+      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+    }
+  }
+}
+```
+
+## Haven Protocol Integration Patterns
+
+### Creator Community Rooms
+
+```typescript
+// Setup for Haven Protocol creator communities
+async function createCreatorCommunity(
+  creatorProfile: CreatorProfile,
+  initialMembers: User[]
+) {
+  // Create main community room
+  const communityRoom = await createUnencryptedConversation(
+    initialMembers,
+    `${creatorProfile.name} Community`,
+    creatorProfile.coverImage,
+    'social'
+  );
+  
+  // Create private creator workspace
+  const workspaceRoom = await createPrivateRoom(
+    [creatorProfile.user, ...creatorProfile.collaborators],
+    `${creatorProfile.name} - Workspace`
+  );
+  
+  // Tag rooms for organization
+  await tagRoom(communityRoom.id, 'haven:community');
+  await tagRoom(workspaceRoom.id, 'haven:workspace');
+  
+  return {
+    community: communityRoom,
+    workspace: workspaceRoom
+  };
+}
+```
+
+### Artwork Drop Events
+
+```typescript
+// Custom event for artwork drops
+async function announceArtworkDrop(
+  roomId: string,
+  artwork: ArtworkInfo,
+  dropTime: Date
+) {
+  const announcement = `
+🎨 New Artwork Drop Alert! 
+
+"${artwork.title}" by ${artwork.artist}
+Drop Time: ${dropTime.toLocaleString()}
+Preview: ${artwork.previewUrl}
+
+Get ready collectors! #ArtDrop #DigitalArt
+  `;
+  
+  // Send as post for better visibility
+  const result = await client.sendPostsByChannelId(
+    roomId,
+    announcement,
+    generateOptimisticId()
+  );
+  
+  // Schedule reminder if needed
+  scheduleDropReminder(roomId, artwork, dropTime);
+  
+  return result;
+}
+```
+
+## Performance Optimization
+
+### Message Pagination
+
+```typescript
+// Efficient message loading with pagination
+async function loadChannelHistory(
+  channelId: string, 
+  lastTimestamp?: number, 
+  limit = 50
+) {
+  const response = await client.getMessagesByChannelId(
+    channelId,
+    lastTimestamp
+  );
+  
+  return {
+    messages: response.messages.slice(0, limit),
+    hasMore: response.hasMore,
+    nextTimestamp: response.messages[response.messages.length - 1]?.createdAt
+  };
+}
+
+// Infinite scroll implementation
+class InfiniteMessageLoader {
+  private loading = false;
+  private hasMore = true;
+  
+  async loadMore(channelId: string, currentMessages: Message[]) {
+    if (this.loading || !this.hasMore) return currentMessages;
+    
+    this.loading = true;
+    try {
+      const lastMessage = currentMessages[0];
+      const olderMessages = await loadChannelHistory(
+        channelId,
+        lastMessage?.createdAt
+      );
+      
+      this.hasMore = olderMessages.hasMore;
+      return [...olderMessages.messages, ...currentMessages];
+    } finally {
+      this.loading = false;
+    }
+  }
+}
+```
+
+### Sliding Sync Integration
+
+```typescript
+// Efficient room sync using Matrix Sliding Sync
+class RoomSyncManager {
+  async addRoomToSync(roomId: string) {
+    await SlidingSyncManager.instance.addRoomToSync(roomId);
+  }
+  
+  async removeRoomFromSync(roomId: string) {
+    await SlidingSyncManager.instance.removeRoomFromSync(roomId);
+  }
+  
+  // Optimize sync for active conversations
+  async optimizeForActiveRooms(activeRoomIds: string[]) {
+    const allRooms = client.getRooms();
+    
+    for (const room of allRooms) {
+      if (activeRoomIds.includes(room.roomId)) {
+        await this.addRoomToSync(room.roomId);
+      } else {
+        await this.removeRoomFromSync(room.roomId);
+      }
+    }
+  }
+}
+```
+
+## Testing Strategies
+
+### Mock Matrix Client
+
+```typescript
+// Mock for testing without Matrix homeserver
+class MockMatrixClient {
+  private messages: Map<string, Message[]> = new Map();
+  private rooms: Map<string, Room> = new Map();
+  
+  async sendMessagesByChannelId(
+    channelId: string,
+    message: string
+  ): Promise<{ id: string; optimisticId: string }> {
+    const messageId = `msg_${Date.now()}`;
+    const mockMessage: Message = {
+      id: messageId,
+      message,
+      createdAt: Date.now(),
+      senderId: 'test-user',
+      // ... other required fields
+    };
+    
+    const channelMessages = this.messages.get(channelId) || [];
+    channelMessages.push(mockMessage);
+    this.messages.set(channelId, channelMessages);
+    
+    return { id: messageId, optimisticId: 'test-optimistic' };
+  }
+  
+  async getMessagesByChannelId(channelId: string) {
+    return {
+      messages: this.messages.get(channelId) || [],
+      hasMore: false
+    };
+  }
+}
+```
+
+### Integration Tests
+
+```typescript
+// Test Matrix integration with real scenarios
+describe('Matrix Integration', () => {
+  let client: MatrixClient;
+  
+  beforeEach(async () => {
+    client = new MatrixClient();
+    await client.connect('test-user', 'test-token');
+  });
+  
+  it('should send and receive messages', async () => {
+    const roomId = 'test-room';
+    const testMessage = 'Hello, Haven Protocol!';
+    
+    const sent = await client.sendMessagesByChannelId(roomId, testMessage, []);
+    expect(sent.id).toBeTruthy();
+    
+    const messages = await client.getMessagesByChannelId(roomId);
+    expect(messages.messages.some(m => m.id === sent.id)).toBeTruthy();
+  });
+  
+  it('should handle file uploads', async () => {
+    const file = createTestImageFile();
+    const roomId = 'test-room';
+    
+    const result = await client.uploadFileMessage(roomId, file);
+    expect(result.id).toBeTruthy();
+  });
+});
+```
+
+## Common Pitfalls and Solutions
+
+### 1. Message Ordering Issues
+
+**Problem**: Messages appearing out of order due to async operations.
+
+**Solution**: Use origin_server_ts for consistent ordering:
+
+```typescript
+// Sort messages by server timestamp, not client timestamp
+const sortedMessages = messages.sort((a, b) => a.createdAt - b.createdAt);
+```
+
+### 2. Memory Leaks with Event Listeners
+
+**Problem**: Event listeners not properly cleaned up.
+
+**Solution**: Always clean up listeners:
+
+```typescript
+class MatrixManager {
+  private eventHandlers = new Map();
+  
+  addEventHandler(eventType: string, handler: Function) {
+    this.eventHandlers.set(eventType, handler);
+    client.on(eventType, handler);
+  }
+  
+  cleanup() {
+    for (const [eventType, handler] of this.eventHandlers) {
+      client.removeListener(eventType, handler);
+    }
+    this.eventHandlers.clear();
+  }
+}
+```
+
+### 3. Encryption Key Management
+
+**Problem**: Lost encryption keys make message history unreadable.
+
+**Solution**: Implement robust backup strategies:
+
+```typescript
+// Check encryption status before sensitive operations
+async function ensureEncryptionReadiness(roomId: string) {
+  const room = client.getRoom(roomId);
+  if (room?.hasEncryptionStateEvent()) {
+    const backup = await client.getSecureBackup();
+    if (!backup || !backup.trustInfo.trusted) {
+      throw new Error('Encryption backup required for this room');
+    }
+  }
+}
+```
+
+### 4. Rate Limiting
+
+**Problem**: Hitting Matrix homeserver rate limits.
+
+**Solution**: Implement rate limiting and queuing:
+
+```typescript
+class MessageQueue {
+  private queue: Array<() => Promise<any>> = [];
+  private processing = false;
+  private lastSend = 0;
+  private minInterval = 100; // 100ms between sends
+  
+  async enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      this.queue.push(async () => {
+        try {
+          const result = await operation();
+          resolve(result);
+        } catch (error) {
+          reject(error);
+        }
+      });
+      
+      this.processQueue();
+    });
+  }
+  
+  private async processQueue() {
+    if (this.processing || this.queue.length === 0) return;
+    
+    this.processing = true;
+    
+    while (this.queue.length > 0) {
+      const now = Date.now();
+      const timeSinceLastSend = now - this.lastSend;
+      
+      if (timeSinceLastSend < this.minInterval) {
+        await new Promise(resolve => 
+          setTimeout(resolve, this.minInterval - timeSinceLastSend)
+        );
+      }
+      
+      const operation = this.queue.shift();
+      await operation();
+      this.lastSend = Date.now();
+    }
+    
+    this.processing = false;
+  }
+}
+```
+
+## Conclusion
+
+This Matrix integration guide provides the foundation for building rich, real-time communication features in zOS. The patterns shown here are particularly well-suited for Haven Protocol's creator communities, enabling:
+
+- **Real-time collaboration** between artists and collectors
+- **Rich media sharing** for artwork and creative processes  
+- **Community management** tools for creator spaces
+- **Secure, encrypted** conversations for sensitive collaborations
+- **Custom events and reactions** for engagement
+
+The event-driven architecture and comprehensive error handling ensure reliable performance at scale, while the modular design allows for easy customization and extension for specific use cases.
+
+For Haven Protocol implementers, focus on the room management patterns, custom event types, and media handling capabilities to create compelling creator community experiences.
\ No newline at end of file
diff --git a/opusdocs/new-recruits/agent-implementation-guide.md b/opusdocs/new-recruits/agent-implementation-guide.md
new file mode 100644
index 00000000..69be1990
--- /dev/null
+++ b/opusdocs/new-recruits/agent-implementation-guide.md
@@ -0,0 +1,122 @@
+# Step-by-Step Agent Implementation Guide
+
+## Overview
+This guide helps you use the agent team to generate comprehensive documentation for zOS.
+
+## Prerequisites
+- Access to Claude Code with the `/agent` command
+- The zOS repository with the agent meta-prompts in `./agents-only/meta-prompts/`
+
+## Implementation Steps
+
+### Step 1: Generate Architecture Overview
+```bash
+/agent general-purpose "Using the meta-prompt from ./agents-only/meta-prompts/architecture-guide-agent.md, analyze the zOS codebase and create a comprehensive architecture overview. Focus on helping new developers understand the mental model of how zOS works."
+```
+
+**Expected Output**: `./opusdocs/architecture-overview.md`
+
+### Step 2: Create Component Reference
+```bash
+/agent general-purpose "Using the meta-prompt from ./agents-only/meta-prompts/developer-reference-agent.md, document the key React components in /src/components/. Start with the most commonly used components like Avatar, Modal, and Button. Include TypeScript types and practical examples."
+```
+
+**Expected Output**: `./opusdocs/developer-reference/components.md`
+
+### Step 3: Document Custom Hooks
+```bash
+/agent general-purpose "Using the meta-prompt from ./agents-only/meta-prompts/developer-reference-agent.md, document all custom hooks in /src/lib/hooks/. Show practical usage examples and explain when to use each hook."
+```
+
+**Expected Output**: `./opusdocs/developer-reference/hooks.md`
+
+### Step 4: Create Contribution Guide
+```bash
+/agent general-purpose "Using the meta-prompt from ./agents-only/meta-prompts/contribution-guide-agent.md, create a welcoming contribution guide specifically for new developers' skill level. Include step-by-step instructions for making first contributions to zOS."
+```
+
+**Expected Output**: `./opusdocs/new-recruits/contribution-guide.md`
+
+### Step 5: Document Development Workflow
+```bash
+/agent general-purpose "Using the meta-prompt from ./agents-only/meta-prompts/development-workflow-agent.md, create a practical development workflow guide. Include daily tasks, debugging strategies, and productivity tips for working with the zOS codebase."
+```
+
+**Expected Output**: `./opusdocs/new-recruits/development-workflow.md`
+
+### Step 6: Create Integration Guides
+```bash
+# Matrix Integration
+/agent general-purpose "Using the meta-prompt from ./agents-only/meta-prompts/integration-expert-agent.md, document how Matrix chat integration works in zOS. Include practical examples of sending messages, handling events, and managing rooms."
+
+# Blockchain Integration
+/agent general-purpose "Using the meta-prompt from ./agents-only/meta-prompts/integration-expert-agent.md, create a blockchain integration guide focusing on wallet connections, transactions, and smart contract interactions in zOS."
+```
+
+**Expected Outputs**: 
+- `./opusdocs/integration-guide.md`
+- `./opusdocs/blockchain-integration.md`
+
+## Tips for Success
+
+### 1. Run Agents in Order
+- Start with architecture (provides context for everything else)
+- Then do reference documentation
+- Finally, create guides and workflows
+
+### 2. Review and Iterate
+- Check each output before moving to the next
+- Agents can refine their work if needed:
+  ```bash
+  /agent general-purpose "Review the architecture overview in ./opusdocs/architecture-overview.md and add a section about performance considerations and optimization strategies used in zOS."
+  ```
+
+### 3. Cross-Reference Documents
+- Ensure documents link to each other
+- Use consistent terminology (check `./agents-only/shared/terminology.md`)
+
+### 4. Customize for Your Needs
+- Modify the meta-prompts if you need different focus areas
+- Add new agents for specific documentation needs
+
+## Common Patterns
+
+### Adding Examples
+```bash
+/agent general-purpose "Add more practical examples to the hooks documentation in ./opusdocs/developer-reference/hooks.md, specifically showing how to use hooks with TypeScript and error handling."
+```
+
+### Creating Cheatsheets
+```bash
+/agent general-purpose "Create a quick-reference cheatsheet for common Redux-Saga patterns used in zOS. Save to ./opusdocs/new-recruits/redux-saga-cheatsheet.md"
+```
+
+### Documenting Specific Features
+```bash
+/agent general-purpose "Document how to add a new app module to zOS, including all necessary files, Redux setup, and routing configuration. Save to ./opusdocs/new-recruits/creating-new-app-module.md"
+```
+
+## Troubleshooting
+
+### If Documentation Seems Incomplete
+- Check if the agent had access to all necessary files
+- Provide specific file paths in your prompts
+- Ask the agent to explore specific directories
+
+### If Examples Don't Work
+- Verify against the actual codebase
+- Check for recent changes in the code
+- Update examples to match current patterns
+
+### If Terminology Is Inconsistent
+- Refer agents to `./agents-only/shared/terminology.md`
+- Do a final consistency pass across all documents
+
+## Next Steps
+1. Start with Step 1 (Architecture Overview)
+2. Review the output
+3. Proceed through each step
+4. Customize based on what you learn
+5. Share feedback to improve the process
+
+Remember: The goal is to create documentation that helps you (and developers like you) contribute effectively to zOS!
\ No newline at end of file
diff --git a/opusdocs/new-recruits/contribution-guide.md b/opusdocs/new-recruits/contribution-guide.md
new file mode 100644
index 00000000..5078a471
--- /dev/null
+++ b/opusdocs/new-recruits/contribution-guide.md
@@ -0,0 +1,405 @@
+# Your Welcome Guide to Contributing to zOS
+
+Welcome to the zOS contribution journey! This guide is specifically crafted to help you make meaningful contributions to one of the most sophisticated decentralized operating systems. Whether you're just getting started or ready to tackle bigger challenges, we'll guide you step by step.
+
+## Getting Started
+
+### Understanding zOS
+zOS is a React-based decentralized operating system with a rich ecosystem including:
+- **Matrix Integration**: Real-time messaging and communication
+- **Web3 Features**: Wallet integration, staking, NFTs
+- **Modern Architecture**: TypeScript, Redux-Saga, and component-driven design
+- **Professional Standards**: Comprehensive testing, code quality, and documentation
+
+### Your Development Environment Setup
+
+#### Prerequisites Checklist
+- [ ] Node.js 20.11.0+ installed
+- [ ] npm 10.2.4+ installed  
+- [ ] Git configured with your GitHub account
+- [ ] Code editor with TypeScript support (VS Code recommended)
+
+#### Getting Your Local Environment Ready
+```bash
+# Clone the repository
+git clone https://github.com/your-org/zOS.git
+cd zOS
+
+# Install dependencies
+npm install
+
+# Start the development server
+npm start
+
+# In another terminal, run tests to ensure everything works
+npm test
+```
+
+**Success Check**: Visit `http://localhost:3000` - you should see the zOS interface.
+
+#### Understanding the Codebase Structure
+```
+src/
+├── apps/           # Major application modules (messenger, wallet, etc.)
+├── components/     # Reusable UI components
+├── lib/           # Utility functions and custom hooks
+├── store/         # Redux state management with sagas
+├── authentication/ # Login and signup flows
+└── platform-apps/ # Specific platform integrations
+```
+
+## Your Contribution Journey
+
+### Phase 1: Getting Comfortable (First 2-3 PRs)
+
+#### 1.1 Documentation Improvements
+**What to Look For:**
+- Typos in comments or README files
+- Missing JSDoc comments on functions
+- Outdated documentation
+
+**Example First Contribution:**
+```typescript
+// BEFORE: Missing documentation
+export const formatAddress = (address: string) => {
+  return `${address.slice(0, 6)}...${address.slice(-4)}`;
+};
+
+// AFTER: Well-documented
+/**
+ * Formats a wallet address for display by showing first 6 and last 4 characters
+ * @param address - The full wallet address to format
+ * @returns Formatted address like "0x1234...abcd"
+ */
+export const formatAddress = (address: string) => {
+  return `${address.slice(0, 6)}...${address.slice(-4)}`;
+};
+```
+
+#### 1.2 Small UI Improvements
+**Perfect Starter Tasks:**
+- Adjusting button spacing or colors
+- Adding loading states to buttons
+- Improving accessibility (adding ARIA labels)
+- Fixing minor styling inconsistencies
+
+**Example Component Enhancement:**
+```tsx
+// Find a button component and add a loading state
+interface ButtonProps {
+  onClick: () => void;
+  children: React.ReactNode;
+  isLoading?: boolean; // Add this prop
+}
+
+export const Button = ({ onClick, children, isLoading }: ButtonProps) => (
+  <button 
+    onClick={onClick} 
+    disabled={isLoading}
+    className={styles.button}
+  >
+    {isLoading ? 'Loading...' : children}
+  </button>
+);
+```
+
+### Phase 2: Building Confidence (Next 3-5 PRs)
+
+#### 2.1 Bug Fixes
+**How to Find Bugs:**
+1. Look for open issues labeled "bug" or "good first issue"
+2. Test the application and note anything that feels wrong
+3. Check console logs for warnings or errors
+
+**Example Bug Fix Process:**
+```typescript
+// Bug: Avatar component doesn't show fallback for broken images
+// File: src/components/avatar/index.tsx
+
+// BEFORE
+<img src={imageURL} alt="avatar" />
+
+// AFTER
+<img 
+  src={imageURL} 
+  alt="avatar"
+  onError={(e) => {
+    e.currentTarget.src = '/default-avatar.png';
+  }}
+/>
+```
+
+#### 2.2 Adding Tests
+**Testing Strategy in zOS:**
+- Components use Enzyme for shallow rendering
+- Sagas use `redux-saga-test-plan`
+- Utilities use straightforward Jest unit tests
+
+**Example Test Addition:**
+```typescript
+// File: src/lib/address.test.ts
+import { formatAddress } from './address';
+
+describe('formatAddress', () => {
+  it('should format a valid address correctly', () => {
+    const address = '0x1234567890abcdef1234567890abcdef12345678';
+    const result = formatAddress(address);
+    expect(result).toBe('0x1234...5678');
+  });
+
+  it('should handle short addresses gracefully', () => {
+    const address = '0x123';
+    const result = formatAddress(address);
+    expect(result).toBe('0x123');
+  });
+});
+```
+
+### Phase 3: Feature Development (Ongoing)
+
+#### 3.1 Small Features
+**Good Feature Ideas:**
+- Adding keyboard shortcuts to existing components
+- Creating new utility hooks
+- Implementing loading skeletons
+- Adding form validation improvements
+
+**Example Feature: Custom Hook**
+```typescript
+// File: src/lib/hooks/useClipboard.ts
+import { useState } from 'react';
+
+export const useClipboard = () => {
+  const [copied, setCopied] = useState(false);
+
+  const copy = async (text: string) => {
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch (error) {
+      console.error('Failed to copy text:', error);
+    }
+  };
+
+  return { copy, copied };
+};
+```
+
+#### 3.2 Component Enhancements
+**Enhancement Opportunities:**
+- Adding new props to existing components
+- Improving accessibility
+- Adding animation or micro-interactions
+- Creating variant styles
+
+## Code Standards & Best Practices
+
+### TypeScript Conventions
+```typescript
+// ✅ Good: Explicit types and clear interfaces
+interface UserProfileProps {
+  userId: string;
+  displayName: string;
+  avatarUrl?: string;
+  onFollow: (userId: string) => void;
+}
+
+// ✅ Good: Proper error handling
+const fetchUserProfile = async (userId: string): Promise<UserProfile | null> => {
+  try {
+    const response = await api.get(`/users/${userId}`);
+    return response.data;
+  } catch (error) {
+    console.error('Failed to fetch user profile:', error);
+    return null;
+  }
+};
+```
+
+### React Component Patterns
+```typescript
+// ✅ Good: Proper component structure
+interface AvatarProps {
+  size: 'small' | 'medium' | 'large';
+  imageURL?: string;
+  fallbackText: string;
+}
+
+export const Avatar: React.FC<AvatarProps> = ({ 
+  size, 
+  imageURL, 
+  fallbackText 
+}) => {
+  const [imageError, setImageError] = useState(false);
+  
+  return (
+    <div className={`avatar avatar--${size}`}>
+      {imageURL && !imageError ? (
+        <img 
+          src={imageURL}
+          alt={fallbackText}
+          onError={() => setImageError(true)}
+        />
+      ) : (
+        <span>{fallbackText.charAt(0).toUpperCase()}</span>
+      )}
+    </div>
+  );
+};
+```
+
+### Testing Requirements
+**All PRs Must Include:**
+- Unit tests for new utilities/functions
+- Component tests for new components
+- Integration tests for complex features
+- All existing tests must pass
+
+### Styling with SCSS & BEM
+```scss
+// ✅ Good: Follow BEM methodology
+.user-profile {
+  padding: 16px;
+  
+  &__avatar {
+    margin-right: 12px;
+  }
+  
+  &__name {
+    font-weight: 600;
+    color: theme.$color-text-primary;
+    
+    &--verified {
+      color: theme.$color-success;
+    }
+  }
+}
+```
+
+## The Pull Request Process
+
+### Before You Submit
+**Pre-Submission Checklist:**
+- [ ] Code follows the style guide
+- [ ] All tests pass (`npm test`)
+- [ ] Build succeeds (`npm run build`)
+- [ ] No TypeScript errors
+- [ ] Added tests for new functionality
+- [ ] Updated documentation if needed
+
+### PR Template Usage
+When you create a PR, fill out the template sections:
+
+```markdown
+### What does this do?
+Added a clipboard copy feature to the wallet address display
+
+### Why are we making this change?
+Users frequently need to copy their wallet addresses for external use
+
+### How do I test this?
+1. Navigate to wallet page
+2. Click the copy button next to your address
+3. Verify the address is copied to clipboard
+4. Check that success feedback is shown
+
+### Key decisions and Risk Assessment:
+- Used native clipboard API with fallback
+- No security concerns as this only copies public addresses
+- Performance impact is minimal
+```
+
+### Branch Naming Convention
+```bash
+# ✅ Good branch names
+git checkout -b feature/clipboard-copy-wallet-address
+git checkout -b fix/avatar-image-loading-error  
+git checkout -b docs/update-contribution-guide
+```
+
+### Commit Message Format
+```bash
+# ✅ Good commit messages
+git commit -m "feat: add clipboard copy to wallet address display"
+git commit -m "fix: handle avatar image loading errors gracefully"
+git commit -m "test: add unit tests for formatAddress utility"
+```
+
+## Getting Help & Communication
+
+### Where to Ask Questions
+- **GitHub Issues**: For bugs and feature requests
+- **PR Comments**: For code-specific discussions
+- **Team Chat**: For quick questions and clarifications
+
+### Code Review Process
+**What to Expect:**
+1. Automated checks run (tests, linting, build)
+2. Team member reviews within 1-2 business days
+3. Address feedback with additional commits
+4. Approval and merge by maintainer
+
+**Common Review Feedback:**
+- "Can you add a test for this function?"
+- "This could be more type-safe with a stricter interface"
+- "Consider extracting this logic into a custom hook"
+- "The styling should follow our BEM conventions"
+
+### Response Time Expectations
+- **Initial Review**: 1-2 business days
+- **Follow-up Reviews**: Same day to 1 business day
+- **Questions in Issues**: Within 24 hours
+
+## Learning Resources
+
+### zOS-Specific Knowledge
+- Review existing components in `/src/components/` for patterns
+- Study the Redux-Saga patterns in `/src/store/`
+- Look at how Matrix integration works in `/src/lib/chat/`
+- Understand Web3 patterns in `/src/lib/web3/`
+
+### General Skills Development
+- **TypeScript**: Official TypeScript docs
+- **React Testing**: Enzyme and Jest documentation
+- **Redux-Saga**: Official saga documentation
+- **SCSS/BEM**: BEM methodology guide
+
+## Your Next Steps
+
+### Immediate Actions (This Week)
+1. Set up your development environment
+2. Find your first documentation or small UI fix
+3. Create your first PR
+4. Join team communication channels
+
+### Short-term Goals (Next Month)
+1. Complete 2-3 small PRs successfully
+2. Fix your first bug
+3. Add your first test
+4. Understand the component architecture
+
+### Long-term Growth (Next Quarter)  
+1. Implement your first feature
+2. Help review other contributors' PRs
+3. Contribute to architectural discussions
+4. Mentor new contributors
+
+## Success Stories & Inspiration
+
+Remember, every expert contributor started exactly where you are now. The zOS codebase is sophisticated, but it's also well-structured and designed to help you learn. Each contribution you make:
+
+- **Builds Your Skills**: Every PR teaches you something new
+- **Helps Users**: Real people use zOS daily
+- **Advances Web3**: You're contributing to the decentralized future
+- **Grows Your Network**: Connect with other talented developers
+
+## Final Encouragement
+
+Contributing to zOS is a journey of continuous learning and growth. Start small, be consistent, and don't hesitate to ask questions. The team values thoughtful contributions over perfect code, and every suggestion or improvement helps make zOS better.
+
+Your unique perspective and fresh eyes are valuable assets to the project. Welcome to the team, and we're excited to see what you'll build!
+
+---
+
+*This guide is a living document. As you gain experience, consider contributing improvements to help future contributors on their journey.*
\ No newline at end of file
diff --git a/opusdocs/new-recruits/development-workflow.md b/opusdocs/new-recruits/development-workflow.md
new file mode 100644
index 00000000..12013f31
--- /dev/null
+++ b/opusdocs/new-recruits/development-workflow.md
@@ -0,0 +1,736 @@
+# zOS Development Workflow Guide
+
+A comprehensive guide for efficient development, debugging, and productivity when working with the zOS codebase.
+
+## Table of Contents
+
+1. [Daily Development Workflow](#daily-development-workflow)
+2. [Feature Development Flow](#feature-development-flow)
+3. [Debugging Strategies](#debugging-strategies)
+4. [Testing Workflows](#testing-workflows)
+5. [Build & Deploy](#build--deploy)
+6. [Productivity Tips](#productivity-tips)
+7. [Tool Configuration](#tool-configuration)
+
+## Daily Development Workflow
+
+### Starting Your Development Environment
+
+1. **Environment Setup**
+   ```bash
+   # Start the Vite development server
+   npm start
+   
+   # Alternative for legacy systems
+   npm run start:legacy
+   
+   # For Electron development
+   npm run electron:start
+   ```
+
+2. **Hot Reload & Fast Refresh**
+   - Vite provides instant hot module replacement (HMR)
+   - React Fast Refresh preserves component state during development
+   - SCSS changes reflect immediately without page refresh
+   - Redux DevTools state persists through most code changes
+
+3. **Browser DevTools Setup**
+   - **Chrome/Edge**: Press F12 or Ctrl+Shift+I
+   - **Firefox**: Press F12 or Ctrl+Shift+I
+   - Enable "Preserve log" in Console tab for debugging page navigation
+   - Use Network tab with "Disable cache" for testing fresh loads
+
+4. **Redux DevTools Usage**
+   ```javascript
+   // Access Redux state in console
+   window.store.getState()
+   
+   // Feature flags accessible globally
+   window.FEATURE_FLAGS.enableDevPanel = true
+   
+   // Check current user state
+   window.store.getState().authentication.user
+   ```
+
+### Essential Development Commands
+
+```bash
+# Development
+npm start                    # Start Vite dev server (port 3000)
+npm run test:vitest         # Run Vitest tests in watch mode
+npm run lint                # Check ESLint rules
+npm run lint:fix            # Auto-fix ESLint issues
+
+# Code Quality
+npm run code-format:fix     # Format code with Prettier
+npm run code-format:validate # Check code formatting
+
+# Testing
+npm test                    # Run all tests (legacy)
+npm run test:vitest         # Run Vitest tests
+vitest run --reporter=verbose # Run tests with detailed output
+```
+
+## Feature Development Flow
+
+### Planning a New Feature
+
+1. **Architecture Review**
+   - Check if Redux state needs modification
+   - Identify required API endpoints
+   - Plan component hierarchy
+   - Consider Matrix.js integration if chat-related
+
+2. **Feature Flag Setup**
+   ```typescript
+   // Add to src/lib/feature-flags/development.ts
+   export const developmentFlags = {
+     // ... existing flags
+     enableMyNewFeature: { defaultValue: true },
+   };
+   
+   // Use in components
+   import { featureFlags } from '../../lib/feature-flags';
+   
+   if (featureFlags.enableMyNewFeature) {
+     // Feature code here
+   }
+   ```
+
+### Creating Components
+
+1. **Component Structure**
+   ```
+   src/components/my-feature/
+   ├── index.tsx              # Main component
+   ├── index.vitest.tsx       # Vitest tests
+   ├── container.tsx          # Redux container (if needed)
+   ├── styles.module.scss     # Component styles
+   └── lib/
+       ├── types.ts           # TypeScript types
+       ├── hooks.ts           # Custom hooks
+       └── utils.ts           # Utility functions
+   ```
+
+2. **Component Template**
+   ```typescript
+   // src/components/my-feature/index.tsx
+   import React from 'react';
+   import { bemClassName } from '../../lib/bem';
+   import './styles.module.scss';
+   
+   const cn = bemClassName('my-feature');
+   
+   export interface Properties {
+     // Define props
+   }
+   
+   export const MyFeature: React.FC<Properties> = ({ ...props }) => {
+     return (
+       <div {...cn('')}>
+         {/* Component content */}
+       </div>
+     );
+   };
+   
+   export default MyFeature;
+   ```
+
+3. **SCSS Styling with BEM**
+   ```scss
+   // src/components/my-feature/styles.module.scss
+   @use '~@zero-tech/zui/styles/theme' as theme;
+   @import '../../functions';
+   @import '../../animation';
+   
+   .my-feature {
+     // Block styles
+     
+     &__element {
+       // Element styles
+       color: theme.$color-primary;
+     }
+     
+     &--modifier {
+       // Modifier styles
+     }
+   }
+   ```
+
+### Adding Redux State
+
+1. **Create Store Module**
+   ```
+   src/store/my-feature/
+   ├── index.ts               # Actions, types, reducer
+   ├── saga.ts                # Redux-Saga logic
+   ├── saga.test.ts           # Saga tests
+   ├── selectors.ts           # State selectors
+   ├── api.ts                 # API calls
+   └── types.ts               # TypeScript interfaces
+   ```
+
+2. **Redux Toolkit Slice**
+   ```typescript
+   // src/store/my-feature/index.ts
+   import { createSlice, PayloadAction } from '@reduxjs/toolkit';
+   
+   export interface State {
+     loading: boolean;
+     data: any[];
+     error: string | null;
+   }
+   
+   const initialState: State = {
+     loading: false,
+     data: [],
+     error: null,
+   };
+   
+   export const slice = createSlice({
+     name: 'myFeature',
+     initialState,
+     reducers: {
+       startRequest: (state) => {
+         state.loading = true;
+       },
+       requestSuccess: (state, action: PayloadAction<any[]>) => {
+         state.loading = false;
+         state.data = action.payload;
+       },
+       requestFailure: (state, action: PayloadAction<string>) => {
+         state.loading = false;
+         state.error = action.payload;
+       },
+     },
+   });
+   
+   export const SagaActionTypes = {
+     FETCH_DATA: 'my-feature/saga/FETCH_DATA',
+   };
+   
+   export const { startRequest, requestSuccess, requestFailure } = slice.actions;
+   export const reducer = slice.reducer;
+   ```
+
+### Writing Sagas
+
+1. **Saga Structure**
+   ```typescript
+   // src/store/my-feature/saga.ts
+   import { takeLatest, put, call, select } from 'redux-saga/effects';
+   import { PayloadAction } from '@reduxjs/toolkit';
+   import { startRequest, requestSuccess, requestFailure, SagaActionTypes } from './';
+   import { apiCall } from './api';
+   
+   function* fetchDataSaga(action: PayloadAction<{ id: string }>) {
+     try {
+       yield put(startRequest());
+       const data = yield call(apiCall, action.payload.id);
+       yield put(requestSuccess(data));
+     } catch (error) {
+       yield put(requestFailure(error.message));
+     }
+   }
+   
+   export function* saga() {
+     yield takeLatest(SagaActionTypes.FETCH_DATA, fetchDataSaga);
+   }
+   ```
+
+2. **Testing Sagas**
+   ```typescript
+   // src/store/my-feature/saga.test.ts
+   import { expectSaga } from 'redux-saga-test-plan';
+   import * as matchers from 'redux-saga-test-plan/matchers';
+   import { fetchDataSaga } from './saga';
+   import { startRequest, requestSuccess } from './';
+   import { apiCall } from './api';
+   
+   describe('my-feature saga', () => {
+     it('fetches data successfully', () => {
+       const action = { payload: { id: '123' } };
+       const mockData = [{ id: '123', name: 'Test' }];
+       
+       return expectSaga(fetchDataSaga, action)
+         .put(startRequest())
+         .call(apiCall, '123')
+         .put(requestSuccess(mockData))
+         .provide([
+           [matchers.call.fn(apiCall), mockData]
+         ])
+         .run();
+     });
+   });
+   ```
+
+## Debugging Strategies
+
+### Common Error Patterns
+
+1. **Matrix.js Connection Issues**
+   ```javascript
+   // Enable Matrix debugging
+   window.FEATURE_FLAGS.enableMatrixDebug = true;
+   
+   // Check Matrix client state
+   console.log(window.matrixClient?.getClientWellKnown());
+   console.log(window.matrixClient?.getSyncState());
+   ```
+
+2. **Redux State Issues**
+   ```javascript
+   // Debug Redux state
+   window.store.getState()
+   
+   // Watch specific state slice
+   window.store.subscribe(() => {
+     console.log('State changed:', window.store.getState().myFeature);
+   });
+   ```
+
+3. **Component Rendering Issues**
+   ```typescript
+   // Add debug logging
+   useEffect(() => {
+     console.log('Component props:', props);
+     console.log('Component state:', state);
+   });
+   ```
+
+### Using Source Maps
+
+1. **Vite Source Maps**
+   - Source maps are enabled by default in development
+   - Set breakpoints directly in TypeScript/JSX files
+   - Use browser DevTools to step through original source code
+
+2. **Redux DevTools Integration**
+   ```javascript
+   // Time travel debugging
+   // Use Redux DevTools extension to:
+   // - Inspect action history
+   // - Jump to any previous state
+   // - Export/import state for testing
+   ```
+
+### Saga Flow Debugging
+
+1. **Saga Logger**
+   ```typescript
+   // Add logging to sagas
+   function* mySaga(action) {
+     console.log('Saga started:', action);
+     try {
+       const result = yield call(apiCall);
+       console.log('API result:', result);
+       yield put(success(result));
+     } catch (error) {
+       console.error('Saga error:', error);
+       yield put(failure(error.message));
+     }
+   }
+   ```
+
+2. **Redux-Saga Test Plan**
+   ```typescript
+   // Test saga flows with detailed assertions
+   expectSaga(mySaga)
+     .put.actionType('START_REQUEST')
+     .call.fn(apiCall)
+     .put.actionType('REQUEST_SUCCESS')
+     .run();
+   ```
+
+### Performance Profiling
+
+1. **React DevTools Profiler**
+   - Install React DevTools extension
+   - Use Profiler tab to identify slow components
+   - Look for unnecessary re-renders
+
+2. **Vite Bundle Analysis**
+   ```bash
+   # Analyze bundle size
+   npm run build
+   npx vite-bundle-analyzer dist
+   ```
+
+## Testing Workflows
+
+### Writing Unit Tests
+
+1. **Vitest Configuration**
+   ```typescript
+   // vitest.config.ts is integrated in vite.config.ts
+   test: {
+     include: ['**/*.vitest.*'],
+     globals: true,
+     environment: 'jsdom',
+     setupFiles: ['./setupVitest.ts'],
+   }
+   ```
+
+2. **Component Testing Pattern**
+   ```typescript
+   // src/components/my-feature/index.vitest.tsx
+   import { screen, fireEvent, waitFor } from '@testing-library/react';
+   import { vi } from 'vitest';
+   import { renderWithProviders } from '../../test-utils';
+   import { MyFeature } from './index';
+   
+   describe('MyFeature', () => {
+     it('renders correctly', () => {
+       renderWithProviders(<MyFeature />);
+       expect(screen.getByText('Expected text')).toBeInTheDocument();
+     });
+     
+     it('handles user interaction', async () => {
+       const mockOnClick = vi.fn();
+       renderWithProviders(<MyFeature onClick={mockOnClick} />);
+       
+       fireEvent.click(screen.getByRole('button'));
+       await waitFor(() => {
+         expect(mockOnClick).toHaveBeenCalledOnce();
+       });
+     });
+   });
+   ```
+
+### Running Tests
+
+```bash
+# Run all Vitest tests
+npm run test:vitest
+
+# Run tests in watch mode
+vitest
+
+# Run specific test file
+vitest src/components/my-feature/index.vitest.tsx
+
+# Run tests with coverage
+vitest --coverage
+
+# Run tests matching pattern
+vitest --reporter=verbose --grep "MyFeature"
+```
+
+### Test Coverage Reports
+
+```bash
+# Generate coverage report
+vitest --coverage
+
+# View coverage in browser
+open coverage/index.html
+```
+
+### Debugging Failing Tests
+
+1. **Debug Mode**
+   ```bash
+   # Run single test with debugging
+   vitest --reporter=verbose --no-coverage src/path/to/test.vitest.tsx
+   ```
+
+2. **Test Debugging Tools**
+   ```typescript
+   // Add debug output
+   import { screen } from '@testing-library/react';
+   
+   // Debug DOM structure
+   screen.debug();
+   
+   // Check what's rendered
+   console.log(screen.getByRole('button'));
+   ```
+
+## Build & Deploy
+
+### Local Build Process
+
+```bash
+# Production build
+npm run build
+
+# Legacy build (if needed)
+npm run build:legacy
+
+# Electron builds
+npm run electron:package:mac
+npm run electron:package:win
+npm run electron:package:linux
+```
+
+### Environment Variables
+
+1. **Vite Environment Variables**
+   ```bash
+   # .env.local
+   REACT_APP_API_URL=http://localhost:8000
+   REACT_APP_MATRIX_SERVER=https://matrix.example.com
+   REACT_APP_SENTRY_DSN=your-sentry-dsn
+   ```
+
+2. **Feature Flag Override**
+   ```bash
+   # Override feature flags in development
+   REACT_APP_ENABLE_DEV_PANEL=true
+   REACT_APP_VERBOSE_LOGGING=true
+   ```
+
+### Build Optimization
+
+1. **Bundle Analysis**
+   ```bash
+   # Analyze bundle composition
+   npm run build
+   npx bundle-analyzer dist/static/js/*.js
+   ```
+
+2. **Performance Monitoring**
+   ```typescript
+   // Monitor build performance
+   console.time('Component render');
+   // Component code
+   console.timeEnd('Component render');
+   ```
+
+### Deployment Checklist
+
+- [ ] All tests passing
+- [ ] ESLint checks pass
+- [ ] Code formatted with Prettier
+- [ ] Feature flags properly configured
+- [ ] Environment variables set
+- [ ] Source maps generated
+- [ ] Bundle size within limits
+- [ ] Performance metrics acceptable
+
+## Productivity Tips
+
+### VS Code Setup for zOS
+
+1. **Recommended Extensions**
+   ```json
+   // .vscode/extensions.json
+   {
+     "recommendations": [
+       "esbenp.prettier-vscode",
+       "ms-vscode.vscode-typescript-next",
+       "bradlc.vscode-tailwindcss",
+       "ms-vscode.vscode-json",
+       "redhat.vscode-yaml",
+       "ms-vscode.test-adapter-converter"
+     ]
+   }
+   ```
+
+2. **VS Code Settings**
+   ```json
+   // .vscode/settings.json
+   {
+     "editor.formatOnSave": true,
+     "editor.defaultFormatter": "esbenp.prettier-vscode",
+     "typescript.preferences.importModuleSpecifier": "relative",
+     "emmet.includeLanguages": {
+       "typescript": "html",
+       "typescriptreact": "html"
+     }
+   }
+   ```
+
+### Keyboard Shortcuts
+
+```
+Ctrl+Shift+P - Command palette
+Ctrl+` - Toggle terminal
+Ctrl+Shift+` - New terminal
+Ctrl+B - Toggle sidebar
+Ctrl+Shift+E - Explorer
+Ctrl+Shift+F - Search across files
+Ctrl+Shift+G - Git panel
+Ctrl+Shift+D - Debug panel
+F5 - Start debugging
+Ctrl+F5 - Run without debugging
+Ctrl+Shift+I - Developer tools
+```
+
+### Code Snippets
+
+1. **React Component Snippet**
+   ```typescript
+   // Type: rfc
+   import React from 'react';
+   import { bemClassName } from '../../lib/bem';
+   
+   const cn = bemClassName('$1');
+   
+   export interface Properties {
+     // Props here
+   }
+   
+   export const $1: React.FC<Properties> = () => {
+     return (
+       <div {...cn('')}>
+         $0
+       </div>
+     );
+   };
+   ```
+
+2. **Redux Saga Snippet**
+   ```typescript
+   // Type: saga
+   function* $1Saga(action: PayloadAction<$2>) {
+     try {
+       yield put(start$1());
+       const result = yield call($3, action.payload);
+       yield put($1Success(result));
+     } catch (error) {
+       yield put($1Failure(error.message));
+     }
+   }
+   ```
+
+### Git Workflows
+
+1. **Branch Naming**
+   ```bash
+   # Feature branches
+   git checkout -b feature/add-user-profile
+   
+   # Bug fixes
+   git checkout -b fix/login-redirect-issue
+   
+   # Hotfix
+   git checkout -b hotfix/security-patch
+   ```
+
+2. **Commit Messages**
+   ```bash
+   # Good commit messages
+   git commit -m "feat: add user profile component"
+   git commit -m "fix: resolve login redirect issue"
+   git commit -m "refactor: simplify Redux store structure"
+   git commit -m "test: add unit tests for message component"
+   git commit -m "docs: update development workflow guide"
+   ```
+
+3. **Pre-commit Hooks**
+   ```bash
+   # Husky runs automatically:
+   # - Prettier formatting on staged files
+   # - ESLint validation
+   # - Pre-push code format validation
+   ```
+
+### PR Management
+
+1. **PR Template**
+   ```markdown
+   ## Summary
+   Brief description of changes
+   
+   ## Test Plan
+   - [ ] Unit tests added/updated
+   - [ ] Manual testing completed
+   - [ ] Integration tests pass
+   
+   ## Screenshots
+   (If UI changes)
+   
+   ## Breaking Changes
+   (If any)
+   ```
+
+2. **PR Checklist**
+   - [ ] Tests added for new functionality
+   - [ ] All tests passing
+   - [ ] Code reviewed by team
+   - [ ] Documentation updated
+   - [ ] Feature flags considered
+   - [ ] Performance impact assessed
+
+## Tool Configuration
+
+### Vite Configuration
+
+Key features in `vite.config.ts`:
+- React SWC for fast compilation
+- SVG as React components (`*.svg?react`)
+- Node.js polyfills for Matrix.js compatibility
+- SCSS preprocessing with `~` imports
+- Sentry integration for error tracking
+- Source maps for debugging
+
+### ESLint Rules
+
+Current configuration (`.eslintrc.json`):
+- Single quotes preferred
+- Unused variables as errors (with underscore prefix exception)
+- Import duplicate detection
+- React-Redux specific rules
+
+### Prettier Setup
+
+Configuration (`.prettierrc.json`):
+- Single quotes in JS/TS
+- JSX single quotes
+- Trailing commas (ES5)
+- 120 character line width
+- Multiline arrays formatting
+
+### Pre-commit Hooks
+
+Husky configuration:
+- **pre-commit**: Runs Prettier on staged files
+- **pre-push**: Validates code formatting
+
+## Troubleshooting Common Issues
+
+### Build Failures
+
+1. **Memory Issues**
+   ```bash
+   # Increase Node.js memory limit
+   NODE_OPTIONS='--max-old-space-size=6144' npm run build
+   ```
+
+2. **Type Errors**
+   ```bash
+   # Check TypeScript compilation
+   npx tsc --noEmit
+   ```
+
+### Runtime Errors
+
+1. **Matrix.js Issues**
+   ```javascript
+   // Check Matrix client status
+   window.matrixClient?.getClientWellKnown()
+   ```
+
+2. **Redux State Issues**
+   ```javascript
+   // Reset Redux state
+   window.location.reload()
+   ```
+
+### Development Server Issues
+
+1. **Port Conflicts**
+   ```bash
+   # Use different port
+   PORT=3001 npm start
+   ```
+
+2. **Module Resolution**
+   ```bash
+   # Clear cache and reinstall
+   rm -rf node_modules package-lock.json
+   npm install
+   ```
+
+This workflow guide should be your go-to reference for efficient zOS development. Keep it bookmarked and update it as new patterns emerge in the codebase.
\ No newline at end of file
diff --git a/opusdocs/new-recruits/documentation-index.md b/opusdocs/new-recruits/documentation-index.md
new file mode 100644
index 00000000..a3732588
--- /dev/null
+++ b/opusdocs/new-recruits/documentation-index.md
@@ -0,0 +1,104 @@
+# zOS Documentation Index
+
+Welcome to the comprehensive zOS documentation! This guide is organized to help you progress from understanding the architecture to contributing meaningful features.
+
+## 📚 Documentation Overview
+
+### 1. [Architecture Overview](../architecture-overview.md)
+Start here to understand how zOS works at a system level.
+- Redux-Saga-Normalizr pattern
+- Data flow architecture
+- Module organization
+- Key design decisions
+
+### 2. [Component Reference](../developer-reference/components.md)
+Complete guide to zOS's React components.
+- Avatar, Modal, Button components
+- ProfileCard, Tooltip, Lightbox
+- TypeScript interfaces and examples
+- Performance tips
+
+### 3. [Hooks Documentation](../developer-reference/hooks.md)
+Custom React hooks for common patterns.
+- Matrix media handling
+- Debouncing and optimization
+- Web3 wallet management
+- Practical usage examples
+
+### 4. [Contribution Guide](./contribution-guide.md)
+Your roadmap for contributing to zOS.
+- Progressive learning path
+- Code standards and conventions
+- PR process and review tips
+- From documentation fixes to features
+
+### 5. [Development Workflow](./development-workflow.md)
+Daily development practices and tools.
+- Environment setup
+- Debugging strategies
+- Testing approaches
+- Productivity tips
+
+### 6. [Matrix Integration Guide](../integration-guide.md)
+Deep dive into chat and real-time features.
+- Event handling patterns
+- Room management
+- Media and encryption
+- Custom features (MEOW reactions)
+
+### 7. [Blockchain Integration Guide](../blockchain-integration.md)
+Web3 functionality in zOS.
+- Wallet connections
+- Transaction handling
+- Smart contract interactions
+- Creator economy patterns
+
+## 🚀 Suggested Learning Path
+
+### Week 1: Foundation
+1. Read Architecture Overview
+2. Explore Component Reference
+3. Set up development environment (Development Workflow)
+
+### Week 2: Hands-On
+1. Make first contribution (Contribution Guide)
+2. Learn custom hooks (Hooks Documentation)
+3. Debug your first issue (Development Workflow)
+
+### Week 3: Integration
+1. Understand Matrix chat (Matrix Integration)
+2. Explore Web3 features (Blockchain Integration)
+3. Build a small feature
+
+### Week 4: Advanced
+1. Implement a complete feature
+2. Help review others' PRs
+3. Contribute to documentation
+
+## 💡 Tips for Success
+
+1. **Start Small**: Begin with documentation fixes to understand the workflow
+2. **Use the Tools**: Redux DevTools and Chrome DevTools are your friends
+3. **Ask Questions**: The community values learning and growth
+4. **Test Everything**: Follow the testing patterns in the guides
+5. **Think Integration**: Consider how features work with Matrix and Web3
+
+## 🔗 Quick Links
+
+- [CLAUDE.md](../../CLAUDE.md) - AI assistant guidance
+- [README.md](../../README.md) - Project overview
+- [package.json](../../package.json) - Available scripts
+
+## 🎯 For Haven Protocol Development
+
+As you learn zOS, pay special attention to:
+- ExternalApp integration patterns
+- Matrix room customization
+- Web3 creator economy features
+- Component composition patterns
+
+These will be valuable when building the creator platform!
+
+---
+
+*Documentation created with care for developers ready to contribute to the future of decentralized applications.*
\ No newline at end of file
diff --git a/opusdocs/new-recruits/gato-project/scripts/install.sh b/opusdocs/new-recruits/gato-project/scripts/install.sh
new file mode 100755
index 00000000..a00683d5
--- /dev/null
+++ b/opusdocs/new-recruits/gato-project/scripts/install.sh
@@ -0,0 +1,133 @@
+#!/bin/bash
+# Gato Installation Script
+# Installs the cat-themed Git wrapper
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+PURPLE='\033[0;35m'
+NC='\033[0m' # No Color
+
+# Cat ASCII art for installer
+CAT_INSTALLER='
+     /\_/\  
+    ( ^.^ ) 
+     > ^ <  
+   Installing...
+'
+
+echo -e "${PURPLE}${CAT_INSTALLER}${NC}"
+echo -e "${BLUE}🐱 Welcome to Gato Installation! 🐱${NC}"
+echo -e "${YELLOW}Preparing to install your new cat-themed Git wrapper...${NC}"
+
+# Check if Python 3 is installed
+if ! command -v python3 &> /dev/null; then
+    echo -e "${RED}❌ Python 3 is required but not installed.${NC}"
+    echo -e "${YELLOW}Please install Python 3 and try again.${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}✅ Python 3 found!${NC}"
+
+# Get the script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+GATO_SCRIPT="$PROJECT_DIR/src/gato.py"
+
+# Check if gato.py exists
+if [ ! -f "$GATO_SCRIPT" ]; then
+    echo -e "${RED}❌ Gato script not found at: $GATO_SCRIPT${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}✅ Gato script found!${NC}"
+
+# Create ~/.local/bin if it doesn't exist
+LOCAL_BIN="$HOME/.local/bin"
+mkdir -p "$LOCAL_BIN"
+
+# Copy gato script to local bin
+echo -e "${YELLOW}📦 Installing Gato to $LOCAL_BIN...${NC}"
+cp "$GATO_SCRIPT" "$LOCAL_BIN/gato"
+chmod +x "$LOCAL_BIN/gato"
+
+# Check if ~/.local/bin is in PATH
+if [[ ":$PATH:" != *":$LOCAL_BIN:"* ]]; then
+    echo -e "${YELLOW}⚠️  $LOCAL_BIN is not in your PATH${NC}"
+    echo -e "${BLUE}Adding to your shell configuration...${NC}"
+    
+    # Determine which shell config file to use
+    if [ -n "$ZSH_VERSION" ]; then
+        SHELL_CONFIG="$HOME/.zshrc"
+    elif [ -n "$BASH_VERSION" ]; then
+        if [ -f "$HOME/.bashrc" ]; then
+            SHELL_CONFIG="$HOME/.bashrc"
+        else
+            SHELL_CONFIG="$HOME/.bash_profile"
+        fi
+    else
+        SHELL_CONFIG="$HOME/.profile"
+    fi
+    
+    # Add to PATH if not already there
+    if ! grep -q "export PATH.*$LOCAL_BIN" "$SHELL_CONFIG" 2>/dev/null; then
+        echo "" >> "$SHELL_CONFIG"
+        echo "# Added by Gato installer" >> "$SHELL_CONFIG"
+        echo "export PATH=\"\$HOME/.local/bin:\$PATH\"" >> "$SHELL_CONFIG"
+        echo -e "${GREEN}✅ Added $LOCAL_BIN to PATH in $SHELL_CONFIG${NC}"
+    fi
+fi
+
+# Create desktop shortcut (optional)
+if command -v xdg-user-dir &> /dev/null && [ -d "$(xdg-user-dir DESKTOP 2>/dev/null)" ]; then
+    DESKTOP_DIR="$(xdg-user-dir DESKTOP)"
+    DESKTOP_FILE="$DESKTOP_DIR/Gato.desktop"
+    
+    echo -e "${YELLOW}🖥️  Creating desktop shortcut...${NC}"
+    cat > "$DESKTOP_FILE" << EOF
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=Gato
+Comment=Cat-themed Git wrapper with MEOW tokens
+Exec=x-terminal-emulator -e gato help
+Icon=applications-games
+Terminal=true
+Categories=Development;
+EOF
+    chmod +x "$DESKTOP_FILE"
+    echo -e "${GREEN}✅ Desktop shortcut created!${NC}"
+fi
+
+# Test installation
+echo -e "${YELLOW}🧪 Testing installation...${NC}"
+if "$LOCAL_BIN/gato" help &>/dev/null; then
+    echo -e "${GREEN}✅ Installation successful!${NC}"
+else
+    echo -e "${RED}❌ Installation test failed${NC}"
+    exit 1
+fi
+
+# Success message with cat art
+SUCCESS_CAT='
+     /\_/\  
+    ( ^o^ ) 
+     > ^ <  
+   SUCCESS!
+'
+
+echo -e "${GREEN}${SUCCESS_CAT}${NC}"
+echo -e "${BLUE}🎉 Gato has been successfully installed! 🎉${NC}"
+echo -e "${YELLOW}Start using it with:${NC}"
+echo -e "${PURPLE}  gato help           ${NC}# Show help"
+echo -e "${PURPLE}  gato spawn          ${NC}# Initialize a repo"
+echo -e "${PURPLE}  gato hunt .         ${NC}# Add files"
+echo -e "${PURPLE}  gato pounce -m \"meow\"${NC}# Commit changes"
+echo -e "${PURPLE}  gato meow-status    ${NC}# Check MEOW tokens"
+echo ""
+echo -e "${BLUE}🐱 May your commits be purr-fect! 🐱${NC}"
+echo -e "${YELLOW}💡 Tip: You may need to restart your terminal or run 'source ~/.bashrc' (or ~/.zshrc) to use gato immediately.${NC}"
\ No newline at end of file
diff --git a/opusdocs/new-recruits/gato-project/scripts/uninstall.sh b/opusdocs/new-recruits/gato-project/scripts/uninstall.sh
new file mode 100755
index 00000000..74375d3a
--- /dev/null
+++ b/opusdocs/new-recruits/gato-project/scripts/uninstall.sh
@@ -0,0 +1,67 @@
+#!/bin/bash
+# Gato Uninstallation Script
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+PURPLE='\033[0;35m'
+NC='\033[0m' # No Color
+
+# Sad cat ASCII art
+SAD_CAT='
+     /\_/\  
+    ( ;_; ) 
+     > ^ <  
+   Goodbye...
+'
+
+echo -e "${PURPLE}${SAD_CAT}${NC}"
+echo -e "${BLUE}🐱 Gato Uninstallation 🐱${NC}"
+echo -e "${YELLOW}Are you sure you want to remove Gato? (y/N):${NC}"
+
+read -r response
+if [[ ! "$response" =~ ^[Yy]$ ]]; then
+    echo -e "${GREEN}🐱 Phew! Gato stays! Meow! 🐱${NC}"
+    exit 0
+fi
+
+LOCAL_BIN="$HOME/.local/bin"
+GATO_BIN="$LOCAL_BIN/gato"
+CONFIG_DIR="$HOME/.gato"
+
+# Remove executable
+if [ -f "$GATO_BIN" ]; then
+    rm "$GATO_BIN"
+    echo -e "${GREEN}✅ Removed Gato executable${NC}"
+else
+    echo -e "${YELLOW}⚠️  Gato executable not found${NC}"
+fi
+
+# Ask about config/MEOW tokens
+if [ -d "$CONFIG_DIR" ]; then
+    echo -e "${YELLOW}Do you want to remove your MEOW tokens and config? (y/N):${NC}"
+    read -r config_response
+    if [[ "$config_response" =~ ^[Yy]$ ]]; then
+        rm -rf "$CONFIG_DIR"
+        echo -e "${GREEN}✅ Removed MEOW tokens and config${NC}"
+    else
+        echo -e "${BLUE}💰 Keeping your precious MEOW tokens safe!${NC}"
+    fi
+fi
+
+# Remove desktop shortcut if it exists
+if command -v xdg-user-dir &> /dev/null && [ -d "$(xdg-user-dir DESKTOP 2>/dev/null)" ]; then
+    DESKTOP_DIR="$(xdg-user-dir DESKTOP)"
+    DESKTOP_FILE="$DESKTOP_DIR/Gato.desktop"
+    if [ -f "$DESKTOP_FILE" ]; then
+        rm "$DESKTOP_FILE"
+        echo -e "${GREEN}✅ Removed desktop shortcut${NC}"
+    fi
+fi
+
+echo -e "${BLUE}🐱 Gato has been uninstalled. Thanks for all the fish... er, MEOW tokens! 🐱${NC}"
+echo -e "${YELLOW}💡 Note: PATH modifications in shell config files were left unchanged.${NC}"
\ No newline at end of file
diff --git a/opusdocs/new-recruits/gato-project/src/gato.py b/opusdocs/new-recruits/gato-project/src/gato.py
new file mode 100644
index 00000000..25e171d0
--- /dev/null
+++ b/opusdocs/new-recruits/gato-project/src/gato.py
@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""
+Gato - A cat-themed Git wrapper with MEOW token integration
+Because every developer needs more cats in their workflow!
+"""
+
+import os
+import sys
+import subprocess
+import json
+import random
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+class GatoASCII:
+    """Collection of cat ASCII art for different commands"""
+    
+    CAT_SITTING = """
+     /\\_/\\  
+    ( o.o ) 
+     > ^ <  
+    """
+    
+    CAT_HUNTING = """
+    /\\   /\\
+   (  . .)
+    )   (
+   (  v  )
+    ^^-^^
+    """
+    
+    CAT_POUNCING = """
+      /\\_/\\
+     ( >_< )
+    _)     (_
+   (  \\_V_/  )
+    \\__\\_/__/
+    """
+    
+    CAT_LEAPING = """
+        /\\_/\\
+       ( ^.^ )
+      _)     (_
+     (   \\_/   )
+      \\__/|\\__/
+         / \\
+    """
+    
+    CAT_SLEEPING = """
+     /\\_/\\  
+    ( -.- ) 
+     > ^ <  
+    zzZ..
+    """
+    
+    CAT_GROOMING = """
+     /\\_/\\
+    ( o_O )
+     > \\/ <
+    """
+    
+    CAT_PROWLING = """
+       /\\_/\\
+      ( o.o )
+       > ^ <
+    ___) (___ 
+    """
+
+class MEOWToken:
+    """MEOW token tracking system"""
+    
+    def __init__(self):
+        self.config_dir = Path.home() / '.gato'
+        self.config_dir.mkdir(exist_ok=True)
+        self.token_file = self.config_dir / 'meow_tokens.json'
+        self.load_tokens()
+    
+    def load_tokens(self):
+        """Load MEOW token data from file"""
+        if self.token_file.exists():
+            with open(self.token_file, 'r') as f:
+                self.data = json.load(f)
+        else:
+            self.data = {
+                'total_meow': 0,
+                'pounces': 0,
+                'purr_requests': 0,
+                'sniff_checks': 0,
+                'daily_streak': 0,
+                'last_active': None,
+                'achievements': []
+            }
+        self.save_tokens()
+    
+    def save_tokens(self):
+        """Save MEOW token data to file"""
+        with open(self.token_file, 'w') as f:
+            json.dump(self.data, f, indent=2)
+    
+    def award_meow(self, action: str, amount: int):
+        """Award MEOW tokens for actions"""
+        self.data['total_meow'] += amount
+        
+        # Track specific actions
+        if action == 'pounce':
+            self.data['pounces'] += 1
+        elif action == 'purr_request':
+            self.data['purr_requests'] += 1
+        elif action == 'sniff_check':
+            self.data['sniff_checks'] += 1
+        
+        # Update daily streak
+        today = datetime.now().strftime('%Y-%m-%d')
+        if self.data['last_active'] != today:
+            if self.data['last_active'] == (datetime.now().replace(day=datetime.now().day-1)).strftime('%Y-%m-%d'):
+                self.data['daily_streak'] += 1
+            else:
+                self.data['daily_streak'] = 1
+            self.data['last_active'] = today
+        
+        self.check_achievements()
+        self.save_tokens()
+        return amount
+    
+    def check_achievements(self):
+        """Check and award achievements"""
+        achievements = []
+        
+        if self.data['pounces'] >= 1 and 'first_pounce' not in self.data['achievements']:
+            achievements.append('first_pounce')
+            self.data['total_meow'] += 50
+        
+        if self.data['pounces'] >= 100 and 'century_pouncer' not in self.data['achievements']:
+            achievements.append('century_pouncer')
+            self.data['total_meow'] += 500
+        
+        if self.data['daily_streak'] >= 7 and 'week_warrior' not in self.data['achievements']:
+            achievements.append('week_warrior')
+            self.data['total_meow'] += 200
+        
+        if self.data['purr_requests'] >= 10 and 'purr_master' not in self.data['achievements']:
+            achievements.append('purr_master')
+            self.data['total_meow'] += 300
+        
+        self.data['achievements'].extend(achievements)
+        return achievements
+    
+    def get_status(self) -> str:
+        """Get current MEOW token status"""
+        return f"""
+🐱 MEOW Token Status 🐱
+Total MEOW: {self.data['total_meow']}
+Pounces: {self.data['pounces']} (+10 MEOW each)
+Purr Requests: {self.data['purr_requests']} (+100 MEOW each)
+Sniff Checks: {self.data['sniff_checks']} (+25 MEOW each)
+Daily Streak: {self.data['daily_streak']} days
+Achievements: {len(self.data['achievements'])}
+        """
+
+class Gato:
+    """Main Gato class - Git wrapper with cat personality"""
+    
+    def __init__(self):
+        self.meow_token = MEOWToken()
+        self.ascii_art = GatoASCII()
+        
+        # Command mapping: gato_command -> (git_command, ascii_art, meow_reward, sound)
+        self.command_map = {
+            'spawn': ('init', self.ascii_art.CAT_SITTING, 20, 'mrow'),
+            'hunt': ('add', self.ascii_art.CAT_HUNTING, 5, 'meow'),
+            'pounce': ('commit', self.ascii_art.CAT_POUNCING, 10, 'POUNCE!'),
+            'leap': ('push', self.ascii_art.CAT_LEAPING, 15, 'whoosh'),
+            'fetch': ('pull', self.ascii_art.CAT_SITTING, 10, 'purr'),
+            'kitten': ('clone', self.ascii_art.CAT_SITTING, 25, 'mew mew'),
+            'scratch': ('branch', self.ascii_art.CAT_HUNTING, 8, 'scratch scratch'),
+            'cuddle': ('merge', self.ascii_art.CAT_SLEEPING, 20, 'purrrrr'),
+            'hide': ('stash', self.ascii_art.CAT_SLEEPING, 5, 'shh'),
+            'meowmory': ('log', self.ascii_art.CAT_SITTING, 2, 'meow?'),
+            'groom': ('rebase', self.ascii_art.CAT_GROOMING, 15, 'lick lick'),
+            'prowl': ('checkout', self.ascii_art.CAT_PROWLING, 8, 'prowl prowl'),
+        }
+        
+        # Cat sounds for different situations
+        self.success_sounds = ['purr', 'meow', 'mrow', 'chirp', 'trill']
+        self.error_sounds = ['hiss', 'yowl', 'screech', 'growl']
+    
+    def print_cat_header(self, command: str):
+        """Print cat-themed header for commands"""
+        if command in self.command_map:
+            ascii_art, _, _, sound = self.command_map[command][1:]
+            print(f"\n{ascii_art}")
+            print(f"🐱 Gato says: {sound}!")
+            print(f"📝 Running: gato {command}")
+            print("-" * 40)
+    
+    def execute_git_command(self, gato_command: str, args: List[str]) -> Tuple[bool, str]:
+        """Execute the corresponding git command"""
+        if gato_command not in self.command_map:
+            return False, f"Unknown gato command: {gato_command}"
+        
+        git_command = self.command_map[gato_command][0]
+        cmd = ['git', git_command] + args
+        
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True)
+            return result.returncode == 0, result.stdout + result.stderr
+        except Exception as e:
+            return False, str(e)
+    
+    def award_meow_tokens(self, command: str, success: bool):
+        """Award MEOW tokens based on command and success"""
+        if not success:
+            return 0
+        
+        if command not in self.command_map:
+            return 0
+        
+        reward = self.command_map[command][2]
+        
+        # Determine action type for tracking
+        action = 'pounce' if command == 'pounce' else 'general'
+        
+        awarded = self.meow_token.award_meow(action, reward)
+        return awarded
+    
+    def print_success_message(self, command: str, awarded_meow: int):
+        """Print success message with cat sounds"""
+        sound = random.choice(self.success_sounds)
+        print(f"\n🎉 Success! {sound.upper()}!")
+        if awarded_meow > 0:
+            print(f"💰 Earned {awarded_meow} MEOW tokens!")
+        
+        # Check for new achievements
+        achievements = self.meow_token.check_achievements()
+        if achievements:
+            for achievement in achievements:
+                print(f"🏆 New Achievement: {achievement.replace('_', ' ').title()}!")
+    
+    def print_error_message(self, error: str):
+        """Print error message with cat sounds"""
+        sound = random.choice(self.error_sounds)
+        print(f"\n❌ Oops! {sound.upper()}!")
+        print(f"Error: {error}")
+        print("🐱 This cat needs some help...")
+    
+    def show_help(self):
+        """Show Gato help menu"""
+        print("""
+🐱 GATO - Git with Attitude, Tokens, and Outstanding cat-ness! 🐱
+
+Cat-themed Git Commands:
+  gato spawn      → git init       (Start a new litter)
+  gato hunt       → git add        (Hunt for changes)
+  gato pounce     → git commit     (Pounce on those changes!)
+  gato leap       → git push       (Leap to the remote)
+  gato fetch      → git pull       (Fetch the latest)
+  gato kitten     → git clone      (Adopt a new kitten)
+  gato scratch    → git branch     (Scratch a new branch)
+  gato cuddle     → git merge      (Cuddle branches together)
+  gato hide       → git stash      (Hide your mess)
+  gato meowmory   → git log        (Remember the past)
+  gato groom      → git rebase     (Groom your commits)
+  gato prowl      → git checkout   (Prowl to another branch)
+
+Special Gato Commands:
+  gato meow-status  → Show MEOW token balance
+  gato purr-request → Create a pull request (coming soon!)
+  gato help         → This help menu
+
+MEOW Token Rewards:
+  🐾 Pounces (commits): +10 MEOW
+  🏆 Approved Purr Requests: +100 MEOW  
+  👃 Sniff Checks (reviews): +25 MEOW
+  🌟 Daily streak bonuses and achievements!
+
+Examples:
+  gato spawn                    # Initialize a new repo
+  gato hunt .                   # Add all files
+  gato pounce -m "First hunt!"  # Commit with message
+  gato leap                     # Push to remote
+  
+May your commits be clean and your MEOW tokens plenty! 🐱✨
+        """)
+    
+    def show_meow_status(self):
+        """Show MEOW token status"""
+        print(self.meow_token.get_status())
+    
+    def run(self, args: List[str]):
+        """Main entry point for Gato"""
+        if not args:
+            self.show_help()
+            return
+        
+        command = args[0]
+        command_args = args[1:]
+        
+        # Special Gato commands
+        if command == 'help':
+            self.show_help()
+            return
+        elif command == 'meow-status':
+            self.show_meow_status()
+            return
+        elif command == 'purr-request':
+            print("🚧 Purr Requests coming soon! Stay tuned, fellow cat! 🐱")
+            return
+        
+        # Standard git commands through Gato
+        if command in self.command_map:
+            self.print_cat_header(command)
+            success, output = self.execute_git_command(command, command_args)
+            
+            if success:
+                print(output)
+                awarded_meow = self.award_meow_tokens(command, success)
+                self.print_success_message(command, awarded_meow)
+            else:
+                self.print_error_message(output)
+        else:
+            print(f"🙀 Unknown command: {command}")
+            print("Try 'gato help' for available commands!")
+
+def main():
+    """Main entry point"""
+    gato = Gato()
+    gato.run(sys.argv[1:])
+
+if __name__ == '__main__':
+    main()
\ No newline at end of file