diff --git a/pallets/messages/README.md b/pallets/messages/README.md
new file mode 100644
index 0000000000..46c490b694
--- /dev/null
+++ b/pallets/messages/README.md
@@ -0,0 +1,65 @@
+# Messages Pallet
+
+Stores block-indexed data for a Schema using `OnChain` or `IPFS` payload location.
+
+## Summary
+
+Messages stores metadata and message payload data for a set Schema.
+Message payloads are meant for streaming data, where when the message was sent is the focus.
+Discovery is via the `MessagesInBlock` on new blocks or requesting messages from a block.
+Retrieval is via RPC.
+
+### Metadata vs Payload
+
+Messages have both metadata and payloads.
+The payload should always match the data structure or the message is considered invalid.
+The metadata is the Block Number, Schema Id, and other data useful for discovering and organizing the payload information.
+
+### Payload Options
+
+- `IPFS`: Storage of the CID and length of the file on IPFS
+- `OnChain`: Storage of the entire payload data, usually for sub-256 byte payloads
+
+### Message Ordering
+
+Messages are ordered by block number, and within each block, they follow a specific order based on their transaction sequence within that block.
+This order is immutable.
+
+### Actions
+
+The Messages pallet provides for:
+
+- Adding messages for a given schema
+- Enabling the retrieval of messages for a given schema
+
+## Interactions
+
+### Extrinsics
+
+| Name/Description | Caller | Payment | Key Events | Runtime Added |
+| ---------------------------------------------------------------------------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `add_ipfs_message`
Add a message to a Schema with an `IPFS` payload location | Provider | Capacity or Tokens | [`MessagesInBlock`](https://frequency-chain.github.io/frequency/pallet_messages/pallet/enum.Event.html#variant.MessagesInBlock)\* | 1 |
+| `add_onchain_message`
Add a message to a Schema with an `ON_CHAIN` payload location | Provider | Capacity or Tokens | [`MessagesInBlock`](https://frequency-chain.github.io/frequency/pallet_messages/pallet/enum.Event.html#variant.MessagesInBlock)\* | 1 |
+
+\* The `MessagesInBlock` may not occur more than once per block and does _not_ indicate which schema received messages.
+
+See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_messages/pallet/struct.Pallet.html) for more details.
+
+### State Queries
+
+| Name | Description | Query | Runtime Added |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- |
+| Get Messages v2 | _Suggested_: Use RPC instead of this storage directly. Storage for the messages by Block number, Schema Id, and Message Index | `messagesV2` | 61 |
+| Get Messages v1 | Removed in Runtime 60 | `messages` | 1-60 |
+
+See the [Rust Docs](https://frequency-chain.github.io/frequency/pallet_messages/pallet/storage_types/index.html) for additional state queries and details.
+
+### RPCs
+
+Note: May be restricted based on node settings and configuration.
+
+| Name | Description | Call | Node Version |
+| ------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| Get Messages by Schema Id | Fetch paginated messages for a specific Schema Id in the given block range for a given Schema Id | [`getBySchemaId`](https://frequency-chain.github.io/frequency/pallet_messages_rpc/trait.MessagesApiServer.html#tymethod.get_messages_by_schema_id) | v1.0.0+ |
+
+See [Rust Docs](https://frequency-chain.github.io/frequency/pallet_messages_rpc/trait.MessagesApiServer.html) for more details.
diff --git a/pallets/messages/src/lib.rs b/pallets/messages/src/lib.rs
index 8a620a1952..b8ee6b68c0 100644
--- a/pallets/messages/src/lib.rs
+++ b/pallets/messages/src/lib.rs
@@ -1,37 +1,13 @@
-//! # Messages pallet
-//! A pallet for storing messages.
+//! Stores messages for `IPFS` and `OnChain` Schema payload locations
//!
+//! ## Quick Links
//! - [Configuration: `Config`](Config)
//! - [Extrinsics: `Call`](Call)
//! - [Runtime API: `MessagesRuntimeApi`](../pallet_messages_runtime_api/trait.MessagesRuntimeApi.html)
//! - [Custom RPC API: `MessagesApiServer`](../pallet_messages_rpc/trait.MessagesApiServer.html)
//! - [Event Enum: `Event`](Event)
//! - [Error Enum: `Error`](Error)
-//!
-//! ## Overview
-//!
-//! Messages allow for discovery of new content matching a given Schema.
-//! Each message MUST have either a provider or a validated source and provider.
-//! Message is the metadata of the source, order, schema for a payload or referenced payload.
-//!
-//! The Messages Pallet provides functions for:
-//!
-//! - Adding messages for a given schema.
-//! - Enabling retrieving messages for a given schema.
-//! - (FUTURE) Removing messages after expiration
-//!
-//! ## Terminology
-//!
-//! - **Message:** A message that matches a registered Schema (on-chain or off-chain).
-//! - **Payload:** The data in a `Message` that matches a `Schema`.
-//! - **MSA Id:** The 64 bit unsigned integer associated with an `Message Source Account`.
-//! - **MSA:** Message Source Account. A registered identifier with the [MSA pallet](../pallet_msa/index.html).
-//! - **Schema:** A registered data structure and the settings around it. (See [Schemas pallet](../pallet_schemas/index.html))
-//! - **Schema Id:** A U16 bit identifier for a schema stored on-chain.
-//!
-//! ## Implementations
-//! - None
-//!
+#![doc = include_str!("../README.md")]
// Substrate macros are tripping the clippy::expect_used lint.
#![allow(clippy::expect_used)]
// Ensure we're `no_std` when compiling for Wasm.