docs(Echo): update architectural documentation and usage examples

- Align README.md crate references from `echo-scheduler` to `Echo` for consistency with internal naming
- Refine module structure documentation to reflect final synthesized architecture separation between generic `Queue` and application-specific `Scheduler`/`Task`
- Update code samples to match actual implementation patterns (e.g., `Builder::Create()` vs `New()`)
- Enhance Deep Dive explanations of work-stealing mechanics and context ownership model
- Clarify Mountain integration workflow showing `ActionEffect` execution through Echo's scheduler

These changes ensure documentation accuracy for the core concurrency system that drives Mountain's `ActionEffect` processing and Cocoon's extension host operations.

Author: NikolaRHristov

README.md

@@ -12,7 +12,7 @@
 # **Echo** 📣 A Resilient, High-Performance Task Scheduler for Rust
 
 [![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://github.com/CodeEditorLand/Echo/tree/Current/LICENSE)
-[![Crates.io](https://img.shields.io/crates/v/echo-scheduler.svg)](https://crates.io/crates/echo-scheduler)
+[![Crates.io](https://img.shields.io/crates/v/Echo.svg)](https://crates.io/crates/Echo)
 [![Tokio Version](https://img.shields.io/badge/Tokio-v1-blue.svg)](https://tokio.rs/)
 [![Crossbeam Version](https://img.shields.io/badge/Crossbeam-v0.8-blueviolet.svg)](https://github.com/crossbeam-rs/crossbeam)
 
@@ -47,11 +47,10 @@ executing complex asynchronous workflows with resilience and efficiency.
 - **Task Prioritization:** Supports submitting tasks with `High`, `Normal`, or
   `Low` priority, ensuring that latency-sensitive operations are handled
   immediately.
-- **Fluent Builder API:** A clean `SchedulerBuilder` allows for easy
-  configuration of the worker pool and other scheduler parameters.
-- **Graceful Shutdown:** Provides a `Shutdown()` method to ensure all worker
-  threads complete their current tasks and exit cleanly, preventing orphaned
-  threads.
+- **Fluent Builder API:** A clean `Builder` allows for easy configuration of the
+  worker pool and other scheduler parameters.
+- **Graceful Shutdown:** Provides a `Stop()` method to ensure all worker threads
+  complete their current tasks and exit cleanly, preventing orphaned threads.
 - **Built for `ActionEffect`:** Serves as the ideal backend for effect systems,
   providing the runtime engine that executes declarative, asynchronous workflows
   defined in other parts of the application.
@@ -60,13 +59,13 @@ executing complex asynchronous workflows with resilience and efficiency.
 
 ## Core Architecture Principles 🏗️
 
-| Principle                  | Description                                                                                                                                             | Key Components Involved                     |
-| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------ |
-| **Performance**            | Use lock-free data structures (`crossbeam-deque`) and a work-stealing algorithm to achieve maximum throughput and low-latency task execution.           | `queue::StealingQueue`, `scheduler::Worker` |
-| **Structured Concurrency** | Manage all asynchronous operations within a supervised pool of workers, providing graceful startup and shutdown, unlike fire-and-forget `tokio::spawn`. | `scheduler::Scheduler`, `SchedulerBuilder`  |
-| **Decoupling**             | Separate the _submission_ of a task from its _execution_. The `AppRuntime` submits work, and the `Scheduler` handles how, when, and where it runs.      | `Scheduler::Submit`, `task::Task`           |
-| **Resilience**             | The scheduler's design is inherently resilient, as the failure of one task (if it panics) does not bring down the entire worker pool.                   | `scheduler::Worker` (execution loop)        |
-| **Composability**          | Provide a simple, generic `Submit` API that accepts any `Future<Output = ()>`, making it easy to integrate with any asynchronous Rust code.             | `task::Task`, `Scheduler::Submit`           |
+| Principle                  | Description                                                                                                                                             | Key Components Involved                               |
+| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------- |
+| **Performance**            | Use lock-free data structures (`crossbeam-deque`) and a work-stealing algorithm to achieve maximum throughput and low-latency task execution.           | `Queue::StealingQueue`, `Scheduler::Worker`           |
+| **Structured Concurrency** | Manage all asynchronous operations within a supervised pool of workers, providing graceful startup and shutdown, unlike fire-and-forget `tokio::spawn`. | `Scheduler::Scheduler`, `Scheduler::SchedulerBuilder` |
+| **Decoupling**             | Separate the _submission_ of a task from its _execution_. The application submits work, and the `Scheduler` handles how, when, and where it runs.       | `Scheduler::Scheduler::Submit`, `Task::Task::Task`    |
+| **Resilience**             | The scheduler's design is inherently resilient, as the failure of one task (if it panics) does not bring down the entire worker pool.                   | `Scheduler::Worker::Run` (execution loop)             |
+| **Composability**          | Provide a simple, generic `Submit` API that accepts any `Future<Output = ()>`, making it easy to integrate with any asynchronous Rust code.             | `Task::Task::Task`, `Scheduler::Scheduler::Submit`    |
 
 ---
 
@@ -91,7 +90,6 @@ graph LR
     classDef echo fill:#ffc,stroke:#333,stroke-width:2px;
     classDef rust fill:#f9d,stroke:#333,stroke-width:1px;
 
-
 	subgraph "Common (Abstract Core)"
 		ActionEffect["ActionEffect (Task Definition)"]:::common
 	end
@@ -127,10 +125,10 @@ The `Echo` repository is organized into a few core modules:
 ```
 Echo/
 └── Source/
-    ├── lib.rs                   # Crate root, declares public modules.
-    ├── scheduler/               # The main public API: Scheduler and SchedulerBuilder.
-    ├── queue/                   # The internal, high-performance work-stealing queue.
-    └── task/                    # The internal definition of a Task and its Priority.
+    ├── Library.rs               # Crate root, declares all modules.
+    ├── Scheduler/               # The main public API: Scheduler and Builder.
+    ├── Queue/                   # The generic, high-performance work-stealing queue.
+    └── Task/                    # The application-specific definition of a Task and its Priority.
 ```
 
 ---
@@ -139,64 +137,71 @@ Echo/
 
 ### Installation
 
-```sh
-# In your Cargo.toml
+To add `Echo` to your project, add the following to your `Cargo.toml`:
+
+```toml
 [dependencies]
-echo-scheduler = "0.1.0" # Or use a path dependency for local development
+Echo = { git = "https://github.com/CodeEditorLand/Echo.git", branch = "Current" }
 ```
 
 **Key Dependencies:**
 
-- `tokio`: `^1.0` (with `full` features)
-- `crossbeam-deque`: `^0.8`
-- `rand`: `^0.8`
-- `log`: `^0.4`
+- `tokio = { version = "1", features = ["full"] }`
+- `crossbeam-deque = "0.8"`
+- `rand = "0.8"`
+- `log = "0.4"`
+- `num_cpus = "1.0"`
 
 ### Usage
 
 `Echo` is designed to be integrated into an application's main entry point and
-used via a shared `AppRuntime`.
+used throughout the application, often via a shared context or runtime.
 
-1.  **Initialize the Scheduler:** Create and start the scheduler when your
-    application starts.
+1.  **Define the Public API:** In your library's root (`lib.rs` or `main.rs`),
+    re-export the primary components for easy access.
 
     ```rust
-    // In your application's main.rs
-    use Echo::scheduler::{Scheduler, SchedulerBuilder};
-    use std::sync::Arc;
-
-    let scheduler = Arc::new(SchedulerBuilder::New().WithWorkerCount(8).Build());
+    // In your application's lib.rs
+    pub use Echo::Scheduler::{Scheduler, SchedulerBuilder as Builder, Priority};
     ```
 
-2.  **Create a Runtime:** Construct a runtime object that holds the scheduler
-    and any other necessary context (like your application's `Environment`).
+2.  **Initialize the Scheduler:** Create and start the scheduler when your
+    application starts. It is typically wrapped in an `Arc` to be shared safely
+    across your application.
 
     ```rust
-    use Common::effect::AppRuntime as AppRuntimeTrait;
-
-    struct MyAppRuntime {
-        scheduler: Arc<Scheduler>,
-        // ... other context
-    }
+    // In your application's main function
+    use std::sync::Arc;
 
-    // This runtime will submit tasks to the scheduler.
-    // (See the full implementation from our synthesis session for details).
+    // Use the fluent builder to configure and build the scheduler
+    let Scheduler = Arc::new(Builder::Create().Count(8).Build());
     ```
 
-3.  **Submit Tasks:** Use your runtime to submit asynchronous work to the
-    scheduler.
+3.  **Submit Tasks:** Use the `Scheduler` instance to submit asynchronous work
+    from anywhere in your application.
 
     ```rust
-    use Echo::task::Priority;
-
     // An example async block to be run by the scheduler
-    let my_task = async {
-        println!("This is running on a worker thread!");
+    let MyTask = async {
+        println!("This is running on an Echo worker thread!");
         // ... perform some work ...
     };
 
-    // The runtime's `Run` method would internally call this:
-    runtime.scheduler.Submit(my_task, Priority::Normal);
+    // Submit the task with a desired priority
+    Scheduler.Submit(MyTask, Priority::Normal);
+
+    // Another example with high priority
+    Scheduler.Submit(async { /* critical work */ }, Priority::High);
+    ```
+
+4.  **Graceful Shutdown:** Before your application exits, ensure a clean
+    shutdown of all worker threads.
+
+    ```rust
+    // In your application's shutdown sequence
+    if let Some(mut Scheduler) = Arc::get_mut(&mut Scheduler) {
+        Scheduler.Stop().await;
+    }
     ```
 
 ---