feat: scaffold BlackRoad OS Phase 2 infrastructure

Implements complete Phase 2 scaffold across 6 core modules:

## New Modules

### 1. Backend API Enhancements
- Add system router with /version, /config/public, /os/state endpoints
- Register system router in main.py
- Add comprehensive tests for system endpoints

### 2. Core OS Runtime (core_os/)
- Implement UserSession, Window, OSState models
- Add state management functions (open_window, close_window, etc.)
- Create Backend API adapter for communication
- Include full test suite for models and state

### 3. Operator Engine (operator_engine/)
- Build job registry with example jobs
- Implement simple scheduler with lifecycle management
- Optional HTTP server on port 8001
- Complete tests for jobs and scheduler

### 4. Web Client Enhancements
- Add CoreOSClient JavaScript class
- Integrate system API endpoints
- Event-driven architecture for state updates
- Zero dependencies, vanilla JavaScript

### 5. Prism Console (prism-console/)
- Modern dark-themed admin UI
- Multi-tab navigation (Overview, Jobs, Agents, Logs, System)
- Real-time metrics dashboard
- Backend API integration with auto-refresh

### 6. Documentation (codex-docs/)
- Complete MkDocs-based documentation
- Architecture guides and component docs
- Infrastructure setup guides
- API reference documentation

## CI/CD

- Add core-os-tests.yml workflow
- Add operator-tests.yml workflow
- Add docs-build.yml workflow

## Documentation

- Create BLACKROAD_OS_REPO_MAP.md cross-reference
- Add README for each module
- Comprehensive integration documentation

## Summary

- 37 new files created
- ~3,500 lines of new code
- 5 test suites with 15+ tests
- 3 new CI workflows
- 10+ documentation pages

All modules are minimal working skeletons ready for integration.
Designed to be extracted into separate repos if needed.

Phase 2 scaffold complete and ready for review.

core_os/README.md

@@ -0,0 +1,227 @@
+## BlackRoad Core OS Runtime
+
+**Version:** 0.1.0
+**Status:** Phase 2 Scaffold
+
+## Overview
+
+The Core OS Runtime is the heart of BlackRoad OS. It manages the operating system state, window management, user sessions, and provides the foundation for the desktop experience.
+
+## Features
+
+- **Session Management**: User session tracking and authentication state
+- **Window Management**: Create, minimize, maximize, and close windows
+- **State Management**: Centralized OS state with desktop, taskbar, and system tray
+- **API Integration**: Adapter for backend API communication
+- **Extensible**: Designed to integrate with backend persistence and real-time sync
+
+## Architecture
+
+```
+core_os/
+├── __init__.py          # Package exports
+├── models.py            # Data models (UserSession, Window, OSState)
+├── state.py             # State management functions
+├── adapters/            # External service adapters
+│   ├── __init__.py
+│   └── api_client.py    # Backend API client
+├── tests/               # Test suite
+│   ├── test_models.py
+│   └── test_state.py
+└── README.md            # This file
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from core_os import get_initial_state, open_window, close_window
+
+# Get initial OS state
+state = get_initial_state()
+print(f"Session: {state.session.display_name}")
+print(f"Desktop items: {len(state.desktop_items)}")
+
+# Open a window
+state = open_window("notepad", "Untitled - Notepad")
+print(f"Windows open: {len(state.windows)}")
+
+# Close the window
+window_id = state.windows[0].id
+state = close_window(window_id)
+print(f"Windows remaining: {len(state.windows)}")
+```
+
+### With Backend API
+
+```python
+from core_os.adapters.api_client import BackendAPIClient
+
+# Create client
+api = BackendAPIClient("http://localhost:8000")
+
+# Check backend health
+healthy = await api.health_check()
+print(f"Backend healthy: {healthy}")
+
+# Get backend version
+version = await api.get_version()
+print(f"Backend version: {version['version']}")
+
+# Get public config
+config = await api.get_public_config()
+print(f"Features: {config['features']}")
+```
+
+## Models
+
+### UserSession
+
+Represents a user session with:
+- `id`: Unique session ID
+- `user_id`: User ID from auth system
+- `display_name`: Display name
+- `created_at`: Session creation time
+- `last_activity`: Last activity time
+
+### Window
+
+Represents an application window with:
+- `id`: Unique window ID
+- `app_id`: Application identifier
+- `title`: Window title
+- `state`: Window state (normal, minimized, maximized)
+- `position`: Window position (x, y)
+- `size`: Window size (width, height)
+- `z_index`: Z-index for layering
+
+### OSState
+
+Complete OS state with:
+- `session`: Current user session
+- `windows`: List of open windows
+- `active_window_id`: Currently focused window
+- `desktop_items`: Desktop icons/shortcuts
+- `taskbar_items`: Taskbar items
+- `system_tray_items`: System tray items
+- `theme`: Current theme name
+
+## State Management Functions
+
+```python
+# Get current state
+state = get_current_state()
+
+# Open a window
+state = open_window("calculator", "Calculator")
+
+# Close a window
+state = close_window(window_id)
+
+# Minimize/maximize windows
+state = minimize_window(window_id)
+state = maximize_window(window_id)
+
+# Set active window
+state = set_active_window(window_id)
+
+# Reset to initial state
+state = reset_state()
+```
+
+## Running Tests
+
+```bash
+# Install pytest if not already installed
+pip install pytest
+
+# Run tests
+python -m pytest core_os/tests/ -v
+
+# With coverage
+python -m pytest core_os/tests/ --cov=core_os --cov-report=html
+```
+
+## Integration with BlackRoad OS
+
+The Core OS integrates with:
+
+- **Backend API** - State persistence and authentication
+- **Frontend (Pocket OS)** - Desktop UI rendering
+- **Operator Engine** - Background task execution
+- **Prism Console** - Admin monitoring and debugging
+
+## Phase 2 Roadmap
+
+Current implementation is a **minimal scaffold**. Production roadmap includes:
+
+- [ ] Persistent state storage (Redis/PostgreSQL)
+- [ ] Real-time state sync (WebSocket)
+- [ ] Multi-user session support
+- [ ] Window focus management
+- [ ] Desktop customization (icons, wallpaper)
+- [ ] Theme switching (classic, dark, custom)
+- [ ] Clipboard management
+- [ ] Keyboard shortcuts
+- [ ] Drag-and-drop support
+- [ ] Window snapping and tiling
+
+## How to Run Locally
+
+```bash
+# As a library (import in Python)
+python
+>>> from core_os import get_initial_state, open_window
+>>> state = get_initial_state()
+>>> print(state.to_dict())
+
+# Run tests
+pytest core_os/tests/
+```
+
+## API Client Usage
+
+```python
+import asyncio
+from core_os.adapters.api_client import BackendAPIClient
+
+async def main():
+    client = BackendAPIClient("http://localhost:8000")
+
+    # Health check
+    if await client.health_check():
+        print("Backend is healthy!")
+
+        # Get version
+        version = await client.get_version()
+        print(f"Version: {version['version']}")
+
+        # Get config
+        config = await client.get_public_config()
+        print(f"Environment: {config['environment']}")
+
+asyncio.run(main())
+```
+
+## Development
+
+```bash
+# Install dependencies
+pip install httpx pytest
+
+# Run tests
+pytest core_os/tests/
+
+# Test with backend
+# 1. Start backend: cd backend && uvicorn app.main:app --reload
+# 2. Run integration tests
+```
+
+## License
+
+Part of BlackRoad Operating System - MIT License
+
+---
+
+**Next Steps**: Integrate with backend persistence, add WebSocket for real-time sync, implement window focus management.