docs: update README for unified backend and concurrency (from feature branch)

Author: Cod-e-Codes

README.md

@@ -8,6 +8,17 @@
 
 ---
 
+## 🚀 Why Use CodeSleuth?
+
+Enterprise COBOL codebases are often large, undocumented, and hard to modernize. CodeSleuth automates structural analysis, dead code detection, and documentation — helping teams audit, refactor, or migrate legacy COBOL more confidently.
+
+---
+
+> **Note:**
+> This is the `main` branch. It currently uses a single-threaded Go CLI and separate Rust parser/summarizer binaries. **Unified backend and concurrency are available on the [`feat/concurrency-worker-pool`](https://github.com/Cod-e-Codes/codesleuth/tree/feat/concurrency-worker-pool) branch and will be merged soon.**
+
+---
+
 ## Features
 
 - **COBOL Parsing:** Rust-based parser for extracting program structure and metadata
@@ -26,6 +37,38 @@
 - **Rust Summarizer** (`summarizer/`): Consumes IR and generates Markdown reports
 - **Go CLI** (`cmd/`): Orchestrates parsing and summarization, providing a user-facing CLI
 
+> **Upcoming:**
+> The next release will unify the Rust backend and add concurrent file analysis, as already available on the feature branch.
+
+---
+
+## 🔧 Project Status
+
+This is a **work-in-progress alpha**. The `main` branch is stable for single-file and small-batch COBOL analysis. **Unified backend and concurrency are being actively tested on the feature branch and will be merged after further bug fixes.**
+
+---
+
+## 📄 Example Output
+
+```markdown
+# COBOL Program Summary
+
+**Program Name:** PAYROLL01  
+**Author:** Jane Doe  
+**Working-Storage:** 28 variables  
+**Dead Code Detected:** 3 paragraphs
+
+## Control Flow
+
+```
+
+```mermaid
+graph TD
+  Start --> Validate
+  Validate --> Process
+  Process --> End
+```
+
 ---
 
 ## Installation
@@ -70,6 +113,12 @@ cd cmd && go build -o codesleuth && cd ..
 
 # Output analysis to a Markdown file
 ./cmd/codesleuth.exe analyze path/to/your/cobol/files > analysis_report.md
+
+# Output per-file Markdown to a directory
+./cmd/codesleuth.exe analyze --output ./summaries path/to/your/cobol/files
+
+# Output JSON instead of Markdown
+./cmd/codesleuth.exe analyze --json path/to/your/cobol/files
 ```
 
 ---
@@ -108,7 +157,7 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 
 ## Roadmap & Future Enhancements
 
-- **Concurrency:** Planned support for parallel analysis of multiple files to improve performance on large codebases.
+- **Unified Backend & Concurrency:** Planned for the next release (see feature branch for early access)
 - **Configurable Output:** More options for customizing report formats and output destinations.
 - **Plugin System:** Extensible architecture for custom analysis or reporting plugins.
 - **Improved Error Handling:** More robust diagnostics and user feedback for parsing and analysis errors.
@@ -117,4 +166,4 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 
 ---
 
-*Built for maintainers and developers working with legacy COBOL systems.* 
+*Built for maintainers and developers working with legacy COBOL systems.*