ocs: improve README structure and project overview

README.md

@@ -1,38 +1,198 @@
 # mohu
 
-Rust-powered arrays for Python. Fast, parallel, and built for the future.
+**Rust-powered arrays for Python. Fast, parallel, and built for modern data workloads.**
 
-mohu is an early-stage NumPy replacement with its core written in Rust. The goal is simple — take everything Python's scientific stack does and do it without the bottlenecks that have been accepted for decades.
+mohu is an early-stage attempt to build a NumPy-compatible array system with its core implemented in Rust. The goal is to explore a faster, more parallel-friendly foundation for Python numerical computing.
 
-No GIL. No single-threaded ops. No object overhead. Just arrays.
+---
 
-## why
+## 🚀 Overview
 
-NumPy is written in C and hasn't fundamentally changed in 20 years. It's single-threaded by default, its string arrays are an afterthought, and parallelism requires reaching for other tools. The Python data ecosystem deserves a better foundation.
+mohu focuses on:
 
-Polars proved you can rewrite the data layer in Rust and win. mohu is that same bet, one layer down.
+- Rust-backed array execution
+- Parallel operations by default
+- Efficient memory layouts using Apache Arrow
+- Python interoperability via PyO3
 
-## what's coming
+The project is inspired by the idea that modern hardware and modern data workloads deserve a modern numerical computing foundation.
+
+---
+
+## ❓ Why This Exists
+
+Python’s numerical ecosystem is powerful, but much of its foundation was designed decades ago.
+
+Some common limitations include:
+
+- NumPy is primarily single-threaded for many operations
+- Object-based arrays introduce significant overhead
+- Parallel execution is not the default model
+- Memory layouts are constrained by legacy design decisions
+
+Modern workloads increasingly demand:
+
+- Parallel execution
+- Cache-efficient memory layouts
+- Zero-copy interoperability
+- Better utilization of modern CPUs
+
+mohu explores an alternative approach using Rust as the core execution engine.
+
+---
+
+## 🗺️ Roadmap
+
+This project is in active early development.
+
+### Planned Features
 
 - N-dimensional arrays with a NumPy-compatible API
-- Parallel operations by default via Rayon
-- First-class string arrays — not `dtype=object`
-- Built on Apache Arrow — interop with Polars, DuckDB, and the rest of the ecosystem out of the box
-- Zero-copy Python integration via PyO3
-- SIMD-accelerated math ops
-- Memory layouts NumPy can't express
+- Parallel operations powered by Rayon
+- First-class string arrays (without `dtype=object`)
+- Apache Arrow-based memory model
+- Zero-copy Python bindings through PyO3
+- SIMD-accelerated numerical operations
+- Flexible memory layouts beyond NumPy constraints
+
+---
+
+## ⚡ Quick Start
+
+> ⚠️ APIs are unstable and may change frequently.
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/<your-fork>/mohu.git
+cd mohu
+```
+
+### 2. Install Dependencies
+
+Requirements:
+
+- Rust (latest stable)
+- Python 3.9+
+- maturin
+
+Install maturin:
+
+```bash
+pip install maturin
+```
+
+### 3. Build the Python Extension
+
+```bash
+maturin develop
+```
+
+This compiles the Rust core and exposes it as a Python package.
+
+### 4. Example Usage
+
+```python
+import mohu as mh
+
+arr = mh.array([1, 2, 3, 4])
+
+print(arr)
+
+# Placeholder example
+result = arr
+```
+
+---
+
+## 🏗️ Architecture
+
+| Component | Purpose |
+|------------|----------|
+| Rust | Core compute engine |
+| PyO3 | Python bindings |
+| Rayon | Parallel execution |
+| Apache Arrow | Columnar memory model |
+
+---
+
+## 🧠 Design Principles
+
+### Parallel by Default
+
+Operations should automatically take advantage of available CPU cores.
+
+### Zero-Copy Where Possible
+
+Avoid unnecessary memory duplication and movement.
+
+### Interoperability First
+
+Designed to integrate naturally with the Arrow ecosystem.
+
+### Performance-Oriented
+
+SIMD acceleration, efficient memory layouts, and cache locality are core priorities.
+
+---
+
+## 📦 Project Status
+
+mohu is currently experimental.
+
+| Area | Status |
+|--------|---------|
+| Core Array Engine | 🚧 In Progress |
+| Python Bindings | 🚧 In Progress |
+| API Stability | ⚠️ Not Stable |
+| Production Ready | ❌ No |
+
+Expect frequent changes as development continues.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome.
+
+Areas where help is especially valuable:
+
+- Documentation improvements
+- Python API design feedback
+- Rust performance optimizations
+- Testing and benchmarking
+- Developer tooling
+
+### Development Workflow
+
+```bash
+git clone https://github.com/<your-fork>/mohu.git
+cd mohu
+
+git checkout -b feature/my-change
+
+# Make your changes
+
+git add .
+git commit -m "feat: describe your change"
+
+git push origin feature/my-change
+```
+
+Then open a Pull Request.
+
+---
+
+## 📄 License
 
-## status
+Licensed under the MIT License.
 
-Early. The foundation is being laid. If you believe the Python numerical stack deserves a rewrite, watch this repo or contribute.
+See the `LICENSE` file for details.
 
-## built with
+---
 
-- [Rust](https://rust-lang.org)
-- [PyO3](https://github.com/PyO3/pyo3) — Python bindings
-- [arrow-rs](https://github.com/apache/arrow-rs) — columnar memory format
-- [Rayon](https://github.com/rayon-rs/rayon) — data parallelism
+## ⚠️ Important Note
 
-## license
+mohu is currently experimental and should not be considered a drop-in replacement for NumPy.
 
-MIT
+The project is still laying its foundations, and substantial changes should be expected as development progresses.