docs: update readme content and remove docs from gitignore

Update README with improved formatting, updated statistics, and added comparison table
Remove docs directory from gitignore as documentation is now tracked

Author: moazbuilds

.gitignore

@@ -3,7 +3,6 @@ dist/
 coverage/
 .DS_Store
 reports/
-docs/*
 
 # Ignore specific dotfiles/folders
 .codemachine

README.md

@@ -1,22 +1,30 @@
-<h3 align="center">
+
+<p align="center">
   <code>npm i -g codemachine</code>
-</h3>
+</p>
+
 
 <p align="center">
   <strong>CodeMachine CLI</strong> is an autonomous multi-agent platform that works locally on your computer, turning specifications into production-ready code.<br></p>
 
-> ### **✨ CodeMachine Built Itself**
->
-> **90% of this entire codebase was generated by CodeMachine from a single specification file.**
-> This isn't a demo—it's proof. CodeMachine orchestrated its own architecture, planning, implementation, and testing—creating a massively scalable codebase ready for continuous updates and improvements.
-
 <p align="center">
   <img src="assets/images/codemachine-demo.gif" alt="CodeMachine in Action" width="800">
 </p>
 
+
+<p align="center">
+  <strong>✨ CodeMachine Built Itself</strong>
+</p>
+
+<p align="center">
+  <strong>90% of this entire codebase was generated by CodeMachine from a single specification file.</strong><br>
+  This isn't a demo—it's proof. CodeMachine engine orchestrated its own architecture, planning, implementation, and testing—creating a massively scalable codebase ready for continuous updates and improvements.
+</p>
+
+
 ---
 
-## **What is CodeMachine?**
+**What is CodeMachine?**
 
 CodeMachine is a CLI-native orchestration platform that transforms specification files and contextual inputs into production-ready code through coordinated multi-agent workflows. Specialized AI agents operate in hierarchical and parallel configurations with the ability for bidirectional communication, enabling runtime-adaptable methodologies that dynamically adjust to project requirements without framework modifications.
 
@@ -105,28 +113,96 @@ CodeMachine requires at least one CLI-based AI engine to handle the primary role
 
 ## **Production Validation:**
 
-CodeMachine has been battle-tested on the Sustaina Platform a full-stack ESG compliance system spanning **7 microservices**, **500+ files**, and **50,000+ lines of code** across Python, TypeScript, React, FastAPI, and NestJS.
+CodeMachine has been battle-tested on the Sustaina Platform a full-stack ESG compliance system spanning **7 microservices**, **500+ files**, and **60,000+ lines of code** across Python, TypeScript, React, FastAPI, and NestJS.
 
-<table>
+<table align="center">
   <tr>
     <td><strong>Services Generated</strong></td>
     <td>7 microservices (AI/ML + CRUD APIs)</td>
   </tr>
   <tr>
     <td><strong>Codebase Scale</strong></td>
-    <td>~500 files, 50K+ Line of code</td>
+    <td>~500 files, 60K+ Line of code</td>
   </tr>
   <tr>
     <td><strong>Tech Stack</strong></td>
     <td>React 18, FastAPI, NestJS, PostgreSQL, MongoDB, Redis, Kubernetes</td>
   </tr>
   <tr>
     <td><strong>Time to MVP</strong></td>
-    <td>~6 raw hours of autonomous orchestration</td>
+    <td>~8 hours of autonomous orchestration</td>
   </tr>
 </table>
 
-### [View detailed breakdown →](./docs/case-study-sustaina.md)
+### **CodeMachine vs Regular AI Agents**
+
+We conducted a real-world comparison by monitoring development work on a project of identical scope and complexity using the most powerful AI agent tools (Claude Code, Cursor, Copilot) with manual orchestration and human review, versus CodeMachine's autonomous multi-agent orchestration.
+
+<table align="center">
+  <tr>
+    <th><strong>Aspect</strong></th>
+    <th><strong>Regular AI Agents</strong><br/>(Manual Orchestration + Human Review)</th>
+    <th><strong>CodeMachine</strong><br/>(Autonomous Orchestration)</th>
+  </tr>
+  <tr>
+    <td><strong>Architecture Planning</strong></td>
+    <td>4-6 hours of manual prompting</td>
+    <td>Automated (30 min)</td>
+  </tr>
+  <tr>
+    <td><strong>Service Implementation</strong></td>
+    <td>140-200 hours (7 services × 20-30h each)<br/>Manual prompting, context switching</td>
+    <td>Parallel execution (5 hours)</td>
+  </tr>
+  <tr>
+    <td><strong>Integration & Testing</strong></td>
+    <td>30-50 hours<br/>Manual coordination, debugging</td>
+    <td>Automated validation (2 hours)</td>
+  </tr>
+  <tr>
+    <td><strong>Deployment Setup</strong></td>
+    <td>8-12 hours<br/>Scripts, configs, orchestration</td>
+    <td>Auto-generated (30 min)</td>
+  </tr>
+  <tr>
+    <td><strong>Code Consistency</strong></td>
+    <td>Inconsistent patterns across services<br/>Different coding styles per session</td>
+    <td>Unified architecture & patterns<br/>Consistent across all components</td>
+  </tr>
+  <tr>
+    <td><strong>Quality Control</strong></td>
+    <td>Manual review required<br/>Errors compound over time</td>
+    <td>Built-in validation at each step<br/>Automated sanity checks</td>
+  </tr>
+  <tr>
+    <td><strong>Context Retention</strong></td>
+    <td>Lost between sessions<br/>Repeated explanations needed</td>
+    <td>Full project context maintained<br/>Cross-service awareness</td>
+  </tr>
+  <tr>
+    <td><strong>Total Developer Time</strong></td>
+    <td><strong>~200-300 hours</strong></td>
+    <td><strong>~8 hours</strong></td>
+  </tr>
+  <tr>
+    <td><strong>Efficiency Gain</strong></td>
+    <td>Baseline</td>
+    <td><strong>25-37× faster</strong></td>
+  </tr>
+</table>
+
+<p align="center"><em>Real-world comparison: One developer manually prompting AI coding assistants vs CodeMachine's autonomous multi-agent orchestration</em></p>
+
+---
+
+<p align="center">
+  <strong>Want to see how CodeMachine built this?</strong><br/>
+  Explore the complete case study showing the detailed path CodeMachine took to create this project—every step, decision, and workflow tracked from specification to production.
+</p>
+
+<p align="center">
+  <a href="./docs/case-study-sustaina.md"><strong>📊 View Complete Case Study & Development Track →</strong></a>
+</p>
 
 ---