chore: initial import

docs/EVENT_GENERATION.md

@@ -0,0 +1,83 @@
+# VaultMesh Command Center: Event Generation Mechanism
+
+## Overview
+
+The VaultMesh Command Center generates events through a sophisticated, multi-layered mechanism designed for real-time monitoring and fleet management.
+
+## Event Types
+
+### 1. Heartbeat Events
+- **Trigger**: Node heartbeat submission
+- **Payload Includes**:
+  * Timestamp
+  * Node ID
+  * Hostname
+  * OS Profile
+  * Cloudflare Status
+  * Services Status
+  * VaultMesh Root Path
+  * System Metrics (uptime, load averages)
+
+### 2. Scan Events
+- **Trigger**: Successful scan result submission
+- **Payload Includes**:
+  * Timestamp
+  * Node ID
+  * Hostname
+  * OS Profile
+  * Scan Summary (critical/high/medium/low findings)
+  * Real/Mock Findings Flag
+  * Receipt Hash
+
+### 3. Command Events
+- **Trigger**: Command execution result
+- **Payload Includes**:
+  * Timestamp
+  * Node ID
+  * Hostname
+  * OS Profile
+  * Command Name
+  * Execution Status
+  * Exit Code
+  * Nonce (for replay protection)
+
+## Event Generation Flow
+
+1. **Data Collection**
+   - Node agents submit heartbeats and scan results
+   - Command results are reported back to the Command Center
+
+2. **Event Processing**
+   - Raw data is transformed into structured event payloads
+   - Events are published to a broadcast channel
+   - Server-Sent Events (SSE) distribute events to connected clients
+
+3. **State Management**
+   - Events trigger state updates (node history, last scan, etc.)
+   - Attention status is recomputed based on new events
+
+## Advanced Features
+
+- **Automatic Scan Scheduling**
+  - Periodic scans triggered based on node profile and last scan timestamp
+  - Configurable scan intervals
+
+- **Attention Computation**
+  - Dynamic assessment of node health
+  - Tracks critical findings, heartbeat staleness, service status
+
+## Security Considerations
+
+- Ed25519 key signing for commands
+- Nonce-based replay protection
+- Configurable command policies per node profile
+
+## Performance Characteristics
+
+- In-memory event storage (500 most recent events)
+- Optional JSONL log persistence
+- Low-overhead event broadcasting
+
+## Extensibility
+
+The event system supports easy addition of new event types and payloads through the `ServerEvent` enum and corresponding payload structures.