ProgrammingDevelopment · ProgrammingDevelopment · Feb 27, 2026
diff --git a/README.md b/README.md
@@ -1,25 +1,18 @@
-# System Architecture Overview
+# SigmaPrompt Robotics
 
-SigmaPrompt Robotic OS follows a distributed cognitive microservices architecture:
+SigmaPrompt is a distributed cognitive robotic operating system blueprint for production-scale humanoid deployment.
 
-Physical Robot
-   ↓
-Telemetry Ingestion Service
-   ↓
-Real-Time Analyzer
-   ↓
-SigmaPrompt Cognitive Core
-   ↓
-Decision Arbitration Engine
-   ↓
-Actuator Command Layer
-   ↓
-Monitoring Dashboard
+## Core Architecture Summary
 
----
-
-## Core Services
+Physical Robot  
+-> Telemetry Ingestion Service  
+-> Real-Time Analyzer  
+-> SigmaPrompt Cognitive Core  
+-> Decision Arbitration Engine  
+-> Actuator Command Layer  
+-> Monitoring Dashboard
 
+### Core Services
 - Telemetry Service
 - Digital Twin Engine
 - Swarm Coordinator
@@ -28,90 +21,25 @@ Monitoring Dashboard
 - Authentication Service
 - Dashboard API
 
----
-
-## Data Layer
-
+### Data Layer
 - Neon Serverless PostgreSQL
 - Drizzle ORM schema management
 - Redis event streaming
 - Partitioned telemetry storage
 
----
-
-## Infrastructure
-
+### Infrastructure
 - Docker containers
 - Kubernetes orchestration
 - Horizontal Pod Autoscaling
 - CI/CD pipeline
 
----
-
-# 12-Month Roadmap
-
-## Phase 1 (Month 1–3)
-- Core telemetry ingestion
-- Neon + Drizzle schema stabilization
-- Real-time anomaly detection MVP
-- Basic dashboard
-
-## Phase 2 (Month 4–6)
-- Digital Twin integration
-- Swarm coordination prototype
-- Advanced AI reasoning layer
-- Performance optimization
-
-## Phase 3 (Month 7–9)
-- Edge deployment mode
-- Federated robotic learning
-- Predictive maintenance engine
-- Distributed consensus refinement
-
-## Phase 4 (Month 10–12)
-- Production-grade Kubernetes scaling
-- Multi-robot fleet management
-- Enterprise security hardening
-- Observability & telemetry analytics expansion
-
----
-
-# Enterprise Integration Strategy
-
-SigmaPrompt Robotic OS is designed for industrial-grade adoption.
-
----
-
-## Target Integration Domains
-
-- Industrial automation
-- Humanoid robotics manufacturers
-- Autonomous fleet systems
-- Research institutions
-- AI infrastructure providers
-
----
-
-## Integration Capabilities
-
-- REST + gRPC APIs
-- Event-driven architecture
-- Cloud-native deployment
-- Hybrid on-prem + cloud model
-- Secure multi-tenant support
-
----
-
-## Enterprise Features (Planned)
-
-- SLA-backed deployment model
-- Dedicated cluster mode
-- Private AI routing
-- Advanced telemetry analytics
-- Enterprise observability dashboards
+## New Production Planning Documents
 
----
+- [Full system architecture diagram specification](docs/system-architecture-diagram-spec.md)
+- [Detailed API contract specification](docs/api-contract-spec.md)
+- [Formal technical whitepaper](docs/technical-whitepaper.md)
+- [Hardware integration roadmap](docs/hardware-integration-roadmap.md)
 
 ## Long-Term Vision
 
-To establish SigmaPrompt as a distributed cognitive backbone for humanoid robotics and intelligent autonomous systems worldwide.
+Distributed Cognitive Robotic Operating System with Digital Twin simulation, swarm intelligence, real-time monitoring, defensive safety framework, and AGI-ready cognitive architecture.
diff --git a/docs/api-contract-spec.md b/docs/api-contract-spec.md
@@ -0,0 +1,196 @@
+# SigmaPrompt API Contract Specification (v1)
+
+## 1. Protocol Standards
+- External client APIs: REST/JSON over HTTPS
+- Service-to-service APIs: gRPC over mTLS
+- Realtime push: WebSocket and server-sent events for dashboard streams
+- Event contracts: versioned JSON schema messages on event bus
+
+## 2. Global API Conventions
+- Base URL: `/api/v1`
+- Authentication: OAuth2/JWT bearer token
+- Tenant scoping: `X-Tenant-ID` required for enterprise requests
+- Robot scoping: `robot_id` required in all telemetry/control endpoints
+- Traceability: `X-Request-ID` propagated through all services
+
+## 3. Authentication Service
+
+### POST `/auth/token`
+Issue access token.
+
+**Request**
+```json
+{
+  "client_id": "fleet-console",
+  "client_secret": "***",
+  "grant_type": "client_credentials",
+  "scope": "telemetry:read command:write"
+}
+```
+
+**Response 200**
+```json
+{
+  "access_token": "jwt",
+  "token_type": "Bearer",
+  "expires_in": 3600
+}
+```
+
+## 4. Telemetry Ingestion Service
+
+### POST `/telemetry/events`
+Ingest batched robot telemetry.
+
+**Request**
+```json
+{
+  "robot_id": "RB-1022",
+  "timestamp": "2026-01-11T05:12:00Z",
+  "joint_state": [{"name": "knee_l", "position": 0.42, "torque_nm": 6.1}],
+  "power": {"battery_soc": 0.77, "draw_w": 312.0},
+  "thermal": {"motor_max_c": 64.2},
+  "imu": {"pitch": 0.03, "roll": -0.01, "yaw": 1.22},
+  "flags": ["nominal"]
+}
+```
+
+**Response 202**
+```json
+{
+  "accepted": true,
+  "event_id": "evt_01J...",
+  "ingested_at": "2026-01-11T05:12:00.124Z"
+}
+```
+
+## 5. Real-Time Analyzer Service
+
+### GET `/robots/{robot_id}/health`
+Returns computed health and risk summary.
+
+**Response 200**
+```json
+{
+  "robot_id": "RB-1022",
+  "health_score": 0.93,
+  "anomaly_score": 0.04,
+  "risk_level": "low",
+  "updated_at": "2026-01-11T05:12:02Z"
+}
+```
+
+## 6. Digital Twin Engine
+
+### POST `/twins/{robot_id}/simulate`
+Run an on-demand simulation mode.
+
+**Request**
+```json
+{
+  "mode": "joint_fatigue",
+  "horizon_minutes": 180,
+  "physics_backend": "mujoco",
+  "parameters": {
+    "payload_kg": 8.5,
+    "ambient_c": 36.0
+  }
+}
+```
+
+**Response 200**
+```json
+{
+  "simulation_id": "sim_7f2",
+  "failure_probability": 0.28,
+  "maintenance_window_hours": 72,
+  "risk_heatmap_uri": "s3://sigma/twins/RB-1022/sim_7f2.png"
+}
+```
+
+## 7. Swarm Coordination Service
+
+### POST `/swarm/tasks/allocate`
+Allocate tasks across active robot cluster.
+
+**Request**
+```json
+{
+  "swarm_id": "assembly-line-a",
+  "tasks": [
+    {"task_id": "pick-1", "priority": "high", "required_capabilities": ["lift", "vision"]}
+  ],
+  "constraints": {"max_latency_ms": 120, "safety_mode": "strict"}
+}
+```
+
+**Response 200**
+```json
+{
+  "allocation_id": "alloc_112",
+  "leader_robot_id": "RB-2001",
+  "assignments": [{"task_id": "pick-1", "robot_id": "RB-2009"}]
+}
+```
+
+## 8. Command and Failsafe Endpoints
+
+### POST `/robots/{robot_id}/commands`
+Dispatch validated actuator-level command.
+
+### POST `/robots/{robot_id}/failsafe/trigger`
+Trigger failsafe mode (`thermal_shutdown`, `geofence_lock`, `mechanical_lock`).
+
+### POST `/robots/{robot_id}/failsafe/recover`
+Attempt controlled recovery from safe mode.
+
+## 9. Alert Service
+
+### GET `/alerts`
+Query active and historical alerts (filter by severity, robot, window).
+
+### POST `/alerts/ack`
+Acknowledge alert with operator identity and notes.
+
+## 10. Dashboard API
+
+### GET `/dashboard/fleet/overview`
+Returns fleet KPIs: active robots, anomaly count, energy usage, and SLA status.
+
+### GET `/dashboard/stream`
+WebSocket channel for live telemetry and incident updates.
+
+## 11. Event Schemas (Bus)
+Mandatory event types:
+- `telemetry.ingested.v1`
+- `anomaly.detected.v1`
+- `failsafe.triggered.v1`
+- `swarm.leader_elected.v1`
+- `twin.simulation.completed.v1`
+
+Each event includes:
+- `event_id`
+- `event_type`
+- `occurred_at`
+- `robot_id` or `swarm_id`
+- `trace_id`
+- versioned payload
+
+## 12. Error Model
+Standard error envelope:
+```json
+{
+  "error": {
+    "code": "INVALID_ARGUMENT",
+    "message": "robot_id is required",
+    "details": [{"field": "robot_id", "reason": "missing"}],
+    "request_id": "req_..."
+  }
+}
+```
+
+## 13. SLO-aligned API Targets
+- P95 read latency: <200 ms
+- P95 command dispatch: <350 ms
+- Critical failsafe API availability: 99.99%
+- End-to-end decision window: <500 ms
diff --git a/docs/hardware-integration-roadmap.md b/docs/hardware-integration-roadmap.md
@@ -0,0 +1,61 @@
+# SigmaPrompt Hardware Integration Roadmap
+
+## Objective
+Define a phased path for integrating heterogeneous humanoid hardware into SigmaPrompt with repeatable validation gates.
+
+## Phase 0 — Interface Baseline (Weeks 1-4)
+- Finalize canonical robot interface spec (joint, power, thermal, IMU, vision, audio).
+- Define control command schema with safety envelopes.
+- Build hardware abstraction layer (HAL) adapter template.
+- Acceptance gate: one reference robot streams full telemetry and accepts sandbox commands.
+
+## Phase 1 — Sensor and Actuator Bring-Up (Weeks 5-10)
+- Integrate motor controller APIs and encoder feedback.
+- Calibrate battery BMS reporting and thermal channels.
+- Validate IMU + joint kinematics synchronization.
+- Add emergency-stop and mechanical lock GPIO hooks.
+- Acceptance gate: deterministic command roundtrip and hard-stop verified.
+
+## Phase 2 — Edge Runtime and Safety MCU (Weeks 11-16)
+- Deploy edge runtime agent on robot compute module.
+- Add local failover controller and watchdog heartbeat.
+- Implement geofence and unsafe-movement local policies.
+- Acceptance gate: robot enters safe mode autonomously under induced faults.
+
+## Phase 3 — Digital Twin Parity (Weeks 17-22)
+- Map live telemetry into state replicator.
+- Validate MuJoCo/Isaac/Gazebo adapter equivalence for key maneuvers.
+- Run fatigue and battery degradation simulations against real operation logs.
+- Acceptance gate: simulation prediction error within agreed tolerance band.
+
+## Phase 4 — Swarm Enablement (Weeks 23-30)
+- Install secure communication module for peer mesh (gRPC/WebRTC).
+- Enable distributed task engine and leader election participation.
+- Validate cooperative obstacle avoidance in multi-robot trials.
+- Acceptance gate: stable coordination under node churn and network jitter.
+
+## Phase 5 — Production Hardening (Weeks 31-40)
+- Enable firmware integrity attestation and tamper alerts.
+- Conduct thermal stress, overload, and long-run reliability tests.
+- Tune energy optimization profiles for mission classes.
+- Acceptance gate: meets latency, uptime, and failover SLO targets.
+
+## Hardware Compatibility Matrix (Initial)
+- **Compute:** NVIDIA Jetson class / x86 edge IPC
+- **Motor drivers:** CANopen / EtherCAT capable controllers
+- **Sensors:** IMU, depth camera, force-torque, thermal probes
+- **Connectivity:** Wi-Fi 6 / private 5G / wired Ethernet dock
+- **Safety:** Independent MCU + hardware interlock circuit
+
+## Test and Validation Tracks
+1. Functional hardware-in-the-loop (HIL)
+2. Safety compliance and emergency procedures
+3. Cybersecurity penetration and firmware integrity checks
+4. Endurance and environmental stress (temperature, vibration)
+
+## Deliverables by Milestone
+- Interface conformance reports
+- Calibration package and tuning profiles
+- Safety certification evidence pack
+- Twin parity benchmark report
+- Fleet readiness checklist