robusta-dev · aantn · Nov 6, 2025 · Nov 6, 2025 · Nov 6, 2025 · Nov 6, 2025
diff --git a/docs/conf.py b/docs/conf.py
@@ -108,7 +108,8 @@
     "configuration/configuring-sinks.html": "/master/notification-routing/configuring-sinks.html",
     "how-it-works/privacy-and-security.html": "/master/setup-robusta/privacy-and-security.html",
     "how-it-works/index.html": "/master/playbook-reference/what-are-playbooks.html",
-    "playbook-reference/examples.html": "/master/playbook-reference/prometheus-examples/index.html",
+    "playbook-reference/examples.html": "/master/playbook-reference/builtin-alert-enrichment.html",
+    "playbook-reference/prometheus-examples/index.html": "/master/playbook-reference/builtin-alert-enrichment.html",
     "tutorials/playbook-track-changes.html": "/master/playbook-reference/kubernetes-examples/kubernetes-change-notifications.html",
     "tutorials/playbook-job-failure.html": "/master/playbook-reference/kubernetes-examples/kubernetes-change-notifications.html",
     "tutorials/playbook-failed-liveness.html": "/master/playbook-reference/kubernetes-examples/kubernetes-change-notifications.html",

diff --git a/docs/configuration/alertmanager-integration/grafana-self-hosted.rst b/docs/configuration/alertmanager-integration/grafana-self-hosted.rst
@@ -93,7 +93,7 @@ To enable Robusta to correlate your Grafana alerts with the specific Kubernetes
     This is only required for Kubernetes alerts. You can send any alert to the Robusta timeline, including non-Kubernetes alerts.
 
 Option 2: Inline Alert Enrichment and Routing
-===========================================
+==============================================
 
 Use Robusta to enrich alerts inline with extra context and route them to :doc:`other systems </configuration/sinks/index>` (Slack, Microsoft Teams, etc.). Learn more about :doc:`alert routing </notification-routing/index>`.
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -144,8 +144,7 @@
    :hidden:
 
    playbook-reference/index
-   Builtin Alert Enrichment <playbook-reference/builtin-alert-enrichment>
-   Custom Alert Enrichment <playbook-reference/prometheus-examples/index>
+   Enrich Alerts <playbook-reference/builtin-alert-enrichment>
    Kubernetes Change Notifications <playbook-reference/kubernetes-examples/kubernetes-change-notifications>
    Cost Savings - KRR <configuration/resource-recommender>
 

diff --git a/docs/playbook-reference/builtin-alert-enrichment.rst b/docs/playbook-reference/builtin-alert-enrichment.rst
@@ -1,26 +1,60 @@
 .. _builtin-alert-enrichment:
 
-Builtin Alert Enrichment
+Enrich Alerts
 ########################################
 
-Robusta takes Prometheus to the next level by correlating alerts with other observability data.
+Ever feel overwhelmed by alerts that lack context? Robusta enriches alerts automatically and lets you create custom enrichment rules.
+
+.. note::
 
-Testing out Prometheus alerts
+   **Looking for automatic AI enrichment?** Check out :doc:`HolmesGPT </configuration/holmesgpt/main-features>` for zero-configuration AI-powered alert enrichment that automatically investigates alerts and provides root cause analysis.
+
+Builtin Alert Enrichment
 *********************************
-1. Deploy a broken pod that will be stuck in pending state:
+
+Robusta automatically enriches Prometheus alerts with relevant Kubernetes context:
+
+* **Pod events** - Recent events related to the affected pod
+* **Pod logs** - Relevant log excerpts from crashing or failing containers
+* **Resource metrics** - CPU, memory, and other resource usage data
+* **Related Kubernetes objects** - Deployments, ReplicaSets, ConfigMaps, etc.
+
+This happens automatically for common Prometheus alerts without any configuration. To extend it to your own Prometheus alerts you can define custom playbooks.
+
+Testing Alert Enrichment
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Deploy a broken pod:
 
 .. code-block:: bash
    :name: cb-apply-pendingpod
 
    kubectl apply -f https://raw.githubusercontent.com/robusta-dev/kubernetes-demos/main/pending_pods/pending_pod_resources.yaml
 
-2. Trigger a Prometheus alert immediately, skipping the normal delays:
+2. Trigger a Prometheus alert immediately:
 
 .. code-block:: bash
    :name: cb-trigger-prometheus-alert
 
    robusta playbooks trigger prometheus_alert alert_name=KubePodCrashLooping namespace=default pod_name=example-pod
 
-.. admonition:: Example Slack Message
+.. admonition:: Example Enriched Alert
 
     .. image:: /images/simulatedprometheusalert.png
+
+Custom Alert Enrichment
+*********************************
+
+Create custom enrichment rules to:
+
+* Reduce MTTR by automatically gathering system state and logs when alerts fire
+* Make faster decisions on which team needs to investigate
+* Link alerts to runbooks and documentation for better knowledge sharing
+
+Get started with these examples:
+
+.. toctree::
+   :maxdepth: 1
+
+   prometheus-examples/bash-alert-enrichment
+   prometheus-examples/link-alert-enrichment
diff --git a/docs/playbook-reference/defining-playbooks/builtin-playbooks.rst b/docs/playbook-reference/defining-playbooks/builtin-playbooks.rst
@@ -25,7 +25,7 @@ The following default playbook handles all Prometheus alerts that Robusta receiv
 
 There are additional enrichments for specific alerts. For example:
 
-To define additional playbooks for your own alerts, refer to the :doc:`Custom Alert Enrichment </playbook-reference/prometheus-examples/index>` guide.
+To define additional playbooks for your own alerts, refer to the :doc:`Enrich Alerts </playbook-reference/builtin-alert-enrichment>` guide.
 
 Default Prometheus Silencing
 --------------------------------

diff --git a/docs/playbook-reference/defining-playbooks/creating-notifications.rst b/docs/playbook-reference/defining-playbooks/creating-notifications.rst
@@ -1,4 +1,4 @@
-Creating Notifications
+Playbook Notifications
 ######################
 
 Playbooks can generate notifications to *let a human know* about something in your cluster.

diff --git a/docs/playbook-reference/defining-playbooks/playbook-advanced.rst b/docs/playbook-reference/defining-playbooks/playbook-advanced.rst
@@ -3,7 +3,7 @@
 Advanced Playbook Techniques
 ################################
 
-This guide assumes you already know :ref:`playbook basics <Playbook Basics>` and how to :ref:`create notifications <Creating Notifications>`. It explains
+This guide assumes you already know :ref:`playbook basics <Playbook Basics>` and how to :ref:`create notifications <Playbook Notifications>`. It explains
 implementation details and common techniques.
 
 Using Filters to Restrict Triggers

diff --git a/docs/playbook-reference/defining-playbooks/playbook-basics.rst b/docs/playbook-reference/defining-playbooks/playbook-basics.rst
@@ -186,7 +186,7 @@ Understanding Notifications
 
 In Robusta, notifications are called Findings, as they represent something the playbook discovered.
 
-In the above example, a Finding was generated by the ``create_finding`` action. Refer to :ref:`Creating Notifications`
+In the above example, a Finding was generated by the ``create_finding`` action. Refer to :ref:`Playbook Notifications`
 for more details.
 
 Matching Actions to Triggers

diff --git a/docs/playbook-reference/index.rst b/docs/playbook-reference/index.rst
@@ -6,7 +6,7 @@
 
    overview
    Playbook Basics <defining-playbooks/playbook-basics>
-   Creating Notifications <defining-playbooks/creating-notifications>
+   Playbook Notifications <defining-playbooks/creating-notifications>
    Advanced Playbook Techniques <defining-playbooks/playbook-advanced>
    Matching Actions to Triggers <defining-playbooks/trigger-action-binding>
    Loading External Actions <defining-playbooks/external-playbook-repositories>

diff --git a/docs/playbook-reference/overview.rst b/docs/playbook-reference/overview.rst
@@ -6,6 +6,11 @@ Playbooks are deterministic rules for responding to alerts and unhealthy conditi
 
 Playbooks are recommended for advanced use cases. Most users should start with :doc:`AI Analysis </configuration/holmesgpt/main-features>` of alerts first, which requires far less configuration.
 
+Quick Start
+---------------------
+
+New to playbooks? Start with the :doc:`Playbook Basics </playbook-reference/defining-playbooks/playbook-basics>` guide to learn how to create your first playbook.
+
 How Playbooks Work
 ---------------------
 

diff --git a/docs/playbook-reference/prometheus-examples/index.rst b/docs/playbook-reference/prometheus-examples/index.rst
diff --git a/docs/playbook-reference/prometheus-examples/link-alert-enrichment.rst b/docs/playbook-reference/prometheus-examples/link-alert-enrichment.rst
@@ -8,7 +8,7 @@ This guide demonstrates how to link Prometheus alerts with external links to you
 Implementation
 -----------------
 
-In this example, we add links to the alert ``KubeContainerCPURequestAlert`` that we created in a :ref:`previous tutorial <Create Custom Prometheus Alerts>`.
+In this example, we'll add links to a Prometheus alert. We're using ``KubeContainerCPURequestAlert`` as an example, but you can apply this to any alert.
 
 Below there are three alternatives ways to enrich the alert with links. Apply the YAML to the ``customPlaybooks`` Helm value and :ref:`update Robusta <Simple Upgrade>`.
 

diff --git a/docs/setup-robusta/installation-faq.rst b/docs/setup-robusta/installation-faq.rst
@@ -64,6 +64,6 @@ It's being planned, speak to us on Slack.
 
 Does Robusta replace monitoring tools?
 ============================================================
-Robusta's :ref:`all-in-one package <Install Robusta + Prometheus>` is a complete monitoring and observability solution.
+Robusta's :ref:`all-in-one package <install-all-in-one>` is a complete monitoring and observability solution.
 
 Alternatively, you can keep your existing tools and add-on robusta.