docs: standardize and enhance READMEs for all crates

Author: Tuntii

crates/cargo-rustapi/README.md

@@ -1,66 +1,61 @@
 # cargo-rustapi
 
-The official CLI tool for the RustAPI framework. Scaffold new projects, run development servers, and manage database migrations.
+**The official CLI tool for the RustAPI framework.**
 
-## Installation
+Use this tool to scaffold new projects, generate code, and fast-track your development workflow.
 
-`ash
+## 📦 Installation
+
+```bash
 cargo install cargo-rustapi
-`
+```
 
-## Features
+## 🛠️ Usage
 
-- **Project Scaffolding**: Create new projects with 
-ew command, choosing from templates like pi, web, or ull.
-- **Development Server**: Run your project with un command, supporting hot-reloading (via cargo-watch integration if available).
-- **Code Generation**: Generate handlers, models, and CRUD operations with generate.
-- **Database Management**: (Planned) Simple wrappers around migration tools.
+### Creating a New Project
 
-## Usage
+Use the `new` command to generate a project structure.
 
-### Create a New Project
+```bash
+# Interactive mode (Recommended)
+cargo rustapi new my-app
 
-`ash
-# Interactive mode
-cargo rustapi new my-project
+# Quick start with specific template
+cargo rustapi new my-app --template api
+```
 
-# With template
-cargo rustapi new my-project --template api
+**Available Templates:**
+- `minimal`: Basic `main.rs` and `Cargo.toml`.
+- `api`: REST API structure with separated `handlers` and `models`.
+- `web`: Web application with HTML templates (`rustapi-view`).
+- `full`: Complete example with Database, Auth, and Docker support.
 
-# With features
-cargo rustapi new my-project --features jwt,cors
-`
+### Running Development Server
 
-### Run Development Server
+Run your application with hot-reloading (requires `cargo-watch`).
 
-`ash
-# Run with auto-reload
+```bash
 cargo rustapi run
+```
 
-# Run on specific port
-cargo rustapi run --port 8080
-`
+### Code Generation
 
-### Generate Code
+Save time by generating boilerplate.
 
-`ash
-# Generate a new handler
+```bash
+# Generate a handler function and register it
 cargo rustapi generate handler users
 
-# Generate a model
+# Generate a database model
 cargo rustapi generate model User
 
-# Generate CRUD endpoints (Handlers + Models + Tests)
-cargo rustapi generate crud users
-`
-
-## Templates
-
-- minimal: Bare bones setup.
-- pi: REST API structure with handlers and models.
-- web: Includes ustapi-view and 	emplates folder.
-- ull: Complete setup with Auth, DB (SQLx), and more.
+# Generate a full CRUD resource (Model + Handlers + Tests)
+cargo rustapi generate crud product
+```
 
-## License
+### Managing Migrations (Planned)
 
-MIT OR Apache-2.0
+```bash
+cargo rustapi migrate run
+cargo rustapi migrate revert
+```

crates/rustapi-core/README.md

@@ -1,16 +1,37 @@
 # RustAPI Core
 
-The core engine for the RustAPI framework.
+**The internal engine of the RustAPI framework.**
 
-> **Note**: This is an internal crate. You should depend on `rustapi-rs` instead.
+> ⚠️ **Warning**: Most users should depend on `rustapi-rs` instead of using this crate directly. This crate's API is subject to change to support the higher-level facade.
 
-## Responsibilities
+## Overview
 
-- **HTTP Server**: Wraps `hyper` 1.0.
-- **Routing**: Implements radix-tree routing via `matchit`.
-- **Glue Code**: Connects extractors, handlers, and responses.
-- **Middleware Integration**: Provides `tower` compatibility (internal).
+`rustapi-core` handles the low-level HTTP mechanics, leveraging the best-in-class Rust async ecosystem:
 
-## Architecture
+- **Hyper 1.0**: For robust, correct HTTP/1 and HTTP/2 implementation.
+- **Matchit**: For extremely fast URL routing (radix tree based).
+- **Tower**: For middleware composition (Service, Layer).
+- **Tokio**: For the async runtime.
 
-This crate provides the `RustApi` builder and the `Handler` trait system that powers the framework's ergonomics.
+## Key Concepts
+
+### The `RustApi` Builder
+Responsible for assembling routes, middleware, and starting the Hyper server.
+
+### The `Handler` Trait
+The magic that allows functions with arbitrary arguments (extractors) to be used as request handlers.
+
+```rust
+// This function...
+async fn my_handler(Json(body): Json<MyData>) -> impl Responder { ... }
+
+// ...is converted into a Tower Service via the Handler trait.
+```
+
+### Extractors
+`FromRequest` and `FromRequestParts` traits are defined here. They allow type-safe extraction of data from HTTP requests.
+
+- `Json<T>`
+- `Query<T>`
+- `Path<T>`
+- `State<T>`

crates/rustapi-extras/README.md

@@ -1,71 +1,48 @@
-# rustapi-extras
+# RustAPI Extras
 
-Optional security and utility features for the RustAPI framework.
+**Production-ready middleware and utilities for RustAPI.**
 
-## Features
+This crate provides optional "batteries" that you can enable to build robust applications.
 
-This crate provides production-ready middleware and utilities that are opt-in via Cargo feature flags to minimize binary size when not needed.
+## Feature Flags
 
-### Available Features
+Enable these in your `Cargo.toml`.
 
-- `jwt` - JWT authentication middleware and `AuthUser<T>` extractor
-- `cors` - CORS middleware with builder pattern configuration
-- `rate-limit` - IP-based rate limiting middleware
-- `config` - Configuration management with `.env` file support
-- `cookies` - Cookie parsing extractor
-- `extras` - Meta feature enabling jwt, cors, and rate-limit
-- `full` - All features enabled
+| Feature | Description | Dependencies |
+|---------|-------------|--------------|
+| `jwt` | JSON Web Token authentication extractor & middleware | `jsonwebtoken` |
+| `cors` | Cross-Origin Resource Sharing middleware | `tower-http` |
+| `rate-limit` | IP-based rate limiting | `governor` / `dashmap` |
+| `sqlx` | Database integration helpers | `sqlx` |
+| `config` | Typed configuration loading from env/files | `config`, `dotenvy` |
+| `otel` | OpenTelemetry observability integration | `opentelemetry` |
 
-## Usage
-
-Add to your `Cargo.toml`:
-
-```toml
-[dependencies]
-rustapi-extras = { version = "0.1", features = ["jwt", "cors"] }
-```
-
-## Examples
+## Usage Examples
 
 ### JWT Authentication
 
 ```rust
-use rustapi_extras::jwt::{JwtLayer, AuthUser};
-use serde::Deserialize;
+use rustapi_rs::prelude::*;
+use rustapi_extras::jwt::{JwtAuth, AuthUser};
 
-#[derive(Deserialize)]
+#[derive(Serialize, Deserialize)]
 struct Claims {
     sub: String,
-    exp: u64,
+    exp: usize,
 }
 
-async fn protected(AuthUser(claims): AuthUser<Claims>) -> String {
-    format!("Hello, {}", claims.sub)
+#[get("/protected")]
+async fn protected_route(auth: AuthUser<Claims>) -> impl Responder {
+    format!("Hello user {}", auth.sub)
 }
 ```
 
-### CORS Configuration
+### CORS
 
 ```rust
 use rustapi_extras::cors::CorsLayer;
-use http::Method;
 
-let cors = CorsLayer::new()
-    .allow_origins(["https://example.com"])
-    .allow_methods([Method::GET, Method::POST])
-    .allow_credentials(true);
+RustApi::new()
+    .layer(CorsLayer::permissive())
+    // ...
 ```
-
-### Rate Limiting
-
-```rust
-use rustapi_extras::rate_limit::RateLimitLayer;
-use std::time::Duration;
-
-// Allow 100 requests per minute per IP
-let rate_limit = RateLimitLayer::new(100, Duration::from_secs(60));
-```
-
-## License
-
-Licensed under either of Apache License, Version 2.0 or MIT license at your option.

crates/rustapi-jobs/README.md

@@ -1,55 +1,37 @@
 # RustAPI Jobs
 
-Robust background job processing for the RustAPI framework.
+**Background job processing for RustAPI.**
 
-## Features
+Offload heavy tasks (emails, report generation, webhooks) to background workers.
 
-- **Multiple Backends**: Support for Redis and PostgreSQL backends.
-- **Reliable Processing**: At-least-once delivery guarantees.
-- **Retries**: Configurable retry policies with exponential backoff.
-- **Scheduled Tasks**: Cron-like scheduling for recurring jobs.
-- **Async Processing**: Fully async/await based on Tokio.
+## Key Features
 
-## Usage
+- **Backend Agnostic**: Drivers for **Redis** (recommended for speed) and **PostgreSQL** (for transactional reliability).
+- **At-Least-Once Delivery**: Jobs are not lost if a worker crashes.
+- **Retries**: Configurable exponential backoff policies.
+- **Scheduling**: Cron-like recurring tasks.
 
-Add to your `Cargo.toml`:
-
-```toml
-[dependencies]
-rustapi-jobs = { version = "0.1", features = ["redis"] }
-```
-
-### Defining a Job
+## Quick Start
 
 ```rust
 use rustapi_jobs::{Job, JobContext};
-use serde::{Serialize, Deserialize};
 
 #[derive(Serialize, Deserialize)]
-struct EmailJob {
+struct SendEmail {
     to: String,
-    subject: String,
-    body: String,
+    content: String,
 }
 
 #[async_trait]
-impl Job for EmailJob {
+impl Job for SendEmail {
     const NAME: &'static str = "send_email";
 
-    async fn run(&self, _ctx: JobContext) -> Result<(), Error> {
-        // Send email...
+    async fn run(&self, _ctx: JobContext) -> Result<()> {
+        // Send the email...
         Ok(())
     }
 }
-```
-
-### Enqueueing Jobs
 
-```rust
-let queue = RedisQueue::new("redis://localhost:6379").await?;
-queue.push(EmailJob {
-    to: "user@example.com".to_string(),
-    subject: "Welcome!".to_string(),
-    body: "Hello...".to_string(),
-}).await?;
+// Enqueue
+queue.push(SendEmail { ... }).await?;
 ```

crates/rustapi-macros/README.md

@@ -1,31 +1,38 @@
 # RustAPI Macros
 
-Internal procedural macros for the RustAPI framework.
+**Procedural macros that power the RustAPI developer experience.**
 
-> **Note**: This is an internal crate. You should depend on `rustapi-rs` instead.
+> ℹ️ **Note**: These macros are re-exported by `rustapi-rs`. You do not need to add this crate manually.
 
-## Features
+## Attribute Macros
 
-- `#[rustapi::main]`: Async runtime entry point.
-- `#[rustapi::get]`: GET handler definition.
-- `#[rustapi::post]`: POST handler definition.
-- `#[rustapi::put]`: PUT handler definition.
-- `#[rustapi::patch]`: PATCH handler definition.
-- `#[rustapi::delete]`: DELETE handler definition.
-- `#[rustapi::tag]`: OpenAPI tag metadata.
-- `#[rustapi::summary]`: OpenAPI summary metadata.
-- `#[rustapi::description]`: OpenAPI description metadata.
+### `#[rustapi::main]`
+Replaces `#[tokio::main]`. Sets up the runtime, tracing subscriber, and other framework essentials.
 
-## Usage
+### HTTP Method Handlers
+Registers a function as a route handler.
 
-These are automatically exported via the `rustapi` prefix when using `rustapi-rs`.
+- `#[rustapi::get("/users/{id}")]`
+- `#[rustapi::post("/users")]`
+- `#[rustapi::put("/users/{id}")]`
+- `#[rustapi::delete("/users/{id}")]`
+- `#[rustapi::patch("/users/{id}")]`
+- `#[rustapi::head("/health")]`
+- `#[rustapi::options("/cors")]`
 
-```rust
-use rustapi_rs::prelude::*;
+### OpenAPI Metadata
+Enrich your auto-generated documentation.
 
-#[rustapi::get("/hello")]
-#[rustapi::summary("Hello Endpoint")]
-async fn hello() -> &'static str {
-    "Hello World"
-}
-```
+- `#[rustapi::tag("Auth")]`: Groups endpoints.
+- `#[rustapi::summary("Logs in a user")]`: Brief summary.
+- `#[rustapi::description("Full markdown description...")]`: Detailed docs.
+
+## Derive Macros
+
+### `#[derive(Schema)]`
+Generates a JSON Schema for the struct, used by `rustapi-openapi`.
+*Wraps `utoipa::ToSchema` via `rustapi-openapi` integration.*
+
+### `#[derive(Validate)]`
+Generates validation logic.
+*Wraps `validator::Validate` via `rustapi-validate` integration.*