diff --git a/README.md b/README.md
index a3b79a634..414e12b29 100644
--- a/README.md
+++ b/README.md
@@ -8,10 +8,27 @@
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Modules](#modules)
+- [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+- [Maven](#maven)
+- [Gradle](#gradle)
+- [Usage Examples](#usage-examples)
+- [Building from Source](#building-from-source)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [Getting Help](#getting-help)
+- [Maintainers](#maintainers)
+- [License](#license)
+
## Introduction
Microsphere Java Framework is a foundational library that serves as the backbone
-for [MicroSphere](https://github.com/microsphere-projects) ecosystem. It provides a rich set of reusable components,
+for the [MicroSphere](https://github.com/microsphere-projects) ecosystem. It provides a rich set of reusable components,
utilities, and annotation processing capabilities that address common challenges in Java development. Whether you're
building enterprise applications, microservices, or standalone Java tools, this framework offers the building blocks you
need to accelerate development and maintain consistency across your projects.
@@ -22,145 +39,202 @@ frameworks like Spring, making it a versatile addition to any Java developer's t
## Features
-- Core Utilities
-- I/O
-- Collection manipulation
-- Class loading
-- Concurrency
-- Reflection
-- Networking
-- Artifact management
-- Event Sourcing
-- JMX
-- Versioning
-- Annotation processing
-- Tools
-- Testing
+- **String & Collection Utilities** — Null-safe helpers for strings, arrays, lists, sets, maps, and deques
+- **Reflection Utilities** — Simplified access to fields, methods, constructors, and generic type arguments
+- **Type Conversion** — Extensible `Converter` SPI with built-in converters for standard Java types (primitives, collections, `Duration`, `InputStream`, and more)
+- **Event Dispatching** — Lightweight `EventDispatcher` with sequential and parallel execution modes
+- **Class Loading & Artifact Detection** — Utilities for classpath scanning, JAR introspection, and Maven/module artifact resolution
+- **Networking** — Custom `URLStreamHandler` and URL utility helpers
+- **I/O** — Enhanced file, stream, and charset utilities, plus a file-watch service
+- **Concurrency** — Delegating executor wrappers and custom thread factory
+- **Configuration Properties** — SPI-based property loading with annotation-driven generation
+- **Annotation Processing** — Compile-time processor for `@ConfigurationProperty` metadata generation
+- **Language Model** — Components and utilities for the Java Language Model API
+- **JDK Tools** — Helpers bridging the Java compiler and annotation processing tool APIs
+- **Testing Support** — Base classes and utilities for JUnit 5-based unit tests
## Modules
-The framework is organized into several key modules:
+The framework is organized into several focused modules:
+
+| Module | Artifact ID | Purpose |
+|----------------------------------|------------------------------------|------------------------------------------------------------------------------------------------------|
+| microsphere-java-annotations | `microsphere-java-annotations` | Common annotations (`@Nullable`, `@Nonnull`, `@Immutable`, `@Experimental`, `@Since`, …) |
+| microsphere-java-core | `microsphere-java-core` | Core utilities: strings, collections, reflection, I/O, concurrency, events, type conversion, and more |
+| microsphere-lang-model | `microsphere-lang-model` | Components and utilities for the Java Language Model API |
+| microsphere-jdk-tools | `microsphere-jdk-tools` | Helpers for Java compiler and JDK tool APIs |
+| microsphere-annotation-processor | `microsphere-annotation-processor` | Compile-time annotation processor for `@ConfigurationProperty` metadata generation |
+| microsphere-java-test | `microsphere-java-test` | Models and utilities for JUnit 5-based testing |
+| microsphere-java-dependencies | `microsphere-java-dependencies` | BOM (Bill of Materials) managing dependency versions across the project |
+| microsphere-java-parent | `microsphere-java-parent` | Parent POM with shared build configuration |
- Module | Purpose
-----------------------------------|-----------------------------------------------------------------------------------------------------
- microsphere-java-annotations | Provides the common annotations for Microsphere Java projects.
- microsphere-java-core | Provides the core utilities across various domains like annotations, collections, concurrency, etc.
- microsphere-java-model | Provides the components and utilities across Java Language Model API.
- microsphere-jdk-tools | Offers the components for Java tools.
- microsphere-annotation-processor | Offers annotation processing capabilities for compile-time code generation.
- microsphere-java-test | Provides the models and components for Java testing.
- microsphere-java-dependencies | Manages dependency versions across the project.
- microsphere-java-parent | Parent POM with shared configurations.
+## Prerequisites
+
+- **Java** 8, 11, 17, 21, or 25 (all actively tested in CI)
+- **Maven** 3.6+ (or use the included `mvnw`/`mvnw.cmd` wrapper)
## Getting Started
-The easiest way to get started is by adding the Microsphere Java BOM (Bill of Materials) to your project's pom.xml:
+### Maven
-```xml
+Add the BOM to your `pom.xml` to manage versions centrally:
+```xml
-
- ...
-
-
- io.github.microsphere-projects
- microsphere-java-dependencies
- ${microsphere-java.version}
- pom
- import
-
- ...
-
+
+
+ io.github.microsphere-projects
+ microsphere-java-dependencies
+ ${microsphere-java.version}
+ pom
+ import
+
+
```
-Then add the specific modules you need:
+Then declare only the modules you need:
```xml
-
-
-
- io.github.microsphere-projects
- microsphere-java-core
-
-
-
-
- io.github.microsphere-projects
- microsphere-annotation-processor
-
+
+
+ io.github.microsphere-projects
+ microsphere-java-core
+
+
+
+
+ io.github.microsphere-projects
+ microsphere-annotation-processor
+ true
+
```
-### Quick Examples
+### Gradle
+
+```groovy
+dependencies {
+ implementation platform("io.github.microsphere-projects:microsphere-java-dependencies:${microsphereJavaVersion}")
+
+ implementation "io.github.microsphere-projects:microsphere-java-core"
+ annotationProcessor "io.github.microsphere-projects:microsphere-annotation-processor"
+}
+```
+
+### Usage Examples
+
+#### String Utilities
```java
import io.microsphere.util.StringUtils;
-import org.junit.jupiter.api.Test;
-import static org.junit.jupiter.api.Assertions.*;
+StringUtils.isBlank(null); // true
+StringUtils.isBlank(""); // true
+StringUtils.isBlank(" "); // true
+StringUtils.isBlank("Hello"); // false
+```
-public class MicrosphereTest {
+#### Collection Utilities
- @Test
- public void testStringUtils() {
- assertTrue(StringUtils.isBlank(null));
- assertTrue(StringUtils.isBlank(""));
- assertFalse(StringUtils.isBlank("Hello"));
- }
-}
+```java
+import io.microsphere.collection.CollectionUtils;
+
+CollectionUtils.isEmpty(null); // true
+CollectionUtils.isEmpty(List.of()); // true
+CollectionUtils.isEmpty(List.of("item")); // false
```
-## Building from Source
+#### Reflection Utilities
+
+```java
+import io.microsphere.reflect.FieldUtils;
+import io.microsphere.reflect.MethodUtils;
+
+// Read a private field value without boilerplate
+Object value = FieldUtils.getFieldValue(myObject, "fieldName");
+
+// Find all declared methods matching a predicate
+Set methods = MethodUtils.findMethods(MyClass.class, m -> m.isAnnotationPresent(Override.class));
+```
-You don't need to build from source unless you want to try out the latest code or contribute to the project.
+#### Type Conversion
-To build the project, follow these steps:
+```java
+import io.microsphere.convert.Converters;
+
+// Convert a String to Integer
+Integer number = Converters.convert("42", Integer.class);
+
+// Convert a String to a List of Strings
+List items = Converters.convert("a,b,c", List.class);
+```
-1. Clone the repository:
+#### Event Dispatching
+
+```java
+import io.microsphere.event.EventDispatcher;
+import io.microsphere.event.EventListener;
+
+// Sequential (direct) dispatcher
+EventDispatcher dispatcher = EventDispatcher.newDefault();
+dispatcher.addEventListener((EventListener) event -> System.out.println("Received: " + event));
+dispatcher.dispatch(new MyEvent("hello"));
+
+// Parallel dispatcher with a custom thread pool
+Executor executor = Executors.newFixedThreadPool(4);
+EventDispatcher parallel = EventDispatcher.parallel(executor);
+parallel.addEventListener(myListener);
+parallel.dispatch(new MyEvent("world"));
+```
+
+#### Artifact / Version Detection
+
+```java
+import io.microsphere.util.Version;
+
+// Detect the runtime version of a library from its JAR manifest
+Version springVersion = Version.ofVersion(org.springframework.core.SpringVersion.class);
+boolean isModern = springVersion.isGreaterThanOrEqualTo("6.0.0");
+```
+
+## Building from Source
+
+You don't need to build from source to use the library — published artifacts are available on Maven Central.
+Clone and build only if you want to try the latest unreleased code or contribute to the project.
```bash
git clone https://github.com/microsphere-projects/microsphere-java.git
+cd microsphere-java
```
-2. Build the source:
-
-- Linux/MacOS:
+**Linux / macOS**
```bash
./mvnw package
```
-- Windows:
+**Windows**
```powershell
mvnw.cmd package
```
-## Contributing
-
-We welcome your contributions! Please read [Code of Conduct](./CODE_OF_CONDUCT.md) before submitting a pull request.
+To run the full test suite with coverage:
-## Reporting Issues
-
-* Before you log a bug, please search the [issues](https://github.com/microsphere-projects/microsphere-java/issues) to
- see if someone has already reported the problem.
-* If the issue doesn't already
- exist, [create a new issue](https://github.com/microsphere-projects/microsphere-java/issues/new).
-* Please provide as much information as possible with the issue report.
+```bash
+./mvnw test --activate-profiles test,coverage
+```
## Documentation
-## User Guide
-
-[](https://deepwiki.com/microsphere-projects/microsphere-java)
-
-[](https://zread.ai/microsphere-projects/microsphere-java)
-
-### Wiki
-
-[Github Host](https://github.com/microsphere-projects/microsphere-java/wiki)
+| Resource | Link |
+|----------|------|
+| AI-powered docs (DeepWiki) | [](https://deepwiki.com/microsphere-projects/microsphere-java) |
+| Ask Zread | [](https://zread.ai/microsphere-projects/microsphere-java) |
+| Wiki | [GitHub Wiki](https://github.com/microsphere-projects/microsphere-java/wiki) |
+| Release Notes | [release-notes.md](./release-notes.md) |
### JavaDoc
@@ -171,6 +245,29 @@ We welcome your contributions! Please read [Code of Conduct](./CODE_OF_CONDUCT.m
- [microsphere-annotation-processor](https://javadoc.io/doc/io.github.microsphere-projects/microsphere-annotation-processor)
- [microsphere-java-test](https://javadoc.io/doc/io.github.microsphere-projects/microsphere-java-test)
+## Contributing
+
+Contributions are welcome! To get started:
+
+1. Fork the repository and create a feature branch.
+2. Make your changes with tests.
+3. Ensure all tests pass: `./mvnw test`
+4. Submit a pull request against the `main` branch.
+
+Please read [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing.
+
+## Getting Help
+
+- **Bug reports & feature requests** — [Open an issue](https://github.com/microsphere-projects/microsphere-java/issues/new) (search [existing issues](https://github.com/microsphere-projects/microsphere-java/issues) first)
+- **Questions & discussions** — [GitHub Discussions](https://github.com/microsphere-projects/microsphere-java/discussions)
+- **AI-powered documentation** — [DeepWiki](https://deepwiki.com/microsphere-projects/microsphere-java)
+
+## Maintainers
+
+| Name | Role | Contact |
+|------|------|---------|
+| [Mercy Ma (mercyblitz)](https://github.com/mercyblitz) | Lead Architect & Developer | mercyblitz@gmail.com |
+
## License
-The Microsphere Java is released under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+The Microsphere Java Framework is released under the [Apache License 2.0](./LICENSE).