diff --git a/README.md b/README.md
new file mode 100644
index 0000000..870e20e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,152 @@
+# Infor-Request-Response
+
+PHP library for HTTP request/response abstraction. Provides clean, static-style APIs for reading request parameters, building responses, and managing session flash messages.
+
+**Package:** `inforsistemas/rr`
+**Namespace:** `RR`
+**Requires:** PHP 8.1+
+
+---
+
+## Installation
+
+```bash
+composer require inforsistemas/rr
+```
+
+---
+
+## Classes
+
+### `Request` — Reading input parameters
+
+Fully static class. POST always takes precedence over GET.
+
+```php
+use RR\Request;
+use RR\ParamType;
+
+// Required param — throws Exception if missing
+$id = Request::requiredParam('id', ParamType::INT);
+
+// Optional param — returns default if missing
+$search = Request::optionalParam('q', ParamType::ALPHA, '');
+
+// Required array param — throws Exception if missing
+$items = Request::requiredParamArray('items');
+
+// Detect AJAX/fetch/API client requests
+if (Request::detectAjaxRequest()) {
+    // respond with JSON
+}
+```
+
+**`ParamType` enum values:** `INT`, `DOUBLE`, `ALPHA`, `ALPHANUM`
+
+---
+
+### `Response` — Building and sending responses
+
+Singleton accessed via `Response::getInstance()`. All builder methods are chainable and static.
+
+```php
+use RR\Response;
+
+// Send a plain HTML response
+Response::body('<h1>Hello</h1>')->send();
+
+// Append/prepend to the body buffer
+Response::bodyPrepend('<header>...</header>');
+Response::bodyAppend('<footer>...</footer>');
+Response::send();
+
+// Set a custom header
+Response::header('X-Custom', 'value')->send();
+
+// Send a JSON response
+Response::json(['status' => 'ok', 'data' => $result])->send();
+
+// JSONP response
+Response::json($data, 'myCallback')->send();
+
+// Redirect (303 by default)
+// Automatically returns JSON {"location": "..."} for AJAX requests
+Response::redirect('/dashboard');
+Response::redirect('/login', 302);
+
+// Redirect back to the previous page (HTTP_REFERER)
+Response::back();
+
+// Terminate execution after sending
+Response::send()->done();
+```
+
+---
+
+### `Flash` — Session-based flash messages
+
+Singleton accessed via `Flash::getInstance()`. Messages are written to the session and available on the **next** request.
+
+```php
+use RR\Flash;
+use RR\MessageType;
+
+// Add messages (shorthand methods)
+Flash::addInfo('Profile updated.');
+Flash::addSuccess('Order placed successfully!');
+Flash::addWarning('Your session will expire soon.');
+Flash::addError('Invalid credentials.');
+
+// Add a message with an explicit type
+Flash::addMessage('Something happened.', MessageType::INFO);
+
+// Read messages on the next request
+if (Flash::hasMessageType(MessageType::ERROR)) {
+    $errors = Flash::getError();
+}
+
+$infos    = Flash::getInfos();
+$successes = Flash::getSuccess();
+$warnings = Flash::getWarning();
+$errors   = Flash::getError();
+
+// Get all messages of any type
+$messages = Flash::getMessages(MessageType::SUCCESS);
+```
+
+**`MessageType` enum values:** `INFO`, `SUCCESS`, `WARNING`, `ERROR`
+
+---
+
+## Typical usage pattern
+
+```php
+use RR\Request;
+use RR\Response;
+use RR\Flash;
+use RR\ParamType;
+
+// Controller action
+function store(): void
+{
+    try {
+        $name  = Request::requiredParam('name', ParamType::ALPHA);
+        $price = Request::requiredParam('price', ParamType::DOUBLE);
+
+        // ... save to DB ...
+
+        Flash::addSuccess('Item created successfully.');
+        Response::redirect('/items');
+
+    } catch (\Exception $e) {
+        Flash::addError('Missing required fields.');
+        Response::back();
+    }
+}
+```
+
+---
+
+## License
+
+See [composer.json](composer.json) for author information.