diff --git a/crates/rustapi-grpc/Cargo.toml b/crates/rustapi-grpc/Cargo.toml
index 4ca0c986..0e13e503 100644
--- a/crates/rustapi-grpc/Cargo.toml
+++ b/crates/rustapi-grpc/Cargo.toml
@@ -14,7 +14,7 @@ readme = "README.md"
 
 [dependencies]
 rustapi-core = { workspace = true }
-tokio = { workspace = true, features = ["macros"] }
+tokio = { workspace = true, features = ["rt", "sync", "macros"] }
 tonic = { workspace = true, features = ["transport"] }
 prost = { workspace = true }
 
diff --git a/crates/rustapi-grpc/README.md b/crates/rustapi-grpc/README.md
index 6dc90540..b515cd7f 100644
--- a/crates/rustapi-grpc/README.md
+++ b/crates/rustapi-grpc/README.md
@@ -9,7 +9,18 @@
 - `run_rustapi_and_grpc_with_shutdown(app, http_addr, signal, grpc_with_shutdown)`: shared shutdown signal for both servers.
 - Re-exports: `tonic`, `prost`.
 
-## Example
+## Usage
+
+### Via `rustapi-rs` (recommended)
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+rustapi-rs = { version = "0.1", features = ["grpc"] }
+```
+
+Then import via the `grpc` module:
 
 ```rust,ignore
 use rustapi_rs::grpc::{run_rustapi_and_grpc, tonic};
@@ -17,6 +28,36 @@ use rustapi_rs::prelude::*;
 
 #[rustapi_rs::get("/health")]
 async fn health() -> &'static str { "ok" }
+```
+
+### Direct `rustapi-grpc` usage
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+rustapi-grpc = "0.1"
+rustapi-core = "0.1"
+```
+
+Then import directly:
+
+```rust,ignore
+use rustapi_grpc::{run_rustapi_and_grpc, tonic};
+use rustapi_core::{get, RustApi};
+
+#[rustapi_core::get("/health")]
+async fn health() -> &'static str { "ok" }
+```
+
+## Example
+
+```rust,ignore
+use rustapi_grpc::{run_rustapi_and_grpc, tonic};
+use rustapi_core::{get, RustApi};
+
+#[rustapi_core::get("/health")]
+async fn health() -> &'static str { "ok" }
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
@@ -35,7 +76,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
 ## Shared shutdown (Ctrl+C)
 
 ```rust,ignore
-use rustapi_rs::grpc::{run_rustapi_and_grpc_with_shutdown, tonic};
+use rustapi_grpc::{run_rustapi_and_grpc_with_shutdown, tonic};
 
 let grpc_addr = "127.0.0.1:50051".parse()?;
 
diff --git a/crates/rustapi-grpc/src/lib.rs b/crates/rustapi-grpc/src/lib.rs
index 59585e13..88caa7ce 100644
--- a/crates/rustapi-grpc/src/lib.rs
+++ b/crates/rustapi-grpc/src/lib.rs
@@ -7,11 +7,13 @@
 //!
 //! ## Quick start
 //!
+//! When using `rustapi-grpc` directly:
+//!
 //! ```rust,ignore
-//! use rustapi_rs::grpc::{run_rustapi_and_grpc, tonic};
-//! use rustapi_rs::prelude::*;
+//! use rustapi_grpc::{run_rustapi_and_grpc, tonic};
+//! use rustapi_core::{get, RustApi};
 //!
-//! #[rustapi_rs::get("/health")]
+//! #[rustapi_core::get("/health")]
 //! async fn health() -> &'static str { "ok" }
 //!
 //! #[tokio::main]
@@ -27,6 +29,17 @@
 //!     Ok(())
 //! }
 //! ```
+//!
+//! Or use via `rustapi-rs` with the `grpc` feature:
+//!
+//! ```rust,ignore
+//! use rustapi_rs::grpc::{run_rustapi_and_grpc, tonic};
+//! use rustapi_rs::prelude::*;
+//!
+//! #[rustapi_rs::get("/health")]
+//! async fn health() -> &'static str { "ok" }
+//! // ... rest of example
+//! ```
 
 #![warn(missing_docs)]
 #![warn(rustdoc::missing_crate_level_docs)]
@@ -107,10 +120,10 @@ where
 /// # Example
 ///
 /// ```rust,ignore
-/// use rustapi_rs::grpc::{run_rustapi_and_grpc_with_shutdown, tonic};
-/// use rustapi_rs::prelude::*;
+/// use rustapi_grpc::{run_rustapi_and_grpc_with_shutdown, tonic};
+/// use rustapi_core::{get, RustApi};
 ///
-/// #[rustapi_rs::get("/health")]
+/// #[rustapi_core::get("/health")]
 /// async fn health() -> &'static str { "ok" }
 ///
 /// #[tokio::main]