chore(docs): Updated docs for IMailer and MJML

* Updated docs for IMailer.

* More changes.

* Added deprecation context.

* ViewModel corrections.

* Updated link.

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

* Updated link.

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

* Updated steps for clarity.

* Update src/Core/MailTemplates/Mjml/README.md

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

* Grammar fix.

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

---------

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

src/Core/Platform/Mail/README.md

@@ -1,9 +1,14 @@
 # Mail Services
 ## `MailService`
 
-The `MailService` and its implementation in `HandlebarsMailService` has been deprecated in favor of the `Mailer` implementation.
+> [!WARNING]
+> The `MailService` and its implementation in `HandlebarsMailService` has been deprecated in favor of the `Mailer` implementation.
 
-New emails should be implemented using [MJML](../../MailTemplates/README.md) and the `Mailer`.
+The `MailService` class manages **all** emails, and has multiple responsibilities, including formatting, email building (instantiation of ViewModels from variables), and deciding if a mail request should be enqueued or sent directly.
+
+The resulting implementation cannot be owned by a single team (since all emails are in a single class), and as a result, anyone can edit any template without the appropriate team being informed.
+
+To alleviate these issues, all new emails should be implemented using [MJML](../../MailTemplates/README.md) and the `Mailer`.
 
 ## `Mailer`
 
@@ -16,20 +21,20 @@ The Mailer system consists of four main components:
 
 1. **IMailer** - Service interface for sending emails
 2. **BaseMail<TView>** - Abstract base class defining email metadata (recipients, subject, category)
-3. **BaseMailView** - Abstract base class for email template view models
+3. **BaseMailView** - Abstract base class for email template ViewModels
 4. **IMailRenderer** - Internal interface for rendering templates (implemented by `HandlebarMailRenderer`)
 
 ### How To Use
 
-1. Define a view model that inherits from `BaseMailView` with properties for template data
-2. Create Handlebars templates (`.html.hbs` and `.text.hbs`) as embedded resources, preferably using the MJML pipeline,
-   `/src/Core/MailTemplates/Mjml`.
-3. Define an email class that inherits from `BaseMail<TView>` with metadata like subject
-4. Use `IMailer.SendEmail()` to render and send the email
+1. Define a ViewModel that inherits from `BaseMailView` with properties for template data.
+2. Define an email class that inherits from `BaseMail<TView>` with metadata like `Subject`.
+3. Create Handlebars templates (`.html.hbs` and `.text.hbs`) as embedded resources, preferably using the `MJML` [pipeline](../../MailTemplates/Mjml/README.md#development-process), in
+   a directory in `/src/Core/MailTemplates/Mjml`.
+4. Use `IMailer.SendEmail()` to render and send the email.
 
 ### Creating a New Email
 
-#### Step 1: Define the Email & View Model
+#### Step 1: Define the ViewModel
 
 Create a class that inherits from `BaseMailView`:
 
@@ -43,17 +48,25 @@ public class WelcomeEmailView : BaseMailView
     public required string UserName { get; init; }
     public required string ActivationUrl { get; init; }
 }
+```
 
+#### Step 2: Define the email class
+
+Create a class that inherits from `BaseMail<TView>`:
+
+```csharp
 public class WelcomeEmail : BaseMail<WelcomeEmailView>
 {
     public override string Subject => "Welcome to Bitwarden";
 }
 ```
 
-#### Step 2: Create Handlebars Templates
+#### Step 3: Create Handlebars templates
 
-Create two template files as embedded resources next to your view model. **Important**: The file names must be located
-directly next to the `ViewClass` and match the name of the view.
+Create two template files as embedded resources next to your ViewModel.
+
+> [!IMPORTANT]  
+> The files must be located directly next to the `ViewClass` and match the name of the view.
 
 **WelcomeEmailView.html.hbs** (HTML version):
 
@@ -87,7 +100,7 @@ Activate your account: {{ ActivationUrl }}
 </ItemGroup>
 ```
 
-#### Step 3: Send the Email
+#### Step 4: Send the email
 
 Inject `IMailer` and send the email, this may be done in a service, command or some other application layer.
 
@@ -160,7 +173,7 @@ public class MarketingEmail : BaseMail<MarketingEmailView>
 
 ### Built-in View Properties
 
-All view models inherit from `BaseMailView`, which provides:
+All ViewModels inherit from `BaseMailView`, which provides:
 
 - **CurrentYear** - The current UTC year (useful for copyright notices)
 
@@ -176,7 +189,7 @@ Templates must follow this naming convention:
 - HTML template: `{ViewModelFullName}.html.hbs`
 - Text template: `{ViewModelFullName}.text.hbs`
 
-For example, if your view model is `Bit.Core.Auth.Models.Mail.VerifyEmailView`, the templates must be:
+For example, if your ViewModel is `Bit.Core.Auth.Models.Mail.VerifyEmailView`, the templates must be:
 
 - `Bit.Core.Auth.Models.Mail.VerifyEmailView.html.hbs`
 - `Bit.Core.Auth.Models.Mail.VerifyEmailView.text.hbs`
@@ -210,4 +223,4 @@ services.TryAddSingleton<IMailer, Mailer>();
 
 The mail services support loading the mail template from disk. This is intended to be used by self-hosted customers who want to modify their email appearance. These overrides are not intended to be used during local development, as any changes there would not be reflected in the templates used in a normal deployment configuration.
 
-Any customer using this override has worked with Bitwarden support on an approved implementation and has acknowledged that they are responsible for reacting to any changes made to the templates as a part of the Bitwarden development process. This includes, but is not limited to, changes in Handlebars property names, removal of properties from the `ViewModel` classes, and changes in template names.  **Bitwarden is not responsible for maintaining backward compatibility between releases in order to support any overridden emails.**
+Any customer using this override has worked with Bitwarden support on an approved implementation and has acknowledged that they are responsible for reacting to any changes made to the templates as a part of the Bitwarden development process. This includes, but is not limited to, changes in Handlebars property names, removal of properties from the ViewModel classes, and changes in template names.  **Bitwarden is not responsible for maintaining backward compatibility between releases in order to support any overridden emails.**