diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3a619afe..4b41df3e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -56,6 +56,7 @@ There are different types of replacements available:
 When using the `documented` type, you should generally follow these guidelines:
 
 - The mapping should have a `url` which points to an e18e documentation page (i.e. those in the [modules](https://github.com/e18e/module-replacements/tree/main/docs/modules) directory of the repo) which describes the replacement and how to migrate to it. Documentation here will be automatically synced weekly to the e18e website.
+- The documentation page should open with a one sentence reason under the title, explaining why the module is being replaced (e.g. it is deprecated, no longer maintained, or the same job can now be done natively or with fewer dependencies)
 - The replacement does not necessarily need a `url` itself
 - The replacement does not need a `description`
 
diff --git a/docs/modules/better-auth-cli.md b/docs/modules/better-auth-cli.md
index 77bd3e86..4554e641 100644
--- a/docs/modules/better-auth-cli.md
+++ b/docs/modules/better-auth-cli.md
@@ -4,6 +4,8 @@ description: Modern alternative to the @better-auth/cli package for the Better A
 
 # Replacements for `@better-auth/cli`
 
+Better Auth deprecated `@better-auth/cli` and now publishes its CLI as `auth`.
+
 ## `auth`
 
 The Better Auth CLI is now published under the `auth` name, and `@better-auth/cli` is deprecated, so switch the dependency over.
diff --git a/docs/templates/module.md b/docs/templates/module.md
index ed43e46e..58ec1737 100644
--- a/docs/templates/module.md
+++ b/docs/templates/module.md
@@ -4,6 +4,8 @@ description: Modern alternatives to the {moduleName} package for {description}
 
 # Replacements for {moduleName}
 
+{Why the module is being replaced, in one sentence}
+
 ## {Alternative package name}
 
 {Description of alternative package}