docs: consolidate and archive documentation

- Move 30+ outdated docs to docs/_archive/
- Move obsolete root files to _archive/
- Update README.md (Better Auth, current features)
- Update docs/README.md (new architecture diagram)
- Update docs/quick-reference.md (consolidated)
- Update docs/project-status.md (March 2026 state)
- Update docs/nao6-quick-reference.md (14 actions, Docker services)
- Update docs/implementation-guide.md (Better Auth, git submodule)
- Update docs/proposal.tex (timeline updates)
- Archive errors.txt, plugin_dump.json, test HTML files

docs/_archive/MARCH-2026-SESSION.md

@@ -0,0 +1,159 @@
+# HRIStudio - March 2026 Development Summary
+
+## What We Did This Session
+
+### 1. Docker Integration for NAO6 Robot
+**Files**: `nao6-hristudio-integration/`
+
+- Created `Dockerfile` with ROS2 Humble + naoqi packages
+- Created `docker-compose.yaml` with 3 services: `nao_driver`, `ros_bridge`, `ros_api`
+- Created `scripts/init_robot.sh` - Bash script to wake up robot via SSH when Docker starts
+- Fixed autonomous life disable issue (previously used Python `naoqi` package which isn't on PyPI)
+
+**Key insight**: Robot init via SSH + `qicli` calls instead of Python SDK
+
+### 2. Plugin System Fixes
+**Files**: `robot-plugins/plugins/nao6-ros2.json`, `src/lib/ros/wizard-ros-service.ts`
+
+- **Topic fixes**: Removed `/naoqi_driver/` prefix from topics (driver already provides unprefixed topics)
+- **say_with_emotion**: Fixed with proper NAOqi markup (`\rspd=120\^start(animations/...)`)
+- **wave_goodbye**: Added animated speech with waving gesture
+- **play_animation**: Added for predefined NAO animations
+- **Sensor topics**: Fixed camera, IMU, bumper, sonar, touch topics (removed prefix)
+
+### 3. Database Schema - Plugin Identifier
+**Files**: `src/server/db/schema.ts`, `src/server/services/trial-execution.ts`
+
+- Added `identifier` column to `plugins` table (unique, machine-readable ID like `nao6-ros2`)
+- `name` now for display only ("NAO6 Robot (ROS2 Integration)")
+- Updated trial-execution to look up by `identifier` first, then `name` (backwards compat)
+- Created migration script: `scripts/migrate-add-identifier.ts`
+
+### 4. Seed Script Improvements
+**Files**: `scripts/seed-dev.ts`
+
+- Fixed to use local plugin file (not remote `repo.hristudio.com`)
+- Added `identifier` field for all plugins (nao6, hristudio-core, hristudio-woz)
+- Experiment structure:
+  - Step 1: The Hook
+  - Step 2: The Narrative
+  - Step 3: Comprehension Check (conditional with wizard choices)
+  - Step 4a/4b: Branch A/B (with `nextStepId` conditions to converge)
+  - Step 5: Story Continues (convergence point)
+  - Step 6: Conclusion
+
+### 5. Robot Action Timing Fix
+**Files**: `src/lib/ros/wizard-ros-service.ts`
+
+- Speech actions now estimate duration: `1500ms emotion overhead + word_count * 300ms`
+- Added `say_with_emotion` and `wave_goodbye` as explicit built-in actions
+- Fixed 100ms timeout that was completing actions before robot finished
+
+### 6. Branching Logic Fixes (Critical!)
+**Files**: `src/components/trials/wizard/`
+
+**Bug 1**: `onClick={onNextStep}` passed event object instead of calling function
+- Fixed: `onClick={() => onNextStep()}`
+
+**Bug 2**: `onCompleted()` called after branch choice incremented action count
+- Fixed: Removed `onCompleted()` call after branch selection
+
+**Bug 3**: Branch A/B had no `nextStepId` condition, fell through to linear progression
+- Fixed: Added `conditions.nextStepId: step5.id` to Branch A and B
+
+**Bug 4**: Robot actions from previous step executed on new step (branching jumped but actions from prior step still triggered)
+- Root cause: `completedActionsCount` not being reset properly
+- Fixed: `handleNextStep()` now resets `completedActionsCount(0)` on explicit jump
+
+### 7. Auth.js to Better Auth Migration (Attempted, Reverted)
+**Status**: Incomplete - 41+ type errors remain
+
+The migration requires significant changes to how `session.user.roles` is accessed since Better Auth doesn't include roles in session by default. Would need to fetch roles from database on each request.
+
+**Recommendation**: Defer until more development time available.
+
+---
+
+## Current Architecture
+
+### Plugin Identifier System
+```
+plugins table:
+  - id: UUID (primary key)
+  - identifier: varchar (unique, e.g. "nao6-ros2")
+  - name: varchar (display, e.g. "NAO6 Robot (ROS2 Integration)")
+  - robotId: UUID (optional FK to robots)
+  - actionDefinitions: JSONB
+
+actions table:
+  - type: "plugin.action" (e.g., "nao6-ros2.say_with_emotion")
+  - pluginId: varchar (references plugins.identifier)
+```
+
+### Branching Flow
+```
+Step 3 (Comprehension Check)
+  └── wizard_wait_for_response action
+      ├── Click "Correct" → setLastResponse("Correct") → nextStepId=step4a.id
+      └── Click "Incorrect" → setLastResponse("Incorrect") → nextStepId=step4b.id
+
+Step 4a/4b (Branches)
+  └── conditions.nextStepId: step5.id → jump to Story Continues
+
+Step 5 (Story Continues)
+  └── Linear progression to Step 6
+
+Step 6 (Conclusion)
+  └── Trial complete
+```
+
+### ROS Topics (NAO6)
+```
+/speech          - Text-to-speech
+/cmd_vel         - Velocity commands
+/joint_angles    - Joint position commands
+/camera/front/image_raw
+/camera/bottom/image_raw
+/imu/torso
+/bumper
+/{hand,head}_touch
+/sonar/{left,right}
+/info
+```
+
+---
+
+## Known Issues / Remaining Work
+
+1. **Auth.js to Better Auth Migration** - Deferred, requires significant refactoring
+2. **robots.executeSystemAction** - Procedure not found error (fallback works but should investigate)
+3. **say_with_emotion via WebSocket** - May need proper plugin config to avoid fallback
+
+---
+
+## Docker Deployment
+
+```bash
+cd nao6-hristudio-integration
+docker compose up -d
+```
+
+Robot init runs automatically on startup (via `init_robot.sh`).
+
+---
+
+## Testing Checklist
+
+- [x] Docker builds and starts
+- [x] Robot wakes up (autonomous life disabled)
+- [x] Seed script runs successfully
+- [x] Trial executes with proper branching
+- [x] Branch A → Story Continues (not Branch B)
+- [x] Robot speaks with emotion (say_with_emotion)
+- [x] Wave gesture works
+- [ ] Robot movement (walk, turn) tested
+- [ ] All NAO6 actions verified
+
+---
+
+*Last Updated: March 21, 2026*

docs/_archive/block-designer-implementation.md

@@ -0,0 +1,481 @@
+# Block Designer Implementation Tracking
+
+## Project Status: COMPLETED ✅
+
+**Implementation Date**: December 2024  
+**Total Development Time**: ~8 hours  
+**Final Status**: Production ready with database integration
+
+## ✨ Key Improvements Implemented
+
+### 1. **Fixed Save Functionality** ✅
+- **API Integration**: Added `visualDesign` field to experiments.update API route
+- **Database Storage**: Visual designs are saved as JSONB to PostgreSQL with GIN indexes
+- **Real-time Feedback**: Loading states, success/error toasts, unsaved changes indicators
+- **Auto-recovery**: Loads existing designs from database on page load
+
+### 2. **Proper Drag & Drop from Palette** ✅
+- **From Palette**: Drag blocks directly from the palette to the canvas
+- **To Canvas**: Drop blocks on main canvas or into control structures
+- **Visual Feedback**: Clear drop zones, hover states, and drag overlays
+- **Touch Support**: Works on tablets and touch devices
+
+### 3. **Clean, Professional UI** ✅
+- **No Double Borders**: Fixed border conflicts between panels and containers
+- **Consistent Spacing**: Proper padding, margins, and visual hierarchy
+- **Modern Design**: Clean color scheme, proper shadows, and hover effects
+- **Responsive Layout**: Three-panel resizable interface with proper constraints
+
+### 4. **Enhanced User Experience** ✅
+- **Better Block Shapes**: Distinct visual shapes (hat, action, control) for different block types
+- **Parameter Previews**: Live preview of block parameters in both palette and canvas
+- **Intuitive Selection**: Click to select, visual selection indicators
+- **Smart Nesting**: Easy drag-and-drop into control structures with clear drop zones
+
+## What Was Built
+
+### Core Interface
+- **Three-panel layout**: Block Library | Experiment Flow | Properties
+- **Dense, structured design** replacing freeform canvas approach
+- **Resizable panels** with proper responsive behavior
+- **Dashboard integration** with existing breadcrumb system
+
+### Block System
+- **Six block categories** with distinct visual design:
+  - Events (Green/Play) - Trial triggers
+  - Wizard (Purple/Users) - Human actions  
+  - Robot (Blue/Bot) - Automated actions
+  - Control (Orange/GitBranch) - Flow control
+  - Sensors (Green/Activity) - Data collection
+- **Shape-based functionality**:
+  - Action blocks: Standard rounded rectangles
+  - Control blocks: C-shaped with nesting areas
+  - Hat blocks: Event triggers with distinctive tops
+- **Parameter system** with type-safe inputs and live preview
+
+### Advanced Features
+- **dnd-kit integration** for reliable cross-platform drag and drop
+- **Block nesting** for control structures (repeat, if statements)
+- **Visual hierarchy** with indentation and connecting lines
+- **Real-time parameter editing** in dedicated properties panel
+- **Block removal** from nested structures
+- **Parameter preview** in block library drawer
+
+### Database Integration
+- **Enhanced schema** with new JSONB columns:
+  - `visual_design`: Complete block layout and parameters
+  - `execution_graph`: Compiled execution sequence  
+  - `plugin_dependencies`: Required robot platform plugins
+- **GIN indexes** on JSONB for fast query performance
+- **Plugin registry** tables for extensible block types
+
+## 🏗️ Technical Architecture
+
+### Core Components
+
+1. **EnhancedBlockDesigner** - Main container component
+2. **BlockPalette** - Left panel with draggable block categories
+3. **SortableBlock** - Individual block component with drag/sort capabilities
+4. **DroppableContainer** - Drop zones for control structures
+5. **DraggablePaletteBlock** - Draggable blocks in the palette
+
+### Block Registry System
+
+```typescript
+class BlockRegistry {
+  private blocks = new Map<string, PluginBlockDefinition>();
+  
+  // Core blocks: Events, Wizard Actions, Robot Actions, Control Flow, Sensors
+  // Extensible plugin architecture for additional robot platforms
+}
+```
+
+### Data Flow
+
+```
+1. Palette Block Drag → 2. Canvas Drop → 3. Block Creation → 4. State Update → 5. Database Save
+     ↓                      ↓                ↓                  ↓                 ↓
+ DraggablePaletteBlock → DroppableContainer → BlockRegistry → React State → tRPC API
+```
+
+## 🎨 Block Categories & Types
+
+### Events (Green - Play Icon)
+- **when trial starts** - Hat-shaped trigger block
+
+### Wizard Actions (Purple - Users Icon)  
+- **say** - Wizard speaks to participant
+- **gesture** - Wizard performs physical gesture
+
+### Robot Actions (Blue - Bot Icon)
+- **say** - Robot speaks using TTS
+- **move** - Robot moves in direction/distance
+- **look at** - Robot orients gaze to target
+
+### Control Flow (Orange - GitBranch Icon)
+- **wait** - Pause execution for time
+- **repeat** - Loop container with nesting
+- **if** - Conditional container with nesting
+
+### Sensors (Green - Activity Icon)
+- **observe** - Record behavioral observations
+
+## Technical Implementation
+
+### Drag & Drop System
+- **Library**: @dnd-kit/core with sortable and utilities
+- **Collision Detection**: closestCenter for optimal drop targeting
+- **Sensors**: Pointer (mouse/touch) + Keyboard for accessibility
+- **Drop Zones**: Main canvas, control block interiors, reordering
+
+### State Management
+```typescript
+interface BlockDesign {
+  id: string;
+  name: string;
+  description: string;
+  blocks: ExperimentBlock[];
+  version: number;
+  lastSaved: Date;
+}
+```
+
+### Database Schema
+```sql
+-- experiments table
+visualDesign JSONB,           -- Complete block design
+executionGraph JSONB,         -- Compiled execution plan  
+pluginDependencies TEXT[],    -- Required robot plugins
+
+-- GIN index for fast JSONB queries
+CREATE INDEX experiment_visual_design_idx ON experiments USING GIN (visual_design);
+```
+
+### API Integration
+```typescript
+// tRPC route: experiments.update
+updateExperiment.mutate({
+  id: experimentId,
+  visualDesign: {
+    blocks: design.blocks,
+    version: design.version,
+    lastSaved: new Date().toISOString(),
+  }
+});
+```
+
+### Architecture Decisions
+1. **Abandoned freeform canvas** in favor of structured vertical list
+2. **Used dnd-kit instead of native drag/drop** for reliability
+3. **Integrated with existing dashboard patterns** rather than custom UI
+4. **JSONB storage** for flexible schema evolution
+5. **Plugin-based block registry** for robot platform extensibility
+
+### Key Components
+- `EnhancedBlockDesigner.tsx` - Main interface (1,200+ lines)
+- `BlockRegistry` class - Manages available block types
+- Database schema extensions for visual design storage
+- Breadcrumb integration with existing dashboard system
+
+### Performance Optimizations
+- **Efficient rendering** with minimal re-renders
+- **Direct DOM manipulation** during drag operations
+- **Lazy loading** of block libraries
+- **Optimized state management** with React hooks
+
+## Challenges Solved
+
+### 1. Layout Conflicts
+- **Problem**: Full-screen designer conflicting with dashboard layout
+- **Solution**: Integrated within dashboard container with proper height management
+
+### 2. Drag and Drop Reliability
+- **Problem**: Native HTML drag/drop was buggy and inconsistent
+- **Solution**: Switched to dnd-kit for cross-platform reliability
+
+### 3. Control Flow Nesting
+- **Problem**: Complex logic for nested block structures
+- **Solution**: Droppable containers with visual feedback and proper data management
+
+### 4. Breadcrumb Integration
+- **Problem**: Custom breadcrumb conflicting with dashboard system
+- **Solution**: Used existing `useBreadcrumbsEffect` hook for proper integration
+
+### 5. Parameter Management
+- **Problem**: Complex parameter editing workflows
+- **Solution**: Dedicated properties panel with type-safe form controls
+
+## Code Quality Improvements
+
+### Removed Deprecated Files
+- `BlockDesigner.tsx` - Old implementation
+- `ExperimentDesigner.tsx` - Card-based approach
+- `ExperimentDesignerClient.tsx` - Wrapper component
+- `FlowDesigner.tsx` - React Flow attempt
+- `FreeFormDesigner.tsx` - Canvas approach
+- `flow-theme.css` - React Flow styling
+
+### Documentation Cleanup
+- Removed outdated step-by-step documentation
+- Removed planning documents that are now implemented
+- Consolidated into single comprehensive guide
+- Added implementation tracking (this document)
+
+### Code Standards
+- **100% TypeScript** with strict type checking
+- **Emoji-free interface** using only lucide icons
+- **Consistent naming** following project conventions
+- **Proper error handling** with user-friendly messages
+- **Accessibility support** with keyboard navigation
+
+## Database Schema Changes
+
+### New Tables
+```sql
+-- Robot plugin registry
+CREATE TABLE hs_robot_plugin (
+  id UUID PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  version VARCHAR(50) NOT NULL,
+  -- ... plugin metadata
+);
+
+-- Block type registry  
+CREATE TABLE hs_block_registry (
+  id UUID PRIMARY KEY,
+  block_type VARCHAR(100) NOT NULL,
+  plugin_id UUID REFERENCES hs_robot_plugin(id),
+  shape block_shape_enum NOT NULL,
+  category block_category_enum NOT NULL,
+  -- ... block definition
+);
+```
+
+### Enhanced Experiments Table
+```sql
+ALTER TABLE hs_experiment ADD COLUMN visual_design JSONB;
+ALTER TABLE hs_experiment ADD COLUMN execution_graph JSONB;
+ALTER TABLE hs_experiment ADD COLUMN plugin_dependencies TEXT[];
+
+CREATE INDEX experiment_visual_design_idx ON hs_experiment 
+USING gin (visual_design);
+```
+
+### New Enums
+```sql
+CREATE TYPE block_shape_enum AS ENUM (
+  'action', 'control', 'value', 'boolean', 'hat', 'cap'
+);
+
+CREATE TYPE block_category_enum AS ENUM (
+  'wizard', 'robot', 'control', 'sensor', 'logic', 'event'
+);
+```
+
+## User Experience Achievements
+
+### Workflow Improvements
+- **Reduced complexity**: No more confusing freeform canvas
+- **Clear hierarchy**: Linear top-to-bottom execution order
+- **Intuitive nesting**: Visual drop zones for control structures
+- **Fast iteration**: Quick block addition and configuration
+- **Professional feel**: Clean, dense interface design
+
+### Accessibility Features
+- **Keyboard navigation** through all interface elements
+- **Screen reader support** with proper ARIA labels
+- **Touch-friendly** sizing for tablet interfaces
+- **High contrast** color schemes for visibility
+- **Clear visual hierarchy** with consistent typography
+
+## Future Enhancement Opportunities
+
+### Short Term
+- **Inline parameter editing** in block drawer
+- **Block templates** with pre-configured parameters
+- **Export/import** of block designs
+- **Undo/redo** functionality
+
+### Medium Term
+- **Real-time collaboration** for multi-researcher editing
+- **Execution visualization** showing current block during trials
+- **Error handling blocks** for robust trial management
+- **Variable blocks** for data manipulation
+
+### Long Term
+- **Machine learning integration** for adaptive experiments
+- **Multi-robot coordination** blocks
+- **Advanced sensor integration** 
+- **Template library** with community sharing
+
+## Lessons Learned
+
+### Design Principles
+1. **Structure over flexibility**: Linear flow is better than freeform for most users
+2. **Integration over isolation**: Work with existing patterns, not against them
+3. **Progressive enhancement**: Start simple, add complexity gradually
+4. **User feedback**: Visual feedback is crucial for drag operations
+5. **Performance matters**: Smooth interactions are essential for user adoption
+
+### Technical Insights
+1. **dnd-kit is superior** to native HTML drag and drop for complex interfaces
+2. **JSONB storage** provides excellent flexibility for evolving schemas
+3. **Type safety** prevents many runtime errors in complex interfaces
+4. **Proper state management** is critical for responsive UI updates
+5. **Database indexing** is essential for JSONB query performance
+
+## Success Metrics
+
+### Quantitative
+- **0 known bugs** in current implementation
+- **<100ms response time** for most user interactions
+- **50+ blocks** supported efficiently in single experiment
+- **3 panel layout** with smooth resizing performance
+- **6 block categories** with 12+ block types implemented
+
+### Qualitative
+- **Intuitive workflow** - Users can create experiments without training
+- **Professional appearance** - Interface feels polished and complete
+- **Reliable interactions** - Drag and drop works consistently
+- **Clear hierarchy** - Experiment flow is easy to understand
+- **Extensible architecture** - Ready for robot platform plugins
+
+## Deployment Status
+
+### Production Ready
+- ✅ **Database migrations** applied successfully
+- ✅ **Code integration** complete with no conflicts
+- ✅ **Documentation** comprehensive and current
+- ✅ **Error handling** robust with user-friendly messages
+- ✅ **Performance** optimized for production workloads
+
+### Access
+- **Route**: `/experiments/[id]/designer`
+- **Permissions**: Requires experiment edit access
+- **Dependencies**: PostgreSQL with JSONB support
+- **Browser support**: Modern browsers with drag/drop APIs
+
+## 🚀 Usage Instructions
+
+### Basic Workflow
+1. **Open Designer**: Navigate to Experiments → [Experiment Name] → Designer
+2. **Add Blocks**: Drag blocks from left palette to main canvas
+3. **Configure**: Click blocks to edit parameters in right panel
+4. **Nest Blocks**: Drag blocks into control structures (repeat, if)
+5. **Save**: Click Save button or Cmd/Ctrl+S
+
+### Advanced Features
+- **Reorder Blocks**: Drag blocks up/down in the sequence
+- **Remove from Control**: Delete nested blocks or drag them out
+- **Parameter Types**: Text inputs, number inputs, select dropdowns
+- **Visual Feedback**: Hover states, selection rings, drag overlays
+
+### Keyboard Shortcuts
+- `Delete` - Remove selected block
+- `Escape` - Deselect all blocks  
+- `↑/↓` - Navigate block selection
+- `Enter` - Edit selected block parameters
+- `Cmd/Ctrl+S` - Save design
+
+## 🎯 Testing the Implementation
+
+### Manual Testing Checklist
+- [ ] Drag blocks from palette to canvas
+- [ ] Drag blocks into repeat/if control structures
+- [ ] Reorder blocks by dragging
+- [ ] Select blocks and edit parameters
+- [ ] Save design (check for success toast)
+- [ ] Reload page (design should persist)
+- [ ] Test touch/tablet interactions
+
+### Browser Compatibility
+- ✅ Chrome/Chromium 90+
+- ✅ Firefox 88+  
+- ✅ Safari 14+
+- ✅ Edge 90+
+- ✅ Mobile Safari (iOS 14+)
+- ✅ Chrome Mobile (Android 10+)
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Blocks won't drag from palette:**
+- Ensure you're dragging from the block area (not just the icon)
+- Check browser drag/drop API support
+- Try refreshing the page
+
+**Save not working:**
+- Check network connection
+- Verify user has edit permissions for experiment
+- Check browser console for API errors
+
+**Drag state gets stuck:**
+- Press Escape to reset drag state
+- Refresh page if issues persist
+- Check for JavaScript errors in console
+
+**Parameters not updating:**
+- Ensure block is selected (blue ring around block)
+- Click outside input fields to trigger save
+- Check for validation errors
+
+### Performance Tips
+- Keep experiments under 50 blocks for optimal performance
+- Use control blocks to organize complex sequences
+- Close unused browser tabs to free memory
+- Clear browser cache if experiencing issues
+
+## 🔮 Future Enhancements
+
+### Planned Features
+- **Inline Parameter Editing**: Edit parameters directly on blocks
+- **Block Templates**: Save and reuse common block sequences  
+- **Visual Branching**: Better visualization of conditional logic
+- **Collaboration**: Real-time collaborative editing
+- **Version History**: Track and restore design versions
+
+### Plugin Extensibility
+```typescript
+// Robot platform plugins can register new blocks
+registry.registerBlock({
+  type: "ur5_move_joint",
+  category: "robot",
+  displayName: "move joint",
+  description: "Move UR5 robot joint to position",
+  icon: "Bot",
+  color: "#3b82f6",
+  parameters: [
+    { id: "joint", name: "Joint", type: "select", options: ["shoulder", "elbow", "wrist"] },
+    { id: "angle", name: "Angle (deg)", type: "number", min: -180, max: 180 }
+  ]
+});
+```
+
+## 📊 Performance Metrics
+
+### Rendering Performance
+- **Initial Load**: <100ms for 20 blocks
+- **Drag Operations**: 60fps smooth animations
+- **Save Operations**: <500ms for typical designs
+- **Memory Usage**: <50MB for complex experiments
+
+### Bundle Size Impact
+- **@dnd-kit/core**: +45KB (gzipped: +12KB)
+- **Component Code**: +25KB (gzipped: +8KB)
+- **Total Addition**: +70KB (gzipped: +20KB)
+
+## 🏆 Success Criteria - All Met ✅
+
+- ✅ **Drag & Drop Works**: Palette to canvas, reordering, nesting
+- ✅ **Save Functionality**: Persistent storage with API integration
+- ✅ **Clean UI**: No double borders, professional appearance
+- ✅ **Parameter Editing**: Full configuration support
+- ✅ **Performance**: Smooth for typical experiment sizes
+- ✅ **Accessibility**: Keyboard navigation and screen reader support
+- ✅ **Mobile Support**: Touch-friendly interactions
+- ✅ **Type Safety**: TypeScript with strict mode
+
+---
+
+**Implementation completed**: Production-ready block designer successfully replacing all previous experimental interfaces. Ready for researcher adoption and robot platform plugin development.

docs/_archive/block-designer.md

@@ -0,0 +1,384 @@
+# HRIStudio Block Designer
+
+## Overview
+
+The HRIStudio Block Designer is a visual programming interface for creating experiment protocols in Human-Robot Interaction research. It provides an intuitive, drag-and-drop environment where researchers can design complex experimental workflows without programming knowledge.
+
+**Status**: Production ready - Fully implemented with database integration
+
+## Features
+
+### **Dense, Structured Interface**
+- **Three-panel layout**: Block Library | Experiment Flow | Properties
+- **Linear block sequencing** with clear top-to-bottom execution order
+- **Resizable panels** to fit different workflow preferences
+- **Compact, efficient design** maximizing information density
+
+### **Visual Block System**
+- **Color-coded categories** for easy identification
+- **Shape-based functionality** indicating block behavior
+- **Parameter preview** showing current values inline
+- **Execution state indicators** during trial playback
+
+### **Advanced Drag & Drop**
+- **Powered by dnd-kit** for reliable, cross-platform operation
+- **Reorder blocks** by dragging in the main sequence
+- **Nest blocks** by dropping into control structures
+- **Visual feedback** with drop zones and hover states
+- **Touch support** for tablet and mobile devices
+
+### **Control Flow & Nesting**
+- **Control blocks** can contain other blocks for complex logic
+- **Visual hierarchy** with indentation and connecting lines
+- **Easy removal** from nested structures
+- **Drop zones** clearly indicate where blocks can be placed
+
+## Block Categories
+
+### **Events** (Green - Play icon)
+Entry points that trigger experiment sequences.
+
+#### `when trial starts`
+- **Shape**: Hat (distinctive top curve)
+- **Purpose**: Marks the beginning of experiment execution
+- **Parameters**: None
+- **Usage**: Every experiment should start with an event block
+
+### **Wizard Actions** (Purple - Users icon)
+Human-operated actions performed by the experiment wizard.
+
+#### `say`
+- **Shape**: Rounded rectangle
+- **Purpose**: Wizard speaks to participant
+- **Parameters**: 
+  - `message` (text): What the wizard should say
+- **Example**: "Please take a seat and get comfortable"
+
+#### `gesture`
+- **Shape**: Rounded rectangle  
+- **Purpose**: Wizard performs physical gesture
+- **Parameters**:
+  - `type` (select): wave, point, nod, thumbs_up
+- **Example**: Wave to greet participant
+
+### **Robot Actions** (Blue - Bot icon)
+Automated behaviors performed by the robot system.
+
+#### `say`
+- **Shape**: Rounded rectangle
+- **Purpose**: Robot speaks using text-to-speech
+- **Parameters**:
+  - `text` (text): Message for robot to speak
+- **Example**: "Hello, I'm ready to help you today"
+
+#### `move`
+- **Shape**: Rounded rectangle
+- **Purpose**: Robot moves in specified direction
+- **Parameters**:
+  - `direction` (select): forward, backward, left, right
+  - `distance` (number): Distance in meters (0.1-5.0)
+- **Example**: Move forward 1.5 meters
+
+#### `look at`
+- **Shape**: Rounded rectangle
+- **Purpose**: Robot orients gaze toward target
+- **Parameters**:
+  - `target` (select): participant, object, door
+- **Example**: Look at participant during conversation
+
+### **Control Flow** (Orange - GitBranch icon)
+Logic and timing blocks that control experiment flow.
+
+#### `wait`
+- **Shape**: Rounded rectangle
+- **Purpose**: Pause execution for specified time
+- **Parameters**:
+  - `seconds` (number): Duration to wait (0.1-60)
+- **Example**: Wait 3 seconds between actions
+
+#### `repeat`
+- **Shape**: Control block (C-shaped with nesting area)
+- **Purpose**: Execute contained blocks multiple times
+- **Parameters**:
+  - `times` (number): Number of repetitions (1-20)
+- **Nesting**: Can contain other blocks
+- **Example**: Repeat greeting sequence 3 times
+
+#### `if`
+- **Shape**: Control block (C-shaped with nesting area)
+- **Purpose**: Conditional execution based on conditions
+- **Parameters**:
+  - `condition` (select): participant speaks, object detected, timer expired
+- **Nesting**: Can contain other blocks
+- **Example**: If participant speaks, respond with acknowledgment
+
+### **Sensors** (Green - Activity icon)
+Data collection and observation tools.
+
+#### `observe`
+- **Shape**: Rounded rectangle
+- **Purpose**: Record behavioral observations
+- **Parameters**:
+  - `what` (text): Description of what to observe
+  - `duration` (number): Observation time in seconds (1-60)
+- **Example**: Observe participant engagement for 10 seconds
+
+## User Interface
+
+### **Block Library Panel (Left)**
+- **Category tabs**: Click to switch between block categories
+- **Block cards**: Click to add blocks to experiment
+- **Visual previews**: Icons and descriptions for each block type
+- **Smooth animations**: Hover effects and visual feedback
+
+### **Experiment Flow Panel (Middle)**
+- **Linear sequence**: Blocks arranged vertically in execution order
+- **Drag handles**: Grip icons for reordering blocks
+- **Selection states**: Click blocks to select for editing
+- **Nesting support**: Control blocks show contained blocks indented
+- **Drop zones**: Dashed areas for dropping blocks into control structures
+
+### **Properties Panel (Right)**
+- **Block details**: Name, description, and icon
+- **Parameter editing**: Form controls for block configuration
+- **Live updates**: Changes reflected immediately in block preview
+- **Type-appropriate inputs**: Text fields, numbers, dropdowns as needed
+
+## Workflow Examples
+
+### **Simple Linear Sequence**
+```
+1. [when trial starts]
+2. [robot say] "Welcome to our study"
+3. [wait] 2 seconds
+4. [wizard say] "Please introduce yourself"
+5. [observe] "participant response" for 10 seconds
+```
+
+### **Repeated Actions**
+```
+1. [when trial starts]
+2. [robot say] "I'll demonstrate this movement 3 times"
+3. [repeat] 3 times
+   ├─ [robot move] forward 0.5 meters
+   ├─ [wait] 1 second
+   ├─ [robot move] backward 0.5 meters
+   └─ [wait] 1 second
+4. [wizard say] "Now you try it"
+```
+
+### **Conditional Logic**
+```
+1. [when trial starts]
+2. [robot say] "Do you have any questions?"
+3. [if] participant speaks
+   ├─ [robot say] "Let me address that"
+   ├─ [wait] 3 seconds
+   └─ [wizard say] "Please elaborate if needed"
+4. [robot say] "Let's begin the main task"
+```
+
+### **Complex Multi-Modal Interaction**
+```
+1. [when trial starts]
+2. [robot look at] participant
+3. [robot say] "Hello! I'm going to help you today"
+4. [wizard gesture] wave
+5. [repeat] 5 times
+   ├─ [robot move] forward 0.3 meters
+   ├─ [if] object detected
+   │  ├─ [robot say] "I see something interesting"
+   │  ├─ [robot look at] object
+   │  └─ [observe] "participant attention" for 5 seconds
+   └─ [wait] 2 seconds
+6. [wizard say] "Great job! That completes our session"
+```
+
+## Technical Implementation
+
+### **Data Structure**
+```typescript
+interface ExperimentBlock {
+  id: string;                    // Unique identifier
+  type: string;                  // Block type (e.g., 'robot_speak')
+  category: BlockCategory;       // Visual category
+  shape: BlockShape;             // Visual shape
+  displayName: string;           // User-friendly name
+  description: string;           // Help text
+  icon: string;                  // Lucide icon name
+  color: string;                 // Category color
+  parameters: BlockParameter[]; // Configurable values
+  children?: ExperimentBlock[];  // Nested blocks (for control)
+  nestable?: boolean;           // Can contain children
+  order: number;                // Sequence position
+}
+```
+
+### **Plugin Architecture**
+The block system supports extensible plugins for different robot platforms:
+
+```typescript
+interface PluginBlockDefinition {
+  type: string;                  // Unique block identifier
+  shape: BlockShape;             // Visual representation
+  category: BlockCategory;       // Palette category
+  displayName: string;           // User-visible name
+  description: string;           // Help description
+  icon: string;                  // Icon identifier
+  color: string;                 // Category color
+  parameters: ParameterSchema[]; // Configuration schema
+  nestable?: boolean;           // Supports nesting
+}
+```
+
+### **Execution Integration**
+Visual blocks compile to executable trial sequences:
+
+1. **Design Phase**: Visual blocks stored as JSON in database
+2. **Compilation**: Blocks converted to execution graph
+3. **Runtime**: Trial executor processes blocks sequentially
+4. **Monitoring**: Real-time status updates back to visual blocks
+
+## Best Practices
+
+### **For Simple Experiments**
+- Start with a clear event trigger (`when trial starts`)
+- Use linear sequences for straightforward protocols
+- Add timing blocks (`wait`) for natural pacing
+- Include observation blocks for data collection
+- Keep nesting minimal for clarity
+
+### **For Complex Experiments**
+- Group related actions in control blocks (`repeat`, `if`)
+- Use descriptive parameter values
+- Test conditional logic thoroughly before trials
+- Document unusual configurations in experiment notes
+- Break complex flows into smaller, testable segments
+
+### **For Team Collaboration**
+- Use consistent naming conventions across experiments
+- Export and share protocol designs
+- Review block sequences visually before implementation
+- Maintain version history of experimental protocols
+- Train team members on block meanings and usage
+
+### **Parameter Configuration**
+- Use clear, descriptive text for speech blocks
+- Set appropriate timing for wait blocks (not too fast/slow)
+- Choose realistic movement distances for robot actions
+- Configure observation durations based on expected behaviors
+- Test parameter values in pilot sessions
+
+### **Parameters in Block Drawer**
+Parameter names are currently shown as badges in the block library for preview:
+- **Parameter badges**: Shows first 2 parameter names under each block
+- **Overflow indicator**: Shows "+X more" for blocks with many parameters  
+- **Visual preview**: Helps identify block configuration needs
+- **Future enhancement**: Could support inline editing for rapid prototyping
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Delete` | Remove selected block |
+| `Escape` | Deselect all blocks |
+| `↑/↓ Arrow` | Navigate block selection |
+| `Enter` | Edit selected block parameters |
+| `Ctrl/Cmd + S` | Save experiment design |
+| `Ctrl/Cmd + Z` | Undo last action |
+
+## Accessibility Features
+
+- **Keyboard navigation** through all interface elements
+- **Screen reader support** with proper ARIA labels
+- **High contrast** color schemes for visibility
+- **Touch-friendly** sizing for tablet interfaces
+- **Clear visual hierarchy** with consistent typography
+
+## Database Integration
+
+### **Storage Schema**
+Experiment designs are stored in the `experiments` table:
+- `visual_design` (JSONB): Complete block layout and configuration
+- `execution_graph` (JSONB): Compiled execution sequence
+- `plugin_dependencies` (TEXT[]): Required robot platform plugins
+
+### **Performance Optimization**
+- **GIN indexes** on JSONB columns for fast queries
+- **Lazy loading** of large block libraries
+- **Efficient rendering** with React virtualization
+- **Minimal re-renders** using optimized state management
+
+## Implementation Status
+
+### **Completed Features**
+- **Dense three-panel interface** with resizable panels
+- **Six block categories** with color coding and icons
+- **dnd-kit powered drag and drop** with nesting support
+- **Control flow blocks** (repeat, if) with visual hierarchy
+- **Parameter editing** in dedicated properties panel
+- **Database integration** with JSONB storage
+- **Breadcrumb navigation** using dashboard system
+- **Plugin architecture** ready for robot platform extensions
+
+### **Technical Implementation**
+- **Database**: PostgreSQL with JSONB columns for visual designs
+- **Frontend**: React with TypeScript, dnd-kit, shadcn/ui
+- **State management**: React hooks with optimistic updates
+- **Performance**: Efficient rendering for experiments up to 50+ blocks
+
+## Troubleshooting
+
+### **Common Issues**
+
+**Blocks won't drag:**
+- Ensure you're dragging from the grip handle (not the block body)
+- Check that browser supports modern drag and drop APIs
+- Try refreshing the page if drag state gets stuck
+
+**Parameters not saving:**
+- Click outside parameter fields to trigger save
+- Check network connection for auto-save functionality
+- Verify you have edit permissions for the experiment
+
+**Control blocks not nesting:**
+- Drag blocks specifically onto the dashed drop zone
+- Ensure control blocks are expanded (not collapsed)
+- Check that target block supports nesting
+
+**Missing blocks in palette:**
+- Verify required robot plugins are installed and active
+- Check that you have access to the block category
+- Refresh page to reload block registry
+
+### **Breadcrumb Navigation** 
+The block designer integrates with the existing dashboard breadcrumb system:
+- **Path**: Dashboard → Experiments → [Experiment Name] → Designer
+- **Header integration**: Breadcrumbs appear in dashboard header (not duplicated)
+- **Context preservation**: Maintains navigation state during design sessions
+- **Automatic cleanup**: Breadcrumbs reset when leaving designer
+
+### **Performance Tips**
+- Keep experiments under 50 blocks for optimal performance
+- Use control blocks to organize complex sequences
+- Regularly save work to prevent data loss
+- Close unused browser tabs to free memory
+
+## Development Notes
+
+### **File Locations**
+- **Main component**: `src/components/experiments/designer/EnhancedBlockDesigner.tsx`
+- **Page route**: `src/app/(dashboard)/experiments/[id]/designer/page.tsx`
+- **Database schema**: Enhanced experiments table with `visual_design` JSONB column
+- **Documentation**: `docs/block-designer.md` (this file)
+
+### **Key Dependencies**
+- **@dnd-kit/core**: Drag and drop functionality
+- **@dnd-kit/sortable**: Block reordering and nesting
+- **lucide-react**: All icons throughout interface
+- **shadcn/ui**: UI components and theming
+- **PostgreSQL**: JSONB storage for block designs
+
+---
+
+*The HRIStudio Block Designer makes complex experimental protocols accessible to researchers regardless of programming background, while maintaining the flexibility needed for cutting-edge HRI research.*

docs/_archive/cleanup-summary.md

@@ -0,0 +1,145 @@
+# HRIStudio Cleanup Summary
+
+## Overview
+
+Successfully cleaned up the HRIStudio codebase and documentation following the implementation of the core blocks system. This cleanup addressed file organization, documentation structure, and removed unused artifacts.
+
+## Files Removed
+
+### Unused Development Files
+- `hristudio-core/` - Removed duplicate development repository (kept public serving copy)
+- `CORE_BLOCKS_IMPLEMENTATION.md` - Moved to proper location in docs/
+- `test-designer-api.js` - Removed obsolete test file
+- `lint_output.txt` - Removed temporary lint output
+
+### Total Files Removed: 4 + 1 directory
+
+## Files Moved/Reorganized
+
+### Documentation Consolidation
+- `CORE_BLOCKS_IMPLEMENTATION.md` → `docs/core-blocks-system.md`
+- Integrated core blocks documentation with existing docs structure
+- Updated cross-references throughout documentation
+
+## Repository Structure Simplified
+
+### Before Cleanup
+```
+hristudio/
+├── hristudio-core/              # Duplicate development copy
+├── public/hristudio-core/       # Serving copy
+├── CORE_BLOCKS_IMPLEMENTATION.md # Root-level documentation
+├── test-designer-api.js         # Obsolete test
+└── lint_output.txt              # Temporary file
+```
+
+### After Cleanup
+```
+hristudio/
+├── public/hristudio-core/       # Single serving copy
+├── docs/core-blocks-system.md   # Properly organized documentation
+└── scripts/test-core-blocks.ts  # Proper test location
+```
+
+## Documentation Updates
+
+### Updated Files
+1. **`.rules`** - Added comprehensive documentation guidelines
+2. **`docs/README.md`** - Updated with core blocks system in documentation index
+3. **`docs/quick-reference.md`** - Added core blocks system quick reference
+4. **`docs/project-overview.md`** - Integrated core blocks architecture
+5. **`docs/implementation-details.md`** - Added core blocks technical details
+6. **`docs/project-status.md`** - Updated completion status and dates
+7. **`docs/work_in_progress.md`** - Added cross-references to new documentation
+8. **`docs/core-blocks-system.md`** - Complete implementation guide with proper integration
+
+### Documentation Guidelines Added
+- Location standards (docs/ folder only)
+- Cross-referencing requirements
+- Update procedures for existing files
+- Format consistency standards
+- Plugin system documentation standards
+
+## Code Quality Improvements
+
+### Seed Scripts Fixed
+- `scripts/seed-core-blocks.ts` - Fixed imports and TypeScript errors
+- `scripts/seed-plugins.ts` - Removed unused imports, fixed operators
+- `scripts/seed.ts` - Fixed delete operation warnings
+
+### TypeScript Compliance
+- All unsafe `any` types resolved in BlockDesigner
+- Proper type definitions for plugin interfaces
+- Nullish coalescing operators used consistently
+- No compilation errors in main codebase
+
+## Core Blocks System Status
+
+### Repository Architecture
+- **Single Source**: `public/hristudio-core/` serves as authoritative source
+- **26 Blocks**: Across 4 categories (events, wizard, control, observation)
+- **Type Safe**: Full TypeScript integration with proper error handling
+- **Tested**: Comprehensive validation with test script
+- **Documented**: Complete integration with existing documentation
+
+### Plugin Architecture Benefits
+- **Consistency**: Unified approach for core blocks and robot plugins
+- **Extensibility**: JSON-based block definitions, no code changes needed
+- **Maintainability**: Centralized definitions with validation
+- **Version Control**: Independent updates for core functionality
+
+## Quality Assurance
+
+### Tests Passing
+```bash
+# Core blocks loading test
+✅ All tests passed! Core blocks system is working correctly.
+   • 26 blocks loaded from repository
+   • All required core blocks present
+   • Registry loading simulation successful
+```
+
+### Build Status
+```bash
+# TypeScript compilation
+✅ Build successful (0.77 MB bundle)
+✅ No compilation errors
+✅ Type safety maintained
+```
+
+### Documentation Integrity
+- ✅ All cross-references updated
+- ✅ Consistent formatting applied
+- ✅ Integration with existing structure
+- ✅ Guidelines established for future updates
+
+## Benefits Achieved
+
+### Improved Organization
+- Single source of truth for core blocks repository
+- Proper documentation hierarchy following established patterns
+- Eliminated redundant files and temporary artifacts
+- Clear separation between development and serving content
+
+### Enhanced Maintainability
+- Documentation guidelines prevent future organizational issues
+- Consistent structure makes updates easier
+- Cross-references ensure documentation stays synchronized
+- Plugin architecture allows independent updates
+
+### Better Developer Experience
+- Cleaner repository structure
+- Comprehensive documentation index
+- Clear guidelines for contributions
+- Proper integration of new features with existing docs
+
+## Production Readiness
+
+### Status: Complete ✅
+- **Architecture**: Repository-based core blocks system fully implemented
+- **Documentation**: Comprehensive and properly organized
+- **Quality**: All tests passing, no build errors
+- **Integration**: Seamless with existing platform components
+- **Maintenance**: Clear guidelines and structure established
+
+The HRIStudio codebase is now clean, well-organized, and ready for production deployment with a robust plugin architecture that maintains consistency across all platform components.

docs/_archive/core-blocks-system.md

@@ -0,0 +1,233 @@
+# HRIStudio Core Blocks System
+
+## Overview
+
+The core blocks system provides essential building blocks for the visual experiment designer through a repository-based plugin architecture. This system ensures consistency, extensibility, and maintainability by treating all blocks (core functionality and robot actions) as plugins loaded from repositories.
+
+**Quick Links:**
+- [Plugin System Implementation Guide](plugin-system-implementation-guide.md)
+- [Work in Progress](work_in_progress.md#core-block-system-implementation-february-2024)
+- [Project Overview](project-overview.md#2-visual-experiment-designer-ede)
+
+## ✅ **Implementation Complete**
+
+### **1. Core Repository Structure**
+
+Created `hristudio-core/` repository with complete plugin architecture:
+
+```
+hristudio-core/
+├── repository.json           # Repository metadata
+├── plugins/
+│   ├── index.json           # Plugin index (26 total blocks)
+│   ├── events.json          # Event trigger blocks (4 blocks)
+│   ├── wizard-actions.json  # Wizard action blocks (6 blocks)
+│   ├── control-flow.json    # Control flow blocks (8 blocks)
+│   └── observation.json     # Observation blocks (8 blocks)
+├── assets/                  # Repository assets
+└── README.md               # Complete documentation
+```
+
+### **2. Block Categories Implemented**
+
+#### **Event Triggers (4 blocks)**
+- `when_trial_starts` - Trial initialization trigger
+- `when_participant_speaks` - Speech detection with duration threshold
+- `when_timer_expires` - Time-based triggers with custom delays
+- `when_key_pressed` - Wizard keyboard shortcuts
+
+#### **Wizard Actions (6 blocks)**
+- `wizard_say` - Speech with tone guidance
+- `wizard_gesture` - Physical gestures with directions
+- `wizard_show_object` - Object presentation with action types
+- `wizard_record_note` - Observation recording with categorization
+- `wizard_wait_for_response` - Response waiting with timeout
+- `wizard_rate_interaction` - Subjective rating scales
+
+#### **Control Flow (8 blocks)**
+- `wait` - Pause execution with optional countdown
+- `repeat` - Loop execution with delay between iterations
+- `if_condition` - Conditional logic with multiple condition types
+- `parallel` - Simultaneous execution with timeout controls
+- `sequence` - Sequential execution with error handling
+- `random_choice` - Weighted random path selection
+- `try_catch` - Error handling with retry mechanisms
+- `break` - Exit controls for loops/sequences/trials
+
+#### **Observation & Sensing (8 blocks)**
+- `observe_behavior` - Behavioral coding with standardized scales
+- `measure_response_time` - Stimulus-response timing measurement
+- `count_events` - Event frequency tracking
+- `record_audio` - Audio capture with quality settings
+- `capture_video` - Multi-camera video recording
+- `log_event` - Timestamped event logging
+- `survey_question` - In-trial questionnaires
+- `physiological_measure` - Sensor data collection
+
+### **3. Technical Architecture Changes**
+
+#### **BlockRegistry Refactoring**
+- **Removed**: All hardcoded core blocks (`initializeCoreBlocks()`)
+- **Added**: Async `loadCoreBlocks()` method with repository fetching
+- **Improved**: Error handling, fallback system, type safety
+- **Enhanced**: Logging and debugging capabilities
+
+#### **Dynamic Loading System**
+```typescript
+async loadCoreBlocks() {
+  // Fetch blocks from /hristudio-core/plugins/
+  // Parse and validate JSON structures
+  // Convert to PluginBlockDefinition format
+  // Register with BlockRegistry
+  // Fallback to minimal blocks if loading fails
+}
+```
+
+#### **Public Serving**
+- Core repository copied to `public/hristudio-core/`
+- Accessible via `/hristudio-core/plugins/*.json`
+- Static serving ensures reliable access
+
+### **4. Files Created/Modified**
+
+#### **New Files**
+- `hristudio-core/repository.json` - Repository metadata
+- `hristudio-core/plugins/events.json` - Event blocks (4)
+- `hristudio-core/plugins/wizard-actions.json` - Wizard blocks (6)
+- `hristudio-core/plugins/control-flow.json` - Control blocks (8)
+- `hristudio-core/plugins/observation.json` - Observation blocks (8)
+- `hristudio-core/plugins/index.json` - Plugin index
+- `hristudio-core/README.md` - Complete documentation
+- `public/hristudio-core/` - Public serving copy
+- `scripts/test-core-blocks.ts` - Validation test script
+
+#### **Modified Files**
+- `src/components/experiments/designer/EnhancedBlockDesigner.tsx`
+  - Replaced hardcoded blocks with dynamic loading
+  - Enhanced error handling and type safety
+  - Improved plugin loading integration
+- `scripts/seed-core-blocks.ts` - Fixed imports and type errors
+- `scripts/seed-plugins.ts` - Fixed operators and imports  
+- `scripts/seed.ts` - Fixed delete operations warnings
+
+### **5. Quality Assurance**
+
+#### **Validation System**
+- JSON schema validation for all block definitions
+- Type consistency checking (category colors, required fields)
+- Parameter validation (types, constraints, options)
+- Comprehensive test coverage
+
+#### **Test Results**
+```
+✅ All tests passed! Core blocks system is working correctly.
+   • 26 blocks loaded from repository
+   • All required core blocks present
+   • Registry loading simulation successful
+```
+
+#### **TypeScript Compliance**
+- Fixed all unsafe `any` type usage
+- Proper type definitions for all block structures
+- Nullish coalescing operators throughout
+- No compilation errors or warnings
+
+### **6. Benefits Achieved**
+
+#### **Complete Consistency**
+- All blocks (core + robot) now use identical plugin architecture
+- Unified block management and loading patterns
+- Consistent JSON schema and validation
+
+#### **Enhanced Extensibility**
+- Add new core blocks by editing JSON files (no code changes)
+- Version control for core functionality
+- Independent updates and rollbacks
+
+#### **Improved Maintainability**
+- Centralized block definitions
+- Clear separation of concerns
+- Comprehensive documentation and validation
+
+#### **Better Developer Experience**
+- Type-safe block loading
+- Detailed error messages and logging
+- Fallback system ensures robustness
+
+### **7. Integration Points**
+
+#### **Experiment Designer**
+- Automatic core blocks loading on component mount
+- Seamless integration with existing plugin system
+- Consistent block palette organization
+
+#### **Database Integration**
+- Core blocks can be seeded as plugins if needed
+- Compatible with existing plugin management system
+- Study-scoped installations possible
+
+#### **Future Extensibility**
+- Easy to create additional core repositories
+- Simple to add new block categories
+- Version management ready
+
+## **Technical Specifications**
+
+### **Block Definition Schema**
+```json
+{
+  "id": "block_identifier",
+  "name": "Display Name",
+  "description": "Block description",
+  "category": "event|wizard|control|sensor",
+  "shape": "hat|action|control|boolean|value",
+  "icon": "LucideIconName",
+  "color": "#hexcolor",
+  "parameters": [...],
+  "execution": {...}
+}
+```
+
+### **Loading Process**
+1. Component mount triggers `loadCoreBlocks()`
+2. Fetch each block set from `/hristudio-core/plugins/`
+3. Validate JSON structure and block definitions
+4. Convert to `PluginBlockDefinition` format
+5. Register with `BlockRegistry`
+6. Fallback to minimal blocks if any failures
+
+### **Error Handling**
+- Network failures → fallback blocks
+- Invalid JSON → skip block set with warning
+- Invalid blocks → skip individual blocks
+- Type errors → graceful degradation
+
+## Integration with HRIStudio Platform
+
+### Related Documentation
+- **[Plugin System Implementation Guide](plugin-system-implementation-guide.md)** - Robot plugin architecture
+- **[Implementation Details](implementation-details.md)** - Overall platform architecture
+- **[Database Schema](database-schema.md)** - Plugin storage and management tables
+- **[API Routes](api-routes.md)** - Plugin management endpoints
+
+### Development Commands
+```bash
+# Test core blocks loading
+bun run scripts/test-core-blocks.ts
+
+# Validate block definitions
+cd public/hristudio-core && node validate.js
+
+# Update public repository
+cp -r hristudio-core/ public/hristudio-core/
+```
+
+## Status: Production Ready
+
+✅ **Complete**: All 26 core blocks implemented and tested  
+✅ **Validated**: Comprehensive testing and type checking  
+✅ **Documented**: Integrated with existing documentation system  
+✅ **Integrated**: Seamless experiment designer integration  
+✅ **Extensible**: Ready for future enhancements
+
+The core blocks system provides a robust, maintainable foundation for HRIStudio's experiment designer, ensuring complete architectural consistency across all platform components.

docs/_archive/database-schema.md

@@ -0,0 +1,598 @@
+# HRIStudio Database Schema
+
+## Overview
+
+This document provides a comprehensive database schema for HRIStudio using PostgreSQL with Drizzle ORM. The schema follows the hierarchical structure of WoZ studies and implements role-based access control, comprehensive data capture, and collaboration features.
+
+## Core Entities
+
+### Users and Authentication
+
+```sql
+-- Users table for authentication and profile information
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) UNIQUE NOT NULL,
+  email_verified TIMESTAMP,
+  name VARCHAR(255),
+  image TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  deleted_at TIMESTAMP,
+  CONSTRAINT email_format CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$')
+);
+
+-- NextAuth accounts table
+CREATE TABLE accounts (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  type VARCHAR(255) NOT NULL,
+  provider VARCHAR(255) NOT NULL,
+  provider_account_id VARCHAR(255) NOT NULL,
+  refresh_token TEXT,
+  access_token TEXT,
+  expires_at INTEGER,
+  token_type VARCHAR(255),
+  scope VARCHAR(255),
+  id_token TEXT,
+  session_state VARCHAR(255),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(provider, provider_account_id)
+);
+
+-- NextAuth sessions table
+CREATE TABLE sessions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_token VARCHAR(255) UNIQUE NOT NULL,
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  expires TIMESTAMP NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- NextAuth verification tokens
+CREATE TABLE verification_tokens (
+  identifier VARCHAR(255) NOT NULL,
+  token VARCHAR(255) UNIQUE NOT NULL,
+  expires TIMESTAMP NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (identifier, token)
+);
+```
+
+### Roles and Permissions
+
+```sql
+-- System roles
+CREATE TYPE system_role AS ENUM ('administrator', 'researcher', 'wizard', 'observer');
+
+-- User system roles
+CREATE TABLE user_system_roles (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  role system_role NOT NULL,
+  granted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  granted_by UUID REFERENCES users(id),
+  UNIQUE(user_id, role)
+);
+
+-- Custom permissions for fine-grained access control
+CREATE TABLE permissions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(100) UNIQUE NOT NULL,
+  description TEXT,
+  resource VARCHAR(50) NOT NULL,
+  action VARCHAR(50) NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Role permissions mapping
+CREATE TABLE role_permissions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  role system_role NOT NULL,
+  permission_id UUID NOT NULL REFERENCES permissions(id) ON DELETE CASCADE,
+  UNIQUE(role, permission_id)
+);
+```
+
+### Study Hierarchy
+
+```sql
+-- Studies: Top-level research projects
+CREATE TABLE studies (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(255) NOT NULL,
+  description TEXT,
+  institution VARCHAR(255),
+  irb_protocol VARCHAR(100),
+  status VARCHAR(50) DEFAULT 'draft' CHECK (status IN ('draft', 'active', 'completed', 'archived')),
+  created_by UUID NOT NULL REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSONB DEFAULT '{}',
+  settings JSONB DEFAULT '{}',
+  deleted_at TIMESTAMP
+);
+
+-- Study team members with roles
+CREATE TABLE study_members (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  role VARCHAR(50) NOT NULL CHECK (role IN ('owner', 'researcher', 'wizard', 'observer')),
+  permissions JSONB DEFAULT '[]',
+  joined_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  invited_by UUID REFERENCES users(id),
+  UNIQUE(study_id, user_id)
+);
+
+-- Experiments: Protocol templates within studies
+CREATE TABLE experiments (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  name VARCHAR(255) NOT NULL,
+  description TEXT,
+  version INTEGER DEFAULT 1,
+  robot_id UUID REFERENCES robots(id),
+  status VARCHAR(50) DEFAULT 'draft' CHECK (status IN ('draft', 'testing', 'ready', 'deprecated')),
+  estimated_duration INTEGER, -- in minutes
+  created_by UUID NOT NULL REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSONB DEFAULT '{}',
+  deleted_at TIMESTAMP,
+  UNIQUE(study_id, name, version)
+);
+
+-- Trials: Executable instances of experiments
+CREATE TABLE trials (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  experiment_id UUID NOT NULL REFERENCES experiments(id),
+  participant_id UUID REFERENCES participants(id),
+  wizard_id UUID REFERENCES users(id),
+  session_number INTEGER NOT NULL DEFAULT 1,
+  status VARCHAR(50) DEFAULT 'scheduled' CHECK (status IN ('scheduled', 'in_progress', 'completed', 'aborted', 'failed')),
+  scheduled_at TIMESTAMP,
+  started_at TIMESTAMP,
+  completed_at TIMESTAMP,
+  duration INTEGER, -- actual duration in seconds
+  notes TEXT,
+  parameters JSONB DEFAULT '{}',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSONB DEFAULT '{}'
+);
+
+-- Steps: Phases within experiments
+CREATE TABLE steps (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  experiment_id UUID NOT NULL REFERENCES experiments(id) ON DELETE CASCADE,
+  name VARCHAR(255) NOT NULL,
+  description TEXT,
+  type VARCHAR(50) NOT NULL CHECK (type IN ('wizard', 'robot', 'parallel', 'conditional')),
+  order_index INTEGER NOT NULL,
+  duration_estimate INTEGER, -- in seconds
+  required BOOLEAN DEFAULT true,
+  conditions JSONB DEFAULT '{}',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(experiment_id, order_index)
+);
+
+-- Actions: Atomic tasks within steps
+CREATE TABLE actions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  step_id UUID NOT NULL REFERENCES steps(id) ON DELETE CASCADE,
+  name VARCHAR(255) NOT NULL,
+  description TEXT,
+  type VARCHAR(100) NOT NULL, -- e.g., 'speak', 'move', 'wait', 'collect_data'
+  order_index INTEGER NOT NULL,
+  parameters JSONB DEFAULT '{}',
+  validation_schema JSONB,
+  timeout INTEGER, -- in seconds
+  retry_count INTEGER DEFAULT 0,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(step_id, order_index)
+);
+```
+
+### Participants and Data Protection
+
+```sql
+-- Participants in studies
+-- NOTE: The application exposes a computed `trialCount` field in API list responses.
+-- This value is derived at query time by counting linked trials and is NOT persisted
+-- as a physical column in this table to avoid redundancy and maintain consistency.
+CREATE TABLE participants (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  participant_code VARCHAR(50) NOT NULL,
+  email VARCHAR(255),
+  name VARCHAR(255),
+  demographics JSONB DEFAULT '{}', -- encrypted
+  consent_given BOOLEAN DEFAULT false,
+  consent_date TIMESTAMP,
+  notes TEXT, -- encrypted
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(study_id, participant_code)
+);
+
+-- Consent forms and documents
+CREATE TABLE consent_forms (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  version INTEGER DEFAULT 1,
+  title VARCHAR(255) NOT NULL,
+  content TEXT NOT NULL,
+  active BOOLEAN DEFAULT true,
+  created_by UUID NOT NULL REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  storage_path TEXT, -- path in MinIO
+  UNIQUE(study_id, version)
+);
+
+-- Participant consent records
+CREATE TABLE participant_consents (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  participant_id UUID NOT NULL REFERENCES participants(id) ON DELETE CASCADE,
+  consent_form_id UUID NOT NULL REFERENCES consent_forms(id),
+  signed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  signature_data TEXT, -- encrypted
+  ip_address INET,
+  storage_path TEXT, -- path to signed PDF in MinIO
+  UNIQUE(participant_id, consent_form_id)
+);
+```
+
+### Robot Platform Integration
+
+```sql
+-- Robot types/models
+CREATE TABLE robots (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(255) NOT NULL,
+  manufacturer VARCHAR(255),
+  model VARCHAR(255),
+  description TEXT,
+  capabilities JSONB DEFAULT '[]',
+  communication_protocol VARCHAR(50) CHECK (communication_protocol IN ('rest', 'ros2', 'custom')),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Plugin definitions
+CREATE TABLE plugins (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  robot_id UUID REFERENCES robots(id) ON DELETE CASCADE,
+  name VARCHAR(255) NOT NULL,
+  version VARCHAR(50) NOT NULL,
+  description TEXT,
+  author VARCHAR(255),
+  repository_url TEXT,
+  trust_level VARCHAR(20) CHECK (trust_level IN ('official', 'verified', 'community')),
+  status VARCHAR(20) DEFAULT 'active' CHECK (status IN ('active', 'deprecated', 'disabled')),
+  configuration_schema JSONB,
+  action_definitions JSONB DEFAULT '[]',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSONB DEFAULT '{}',
+  UNIQUE(name, version)
+);
+
+-- Plugin installations per study
+CREATE TABLE study_plugins (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  plugin_id UUID NOT NULL REFERENCES plugins(id),
+  configuration JSONB DEFAULT '{}',
+  installed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  installed_by UUID NOT NULL REFERENCES users(id),
+  UNIQUE(study_id, plugin_id)
+);
+```
+
+### Experiment Execution and Data Capture
+
+```sql
+-- Trial events log
+CREATE TABLE trial_events (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  trial_id UUID NOT NULL REFERENCES trials(id) ON DELETE CASCADE,
+  event_type VARCHAR(50) NOT NULL, -- 'action_started', 'action_completed', 'error', 'intervention'
+  action_id UUID REFERENCES actions(id),
+  timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  data JSONB DEFAULT '{}',
+  created_by UUID REFERENCES users(id), -- NULL for system events
+  INDEX idx_trial_events_trial_timestamp (trial_id, timestamp)
+);
+
+-- Wizard interventions/quick actions
+CREATE TABLE wizard_interventions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  trial_id UUID NOT NULL REFERENCES trials(id) ON DELETE CASCADE,
+  wizard_id UUID NOT NULL REFERENCES users(id),
+  intervention_type VARCHAR(100) NOT NULL,
+  description TEXT,
+  timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  parameters JSONB DEFAULT '{}',
+  reason TEXT
+);
+
+-- Media captures (video, audio)
+CREATE TABLE media_captures (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  trial_id UUID NOT NULL REFERENCES trials(id) ON DELETE CASCADE,
+  media_type VARCHAR(20) CHECK (media_type IN ('video', 'audio', 'image')),
+  storage_path TEXT NOT NULL, -- MinIO path
+  file_size BIGINT,
+  duration INTEGER, -- in seconds for video/audio
+  format VARCHAR(20),
+  resolution VARCHAR(20), -- for video
+  start_timestamp TIMESTAMP,
+  end_timestamp TIMESTAMP,
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Sensor data captures
+CREATE TABLE sensor_data (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  trial_id UUID NOT NULL REFERENCES trials(id) ON DELETE CASCADE,
+  sensor_type VARCHAR(50) NOT NULL,
+  timestamp TIMESTAMP NOT NULL,
+  data JSONB NOT NULL,
+  robot_state JSONB DEFAULT '{}',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_sensor_data_trial_timestamp (trial_id, timestamp)
+);
+
+-- Analysis annotations
+CREATE TABLE annotations (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  trial_id UUID NOT NULL REFERENCES trials(id) ON DELETE CASCADE,
+  annotator_id UUID NOT NULL REFERENCES users(id),
+  timestamp_start TIMESTAMP NOT NULL,
+  timestamp_end TIMESTAMP,
+  category VARCHAR(100),
+  description TEXT,
+  tags JSONB DEFAULT '[]',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### Collaboration and Activity Tracking
+
+```sql
+-- Study activity log
+CREATE TABLE activity_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID REFERENCES studies(id) ON DELETE CASCADE,
+  user_id UUID REFERENCES users(id),
+  action VARCHAR(100) NOT NULL,
+  resource_type VARCHAR(50),
+  resource_id UUID,
+  description TEXT,
+  ip_address INET,
+  user_agent TEXT,
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_activity_logs_study_created (study_id, created_at DESC)
+);
+
+-- Comments and discussions
+CREATE TABLE comments (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  parent_id UUID REFERENCES comments(id) ON DELETE CASCADE,
+  resource_type VARCHAR(50) NOT NULL, -- 'experiment', 'trial', 'annotation'
+  resource_id UUID NOT NULL,
+  author_id UUID NOT NULL REFERENCES users(id),
+  content TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  deleted_at TIMESTAMP
+);
+
+-- File attachments
+CREATE TABLE attachments (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  uploaded_by UUID NOT NULL REFERENCES users(id),
+  filename VARCHAR(255) NOT NULL,
+  mime_type VARCHAR(100),
+  file_size BIGINT,
+  storage_path TEXT NOT NULL, -- MinIO path
+  description TEXT,
+  resource_type VARCHAR(50),
+  resource_id UUID,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### Data Export and Sharing
+
+```sql
+-- Export jobs
+CREATE TABLE export_jobs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  requested_by UUID NOT NULL REFERENCES users(id),
+  export_type VARCHAR(50) NOT NULL, -- 'full', 'trials', 'analysis', 'media'
+  format VARCHAR(20) NOT NULL, -- 'json', 'csv', 'zip'
+  filters JSONB DEFAULT '{}',
+  status VARCHAR(20) DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
+  storage_path TEXT,
+  expires_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  completed_at TIMESTAMP,
+  error_message TEXT
+);
+
+-- Shared resources
+CREATE TABLE shared_resources (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  resource_type VARCHAR(50) NOT NULL,
+  resource_id UUID NOT NULL,
+  shared_by UUID NOT NULL REFERENCES users(id),
+  share_token VARCHAR(255) UNIQUE,
+  permissions JSONB DEFAULT '["read"]',
+  expires_at TIMESTAMP,
+  access_count INTEGER DEFAULT 0,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### System Configuration
+
+```sql
+-- System settings
+CREATE TABLE system_settings (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  key VARCHAR(100) UNIQUE NOT NULL,
+  value JSONB NOT NULL,
+  description TEXT,
+  updated_by UUID REFERENCES users(id),
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Audit log for compliance
+CREATE TABLE audit_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id),
+  action VARCHAR(100) NOT NULL,
+  resource_type VARCHAR(50),
+  resource_id UUID,
+  changes JSONB DEFAULT '{}',
+  ip_address INET,
+  user_agent TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_audit_logs_created (created_at DESC)
+);
+```
+
+## Indexes and Performance
+
+```sql
+-- Performance indexes
+CREATE INDEX idx_users_email ON users(email) WHERE deleted_at IS NULL;
+CREATE INDEX idx_studies_created_by ON studies(created_by) WHERE deleted_at IS NULL;
+CREATE INDEX idx_trials_experiment ON trials(experiment_id);
+CREATE INDEX idx_trials_status ON trials(status) WHERE status IN ('scheduled', 'in_progress');
+CREATE INDEX idx_trial_events_type ON trial_events(event_type);
+CREATE INDEX idx_participants_study ON participants(study_id);
+CREATE INDEX idx_study_members_user ON study_members(user_id);
+CREATE INDEX idx_media_captures_trial ON media_captures(trial_id);
+CREATE INDEX idx_annotations_trial ON annotations(trial_id);
+
+-- Full text search indexes
+CREATE INDEX idx_studies_search ON studies USING GIN (to_tsvector('english', name || ' ' || COALESCE(description, '')));
+CREATE INDEX idx_experiments_search ON experiments USING GIN (to_tsvector('english', name || ' ' || COALESCE(description, '')));
+```
+
+## Views for Common Queries
+
+```sql
+-- Active studies with member count
+CREATE VIEW active_studies_summary AS
+SELECT 
+  s.id,
+  s.name,
+  s.status,
+  s.created_at,
+  u.name as creator_name,
+  COUNT(DISTINCT sm.user_id) as member_count,
+  COUNT(DISTINCT e.id) as experiment_count,
+  COUNT(DISTINCT t.id) as trial_count
+FROM studies s
+LEFT JOIN users u ON s.created_by = u.id
+LEFT JOIN study_members sm ON s.id = sm.study_id
+LEFT JOIN experiments e ON s.id = e.study_id AND e.deleted_at IS NULL
+LEFT JOIN trials t ON e.id = t.experiment_id
+WHERE s.deleted_at IS NULL AND s.status = 'active'
+GROUP BY s.id, s.name, s.status, s.created_at, u.name;
+
+-- Trial execution summary
+CREATE VIEW trial_execution_summary AS
+SELECT 
+  t.id,
+  t.experiment_id,
+  t.status,
+  t.scheduled_at,
+  t.started_at,
+  t.completed_at,
+  t.duration,
+  p.participant_code,
+  w.name as wizard_name,
+  COUNT(DISTINCT te.id) as event_count,
+  COUNT(DISTINCT wi.id) as intervention_count
+FROM trials t
+LEFT JOIN participants p ON t.participant_id = p.id
+LEFT JOIN users w ON t.wizard_id = w.id
+LEFT JOIN trial_events te ON t.id = te.trial_id
+LEFT JOIN wizard_interventions wi ON t.id = wi.trial_id
+GROUP BY t.id, t.experiment_id, t.status, t.scheduled_at, t.started_at, 
+         t.completed_at, t.duration, p.participant_code, w.name;
+```
+
+## Database Functions and Triggers
+
+```sql
+-- Update timestamp trigger
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = CURRENT_TIMESTAMP;
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Apply update trigger to relevant tables
+CREATE TRIGGER update_users_updated_at BEFORE UPDATE ON users
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+CREATE TRIGGER update_studies_updated_at BEFORE UPDATE ON studies
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+CREATE TRIGGER update_experiments_updated_at BEFORE UPDATE ON experiments
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+-- Apply to other tables as needed...
+
+-- Function to check user permissions
+CREATE OR REPLACE FUNCTION check_user_permission(
+  p_user_id UUID,
+  p_study_id UUID,
+  p_action VARCHAR
+) RETURNS BOOLEAN AS $$
+DECLARE
+  v_has_permission BOOLEAN;
+BEGIN
+  -- Check if user has permission through study membership or system role
+  SELECT EXISTS (
+    SELECT 1 FROM study_members sm
+    WHERE sm.user_id = p_user_id 
+    AND sm.study_id = p_study_id
+    AND (
+      sm.role = 'owner' OR
+      p_action = ANY(sm.permissions::text[])
+    )
+  ) OR EXISTS (
+    SELECT 1 FROM user_system_roles usr
+    WHERE usr.user_id = p_user_id
+    AND usr.role = 'administrator'
+  ) INTO v_has_permission;
+  
+  RETURN v_has_permission;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+## Migration Notes
+
+1. Tables should be created in the order listed to respect foreign key constraints
+2. Sensitive data in `participants`, `participant_consents`, and related tables should use PostgreSQL's pgcrypto extension for encryption
+3. Consider partitioning large tables like `sensor_data` and `trial_events` by date for better performance
+4. Implement regular vacuum and analyze schedules for optimal performance
+5. Set up appropriate backup strategies for both PostgreSQL and MinIO data

docs/_archive/experiment-designer-redesign.md

@@ -0,0 +1,532 @@
+# Experiment Designer Redesign (Production Baseline)
+
+This document defines the production-ready redesign of the Experiment Designer. It supersedes prior "modular refactor" notes and consolidates architecture, hashing, drift detection, UI/UX, state management, validation, plugin integration, saving/versioning, and export strategy. All implementation must adhere to this specification to ensure reproducibility, extensibility, and maintainability.
+
+---
+
+## 1. Goals
+
+- Provide a clear, fast, and intuitive hierarchical design workflow.
+- Guarantee reproducibility via deterministic hashing and provenance retention.
+- Surface plugin dependency health and schema drift early.
+- Support scalable experiments (many steps/actions) without UI degradation.
+- Enable structured validation (structural, parameter-level, semantic) before compilation.
+- Provide robust export/import and future multi-user collaboration readiness.
+- Maintain 100% type safety and consistent design patterns across the platform.
+
+---
+
+## 2. Conceptual Model
+
+Hierarchy:
+```
+Experiment
+  └─ Step (ordered, typed)
+        └─ Action (ordered, typed, provenance-bound)
+```
+
+Key invariants:
+- Step `order` is zero-based, contiguous after any mutation.
+- Action `orderIndex` is zero-based within its parent step.
+- Each action retains provenance: `{ source.kind, pluginId?, pluginVersion?, baseActionId? }`
+- Execution descriptors are retained for reproducibility (`transport`, `ros2`, `rest`, `retryable`, `timeoutMs`).
+
+---
+
+## 3. Hashing & Integrity Guarantees
+
+### 3.1 Purposes of Hashing
+- Detect structural drift between persisted design and working edits.
+- Bind design to plugin and action schemas for reproducibility.
+- Support execution graph provenance (hash at compile time).
+- Enable export integrity and offline verification.
+
+### 3.2 Design Hash Components
+Included:
+- Steps (ordered): `id`, `name`, `type`, `order`, `trigger.type`, sorted trigger condition keys.
+- Actions (per step, ordered): `id`, `type`, `source.kind`, `pluginId`, `pluginVersion`, `baseActionId`, `execution.transport`, parameter key set (NOT values by default—configurable).
+- Optional: parameter values (toggle design mode if needed—default: exclude values to reduce false-positive drift).
+
+Excluded:
+- Ephemeral UI state (`expanded`, selection state).
+- Human-friendly timestamps or transient meta.
+
+### 3.3 Canonicalization Steps
+1. Deep clone design subset.
+2. Remove `undefined` keys.
+3. Sort object keys recursively.
+4. Sort arrays where semantic ordering is not meaningful (e.g. condition key sets).
+5. JSON stringify (no whitespace).
+6. SHA-256 digest → hex.
+
+### 3.4 Incremental Hash Optimization
+Per-action hash → per-step hash → design hash:
+```
+H_action = hash(canonical(actionMeta))
+H_step = hash(stepMeta + concat(H_action_i))
+H_design = hash(globalMeta + concat(H_step_i))
+```
+Recompute only modified branches for responsiveness.
+
+### 3.5 Drift States
+| State        | Condition                                                                                          |
+|--------------|----------------------------------------------------------------------------------------------------|
+| Unvalidated  | No validation performed since load                                                                 |
+| Validated    | Last validated hash matches stored experiment integrity hash and working snapshot unchanged        |
+| Drift        | (A) Working snapshot changed since last validation OR (B) validated hash ≠ stored integrity hash   |
+| Plugin Drift | Design validated, but one or more action definitions (schema/provenance) no longer match registry  |
+
+### 3.6 Plugin Signature Drift
+Signature hash per action definition: hash of `(type + category + parameterSchema + transport + baseActionId + pluginVersion)`.
+- If signature mismatch for existing action instance: mark as “schema drift”.
+- Provide reconciliation CTA to refetch schema and optionally run migration.
+
+---
+
+## 4. UI Architecture
+
+High-level layout:
+
+```
+┌───────────────────────────────────────────────────────────────────────────┐
+│ Header: breadcrumbs • experiment name • hash badge • plugin deps summary  │
+├──────────────┬───────────────────────────────┬────────────────────────────┤
+│ Action       │ Step Flow (sortable linear)   │ Properties / Inspector      │
+│ Library      │ - Step cards (collapsible)     │ - Step editor               │
+│ - Search     │ - Inline action list           │ - Action parameters         │
+│ - Categories │ - DnD (steps/actions/library)  │ - Validation & drift panel  │
+│ - Plugins    │ - Structural markers           │ - Dependencies & provenance │
+├──────────────┴───────────────────────────────┴────────────────────────────┤
+│ Bottom Save Bar: dirty state • versioning • export • last saved • conflicts│
+└───────────────────────────────────────────────────────────────────────────┘
+```
+
+Component responsibilities:
+| Component                     | Responsibility |
+|------------------------------|----------------|
+| `DesignerRoot`               | Data loading, permission guard, store boot |
+| `ActionLibraryPanel`         | Search/filter, categorized draggable items |
+| `FlowWorkspace`              | Rendering + reordering steps & actions |
+| `StepCard`                   | Step context container |
+| `ActionItem`                 | Visual + selectable action row |
+| `PropertiesPanel`            | Context editing (step/action) |
+| `ParameterFieldFactory`      | Schema → control mapping |
+| `ValidationPanel`            | Issue listing + filtering |
+| `DependencyInspector`        | Plugin + action provenance health |
+| `BottomStatusBar`            | Hash/drift/dirtiness/export/version controls |
+| `hashing.ts`                 | Canonicalization + incremental hashing |
+| `validators.ts`              | Rule execution (structural, parameter) |
+| `exporters.ts`               | Export bundle builder |
+| `store/useDesignerStore.ts`  | Central state store |
+
+---
+
+## 5. State Management
+
+Use a lightweight, framework-agnostic, fully typed store (Zustand). Core fields:
+
+```
+{
+  steps: ExperimentStep[]
+  dirty: Set<string>
+  selectedStepId?: string
+  selectedActionId?: string
+  lastPersistedHash?: string
+  lastValidatedHash?: string
+  lastValidatedSnapshot?: string
+  pluginSignatureIndex: Record<actionTypeOrId, string>
+  validationIssues: Record<entityId, string[]>
+  pendingSave?: boolean
+  conflict?: { serverHash: string; localHash: string }
+}
+```
+
+### Actions
+- `setSteps`, `upsertStep`, `removeStep`, `reorderStep`
+- `upsertAction`, `removeAction`, `reorderAction`
+- `markDirty(entityId)`
+- `computeDesignHash()`
+- `setValidationResult({ hash, issues, snapshot })`
+- `applyServerSync({ steps, hash })`
+- `recordConflict(serverHash, localHash)`
+
+---
+
+## 6. Drag & Drop
+
+Library → Step
+- Drag action definition placeholder onto step drop zone triggers action instantiation.
+Step reorder
+- Sortable vertical list with keyboard accessibility.
+Action reorder
+- Sortable within a step (no cross-step move initially; future extension).
+Framework: `@dnd-kit/core` + `@dnd-kit/sortable`.
+
+Accessibility:
+- Custom keyboard handlers: Up/Down to move selection; Alt+Up/Down to reorder.
+
+---
+
+## 7. Parameters & Control Mapping
+
+Mapping:
+| Schema Type | Control |
+|-------------|---------|
+| boolean     | Switch |
+| number (bounded) | Slider + numeric display |
+| number (unbounded) | Numeric input |
+| text short  | Text input |
+| text long   | Textarea (expandable) |
+| select/enumeration | Select / Combobox |
+| multi-select | Tag list (future) |
+| json/object | Lazy code editor (future) |
+
+Enhancements:
+- Show required indicator
+- Inline validation message
+- Revert-to-default button if default provided
+- Modified badge (dot) for overridden parameters
+
+---
+
+## 8. Validation System
+
+Levels:
+1. Structural
+   - No empty step names
+   - Steps must have valid `type`
+   - Conditional/loop must define required condition semantics
+2. Parameter
+   - Required values present
+   - Number bounds enforced
+   - Enum membership
+3. Semantic
+   - No unresolved plugin dependency
+   - Unique action IDs and step IDs
+   - Loop guard presence (future)
+4. Execution Preflight (optional)
+   - Detect obviously irrecoverable execution (e.g. empty parallel block)
+
+Severity classification:
+- Error: blocks save/compile
+- Warning: surfaced but non-blocking
+- Info: advisory (e.g. unused parameter)
+
+Store format:
+```
+validationIssues: {
+  [entityId: string]: { severity: "error" | "warning" | "info"; message: string }[]
+}
+```
+
+Rendering:
+- Badge on step/actions with count + highest severity color.
+- Panel filter toggles (Errors / Warnings / All).
+- Inline icon markers.
+
+---
+
+## 9. Plugin Integration & Drift
+
+Definitions loaded into `ActionRegistry`:
+```
+{
+  id,
+  type,
+  name,
+  category,
+  parameters[],
+  source: { kind, pluginId?, pluginVersion?, baseActionId? },
+  execution?,
+  parameterSchemaRaw
+}
+```
+
+Per-definition signatureHash computed:
+`hash(type + category + JSON(parameterSchemaRaw) + execution.transport + baseActionId + pluginVersion)`
+
+Per-action drift logic:
+- If action.source.pluginVersion missing in registry → Blocked (hard drift).
+- If signatureHash mismatch → Soft drift (allow edit, prompt reconcile).
+- Provide “Reconcile” overlay listing changed parameters (added / removed / type changed).
+
+---
+
+## 10. Saving & Versioning
+
+Save triggers:
+- Manual (primary save button or Cmd+S)
+- Debounced auto-save (idle > 5s, no pending errors)
+- Forced save before export
+
+Payload:
+```
+{
+  id,
+  visualDesign: { steps, version, lastSaved },
+  createSteps: true,
+  compileExecution: true
+}
+```
+
+Version management:
+- If structural change (add/remove/reorder step/action or change type) → version bump (auto unless user disables).
+- Parameter-only changes may optionally not bump version (configurable toggle; default: no bump).
+- UI: dropdown / toggle “Increment version on save”.
+
+Conflict detection:
+- Server returns persisted integrityHash.
+- If local lastPersistedHash differs and serverHash differs from our pre-save computed hash → conflict modal.
+- Provide:
+  - View diff summary (step added/removed, action count deltas).
+  - Override server (if authorized) or Reload.
+
+---
+
+## 11. Export / Import
+
+Export bundle structure:
+```json
+{
+  "format": "hristudio.design.v1",
+  "exportedAt": "...ISO8601...",
+  "experiment": {
+    "id": "...",
+    "name": "...",
+    "version": 4,
+    "integrityHash": "...",
+    "steps": [... canonical steps ...],
+    "pluginDependencies": ["pluginA@1.2.1", "robot.voice@0.9.3"]
+  },
+  "compiled": {
+    "graphHash": "...",
+    "steps": 12,
+    "actions": 47,
+    "plan": { /* normalized execution nodes */ }
+  }
+}
+```
+
+Import validation:
+- Check `format` signature & version.
+- Recompute design hash vs embedded.
+- Check plugin availability (list missing).
+- Offer “Install required plugins” if privileges allow.
+
+---
+
+## 12. Accessibility & UX Standards
+
+- Keyboard traversal (Tab / Arrow) across steps & actions.
+- Focus ring on selected entities.
+- ARIA labels on all interactive controls (drag handles, add buttons).
+- Color usage passes contrast (WCAG 2.1 AA).
+- Non-color indicators for drift (icons / labels).
+- All icons: Lucide only.
+
+---
+
+## 13. Performance Considerations
+
+- Virtualize StepFlow when step count > threshold (e.g. 50).
+- Memoize parameter forms (avoid re-render on unrelated step changes).
+- Incremental hashing—avoid full recompute on each keystroke.
+- Lazy-load advanced components (JSON editor, large schema viewers).
+
+---
+
+## 14. Testing Strategy
+
+Unit Tests:
+- Hash determinism (same structure -> same hash).
+- Hash sensitivity (reorder step / change action type -> different hash).
+- Signature drift detection logic.
+- Validation rule coverage (structural & parameter).
+
+Integration Tests:
+- Save cycle (design → save → fetch → hash equality).
+- Plugin dependency missing scenario.
+- Conflict resolution workflow.
+
+Edge Cases:
+- Empty experiment (0 steps) → validation error.
+- Conditional step with no conditions → error.
+- Loop step missing guard → warning (future escalation).
+- Plugin removed post-design → plugin drift surfaced.
+
+---
+
+## 15. Migration Plan (Internal) - COMPLETE ✅
+
+1. ✅ Introduce new store + hashing modules.
+2. ✅ Replace current `BlockDesigner` usage with `DesignerRoot`.
+3. ✅ Port ActionLibrary / StepFlow / PropertiesPanel to new contract (`ActionLibraryPanel`, `FlowWorkspace`, `InspectorPanel`).
+4. ✅ Add BottomStatusBar + drift/UI overlays.
+5. ✅ Remove deprecated legacy design references and components.
+6. ✅ Update docs cross-links (`project-overview.md`, `implementation-details.md`).
+7. Add export/import UI.
+8. Stabilize, then enforce hash validation before trial creation.
+
+---
+
+## 16. Security & Integrity
+
+- Server must recompute its own structural hash during compile to trust design.
+- Client-submitted integrityHash considered advisory; never trusted alone.
+- Plugin versions pinned explicitly inside actions (no implicit latest resolution).
+- Attempting to execute an experiment with unresolved drift prompts required validation.
+
+---
+
+## 17. Future Extensions
+
+| Feature                  | Description |
+|--------------------------|-------------|
+| Real-time co-editing     | WebSocket presence + granular patch sync |
+| Branching workflows      | Conditional branches forming DAG (graph mode) |
+| Step templates library   | Shareable reproducible step/action sets |
+| Parameter presets        | Save named parameter bundles per action type |
+| Timeline estimation view | Aggregate predicted duration |
+| Replay / provenance diff | Compare two design versions side-by-side |
+| Plugin action migration  | Scripted param transforms on schema changes |
+| Execution simulation     | Dry-run graph traversal with timing estimates |
+
+---
+
+## 18. Implementation Checklist (Actionable)
+
+- [x] hashing.ts (canonical + incremental)
+- [x] validators.ts (structural + param rules)
+- [x] store/useDesignerStore.ts
+- [x] layout/PanelsContainer.tsx — Tailwind-first grid (fraction-based), strict overflow containment, non-persistent
+- [x] Drag-resize for panels — fraction CSS variables with hard clamps (no localStorage)
+- [x] DesignerRoot layout — status bar inside bordered container (no bottom gap), min-h-0 + overflow-hidden chain
+- [x] ActionLibraryPanel — internal scroll only (panel scroll, not page)
+- [x] InspectorPanel — single Tabs root for header+content; removed extra border; grid tabs header
+- [x] Tabs (shadcn) — restored stock component; globals.css theming for active state
+
+---
+
+## 19. Layout & Overflow Refactor (2025‑08)
+
+Why:
+- Eliminate page-level horizontal scrolling and snapping
+- Ensure each panel scrolls internally while the page/container never does on X
+- Remove brittle width persistence and hard-coded pixel widths
+
+Key rules (must follow):
+- Use Tailwind-first CSS Grid for panels; ratios, not pixels
+  - PanelsContainer sets grid-template-columns with CSS variables (e.g., --col-left/center/right)
+  - No hard-coded px widths in panels; use fractions and minmax(0, …)
+- Strict overflow containment chain:
+  - Dashboard content wrapper: flex, min-h-0, overflow-hidden
+  - DesignerRoot outer container: flex, min-h-0, overflow-hidden
+  - PanelsContainer root: grid, h-full, min-h-0, w-full, overflow-hidden
+  - Panel wrapper: min-w-0, overflow-hidden
+  - Panel content: overflow-y-auto, overflow-x-hidden
+- Status Bar:
+  - Lives inside the bordered designer container
+  - No gap between panels area and status bar (status bar is flex-shrink-0 with border-t)
+- No persistence:
+  - Remove localStorage panel width persistence to avoid flash/snap on load
+- No page-level X scroll:
+  - If X scroll appears, fix the child (truncate/break-words/overflow-x-hidden), not the container
+
+Container chain snapshot:
+- Dashboard layout: header + content (p-4, pt-0, overflow-hidden)
+- DesignerRoot: flex column; PageHeader (shrink-0) + main bordered container (flex-1, overflow-hidden)
+- PanelsContainer: grid with minmax(0, …) columns; internal y-scroll per panel
+- BottomStatusBar: inside bordered container (no external spacing)
+
+---
+
+## 20. Inspector Tabs (shadcn) Resolution
+
+Symptoms:
+- Active state not visible in right panel tabs despite working elsewhere
+
+Root cause:
+- Multiple Tabs roots and extra wrappers around triggers prevented data-state propagation/styling
+
+Fix:
+- Use a single Tabs root to control both header and content
+- Header markup mirrors working example (e.g., trials analysis):
+  - TabsList: grid w-full grid-cols-3 (or inline-flex with bg-muted and p-1)
+  - TabsTrigger: stock shadcn triggers (no Tooltip wrapper around the trigger itself)
+- Remove right-panel self border when container draws dividers (avoid double border)
+- Restore stock shadcn/ui Tabs component via generator; theme via globals.css only
+
+Do:
+- Keep Tabs value/onValueChange at the single root
+- Style active state via globals.css selectors targeting data-state="active"
+
+Don’t:
+- Wrap TabsTrigger directly in Tooltip wrappers (use title or wrap outside the trigger)
+- Create nested Tabs roots for header vs content
+
+---
+
+## 21. Drag‑Resize Panels (Non‑Persistent)
+
+Approach:
+- PanelsContainer exposes drag handles at left/center and center/right separators
+- Resize adjusts CSS variables for grid fractions:
+  - --col-left, --col-center, --col-right (sum ~ 1)
+- Hard clamps ensure usable panels and avoid overflow:
+  - left in [minLeftPct, maxLeftPct], right in [minRightPct, maxRightPct]
+  - center = 1 − (left + right), with a minimum center fraction
+
+Accessibility:
+- Handles are buttons with role="separator", aria-orientation="vertical"
+- Keyboard: Arrow keys resize (Shift increases step)
+
+Persistence:
+- None. No localStorage. Prevents snap-back and layout flash on load
+
+Overflow:
+- Grid and panels keep overflow-x hidden at every level
+- Long content in a panel scrolls vertically within that panel only
+
+---
+
+## 22. Tabs Theming (Global)
+
+- Use globals.css to style shadcn Tabs consistently via data attributes:
+  - [data-slot="tabs-list"]: container look (bg-muted, rounded, p-1)
+  - [data-slot="tabs-trigger"][data-state="active"]: bg/text/shadow (active contrast)
+- Avoid component-level overrides unless necessary; prefer global theme tokens (background, foreground, muted, accent)
+
+- [x] ActionRegistry rewrite with signature hashing
+- [x] ActionLibraryPanel (search, categories, drift indicators)
+- [x] FlowWorkspace + StepCard + ActionItem (DnD with @dnd-kit)
+- [x] PropertiesPanel + ParameterFieldFactory
+- [x] ValidationPanel + badges
+- [x] DependencyInspector + plugin drift mapping
+- [x] BottomStatusBar (dirty, versioning, export)
+- [ ] Exporter (JSON bundle) + import hook
+- [ ] Conflict modal
+- [ ] Drift reconciliation UI
+- [ ] Unit & integration tests
+- [x] Docs cross-link updates
+- [x] Remove obsolete legacy code paths
+
+(Track progress in `docs/work_in_progress.md` under “Experiment Designer Redesign Implementation”.)
+
+---
+
+## 19. Cross-References
+
+- See `docs/implementation-details.md` (update with hashing + drift model)
+- See `docs/api-routes.md` (`experiments.update`, `experiments.validateDesign`)
+- See `docs/database-schema.md` (`steps`, `actions`, provenance fields)
+- See `docs/project-overview.md` (designer feature summary)
+- See `docs/work_in_progress.md` (status tracking)
+
+---
+
+## 20. Summary
+
+This redesign formalizes a production-grade, reproducible, and extensible experiment design environment with deterministic hashing, plugin-aware action provenance, structured validation, export integrity, and a modular, performance-conscious UI framework. Implementation should now proceed directly against this spec; deviations require documentation updates and justification.
+
+---
+End of specification.

docs/_archive/experiment-designer-step-integration.md

@@ -0,0 +1,253 @@
+# Experiment Designer Step Integration (Modular Architecture + Drift Handling)
+
+## Overview
+
+The HRIStudio experiment designer has been redesigned with a step-based + provenance-aware architecture that provides intuitive experiment creation, transparent plugin usage, and reproducible execution through integrity hashing and a compiled execution graph.
+
+## Architecture
+
+### Core Design Philosophy
+
+The designer follows a clear hierarchy that matches database structure, runtime execution, and reproducibility tracking:
+- **Experiment** → **Steps** → **Actions** (with provenance + execution descriptors)
+- Steps are primary containers in the flow (Step 1 → Step 2 → Step 3) with sortable ordering
+- Actions are dragged from a categorized library into step containers (core vs plugin clearly labeled)
+- Direct 1:1 mapping to database `steps` and `actions` tables, persisting provenance & transport metadata
+
+### Key Components (Post-Modularization)
+
+#### ActionRegistry (`ActionRegistry.ts`)
+- Loads actions from core plugin repositories (`hristudio-core/plugins/`)
+- Integrates study-scoped robot plugins (namespaced: `pluginId.actionId`)
+- Provides fallback actions if plugin loading fails (ensures minimal operability)
+- Maps plugin parameter schemas (primitive: text/number/select/boolean) to UI fields
+- Retains provenance + execution descriptors (transport, timeout, retryable)
+
+#### Step-Based Flow (`StepFlow.tsx`)
+- Sortable step containers with drag-and-drop reordering (via `@dnd-kit`)
+- Color-coded step types (sequential, parallel, conditional, loop) with left border accent
+- Expandable/collapsible view for managing complex experiments
+- Visual connectors between steps (light vertical separators)
+- Isolated from parameter/editor logic for performance and clarity
+
+#### Action Library (`ActionLibrary.tsx`)
+- Categorized tabs: Wizard (blue), Robot (emerald), Control (amber), Observation (purple)
+- Tooltips show description, parameters, provenance badge (C core / P plugin)
+- Drag-and-drop from library directly into specific step droppable zones
+- Footer statistics (total actions / category count)
+- Empty + fallback guidance when plugin actions absent
+- Guarantees availability: once the experiment's study context and its installed plugins are loaded, all corresponding plugin actions are registered and appear (guarded against duplicate loads / stale study mismatch)
+- Plugin availability is study-scoped: only plugins installed for the experiment's parent study (via Plugin Store installation) are loaded and exposed; this ensures experiments cannot reference uninstalled or unauthorized plugin actions.
+
+#### Properties Panel (`PropertiesPanel.tsx`)
+- Context-aware: action selection → action parameters; step selection → step metadata; otherwise instructional state
+- Boolean parameters now render as accessible Switch
+- Number parameters with `min`/`max` render as Slider (shows live value + bounds)
+- Number parameters without bounds fall back to numeric input
+- Select/text unchanged; future: enum grouping + advanced editors
+- Displays provenance + transport badges (plugin id@version, transport, retryable)
+
+## User Experience
+
+### Visual Design
+- **Tightened Spacing**: Compact UI with efficient screen real estate usage
+- **Dark Mode Support**: Proper selection states and theme-aware colors
+- **Color Consistency**: Category colors used throughout for visual coherence
+- **Micro-interactions**: Hover states, drag overlays, smooth transitions
+
+### Interaction Patterns
+- **Direct Action Editing**: Click any action to immediately edit properties (no step selection required)
+- **Multi-level Sorting**: Reorder steps in flow, reorder actions within steps
+- **Visual Feedback**: Drop zones highlight, selection states clear, drag handles intuitive
+- **Touch-friendly**: Proper activation constraints for mobile/touch devices
+
+### Properties Panel (Enhanced Parameter Controls)
+- **Action-First Workflow**: Immediate property editing on action selection
+- **Rich Metadata**: Icon, category color, provenance badges (Core/Plugin, transport)
+- **Switch for Boolean**: Improves clarity vs checkbox in dense layouts
+- **Slider for Ranged Number**: Applies when `min` or `max` present (live formatted value)
+- **Graceful Fallbacks**: Plain number input if no bounds; text/select unchanged
+- **Context-Aware**: Step editing (name/type/trigger) isolated from action editing
+
+## Technical Implementation
+
+### Drag and Drop System
+Built with `@dnd-kit` for robust, accessible drag-and-drop:
+
+```typescript
+// Multi-context sorting support
+const handleDragEnd = (event: DragEndEvent) => {
+  // Action from library to step
+  if (activeId.startsWith("action-") && overId.startsWith("step-")) {
+    // Add action to step
+  }
+  
+  // Step reordering in flow
+  if (!activeId.startsWith("action-") && !overId.startsWith("step-")) {
+    // Reorder steps
+  }
+  
+  // Action reordering within step
+  if (!activeId.startsWith("action-") && !overId.startsWith("step-")) {
+    // Reorder actions in step
+  }
+};
+```
+
+### Plugin Integration (Registry-Centric)
+Actions are loaded dynamically from multiple sources with provenance & version retention:
+
+```typescript
+class ActionRegistry {
+  async loadCoreActions() {
+    // Load from hristudio-core/plugins/
+    const coreActionSets = ["wizard-actions", "control-flow", "observation"];
+    // Process and register actions
+  }
+  
+  loadPluginActions(studyId: string, studyPlugins: Array<{plugin: any}>) {
+    // Load robot-specific actions from study plugins
+    // Map parameter schemas to form controls
+  }
+}
+```
+
+### Database & Execution Conversion
+Two-layer conversion:
+1. Visual design → DB steps/actions with provenance & execution metadata
+2. Visual design → Compiled execution graph (normalized actions + transport summary + integrity hash)
+
+```typescript
+function convertStepsToDatabase(steps: ExperimentStep[]): ConvertedStep[] {
+  return steps.map((step, index) => ({
+    name: step.name,
+    type: mapStepTypeToDatabase(step.type),
+    orderIndex: index,
+    conditions: step.trigger.conditions,
+    actions: step.actions.map((action, actionIndex) => ({
+      name: action.name,
+      type: action.type,
+      orderIndex: actionIndex,
+      parameters: action.parameters,
+    })),
+  }));
+}
+```
+
+## Validation & Hash Drift Handling
+A validation workflow now surfaces structural integrity + reproducibility signals:
+
+### Validation Endpoint
+- `experiments.validateDesign` returns:
+  - `valid` + `issues[]`
+  - `integrityHash` (deterministic structural hash from compiled execution graph)
+  - `pluginDependencies` (sorted, namespaced with versions)
+  - Execution summary (steps/actions/transport mix)
+
+### Drift Detection (Client-Side)
+- Local state caches: `lastValidatedHash` + serialized design snapshot
+- Drift conditions:
+  1. Stored experiment `integrityHash` ≠ last validated hash
+  2. Design snapshot changed since last validation (structural or param changes)
+- Badge States:
+  - `Validated` (green outline): design unchanged since last validation and matches stored hash
+  - `Drift` (destructive): mismatch or post-validation edits
+  - `Unvalidated`: no validation performed yet
+
+### Rationale
+- Encourages explicit revalidation after structural edits
+- Prevents silent divergence from compiled execution artifact
+- Future: differentiate structural vs param-only drift (hash currently parameter-key-based)
+
+### Planned Enhancements
+- Hash stability tuning (exclude mutable free-text values if needed)
+- Inline warnings on mutated steps/actions
+- Optional auto-validate on save (configurable)
+
+## Plugin System Integration
+
+### Core Actions
+Loaded from `hristudio-core/plugins/` repositories:
+- **wizard-actions.json**: Wizard speech, gestures, instructions
+- **control-flow.json**: Wait, conditional logic, loops
+- **observation.json**: Behavioral coding, data collection, measurements
+
+### Robot Actions
+Dynamically loaded based on study configuration:
+- Robot-specific actions from plugin repositories
+- Parameter schemas automatically converted to form controls
+- Platform-specific validation and constraints
+
+### Fallback System
+Essential actions available even if plugin loading fails:
+- Basic wizard speech and gesture actions
+- Core control flow (wait, conditional)
+- Simple observation and data collection
+
+## Example Usage
+
+### Creating an Experiment
+1. **Add Steps**: Click "Add Step" to create containers in the experiment flow
+2. **Configure Steps**: Set name, type (sequential/parallel/conditional/loop), triggers
+3. **Drag Actions**: Drag from categorized library into step drop zones
+4. **Edit Properties**: Click actions to immediately edit parameters
+5. **Reorder**: Drag steps in flow, drag actions within steps
+6. **Save**: Direct conversion to database step/action records (provenance & execution metadata persisted)
+
+### Visual Workflow
+```
+Action Library          Experiment Flow              Properties
+┌─────────────┐        ┌──────────────────┐         ┌─────────────┐
+│ [Wizard]    │        │ Step 1: Welcome  │         │ Action:     │
+│ [Robot]     │ -----> │ ├ Wizard Says    │ ------> │ Wizard Says │
+│ [Control]   │        │ ├ Wait 2s        │         │ Text: ...   │
+│ [Observe]   │        │ └ Observe        │         │ Tone: ...   │
+└─────────────┘        └──────────────────┘         └─────────────┘
+```
+
+## Benefits
+
+### For Researchers
+- **Intuitive Design**: Natural workflow matching experimental thinking
+- **Visual Clarity**: Clear step-by-step experiment structure
+- **Plugin Integration**: Access to full ecosystem of robot platforms
+- **Direct Editing**: No complex nested selections required
+
+### For System Architecture
+- **Clean Separation**: Visual design vs execution logic clearly separated
+- **Database Integrity**: Direct 1:1 mapping maintains relationships
+- **Plugin Extensibility**: Easy integration of new robot platforms
+- **Type Safety**: Complete TypeScript integration throughout
+
+### For Development
+- **Maintainable Code**: Clean component architecture with clear responsibilities
+- **Performance**: Efficient rendering with proper React patterns
+- **Error Handling**: Graceful degradation when plugins fail
+- **Accessibility**: Built on accessible `@dnd-kit` foundation
+
+## Modular Architecture Summary
+| Module | Responsibility | Notes |
+|--------|----------------|-------|
+| `BlockDesigner.tsx` | Orchestration (state, save, validation, drift badges) | Thin controller after refactor |
+| `ActionRegistry.ts` | Core + plugin action loading, provenance, fallback | Stateless across renders (singleton) |
+| `ActionLibrary.tsx` | Categorized draggable palette | Performance-isolated |
+| `StepFlow.tsx` | Sortable steps & actions, structural UI | No parameter logic |
+| `PropertiesPanel.tsx` | Parameter + metadata editing (enhanced controls) | Switch + Slider integration |
+
+## Future Enhancements
+
+### Planned Features (Updated Roadmap)
+- **Step Templates**: Reusable step patterns for common workflows
+- **Visual Debugging**: Inline structural + provenance validation markers
+- **Collaborative Editing**: Real-time multi-user design sessions
+- **Advanced Conditionals**: Branching logic & guard editors (visual condition builder)
+- **Structural Drift Granularity**: Distinguish param-value vs structural changes
+- **Version Pin Diffing**: Detect plugin version upgrades vs design-pinned versions
+
+### Integration Opportunities
+- **Version Control**: Track experiment changes across iterations
+- **A/B Testing**: Support for experimental variations within single design
+- **Analytics Integration**: Step-level performance monitoring
+- **Export Formats**: Convert to external workflow systems
+
+This redesigned experiment designer now combines step-based structure, provenance tracking, transport-aware execution compilation, integrity hashing, and validation workflows to deliver reproducible, extensible, and transparent experimental protocols.

docs/_archive/feature-requirements.md

@@ -0,0 +1,609 @@
+# HRIStudio Feature Requirements
+
+## Overview
+
+This document provides detailed feature requirements for HRIStudio, organized by functional areas. Each feature includes user stories, acceptance criteria, and technical implementation notes.
+
+## 1. Authentication and User Management
+
+### 1.1 User Registration
+
+**User Story**: As a new researcher, I want to create an account so that I can start using HRIStudio for my studies.
+
+**Functional Requirements**:
+- Support email/password registration
+- Support OAuth providers (Google, GitHub, Microsoft)
+- Email verification required before account activation
+- Capture user's name and institution during registration
+- Password strength requirements enforced
+- Prevent duplicate email registrations
+
+**Acceptance Criteria**:
+- [ ] User can register with valid email and strong password
+- [ ] Email verification sent within 1 minute
+- [ ] OAuth registration creates account with verified email
+- [ ] Appropriate error messages for validation failures
+- [ ] Account creation logged in audit trail
+
+**Technical Notes**:
+- Use NextAuth.js v5 for authentication
+- Store hashed passwords using bcrypt
+- Implement rate limiting on registration endpoint
+
+### 1.2 User Login
+
+**User Story**: As a registered user, I want to log in securely so that I can access my studies.
+
+**Functional Requirements**:
+- Support email/password login
+- Support OAuth login
+- Remember me functionality
+- Session timeout after inactivity
+- Multiple device login support
+- Failed login attempt tracking
+
+**Acceptance Criteria**:
+- [ ] Successful login redirects to dashboard
+- [ ] Failed login shows appropriate error
+- [ ] Session persists based on remember me selection
+- [ ] Account locked after 5 failed attempts
+- [ ] OAuth login works seamlessly
+
+### 1.3 Role Management
+
+**User Story**: As an administrator, I want to assign system roles to users so that they have appropriate permissions.
+
+**Functional Requirements**:
+- Four system roles: Administrator, Researcher, Wizard, Observer
+- Role assignment by administrators only
+- Role changes take effect immediately
+- Role history maintained
+- Bulk role assignment support
+
+**Acceptance Criteria**:
+- [ ] Admin can view all users and their roles
+- [ ] Admin can change user roles
+- [ ] Role changes logged in audit trail
+- [ ] Users see appropriate UI based on role
+- [ ] Cannot remove last administrator
+
+## 2. Study Management
+
+### 2.1 Study Creation
+
+**User Story**: As a researcher, I want to create a new study so that I can organize my experiments.
+
+**Functional Requirements**:
+- Create study with name and description
+- Optional IRB protocol number
+- Institution association
+- Auto-assign creator as study owner
+- Study status tracking (draft, active, completed, archived)
+- Rich metadata support
+
+**Acceptance Criteria**:
+- [ ] Study created with unique identifier
+- [ ] Creator has full permissions on study
+- [ ] Study appears in user's study list
+- [ ] Can edit study details after creation
+- [ ] Study creation logged
+
+### 2.2 Team Collaboration
+
+**User Story**: As a study owner, I want to add team members so that we can collaborate on the research.
+
+**Functional Requirements**:
+- Add users by email with specific role
+- Study-specific roles: Owner, Researcher, Wizard, Observer
+- Email invitations for non-registered users
+- Permission customization per member
+- Member removal capability
+- Transfer ownership functionality
+
+**Acceptance Criteria**:
+- [ ] Can add existing users immediately
+- [ ] Invitations sent to new users
+- [ ] Members see study in their dashboard
+- [ ] Permissions enforced throughout app
+- [ ] Activity log shows member changes
+
+### 2.3 Study Dashboard
+
+**User Story**: As a study member, I want to see study progress at a glance so that I can track our research.
+
+**Functional Requirements**:
+- Overview of experiments and trials
+- Recent activity timeline
+- Team member list with online status
+- Upcoming scheduled trials
+- Quick statistics (participants, completion rate)
+- Document repository access
+
+**Acceptance Criteria**:
+- [ ] Dashboard loads within 2 seconds
+- [ ] Real-time updates for trial status
+- [ ] Click-through to detailed views
+- [ ] Responsive design for mobile
+- [ ] Export study summary report
+
+## 3. Experiment Design
+
+### 3.1 Visual Experiment Designer
+
+**User Story**: As a researcher, I want to design experiments visually so that I don't need programming skills.
+
+**Functional Requirements**:
+- Drag-and-drop interface for steps
+- Step types: Wizard, Robot, Parallel, Conditional
+- Action library based on robot capabilities
+- Parameter configuration panels
+- Visual flow representation
+- Undo/redo functionality
+- Auto-save while designing
+- Version control for designs
+
+**Acceptance Criteria**:
+- [ ] Can create experiment without code
+- [ ] Visual representation matches execution flow
+- [ ] Validation prevents invalid configurations
+- [ ] Can preview experiment flow
+- [ ] Changes saved automatically
+- [ ] Can revert to previous versions
+
+### 3.2 Step Configuration
+
+**User Story**: As a researcher, I want to configure each step in detail so that the experiment runs correctly.
+
+**Functional Requirements**:
+- Name and description for each step
+- Duration estimates
+- Required vs optional steps
+- Conditional logic support
+- Parameter validation
+- Help text and examples
+- Copy/paste steps between experiments
+
+**Acceptance Criteria**:
+- [ ] All step properties editable
+- [ ] Validation prevents invalid values
+- [ ] Conditions use intuitive UI
+- [ ] Can test conditions with sample data
+- [ ] Duration estimates aggregate correctly
+
+### 3.3 Action Management
+
+**User Story**: As a researcher, I want to add specific actions to steps so that the robot and wizard know what to do.
+
+**Functional Requirements**:
+- Action types based on robot plugin
+- Wizard instruction actions
+- Robot command actions
+- Data collection actions
+- Wait/delay actions
+- Parameter configuration per action
+- Action validation
+- Quick action templates
+
+**Acceptance Criteria**:
+- [ ] Actions appropriate to step type
+- [ ] Parameters validated in real-time
+- [ ] Can reorder actions within step
+- [ ] Action execution time estimates
+- [ ] Templates speed up common tasks
+
+### 3.4 Experiment Validation
+
+**User Story**: As a researcher, I want to validate my experiment before running trials so that I can catch errors early.
+
+**Functional Requirements**:
+- Automatic validation on save
+- Manual validation trigger
+- Check robot compatibility
+- Verify parameter completeness
+- Estimate total duration
+- Identify potential issues
+- Suggest improvements
+
+**Acceptance Criteria**:
+- [ ] Validation completes within 5 seconds
+- [ ] Clear error messages with fixes
+- [ ] Warnings for non-critical issues
+- [ ] Can run validation without saving
+- [ ] Validation status clearly shown
+
+## 4. Robot Integration
+
+### 4.1 Plugin Management
+
+**User Story**: As a researcher, I want to install robot plugins so that I can use different robots in my studies.
+
+**Functional Requirements**:
+- Browse available plugins
+- Filter by robot type and trust level
+- View plugin details and documentation
+- One-click installation
+- Configuration interface
+- Version management
+- Plugin updates notifications
+
+**Acceptance Criteria**:
+- [ ] Plugin store loads quickly
+- [ ] Can search and filter plugins
+- [ ] Installation completes without errors
+- [ ] Configuration validated
+- [ ] Can uninstall plugins cleanly
+
+### 4.2 Robot Communication
+
+**User Story**: As a system, I need to communicate with robots reliably so that experiments run smoothly.
+
+**Functional Requirements**:
+- Support REST, ROS2, and custom protocols
+- Connection health monitoring
+- Automatic reconnection
+- Command queuing
+- Response timeout handling
+- Error recovery
+- Latency tracking
+
+**Acceptance Criteria**:
+- [ ] Commands sent within 100ms
+- [ ] Connection status visible
+- [ ] Graceful handling of disconnections
+- [ ] Commands never lost
+- [ ] Errors reported clearly
+
+### 4.3 Action Translation
+
+**User Story**: As a system, I need to translate abstract actions to robot commands so that experiments work across platforms.
+
+**Functional Requirements**:
+- Map abstract actions to robot-specific commands
+- Parameter transformation
+- Capability checking
+- Fallback behaviors
+- Success/failure detection
+- State synchronization
+
+**Acceptance Criteria**:
+- [ ] Translations happen transparently
+- [ ] Incompatible actions prevented
+- [ ] Clear error messages
+- [ ] Robot state tracked accurately
+- [ ] Performance overhead < 50ms
+
+## 5. Trial Execution
+
+### 5.1 Trial Scheduling
+
+**User Story**: As a researcher, I want to schedule trials in advance so that participants and wizards can plan.
+
+**Functional Requirements**:
+- Calendar interface for scheduling
+- Participant assignment
+- Wizard assignment
+- Email notifications
+- Schedule conflict detection
+- Recurring trial support
+- Time zone handling
+
+**Acceptance Criteria**:
+- [ ] Can schedule weeks in advance
+- [ ] Notifications sent automatically
+- [ ] No double-booking possible
+- [ ] Can reschedule easily
+- [ ] Calendar syncs with external tools
+
+### 5.2 Wizard Interface
+
+**User Story**: As a wizard, I want an intuitive interface during trials so that I can focus on the participant.
+
+**Functional Requirements**:
+- Step-by-step guidance
+- Current instruction display
+- Live video feed
+- Quick action buttons
+- Emergency stop
+- Note-taking ability
+- Progress indicator
+- Intervention logging
+
+**Acceptance Criteria**:
+- [ ] Interface loads in < 3 seconds
+- [ ] Video feed has < 500ms latency
+- [ ] All controls easily accessible
+- [ ] Can operate with keyboard only
+- [ ] Notes saved automatically
+
+### 5.3 Real-time Execution
+
+**User Story**: As a wizard, I need real-time control so that I can respond to participant behavior.
+
+**Functional Requirements**:
+- WebSocket connection for updates
+- < 100ms command latency
+- Synchronized state management
+- Offline capability with sync
+- Concurrent observer support
+- Event stream recording
+- Bandwidth optimization
+
+**Acceptance Criteria**:
+- [ ] Commands execute immediately
+- [ ] State synchronized across clients
+- [ ] Observers see same view
+- [ ] Works on 4G connection
+- [ ] No data loss on disconnect
+
+### 5.4 Data Capture
+
+**User Story**: As a researcher, I want all trial data captured automatically so that nothing is lost.
+
+**Functional Requirements**:
+- Video recording (configurable quality)
+- Audio recording
+- Event timeline capture
+- Robot sensor data
+- Wizard actions/interventions
+- Participant responses
+- Automatic uploads
+- Encryption for sensitive data
+
+**Acceptance Criteria**:
+- [ ] All data streams captured
+- [ ] Minimal frame drop rate
+- [ ] Uploads complete within 5 min
+- [ ] Data encrypted at rest
+- [ ] Can verify data integrity
+
+## 6. Participant Management
+
+### 6.1 Participant Registration
+
+**User Story**: As a researcher, I want to register participants so that I can track their involvement.
+
+**Functional Requirements**:
+- Anonymous participant codes
+- Optional demographic data
+- Consent form integration
+- Contact information (encrypted)
+- Study assignment
+- Participation history
+- GDPR compliance tools
+
+**Acceptance Criteria**:
+- [ ] Unique codes generated
+- [ ] PII encrypted in database
+- [ ] Can export participant data
+- [ ] Consent status tracked
+- [ ] Right to deletion supported
+
+### 6.2 Consent Management
+
+**User Story**: As a researcher, I want to manage consent forms so that ethical requirements are met.
+
+**Functional Requirements**:
+- Create consent form templates
+- Version control for forms
+- Digital signature capture
+- PDF generation
+- Multi-language support
+- Audit trail
+- Withdrawal handling
+
+**Acceptance Criteria**:
+- [ ] Forms legally compliant
+- [ ] Signatures timestamped
+- [ ] PDFs generated automatically
+- [ ] Can track consent status
+- [ ] Withdrawal process clear
+
+## 7. Data Analysis
+
+### 7.1 Playback Interface
+
+**User Story**: As a researcher, I want to review trial recordings so that I can analyze participant behavior.
+
+**Functional Requirements**:
+- Synchronized playback of all streams
+- Variable playback speed
+- Frame-by-frame navigation
+- Event timeline overlay
+- Annotation tools
+- Bookmark important moments
+- Export clips
+
+**Acceptance Criteria**:
+- [ ] Smooth playback at 1080p
+- [ ] All streams synchronized
+- [ ] Can jump to any event
+- [ ] Annotations saved in real-time
+- [ ] Clips export in standard formats
+
+### 7.2 Annotation System
+
+**User Story**: As a researcher, I want to annotate trials so that I can code behaviors and events.
+
+**Functional Requirements**:
+- Time-based annotations
+- Categorization system
+- Tag support
+- Multi-coder support
+- Inter-rater reliability
+- Annotation templates
+- Bulk annotation tools
+
+**Acceptance Criteria**:
+- [ ] Can annotate while playing
+- [ ] Categories customizable
+- [ ] Can compare coder annotations
+- [ ] Export annotations as CSV
+- [ ] Search annotations easily
+
+### 7.3 Data Export
+
+**User Story**: As a researcher, I want to export data so that I can analyze it in external tools.
+
+**Functional Requirements**:
+- Multiple export formats (CSV, JSON, SPSS)
+- Selective data export
+- Anonymization options
+- Batch export
+- Scheduled exports
+- API access
+- R/Python integration examples
+
+**Acceptance Criteria**:
+- [ ] Exports complete within minutes
+- [ ] Data properly formatted
+- [ ] Anonymization verified
+- [ ] Can automate exports
+- [ ] Documentation provided
+
+## 8. System Administration
+
+### 8.1 User Management
+
+**User Story**: As an administrator, I want to manage all users so that the system remains secure.
+
+**Functional Requirements**:
+- User search and filtering
+- Bulk operations
+- Activity monitoring
+- Access logs
+- Password resets
+- Account suspension
+- Usage statistics
+
+**Acceptance Criteria**:
+- [ ] Can find users quickly
+- [ ] Bulk operations reversible
+- [ ] Activity logs comprehensive
+- [ ] Can force password reset
+- [ ] Usage reports exportable
+
+### 8.2 System Configuration
+
+**User Story**: As an administrator, I want to configure system settings so that it meets our needs.
+
+**Functional Requirements**:
+- Storage configuration
+- Email settings
+- Security policies
+- Backup schedules
+- Plugin management
+- Performance tuning
+- Feature flags
+
+**Acceptance Criteria**:
+- [ ] Changes take effect immediately
+- [ ] Configuration backed up
+- [ ] Can test settings safely
+- [ ] Rollback capability
+- [ ] Changes logged
+
+### 8.3 Monitoring and Maintenance
+
+**User Story**: As an administrator, I want to monitor system health so that I can prevent issues.
+
+**Functional Requirements**:
+- Real-time metrics dashboard
+- Alert configuration
+- Log aggregation
+- Performance metrics
+- Storage usage tracking
+- Backup verification
+- Update management
+
+**Acceptance Criteria**:
+- [ ] Metrics update in real-time
+- [ ] Alerts sent within 1 minute
+- [ ] Logs searchable
+- [ ] Can identify bottlenecks
+- [ ] Updates tested before deploy
+
+## 9. Mobile Support
+
+### 9.1 Responsive Web Design
+
+**User Story**: As a user, I want to access HRIStudio on my tablet so that I can work anywhere.
+
+**Functional Requirements**:
+- Responsive layouts for all pages
+- Touch-optimized controls
+- Offline capability for critical features
+- Reduced data usage mode
+- Native app features via PWA
+- Biometric authentication
+
+**Acceptance Criteria**:
+- [ ] Works on tablets and large phones
+- [ ] Touch targets appropriately sized
+- [ ] Can work offline for 1 hour
+- [ ] PWA installable
+- [ ] Performance acceptable on 4G
+
+## 10. Integration and APIs
+
+### 10.1 External Tool Integration
+
+**User Story**: As a researcher, I want to integrate with analysis tools so that I can use my preferred software.
+
+**Functional Requirements**:
+- RESTful API with authentication
+- GraphQL endpoint for complex queries
+- Webhook support for events
+- OAuth provider capability
+- SDK for common languages
+- OpenAPI documentation
+
+**Acceptance Criteria**:
+- [ ] API response time < 200ms
+- [ ] Rate limiting implemented
+- [ ] Webhooks reliable
+- [ ] SDKs well documented
+- [ ] Breaking changes versioned
+
+## Non-Functional Requirements
+
+### Performance
+- Page load time < 2 seconds
+- API response time < 200ms (p95)
+- Support 100 concurrent users
+- Video streaming at 1080p30fps
+- Database queries < 100ms
+
+### Security
+- OWASP Top 10 compliance
+- Data encryption at rest and in transit
+- Regular security audits
+- Penetration testing
+- GDPR and HIPAA compliance options
+
+### Scalability
+- Horizontal scaling capability
+- Database sharding ready
+- CDN for media delivery
+- Microservices architecture ready
+- Multi-region deployment support
+
+### Reliability
+- High uptime SLA
+- Automated backups every 4 hours
+- Disaster recovery plan
+- Data replication
+- Graceful degradation
+
+### Usability
+- WCAG 2.1 AA compliance
+- Multi-language support
+- Comprehensive help documentation
+- In-app tutorials
+- Context-sensitive help
+
+### Maintainability
+- Comprehensive test coverage
+- Automated deployment pipeline
+- Monitoring and alerting
+- Clear error messages
+- Modular architecture

docs/_archive/flow-designer-connections.md

@@ -0,0 +1,310 @@
+# Flow Designer Connections & Ordering System
+
+## Overview
+
+The HRIStudio Flow Designer uses React Flow to provide an intuitive visual interface for connecting and ordering experiment steps. This document explains how the connection system works and why React Flow is the optimal choice for this functionality.
+
+## Why React Flow?
+
+### ✅ **Advantages of React Flow**
+
+1. **Visual Clarity**: Users can see the experiment flow at a glance
+2. **Intuitive Interaction**: Drag-and-drop connections feel natural
+3. **Professional UI**: Industry-standard flow editor interface
+4. **Flexible Layouts**: Non-linear arrangements for complex experiments
+5. **Real-time Feedback**: Immediate visual confirmation of connections
+6. **Zoom & Pan**: Handle large, complex experiments easily
+7. **Accessibility**: Built-in keyboard navigation and screen reader support
+
+### 🔄 **Alternative Approaches Considered**
+
+| Approach | Pros | Cons | Verdict |
+|----------|------|------|---------|
+| **List-based ordering** | Simple to implement | Limited to linear flows | ❌ Too restrictive |
+| **Tree structure** | Good for hierarchies | Complex for parallel flows | ❌ Not flexible enough |
+| **Graph-based UI** | Very flexible | Higher learning curve | ⚠️ React Flow provides this |
+| **Timeline interface** | Good for time-based flows | Poor for conditional logic | ❌ Wrong metaphor |
+
+**Conclusion**: React Flow provides the best balance of power, usability, and visual clarity.
+
+## Connection System
+
+### 🔗 **How Connections Work**
+
+#### **1. Visual Connection Handles**
+```typescript
+// Each step node has input/output handles
+<Handle
+  type="target"
+  position={Position.Left}
+  className="!bg-primary !border-background !h-3 !w-3 !border-2"
+  id="input"
+/>
+<Handle
+  type="source"
+  position={Position.Right}
+  className="!bg-primary !border-background !h-3 !w-3 !border-2"
+  id="output"
+/>
+```
+
+#### **2. Connection Logic**
+- **Source Handle**: Right side of each step (output)
+- **Target Handle**: Left side of each step (input)
+- **Visual Feedback**: Handles highlight during connection attempts
+- **Theme Integration**: Handles use `!bg-primary` for consistent theming
+
+#### **3. Auto-Positioning**
+When steps are connected, the system automatically adjusts positions:
+```typescript
+const handleConnect = useCallback((params: Connection) => {
+  // Automatically position target step to the right of source
+  const updatedPosition = {
+    x: Math.max(sourceStep.position.x + 300, step.position.x),
+    y: step.position.y,
+  };
+});
+```
+
+### 📋 **Connection Rules**
+
+1. **One Input per Step**: Each step can have multiple inputs but should logically follow one primary path
+2. **Multiple Outputs**: Steps can connect to multiple subsequent steps (for parallel or conditional flows)
+3. **No Circular Dependencies**: System prevents creating loops that could cause infinite execution
+4. **Automatic Spacing**: Connected steps maintain minimum 300px horizontal spacing
+
+## Ordering System
+
+### 🔢 **How Ordering Works**
+
+#### **1. Position-Based Ordering**
+```typescript
+// Steps are ordered based on X position (left to right)
+const sortedSteps = [...design.steps].sort(
+  (a, b) => a.position.x - b.position.x
+);
+```
+
+#### **2. Auto-Connection Logic**
+```typescript
+// Automatically connect steps that are close horizontally
+const distance = Math.abs(targetStep.position.x - sourceStep.position.x);
+if (distance < 400) {
+  // Create automatic connection
+}
+```
+
+#### **3. Manual Reordering**
+- **Drag Steps**: Users can drag steps to reposition them
+- **Visual Feedback**: Connections update in real-time
+- **Smart Snapping**: 20px grid snapping for clean alignment
+
+### 🎯 **Ordering Strategies**
+
+#### **Linear Flow** (Most Common)
+```
+[Start] → [Step 1] → [Step 2] → [Step 3] → [End]
+```
+- Simple left-to-right arrangement
+- Auto-connection between adjacent steps
+- Perfect for basic experimental protocols
+
+#### **Parallel Flow** (Advanced)
+```
+[Start] → [Parallel] → [Step A]
+                    → [Step B] → [Merge] → [End]
+```
+- Multiple paths from one step
+- Useful for simultaneous robot/wizard actions
+- Visual branching with clear convergence points
+
+#### **Conditional Flow** (Complex)
+```
+[Start] → [Decision] → [Path A] → [End A]
+                    → [Path B] → [End B]
+```
+- Branching based on conditions
+- Different outcomes based on participant responses
+- Clear visual representation of decision points
+
+## User Interaction Guide
+
+### 🖱️ **Connecting Steps**
+
+1. **Hover over Source Handle**: Right side of a step highlights
+2. **Click and Drag**: Start connection from source handle
+3. **Drop on Target Handle**: Left side of destination step
+4. **Visual Confirmation**: Animated line appears between steps
+5. **Auto-Positioning**: Target step repositions if needed
+
+### ⌨️ **Keyboard Shortcuts**
+
+| Shortcut | Action |
+|----------|--------|
+| `Delete` | Delete selected step/connection |
+| `Ctrl/Cmd + D` | Duplicate selected step |
+| `Ctrl/Cmd + Z` | Undo last action |
+| `Ctrl/Cmd + Y` | Redo last action |
+| `Space + Drag` | Pan canvas |
+| `Ctrl/Cmd + Scroll` | Zoom in/out |
+
+### 🎨 **Visual Feedback**
+
+#### **Connection States**
+- **Default**: Muted gray lines (`stroke: hsl(var(--muted-foreground))`)
+- **Animated**: Flowing dashes during execution
+- **Hover**: Highlighted with primary color
+- **Selected**: Thicker stroke with selection indicators
+
+#### **Handle States**
+- **Default**: Primary color background
+- **Hover**: Pulsing animation
+- **Connecting**: Enlarged with glow effect
+- **Invalid Target**: Red color with error indication
+
+## Technical Implementation
+
+### 🔧 **React Flow Configuration**
+
+```typescript
+<ReactFlow
+  nodes={nodes}
+  edges={edges}
+  nodeTypes={nodeTypes}
+  connectionLineType="smoothstep"
+  snapToGrid={true}
+  snapGrid={[20, 20]}
+  defaultEdgeOptions={{
+    type: "smoothstep",
+    animated: true,
+    style: { strokeWidth: 2 },
+  }}
+  onConnect={handleConnect}
+  onNodesChange={handleNodesChange}
+/>
+```
+
+### 🎨 **Theme Integration**
+
+```css
+/* Custom theming for React Flow components */
+.react-flow__handle {
+  background-color: hsl(var(--primary));
+  border: 2px solid hsl(var(--background));
+}
+
+.react-flow__edge-path {
+  stroke: hsl(var(--muted-foreground));
+  stroke-width: 2;
+}
+
+.react-flow__connection-line {
+  stroke: hsl(var(--primary));
+  stroke-dasharray: 5;
+}
+```
+
+### 📊 **Data Structure**
+
+```typescript
+interface FlowDesign {
+  id: string;
+  name: string;
+  steps: FlowStep[];
+  version: number;
+}
+
+interface FlowStep {
+  id: string;
+  type: StepType;
+  name: string;
+  position: { x: number; y: number };
+  actions: FlowAction[];
+}
+
+// Connections are implicit through React Flow edges
+interface Edge {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle: string;
+  targetHandle: string;
+}
+```
+
+## Best Practices
+
+### 🎯 **For Researchers**
+
+1. **Start Simple**: Begin with linear flows, add complexity gradually
+2. **Clear Naming**: Use descriptive step names that explain their purpose
+3. **Logical Flow**: Arrange steps left-to-right in execution order
+4. **Group Related Steps**: Use visual proximity for related actions
+5. **Test Connections**: Verify flow logic before running trials
+
+### 🛠️ **For Developers**
+
+1. **Handle Edge Cases**: Validate connections to prevent loops
+2. **Performance**: Optimize for large flows (100+ steps)
+3. **Accessibility**: Ensure keyboard navigation works properly
+4. **Mobile Support**: Test touch interactions on tablets
+5. **Error Recovery**: Graceful handling of malformed flows
+
+## Advanced Features
+
+### 🔮 **Future Enhancements**
+
+#### **Smart Auto-Layout**
+- Automatic optimal positioning of connected steps
+- Hierarchical layout algorithms for complex flows
+- Conflict resolution for overlapping connections
+
+#### **Connection Types**
+- **Sequential**: Normal step-to-step execution
+- **Conditional**: Based on runtime conditions
+- **Parallel**: Simultaneous execution paths
+- **Loop**: Repeat sections based on criteria
+
+#### **Visual Enhancements**
+- **Step Previews**: Hover to see step details
+- **Execution Trace**: Visual playback of completed trials
+- **Error Highlighting**: Red indicators for problematic connections
+- **Performance Metrics**: Timing information on connections
+
+## Troubleshooting
+
+### ❓ **Common Issues**
+
+#### **Steps Won't Connect**
+- Check that handles are properly positioned
+- Ensure no circular dependencies
+- Verify both nodes are valid connection targets
+
+#### **Connections Disappear**
+- May indicate data consistency issues
+- Check that both source and target steps exist
+- Verify connection IDs are unique
+
+#### **Poor Performance**
+- Large flows (50+ steps) may need optimization
+- Consider pagination or virtualization
+- Check for memory leaks in event handlers
+
+### 🔧 **Debug Tools**
+
+```typescript
+// Enable React Flow debug mode
+const DEBUG_MODE = process.env.NODE_ENV === 'development';
+
+<ReactFlow
+  {...props}
+  onError={DEBUG_MODE ? console.error : undefined}
+  onInit={DEBUG_MODE ? console.log : undefined}
+/>
+```
+
+## Conclusion
+
+The React Flow-based connection system provides HRIStudio with a professional, intuitive interface for designing complex experimental workflows. The combination of visual clarity, flexible layout options, and robust connection handling makes it the ideal solution for HRI researchers who need to create sophisticated experimental protocols.
+
+The system successfully balances ease of use for simple linear experiments with the power needed for complex branching and parallel execution flows, making it suitable for researchers at all skill levels.

docs/_archive/paper.md

@@ -0,0 +1,694 @@
+# Introduction
+
+Human-robot interaction (HRI) is an essential field of study for
+understanding how robots should communicate, collaborate, and coexist
+with people. The development of autonomous behaviors in social robot
+applications, however, offers a number of challenges. The Wizard-of-Oz
+(WoZ) technique has emerged as a valuable experimental paradigm to
+address these difficulties, as it allows experimenters to simulate a
+robot's autonomous behaviors. With WoZ, a human operator (the
+*"wizard"*) can operate the robot remotely, essentially simulating its
+autonomous behavior during user studies. This enables the rapid
+prototyping and continuous refinement of human-robot interactions
+postponing to later the full development of complex robot behaviors.
+
+While WoZ is a powerful paradigm, it does not eliminate all experimental
+challenges. The paradigm is centered on the wizard who must carry out
+scripted sequences of actions. Ideally, the wizard should execute their
+script identically across runs of the experiment with different
+participants. Deviations from the script in one run or another may
+change experimental conditions significantly decreasing the
+methodological rigor of the larger study. This kind of problem can be
+minimized by instrumenting the wizard with a system that prevents
+deviations from the prescribed interactions with the participant. In
+addition to the variability that can be introduced by wizard behaviors,
+WoZ studies can be undermined by technical barriers related to the use
+of specialized equipment and tools. Different robots may be controlled
+or programmed through different systems requiring expertise with a range
+of technologies such as programming languages, development environments,
+and operating systems.
+
+The elaboration and the execution of rigorous and reproducible WoZ
+experiments can be challenging for HRI researchers. Although there do
+exist solutions to support this kind of endeavor, they often rely on
+low-level robot operating systems, limited proprietary platforms, or
+require extensive custom coding, which can restrict their use to domain
+experts with extensive technical backgrounds. The development of our
+work was motivated by the desire to offer a platform that would lower
+the barriers to entry in HRI research with the WoZ paradigm.
+
+Through the literature review described in the next section, we
+identified six categories of desirables to be included in a modern
+system that streamlines the WoZ experimental process: an environment
+that integrates all the functionalities of the system; mechanisms for
+the description of WoZ experiments which require minimal to no coding
+expertise; fine grained, real-time control of scripted experimental runs
+with a variety of robotic platforms; comprehensive data collection and
+logging; a platform-agnostic approach to support a wide range of robot
+hardware; and collaborative features that allow research teams to work
+together effectively.
+
+The design and development of HRIStudio were driven by the desirables
+enumerated above and described in [@OConnor2024], our preliminary
+report. In this work, our main contribution is to demonstrate how a
+system such the one we are developing has significant potential to make
+WoZ experiments easier to carry out, more rigorous, and ultimately
+reproducible. The remainder of this paper is structured as follows. In
+Section [2](#sota){reference-type="ref" reference="sota"}, we establish
+the context for our contribution through a review of recent literature.
+In Section [3](#repchallenges){reference-type="ref"
+reference="repchallenges"}, we discuss the aspects of the WoZ paradigm
+that can lead to reproducibility challenges and in
+Section [4](#arch){reference-type="ref" reference="arch"} we propose
+solutions to address these challenges. Subsequently, in
+Section [5](#workflow){reference-type="ref" reference="workflow"}, we
+describe our solution to create a structure for the experimental
+workflow. Finally, in Section [6](#conclusion){reference-type="ref"
+reference="conclusion"}, we conclude the paper with a summary of our
+contributions, a reflection on the current state of our project, and
+directions for the future.
+
+# Assessment of the State-of-the-Art {#sota}
+
+Over the last two decades, multiple frameworks to support and automate
+the WoZ paradigm have been reported in the literature. These frameworks
+can be categorized according to how they focus on four primary areas of
+interest, which we discuss below as we expose some of the most important
+contributions to the field.
+
+## Technical Infrastructure and Architectures
+
+The foundation of any WoZ framework lies in its technical infrastructure
+and architectural design. These elements determine not only the system's
+capabilities but also its longevity and adaptability to different
+research needs. Several frameworks have focused on providing robust
+technical infrastructures for WoZ experiments.
+
+*Polonius* [@Lu2011] utilizes the modular *Robot Operating System* (ROS)
+platform as its foundation, offering a graphical user interface for
+wizards to define finite-state machine scripts that drive robot
+behaviors. A notable feature is its integrated logging system that
+eliminates the need for post-experiment video coding, allowing
+researchers to record human-robot interactions in real-time as they
+occur. Polonius was specifically designed to be accessible to
+non-programming collaborators, addressing an important accessibility gap
+in HRI research tools.
+
+*OpenWoZ* [@Hoffman2016] takes a different approach with its
+runtime-configurable framework and multi-client architecture, enabling
+evaluators to modify robot behaviors during experiments without
+interrupting the flow. This flexibility allows for dynamic adaptation to
+unexpected participant responses, though it requires programming
+expertise to create customized robot behaviors. The system's
+architecture supports distributed operation, where multiple operators
+can collaborate during an experiment.
+
+## Interface Design and User Experience
+
+The design of an interface for the wizard to control the execution of an
+experiment is important. The qualities of the interface can
+significantly impact both the quality of data collected and the
+longevity of the tool itself. *NottReal* [@Porcheron2020] exemplifies
+careful attention to interface design in its development for voice user
+interface studies. The system makes it easier for the wizard to play
+their role featuring tabbed lists of pre-scripted messages, slots for
+customization, message queuing capabilities, and comprehensive logging.
+Its visual feedback mechanisms mimic commercial voice assistants,
+providing participants with familiar interaction cues such as dynamic
+"orbs" that indicate the system is listening and processing states.
+
+*WoZ4U* [@Rietz2021] prioritizes usability with a GUI specifically
+designed to make HRI studies accessible to non-programmers. While its
+tight integration with Aldebaran's Pepper robot constrains
+generalizability, it demonstrates how specialized interfaces can lower
+barriers to entry for conducting WoZ studies with specific platforms.
+
+## Domain Specialization vs. Generalizability
+
+A key tension in WoZ framework development exists between domain
+specialization and generalizability. Some systems are designed for
+specific types of interactions or robot platforms, offering deep
+functionality within a narrow domain. Others aim for broader
+applicability across various robots and interaction scenarios,
+potentially sacrificing depth of functionalities for breadth.
+
+Pettersson and Wik's [@Pettersson2015] systematic review identified this
+tension as central to the longevity of WoZ tools, that is, their ability
+to remain operational despite changes in underlying technologies. Their
+analysis of 24 WoZ systems revealed that most general-purpose tools have
+a lifespan of only 2-3 years. Their own tool, Ozlab, achieved
+exceptional longevity (15+ years) through three factors: (1) a truly
+general-purpose approach from inception, (2) integration into HCI
+curricula ensuring institutional support, and (3) a flexible wizard
+interface design that adapts to specific experimental needs rather than
+forcing standardization.
+
+## Standardization Efforts and Methodological Approaches
+
+The tension between specialization and generalizability has led to
+increased interest in developing standardized approaches to WoZ
+experimentation. Recent efforts have focused on developing standards for
+HRI research methodology and interaction specification. Porfirio et
+al. [@Porfirio2023] proposed guidelines for an *interaction
+specification language* (ISL), emphasizing the need for standardized
+ways to define and communicate robot behaviors across different
+platforms. Their work introduces the concept of *Application Development
+Environments* (ADEs) for HRI and details how hierarchical modularity and
+formal representations can enhance the reproducibility of robot
+behaviors. These ADEs would provide structured environments for creating
+robot behaviors with varying levels of expressiveness while maintaining
+platform independence.
+
+This standardization effort addresses a critical gap identified in
+Riek's [@Riek2012] systematic analysis of published WoZ experiments.
+Riek's work revealed concerning methodological deficiencies: 24.1% of
+papers clearly described their WoZ simulation as part of an iterative
+design process, 5.4% described wizard training procedures, and 11%
+constrained what the wizard could recognize. This lack of methodological
+transparency hinders reproducibility and, therefore, scientific progress
+in the field.
+
+Methodological considerations extend beyond wizard protocols to the
+fundamental approaches in HRI evaluation. Steinfeld et
+al. [@Steinfeld2009] introduced a complementary framework to the
+traditional WoZ method, which they termed "the Oz of Wizard." While WoZ
+uses human experimenters to simulate robot capabilities, the Oz of
+Wizard approach employs simplified human models to evaluate robot
+behaviors and technologies. Their framework systematically describes
+various permutations of real versus simulated components in HRI
+experiments, establishing that both approaches serve valid research
+objectives. They contend that technological advances in HRI constitute
+legitimate research even when using simplified human models rather than
+actual participants, provided certain conditions are met. This framework
+establishes an important lesson for the development of new WoZ platforms
+like HRIStudio which must balance standardization with flexibility in
+experimental design.
+
+The interdisciplinary nature of HRI creates methodological
+inconsistencies that Belhassein et al. [@Belhassein2019] examine in
+depth. Their analysis identifies recurring challenges in HRI user
+studies: limited participant pools, insufficient reporting of wizard
+protocols, and barriers to experiment replication. They note that
+self-assessment measures like questionnaires, though commonly employed,
+often lack proper validation for HRI contexts and may not accurately
+capture the participants' experiences. Our platform's design goals align
+closely with their recommendations to combine multiple evaluation
+approaches, thoroughly document procedures, and develop validated
+HRI-specific assessment tools.
+
+Complementing these theoretical frameworks, Fraune et al. [@Fraune2022]
+provide practical methodological guidance from an HRI workshop focused
+on study design. Their work organizes expert insights into themes
+covering study design improvement, participant interaction strategies,
+management of technical limitations, and cross-field collaboration. Key
+recommendations include pre-testing with pilot participants and ensuring
+robot behaviors are perceived as intended. Their discussion of
+participant expectations and the "novelty effect\" in first-time robot
+interactions is particularly relevant for WoZ studies, as these factors
+can significantly influence experimental outcomes.
+
+## Challenges and Research Gaps
+
+Despite these advances, significant challenges remain in developing
+accessible and rigorous WoZ frameworks that can remain usable over
+non-trivial periods of time. Many existing frameworks require
+significant programming expertise, constraining their usability by
+interdisciplinary teams. While technical capabilities have advanced,
+methodological standardization lags behind, resulting in inconsistent
+experimental practices. Few platforms provide comprehensive data
+collection and sharing capabilities that enable robust meta-analyses
+across multiple studies. We are challenged to create tools that provide
+sufficient structure for reproducibility while allowing the flexibility
+needed for the pursuit of answers to diverse research questions.
+
+HRIStudio aims to address these challenges with a platform that is
+robot-agnostic, methodologically rigorous, and eminently usable by those
+with less honed technological skills. By incorporating lessons from
+previous frameworks and addressing the gaps identified in this section,
+we designed a system that supports the full lifecycle of WoZ
+experiments, from design through execution to analysis, with an emphasis
+on usability, reproducibility, and collaboration.
+
+# Reproducibility Challenges in WoZ Studies {#repchallenges}
+
+Reproducibility is a cornerstone of scientific research, yet it remains
+a significant challenge in human-robot interaction studies, particularly
+those centered on the Wizard-of-Oz methodology. Before detailing our
+platform design, we first examine the critical reproducibility issues
+that have informed our approach.
+
+The reproducibility challenges affecting many scientific fields are
+particularly acute in HRI research employing WoZ techniques. Human
+wizards may respond differently to similar situations across
+experimental trials, introducing inconsistency that undermines
+reproducibility and the integrity of collected data. Published studies
+often provide insufficient details about wizard protocols,
+decision-making criteria, and response timing, making replication by
+other researchers nearly impossible. Without standardized tools,
+research teams create custom setups that are difficult to recreate, and
+ad-hoc changes during experiments frequently go unrecorded. Different
+data collection methodologies and metrics further complicate cross-study
+comparisons.
+
+As previously discussed, Riek's [@Riek2012] systematic analysis of WoZ
+research exposed significant methodological transparency issues in the
+literature. These documented deficiencies in reporting experimental
+procedures make replication challenging, undermining the scientific
+validity of findings and slowing progress in the field as researchers
+cannot effectively build upon previous work.
+
+We have identified five key requirements for enhancing reproducibility
+in WoZ studies. First, standardized terminology and structure provide a
+common vocabulary for describing experimental components, reducing
+ambiguity in research communications. Second, wizard behavior
+formalization establishes clear guidelines for wizard actions that
+balance consistency with flexibility, enabling reproducible interactions
+while accommodating the natural variations in human-robot exchanges.
+Third, comprehensive data capture through time-synchronized recording of
+all experimental events with precise timestamps allows researchers to
+accurately analyze interaction patterns. Fourth, experiment
+specification sharing capabilities enable researchers to package and
+distribute complete experimental designs, facilitating replication by
+other teams. Finally, procedural documentation through automatic logging
+of experimental parameters and methodological details preserves critical
+information that might otherwise be omitted in publications. These
+requirements directly informed HRIStudio's architecture and design
+principles, ensuring that reproducibility is built into the platform
+rather than treated as an afterthought.
+
+# The Design and Architecture of HRIStudio {#arch}
+
+Informed by our analysis of both existing WoZ frameworks and the
+reproducibility challenges identified in the previous section, we have
+developed several guiding design principles for HRIStudio. Our primary
+goal is to create a platform that enhances the scientific rigor of WoZ
+studies while remaining accessible to researchers with varying levels of
+technical expertise. We have been drive by the goal of prioritizing
+"accessibility" in the sense that the platform should be usable by
+researchers without deep robot programming expertise so as to lower the
+barrier to entry for HRI studies. Through abstraction, users can focus
+on experimental design without getting bogged down by the technical
+details of specific robot platforms. Comprehensive data management
+enables the system to capture and store all generated data, including
+logs, audio, video, and study materials. To facilitate teamwork, the
+platform provides collaboration support through multiple user accounts,
+role-based access control, and data sharing capabilities that enable
+effective knowledge transfer while restricting access to sensitive data.
+Finally, methodological guidance is embedded throughout the platform,
+directing users toward scientifically sound practices through its design
+and documentation. These principles directly address the reproducibility
+requirements identified earlier, particularly the need for standardized
+terminology, wizard behavior formalization, and comprehensive data
+capture.
+
+We have implemented HRIStudio as a modular web application with explicit
+separation of concerns in accordance with these design principles. The
+structure of the application into client and server components creates a
+clear separation of responsibilities and functionalities. While the
+client exposes interactive elements to users, the server handles data
+processing, storage, and access control. This architecture provides a
+foundation for implementing data security through role-based interfaces
+in which different members of a team have tailored views of the same
+experimental session.
+
+As shown in Figure [1](#fig:system-architecture){reference-type="ref"
+reference="fig:system-architecture"}, the architecture consists of three
+main functional layers that work in concert to provide a comprehensive
+experimental platform. The *User Interface Layer* provides intuitive,
+browser-based interfaces for three components: an *Experiment Designer*
+with visual programming capabilities for one to specify experimental
+details, a *Wizard Interface* that grants real-time control over the
+execution of a trial, and a *Playback & Analysis* module that supports
+data exploration and visualization.
+
+The *Data Management Layer* provides database functionality to organize,
+store, and retrieve experiment definitions, metadata, and media assets
+generated throughout an experiment. Since HRIStudio is a web-based
+application, users can access this database remotely through an access
+control system that defines roles such as *researcher*, *wizard*, and
+*observer* each with appropriate capabilities and constraints. This
+fine-grained access control protects sensitive participant data while
+enabling appropriate sharing within research teams, with flexible
+deployment options either on-premise or in the cloud depending on one's
+needs. The layer enables collaboration among the parties involved in
+conducting a user study while keeping information compartmentalized and
+secure according to each party's requirements.
+
+The third major component is the *Robot Integration Layer*, which is
+responsible for translating our standardized abstractions for robot
+control to the specific commands accepted by different robot platforms.
+HRIStudio relies on the assumption that at least one of three different
+mechanisms is available for communication with a robot: a RESTful API,
+standard communication structures provided by ROS, or a plugin that is
+custom-made for that platform. The *Robot Integration Layer* serves as
+an intermediary between the *Data Management Layer* with *External
+Systems* such as robot hardware, external sensors, and analysis tools.
+This layer allows the main components of the system to remain
+"robot-agnostic" pending the identification or the creation of the
+correct communication method and changes to a configuration file.
+
+![HRIStudio's three-layer
+architecture.](assets/diagrams/system-architecture.pdf){#fig:system-architecture
+width="1\\columnwidth"}
+
+In order to facilitate the deployment of our application, we leverage
+containerization with Docker to ensure that every component of HRIStudio
+will be supported by their system dependencies on different
+environments. This is an important step toward extending the longevity
+of the tool and toward guaranteeing that experimental environments
+remain consistent across different platforms. Furthermore, it allows
+researchers to share not only experimental designs, but also their
+entire execution environment should a third party wish to reproduce an
+experimental study.
+
+# Experimental Workflow Support {#workflow}
+
+The experimental workflow in HRIStudio directly addresses the
+reproducibility challenges identified in
+Section [3](#repchallenges){reference-type="ref"
+reference="repchallenges"} by providing standardized structures,
+explicit wizard guidance, and comprehensive data capture. This section
+details how the platform's workflow components implement solutions for
+each key reproducibility requirement.
+
+## Embracing a Hierarchical Structure for WoZ Studies
+
+HRIStudio defines its own standard terminology with a hierarchical
+organization of the elements in WoZ studies as follows.
+
+- At the top level, an experiment designer defines a *study* element,
+  which comprises one or more *experiment* elements.
+
+- Each *experiment* specifies the experimental protocol for a discrete
+  subcomponent of the overall study and comprises one or more *step*
+  elements, each representing a distinct phase in the execution
+  sequence. The *experiment* functions as a parameterized template.
+
+- Defining all the parameters in an *experiment*, one creates a *trial*,
+  which is an executable instance involving a specific participant and
+  conducted under predefined conditions. The data generated by each
+  *trial* is recorded by the system so that later one can examine how
+  the experimental protocol was applied to each participant. The
+  distinction between experiment and trial enables a clear separation
+  between the abstract protocol specification and its concrete
+  instantiation and execution.
+
+- Each *step* encapsulates instructions that are meant either for the
+  wizard or for the robot thereby creating the concept of "type" for
+  this element. The *step* is a container for a sequence of one or more
+  *action* elements.
+
+- Each *action* represents a specific, atomic task for either the wizard
+  or the robot, according to the nature of the *step* element that
+  contains it. An *action* for the robot may represent commands for
+  input gathering, speech, waiting, movement, etc., and may be
+  configured by parameters specific for the *trial*.
+
+Figure [2](#fig:experiment-architecture){reference-type="ref"
+reference="fig:experiment-architecture"} illustrates this hierarchical
+structure through a fictional study. In the diagram, we see a "Social
+Robot Greeting Study" containing an experiment with a specific robot
+platform, steps containing actions, and a trial with a participant. Note
+that each trial event is a traceable record of the sequence of actions
+defined in the experiment. HRIStudio enables researchers to collect the
+same data across multiple trials while adhering to consistent
+experimental protocols and recording any reactions the wizard may inject
+into the process.
+
+![Hierarchical organization of a sample user study in
+HRIStudio.](assets/diagrams/experiment-architecture.pdf){#fig:experiment-architecture
+width="1\\columnwidth"}
+
+This standardized hierarchical structure creates a common vocabulary for
+experimental elements, eliminating ambiguity in descriptions and
+enabling clearer communication among researchers. Our approach aligns
+with the guidelines proposed by Porfirio et al. [@Porfirio2023] for an
+HRI specification language, particularly in regards to standardized
+formal representations and hierarchical modularity. Our system uses the
+formal study definitions to create comprehensive procedural
+documentation requiring no additional effort by the researcher. Beyond
+this documentation, a study definition can be shared with other
+researchers for the faithful reproduction of experiments.
+
+Figure [3](#fig:study-details){reference-type="ref"
+reference="fig:study-details"} shows how the system displays the data of
+an experimental study in progress. In this view, researchers can inspect
+summary data about the execution of a study and its trials, find a list
+of human subjects ("participants") and go on to see data and documents
+associated with them such as consent forms, find the list of teammates
+collaborating in this study ("members"), read descriptive information on
+the study ("metadata"), and inspect an audit log that records work that
+has been done toward the completion of the study ("activity").
+
+![Summary view of system data on an example
+study.](assets/mockups/study-details.png){#fig:study-details
+width="1\\columnwidth"}
+
+## Collaboration and Knowledge Sharing
+
+Experiments are reproducible when they are thoroughly documented and
+when that documentation is easily disseminated. To support this,
+HRIStudio includes features that enable collaborative experiment design
+and streamlined sharing of assets generated during experimental studies.
+The platform provides a dashboard that offers an overview of project
+status, details about collaborators, a timeline of completed and
+upcoming trials, and a list of pending tasks.
+
+As previously noted, the *Data Management Layer* incorporates a
+role-based access control system that defines distinct user roles
+aligned with specific responsibilities within a study. This role
+structure enforces a clear separation of duties and enables
+fine-grained, need-to-know access to study-related information. This
+design supports various research scenarios, including double-blind
+studies where certain team members have restricted access to
+information. The pre-defined roles are as follows:
+
+- *Administrator*, a "super user" who can manage the installation and
+  the configuration of the system,
+
+- *Researcher*, a user who can create and configure studies and
+  experiments,
+
+- *Observer*, a user role with read-only access, allowing inspection of
+  experiment assets and real-time monitoring of experiment execution,
+  and
+
+- *Wizard*, a user role that allows one to execute an experiment.
+
+For maximum flexibility, the system allows additional roles with
+different sets of permissions to be created by the administrator as
+needed.
+
+The collaboration system allows multiple researchers to work together on
+experiment designs, review each other's work, and build shared knowledge
+about effective methodologies. This approach also enables the packaging
+and dissemination of complete study materials, including experimental
+designs, configuration parameters, collected data, and analysis results.
+By making all aspects of the research process shareable, HRIStudio
+facilitates replication studies and meta-analyses, enhancing the
+cumulative nature of scientific knowledge in HRI.
+
+## Visual Experiment Design
+
+HRIStudio implements an *Experiment Development Environment* (EDE) that
+builds on Porfirio et al.'s [@Porfirio2023] concept of Application
+Development Environment.
+Figure [4](#fig:experiment-designer){reference-type="ref"
+reference="fig:experiment-designer"} shows how this EDE is implemented
+as a visual programming, drag-and-drop canvas for sequencing steps and
+actions. In this example, we see a progression of steps ("Welcome" and
+"Robot Approach") where each step is customized with specific actions.
+Robot actions issue abstract commands, which are then translated into
+platform-specific concrete commands by components known as *plugins*,
+which are tailored to each type of robot and discussed later in this
+section.
+
+![View of experiment
+designer.](assets/mockups/experiment-designer.png){#fig:experiment-designer
+width="1\\columnwidth"}
+
+Our EDE was inspired by Choregraphe [@Pot2009] which enables researchers
+without coding expertise to build the steps and actions of an experiment
+visually as flow diagrams. The robot control components shown in the
+interface are automatically added to the inventory of options according
+to the experiment configuration, which specifies the robot to be used.
+We expect that this will make experiment design more accessible to those
+with reduced programming skills while maintaining the expressivity
+required for sophisticated studies. Conversely, to support those without
+knowledge of best practices for WoZ studies, the EDE offers contextual
+help and documentation as guidance for one to stay on the right track.
+
+## The Wizard Interface and Experiment Execution
+
+We built into HRIStudio an interface for the wizard to execute
+experiments and to interact with them in real time. In the development
+of this component, we drew on lessons from Pettersson and
+Wik's [@Pettersson2015] work on WoZ tool longevity. From them we have
+learned that a significant factor that determines the short lifespan of
+WoZ tools is the trap of a fixed, one-size-fits-all wizard interface.
+Following the principle incorporated into their Ozlab, we have
+incorporated into our framework functionality that allows the wizard
+interface to be adapted to the specific needs of each experiment. One
+can configure wizard controls and visualizations for their specific
+study, while keeping other elements of the framework unchanged.
+
+Figure [5](#fig:experiment-runner){reference-type="ref"
+reference="fig:experiment-runner"} shows the wizard interface for the
+fictional experiment "Initial Greeting Protocol." This view shows the
+current step with an instruction for the wizard that corresponds to an
+action they will carry out. These instructions are presented one at a
+time so as not to overwhelm the wizard, but one can also use the "View
+More" button when it becomes desirable to see the complete experimental
+script. The view also includes a window for the captured video feed
+showing the robot and the participant, a timestamped log of recent
+events, and various interaction controls for unscripted actions that can
+be applied in real time ("quick actions"). By following the instructions
+which are provided incrementally, the wizard is guided to execute the
+experimental procedure consistently across its different trials with
+different participants. To provide live monitoring functionalities to
+users in the role of *observer*, a similar view is presented to them
+without the controls that might interfere with the execution of an
+experiment.
+
+When a wizard initiates an action during a trial, the system executes a
+three-step process to implement the command. First, it translates the
+high-level action into specific API calls as defined by the relevant
+plugin, converting abstract experimental actions into concrete robot
+instructions. Next, the system routes these calls to the robot's control
+system through the appropriate communication channels. Finally, it
+processes any feedback received from the robot, logs this information in
+the experimental record, and updates the experiment state accordingly to
+reflect the current situation. This process ensures reliable
+communication between the wizard interface and the physical robot while
+maintaining comprehensive records of all interactions.
+
+![View of HRIStudio's wizard interface during experiment
+execution.](assets/mockups/experiment-runner.png){#fig:experiment-runner
+width="1\\columnwidth"}
+
+## Robot Platform Integration {#plugin-store}
+
+The three-step process described above relies on a modular, two-tier
+system for communication between HRIStudio and each specific robot
+platform. The EDE offers an experiment designer a number of pre-defined
+action components representing common tasks and behaviors such as robot
+movements, speech synthesis, and sensor controls. Although these
+components can accept parameters for the configuration of each action,
+they exist at a higher level of abstraction. When actions are executed,
+the system translates these abstractions so that they match the commands
+accepted by the robot selected for the experiment. This translation is
+achieved by a *plugin* for the specific robot, which serves as the
+communication channel between HRIStudio and the physical robots.
+
+Each robot plugin contains detailed action definitions with multiple
+components: action identifiers and metadata such as title, description,
+and a graphical icon to be presented in the EDE. Additionally, the
+plugin is programmed with parameter schemas including data types,
+validation rules, and default values to ensure proper configuration. For
+robots running ROS2, we support mappings that connect HRIStudio to the
+robot middleware. This integration approach ensures that HRIStudio can
+be used with any robot for which a plugin has been built.
+
+As shown in Figure [6](#fig:plugins-store){reference-type="ref"
+reference="fig:plugins-store"}, we have developed a *Plugin Store* to
+aggregate plugins available for an HRIStudio installation. Currently, it
+includes a plugin specifically for the TurtleBot3 Burger (illustrated in
+the figure) as well as a template to support the creation of additional
+plugins for other robots. Over time, we anticipate that the Plugin Store
+will expand to include a broader range of plugins, supporting robots of
+diverse types. In order to let users of the platform know what to expect
+of the plugins in the store, we have defined three different trust
+levels:
+
+- *Official* plugins will have been created and tested by HRIStudio
+  developers.
+
+- *Verified* plugins will have different provenance, but will have
+  undergone a validation process.
+
+- *Community* plugins will have been developed by third-parties but will
+  not yet have been validated.
+
+The Plugin Store provides access to the source version control
+*repositories* which are used in the development of plugins allowing for
+the precise tracking of which plugin versions are used in each
+experiment. This system enables community contributions while
+maintaining reproducibility by documenting exactly which plugin versions
+were used for any given experiment.
+
+![The Plugin Store for plugin
+selection.](assets/mockups/plugins-store.png){#fig:plugins-store
+width="1\\columnwidth"}
+
+## Comprehensive Data Capture and Analysis
+
+We have designed HRIStudio to create detailed logs of experiment
+executions and to capture and place in persistent storage all the data
+generated during each trial. The system keeps timestamped records of all
+executed actions and experimental events so that it is able to create an
+accurate timeline of the study. It collects robot sensor data including
+position, orientation, and various sensor readings that provide context
+about the robot's state throughout the experiment.
+
+The platform records audio and video of interactions between a robot and
+participant, enabling post-hoc analysis of verbal and non-verbal
+behaviors. The system also records wizard decisions and interventions,
+including any unplanned actions that deviate from the experimental
+protocol. Finally, it saves with the experiment the observer notes and
+annotations, capturing qualitative insights from researchers monitoring
+the study. Together, these synchronized data streams provide a complete
+record of experimental sessions.
+
+Experimental data is stored in structured formats to support long-term
+preservation and seamless integration with analysis tools. Sensitive
+participant data is encrypted at the database level to safeguard
+participant privacy while retaining comprehensive records for research
+use. To facilitate analysis, the platform allows trials to be studied
+with "playback" functionalities that allow one to review the steps in a
+trial and to annotate any significant events identified.
+
+# Conclusion and Future Directions {#conclusion}
+
+Although Wizard-of-Oz (WoZ) experiments are a powerful method for
+developing human-robot interaction applications, they demand careful
+attention to procedural details. Trials involving different participants
+require wizards to consistently execute the same sequence of events,
+accurately log any deviations from the prescribed script, and
+systematically manage all assets associated with each participant. The
+reproducibility of WoZ experiments depends on the thoroughness of their
+documentation and the ease with which their experimental setup can be
+disseminated.
+
+To support these efforts, we drew on both existing literature and our
+own experience to develop HRIStudio, a modular platform designed to ease
+the burden on wizards while enhancing the reproducibility of
+experiments. HRIStudio maintains detailed records of experimental
+designs and results, facilitating dissemination and helping third
+parties interested in replication. The platform offers a hierarchical
+framework for experiment design and a visual programming interface for
+specifying sequences of events. By minimizing the need for programming
+expertise, it lowers the barrier to entry and broadens access to WoZ
+experimentation.
+
+HRIStudio is built using a variety of web application and database
+technologies, which introduce certain dependencies for host systems. To
+simplify deployment, we are containerizing the platform and developing
+comprehensive, interface-integrated documentation to guide users through
+installation and operation. Our next development phase focuses on
+enhancing execution and analysis capabilities, including advanced wizard
+guidance, dynamic adaptation, and improved real-time feedback. We are
+also implementing playback functionality for reviewing synchronized data
+streams and expanding integration with hardware commonly used HRI
+research.
+
+Ongoing engagement with the research community has played a key role in
+shaping HRIStudio. Feedback from the reviewers of our RO-MAN 2024 late
+breaking report and conference participants directly influenced our
+design choices, particularly around integration with existing research
+infrastructures and workflows. We look forward to creating more
+systematic opportunities to engage researchers to guide and refine our
+development as we prepare for an open beta release.
+
+[^1]: $^{*}$Both authors are with the Department of Computer Science at
+    Bucknell University in Lewisburg, PA, USA. They can be reached at
+    `sso005@bucknell.edu` and `perrone@bucknell.edu`

docs/_archive/plugin-system-implementation-guide.md

@@ -0,0 +1,654 @@
+# HRIStudio Plugin System Implementation Guide
+
+## Overview
+
+This guide provides step-by-step instructions for implementing the HRIStudio Plugin System integration. You have access to two repositories:
+
+1. **HRIStudio Main Repository** - Contains the core platform
+2. **Plugin Repository** - Contains robot plugin definitions and web interface
+
+Your task is to create a plugin store within HRIStudio and modify the plugin repository to ensure seamless integration.
+
+## Architecture Overview
+
+```
+HRIStudio Platform
+├── Plugin Store (Frontend)
+├── Plugin Manager (Backend)
+├── Plugin Registry (Database)
+└── ROS2 Integration Layer
+    └── Plugin Repository (External)
+        ├── Repository Metadata
+        ├── Plugin Definitions
+        └── Web Interface
+```
+
+## Phase 1: Plugin Store Frontend Implementation
+
+### 1.1 Create Plugin Store Page
+
+**Location**: `src/app/(dashboard)/plugins/page.tsx`
+
+Create a new page that displays available plugins from registered repositories.
+
+```typescript
+// Key features to implement:
+- Repository management (add/remove plugin repositories)
+- Plugin browsing with categories and search
+- Plugin details modal/page
+- Installation status tracking
+- Trust level indicators (Official, Verified, Community)
+```
+
+**UI Requirements**:
+- Use existing HRIStudio design system (shadcn/ui)
+- Follow established patterns from studies/experiments pages
+- Include plugin cards with thumbnails, descriptions, and metadata
+- Implement filtering by category, platform (ROS2), trust level
+- Add search functionality
+
+### 1.2 Plugin Repository Management
+
+**Location**: `src/components/plugins/repository-manager.tsx`
+
+```typescript
+// Features to implement:
+- Add repository by URL
+- Validate repository structure
+- Display repository metadata (name, trust level, plugin count)
+- Enable/disable repositories
+- Remove repositories
+- Repository status indicators (online, offline, error)
+```
+
+### 1.3 Plugin Installation Interface
+
+**Location**: `src/components/plugins/plugin-installer.tsx`
+
+```typescript
+// Features to implement:
+- Plugin installation progress
+- Dependency checking
+- Version compatibility validation
+- Installation success/error handling
+- Plugin configuration interface
+```
+
+## Phase 2: Plugin Manager Backend Implementation
+
+### 2.1 Database Schema Extensions
+
+**Location**: `src/server/db/schema/plugins.ts`
+
+Add these tables to the existing schema:
+
+```sql
+-- Plugin repositories
+CREATE TABLE plugin_repositories (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(255) NOT NULL,
+  url TEXT NOT NULL UNIQUE,
+  trust_level VARCHAR(20) NOT NULL CHECK (trust_level IN ('official', 'verified', 'community')),
+  enabled BOOLEAN DEFAULT true,
+  last_synced TIMESTAMP,
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Installed plugins
+CREATE TABLE installed_plugins (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  repository_id UUID NOT NULL REFERENCES plugin_repositories(id) ON DELETE CASCADE,
+  plugin_id VARCHAR(255) NOT NULL, -- robotId from plugin definition
+  name VARCHAR(255) NOT NULL,
+  version VARCHAR(50) NOT NULL,
+  configuration JSONB DEFAULT '{}',
+  enabled BOOLEAN DEFAULT true,
+  installed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  installed_by UUID NOT NULL REFERENCES users(id),
+  UNIQUE(repository_id, plugin_id)
+);
+
+-- Plugin usage in studies
+CREATE TABLE study_plugins (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  study_id UUID NOT NULL REFERENCES studies(id) ON DELETE CASCADE,
+  installed_plugin_id UUID NOT NULL REFERENCES installed_plugins(id),
+  configuration JSONB DEFAULT '{}',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(study_id, installed_plugin_id)
+);
+```
+
+### 2.2 tRPC Routes Implementation
+
+**Location**: `src/server/api/routers/plugins.ts`
+
+```typescript
+export const pluginsRouter = createTRPCRouter({
+  // Repository management
+  addRepository: protectedProcedure
+    .input(z.object({
+      url: z.string().url(),
+      name: z.string().optional()
+    }))
+    .mutation(async ({ ctx, input }) => {
+      // Validate repository structure
+      // Add to database
+      // Sync plugins
+    }),
+
+  listRepositories: protectedProcedure
+    .query(async ({ ctx }) => {
+      // Return user's accessible repositories
+    }),
+
+  syncRepository: protectedProcedure
+    .input(z.object({ repositoryId: z.string().uuid() }))
+    .mutation(async ({ ctx, input }) => {
+      // Fetch repository.json
+      // Update plugin definitions
+      // Handle errors
+    }),
+
+  // Plugin management
+  listAvailablePlugins: protectedProcedure
+    .input(z.object({
+      repositoryId: z.string().uuid().optional(),
+      search: z.string().optional(),
+      category: z.string().optional(),
+      platform: z.string().optional()
+    }))
+    .query(async ({ ctx, input }) => {
+      // Fetch plugins from repositories
+      // Apply filters
+      // Return plugin metadata
+    }),
+
+  installPlugin: protectedProcedure
+    .input(z.object({
+      repositoryId: z.string().uuid(),
+      pluginId: z.string(),
+      configuration: z.record(z.any()).optional()
+    }))
+    .mutation(async ({ ctx, input }) => {
+      // Validate plugin compatibility
+      // Install plugin
+      // Create plugin instance
+    }),
+
+  listInstalledPlugins: protectedProcedure
+    .query(async ({ ctx }) => {
+      // Return user's installed plugins
+    }),
+
+  getPluginActions: protectedProcedure
+    .input(z.object({ pluginId: z.string() }))
+    .query(async ({ ctx, input }) => {
+      // Return plugin action definitions
+      // For use in experiment designer
+    })
+});
+```
+
+### 2.3 Plugin Registry Service
+
+**Location**: `src/lib/plugins/registry.ts`
+
+```typescript
+export class PluginRegistry {
+  // Fetch and validate repository metadata
+  async fetchRepository(url: string): Promise<RepositoryMetadata>
+  
+  // Sync plugins from repository
+  async syncRepository(repositoryId: string): Promise<void>
+  
+  // Load plugin definition
+  async loadPlugin(repositoryId: string, pluginId: string): Promise<PluginDefinition>
+  
+  // Validate plugin compatibility
+  async validatePlugin(plugin: PluginDefinition): Promise<ValidationResult>
+  
+  // Install plugin
+  async installPlugin(repositoryId: string, pluginId: string, config?: any): Promise<void>
+}
+```
+
+## Phase 3: Plugin Repository Modifications
+
+### 3.1 Schema Enhancements
+
+**Location**: Plugin Repository - `docs/schema.md`
+
+Update the plugin schema to include HRIStudio-specific fields:
+
+```json
+{
+  "robotId": "string (required)",
+  "name": "string (required)", 
+  "description": "string (optional)",
+  "platform": "string (required)",
+  "version": "string (required)",
+  
+  // Add these HRIStudio-specific fields:
+  "pluginApiVersion": "string (required) - Plugin API version",
+  "hriStudioVersion": "string (required) - Minimum HRIStudio version", 
+  "trustLevel": "string (enum: official|verified|community)",
+  "category": "string (required) - Plugin category for UI organization",
+  
+  // Enhanced action schema:
+  "actions": [
+    {
+      "id": "string (required) - Unique action identifier",
+      "name": "string (required) - Display name",
+      "description": "string (optional)",
+      "category": "string (required) - movement|interaction|sensors|logic",
+      "icon": "string (optional) - Lucide icon name",
+      "timeout": "number (optional) - Default timeout in milliseconds",
+      "retryable": "boolean (optional) - Can this action be retried on failure",
+      
+      "parameterSchema": {
+        "type": "object",
+        "properties": {
+          // Zod-compatible parameter definitions
+        },
+        "required": ["array of required parameter names"]
+      },
+      
+      "ros2": {
+        // Existing ROS2 configuration
+      }
+    }
+  ]
+}
+```
+
+### 3.2 TurtleBot3 Plugin Update
+
+**Location**: Plugin Repository - `plugins/turtlebot3-burger.json`
+
+Add the missing HRIStudio fields to the existing plugin:
+
+```json
+{
+  "robotId": "turtlebot3-burger",
+  "name": "TurtleBot3 Burger",
+  "description": "A compact, affordable, programmable, ROS2-based mobile robot for education and research",
+  "platform": "ROS2",
+  "version": "2.0.0",
+  
+  // Add these new fields:
+  "pluginApiVersion": "1.0",
+  "hriStudioVersion": ">=0.1.0",
+  "trustLevel": "official",
+  "category": "mobile-robot",
+  
+  // Update actions with HRIStudio fields:
+  "actions": [
+    {
+      "id": "move_velocity", // Changed from actionId
+      "name": "Set Velocity", // Changed from title
+      "description": "Control the robot's linear and angular velocity",
+      "category": "movement", // New field
+      "icon": "navigation", // New field
+      "timeout": 30000, // New field
+      "retryable": true, // New field
+      
+      "parameterSchema": {
+        // Convert existing parameters to HRIStudio format
+        "type": "object",
+        "properties": {
+          "linear": {
+            "type": "number",
+            "minimum": -0.22,
+            "maximum": 0.22,
+            "default": 0,
+            "description": "Forward/backward velocity in m/s"
+          },
+          "angular": {
+            "type": "number",
+            "minimum": -2.84,
+            "maximum": 2.84,
+            "default": 0,
+            "description": "Rotational velocity in rad/s"
+          }
+        },
+        "required": ["linear", "angular"]
+      },
+      
+      // Keep existing ros2 config
+      "ros2": {
+        "messageType": "geometry_msgs/msg/Twist",
+        "topic": "/cmd_vel",
+        "payloadMapping": {
+          "type": "transform",
+          "transformFn": "transformToTwist"
+        },
+        "qos": {
+          "reliability": "reliable",
+          "durability": "volatile",
+          "history": "keep_last",
+          "depth": 1
+        }
+      }
+    }
+  ]
+}
+```
+
+### 3.3 Repository Metadata Update
+
+**Location**: Plugin Repository - `repository.json`
+
+Add HRIStudio-specific metadata:
+
+```json
+{
+  "id": "hristudio-official",
+  "name": "HRIStudio Official Robot Plugins",
+  "description": "Official collection of robot plugins maintained by the HRIStudio team",
+  
+  // Add API versioning:
+  "apiVersion": "1.0",
+  "pluginApiVersion": "1.0",
+  
+  // Add plugin categories:
+  "categories": [
+    {
+      "id": "mobile-robots",
+      "name": "Mobile Robots", 
+      "description": "Wheeled and tracked mobile platforms"
+    },
+    {
+      "id": "manipulators",
+      "name": "Manipulators",
+      "description": "Robotic arms and end effectors"
+    },
+    {
+      "id": "humanoids", 
+      "name": "Humanoid Robots",
+      "description": "Human-like robots for social interaction"
+    },
+    {
+      "id": "drones",
+      "name": "Aerial Vehicles",
+      "description": "Quadcopters and fixed-wing UAVs"
+    }
+  ],
+  
+  // Keep existing fields...
+  "compatibility": {
+    "hristudio": {
+      "min": "0.1.0",
+      "recommended": "0.1.0"
+    },
+    "ros2": {
+      "distributions": ["humble", "iron"],
+      "recommended": "iron"
+    }
+  }
+}
+```
+
+## Phase 4: Integration Implementation
+
+### 4.1 Experiment Designer Integration
+
+**Location**: HRIStudio - `src/components/experiments/designer/EnhancedBlockDesigner.tsx`
+
+Add plugin-based action loading to the block designer:
+
+```typescript
+// In the block registry, load actions from installed plugins:
+const loadPluginActions = async (studyId: string) => {
+  const installedPlugins = await api.plugins.getStudyPlugins.query({ studyId });
+  
+  for (const plugin of installedPlugins) {
+    const actions = await api.plugins.getPluginActions.query({ 
+      pluginId: plugin.id 
+    });
+    
+    // Register actions in block registry
+    actions.forEach(action => {
+      blockRegistry.register({
+        id: `${plugin.id}.${action.id}`,
+        name: action.name,
+        description: action.description,
+        category: action.category,
+        icon: action.icon || 'bot',
+        shape: 'action',
+        color: getCategoryColor(action.category),
+        parameters: convertToZodSchema(action.parameterSchema),
+        metadata: {
+          pluginId: plugin.id,
+          robotId: plugin.robotId,
+          ros2Config: action.ros2
+        }
+      });
+    });
+  }
+};
+```
+
+### 4.2 Trial Execution Integration
+
+**Location**: HRIStudio - `src/lib/plugins/execution.ts`
+
+Create plugin execution interface:
+
+```typescript
+export class PluginExecutor {
+  private installedPlugins = new Map<string, InstalledPlugin>();
+  private rosConnections = new Map<string, RosConnection>();
+
+  async executePluginAction(
+    pluginId: string, 
+    actionId: string, 
+    parameters: Record<string, any>
+  ): Promise<ActionResult> {
+    const plugin = this.installedPlugins.get(pluginId);
+    if (!plugin) {
+      throw new Error(`Plugin ${pluginId} not found`);
+    }
+
+    const action = plugin.actions.find(a => a.id === actionId);
+    if (!action) {
+      throw new Error(`Action ${actionId} not found in plugin ${pluginId}`);
+    }
+
+    // Validate parameters against schema
+    const validation = this.validateParameters(action.parameterSchema, parameters);
+    if (!validation.success) {
+      throw new Error(`Parameter validation failed: ${validation.error}`);
+    }
+
+    // Execute via ROS2 if configured
+    if (action.ros2) {
+      return this.executeRos2Action(plugin, action, parameters);
+    }
+
+    // Execute via REST API if configured
+    if (action.rest) {
+      return this.executeRestAction(plugin, action, parameters);
+    }
+
+    throw new Error(`No execution method configured for action ${actionId}`);
+  }
+
+  private async executeRos2Action(
+    plugin: InstalledPlugin,
+    action: PluginAction, 
+    parameters: Record<string, any>
+  ): Promise<ActionResult> {
+    const connection = this.getRosConnection(plugin.id);
+    
+    // Transform parameters according to payload mapping
+    const payload = this.transformPayload(action.ros2.payloadMapping, parameters);
+    
+    // Publish to topic or call service
+    if (action.ros2.topic) {
+      return this.publishToTopic(connection, action.ros2, payload);
+    } else if (action.ros2.service) {
+      return this.callService(connection, action.ros2, payload);
+    } else if (action.ros2.action) {
+      return this.executeAction(connection, action.ros2, payload);
+    }
+    
+    throw new Error('No ROS2 communication method specified');
+  }
+}
+```
+
+### 4.3 Plugin Store Navigation
+
+**Location**: HRIStudio - `src/components/layout/navigation/SidebarNav.tsx`
+
+Add plugin store to the navigation:
+
+```typescript
+const navigationItems = [
+  {
+    title: "Dashboard",
+    href: "/",
+    icon: LayoutDashboard,
+    description: "Overview and quick actions"
+  },
+  {
+    title: "Studies", 
+    href: "/studies",
+    icon: FolderOpen,
+    description: "Research projects and team collaboration"
+  },
+  {
+    title: "Experiments",
+    href: "/experiments", 
+    icon: FlaskConical,
+    description: "Protocol design and validation"
+  },
+  {
+    title: "Participants",
+    href: "/participants",
+    icon: Users,
+    description: "Participant management and consent"
+  },
+  {
+    title: "Trials",
+    href: "/trials",
+    icon: Play,
+    description: "Experiment execution and monitoring"
+  },
+  // Add plugin store:
+  {
+    title: "Plugin Store",
+    href: "/plugins",
+    icon: Package,
+    description: "Robot plugins and integrations"
+  },
+  {
+    title: "Admin",
+    href: "/admin",
+    icon: Settings,
+    description: "System administration",
+    roles: ["administrator"]
+  }
+];
+```
+
+### 4.4 Plugin Configuration in Studies
+
+**Location**: HRIStudio - `src/app/(dashboard)/studies/[studyId]/settings/page.tsx`
+
+Add plugin configuration to study settings:
+
+```typescript
+const StudySettingsPage = ({ studyId }: { studyId: string }) => {
+  const installedPlugins = api.plugins.listInstalledPlugins.useQuery();
+  const studyPlugins = api.plugins.getStudyPlugins.useQuery({ studyId });
+  
+  return (
+    <PageLayout title="Study Settings">
+      <Tabs defaultValue="general">
+        <TabsList>
+          <TabsTrigger value="general">General</TabsTrigger>
+          <TabsTrigger value="team">Team</TabsTrigger>
+          <TabsTrigger value="plugins">Robot Plugins</TabsTrigger>
+          <TabsTrigger value="permissions">Permissions</TabsTrigger>
+        </TabsList>
+        
+        <TabsContent value="plugins">
+          <Card>
+            <CardHeader>
+              <CardTitle>Robot Plugins</CardTitle>
+              <CardDescription>
+                Configure which robot plugins are available for this study
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <PluginConfiguration
+                studyId={studyId}
+                availablePlugins={installedPlugins.data || []}
+                enabledPlugins={studyPlugins.data || []}
+              />
+            </CardContent>
+          </Card>
+        </TabsContent>
+      </Tabs>
+    </PageLayout>
+  );
+};
+```
+
+## Phase 5: Testing and Validation
+
+### 5.1 Plugin Repository Testing
+
+Create test scripts to validate:
+- Repository structure and schema compliance
+- Plugin definition validation
+- Web interface functionality
+- API endpoint responses
+
+### 5.2 HRIStudio Integration Testing
+
+Test the complete flow:
+1. Add plugin repository to HRIStudio
+2. Install a plugin from the repository
+3. Configure plugin for a study
+4. Use plugin actions in experiment designer
+5. Execute plugin actions during trial
+
+### 5.3 End-to-End Testing
+
+Create automated tests that:
+- Validate plugin installation process
+- Test ROS2 communication via rosbridge
+- Verify parameter validation and transformation
+- Test error handling and recovery
+
+## Deployment Checklist
+
+### Plugin Repository
+- [ ] Update plugin schema documentation
+- [ ] Enhance existing plugin definitions
+- [ ] Test web interface with new schema
+- [ ] Deploy to GitHub Pages or hosting platform
+- [ ] Validate HTTPS access and CORS headers
+
+### HRIStudio Platform
+- [ ] Implement database schema migrations
+- [ ] Create plugin store frontend pages
+- [ ] Implement plugin management tRPC routes
+- [ ] Integrate plugins with experiment designer
+- [ ] Add plugin execution to trial system
+- [ ] Update navigation to include plugin store
+- [ ] Add plugin configuration to study settings
+
+### Integration Testing
+- [ ] Test repository discovery and syncing
+- [ ] Validate plugin installation workflow
+- [ ] Test plugin action execution
+- [ ] Verify ROS2 integration works end-to-end
+- [ ] Test error handling and user feedback
+
+This implementation will create a complete plugin ecosystem for HRIStudio, allowing researchers to easily discover, install, and use robot plugins in their studies.

docs/_archive/project-overview.md

@@ -0,0 +1,254 @@
+# HRIStudio Project Overview
+
+## Executive Summary
+
+HRIStudio is a web-based platform designed to standardize and improve the reproducibility of Wizard of Oz (WoZ) studies in Human-Robot Interaction (HRI) research. The platform addresses critical challenges in HRI research by providing a comprehensive experimental workflow management system with standardized terminology, visual experiment design tools, real-time wizard control interfaces, and comprehensive data capture capabilities.
+
+## Project Goals
+
+### Primary Objectives
+1. **Enhance Scientific Rigor**: Standardize WoZ study methodologies to improve reproducibility
+2. **Lower Barriers to Entry**: Make HRI research accessible to researchers without deep robot programming expertise
+3. **Enable Collaboration**: Support multi-user workflows with role-based access control
+4. **Ensure Data Integrity**: Comprehensive capture and secure storage of all experimental data
+5. **Support Multiple Robot Platforms**: Provide a plugin-based architecture for robot integration
+
+### Key Problems Addressed
+- Lack of standardized terminology in WoZ studies
+- Poor documentation practices leading to unreproducible experiments
+- Technical barriers preventing non-programmers from conducting HRI research
+- Inconsistent wizard behavior across trials
+- Limited data capture and analysis capabilities in existing tools
+
+## Core Features
+
+### 1. Hierarchical Experiment Structure
+- **Study**: Top-level container for research projects
+- **Experiment**: Parameterized protocol templates within a study
+- **Trial**: Executable instances of experiments with specific participants
+- **Step**: Distinct phases in the execution sequence
+- **Action**: Atomic tasks for wizards or robots
+
+### 2. Visual Experiment Designer (EDE)
+- Drag-and-drop interface for creating experiment workflows
+- No-code solution for experiment design
+- **Repository-based block system** with 26+ core blocks across 4 categories
+- **Plugin architecture** for both core functionality and robot actions
+- Context-sensitive help and best practice guidance
+- Automatic generation of robot-specific action components
+- Parameter configuration with validation
+- **System Plugins**:
+  - **Core (`hristudio-core`)**: Control flow (loops, branches) and observation blocks
+  - **Wizard (`hristudio-woz`)**: Wizard interactions (speech, text input)
+- **External Robot Plugins**:
+  - Located in `robot-plugins/` repository (e.g., `nao6-ros2`)
+  - Loaded dynamically per study
+  - Map abstract actions (Say, Walk) to ROS2 topics
+- **Core Block Categories**:
+  - Events (4): Trial triggers, speech detection, timers, key presses
+  - Wizard Actions (6): Speech, gestures, object handling, rating, notes
+  - Control Flow (8): Loops, conditionals, parallel execution, error handling
+  - Observation (8): Behavioral coding, timing, recording, surveys, sensors
+
+### 3. Adaptive Wizard Interface
+- Real-time experiment execution dashboard
+- Step-by-step guidance for consistent execution
+- Quick actions for unscripted interventions
+- Live video feed integration
+- Timestamped event logging
+- Customizable per-experiment controls
+
+### 4. Robot Platform Integration
+- **Unified plugin architecture** for both core blocks and robot actions
+- Abstract action definitions with platform-specific translations
+- Support for RESTful APIs, ROS2, and custom protocols
+- **Repository system** for plugin distribution and management
+- Plugin Store with trust levels (Official, Verified, Community)
+- Version tracking for reproducibility
+
+### 5. Comprehensive Data Management
+- Automatic capture of all experimental data
+- Synchronized multi-modal data streams (video, audio, logs, sensor data)
+- Encrypted storage for sensitive participant data
+- Role-based access control for data security
+- Export capabilities for analysis tools
+
+### 6. Collaboration Features
+- Multi-user support with defined roles
+- Project dashboards with status tracking
+- Token-based resource sharing for external collaboration
+- Activity logs and audit trails
+- Support for double-blind study designs
+- Comment system for team communication
+- File attachments for supplementary materials
+
+## System Architecture
+
+### Three-Layer Architecture
+
+#### 1. User Interface Layer
+- **Experiment Designer**: Visual programming interface with repository-based blocks
+- **Core Blocks System**: 26 essential blocks for events, wizard actions, control flow, and observation
+- **Wizard Interface**: Real-time control and monitoring during trials
+- **Playback & Analysis**: Data exploration and visualization tools
+- **Administration Panel**: System configuration and user management
+- **Plugin Store**: Browse and install robot platform integrations
+
+#### 2. Data Management Layer
+- **Database**: PostgreSQL for structured data and metadata
+- **Object Storage**: MinIO (S3-compatible) for media files
+- **Access Control**: Role-based permissions system
+- **API Layer**: tRPC for type-safe client-server communication
+- **Data Models**: Drizzle ORM for database operations
+
+#### 3. Robot Integration Layer
+- **Plugin System**: Modular robot platform support
+- **Action Translation**: Abstract to platform-specific command mapping
+- **Communication Protocols**: Support for REST, ROS2, and custom protocols
+- **State Management**: Robot status tracking and synchronization
+
+## User Roles and Permissions
+
+### Administrator
+- Full system access
+- User management capabilities
+- System configuration
+- Plugin installation and management
+- Database maintenance
+
+### Researcher
+- Create and manage studies
+- Design experiments
+- Manage team members
+- View all trial data
+- Export data for analysis
+
+### Wizard
+- Execute assigned experiments
+- Control robot during trials
+- Make real-time decisions
+- View experiment instructions
+- Access quick actions
+
+### Observer
+- Read-only access to experiments
+- Monitor live trial execution
+- Add notes and annotations
+- View historical data
+- No control capabilities
+
+## Technology Stack
+
+### Frontend
+- **Framework**: Next.js 14+ (App Router)
+- **UI Components**: shadcn/ui (built on Radix UI)
+- **Styling**: Tailwind CSS
+- **State Management**: nuqs (URL state), React Server Components
+- **Forms**: React Hook Form with Zod validation
+- **Real-time**: WebSockets for live updates
+
+### Backend
+- **Runtime**: Node.js with Bun package manager
+- **API**: tRPC for type-safe endpoints
+- **Database**: PostgreSQL with Drizzle ORM
+- **Authentication**: NextAuth.js v5 (Auth.js)
+- **File Storage**: MinIO (S3-compatible object storage)
+- **Background Jobs**: Bull queue with Redis
+
+### Infrastructure
+- **Containerization**: Docker and Docker Compose
+- **Development**: Hot reloading, TypeScript strict mode
+- **Testing**: Vitest for unit tests, Playwright for E2E
+- **CI/CD**: GitHub Actions
+- **Monitoring**: OpenTelemetry integration
+
+## Key Concepts
+
+### Experiment Lifecycle
+1. **Design Phase**: Researchers create experiment templates using visual designer
+2. **Configuration Phase**: Set parameters and assign team members
+3. **Execution Phase**: Wizards run trials with participants
+4. **Analysis Phase**: Review captured data and generate insights
+5. **Sharing Phase**: Export or share experiment materials
+
+### Data Flow
+1. **Input**: Experiment designs, wizard actions, robot responses, sensor data
+2. **Processing**: Action translation, state management, data synchronization
+3. **Storage**: Structured data in PostgreSQL, media files in MinIO
+4. **Output**: Real-time updates, analysis reports, exported datasets
+
+### Plugin Architecture
+- **Action Definitions**: Abstract representations of robot capabilities
+- **Parameter Schemas**: Type-safe configuration with validation
+- **Communication Adapters**: Platform-specific protocol implementations
+- **Version Management**: Semantic versioning for compatibility
+
+### Token-Based Sharing Model
+- **Share Links**: Generate unique tokens for resource access
+- **Permission Control**: Granular permissions (read, comment, annotate)
+- **Expiration**: Time-limited access for security
+- **Access Tracking**: Monitor usage and analytics
+- **Public Access**: No authentication required for shared resources
+- **Revocation**: Instant access removal when needed
+
+## Development Principles
+
+### Code Quality
+- TypeScript throughout with strict type checking
+- Functional programming patterns (avoid classes)
+- Comprehensive error handling
+- Extensive logging for debugging
+- Clean architecture with separation of concerns
+
+### User Experience
+- Mobile-first responsive design
+- Progressive enhancement
+- Optimistic UI updates
+- Comprehensive loading states
+- Intuitive error messages
+
+### Performance
+- Server-side rendering where possible
+- Lazy loading for non-critical components
+- Image optimization (WebP, proper sizing)
+- Database query optimization
+- Caching strategies
+
+### Security
+- Role-based access control at all levels
+- Data encryption at rest and in transit
+- Input validation and sanitization
+- Rate limiting on API endpoints
+- Audit logging for compliance
+
+## Success Metrics
+
+### Technical Metrics
+- Page load time < 2 seconds
+- API response time < 200ms (p95)
+- High uptime for critical services
+- Zero data loss incidents
+- Support for 100+ concurrent users
+
+### User Success Metrics
+- Time to create first experiment < 30 minutes
+- High trial execution consistency
+- Complete data capture
+- High user satisfaction score
+- Active monthly users growth
+
+## Future Considerations
+
+### Planned Enhancements
+- AI-powered experiment design suggestions
+- Advanced analytics and visualization tools
+- Mobile app for wizard control
+- Cloud-hosted SaaS offering
+- Integration with popular analysis tools (R, Python)
+
+### Extensibility Points
+- Custom plugin development SDK
+- Webhook system for external integrations
+- Custom report generation
+- API for third-party tools
+- Theming and white-labeling support

docs/_archive/roman-2025-talk.md

@@ -0,0 +1,139 @@
+# A Web-Based Wizard-of-Oz Platform for Collaborative and Reproducible Human-Robot Interaction Research
+
+## 1) Introduction
+- HRI needs rigorous methods for studying robot communication, collaboration, and coexistence with people.
+- WoZ: a wizard remotely operates a robot to simulate autonomous behavior, enabling rapid prototyping and iterative refinement.
+- Challenges with WoZ:
+  - Wizard must execute scripted sequences consistently across participants.
+  - Deviations and technical barriers reduce methodological rigor and reproducibility.
+  - Many available tools require specialized technical expertise.
+- Goal: a platform that lowers barriers to entry, supports rigorous, reproducible WoZ experiments, and provides integrated capabilities.
+
+## 2) Assessment of the State-of-the-Art
+- Technical infrastructure and architectures:
+  - Polonius: ROS-based, finite-state machine scripting, integrated logging for real-time event recording; designed for non-programming collaborators.
+  - OpenWoZ: runtime-configurable, multi-client, supports distributed operation and dynamic evaluator interventions (requires programming for behavior creation).
+- Interface design and user experience:
+  - NottReal: interface for voice UI studies; tabbed pre-scripted messages, customization slots, message queuing, comprehensive logging, familiar listening/processing feedback.
+  - WoZ4U: GUI designed for non-programmers; specialized to Aldebaran Pepper (limited generalizability).
+- Domain specialization vs. generalizability:
+  - System longevity is often short (2–3 years for general-purpose tools).
+  - Ozlab’s longevity due to: general-purpose design, curricular integration, flexible wizard UI that adapts to experiments.
+- Standardization and methodological approaches:
+  - Interaction Specification Language (ISL) and ADEs (Porfirio et al.): hierarchical modularity, formal representations, platform independence for reproducibility.
+  - Riek: methodological transparency deficiencies in WoZ literature (insufficient reporting of protocols/training/constraints).
+  - Steinfeld et al.: “Oz of Wizard” complements WoZ; structured permutations of real vs. simulated components; both approaches serve valid objectives.
+  - Belhassein et al.: recurring HRI study challenges (limited participants, inadequate protocol reporting, weak replication); need for validated measures and comprehensive documentation.
+  - Fraune et al.: practical guidance (pilot testing, ensuring intended perception of robot behaviors, managing novelty effects, cross-field collaboration).
+- Remaining challenges:
+  - Accessibility for interdisciplinary teams.
+  - Methodological standardization and comprehensive data capture/sharing.
+  - Balance of structure (for reproducibility) and flexibility (for diverse research questions).
+
+## 3) Reproducibility Challenges in WoZ Studies
+- Inconsistent wizard behavior across trials undermines reproducibility.
+- Publications often omit critical procedural details, making replication difficult.
+- Custom, ad-hoc setups are hard to recreate; unrecorded changes hinder transparency.
+- HRIStudio’s reproducibility requirements (five areas):
+  - Standardized terminology and structure.
+  - Wizard behavior formalization (clear, consistent execution with controlled flexibility).
+  - Comprehensive, time-synchronized data capture.
+  - Experiment specification sharing (package and distribute complete designs).
+  - Procedural documentation (automatic logging of parameters and methodological details).
+
+## 4) The Design and Architecture of HRIStudio
+- Guiding design principles:
+  - Accessibility for researchers without deep robot programming expertise.
+  - Abstraction to focus on experimental design over platform details.
+  - Comprehensive data management (logs, audio, video, study materials).
+  - Collaboration through multi-user accounts, role-based access control, and data sharing.
+  - Embedded methodological guidance to encourage scientifically sound practices.
+- Conceptual separation aligned to research needs:
+  - User-facing tools for design, execution, and analysis; stewarded data and access control; and standardized interfaces to connect experiments with robots and sensors.
+- Three-layer architecture [Screenshot Placeholder: Architecture Overview]:
+  - User Interface Layer:
+    - Experiment Designer (visual programming for specifying experiments).
+    - Wizard Interface (real-time control for trials).
+    - Playback & Analysis (data exploration and visualization).
+  - Data Management Layer:
+    - Structured storage of experiment definitions, metadata, and media.
+    - Role-based access aligned with study responsibilities.
+    - Collaboration with secure, compartmentalized access for teams.
+  - Robot Integration Layer:
+    - Translates standardized abstractions to robot behaviors through plugins.
+    - Standardized plugin interfaces support diverse platforms without changing study designs.
+    - Integrates with external systems (robot hardware, sensors, tools).
+- Sustained reproducibility and sharing:
+  - Study definitions and execution environments can be packaged and shared to support faithful reproduction by independent teams.
+
+## 5) Experimental Workflow Support
+- Directly addresses reproducibility requirements with standardized structures, wizard guidance, and comprehensive capture.
+
+### 5.1 Hierarchical Structure for WoZ Studies
+- Standard terminology and elements:
+  - Study: top-level container with one or more experiments.
+  - Experiment: parameterized protocol template composed of steps.
+  - Trial: concrete, executable instance of an experiment for a specific participant; all trial data recorded.
+  - Step: type-bound container (wizard or robot) comprising a sequence of actions.
+  - Action: atomic task for wizard or robot (e.g., input gathering, speech, movement), parameterized per trial.
+- [Screenshot Placeholder: Experiment Hierarchy Diagram].
+- [Screenshot Placeholder: Study Details View]:
+  - Overview of execution summaries, trials, participant info and documents (e.g., consent), members, metadata, and audit activity.
+
+### 5.2 Collaboration and Knowledge Sharing
+- Dashboard for project overview, collaborators, trial schedules, pending tasks.
+- Role-based access control (pre-defined roles; flexible extensions):
+  - Administrator: system configuration/management.
+  - Researcher: create/configure studies and experiments.
+  - Observer: read-only access and real-time monitoring.
+  - Wizard: execute experiments.
+- Packaging and dissemination of complete materials for replication and meta-analyses.
+
+### 5.3 Visual Experiment Design (EDE)
+- Visual programming canvas for sequencing steps and actions (drag-and-drop).
+- Abstract robot actions translated by plugins into platform-specific commands.
+- Contextual help and documentation in the interface.
+- [Screenshot Placeholder: Experiment Designer].
+- Inspiration: Choregraphe’s flow-based, no-code composition for steps/actions.
+
+### 5.4 Wizard Interface and Experiment Execution
+- Adaptable, experiment-specific wizard UI (avoids one-size-fits-all trap).
+- Incremental instructions, “View More” for full script, video feed, timestamped event log, and “quick actions.”
+- Observer view mirrors wizard interface without execution controls.
+- Action execution process:
+  1) Translate abstract action into robot-specific calls via plugin.
+  2) Route calls through appropriate communication channels.
+  3) Process robot feedback, log details, update experiment state.
+- [Screenshot Placeholder: Wizard Interface].
+
+### 5.5 Robot Platform Integration (Plugin Store)
+- Two-tier abstraction/translation of actions:
+  - High-level action components (movement, speech, sensors) with parameter schemas and validation rules.
+  - Robot plugins implement concrete mappings appropriate to each platform.
+- [Screenshot Placeholder: Plugin Store]:
+  - Trust levels: Official, Verified, Community.
+  - Source repositories for precise version tracking and reproducibility.
+
+### 5.6 Comprehensive Data Capture and Analysis
+- Timestamped logs of all executed actions and events.
+- Robot sensor data (position, orientation, sensor readings).
+- Audio/video recordings of interactions.
+- Wizard decisions/interventions (including unplanned deviations).
+- Observer notes and annotations.
+- Structured storage for long-term preservation and analysis integration.
+- Sensitive participant data encrypted at the database level.
+- Playback for step-by-step trial review and annotation.
+
+## 6) Conclusion and Future Directions
+- HRIStudio supports rigorous, reproducible WoZ experimentation via:
+  - Standardized hierarchy and terminology.
+  - Visual designer for protocol specification.
+  - Configurable wizard interface for consistent execution.
+  - Plugin-based, robot-agnostic integration.
+  - Comprehensive capture and structured storage of multimodal data.
+- Future directions:
+  - Interface-integrated documentation for installation and operation.
+  - Enhanced execution and analysis (advanced guidance, dynamic adaptation, real-time feedback).
+  - Playback for synchronized streams and expanded hardware integration.
+  - Continued community engagement to refine integration with existing research infrastructures and workflows.
+  - Preparation for an open beta release.

docs/_archive/ros2-integration.md

@@ -0,0 +1,969 @@
+# ROS2 Integration Guide for HRIStudio
+
+## Overview
+
+HRIStudio integrates with ROS2-based robots through the rosbridge protocol, enabling web-based control and monitoring of robots without requiring ROS2 installation on the server. This approach provides flexibility and simplifies deployment, especially on platforms like Vercel.
+
+## Architecture
+
+### Communication Flow
+
+```
+HRIStudio Web App → WebSocket → rosbridge_server → ROS2 Robot
+                                      ↓
+                              ROS2 Topics/Services
+```
+
+### Key Components
+
+1. **rosbridge_suite**: Provides WebSocket interface to ROS2
+2. **roslib.js**: JavaScript library for ROS communication
+3. **HRIStudio Plugin System**: Abstracts robot-specific implementations
+4. **Message Type Definitions**: TypeScript interfaces for ROS2 messages
+
+## ROS2 Bridge Setup
+
+### Robot-Side Configuration
+
+The robot or a companion computer must run rosbridge:
+
+```bash
+# Install rosbridge suite
+sudo apt update
+sudo apt install ros-humble-rosbridge-suite
+
+# Launch rosbridge with WebSocket server
+ros2 launch rosbridge_server rosbridge_websocket_launch.xml
+```
+
+### Custom Launch File
+
+Create `hristudio_bridge.launch.xml`:
+
+```xml
+<launch>
+  <arg name="port" default="9090"/>
+  <arg name="address" default="0.0.0.0"/>
+  <arg name="ssl" default="false"/>
+  <arg name="certfile" default=""/>
+  <arg name="keyfile" default=""/>
+  
+  <node pkg="rosbridge_server" exec="rosbridge_websocket" name="rosbridge_websocket">
+    <param name="port" value="$(var port)"/>
+    <param name="address" value="$(var address)"/>
+    <param name="ssl" value="$(var ssl)"/>
+    <param name="certfile" value="$(var certfile)"/>
+    <param name="keyfile" value="$(var keyfile)"/>
+    
+    <!-- Limit message sizes for security -->
+    <param name="max_message_size" value="10000000"/>
+    <param name="unregister_timeout" value="10.0"/>
+    
+    <!-- Enable specific services only -->
+    <param name="services_glob" value="['/hristudio/*']"/>
+    <param name="topics_glob" value="['/hristudio/*', '/tf', '/tf_static']"/>
+  </node>
+</launch>
+```
+
+## Client-Side Implementation
+
+### ROS Connection Manager
+
+`src/lib/ros/connection.ts`:
+
+```typescript
+import ROSLIB from 'roslib';
+
+export class RosConnection {
+  private ros: ROSLIB.Ros | null = null;
+  private url: string;
+  private reconnectInterval: number = 5000;
+  private reconnectTimer: NodeJS.Timeout | null = null;
+  private listeners: Map<string, Set<(data: any) => void>> = new Map();
+
+  constructor(url: string = process.env.NEXT_PUBLIC_ROSBRIDGE_URL || 'ws://localhost:9090') {
+    this.url = url;
+  }
+
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.ros?.isConnected) {
+        resolve();
+        return;
+      }
+
+      this.ros = new ROSLIB.Ros({
+        url: this.url,
+        options: {
+          // Enable compression for better performance
+          compression: 'png',
+          // Throttle rate for topic subscriptions
+          throttle_rate: 100,
+        }
+      });
+
+      this.ros.on('connection', () => {
+        console.log('Connected to ROS bridge');
+        this.clearReconnectTimer();
+        resolve();
+      });
+
+      this.ros.on('error', (error) => {
+        console.error('ROS connection error:', error);
+        reject(error);
+      });
+
+      this.ros.on('close', () => {
+        console.log('ROS connection closed');
+        this.scheduleReconnect();
+      });
+    });
+  }
+
+  private scheduleReconnect() {
+    if (this.reconnectTimer) return;
+    
+    this.reconnectTimer = setTimeout(() => {
+      console.log('Attempting to reconnect to ROS...');
+      this.connect().catch(console.error);
+    }, this.reconnectInterval);
+  }
+
+  private clearReconnectTimer() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  disconnect() {
+    this.clearReconnectTimer();
+    if (this.ros) {
+      this.ros.close();
+      this.ros = null;
+    }
+  }
+
+  isConnected(): boolean {
+    return this.ros?.isConnected || false;
+  }
+
+  getRos(): ROSLIB.Ros | null {
+    return this.ros;
+  }
+
+  // Topic subscription helper
+  subscribe<T>(topicName: string, messageType: string, callback: (message: T) => void): () => void {
+    if (!this.ros) throw new Error('Not connected to ROS');
+
+    const topic = new ROSLIB.Topic({
+      ros: this.ros,
+      name: topicName,
+      messageType: messageType,
+      compression: 'png',
+      throttle_rate: 100
+    });
+
+    topic.subscribe(callback);
+
+    // Return unsubscribe function
+    return () => {
+      topic.unsubscribe(callback);
+    };
+  }
+
+  // Service call helper
+  async callService<TRequest, TResponse>(
+    serviceName: string,
+    serviceType: string,
+    request: TRequest
+  ): Promise<TResponse> {
+    if (!this.ros) throw new Error('Not connected to ROS');
+
+    const service = new ROSLIB.Service({
+      ros: this.ros,
+      name: serviceName,
+      serviceType: serviceType
+    });
+
+    return new Promise((resolve, reject) => {
+      service.callService(
+        new ROSLIB.ServiceRequest(request),
+        (response: TResponse) => resolve(response),
+        (error: string) => reject(new Error(error))
+      );
+    });
+  }
+
+  // Action client helper
+  createActionClient(actionName: string, actionType: string): ROSLIB.ActionClient {
+    if (!this.ros) throw new Error('Not connected to ROS');
+
+    return new ROSLIB.ActionClient({
+      ros: this.ros,
+      serverName: actionName,
+      actionName: actionType
+    });
+  }
+}
+
+// Singleton instance
+export const rosConnection = new RosConnection();
+```
+
+### ROS2 Message Types
+
+`src/lib/ros/types.ts`:
+
+```typescript
+// Common ROS2 message types
+export interface Header {
+  stamp: {
+    sec: number;
+    nanosec: number;
+  };
+  frame_id: string;
+}
+
+export interface Twist {
+  linear: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  angular: {
+    x: number;
+    y: number;
+    z: number;
+  };
+}
+
+export interface Pose {
+  position: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  orientation: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+  };
+}
+
+export interface JointState {
+  header: Header;
+  name: string[];
+  position: number[];
+  velocity: number[];
+  effort: number[];
+}
+
+export interface BatteryState {
+  header: Header;
+  voltage: number;
+  temperature: number;
+  current: number;
+  charge: number;
+  capacity: number;
+  percentage: number;
+  power_supply_status: number;
+  power_supply_health: number;
+  power_supply_technology: number;
+  present: boolean;
+}
+
+// HRIStudio specific messages
+export interface HRICommand {
+  action_id: string;
+  action_type: string;
+  parameters: Record<string, any>;
+  timeout: number;
+}
+
+export interface HRIResponse {
+  action_id: string;
+  success: boolean;
+  message: string;
+  data: Record<string, any>;
+  duration_ms: number;
+}
+
+export interface HRIState {
+  robot_id: string;
+  connected: boolean;
+  battery: BatteryState;
+  pose: Pose;
+  joint_states: JointState;
+  custom_data: Record<string, any>;
+}
+```
+
+## ROS2 Robot Plugin Implementation
+
+### Base ROS2 Plugin
+
+`src/lib/plugins/ros2/base-plugin.ts`:
+
+```typescript
+import { RobotPlugin, ActionDefinition, ActionResult, RobotState } from '@/lib/plugins/types';
+import { rosConnection } from '@/lib/ros/connection';
+import { HRICommand, HRIResponse, HRIState, Twist } from '@/lib/ros/types';
+import ROSLIB from 'roslib';
+import { z } from 'zod';
+
+export abstract class BaseROS2Plugin implements RobotPlugin {
+  abstract id: string;
+  abstract name: string;
+  abstract version: string;
+  abstract robotId: string;
+  
+  protected namespace: string = '/hristudio';
+  protected commandTopic: ROSLIB.Topic | null = null;
+  protected stateTopic: ROSLIB.Topic | null = null;
+  protected currentState: HRIState | null = null;
+  protected pendingCommands: Map<string, (response: HRIResponse) => void> = new Map();
+
+  abstract configSchema: z.ZodSchema;
+  abstract defaultConfig: Record<string, any>;
+  abstract actions: ActionDefinition[];
+
+  async initialize(config: any): Promise<void> {
+    // Validate config
+    this.configSchema.parse(config);
+    
+    // Set namespace if provided
+    if (config.namespace) {
+      this.namespace = config.namespace;
+    }
+  }
+
+  async connect(): Promise<boolean> {
+    try {
+      await rosConnection.connect();
+      
+      const ros = rosConnection.getRos();
+      if (!ros) return false;
+
+      // Subscribe to robot state
+      this.stateTopic = new ROSLIB.Topic({
+        ros,
+        name: `${this.namespace}/robot_state`,
+        messageType: 'hristudio_msgs/HRIState'
+      });
+
+      this.stateTopic.subscribe((state: HRIState) => {
+        this.currentState = state;
+      });
+
+      // Create command publisher
+      this.commandTopic = new ROSLIB.Topic({
+        ros,
+        name: `${this.namespace}/commands`,
+        messageType: 'hristudio_msgs/HRICommand'
+      });
+
+      // Subscribe to responses
+      const responseTopic = new ROSLIB.Topic({
+        ros,
+        name: `${this.namespace}/responses`,
+        messageType: 'hristudio_msgs/HRIResponse'
+      });
+
+      responseTopic.subscribe((response: HRIResponse) => {
+        const handler = this.pendingCommands.get(response.action_id);
+        if (handler) {
+          handler(response);
+          this.pendingCommands.delete(response.action_id);
+        }
+      });
+
+      // Wait for initial state
+      await this.waitForState(5000);
+      
+      return true;
+    } catch (error) {
+      console.error('Failed to connect to ROS2:', error);
+      return false;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.stateTopic) {
+      this.stateTopic.unsubscribe();
+      this.stateTopic = null;
+    }
+    
+    if (this.commandTopic) {
+      this.commandTopic = null;
+    }
+    
+    this.currentState = null;
+    this.pendingCommands.clear();
+  }
+
+  async executeAction(action: ActionDefinition, params: any): Promise<ActionResult> {
+    if (!this.commandTopic) {
+      return {
+        success: false,
+        error: 'Not connected to robot',
+        duration: 0
+      };
+    }
+
+    const startTime = Date.now();
+    const actionId = `${action.id}_${Date.now()}`;
+
+    try {
+      // Validate parameters
+      const validatedParams = action.parameterSchema.parse(params);
+
+      // Create command
+      const command: HRICommand = {
+        action_id: actionId,
+        action_type: action.id,
+        parameters: validatedParams,
+        timeout: action.timeout || 30000
+      };
+
+      // Send command and wait for response
+      const response = await this.sendCommand(command);
+
+      return {
+        success: response.success,
+        data: response.data,
+        error: response.success ? undefined : response.message,
+        duration: Date.now() - startTime
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        duration: Date.now() - startTime
+      };
+    }
+  }
+
+  async getState(): Promise<RobotState> {
+    if (!this.currentState) {
+      return {
+        connected: false
+      };
+    }
+
+    return {
+      connected: this.currentState.connected,
+      battery: this.currentState.battery.percentage,
+      position: {
+        x: this.currentState.pose.position.x,
+        y: this.currentState.pose.position.y,
+        z: this.currentState.pose.position.z
+      },
+      sensors: {
+        jointStates: this.currentState.joint_states,
+        ...this.currentState.custom_data
+      }
+    };
+  }
+
+  protected sendCommand(command: HRICommand): Promise<HRIResponse> {
+    return new Promise((resolve, reject) => {
+      if (!this.commandTopic) {
+        reject(new Error('Command topic not initialized'));
+        return;
+      }
+
+      // Set timeout
+      const timeout = setTimeout(() => {
+        this.pendingCommands.delete(command.action_id);
+        reject(new Error('Command timeout'));
+      }, command.timeout);
+
+      // Store handler
+      this.pendingCommands.set(command.action_id, (response) => {
+        clearTimeout(timeout);
+        resolve(response);
+      });
+
+      // Publish command
+      this.commandTopic.publish(command);
+    });
+  }
+
+  protected async waitForState(timeoutMs: number): Promise<void> {
+    const startTime = Date.now();
+    while (!this.currentState && Date.now() - startTime < timeoutMs) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    if (!this.currentState) {
+      throw new Error('Timeout waiting for robot state');
+    }
+  }
+
+  // Helper methods for common robot controls
+  protected async moveBase(linear: number, angular: number): Promise<ActionResult> {
+    const ros = rosConnection.getRos();
+    if (!ros) {
+      return { success: false, error: 'Not connected', duration: 0 };
+    }
+
+    const cmdVelTopic = new ROSLIB.Topic({
+      ros,
+      name: '/cmd_vel',
+      messageType: 'geometry_msgs/Twist'
+    });
+
+    const twist: Twist = {
+      linear: { x: linear, y: 0, z: 0 },
+      angular: { x: 0, y: 0, z: angular }
+    };
+
+    cmdVelTopic.publish(twist);
+    
+    return { success: true, duration: 0 };
+  }
+}
+```
+
+### TurtleBot3 Plugin Example
+
+`src/lib/plugins/robots/turtlebot3.ts`:
+
+```typescript
+import { BaseROS2Plugin } from '../ros2/base-plugin';
+import { ActionDefinition } from '@/lib/plugins/types';
+import { z } from 'zod';
+
+export class TurtleBot3Plugin extends BaseROS2Plugin {
+  id = 'turtlebot3-burger';
+  name = 'TurtleBot3 Burger';
+  version = '1.0.0';
+  robotId = 'turtlebot3';
+
+  configSchema = z.object({
+    namespace: z.string().default('/tb3'),
+    maxLinearVelocity: z.number().default(0.22),
+    maxAngularVelocity: z.number().default(2.84),
+    rosbridge_url: z.string().url().optional(),
+  });
+
+  defaultConfig = {
+    namespace: '/tb3',
+    maxLinearVelocity: 0.22,
+    maxAngularVelocity: 2.84,
+  };
+
+  actions: ActionDefinition[] = [
+    {
+      id: 'move_forward',
+      name: 'Move Forward',
+      description: 'Move the robot forward',
+      category: 'movement',
+      icon: 'arrow-up',
+      parameterSchema: z.object({
+        distance: z.number().min(0).max(5).describe('Distance in meters'),
+        speed: z.number().min(0).max(0.22).default(0.1).describe('Speed in m/s'),
+      }),
+      timeout: 30000,
+      retryable: true,
+    },
+    {
+      id: 'turn',
+      name: 'Turn',
+      description: 'Turn the robot',
+      category: 'movement',
+      icon: 'rotate-cw',
+      parameterSchema: z.object({
+        angle: z.number().min(-180).max(180).describe('Angle in degrees'),
+        speed: z.number().min(0).max(2.84).default(0.5).describe('Angular speed in rad/s'),
+      }),
+      timeout: 20000,
+      retryable: true,
+    },
+    {
+      id: 'speak',
+      name: 'Speak',
+      description: 'Make the robot speak using TTS',
+      category: 'interaction',
+      icon: 'volume-2',
+      parameterSchema: z.object({
+        text: z.string().max(500).describe('Text to speak'),
+        voice: z.enum(['male', 'female']).default('female'),
+        speed: z.number().min(0.5).max(2).default(1),
+      }),
+      timeout: 60000,
+      retryable: false,
+    },
+    {
+      id: 'led_color',
+      name: 'Set LED Color',
+      description: 'Change the robot LED color',
+      category: 'feedback',
+      icon: 'lightbulb',
+      parameterSchema: z.object({
+        color: z.enum(['red', 'green', 'blue', 'yellow', 'white', 'off']),
+        duration: z.number().min(0).max(60).default(0).describe('Duration in seconds (0 = permanent)'),
+      }),
+      timeout: 5000,
+      retryable: true,
+    },
+  ];
+
+  async initialize(config: any): Promise<void> {
+    await super.initialize(config);
+    
+    // TurtleBot3 specific initialization
+    if (config.rosbridge_url) {
+      // Override default rosbridge URL if provided
+      process.env.NEXT_PUBLIC_ROSBRIDGE_URL = config.rosbridge_url;
+    }
+  }
+
+  // Override executeAction for robot-specific implementations
+  async executeAction(action: ActionDefinition, params: any): Promise<ActionResult> {
+    // For movement actions, we can use direct topic publishing
+    // for better real-time control
+    if (action.id === 'move_forward') {
+      return this.moveForward(params.distance, params.speed);
+    } else if (action.id === 'turn') {
+      return this.turn(params.angle, params.speed);
+    }
+    
+    // For other actions, use the base implementation
+    return super.executeAction(action, params);
+  }
+
+  private async moveForward(distance: number, speed: number): Promise<ActionResult> {
+    const startTime = Date.now();
+    const duration = (distance / speed) * 1000; // Convert to milliseconds
+    
+    // Start moving
+    await this.moveBase(speed, 0);
+    
+    // Wait for movement to complete
+    await new Promise(resolve => setTimeout(resolve, duration));
+    
+    // Stop
+    await this.moveBase(0, 0);
+    
+    return {
+      success: true,
+      data: { distance, speed },
+      duration: Date.now() - startTime
+    };
+  }
+
+  private async turn(angleDegrees: number, speed: number): Promise<ActionResult> {
+    const startTime = Date.now();
+    const angleRad = (angleDegrees * Math.PI) / 180;
+    const duration = Math.abs(angleRad / speed) * 1000;
+    
+    // Start turning (negative for clockwise)
+    const angularVel = angleDegrees > 0 ? speed : -speed;
+    await this.moveBase(0, angularVel);
+    
+    // Wait for turn to complete
+    await new Promise(resolve => setTimeout(resolve, duration));
+    
+    // Stop
+    await this.moveBase(0, 0);
+    
+    return {
+      success: true,
+      data: { angle: angleDegrees, speed },
+      duration: Date.now() - startTime
+    };
+  }
+}
+```
+
+## ROS2 Node for HRIStudio
+
+For robots to work with HRIStudio, they need a ROS2 node that implements the HRIStudio protocol:
+
+`hristudio_robot_node.py`:
+
+```python
+#!/usr/bin/env python3
+import rclpy
+from rclpy.node import Node
+from std_msgs.msg import String
+from geometry_msgs.msg import Twist
+from sensor_msgs.msg import JointState, BatteryState
+from hristudio_msgs.msg import HRICommand, HRIResponse, HRIState
+import json
+import time
+from threading import Thread
+
+class HRIStudioRobotNode(Node):
+    def __init__(self):
+        super().__init__('hristudio_robot_node')
+        
+        # Publishers
+        self.state_pub = self.create_publisher(HRIState, '/hristudio/robot_state', 10)
+        self.response_pub = self.create_publisher(HRIResponse, '/hristudio/responses', 10)
+        
+        # Subscribers
+        self.command_sub = self.create_subscription(
+            HRICommand,
+            '/hristudio/commands',
+            self.command_callback,
+            10
+        )
+        
+        # Robot control publishers
+        self.cmd_vel_pub = self.create_publisher(Twist, '/cmd_vel', 10)
+        
+        # State update timer
+        self.state_timer = self.create_timer(0.1, self.publish_state)
+        
+        # Action handlers
+        self.action_handlers = {
+            'move_forward': self.handle_move_forward,
+            'turn': self.handle_turn,
+            'speak': self.handle_speak,
+            'led_color': self.handle_led_color,
+        }
+        
+        self.get_logger().info('HRIStudio Robot Node started')
+    
+    def command_callback(self, msg):
+        """Handle incoming commands from HRIStudio"""
+        self.get_logger().info(f'Received command: {msg.action_type}')
+        
+        # Execute action in separate thread to avoid blocking
+        thread = Thread(target=self.execute_command, args=(msg,))
+        thread.start()
+    
+    def execute_command(self, command):
+        """Execute a command and send response"""
+        start_time = time.time()
+        response = HRIResponse()
+        response.action_id = command.action_id
+        
+        try:
+            # Parse parameters
+            params = json.loads(command.parameters) if isinstance(command.parameters, str) else command.parameters
+            
+            # Execute action
+            if command.action_type in self.action_handlers:
+                result = self.action_handlers[command.action_type](params)
+                response.success = result['success']
+                response.message = result.get('message', '')
+                response.data = json.dumps(result.get('data', {}))
+            else:
+                response.success = False
+                response.message = f'Unknown action type: {command.action_type}'
+        
+        except Exception as e:
+            response.success = False
+            response.message = str(e)
+            self.get_logger().error(f'Error executing command: {e}')
+        
+        response.duration_ms = int((time.time() - start_time) * 1000)
+        self.response_pub.publish(response)
+    
+    def publish_state(self):
+        """Publish current robot state"""
+        state = HRIState()
+        state.robot_id = 'turtlebot3'
+        state.connected = True
+        
+        # Add current sensor data
+        # This would come from actual robot sensors
+        state.battery.percentage = 85.0
+        state.pose.position.x = 0.0
+        state.pose.position.y = 0.0
+        state.pose.orientation.w = 1.0
+        
+        self.state_pub.publish(state)
+    
+    def handle_move_forward(self, params):
+        """Move robot forward"""
+        distance = params.get('distance', 0)
+        speed = params.get('speed', 0.1)
+        
+        # Calculate duration
+        duration = distance / speed
+        
+        # Publish velocity command
+        twist = Twist()
+        twist.linear.x = speed
+        self.cmd_vel_pub.publish(twist)
+        
+        # Wait for movement to complete
+        time.sleep(duration)
+        
+        # Stop
+        twist.linear.x = 0.0
+        self.cmd_vel_pub.publish(twist)
+        
+        return {
+            'success': True,
+            'data': {'distance': distance, 'speed': speed}
+        }
+    
+    def handle_turn(self, params):
+        """Turn robot"""
+        angle = params.get('angle', 0)
+        speed = params.get('speed', 0.5)
+        
+        # Convert to radians
+        angle_rad = angle * 3.14159 / 180
+        duration = abs(angle_rad) / speed
+        
+        # Publish velocity command
+        twist = Twist()
+        twist.angular.z = speed if angle > 0 else -speed
+        self.cmd_vel_pub.publish(twist)
+        
+        # Wait for turn to complete
+        time.sleep(duration)
+        
+        # Stop
+        twist.angular.z = 0.0
+        self.cmd_vel_pub.publish(twist)
+        
+        return {
+            'success': True,
+            'data': {'angle': angle, 'speed': speed}
+        }
+    
+    def handle_speak(self, params):
+        """Text to speech"""
+        text = params.get('text', '')
+        # Implement TTS here
+        self.get_logger().info(f'Speaking: {text}')
+        return {'success': True, 'data': {'text': text}}
+    
+    def handle_led_color(self, params):
+        """Set LED color"""
+        color = params.get('color', 'off')
+        # Implement LED control here
+        self.get_logger().info(f'Setting LED to: {color}')
+        return {'success': True, 'data': {'color': color}}
+
+def main(args=None):
+    rclpy.init(args=args)
+    node = HRIStudioRobotNode()
+    rclpy.spin(node)
+    node.destroy_node()
+    rclpy.shutdown()
+
+if __name__ == '__main__':
+    main()
+```
+
+## Security Considerations
+
+### 1. Authentication
+- Use SSL/TLS for rosbridge connections in production
+- Implement token-based authentication for rosbridge
+- Restrict topic/service access patterns
+
+### 2. Network Security
+- Use VPN or SSH tunnels for remote robot connections
+- Implement firewall rules to restrict rosbridge access
+- Use separate network segments for robot communication
+
+### 3. Message Validation
+- Validate all incoming messages on the robot side
+- Implement rate limiting to prevent DoS attacks
+- Sanitize string inputs to prevent injection attacks
+
+## Deployment Considerations
+
+### Local Development
+- Robot and development machine on same network
+- Direct WebSocket connection to rosbridge
+- No SSL required
+
+### Production (Vercel)
+- Robot behind NAT/firewall
+- Use reverse proxy or tunnel (e.g., ngrok, Cloudflare Tunnel)
+- SSL/TLS required for secure communication
+- Consider latency for real-time control
+
+### Hybrid Approach
+- Local "robot companion" server near robot
+- Companion server connects to both robot and Vercel app
+- Reduces latency for critical operations
+- Maintains security boundaries
+
+## Testing ROS2 Integration
+
+### Unit Tests
+
+`src/lib/ros/__tests__/connection.test.ts`:
+
+```typescript
+import { RosConnection } from '../connection';
+import { vi, describe, it, expect, beforeEach } from 'vitest';
+
+vi.mock('roslib', () => ({
+  default: {
+    Ros: vi.fn().mockImplementation(() => ({
+      on: vi.fn(),
+      connect: vi.fn(),
+      close: vi.fn(),
+      isConnected: true,
+    })),
+    Topic: vi.fn(),
+    Service: vi.fn(),
+  },
+}));
+
+describe('RosConnection', () => {
+  let connection: RosConnection;
+
+  beforeEach(() => {
+    connection = new RosConnection('ws://test:9090');
+  });
+
+  it('should connect successfully', async () => {
+    await expect(connection.connect()).resolves.toBeUndefined();
+    expect(connection.isConnected()).toBe(true);
+  });
+
+  // Add more tests...
+});
+```
+
+### Integration Tests
+- Use rosbridge_server in test mode
+- Mock robot responses
+- Test error scenarios
+- Verify message formats
+
+## Performance Optimization
+
+1. **Message Throttling**: Limit frequency of state updates
+2. **Compression**: Enable PNG compression for image topics
+3. **Selective Subscriptions**: Only subscribe to needed topics
+4. **Connection Pooling**: Reuse WebSocket connections
+5. **Client-Side Caching**: Cache robot capabilities
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection Refused**
+   - Check rosbridge is running
+   - Verify firewall rules
+   - Check WebSocket URL
+
+2. **Message Type Errors**
+   - Ensure message types match between client and robot
+   - Verify ROS2 workspace is sourced
+
+3. **High Latency**
+   - Check network conditions
+   - Consider local rosbridge proxy
+   - Optimize message sizes
+
+4. **Authentication Failures**
+   - Verify SSL certificates
+   - Check authentication tokens
+   - Review rosbridge configuration

docs/_archive/ros2_naoqi.md

@@ -0,0 +1,40 @@
+🤖 NAO6 — ROS 2 Humble Topics (via naoqi_driver2)
+🏃 Motion & Odometry
+Topic	Message Type	Description
+/cmd_vel	geometry_msgs/msg/Twist	Command linear and angular base velocities (walking).
+/odom	nav_msgs/msg/Odometry	Estimated robot position and velocity.
+/move_base_simple/goal	geometry_msgs/msg/PoseStamped	Send goal poses for autonomous navigation.
+🔩 Joints & Robot State
+Topic	Message Type	Description
+/joint_states	sensor_msgs/msg/JointState	Standard ROS joint angles, velocities, efforts.
+/joint_angles	naoqi_bridge_msgs/msg/JointAnglesWithSpeed	NAO-specific joint control interface.
+/info	naoqi_bridge_msgs/msg/RobotInfo	General robot info (model, battery, language, etc.).
+🎥 Cameras
+Topic	Message Type	Description
+/camera/front/image_raw	sensor_msgs/msg/Image	Front (head) camera image stream.
+/camera/front/camera_info	sensor_msgs/msg/CameraInfo	Intrinsics for front camera.
+/camera/bottom/image_raw	sensor_msgs/msg/Image	Bottom (mouth) camera image stream.
+/camera/bottom/camera_info	sensor_msgs/msg/CameraInfo	Intrinsics for bottom camera.
+🦶 Sensors
+Topic	Message Type	Description
+/imu/torso	sensor_msgs/msg/Imu	Torso inertial measurement data.
+/bumper	naoqi_bridge_msgs/msg/Bumper	Foot bumper contact sensors.
+/hand_touch	naoqi_bridge_msgs/msg/HandTouch	Hand tactile sensors.
+/head_touch	naoqi_bridge_msgs/msg/HeadTouch	Head tactile sensors.
+/sonar/left	sensor_msgs/msg/Range	Left ultrasonic range sensor.
+/sonar/right	sensor_msgs/msg/Range	Right ultrasonic range sensor.
+🔊 Audio & Speech
+Topic	Message Type	Description
+/audio	audio_common_msgs/msg/AudioData	Raw audio input from NAO’s microphones.
+/speech	std_msgs/msg/String	Send text-to-speech commands.
+🧠 System & Diagnostics
+Topic	Message Type	Description
+/diagnostics	diagnostic_msgs/msg/DiagnosticArray	Hardware and driver status.
+/robot_description	std_msgs/msg/String	URDF description of the robot.
+/tf	tf2_msgs/msg/TFMessage	Coordinate transforms between frames.
+/parameter_events	rcl_interfaces/msg/ParameterEvent	Parameter change notifications.
+/rosout	rcl_interfaces/msg/Log	Logging output.
+✅ ROS 2 bridge status: Active
+✅ Robot model detected: NAO V6 (NAOqi 2.8.7.4)
+✅ Driver: naoqi_driver2
+✅ System confirmed working: motion, speech, camera, IMU, touch, sonar

docs/_archive/route-consolidation-summary.md

@@ -0,0 +1,264 @@
+# Route Consolidation Summary
+
+## Overview
+
+This document summarizes the comprehensive route consolidation work completed in September 2024, which transformed HRIStudio from a fragmented routing structure with duplicated global and study-specific views into a clean, study-scoped architecture.
+
+## Problem Statement
+
+### Issues with Original Architecture
+- **Route Confusion**: Duplicate routes for participants (`/participants` and `/studies/[id]/participants`) and trials (`/trials` and `/studies/[id]/trials`)
+- **Code Duplication**: Separate components for global and study-specific views with 90% overlapping functionality
+- **Navigation Inconsistency**: Users confused about where to find functionality
+- **Maintenance Burden**: Changes required updates to multiple similar components
+- **Dashboard 404**: The `/dashboard` route was incorrectly configured and not accessible
+
+### Technical Debt
+- `participants-data-table.tsx` vs `ParticipantsTable.tsx`
+- `trials-data-table.tsx` vs `TrialsTable.tsx`
+- Inconsistent breadcrumb patterns
+- Broken links in navigation dropdowns
+- Multiple creation flows for the same entities
+
+## Solution: Study-Scoped Architecture
+
+### Design Principles
+1. **Single Source of Truth**: One route and component per entity type
+2. **Logical Hierarchy**: Studies as the primary organizational unit
+3. **Consistent Navigation**: All entity management flows through studies
+4. **User-Friendly Transitions**: Helpful redirects for moved functionality
+
+### Final Route Structure
+
+```
+Global Routes (Platform-Level):
+├── /dashboard                    # Overview across all user's studies
+├── /studies                     # Study management hub
+├── /profile                     # User account management
+└── /admin                       # System administration
+
+Study-Scoped Routes (All Study-Dependent Functionality):
+├── /studies/[id]                # Study details and overview
+├── /studies/[id]/participants   # Participant management for study
+├── /studies/[id]/trials        # Trial management for study
+├── /studies/[id]/experiments    # Experiment protocols for study
+├── /studies/[id]/plugins       # Robot plugins for study
+├── /studies/[id]/analytics     # Analytics for study
+└── /studies/[id]/edit          # Study configuration
+
+Individual Entity Routes (Preserved):
+├── /trials/[trialId]           # Individual trial details
+├── /trials/[trialId]/wizard    # Trial execution interface (TO BE BUILT)
+├── /trials/[trialId]/analysis  # Trial data analysis
+├── /experiments/[id]           # Individual experiment details
+├── /experiments/[id]/edit      # Edit experiment
+└── /experiments/[id]/designer  # Visual experiment designer
+
+Helpful Redirect Routes (User-Friendly Transitions):
+├── /participants               # Redirects to study selection
+├── /trials                     # Redirects to study selection
+├── /experiments                # Redirects to study selection
+├── /plugins                    # Redirects to study selection
+└── /analytics                  # Redirects to study selection
+```
+
+## Implementation Details
+
+### 1. Complete Route Cleanup
+**Converted to Study-Scoped Routes:**
+- `/experiments` → `/studies/[id]/experiments`
+- `/plugins` → `/studies/[id]/plugins`  
+- `/plugins/browse` → `/studies/[id]/plugins/browse`
+
+**Converted to Helpful Redirects:**
+- `/participants` → Shows study selection guidance
+- `/trials` → Shows study selection guidance
+- `/experiments` → Shows study selection guidance  
+- `/plugins` → Shows study selection guidance
+- `/analytics` → Shows study selection guidance (already existed)
+
+**Eliminated Duplicates:**
+- Removed duplicate experiment creation routes
+- Consolidated plugin management to study-scoped only
+- Unified all study-dependent functionality under `/studies/[id]/`
+
+### 2. Dashboard Route Fix
+**Problem**: `/dashboard` was 404ing due to incorrect route group usage
+**Solution**: Moved dashboard from `(dashboard)` route group to explicit `/dashboard` route
+
+**Before:**
+```
+/app/(dashboard)/page.tsx  # Conflicted with /app/page.tsx for root route
+```
+
+**After:**
+```
+/app/dashboard/page.tsx    # Explicit /dashboard route
+/app/dashboard/layout.tsx  # Uses existing (dashboard) layout
+```
+
+### 3. Helpful Redirect Pages
+Created user-friendly redirect pages for moved routes:
+
+**`/participants`** → Shows explanation and redirects to studies
+**`/trials`** → Shows explanation and redirects to studies
+**`/analytics`** → Shows explanation and redirects to studies
+
+**Features:**
+- Auto-redirect if user has selected study in context
+- Clear explanation of new location
+- Maintains dashboard layout with sidebar
+- Action buttons to navigate to studies
+
+### 4. Navigation Updates
+**App Sidebar:**
+- Removed global "Participants" and "Trials" navigation items
+- Kept study-focused navigation structure
+
+**Dashboard Quick Actions:**
+- Updated to focus on study creation and browsing
+- Removed broken links to non-existent routes
+
+**Breadcrumbs:**
+- Updated all entity forms to use study-scoped routes
+- Fixed ParticipantForm and TrialForm navigation
+- Consistent hierarchy: Dashboard → Studies → [Study] → [Entity]
+
+### 5. Form and Component Updates
+**ParticipantForm:**
+- Updated all breadcrumb references to use study-scoped routes
+- Fixed redirect after deletion to go to study participants
+- Updated back/list URLs to be study-scoped
+
+**TrialForm:**
+- Similar updates to ParticipantForm
+- Fixed navigation consistency
+
+**Component Cleanup:**
+- Removed unused imports (Users, TestTube icons)
+- Fixed ESLint errors (apostrophe escaping)
+- Removed duplicate functionality
+
+### 6. Custom 404 Handling
+**Created:** `/app/(dashboard)/not-found.tsx`
+- Uses dashboard layout (sidebar intact)
+- User-friendly error message
+- Navigation options to recover
+- Consistent with platform design
+
+## Benefits Achieved
+
+### 1. Architectural Consistency  
+- **Complete Study-Scoped Architecture**: All study-dependent functionality properly organized
+- **Eliminated Route Confusion**: No more duplicate global/study routes
+- **Clear Mental Model**: Platform-level vs Study-level functionality clearly separated
+- **Unified Navigation Logic**: Single set of breadcrumb patterns
+- **Reduced Maintenance**: Changes only need to be made in one place
+
+### 2. Improved User Experience
+- **Logical Flow**: Studies → Participants/Trials/Analytics makes intuitive sense
+- **Reduced Confusion**: No more "where do I find participants?" questions
+- **Helpful Transitions**: Users with bookmarks get guided to new locations
+- **Consistent Interface**: All entity management follows same patterns
+
+### 3. Better Architecture
+- **Single Responsibility**: Each route has one clear purpose
+- **Hierarchical Organization**: Reflects real-world research workflow
+- **Maintainable Structure**: Clear separation of concerns
+- **Type Safety**: All routes properly typed with no compilation errors
+
+### 4. Enhanced Navigation
+- **Clear Hierarchy**: Dashboard → Studies → Study Details → Entity Management
+- **Breadcrumb Consistency**: All pages follow same navigation pattern
+- **Working Links**: All navigation items point to valid routes
+- **Responsive Design**: Layout works across different screen sizes
+
+## Migration Guide
+
+### For Users
+1. **Bookmarks**: Update any bookmarks from global routes (`/experiments`, `/plugins`, etc.) to study-specific routes
+2. **Workflow**: Access all study-dependent functionality through studies rather than global views
+3. **Navigation**: Use sidebar study-aware navigation - select study context first, then access study-specific functionality
+4. **Redirects**: Helpful guidance pages automatically redirect when study context is available
+
+### For Developers
+1. **Components**: Use study-scoped routes for all study-dependent functionality
+2. **Routing**: All study-dependent entity links should go through `/studies/[id]/` structure
+3. **Forms**: Use study-scoped back/redirect URLs  
+4. **Navigation**: Sidebar automatically shows study-dependent items when study is selected
+5. **Context**: Components automatically receive study context through URL parameters
+
+## Testing Results
+
+### Before Complete Cleanup
+- Route duplication between global and study-scoped functionality
+- Navigation confusion about where to find study-dependent features  
+- Inconsistent sidebar behavior based on study selection
+
+### After Complete Cleanup
+- `/dashboard` → ✅ Global overview with study filtering
+- `/studies` → ✅ Study management hub
+- `/profile` → ✅ User account management
+- `/admin` → ✅ System administration
+- **Study-Scoped Functionality:**
+  - `/studies/[id]/participants` → ✅ Study participants
+  - `/studies/[id]/trials` → ✅ Study trials  
+  - `/studies/[id]/experiments` → ✅ Study experiments
+  - `/studies/[id]/plugins` → ✅ Study plugins
+  - `/studies/[id]/analytics` → ✅ Study analytics
+- **Helpful Redirects:**
+  - `/participants`, `/trials`, `/experiments`, `/plugins`, `/analytics` → ✅ User guidance
+
+### Quality Metrics
+- **TypeScript**: ✅ Zero compilation errors
+- **ESLint**: ✅ All linting issues resolved
+- **Build**: ✅ Successful production builds
+- **Navigation**: ✅ All links functional
+- **Layout**: ✅ Consistent sidebar across all routes
+
+## Lessons Learned
+
+### Route Group Usage
+- Route groups `(name)` are for organization, not URL structure
+- Use explicit routes for specific URLs like `/dashboard`
+- Be careful about root route conflicts
+
+### Component Architecture
+- Prefer single components with conditional logic over duplicates
+- Use consistent naming patterns across similar components
+- Implement proper TypeScript typing for all route parameters
+
+### User Experience
+- Provide helpful redirect pages for moved functionality
+- Maintain layout consistency during navigation changes
+- Clear breadcrumb hierarchies improve user orientation
+
+### Migration Strategy
+- Fix routing issues before making major changes
+- Update all navigation references systematically
+- Test thoroughly after each phase of changes
+
+## Future Considerations
+
+### Potential Enhancements
+1. **Study Context Persistence**: Remember selected study across sessions
+2. **Quick Study Switching**: Add study switcher to global navigation
+3. **Advanced Analytics**: Study comparison tools across multiple studies
+4. **Bulk Operations**: Multi-study management capabilities
+
+### Monitoring
+- Track 404 errors to identify any missed route references
+- Monitor user behavior to ensure new navigation is intuitive
+- Collect feedback on the study-scoped workflow
+
+## Conclusion
+
+The route consolidation successfully transformed HRIStudio from a confusing dual-route system into a clean, study-scoped architecture. This change eliminates significant technical debt, improves user experience, and creates a more maintainable codebase while preserving all functionality.
+
+The implementation demonstrates best practices for large-scale routing refactors in Next.js applications, including helpful user transitions, comprehensive testing, and maintaining backward compatibility through intelligent redirects.
+
+**Status**: Complete ✅  
+**Impact**: Major improvement to platform usability and maintainability  
+**Technical Debt Reduction**: ~60% reduction in duplicate routing/component code  
+**Architectural Consistency**: 100% study-dependent functionality properly scoped  
+**Navigation Clarity**: Clear separation of platform-level vs study-level functionality

docs/_archive/thesis-project-priorities.md

@@ -0,0 +1,90 @@
+# HRIStudio Thesis Implementation - Fall 2025
+
+**Sean O'Connor - CS Honors Thesis**  
+**Advisor**: L. Felipe Perrone  
+**Defense**: April 2026
+
+## Implementation Status
+
+Core platform infrastructure exists but MVP requires wizard interface implementation and robot control integration for functional trials.
+
+## Fall Development Sprint (10-12 weeks)
+
+| Sprint | Focus Area | Key Tasks | Success Metric |
+|--------|------------|-----------|----------------|
+| 1 (3 weeks) | Wizard Interface MVP | Trial control interface<br/>Step navigation<br/>Action execution buttons | Functional wizard interface for trial control |
+| 2 (4 weeks) | Robot Integration | NAO6 API integration<br/>Basic action implementation<br/>Error handling and recovery | Wizard button → robot action |
+| 3 (3 weeks) | Real-time Infrastructure | WebSocket server implementation<br/>Multi-client session management<br/>Event broadcasting system | Multiple users connected to live trial |
+| 4 (2 weeks) | Integration Testing | Complete workflow validation<br/>Reliability testing<br/>Mock robot mode | 30-minute trials without crashes |
+
+## User Study Preparation (4-5 weeks)
+
+| Task Category | Deliverables | Effort |
+|---------------|--------------|--------|
+| Study Design | Reference experiment selection<br/>Equivalent implementations (HRIStudio + Choregraphe)<br/>Protocol validation | 3 weeks |
+| Research Setup | IRB application submission<br/>Training material development<br/>Participant recruitment | 2 weeks |
+
+## MVP Implementation Priorities
+
+| Priority | Component | Current State | Target State |
+|----------|-----------|---------------|-------------|
+| **P0** | Wizard Interface | Design exists, needs implementation | Functional trial control interface |
+| **P0** | Robot Control | Simulated responses only | Live NAO6 hardware control |
+| **P0** | Real-time Communication | Client hooks exist, no server | Multi-user live trial coordination |
+| **P1** | Trial Execution | Basic framework exists | Integrated with wizard + robot hardware |
+| **P2** | Data Capture | Basic logging | Comprehensive real-time events |
+
+## Success Criteria by Phase
+
+### MVP Complete (10-12 weeks)
+- [ ] Wizard interface allows trial control and step navigation
+- [ ] Psychology researcher clicks interface → NAO6 performs action
+- [ ] Multiple observers watch trial with live updates
+- [ ] System remains stable during full experimental sessions
+- [ ] All trial events captured with timestamps
+
+### Study Ready (14-17 weeks)
+- [ ] Reference experiment works identically in both platforms
+- [ ] IRB approval obtained for comparative study
+- [ ] 10-12 participants recruited from target disciplines
+- [ ] Platform validated with non-technical users
+
+## MVP Backlog - Priority Breakdown
+
+### P0 - Critical MVP Features
+| Story | Effort | Definition of Done |
+|-------|--------|-------------------|
+| Wizard interface trial control | 2 weeks | Interface for starting/stopping trials, navigating steps |
+| Action execution buttons | 1 week | Buttons for robot actions with real-time feedback |
+| NAO6 API integration | 3 weeks | Successfully connect to NAO6, execute basic commands |
+| Basic robot actions | 2 weeks | Speech, movement, posture actions working |
+| WebSocket server implementation | 2 weeks | Server accepts connections, handles authentication |
+| Multi-client session management | 1 week | Multiple users can join same trial session |
+
+### P1 - High Priority Features  
+| Story | Effort | Definition of Done |
+|-------|--------|-------------------|
+| Event broadcasting system | 1 week | Actions broadcast to all connected clients |
+| Robot status monitoring | 1 week | Connection status, error detection |
+| End-to-end workflow testing | 1.5 weeks | Complete trial execution with real robot |
+
+### P2 - Backlog (Post-MVP)
+| Story | Effort | Definition of Done |
+|-------|--------|-------------------|
+| Connection recovery mechanisms | 1 week | Auto-reconnect on disconnect, graceful fallback |
+| Mock robot development mode | 0.5 weeks | Development without hardware dependency |
+| Performance optimization | 0.5 weeks | Response times under acceptable thresholds |
+| Advanced data capture | 1 week | Comprehensive real-time event logging |
+
+## User Study Framework
+
+**Participants**: 10-12 researchers from Psychology/Education  
+**Task**: Recreate published HRI experiment  
+**Comparison**: HRIStudio (experimental) vs Choregraphe (control)  
+**Measures**: Protocol accuracy, completion time, user experience ratings
+
+## Implementation Strategy
+
+Core platform infrastructure exists but wizard interface needs full implementation alongside robot integration. Focus on MVP that enables basic trial execution with real robot control.
+
+**Critical Path**: Wizard interface → WebSocket server → NAO6 integration → end-to-end testing → user study execution

docs/_archive/trial-system-overhaul.md

@@ -0,0 +1,237 @@
+# Trial System Overhaul - Complete
+
+## Overview
+
+The HRIStudio trial system has been completely overhauled to use the established panel-based design pattern from the experiment designer. This transformation brings consistency with the platform's visual programming interface and provides an optimal layout for wizard-controlled trial execution.
+
+## Motivation
+
+### Problems with Previous Implementation
+- **Design Inconsistency**: Trial interface didn't match experiment designer's panel layout
+- **Missing Breadcrumbs**: Trial pages lacked proper navigation breadcrumbs
+- **UI Flashing**: Rapid WebSocket reconnection attempts caused disruptive visual feedback
+- **Layout Inefficiency**: Information not optimally organized for wizard workflow
+- **Component Divergence**: Trial components didn't follow established patterns
+
+### Goals
+- Adopt panel-based layout consistent with experiment designer
+- Implement proper breadcrumb navigation like other entity pages
+- Optimize information architecture for wizard interface workflow
+- Stabilize real-time connection indicators
+- Maintain all functionality while improving user experience
+
+## Implementation Changes
+
+### 1. Wizard Interface Redesign
+
+**Before: EntityView Layout**
+```tsx
+<EntityView>
+  <EntityViewHeader 
+    title="Trial Execution"
+    subtitle="Experiment • Participant"
+    icon="Activity"
+    status={{ label: "In Progress", variant: "secondary" }}
+  />
+  
+  <div className="grid grid-cols-1 gap-8 lg:grid-cols-4">
+    <div className="lg:col-span-3 space-y-8">
+      <EntityViewSection title="Current Step" icon="Play">
+        {/* Step execution controls */}
+      </EntityViewSection>
+      <EntityViewSection title="Wizard Controls" icon="Zap">
+        {/* Action controls */}
+      </EntityViewSection>
+    </div>
+    
+    <EntityViewSidebar>
+      <EntityViewSection title="Robot Status" icon="Bot">
+        {/* Robot monitoring */}
+      </EntityViewSection>
+      <EntityViewSection title="Participant" icon="User">
+        {/* Participant info */}
+      </EntityViewSection>
+      <EntityViewSection title="Live Events" icon="Clock">
+        {/* Events log */}
+      </EntityViewSection>
+    </EntityViewSidebar>
+  </div>
+</EntityView>
+```
+
+**After: Panel-Based Layout**
+```tsx
+<div className="flex h-screen flex-col">
+  <PageHeader
+    title="Wizard Control"
+    description={`${trial.experiment.name} • ${trial.participant.participantCode}`}
+    icon={Activity}
+  />
+
+  <PanelsContainer
+    left={leftPanel}
+    center={centerPanel}
+    right={rightPanel}
+    showDividers={true}
+    className="min-h-0 flex-1"
+  />
+</div>
+```
+
+### 2. Panel-Based Architecture
+
+**Left Panel - Trial Controls & Navigation**
+- **Trial Status**: Visual status indicator with elapsed time and progress
+- **Trial Controls**: Start/Next Step/Complete/Abort buttons
+- **Step List**: Visual step progression with current position highlighted
+- **Compact Design**: Optimized for quick access to essential controls
+
+**Center Panel - Main Execution Area** 
+- **Current Step Display**: Prominent step name, description, and navigation
+- **Wizard Actions**: Full-width action controls interface
+- **Connection Alerts**: Stable WebSocket status indicators
+- **Trial State Management**: Scheduled/In Progress/Completed views
+
+**Right Panel - Monitoring & Context**
+- **Robot Status**: Real-time robot monitoring with mock integration
+- **Participant Info**: Essential participant context
+- **Live Events**: Scrollable event log with timestamps
+- **Connection Details**: Technical information and trial metadata
+
+### 3. Breadcrumb Navigation
+```typescript
+useBreadcrumbsEffect([
+  { label: "Dashboard", href: "/dashboard" },
+  { label: "Studies", href: "/studies" },
+  { label: studyData.name, href: `/studies/${studyData.id}` },
+  { label: "Trials", href: `/studies/${studyData.id}/trials` },
+  { label: `Trial ${trial.participant.participantCode}`, href: `/trials/${trial.id}` },
+  { label: "Wizard Control" },
+]);
+```
+
+### 4. Component Integration
+
+**PanelsContainer Integration**
+- Reused proven layout system from experiment designer
+- Drag-resizable panels with overflow containment
+- Consistent spacing and visual hierarchy
+- Full-height layout optimization
+
+**PageHeader Standardization**
+- Matches pattern used across all entity pages
+- Proper icon and description placement
+- Consistent typography and spacing
+
+**WebSocket Stability Improvements**
+```typescript
+// Stable connection status in right panel
+<Badge variant={wsConnected ? "default" : "secondary"}>
+  {wsConnected ? "Connected" : "Polling"}
+</Badge>
+```
+
+**Development Mode Optimization**
+- Disabled aggressive reconnection attempts in development
+- Stable "Polling Mode" indicator instead of flashing states
+- Clear messaging about development limitations
+
+## Technical Benefits
+
+### 1. Visual Consistency
+- **Layout Alignment**: Matches experiment designer's panel-based architecture exactly
+- **Component Reuse**: Leverages proven PanelsContainer and PageHeader patterns
+- **Design Language**: Consistent with platform's visual programming interface
+- **Professional Appearance**: Enterprise-grade visual quality throughout
+
+### 2. Information Architecture
+- **Wizard-Optimized Layout**: Left panel for quick controls, center for main workflow
+- **Contextual Grouping**: Related information grouped in dedicated panels
+- **Screen Space Optimization**: Resizable panels adapt to user preferences
+- **Focus Management**: Clear visual priority for execution vs monitoring
+
+### 3. Code Quality
+- **Pattern Consistency**: Follows established experiment designer patterns
+- **Component Reuse**: 90% code sharing with existing panel system
+- **Type Safety**: Complete TypeScript compatibility maintained
+- **Maintainability**: Easier to update and extend using proven patterns
+
+### 4. User Experience
+- **Familiar Navigation**: Proper breadcrumbs like all other entity pages
+- **Consistent Interface**: Matches experiment designer's interaction patterns
+- **Stable UI**: No more flashing connection indicators
+- **Professional Feel**: Seamless integration with platform design language
+
+## Mock Robot Integration
+
+### Development Capabilities
+- **TurtleBot3 Simulation**: Complete robot status simulation
+- **Real-time Updates**: Battery level, signal strength, position tracking
+- **Sensor Monitoring**: Lidar, camera, IMU, odometry status indicators
+- **No Dependencies**: Works without ROS2 or physical hardware
+
+### Plugin Architecture Ready
+- **Action Definitions**: Abstract robot capabilities with parameter schemas
+- **Multiple Protocols**: RESTful APIs, ROS2 (via rosbridge), custom implementations
+- **Repository System**: Centralized plugin distribution and management
+- **Type Safety**: Full TypeScript support for all robot action definitions
+
+## Production Readiness
+
+### Build Status
+- ✅ **Zero TypeScript Errors**: Complete type safety maintained
+- ✅ **Successful Build**: Production-ready compilation (13.8 kB wizard bundle)
+- ✅ **Lint Compliance**: Clean code quality standards
+- ✅ **Panel Integration**: Seamless integration with experiment designer patterns
+
+### Feature Completeness
+- ✅ **Panel-Based Layout**: Three-panel wizard interface with resizable sections
+- ✅ **Proper Navigation**: Breadcrumb navigation matching platform standards
+- ✅ **Trial Lifecycle**: Create, schedule, execute, complete, analyze
+- ✅ **Real-time Execution**: WebSocket-based live updates with polling fallback
+- ✅ **Wizard Controls**: Comprehensive action controls and intervention logging
+- ✅ **Data Capture**: Complete event logging and trial progression tracking
+- ✅ **Status Monitoring**: Robot status, participant context, live events
+
+### User Experience Quality
+- ✅ **Visual Consistency**: Matches experiment designer's panel architecture
+- ✅ **Responsive Design**: Drag-resizable panels adapt to user preferences
+- ✅ **Stable Interactions**: No UI flashing or disruptive state changes
+- ✅ **Intuitive Navigation**: Proper breadcrumbs and familiar interaction patterns
+
+## Development Experience
+
+### Testing Capabilities
+- **Complete Workflow**: Test entire trial process with mock robots
+- **Realistic Simulation**: Robot status updates and sensor monitoring
+- **Development Mode**: Stable UI without WebSocket connection requirements
+- **Data Validation**: All trial data capture and event logging functional
+
+### Integration Points
+- **Experiment Designer**: Seamless integration with visual protocol creation
+- **Study Management**: Proper context and team collaboration
+- **Participant System**: Complete demographic and consent integration
+- **Plugin System**: Ready for robot platform integration when needed
+
+## Future Enhancements
+
+### When ROS2 Integration Needed
+- WebSocket infrastructure is production-ready
+- Plugin architecture supports immediate ROS2 integration
+- rosbridge protocol implementation documented
+- No architectural changes required
+
+### Potential Improvements
+- Enhanced step configuration modals
+- Advanced workflow validation
+- Additional robot platform plugins
+- Enhanced data visualization in analysis pages
+
+## Summary
+
+The trial system overhaul represents a significant improvement in both user experience and code quality. By adopting the panel-based architecture from the experiment designer, the trial system now provides a familiar, professional interface that feels naturally integrated with the platform's visual programming paradigm. The stable WebSocket handling, proper breadcrumb navigation, and optimized wizard workflow provide a solid foundation for conducting HRI research.
+
+**Status**: Complete and production-ready
+**Architecture**: Panel-based layout matching experiment designer patterns
+**Impact**: Major improvement in consistency, usability, and professional appearance
+**Next Phase**: Platform is ready for research team deployment and use

docs/_archive/wizard-interface-final.md

@@ -0,0 +1,221 @@
+# Wizard Interface - Final Implementation Summary
+
+## Overview
+The Wizard Interface has been completely redesigned from a cluttered multi-section layout to a clean, professional single-window tabbed interface. All issues have been resolved including connection error flashing, duplicate headers, custom background colors, and full-width buttons.
+
+## ✅ Issues Resolved
+
+### 1. Single Window Design
+- **Before**: Multi-section scrolling layout with sidebar requiring vertical scrolling
+- **After**: Compact tabbed interface with 5 organized tabs fitting in single window
+- **Result**: All functionality accessible without scrolling, improved workflow efficiency
+
+### 2. Removed Duplicate Headers
+- **Issue**: Cards had their own headers when wrapped in EntityViewSection
+- **Solution**: Removed redundant Card components, used simple divs with proper styling
+- **Components Fixed**: ParticipantInfo, RobotStatus, all wizard components
+
+### 3. Fixed Connection Error Flashing
+- **Issue**: WebSocket error alert would flash during connection attempts
+- **Solution**: Added proper conditions: `{wsError && wsError.length > 0 && !wsConnecting && (...)`
+- **Result**: Stable error display only when actually disconnected
+
+### 4. Removed Custom Background Colors
+- **Issue**: Components used custom `bg-*` classes instead of relying on globals.css
+- **Solution**: Removed all custom background styling, let theme system handle colors
+- **Files Cleaned**:
+  - WizardInterface.tsx - Connection status badges
+  - ParticipantInfo.tsx - Avatar, consent status, demographic cards
+  - RobotStatus.tsx - Status indicators, battery colors, sensor badges
+  - ActionControls.tsx - Recording indicators, emergency dialogs
+  - ExecutionStepDisplay.tsx - Action type colors and backgrounds
+
+### 5. Button Improvements
+- **Before**: Full-width buttons (`className="flex-1"`)
+- **After**: Compact buttons with `size="sm"` positioned logically in header
+- **Result**: Professional appearance, better space utilization
+
+### 6. Simplified Layout Structure
+- **Before**: Complex EntityView + EntityViewHeader + EntityViewSection nesting
+- **After**: Simple `div` with compact header + `Tabs` component
+- **Result**: Cleaner code, better performance, easier maintenance
+
+## New Tab Organization
+
+### Execution Tab
+- **Purpose**: Primary trial control and step execution
+- **Layout**: Split view - Current step (left) + Actions/controls (right)
+- **Features**: Step details, wizard actions, robot commands, execution controls
+
+### Participant Tab
+- **Purpose**: Complete participant information in single view
+- **Content**: Demographics, background, consent status, session info
+- **Benefits**: No scrolling needed, all info visible at once
+
+### Robot Tab
+- **Purpose**: Real-time robot monitoring and status
+- **Content**: Connection status, battery, signal, position, sensors
+- **Features**: Live updates, error handling, status indicators
+
+### Progress Tab
+- **Purpose**: Visual trial timeline and completion tracking
+- **Content**: Step progression, completion status, trial overview
+- **Benefits**: Quick navigation, clear progress indication
+
+### Events Tab
+- **Purpose**: Live event logging and trial history
+- **Content**: Real-time event stream, timestamps, wizard interventions
+- **Features**: Scrollable log, event filtering, complete audit trail
+
+## Technical Improvements
+
+### Component Cleanup
+```typescript
+// Before: Custom backgrounds and colors
+<div className="bg-card rounded-lg border border-green-200 bg-green-50 p-4">
+<Badge className="bg-green-100 text-green-800">
+<Icon className="h-4 w-4 text-red-500" />
+
+// After: Let theme system handle styling
+<div className="rounded-lg border p-4">
+<Badge variant="secondary">
+<Icon className="h-4 w-4" />
+```
+
+### Layout Simplification
+```typescript
+// Before: Complex nested structure
+<EntityView>
+  <EntityViewHeader>...</EntityViewHeader>
+  <div className="grid gap-6 lg:grid-cols-3">
+    <EntityViewSection>...</EntityViewSection>
+  </div>
+</EntityView>
+
+// After: Clean tabbed structure
+<div className="flex h-screen flex-col">
+  <div className="border-b px-6 py-4">{/* Compact header */}</div>
+  <Tabs defaultValue="execution" className="flex h-full flex-col">
+    <TabsList>...</TabsList>
+    <TabsContent>...</TabsContent>
+  </Tabs>
+</div>
+```
+
+### Error Handling Enhancement
+```typescript
+// Before: Flashing connection errors
+{wsError && <Alert>Connection issue: {wsError}</Alert>}
+
+// After: Stable error display
+{wsError && wsError.length > 0 && !wsConnecting && (
+  <Alert>Connection issue: {wsError}</Alert>
+)}
+```
+
+## User Experience Benefits
+
+### Workflow Efficiency
+- **50% Less Navigation**: Tab switching vs scrolling between sections
+- **Always Visible Controls**: Critical buttons in header, never hidden
+- **Context Preservation**: Tab state maintained during trial execution
+- **Quick Access**: Related information grouped logically
+
+### Visual Clarity
+- **Reduced Clutter**: Removed duplicate headers, unnecessary backgrounds
+- **Consistent Styling**: Theme-based colors, uniform spacing
+- **Professional Appearance**: Clean, modern interface design
+- **Better Focus**: Less visual noise, clearer information hierarchy
+
+### Space Utilization
+- **Full Height**: Uses entire screen real estate efficiently
+- **No Scrolling**: All content accessible via tabs
+- **Responsive Design**: Adapts to different screen sizes
+- **Information Density**: More data visible simultaneously
+
+## Files Modified
+
+### Core Interface
+- `src/components/trials/wizard/WizardInterface.tsx` - Complete redesign to tabbed layout
+- `src/app/(dashboard)/trials/[trialId]/wizard/page.tsx` - Removed duplicate header
+
+### Component Cleanup
+- `src/components/trials/wizard/ParticipantInfo.tsx` - Removed Card headers, custom colors
+- `src/components/trials/wizard/RobotStatus.tsx` - Cleaned backgrounds, status colors
+- `src/components/trials/wizard/ActionControls.tsx` - Removed custom styling
+- `src/components/trials/wizard/ExecutionStepDisplay.tsx` - Fixed color types, backgrounds
+
+## Performance Impact
+
+### Reduced Bundle Size
+- Removed unused Card imports where not needed
+- Simplified component tree depth
+- Less conditional styling logic
+
+### Improved Rendering
+- Fewer DOM nodes with simpler structure
+- More efficient React reconciliation
+- Better CSS cache utilization with theme classes
+
+### Enhanced Responsiveness
+- Tab-based navigation faster than scrolling
+- Lazy-loaded tab content (potential future optimization)
+- More efficient state management
+
+## Compatibility & Migration
+
+### Preserved Functionality
+- ✅ All WebSocket real-time features intact
+- ✅ Robot integration fully functional
+- ✅ Trial control and execution preserved
+- ✅ Data capture and logging maintained
+- ✅ Security and authentication unchanged
+
+### Breaking Changes
+- **Visual Only**: No API or data structure changes
+- **Navigation**: Tab-based instead of scrolling (user adaptation needed)
+- **Layout**: Component positions changed but functionality identical
+
+### Migration Notes
+- No database changes required
+- No configuration updates needed
+- Existing trials and data fully compatible
+- WebSocket connections work identically
+
+## Future Enhancements
+
+### Potential Improvements
+- [ ] Keyboard shortcuts for tab navigation (Ctrl+1-5)
+- [ ] Customizable tab order and visibility
+- [ ] Split-view option for viewing two tabs simultaneously
+- [ ] Workspace state persistence across sessions
+- [ ] Enhanced accessibility features
+
+### Performance Optimizations
+- [ ] Lazy loading of tab content
+- [ ] Virtual scrolling for large event logs
+- [ ] Service worker for offline functionality
+- [ ] Progressive web app features
+
+## Success Metrics
+
+### Quantifiable Improvements
+- **Navigation Efficiency**: 50% reduction in scrolling actions
+- **Space Utilization**: 30% more information visible per screen
+- **Visual Noise**: 60% reduction in redundant UI elements
+- **Load Performance**: 20% faster rendering with simplified DOM
+
+### User Experience Gains
+- **Professional Appearance**: Modern, clean interface design
+- **Workflow Optimization**: Faster task completion times
+- **Reduced Cognitive Load**: Better information organization
+- **Enhanced Focus**: Less distraction from core trial tasks
+
+## Deployment Status
+
+**Status**: ✅ Production Ready  
+**Testing**: All functionality verified in new layout  
+**Performance**: Improved rendering and navigation speed  
+**Compatibility**: Full backward compatibility with existing data  
+
+The wizard interface transformation represents a significant improvement in user experience while maintaining all existing functionality. The interface now provides a professional, efficient environment for conducting high-quality HRI research with improved workflow efficiency and visual clarity.

docs/_archive/wizard-interface-guide.md

@@ -0,0 +1,367 @@
+# Wizard Interface Guide
+
+## Overview
+
+The HRIStudio wizard interface provides a comprehensive, real-time trial execution environment with a consolidated 3-panel design optimized for efficient experiment control and monitoring.
+
+## Interface Layout
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          Trial Execution Header                              │
+│                    [Trial Name] - [Participant] - [Status]                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+┌──────────────┬──────────────────────────────────────┬──────────────────────┐
+│              │                                       │                      │
+│ Trial        │   Execution Timeline                  │ Robot Control        │
+│ Control      │                                       │ & Status             │
+│              │                                       │                      │
+│ ┌──────────┐ │ ┌──┬──┬──┬──┬──┐ Step Progress      │ 📷 Camera View       │
+│ │ Start    │ │ │✓ │✓ │● │  │  │                    │                      │
+│ │ Pause    │ │ └──┴──┴──┴──┴──┘                    │ Connection: ✓        │
+│ │ Next Step│ │                                       │                      │
+│ │ Complete │ │ Current Step: "Greeting"             │ Autonomous Life: ON  │
+│ │ Abort    │ │ ┌────────────────────────────────┐   │                      │
+│ └──────────┘ │ │ Actions:                       │   │ Robot Actions:       │
+│              │ │ • Say "Hello"          [Run]   │   │ ┌──────────────────┐ │
+│ Progress:    │ │ • Wave Hand            [Run]   │   │ │ Quick Commands   │ │
+│ Step 3/5     │ │ • Wait 2s              [Run]   │   │ └──────────────────┘ │
+│              │ └────────────────────────────────┘   │                      │
+│              │                                       │ Movement Controls    │
+│              │                                       │ Quick Actions        │
+│              │                                       │ Status Monitoring    │
+└──────────────┴──────────────────────────────────────┴──────────────────────┘
+```
+
+## Panel Descriptions
+
+### Left Panel: Trial Control
+
+**Purpose**: Manage overall trial flow and progression
+
+**Features:**
+- **Start Trial**: Begin experiment execution
+- **Pause/Resume**: Temporarily halt trial without aborting
+- **Next Step**: Manually advance to next step (when all actions complete)
+- **Complete Trial**: Mark trial as successfully completed
+- **Abort Trial**: Emergency stop with reason logging
+
+**Progress Indicators:**
+- Current step number (e.g., "Step 3 of 5")
+- Overall trial status
+- Time elapsed
+
+**Best Practices:**
+- Use Pause for participant breaks
+- Use Abort only for unrecoverable issues
+- Document abort reasons thoroughly
+
+---
+
+### Center Panel: Execution Timeline
+
+**Purpose**: Visualize experiment flow and execute current step actions
+
+#### Horizontal Step Progress Bar
+
+**Features:**
+- **Visual Overview**: See all steps at a glance
+- **Step States**:
+  - ✓ **Completed** (green checkmark, primary border)
+  - ● **Current** (highlighted, ring effect)
+  - ○ **Upcoming** (muted appearance)
+- **Click Navigation**: Jump to any step (unless read-only)
+- **Horizontal Scroll**: For experiments with many steps
+
+**Step Card Elements:**
+- Step number or checkmark icon
+- Truncated step name (hover for full name)
+- Visual state indicators
+
+#### Current Step View
+
+**Features:**
+- **Step Header**: Name and description
+- **Action List**: Vertical timeline of actions
+- **Action States**:
+  - Completed actions (checkmark)
+  - Active action (highlighted, pulsing)
+  - Pending actions (numbered)
+- **Action Controls**: Run, Skip, Mark Complete buttons
+- **Progress Tracking**: Auto-scrolls to active action
+
+**Action Types:**
+- **Wizard Actions**: Manual tasks for the wizard
+- **Robot Actions**: Commands sent to the robot
+- **Control Flow**: Loops, branches, parallel execution
+- **Observations**: Data collection and recording
+
+**Best Practices:**
+- Review step description before starting
+- Execute actions in order unless branching
+- Use Skip sparingly and document reasons
+- Verify robot action completion before proceeding
+
+---
+
+### Right Panel: Robot Control & Status
+
+**Purpose**: Unified location for all robot-related controls and monitoring
+
+#### Camera View
+- Live video feed from robot or environment
+- Multiple camera support (switchable)
+- Full-screen mode available
+
+#### Connection Status
+- **ROS Bridge**: WebSocket connection state
+- **Robot Status**: Online/offline indicator
+- **Reconnect**: Manual reconnection button
+- **Auto-reconnect**: Automatic retry on disconnect
+
+#### Autonomous Life Toggle
+- **Purpose**: Enable/disable robot's autonomous behaviors
+- **States**:
+  - ON: Robot exhibits idle animations, breathing, awareness
+  - OFF: Robot remains still, fully manual control
+- **Best Practice**: Turn OFF during precise interactions
+
+#### Robot Actions Panel
+- **Quick Commands**: Pre-configured robot actions
+- **Parameter Controls**: Adjust action parameters
+- **Execution Status**: Real-time feedback
+- **Action History**: Recent commands log
+
+#### Movement Controls
+- **Directional Pad**: Manual robot navigation
+- **Speed Control**: Adjust movement speed
+- **Safety Limits**: Collision detection and boundaries
+- **Emergency Stop**: Immediate halt
+
+#### Quick Actions
+- **Text-to-Speech**: Send custom speech commands
+- **Preset Gestures**: Common robot gestures
+- **LED Control**: Change robot LED colors
+- **Posture Control**: Sit, stand, crouch commands
+
+#### Status Monitoring
+- **Battery Level**: Remaining charge percentage
+- **Joint Status**: Motor temperatures and positions
+- **Sensor Data**: Ultrasonic, tactile, IMU readings
+- **Warnings**: Overheating, low battery, errors
+
+**Best Practices:**
+- Monitor battery level throughout trial
+- Check connection status before robot actions
+- Use Emergency Stop for safety concerns
+- Document any robot malfunctions
+
+---
+
+## Workflow Guide
+
+### Pre-Trial Setup
+
+1. **Verify Robot Connection**
+   - Check ROS Bridge status (green indicator)
+   - Test robot responsiveness with quick action
+   - Confirm camera feed is visible
+
+2. **Review Experiment Protocol**
+   - Scan horizontal step progress bar
+   - Review first step's actions
+   - Prepare any physical materials
+
+3. **Configure Robot Settings** (Researchers/Admins only)
+   - Click Settings icon in robot panel
+   - Adjust speech, movement, connection parameters
+   - Save configuration for this study
+
+### During Trial Execution
+
+1. **Start Trial**
+   - Click "Start" in left panel
+   - First step becomes active
+   - First action highlights in timeline
+
+2. **Execute Actions**
+   - Follow action sequence in center panel
+   - Use action controls (Run/Skip/Complete)
+   - Monitor robot status in right panel
+   - Document any deviations
+
+3. **Navigate Steps**
+   - Wait for "Complete Step" button after all actions
+   - Click to advance to next step
+   - Or click step in progress bar to jump
+
+4. **Handle Issues**
+   - **Participant Question**: Use Pause
+   - **Robot Malfunction**: Check status panel, use Emergency Stop if needed
+   - **Protocol Deviation**: Document in notes, continue or abort as appropriate
+
+### Post-Trial Completion
+
+1. **Complete Trial**
+   - Click "Complete Trial" after final step
+   - Confirm completion dialog
+   - Trial marked as completed
+
+2. **Review Data**
+   - All actions logged with timestamps
+   - Robot commands recorded
+   - Sensor data captured
+   - Video recordings saved
+
+---
+
+## Control Flow Features
+
+### Loops
+
+**Behavior:**
+- Loops execute their child actions repeatedly
+- **Implicit Approval**: Wizard automatically approves each iteration
+- **Manual Override**: Wizard can skip or abort loop
+- **Progress Tracking**: Shows current iteration (e.g., "2 of 5")
+
+**Best Practices:**
+- Monitor participant engagement during loops
+- Use abort if participant shows distress
+- Document any skipped iterations
+
+### Branches
+
+**Behavior:**
+- Conditional execution based on criteria
+- Wizard selects branch path
+- Only selected branch actions execute
+- Other branches are skipped
+
+**Best Practices:**
+- Review branch conditions before choosing
+- Document branch selection rationale
+- Ensure participant meets branch criteria
+
+### Parallel Execution
+
+**Behavior:**
+- Multiple actions execute simultaneously
+- All must complete before proceeding
+- Independent progress tracking
+
+**Best Practices:**
+- Monitor all parallel actions
+- Be prepared for simultaneous robot and wizard tasks
+- Coordinate timing carefully
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Space` | Start/Pause Trial |
+| `→` | Next Step |
+| `Esc` | Abort Trial (with confirmation) |
+| `R` | Run Current Action |
+| `S` | Skip Current Action |
+| `C` | Complete Current Action |
+| `E` | Emergency Stop Robot |
+
+---
+
+## Troubleshooting
+
+### Robot Not Responding
+
+1. Check ROS Bridge connection (right panel)
+2. Click Reconnect button
+3. Verify robot is powered on
+4. Check network connectivity
+5. Restart ROS Bridge if needed
+
+### Camera Feed Not Showing
+
+1. Verify camera is enabled in robot settings
+2. Check camera topic in ROS
+3. Refresh browser page
+4. Check camera hardware connection
+
+### Actions Not Progressing
+
+1. Verify action has completed
+2. Check for error messages
+3. Manually mark complete if stuck
+4. Document issue in trial notes
+
+### Timeline Not Updating
+
+1. Refresh browser page
+2. Check WebSocket connection
+3. Verify trial status is "in_progress"
+4. Contact administrator if persists
+
+---
+
+## Role-Specific Features
+
+### Wizards
+- Full trial execution control
+- Action execution and skipping
+- Robot control (if permitted)
+- Real-time decision making
+
+### Researchers
+- All wizard features
+- Robot settings configuration
+- Trial monitoring and oversight
+- Protocol deviation approval
+
+### Observers
+- **Read-only access**
+- View trial progress
+- Monitor robot status
+- Add annotations (no control)
+
+### Administrators
+- All features enabled
+- System configuration
+- Plugin management
+- Emergency overrides
+
+---
+
+## Best Practices Summary
+
+✅ **Before Trial**
+- Verify all connections
+- Test robot responsiveness
+- Review protocol thoroughly
+
+✅ **During Trial**
+- Follow action sequence
+- Monitor robot status continuously
+- Document deviations immediately
+- Use Pause for breaks, not Abort
+
+✅ **After Trial**
+- Complete trial properly
+- Review captured data
+- Document any issues
+- Debrief with participant
+
+❌ **Avoid**
+- Skipping actions without documentation
+- Ignoring robot warnings
+- Aborting trials unnecessarily
+- Deviating from protocol without approval
+
+---
+
+## Additional Resources
+
+- **[Quick Reference](./quick-reference.md)** - Essential commands and shortcuts
+- **[Implementation Details](./implementation-details.md)** - Technical architecture
+- **[NAO6 Quick Reference](./nao6-quick-reference.md)** - Robot-specific commands
+- **[Troubleshooting Guide](./nao6-integration-complete-guide.md)** - Detailed problem resolution

docs/_archive/wizard-interface-redesign.md

@@ -0,0 +1,243 @@
+# Wizard Interface Redesign - Complete ✅
+
+## Overview
+
+The Wizard Interface has been completely redesigned to provide a cleaner, more focused experience that fits everything in a single window using a tabbed layout. The interface is now more compact and professional while maintaining all functionality.
+
+## Key Changes Made
+
+### 🎨 **Single Window Tabbed Design**
+- **Replaced**: Multi-section scrolling layout with sidebar
+- **With**: Compact tabbed interface using `Tabs` component
+- **Result**: All content accessible without scrolling, cleaner organization
+
+### 📏 **Compact Header**
+- **Removed**: Large EntityViewHeader with redundant information
+- **Added**: Simple title bar with essential info and controls
+- **Features**: 
+  - Trial name and participant code
+  - Real-time timer display during active trials
+  - Connection status badge
+  - Action buttons (Start, Next Step, Complete, Abort)
+
+### 🏷️ **Tab Organization**
+The interface now uses 5 focused tabs:
+
+1. **Execution** - Current step and action controls
+2. **Participant** - Demographics and information  
+3. **Robot** - Status monitoring and controls
+4. **Progress** - Trial timeline and completion status
+5. **Events** - Live event log and history
+
+### 🎯 **Button Improvements**
+- **Changed**: Full-width buttons to compact `size="sm"` buttons
+- **Positioned**: Action buttons in header for easy access
+- **Grouped**: Related actions together logically
+
+### 🎨 **Visual Cleanup**
+- **Removed**: Background color styling from child components
+- **Simplified**: Card usage - now only where structurally needed
+- **Cleaned**: Duplicate headers and redundant visual elements
+- **Unified**: Consistent spacing and typography
+
+## Layout Structure
+
+### Before (Multi-Section)
+```
+┌─────────────────────────────────────────────────┐
+│ Large EntityViewHeader                          │
+├─────────────────────┬───────────────────────────┤
+│ Trial Status        │ Participant Info          │
+│                     │ (with duplicate headers)  │
+├─────────────────────┤                           │
+│ Current Step        │ Robot Status              │
+│                     │ (with duplicate headers)  │
+├─────────────────────┤                           │
+│ Execution Control   │ Live Events               │
+├─────────────────────┤                           │
+│ Quick Actions       │                           │
+├─────────────────────┤                           │
+│ Trial Progress      │                           │
+└─────────────────────┴───────────────────────────┘
+```
+
+### After (Tabbed)
+```
+┌─────────────────────────────────────────────────┐
+│ Compact Header [Timer] [Status] [Actions]       │
+├─────────────────────────────────────────────────┤
+│ [Execution][Participant][Robot][Progress][Events]│
+├─────────────────────────────────────────────────┤
+│                                                 │
+│ Tab Content (Full Height)                       │
+│                                                 │
+│   ┌─────────────┬─────────────┐                │
+│   │ Current     │ Actions     │ (Execution Tab) │
+│   │ Step        │ & Controls  │                │
+│   │             │             │                │
+│   └─────────────┴─────────────┘                │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+## Component Changes
+
+### WizardInterface.tsx
+- **Replaced**: `EntityView` with `div` full-height layout
+- **Added**: Compact header with timer and status
+- **Implemented**: `Tabs` component for content organization
+- **Moved**: Action buttons to header for immediate access
+- **Simplified**: Progress bar integrated into header
+
+### ParticipantInfo.tsx
+- **Removed**: `bg-card` background styling
+- **Kept**: Consent status background (green) for importance
+- **Simplified**: Card structure to work in tabbed layout
+
+### RobotStatus.tsx
+- **Removed**: Unused `Card` component imports
+- **Cleaned**: Background styling to match tab content
+- **Maintained**: All functional status monitoring
+
+## User Experience Improvements
+
+### 🎯 **Focused Workflow**
+- **Single View**: No more scrolling between sections
+- **Quick Access**: Most common actions in header
+- **Logical Grouping**: Related information grouped in tabs
+- **Context Switching**: Easy tab navigation without losing place
+
+### ⚡ **Efficiency Gains**
+- **Faster Navigation**: Tab switching vs scrolling
+- **Space Utilization**: Better use of screen real estate
+- **Visual Clarity**: Less visual noise and distractions
+- **Action Proximity**: Critical buttons always visible
+
+### 📱 **Responsive Design**
+- **Adaptive Layout**: Grid adjusts to screen size
+- **Tab Icons**: Visual cues for quick identification
+- **Compact Controls**: Work well on smaller screens
+- **Full Height**: Makes use of available vertical space
+
+## Tab Content Details
+
+### Execution Tab
+- **Left Side**: Current step display with details
+- **Right Side**: Action controls and quick interventions
+- **Features**: Step execution, wizard actions, robot commands
+
+### Participant Tab
+- **Single Card**: All participant information in one view
+- **Sections**: Basic info, demographics, background, consent
+- **Clean Layout**: No duplicate headers or extra cards
+
+### Robot Tab  
+- **Status Overview**: Connection, battery, signal strength
+- **Real-time Updates**: Live sensor readings and position
+- **Error Handling**: Clear error messages and recovery options
+
+### Progress Tab
+- **Visual Timeline**: Step-by-step progress visualization
+- **Completion Status**: Clear indicators of trial state
+- **Navigation**: Quick jump to specific steps
+
+### Events Tab
+- **Live Log**: Real-time event streaming
+- **Timestamps**: Precise timing information
+- **Filtering**: Focus on relevant event types
+- **History**: Complete trial activity record
+
+## Technical Implementation
+
+### Core Changes
+```typescript
+// Before: EntityView layout
+<EntityView>
+  <EntityViewHeader>...</EntityViewHeader>
+  <div className="grid gap-6 lg:grid-cols-3">
+    <EntityViewSection>...</EntityViewSection>
+  </div>
+</EntityView>
+
+// After: Tabbed layout
+<div className="flex h-screen flex-col">
+  <div className="border-b px-6 py-4">
+    {/* Compact header */}
+  </div>
+  <Tabs defaultValue="execution" className="flex h-full flex-col">
+    <TabsList>...</TabsList>
+    <TabsContent>...</TabsContent>
+  </Tabs>
+</div>
+```
+
+### Button Styling
+```typescript
+// Before: Full width buttons
+<Button className="flex-1">Start Trial</Button>
+
+// After: Compact buttons
+<Button size="sm">
+  <Play className="mr-2 h-4 w-4" />
+  Start Trial
+</Button>
+```
+
+### Background Removal
+```typescript
+// Before: Themed backgrounds
+<div className="bg-card rounded-lg border p-4">
+
+// After: Simple borders
+<div className="rounded-lg border p-4">
+```
+
+## Benefits Achieved
+
+### ✅ **Space Efficiency**
+- **50% Less Scrolling**: All content accessible via tabs
+- **Better Density**: More information visible at once
+- **Cleaner Layout**: Reduced visual clutter and redundancy
+
+### ✅ **User Experience**
+- **Faster Workflow**: Critical actions always visible
+- **Logical Organization**: Related information grouped together
+- **Professional Appearance**: Modern, clean interface design
+
+### ✅ **Maintainability**
+- **Simplified Components**: Less complex styling and layout
+- **Consistent Patterns**: Uniform tab structure throughout
+- **Cleaner Code**: Removed redundant styling and imports
+
+## Future Enhancements
+
+### Potential Improvements
+- [ ] **Keyboard Shortcuts**: Tab navigation with Ctrl+1-5
+- [ ] **Customizable Layout**: User-configurable tab order
+- [ ] **Split View**: Option to show two tabs simultaneously
+- [ ] **Workspace Saving**: Remember user's preferred tab
+- [ ] **Quick Actions Bar**: Floating action buttons for common tasks
+
+### Performance Optimizations
+- [ ] **Lazy Loading**: Load tab content only when needed
+- [ ] **Virtual Scrolling**: Handle large event logs efficiently
+- [ ] **State Persistence**: Maintain tab state across sessions
+
+---
+
+## Migration Notes
+
+### Breaking Changes
+- **Layout**: Complete UI restructure (no API changes)
+- **Navigation**: Tab-based instead of scrolling sections
+- **Styling**: Simplified component backgrounds
+
+### Compatibility
+- ✅ **All Features**: Every function preserved and enhanced
+- ✅ **WebSocket**: Real-time functionality unchanged
+- ✅ **Data Flow**: All API integrations maintained
+- ✅ **Robot Integration**: Full robot control capabilities retained
+
+**Status**: ✅ **COMPLETE** - Production Ready
+**Impact**: Significantly improved user experience and interface efficiency
+**Testing**: All existing functionality verified in new layout

docs/_archive/wizard-interface-summary.md

@@ -0,0 +1,238 @@
+# Wizard Interface Summary & Usage Guide
+
+## Overview
+
+The Wizard Interface has been completely fixed and enhanced to provide a professional, production-ready control panel for conducting HRI trials. All duplicate headers have been removed, real experiment data is now used instead of hardcoded values, and the WebSocket system is properly integrated.
+
+## Key Fixes Applied
+
+### 1. Removed Duplicate Headers ✅
+- **ParticipantInfo**: Removed redundant Card headers since it's used inside EntityViewSection
+- **RobotStatus**: Cleaned up duplicate title sections and unified layout
+- **All Components**: Now follow consistent design patterns without header duplication
+
+### 2. Real Experiment Data Integration ✅
+- **Experiment Steps**: Now loads actual steps from database via `api.experiments.getSteps`
+- **Type Mapping**: Database step types ("wizard", "robot", "parallel", "conditional") properly mapped to component types ("wizard_action", "robot_action", "parallel_steps", "conditional_branch")
+- **Step Properties**: Real step names, descriptions, and duration estimates from experiment designer
+
+### 3. Type Safety Improvements ✅
+- **Demographics Handling**: Fixed all `any` types in ParticipantInfo component
+- **Step Type Mapping**: Proper TypeScript types throughout the wizard interface
+- **Null Safety**: Using nullish coalescing (`??`) instead of logical OR (`||`) for better type safety
+
+## Current System Status
+
+### ✅ Working Features
+- **Real-time WebSocket Connection**: Live trial updates and control
+- **Step-by-step Execution**: Navigate through actual experiment protocols
+- **Robot Status Monitoring**: Battery, signal, position, and sensor tracking
+- **Participant Information**: Complete demographics and consent status
+- **Event Logging**: Real-time capture of all trial activities
+- **Trial Control**: Start, execute, complete, and abort trials
+
+### 📊 Seed Data Available
+Run `bun db:seed` to populate with realistic test data:
+
+**Test Experiments:**
+- **"Basic Interaction Protocol 1"** - 3 steps with wizard actions and NAO integration
+- **"Dialogue Timing Pilot"** - Multi-step protocol with parallel/conditional logic
+
+**Test Participants:**
+- 8 participants with complete demographics (age, gender, education, robot experience)
+- Consent already verified for immediate testing
+
+**Test Trials:**
+- Multiple trials in different states (scheduled, in_progress, completed)
+- Realistic metadata and execution history
+
+## WebSocket Server Usage
+
+### Automatic Connection
+The wizard interface automatically connects to the WebSocket server at:
+```
+wss://localhost:3000/api/websocket?trialId={TRIAL_ID}&token={AUTH_TOKEN}
+```
+
+### Real-time Features
+- **Connection Status**: Green "Real-time" badge when connected
+- **Live Updates**: Trial status, step changes, and event logging
+- **Automatic Reconnection**: Exponential backoff on connection loss
+- **Error Handling**: User-friendly error messages and recovery
+
+### Message Flow
+```
+Wizard Action → WebSocket → Server → Database → Broadcast → All Connected Clients
+```
+
+## Quick Start Instructions
+
+### 1. Setup Development Environment
+```bash
+# Install dependencies
+bun install
+
+# Start database (if using Docker)
+bun run docker:up
+
+# Push schema and seed data
+bun db:push
+bun db:seed
+
+# Start development server
+bun dev
+```
+
+### 2. Access Wizard Interface
+1. **Login**: `sean@soconnor.dev` / `password123`
+2. **Navigate**: Dashboard → Studies → Select Study → Trials
+3. **Select Trial**: Click on any trial with "scheduled" status
+4. **Start Wizard**: Click "Wizard Control" button
+
+### 3. Conduct a Trial
+1. **Verify Connection**: Look for green "Real-time" badge in header
+2. **Review Protocol**: Check experiment steps and participant info
+3. **Start Trial**: Click "Start Trial" button
+4. **Execute Steps**: Follow protocol step-by-step using "Next Step" button
+5. **Monitor Status**: Watch robot status and live event log
+6. **Complete Trial**: Click "Complete" when finished
+
+## Expected Trial Flow
+
+### Step 1: Introduction & Object Demo
+- **Wizard Action**: Show object to participant
+- **Robot Action**: NAO says "Hello, I am NAO. Let's begin!"
+- **Duration**: ~60 seconds
+
+### Step 2: Participant Response  
+- **Wizard Action**: Wait for participant response
+- **Prompt**: "What did you notice about the object?"
+- **Timeout**: 20 seconds
+
+### Step 3: Robot Feedback
+- **Robot Action**: Set NAO LED color to blue
+- **Wizard Fallback**: Record observation note if no robot available
+- **Duration**: ~30 seconds
+
+## WebSocket Communication Examples
+
+### Starting a Trial
+```json
+{
+  "type": "trial_action",
+  "data": {
+    "actionType": "start_trial",
+    "step_index": 0,
+    "data": { "notes": "Trial started by wizard" }
+  }
+}
+```
+
+### Logging Wizard Intervention
+```json
+{
+  "type": "wizard_intervention", 
+  "data": {
+    "action_type": "manual_correction",
+    "step_index": 1,
+    "action_data": { "message": "Clarified participant question" }
+  }
+}
+```
+
+### Step Transition
+```json
+{
+  "type": "step_transition",
+  "data": {
+    "from_step": 1,
+    "to_step": 2,
+    "step_name": "Participant Response"
+  }
+}
+```
+
+## Robot Integration
+
+### Supported Robots
+- **TurtleBot3 Burger**: ROS2 navigation and sensing
+- **NAO Humanoid**: REST API for speech, gestures, LEDs
+- **Plugin System**: Extensible architecture for additional robots
+
+### Robot Actions in Seed Data
+- **NAO Say Text**: Text-to-speech with configurable parameters
+- **NAO Set LED Color**: Visual feedback through eye color changes  
+- **NAO Play Animation**: Pre-defined gesture sequences
+- **Wizard Fallbacks**: Manual alternatives when robots unavailable
+
+## Troubleshooting
+
+### WebSocket Issues
+- **Red "Offline" Badge**: Check network connection and server status
+- **Yellow "Connecting" Badge**: Normal during initial connection or reconnection
+- **Connection Errors**: Verify authentication token and trial permissions
+
+### Step Loading Problems
+- **No Steps Showing**: Verify experiment has steps in database
+- **"Loading experiment steps..."**: Normal during initial load
+- **Type Errors**: Check step type mapping in console
+
+### Robot Communication
+- **Robot Status**: Monitor connection, battery, and sensor status
+- **Action Failures**: Check robot plugin configuration and network
+- **Fallback Actions**: System automatically provides wizard alternatives
+
+## Production Deployment
+
+### Environment Variables
+```bash
+DATABASE_URL=postgresql://user:pass@host:port/dbname
+NEXTAUTH_SECRET=your-secret-key
+NEXTAUTH_URL=https://your-domain.com
+```
+
+### WebSocket Configuration
+- **Protocol**: Automatic upgrade from HTTP to WebSocket
+- **Authentication**: Session-based token validation
+- **Scaling**: Per-trial room isolation for concurrent sessions
+- **Security**: Role-based access control and message validation
+
+## Development Notes
+
+### Architecture Decisions
+- **EntityViewSection**: Consistent layout patterns across all pages
+- **Real-time First**: WebSocket primary, polling fallback
+- **Type Safety**: Strict TypeScript throughout wizard components
+- **Plugin System**: Extensible robot integration architecture
+
+### Performance Optimizations
+- **Selective Polling**: Reduced frequency when WebSocket connected
+- **Local State**: Efficient React state management
+- **Event Batching**: Optimized WebSocket message handling
+- **Caching**: Smart API data revalidation
+
+## Next Steps
+
+### Immediate Enhancements
+- [ ] Observer-only interface for read-only trial monitoring
+- [ ] Pause/resume functionality during trial execution
+- [ ] Enhanced post-trial analytics and visualization
+- [ ] Real robot hardware integration testing
+
+### Future Improvements
+- [ ] Multi-wizard collaboration features
+- [ ] Advanced step branching and conditional logic
+- [ ] Voice control integration for hands-free operation
+- [ ] Mobile-responsive wizard interface
+
+---
+
+## Success Criteria Met ✅
+
+- ✅ **No Duplicate Headers**: Clean, professional interface
+- ✅ **Real Experiment Data**: No hardcoded values, actual database integration
+- ✅ **WebSocket Integration**: Live real-time trial control and monitoring
+- ✅ **Type Safety**: Strict TypeScript throughout wizard components
+- ✅ **Production Ready**: Professional UI matching platform standards
+
+The wizard interface is now production-ready and provides researchers with a comprehensive, real-time control system for conducting high-quality HRI studies.

docs/_archive/work_in_progress.md

@@ -0,0 +1,558 @@
+# Work In Progress
+
+## Current Status (December 2024)
+
+### Wizard Interface Multi-View Implementation - COMPLETE ✅ (December 2024)
+Complete redesign of trial execution interface with role-based views for thesis research.
+
+**✅ Completed Implementation:**
+- **Role-Based Views**: Created three distinct interfaces - Wizard, Observer, and Participant views
+- **Fixed Layout Issues**: Eliminated double headers and bottom cut-off problems
+- **Removed Route Duplication**: Cleaned up global trial routes, enforced study-scoped architecture
+- **Professional UI**: Redesigned with experiment designer-inspired three-panel layout
+- **Smart Role Detection**: Automatic role assignment with URL override capability (?view=wizard|observer|participant)
+- **Type Safety**: Full TypeScript compliance with proper metadata handling
+- **WebSocket Integration**: Connected real-time trial updates with fallback polling
+
+**Implementation Details:**
+- **WizardView**: Full trial control with TrialControlPanel, ExecutionPanel, and MonitoringPanel
+- **ObserverView**: Read-only monitoring interface with trial overview and live activity
+- **ParticipantView**: Friendly, welcoming interface designed for study participants
+- **Route Structure**: `/studies/[id]/trials/[trialId]/wizard` with role-based rendering
+- **Layout Fix**: Proper height calculations with `min-h-0 flex-1` and removed duplicate headers
+
+**Benefits for Thesis Research:**
+- **Multi-User Support**: Appropriate interface for researchers, observers, and participants
+- **Professional Experience**: Clean, purpose-built UI for each user role
+- **Research Ready**: Supports Wizard of Oz study methodology comparing HRIStudio vs Choregraphe
+- **Flexible Testing**: URL parameters enable easy view switching during development
+
+### Route Consolidation - COMPLETE ✅ (September 2024)
+Major architectural improvement consolidating global routes into study-scoped workflows.
+
+**✅ Completed Implementation:**
+- **Removed Global Routes**: Eliminated `/participants`, `/trials`, and `/analytics` global views
+- **Study-Scoped Architecture**: All entity management now flows through studies (`/studies/[id]/participants`, `/studies/[id]/trials`, `/studies/[id]/analytics`)
+- **Dashboard Route Fixed**: Resolved `/dashboard` 404 issue by moving from `(dashboard)` route group to explicit `/dashboard` route
+- **Helpful Redirects**: Created redirect pages for moved routes with auto-redirect when study context exists
+- **Custom 404 Handling**: Added dashboard-layout 404 page for broken links within dashboard area
+- **Navigation Cleanup**: Updated sidebar, breadcrumbs, and all navigation references
+- **Form Updates**: Fixed all entity forms (ParticipantForm, TrialForm) to use study-scoped routes
+- **Component Consolidation**: Removed duplicate components (`participants-data-table.tsx`, `trials-data-table.tsx`, etc.)
+
+**Benefits Achieved:**
+- **Logical Hierarchy**: Studies → Participants/Trials/Analytics creates intuitive workflow
+- **Reduced Complexity**: Eliminated confusion about where to find functionality
+- **Code Reduction**: Removed significant duplicate code between global and study-scoped views
+- **Better UX**: Clear navigation path through study-centric organization
+- **Maintainability**: Single source of truth for each entity type
+
+## Next Priority: WebSocket Implementation Enhancement
+
+### WebSocket Real-Time Infrastructure - IN PROGRESS 🚧
+Critical for thesis research - enable real-time trial execution and monitoring.
+
+**Current Status:**
+- ✅ Basic WebSocket hooks exist (`useWebSocket.ts`, `useTrialWebSocket.ts`)
+- ✅ Trial execution engine with tRPC endpoints
+- ❌ **Missing**: Real-time robot communication and status updates
+- ❌ **Missing**: Live trial event broadcasting to all connected clients
+- ❌ **Missing**: WebSocket server implementation for trial coordination
+
+**Required Implementation:**
+- **Robot Integration**: WebSocket connection to robot platforms (ROS2, REST APIs)
+- **Event Broadcasting**: Real-time trial events to wizard, observers, and monitoring systems
+- **Session Management**: Multi-client coordination for collaborative trial execution
+- **Error Handling**: Robust connection recovery and fallback mechanisms
+- **Security**: Proper authentication and role-based WebSocket access
+
+**Files to Focus On:**
+- `src/hooks/useWebSocket.ts` - Client-side WebSocket management
+- `src/server/services/trial-execution.ts` - Trial execution engine
+- WebSocket server implementation (needs creation)
+- Robot plugin WebSocket adapters
+
+## Previous Status (December 2024)
+
+### Experiment Designer Redesign - COMPLETE ✅ (Phase 1)
+Initial redesign delivered per `docs/experiment-designer-redesign.md`. Continuing iterative UX/scale refinement (Phase 2).
+
+> Added (Pending Fixes Note): Current drag interaction in Action Library initiates panel scroll instead of producing a proper drag overlay; action items cannot yet be dropped into steps in the new virtualized workspace. Step and action reordering (drag-based) are still outstanding requirements. Action pane collapse toggle was removed (overlapped breadcrumbs). Category filters must enforce either:
+> - ALL categories selected, or
+> - Exactly ONE category selected
+> (No ambiguous multi-partial subset state in the revamped slim panel.)
+
+#### **Implementation Status (Phase 1 Recap)**
+
+**✅ Core Infrastructure Complete:**
+- Zustand state management with comprehensive actions and selectors
+- Deterministic SHA-256 hashing with incremental computation
+- Type-safe validation (structural, parameter, semantic, execution)
+- Plugin drift detection with action signature tracking
+- Export/import integrity bundles
+
+**✅ UI Components (Initial Generation):**
+- `DesignerShell` (initial orchestration – now superseded by `DesignerRoot`)
+- `ActionLibrary` (v1 palette)
+- `StepFlow` (legacy list)
+- `PropertiesPanel`, `ValidationPanel`, `DependencyInspector`
+- `SaveBar`
+
+**Phase 2 Overhaul Components (In Progress / Added):**
+- `DesignerRoot` (panel + status bar orchestration)
+- `PanelsContainer` (resizable/collapsible left/right)
+- `BottomStatusBar` (hash / drift / unsaved quick actions)
+- `ActionLibraryPanel` (slim, single-column, favorites, density, search)
+- `FlowWorkspace` (virtualized step list replacing `StepFlow` for large scale)
+- `InspectorPanel` (tabbed: properties / issues / dependencies)
+
+### Recent Updates (Latest Iteration)
+
+**Action Library Slim Refactor**
+- Constrained width (max 240px) with internal vertical scroll
+- Single-column tall tiles; star (favorite) moved top-right
+- Multi-line name wrapping; description line-clamped (3 lines)
+- Stacked control layout (search → categories → compact buttons)
+- Eliminated horizontal scroll-on-drag issue (prevented unintended X scroll)
+- Removed responsive two-column to preserve predictable drag targets
+
+**Scroll / Drag Fixes**
+- Explicit `overflow-y-auto overflow-x-hidden` on action list container
+- Prevented accidental horizontal scroll on drag start
+- Ensured tiles use minimal horizontal density to preserve central workspace
+
+**Flow Pane Overhaul**
+- Introduced `FlowWorkspace` virtualized list:
+  - Variable-height virtualization (dynamic measurement with ResizeObserver)
+  - Inline step rename (Enter / Escape / blur commit)
+  - Collapsible steps with action chips
+  - Insert “Below” & “Step Above” affordances
+  - Droppable targets registered per step (`step-<id>`)
+  - Quick action placeholder insertion button
+- Legacy `FlowListView` retained temporarily for fallback (to be removed)
+- Step & action selection preserved (integrates with existing store)
+- Drag-end adaptation for action insertion works with new virtualization
+
+**Panel Layout & Status**
+- `PanelsContainer` persists widths; action panel now narrower by design
+- Status bar provides unified save / export / validate with state badges
+
+### Migration Status
+
+| Legacy Element | Status | Notes |
+| -------------- | ------ | ----- |
+| DesignerShell  | ✅ Removed | Superseded by DesignerRoot |
+| StepFlow       | ✅ Removed | Superseded by FlowWorkspace |
+| BlockDesigner  | ✅ Removed | Superseded by DesignerRoot |
+| SaveBar        | ✅ Removed | Functions consolidated in BottomStatusBar |
+| ActionLibrary  | ✅ Removed | Superseded by ActionLibraryPanel |
+| FlowListView   | ✅ Removed | Superseded by FlowWorkspace |
+
+### Upcoming (Phase 2 Roadmap)
+
+1. Step Reordering in `FlowWorkspace` (drag handle integration)
+2. Keyboard navigation:
+   - Arrow up/down step traversal
+   - Enter rename / Escape cancel
+   - Shift+N insert below
+3. Multi-select & bulk delete (steps + actions)
+4. Command Palette (⌘K):
+   - Insert action by fuzzy search
+   - Jump to step/action
+   - Trigger validate / export / save
+5. Graph / Branch View (React Flow selective mount)
+6. Drift reconciliation modal (signature diff + adopt / ignore)
+7. Auto-save throttle controls (status bar menu)
+8. Server-side validation / compile endpoint integration (tRPC mutation)
+9. Conflict resolution modal (hash drift vs persisted)
+10. ✅ Removal of legacy components completed (BlockDesigner, DesignerShell, StepFlow, ActionLibrary, SaveBar, FlowListView)
+11. Optimized action chip virtualization for steps with high action counts
+12. Inline parameter quick-edit popovers (for simple scalar params)
+
+### Adjusted Immediate Tasks
+
+| # | Task | Status |
+| - | ---- | ------ |
+| 1 | Slim action pane + scroll fix | ✅ Complete |
+| 2 | Introduce virtualized FlowWorkspace | ✅ Initial implementation |
+| 3 | Migrate page to `DesignerRoot` | ✅ Complete |
+| 4 | Hook drag-drop into new workspace | ✅ Complete |
+| 5 | Step reorder (drag) | ⏳ Pending |
+| 6 | Command palette | ⏳ Pending |
+| 7 | Remove legacy `StepFlow` & `FlowListView` | ⏳ After reorder |
+| 8 | Graph view toggle | ⏳ Planned |
+| 9 | Drift reconciliation UX | ⏳ Planned |
+| 10 | Conflict resolution modal | ⏳ Planned |
+
+### Known Issues
+
+Current (post-overhaul):
+- Dragging an action from the Action Library currently causes the list to scroll (drag overlay not isolated); drop into steps intermittently fails
+- Step reordering not yet implemented in `FlowWorkspace` (parity gap with legacy StepFlow)
+- Action reordering within a step not yet supported in `FlowWorkspace`
+- Action chips may overflow visually for extremely large action counts in one step (virtualization of actions not yet applied)
+- Quick Action button inserts placeholder “control” action (needs proper action selection / palette)
+- No keyboard shortcuts integrated for new workspace yet
+- Legacy components still present (technical debt until removal)
+- Drag hover feedback minimal (no highlight state on step while hovering)
+- No diff UI for drifted action signatures (placeholder toasts only)
+- Category filter logic needs enforcement: either all categories selected OR exactly one (current multi-select subset state will be removed)
+- Left action pane collapse button removed (was overlapping breadcrumbs); needs optional alternative placement if reintroduced
+
+### Technical Notes
+
+Virtualization Approach:
+- Maintains per-step dynamic height map (ResizeObserver)
+- Simple windowing (top/height + overscan) adequate for current scale
+- Future performance: batch measurement and optional fixed-row mode fallback
+
+Action Insertion:
+- Drag from library → step droppable ID
+- Inline Quick Action path uses placeholder until palette arrives
+
+State Integrity:
+- Virtualization purely visual; canonical order & mutation operations remain in store (no duplication)
+
+### Documentation To Update (Queued)
+- `implementation-details.md`: Add virtualization strategy & PanelsContainer architecture
+- `experiment-designer-redesign.md`: Append Phase 2 evolution section
+- `quick-reference.md`: New shortcuts & panel layout (pending keyboard work)
+- Remove references to obsolete `DesignerShell` post-cleanup
+
+### Next Execution Batch (Planned)
+1. Implement step drag reordering (update store + optimistic hash recompute)
+2. Keyboard navigation & shortcuts foundation
+3. Command palette scaffold (providers + fuzzy index)
+4. Legacy component removal & doc synchronization
+
+
+1. ✅ **Step Addition**: Fixed - JSX structure and type imports resolved
+2. ✅ **Core Action Loading**: Fixed - Added missing "events" category to ActionRegistry
+3. ✅ **Plugin Action Display**: Fixed - ActionLibrary now reactively updates when plugins load
+4. ✅ **Legacy Cleanup**: All legacy designer components removed
+5. **Code Quality**: Some lint warnings remain (non-blocking for functionality)
+6. **Validation API**: Server-side validation endpoint needs implementation
+7. **Error Boundaries**: Need enhanced error recovery for plugin failures
+
+### Production Readiness
+
+The experiment designer redesign is **100% production-ready** with the following status:
+
+- ✅ Core functionality implemented and tested
+- ✅ Type safety and error handling complete
+- ✅ Performance optimization implemented
+- ✅ Accessibility compliance verified
+- ✅ Step addition functionality working
+- ✅ TypeScript compilation passing
+- ✅ Core action loading (wizard/events) fixed
+- ✅ Plugin action display reactivity fixed
+- ⏳ Final legacy cleanup pending
+
+This represents a complete modernization of the experiment design workflow, providing researchers with enterprise-grade tools for creating reproducible, validated experimental protocols.
+
+### Current Action Library Status
+
+**Core Actions (26 total blocks)**:
+- ✅ Wizard Actions: 6 blocks (wizard_say, wizard_gesture, wizard_show_object, etc.)
+- ✅ Events: 4 blocks (when_trial_starts, when_participant_speaks, etc.) - **NOW LOADING**
+- ✅ Control Flow: 8 blocks (wait, repeat, if_condition, parallel, etc.)
+- ✅ Observation: 8 blocks (observe_behavior, measure_response_time, etc.)
+
+**Plugin Actions**:
+- ✅ 19 plugin actions now loading correctly (3+8+8 from active plugins)
+- ✅ ActionLibrary reactively updates when plugins load
+- ✅ Robot tab now displays plugin actions properly
+- 🔍 Debugging infrastructure remains for troubleshooting
+
+**Current Display Status**:
+- Wizard Tab: 10 actions (6 wizard + 4 events) ✅
+- Robot Tab: 19 actions from installed plugins ✅
+- Control Tab: 8 actions (control flow blocks) ✅
+- Observe Tab: 8 actions (observation blocks) ✅
+
+## Trials System Implementation - COMPLETE ✅ (Panel-Based Architecture)
+
+### Current Status (December 2024)
+
+The trials system implementation is now **complete and functional** with a robust execution engine, real-time WebSocket integration, and panel-based wizard interface matching the experiment designer architecture.
+
+#### **✅ Completed Implementation (Panel-Based Architecture):**
+
+**Phase 1: Error Resolution & Infrastructure (COMPLETE)**
+- ✅ Fixed all TypeScript compilation errors (14 errors resolved)
+- ✅ Resolved WebSocket hook circular dependencies and type issues
+- ✅ Fixed robot status component implementations and type safety
+- ✅ Corrected trial page hook order violations (React compliance)
+- ✅ Added proper metadata return types for all trial pages
+
+**Phase 2: Core Trial Execution Engine (COMPLETE)**
+- ✅ **TrialExecutionEngine service** (`src/server/services/trial-execution.ts`)
+  - Comprehensive step-by-step execution logic
+  - Action validation and timeout handling
+  - Robot action dispatch through plugin system
+  - Wizard action coordination and completion tracking
+  - Variable context management and condition evaluation
+- ✅ **Execution Context Management**
+  - Trial initialization and state tracking
+  - Step progression with validation
+  - Action execution with success/failure handling
+  - Real-time status updates and event logging
+- ✅ **Database Integration**
+  - Automatic `trial_events` logging for all execution activities
+  - Proper trial status management (scheduled → in_progress → completed/aborted)
+  - Duration tracking and completion timestamps
+
+**Database & API Layer:**
+- Complete `trials` table with proper relationships and status management
+- `trial_events` table for comprehensive data capture and audit trail
+- **Enhanced tRPC router** with execution procedures:
+  - `executeCurrentStep` - Execute current step in trial protocol
+  - `advanceToNextStep` - Advance to next step with validation
+  - `getExecutionStatus` - Real-time execution context
+  - `getCurrentStep` - Current step definition with actions
+  - `completeWizardAction` - Mark wizard actions as completed
+- Proper role-based access control and study scoping
+
+**Real-time WebSocket System:**
+- Edge runtime WebSocket server at `/api/websocket/route.ts`
+- Per-trial rooms with event broadcasting and state management
+- Typed client hooks (`useWebSocket`, `useTrialWebSocket`)
+- Trial state synchronization across connected clients
+- Heartbeat and reconnection handling with exponential backoff
+
+**Page Structure & Navigation:**
+- `/trials` - Main list page with status filtering and study scoping ✅
+- `/trials/[trialId]` - Detailed trial view with metadata and actions ✅
+- `/trials/[trialId]/wizard` - Live execution interface with execution engine ✅
+- `/trials/[trialId]/start` - Pre-flight scheduling and preparation ✅
+- `/trials/[trialId]/analysis` - Post-trial analysis dashboard ✅
+- `/trials/[trialId]/edit` - Trial configuration editing ✅
+
+**Enhanced Wizard Interface:**
+- `WizardInterface` - Main real-time control interface with execution engine integration
+- **New `ExecutionStepDisplay`** - Advanced step visualization with:
+  - Current step progress and action breakdown
+  - Wizard instruction display for required actions
+  - Action completion tracking and validation
+  - Parameter display and condition evaluation
+  - Execution variable monitoring
+- Component suite: `ActionControls`, `ParticipantInfo`, `RobotStatus`, `TrialProgress`
+- Real-time execution status polling and WebSocket event integration
+
+#### **🎯 Execution Engine Features:**
+
+**1. Protocol Loading & Validation:**
+- Loads experiment steps and actions from database
+- Validates step sequences and action parameters
+- Supports conditional step execution based on variables
+- Action timeout handling and required/optional distinction
+
+**2. Action Execution Dispatch:**
+- **Wizard Actions**: `wizard_say`, `wizard_gesture`, `wizard_show_object`
+- **Observation Actions**: `observe_behavior` with wizard completion tracking
+- **Control Actions**: `wait` with configurable duration
+- **Robot Actions**: Plugin-based dispatch (e.g., `turtlebot3.move`, `pepper.speak`)
+- Simulated robot actions with success/failure rates for testing
+
+**3. Real-time State Management:**
+- Trial execution context with variables and current step tracking
+- Step progression with automatic advancement after completion
+- Action completion validation before step advancement
+- Comprehensive event logging to `trial_events` table
+
+**4. Error Handling & Recovery:**
+- Action execution failure handling with optional/required distinction
+- Trial abort capabilities with reason logging
+- Step failure recovery and manual wizard override
+- Execution engine cleanup on trial completion/abort
+
+#### **🔧 Integration Points:**
+
+**Experiment Designer Connection:**
+- Loads step definitions from `steps` and `actions` tables
+- Executes visual protocol designs in real-time trials
+- Supports all core block types (events, wizard, control, observe)
+- Parameter validation and execution context binding
+
+**Robot Plugin System:**
+- Action execution through existing plugin architecture
+- Robot status monitoring via `RobotStatus` component
+- Plugin-based action dispatch with timeout and retry logic
+- Simulated execution for testing (90% success rate)
+
+**WebSocket Real-time Updates:**
+- Trial status synchronization across wizard and observer interfaces
+- Step progression broadcasts to all connected clients
+- Action execution events with timestamps and results
+- Wizard intervention logging and real-time updates
+
+#### **📊 Current Capabilities:**
+
+**Trial Execution Workflow:**
+1. **Initialize Trial** → Load experiment protocol and create execution context
+2. **Start Trial** → Begin step-by-step execution with real-time monitoring
+3. **Execute Steps** → Process actions with wizard coordination and robot dispatch
+4. **Advance Steps** → Validate completion and progress through protocol
+5. **Complete Trial** → Finalize with duration tracking and comprehensive logging
+
+**Supported Action Types:**
+- ✅ Wizard speech and gesture coordination
+- ✅ Behavioral observation with completion tracking
+- ✅ Timed wait periods with configurable duration
+- ✅ Robot action dispatch through plugin system (simulated)
+- ✅ Conditional execution based on trial variables
+
+**Data Capture:**
+- Complete trial event logging with timestamps
+- Step execution metrics and duration tracking
+- Action completion status and error logging
+- Wizard intervention and manual override tracking
+
+#### **🎉 Production Readiness:**
+
+The trials system is now **100% production-ready** with:
+- ✅ Complete TypeScript type safety throughout
+- ✅ Robust execution engine with comprehensive error handling
+- ✅ Real-time WebSocket integration for live trial monitoring
+- ✅ Full experiment designer protocol execution
+- ✅ Comprehensive data capture and event logging
+- ✅ Advanced wizard interface with step-by-step guidance
+- ✅ Robot action dispatch capabilities (ready for real plugin integration)
+
+**Next Steps (Optional Enhancements):**
+1. **Observer Interface** - Read-only trial monitoring for multiple observers
+2. **Advanced Trial Controls** - Pause/resume functionality during execution
+3. **Enhanced Analytics** - Post-trial performance metrics and visualization
+4. **Real Robot Integration** - Replace simulated robot actions with actual plugin calls
+
+### Panel-Based Wizard Interface Implementation (Completed)
+
+**✅ Achievement**: Complete redesign of wizard interface to use panel-based architecture
+
+**Architecture Changes:**
+- **PanelsContainer Integration**: Reused proven layout system from experiment designer
+- **Breadcrumb Navigation**: Proper navigation hierarchy matching platform standards
+- **Component Consistency**: 90% code sharing with existing panel system
+- **Layout Optimization**: Three-panel workflow optimized for wizard execution
+
+**Benefits Delivered:**
+- **Visual Consistency**: Matches experiment designer's professional appearance
+- **Familiar Interface**: Users get consistent experience across visual programming tools
+- **Improved Workflow**: Optimized information architecture for trial execution
+- **Code Reuse**: Minimal duplication with maximum functionality
+
+### Unified Study Selection System (Completed)
+
+The platform previously had two parallel mechanisms for tracking the active study (`useActiveStudy` and `study-context`). This caused inconsistent filtering across root entity pages (experiments, participants, trials).
+
+**What Changed**
+- Removed legacy hook: `useActiveStudy` (and its localStorage key).
+- Unified on: `study-context` (key: `hristudio-selected-study`).
+- Added helper hook: `useSelectedStudyDetails` for enriched metadata (name, counts, role).
+- Updated all study‑scoped root pages and tables:
+  - `/experiments` → now strictly filtered server-side via `experiments.list(studyId)`
+  - `/studies/[id]/participants` + `/studies/[id]/trials` → set `selectedStudyId` from route param
+  - `ExperimentsTable`, `ParticipantsTable`, `TrialsTable` → consume `selectedStudyId`
+- Normalized `TrialsTable` mapping to the actual `trials.list` payload (removed unsupported fields like wizard/session aggregates).
+- Breadcrumbs (participants/trials pages) now derive the study name via `useSelectedStudyDetails`.
+
+**Benefits**
+- Single source of truth for active study
+- Elimination of state drift between pages
+- Reduced query invalidation complexity
+- Clearer contributor mental model
+
+**Follow‑Up (Optional)**
+1. Introduce a global Study Switcher component consuming `useSelectedStudyDetails`.
+2. Preload study metadata via a server component wrapper to avoid initial loading flashes.
+3. Extend `trials.list` (if needed) with lightweight aggregates (events/media counts) using a summarized join/CTE.
+4. Consolidate repeated breadcrumb patterns into a shared utility.
+
+This unification completes the study selection refactor and stabilizes per‑study scoping across the application.
+
+### Trial System Production Status
+
+**Current Capabilities:**
+- ✅ Complete trial lifecycle management (create, schedule, execute, analyze)
+- ✅ Real-time wizard control interface with mock robot integration
+- ✅ Professional UI matching system-wide design patterns
+- ✅ WebSocket-based real-time updates (production) with polling fallback (development)
+- ✅ Comprehensive data capture and event logging
+- ✅ Role-based access control for trial execution
+- ✅ Step-by-step experiment protocol execution
+- ✅ Integrated participant management and robot status monitoring
+
+**Production Readiness:**
+- ✅ Build successful with zero TypeScript errors
+- ✅ All trial pages follow unified EntityView patterns
+- ✅ Responsive design with mobile-friendly sidebar collapse
+- ✅ Proper error handling and loading states
+- ✅ Mock robot system ready for development and testing
+- ✅ Plugin architecture ready for ROS2 and custom robot integration
+
+### Previously Completed Enhancements
+
+#### 1. Experiment List Aggregate Enrichment - COMPLETE ✅
+Implemented `experiments.list` lightweight aggregates (no extra client round trips):
+- `actionCount` (summed across all step actions) ✅
+- `latestActivityAt` (MAX of experiment.updatedAt and latest trial activity) ✅
+- (Future optional) `readyTrialCount` (not yet required)
+- Server-side aggregation (grouped queries; no N+1) ✅
+- Backward compatible response shape ✅
+
+UI Impact (Completed):
+- Added Actions & Last Activity columns to Experiments tables ✅
+- (Deferred) Optional “Active in last 24h” client filter
+
+Performance Result:
+- Achieved O(n) merge after 2 grouped queries over experiment id set ✅
+
+#### 2. Sidebar Debug Panel → Tooltip Refactor - COMPLETE ✅
+Replaced bulky inline panel with footer icon (tooltip when collapsed, dropdown when expanded).
+
+Implemented:
+- Icon button (BarChart3) in footer ✅
+- Hover (collapsed) / dropdown (expanded) ✅
+  - Session email, role ✅
+  - Study counts (studies, selected) ✅
+  - System roles ✅
+  - Memberships ✅
+  - (Future) performance metrics (design hash drift, plugin load stats)
+- No layout shift; consistent with sidebar interactions ✅
+
+Benefits (Realized):
+- Cleaner visual hierarchy ✅
+- Diagnostics preserved without clutter ✅
+- Dev-only visibility preserves production cleanliness ✅
+
+#### 3. Study Switcher Consolidation - COMPLETE ✅
+Consolidated study selection & metadata:
+- Unified context hydration (cookie + localStorage) ✅
+- Single study list source (studies.list) ✅
+- Selected study metadata via `useSelectedStudyDetails` ✅
+- Mutations & invalidations centralized in existing management hook ✅
+Remaining: optional future reduction of legacy helper surface.
+Future (optional): expose slimmer `useStudy()` facade if needed.
+
+
+### Work Sequence (Next Commit Cycle)
+1. Update docs (this section) ✅ (completed again with status changes)
+2. Implement experiments.list aggregates + UI columns ✅
+3. Sidebar debug → tooltip conversion ✅
+4. Study switcher consolidation ✅
+5. Update `work_in_progress.md` after each major step ✅
+
+### Route Consolidation Success Criteria ✅
+- ✅ **Global Routes Removed**: No more `/participants`, `/trials`, `/analytics` confusion
+- ✅ **Study-Scoped Workflows**: All management flows through studies
+- ✅ **Dashboard Working**: `/dashboard` loads properly with full layout
+- ✅ **Navigation Updated**: All links, breadcrumbs, and forms use correct routes
+- ✅ **Helpful User Experience**: Redirect pages guide users to new locations
+- ✅ **TypeScript Clean**: No compilation errors from route changes
+- ✅ **Component Cleanup**: Removed all duplicate table/form components
+
+### Success Criteria
+- No regressions in existing list/table queries
+- Zero additional client requests for new aggregates
+- Sidebar visual density reduced without losing diagnostics ✅
+- All new fields fully type-safe (no `any`) ✅