docs: Rewrite and finalize project README and fix ESG/production error feedbacks

README.md

@@ -7,24 +7,40 @@ sdk: docker
 pinned: false
 ---
 
-# NetZero Nav (by Aryanshh)
+# NetZero Nav
 
 **Autonomous RL logistics agent navigating global disruptions with a Net-Zero carbon mandate.**
 
-**NetZero Nav** is an AI agentic environment where an autonomous logistics agent must navigate global supply chain disruptions while adhering to strict "Net Zero" carbon mandates.
+## Overview
+**NetZero Nav** is an AI agentic simulation environment built for logistics optimization. In modern supply chains, decision-making is a multi-objective problem: balancing financial costs, delivery speed, and environmental sustainability. This project simulates a supply chain command center where an agent (or human operator) manages electronic product manufacturing while adhering strictly to "Net-Zero" carbon quotas.
+
+This interface serves as the visual playground and telemetry dashboard representing what an AI Reinforcement Learning (RL) agent interacts with behind the scenes via a custom FastAPI `/step` loop.
 
 ## The Challenge
 Every logistical decision involves a strategic trade-off:
-- **Sea Freight**: Ultra-low carbon, low cost, but very slow (10+ days).
-- **Air Freight**: High speed, but massive CO2 emissions and 5x the cost.
-- **Rail/Road**: Hybrid options for balanced regional resilience.
-
-## Core Tasks
-- **Task 1: The Sustainable Baseline**: Fulfill standard orders while selecting the most carbon-optimal routes.
-- **Task 2: Disruption Management**: A "Port Strike" or "Suez Blockade" occurs. The agent must solve the bottleneck without blowing its carbon quota.
-- **Task 3: The NetZero Crisis**: Manage a week of extreme chaos while minimizing the total CO2 footprint toward a zero-impact goal.
-
-## Tech Specs
-- **Engine**: Custom Python RL Simulator.
-- **Interface**: FastAPI (OpenEnv Spec).
-- **Evaluation**: Programmatic ESG grading (Time/Cost/CO2).
+- **Sea Freight ($10, 10 Days, 0.1kg CO2)**: Ultra-low carbon footprint and cheap, but extremely slow.
+- **Air Freight ($50, 2 Days, 2.0kg CO2)**: High speed fulfillment, but massive CO2 emissions and 5x the cost.
+- **Rail Freight ($25, 5 Days, 0.5kg CO2)**: The hybrid option for balanced regional resilience.
+
+Operators must balance raw inventory against pending order fulfillment schedules to prevent bleeding capital, while ensuring they do not breach the 1,000kg Carbon Footprint limit.
+
+## Core Features
+1. **Real-time Telemetry Dashboard**: A high-fidelity, reactive command console providing live readouts on Capital Balance, Carbon Footprint, and Raw Inventory limitations.
+2. **Dynamic Order Routing & Cart Aggregation**: The environment automatically merges overlapping delivery constraints and cleanly manages multi-batch shipments in the `Your Orders` logistics stream.
+3. **Disruption Management ("The Suez Jam")**: Triggering real-world crises blocks optimal ocean routes (e.g., SEA mode) for 7 simulation days. The agent must rapidly recompute air and rail alternatives without bankrupting the system or violating carbon quotas.
+4. **ESG Strategic Offsetting**: Allows excess capital to be dynamically diverted into Carbon Offset programs, driving the footprint back down toward sustainable parameters.
+5. **Headless Python RL Engine**: Driven entirely by a custom `AtlasEcoEnv` state machine with a strict Pydantic ruleset, validating constraints prior to DOM interaction.
+
+## Tech Stack
+- **Simulation Engine**: Custom Python RL Simulator (`env.py`)
+- **Backend Infrastructure**: FastAPI (Handling continuous Step/Reset states)
+- **Frontend Command Center**: Vanilla HTML/CSS/JS (Glassmorphic Enterprise aesthetic)
+- **Deployment**: Fully dockerized & hosted on Hugging Face Spaces
+
+## Getting Started
+To run locally:
+```bash
+pip install fastapi uvicorn pydantic
+uvicorn netzero_nav.server:app --host 0.0.0.0 --port 7860
+```
+Navigate to `http://localhost:7860/` to launch the Command Console.

dashboard/app.js

@@ -153,7 +153,6 @@ window.execute = async function(type, event, shipment_id = null) {
     if (type === 'order_parts') {
         const part = document.getElementById('part-select').value;
         const qty = parseInt(document.getElementById('qty-input').value) || 1;
-        spawnFeedback(`+${qty} ${part} ordered`, event.clientX, event.clientY);
         actionObj.part_type = part;
         actionObj.mode = document.getElementById('mode-select').value;
         actionObj.quantity = qty; 
@@ -161,11 +160,9 @@ window.execute = async function(type, event, shipment_id = null) {
         actionObj.product = document.getElementById('product-select').value;
         const qty = parseInt(document.getElementById('produce-qty-input').value) || 1;
         actionObj.quantity = qty;
-        spawnFeedback(`Initiated x${qty} run`, event.clientX, event.clientY);
     } else if (type === 'offset') {
         const amt = parseFloat(document.getElementById('offset-qty-input').value) || 10;
         actionObj.offset_amount = amt;
-        spawnFeedback(`Purchased ${amt} offsets`, event.clientX, event.clientY);
     } else if (type === 'skip') {
         actionObj.action_type = 'skip';
     } else if (type === 'cancel') {
@@ -183,8 +180,12 @@ window.execute = async function(type, event, shipment_id = null) {
         
         if (result.info && result.info.error) {
             log(`ERROR: ${result.info.error}`, 'error');
+            spawnFeedback(`❌ ${result.info.error}`, event.clientX, event.clientY);
         } else {
-            if (type === 'cancel') log(`SUCCESS: Canceled Shipment`, 'action');
+            if (type === 'order_parts') spawnFeedback(`+${actionObj.quantity} ordered`, event.clientX, event.clientY);
+            else if (type === 'produce') spawnFeedback(`Initiated x${actionObj.quantity} run`, event.clientX, event.clientY);
+            else if (type === 'offset') spawnFeedback(`Purchased ${actionObj.offset_amount} offsets`, event.clientX, event.clientY);
+            else if (type === 'cancel') log(`SUCCESS: Canceled Shipment`, 'action');
             else log(`SUCCESS: ${type === 'skip' ? 'Skipped Day' : 'Executed ' + type}`, 'action');
         }
         

netzero_nav/env.py

@@ -187,12 +187,18 @@ class AtlasEcoEnv:
 
     def _handle_offset(self, action: Action, info: dict) -> float:
         if not action.offset_amount: return -5.0
+        if self.carbon_total <= 0:
+            info["error"] = "No carbon footprint to offset"
+            return -5.0
+            
         cost = action.offset_amount * 2.0
         if self.cash_balance >= cost:
             self.cash_balance -= cost
             self.carbon_total = max(0.0, self.carbon_total - action.offset_amount)
             return 5.0
-        return -10.0
+        else:
+            info["error"] = "Insufficient funds for offset"
+            return -10.0
 
     def _handle_reroute(self, action: Action, info: dict) -> float:
         return 0.0