docs: add comprehensive developer guides and architecture documentation

.gitignore

@@ -18,6 +18,8 @@
 .env.local
 .env.development.local
 .env.test.local
+
+# Private agent infrastructure
 .env.production.local
 
 npm-debug.log*
@@ -28,4 +30,4 @@ yarn-error.log*
 .vscode/*
 /.idea
 
-.husky/_
+.husky/_

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

agents-only/coordination/active-tasks.md

@@ -0,0 +1,48 @@
+# Active Tasks
+
+## Task Queue
+
+### Priority 1: Foundation
+- [ ] Architecture Overview (architecture-guide-agent)
+  - Status: Not started
+  - Output: `./opusdocs/architecture-overview.md`
+  - Dependencies: None
+
+### Priority 2: Reference
+- [ ] Component Documentation (developer-reference-agent)
+  - Status: Not started
+  - Output: `./opusdocs/developer-reference/components.md`
+  - Dependencies: Architecture Overview
+
+- [ ] Hooks Documentation (developer-reference-agent)
+  - Status: Not started
+  - Output: `./opusdocs/developer-reference/hooks.md`
+  - Dependencies: Architecture Overview
+
+### Priority 3: Onboarding
+- [ ] Contribution Guide for New Developers (contribution-guide-agent)
+  - Status: Not started
+  - Output: `./opusdocs/new-recruits/contribution-guide.md`
+  - Dependencies: Architecture Overview
+
+- [ ] Development Workflow (development-workflow-agent)
+  - Status: Not started
+  - Output: `./opusdocs/new-recruits/development-workflow.md`
+  - Dependencies: None
+
+### Priority 4: Integrations
+- [ ] Matrix Integration Guide (integration-expert-agent)
+  - Status: Not started
+  - Output: `./opusdocs/integration-guide.md`
+  - Dependencies: Architecture Overview
+
+- [ ] Blockchain Integration Guide (integration-expert-agent)
+  - Status: Not started
+  - Output: `./opusdocs/blockchain-integration.md`
+  - Dependencies: Architecture Overview
+
+## Assignment Protocol
+1. Agent checks this file for unassigned tasks
+2. Updates status to "In Progress - [Agent Name]"
+3. Moves to `progress/in-progress.md` with details
+4. Updates `progress/completed.md` when done

agents-only/coordination/progress.md

@@ -0,0 +1,62 @@
+# Documentation Progress Update
+
+## Completed Documentation
+
+### ✅ Architecture Overview
+- Location: `./opusdocs/architecture-overview.md`
+- Status: Complete
+- Key Achievement: Clear mental model of Redux-Saga-Normalizr pattern
+
+### ✅ Component Reference
+- Location: `./opusdocs/developer-reference/components.md`
+- Status: Complete
+- Components Documented: Avatar, Modal, Button, ProfileCard, Tooltip, Lightbox, HoverCard, LoadingScreen, ErrorBoundary
+
+### ✅ Hooks Documentation
+- Location: `./opusdocs/developer-reference/hooks.md`
+- Status: Complete
+- Hooks Documented: useMatrixMedia, useMatrixImage, useDebounce, useLinkPreview, useScrollPosition, usePrevious, useUserWallets, useOwnedZids
+
+### ✅ Contribution Guide
+- Location: `./opusdocs/new-recruits/contribution-guide.md`
+- Status: Complete
+- Features: Progressive learning path, real examples, encouraging tone
+
+### ✅ Development Workflow
+- Location: `./opusdocs/new-recruits/development-workflow.md`
+- Status: Complete
+- Features: Daily workflows, debugging strategies, productivity tips
+
+### ✅ Matrix Integration Guide
+- Location: `./opusdocs/integration-guide.md`
+- Status: Complete
+- Features: Event handling, room management, security patterns
+
+### 🔄 Blockchain Integration Guide
+- Status: In Progress
+- Next: Document Web3 integration patterns
+
+## Strategic Insights for Haven Protocol
+
+### Matrix Integration Discoveries
+- Custom event types enable creator-specific features
+- Room metadata can store gallery/collection information
+- MEOW reaction system could be adapted for artist appreciation
+- Media handling supports high-quality artwork sharing
+
+### Component Patterns
+- Avatar system adaptable for artist profiles
+- Modal system perfect for artwork detail views
+- Lightbox component ideal for gallery viewing
+- ProfileCard extensible for creator profiles
+
+### Hook Opportunities
+- useMatrixMedia handles encrypted NFT previews
+- useLinkPreview for artist portfolio links
+- useUserWallets for multi-wallet creator support
+- Custom hooks pattern for Haven-specific features
+
+## Next Steps
+1. Complete Blockchain Integration Guide
+2. Create summary document linking all guides
+3. Identify any gaps for Haven Protocol needs