robusta-dev · aantn · Aug 6, 2025 · Jul 15, 2025 · Jul 15, 2025 · Jul 15, 2025
diff --git a/docs/configuration/alertmanager-integration/alert-custom-prometheus.rst b/docs/configuration/alertmanager-integration/alert-custom-prometheus.rst
@@ -23,37 +23,35 @@ Prerequisites
 * Kube-Prometheus-Stack, installed via Robusta or seperately.
 * Enable global rule selection for the Prometheus operator. Add the following config to your ``generated_values.yaml``. (By default Prometheus Operator picks up only certain new alerts, here we tell it to pick up all new alerts)
 
-  .. grid-item::
+  .. md-tab-set::
 
-      .. md-tab-set::
+      .. md-tab-item:: Robusta Prometheus
 
-          .. md-tab-item:: Robusta Prometheus
-
-            .. code-block:: yaml
-
-              kube-prometheus-stack:
-                prometheus:
-                  prometheusSpec:
-                    ruleNamespaceSelector: {} # (1)
-                    ruleSelector: {} # (2)
-                    ruleSelectorNilUsesHelmValues: false # (3)
-
-            .. code-annotations::
-              1. Add a namespace if you want Prometheus to identify rules created in specific namespaces. Leave ``{}`` to detect rules from any namespace.
-              2. Add a label if you want Prometheus to detect rules with a specific selector. Leave ``{}`` to detect rules with any label.
-              3. When set to `false`, Prometheus detects rules that are created directly, not just rules created using helm values file.
-
-          .. md-tab-item:: Other Prometheus
-
-            .. code-block:: yaml
+          .. code-block:: yaml
 
+            kube-prometheus-stack:
               prometheus:
                 prometheusSpec:
                   ruleNamespaceSelector: {} # (1)
                   ruleSelector: {} # (2)
                   ruleSelectorNilUsesHelmValues: false # (3)
 
-            .. code-annotations::
+          .. code-annotations::
+            1. Add a namespace if you want Prometheus to identify rules created in specific namespaces. Leave ``{}`` to detect rules from any namespace.
+            2. Add a label if you want Prometheus to detect rules with a specific selector. Leave ``{}`` to detect rules with any label.
+            3. When set to `false`, Prometheus detects rules that are created directly, not just rules created using helm values file.
+
+      .. md-tab-item:: Other Prometheus
+
+          .. code-block:: yaml
+
+            prometheus:
+              prometheusSpec:
+                ruleNamespaceSelector: {} # (1)
+                ruleSelector: {} # (2)
+                ruleSelectorNilUsesHelmValues: false # (3)
+
+          .. code-annotations::
               1. Add a namespace if you want Prometheus to identify rules created in specific namespaces. Leave ``{}`` to detect rules from any namespace.
               2. Add a label if you want Prometheus to detect rules with a specific selector. Leave ``{}`` to detect rules with any label.
               3. When set to `false`, Prometheus detects rules that are created directly, not just rules created using helm values file.

diff --git a/docs/configuration/alertmanager-integration/alert-manager.rst b/docs/configuration/alertmanager-integration/alert-manager.rst
@@ -7,7 +7,7 @@ Here's how to integrate an existing Prometheus with Robusta in the same cluster:
 * Point Robusta at Prometheus so it can query metrics and silence alerts
     * Robusta will attempt auto-detection, so this is not always necessary!
 
-If your Prometheus is in a different cluster, refer to :ref:`Centralized Prometheus`.
+If your Prometheus is in a different cluster, refer to :ref:`External Prometheus`.
 
 Send Alerts to Robusta
 ============================

diff --git a/docs/configuration/alertmanager-integration/embedded-prometheus.rst b/docs/configuration/alertmanager-integration/embedded-prometheus.rst
@@ -54,5 +54,5 @@ Apply the change by performing a :ref:`Helm Upgrade <Simple Upgrade>`.
 Troubleshooting
 ---------------------
 
-Encountering issues with your Prometheus? Follow this guide to resolve some :ref:`common errors <Common Errors>`.
+Encountering issues with your Prometheus? Follow this guide to resolve some :doc:`common errors </help>`.
 
diff --git a/docs/configuration/alertmanager-integration/google-managed-prometheus.rst b/docs/configuration/alertmanager-integration/google-managed-prometheus.rst
@@ -9,10 +9,10 @@ Prerequisites
 ****************
 An instance of Google Managed Prometheus with the following components configured:
 
-* Prometheus Frontend (`Instructions <https://cloud.google.com/stackdriver/docs/managed-prometheus/query#ui-prometheus>`_)
-* Node Exporter (`Instructions <https://cloud.google.com/stackdriver/docs/managed-prometheus/exporters/node_exporter>`_)
-* Scraping configuration for Kubelet and cAdvisor (`Instructions <https://cloud.google.com/stackdriver/docs/managed-prometheus/exporters/kubelet-cadvisor>`_)
-* Kube State Metrics (`Instructions <https://cloud.google.com/stackdriver/docs/managed-prometheus/exporters/kube_state_metrics>`_)
+* Prometheus Frontend (`Frontend Instructions <https://cloud.google.com/stackdriver/docs/managed-prometheus/query#ui-prometheus>`_)
+* Node Exporter (`Node Exporter Instructions <https://cloud.google.com/stackdriver/docs/managed-prometheus/exporters/node_exporter>`_)
+* Scraping configuration for Kubelet and cAdvisor (`Kubelet/cAdvisor Instructions <https://cloud.google.com/stackdriver/docs/managed-prometheus/exporters/kubelet-cadvisor>`_)
+* Kube State Metrics (`Kube State Metrics Instructions <https://cloud.google.com/stackdriver/docs/managed-prometheus/exporters/kube_state_metrics>`_)
 
 Send Alerts to Robusta
 ********************************************

diff --git a/docs/configuration/alertmanager-integration/index.rst b/docs/configuration/alertmanager-integration/index.rst
@@ -28,36 +28,36 @@ Connect Robusta to your Prometheus setup to get enriched alerts with logs, event
     :gutter: 3
 
 
-    .. grid-item-card:: Prometheus in same cluster
+    .. grid-item-card:: In-cluster Prometheus
         :class-card: sd-bg-light sd-bg-text-light
         :link: alert-manager
         :link-type: doc
 
-    .. grid-item-card:: Prometheus outside cluster
+    .. grid-item-card:: External Prometheus
         :class-card: sd-bg-light sd-bg-text-light
         :link: outofcluster-prometheus
         :link-type: doc
 
-    .. grid-item-card:: AWS Managed Prometheus
-        :class-card: sd-bg-light sd-bg-text-light
-        :link: eks-managed-prometheus
-        :link-type: doc
-
     .. grid-item-card:: Azure Managed Prometheus
         :class-card: sd-bg-light sd-bg-text-light
         :link: azure-managed-prometheus
         :link-type: doc
 
-    .. grid-item-card:: Google Managed Prometheus
+    .. grid-item-card:: AWS Managed Prometheus
         :class-card: sd-bg-light sd-bg-text-light
-        :link: google-managed-prometheus
+        :link: eks-managed-prometheus
         :link-type: doc
 
     .. grid-item-card:: Coralogix
         :class-card: sd-bg-light sd-bg-text-light
         :link: coralogix_managed_prometheus
         :link-type: doc
 
+    .. grid-item-card:: Google Managed Prometheus
+        :class-card: sd-bg-light sd-bg-text-light
+        :link: google-managed-prometheus
+        :link-type: doc
+
     .. grid-item-card:: VictoriaMetrics
         :class-card: sd-bg-light sd-bg-text-light
         :link: victoria-metrics

diff --git a/docs/configuration/alertmanager-integration/nagios.rst b/docs/configuration/alertmanager-integration/nagios.rst
@@ -74,7 +74,7 @@ Ensure Robusta is part of a contact group or explicitly included in your alert d
     }
 
 Step 4: Create the Bash Command Script
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Save this as `notify-robusta.sh`, ensure it's executable (`chmod +x notify-robusta.sh`), and Nagios can access it.
 

diff --git a/docs/configuration/alertmanager-integration/outofcluster-prometheus.rst b/docs/configuration/alertmanager-integration/outofcluster-prometheus.rst
@@ -1,4 +1,4 @@
-Centralized Prometheus
+External Prometheus
 **************************************
 
 Follow this guide to connect Robusta to a central Prometheus (e.g. Thanos/Mimir), running outside the cluster monitored by Robusta.
@@ -50,7 +50,7 @@ This integration lets your central Prometheus send alerts to Robusta, as if they
 Filtering Prometheus Queries by Cluster
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If the same centralized Prometheus is used for many clusters, you will want to add a cluster name to all queries.
+If the same external Prometheus is used for many clusters, you will want to add a cluster name to all queries.
 
 You can do so with the ``prometheus_url_query_string`` parameter, shown below:
 

diff --git a/docs/configuration/holmesgpt/custom_toolsets.rst b/docs/configuration/holmesgpt/custom_toolsets.rst
@@ -281,6 +281,7 @@ First `create a GitHub Personal Access Token with fine-grained permissions <http
                     type: "string"
                     description: "Name of the repository."
                     required: true
+
     To test, run: 
 
       .. code-block:: bash

diff --git a/docs/configuration/holmesgpt/index.rst b/docs/configuration/holmesgpt/index.rst
@@ -15,7 +15,7 @@ AI Analysis
 Why use HolmesGPT?
 ^^^^^^^^^^^^^^^^^^^
 
-Robusta can integrate with `Holmes GPT <https://github.com/robusta-dev/holmesgpt>`_ to analyze health issues on your cluster, and to run AI based root cause analysis for alerts.
+Robusta integrates with `HolmesGPT <https://github.com/robusta-dev/holmesgpt>`_ to provide AI-powered root cause analysis for your alerts. It automatically investigates issues by analyzing logs, metrics, and Kubernetes state.
 
 This requires a Robusta SaaS account, and for the Robusta UI sink to be enabled. (We have plans to support HolmesGPT in a pure OSS mode in the near future. Stay tuned!)
 

diff --git a/docs/configuration/holmesgpt/toolsets/opensearch_logs.rst b/docs/configuration/holmesgpt/toolsets/opensearch_logs.rst
@@ -1,7 +1,7 @@
 .. _toolset_opensearch_logs:
 
 OpenSearch logs
-==============
+===============
 
 By enabling this toolset, HolmesGPT will fetch pod logs from `OpenSearch <https://opensearch.org/>`_.
 

diff --git a/docs/configuration/holmesgpt/toolsets/rabbitmq.rst b/docs/configuration/holmesgpt/toolsets/rabbitmq.rst
@@ -1,4 +1,4 @@
-.. _toolset_prometheus:
+.. _toolset_rabbitmq:
 
 RabbitMQ
 ========

diff --git a/docs/configuration/sinks/PagerDuty.rst b/docs/configuration/sinks/PagerDuty.rst
@@ -55,7 +55,7 @@ Add the following code to your generated_values.yaml. This will send all alerts
 Save the file and run
 
 .. code-block:: bash
-   :name: cb-add-pagerduty-sink
+   :name: cb-add-pagerduty-sink-alerts
 
     helm upgrade robusta robusta/robusta --values=generated_values.yaml
 
@@ -91,7 +91,7 @@ Add the following code to your generated_values.yaml file. This will send all ch
 Save the file and run
 
 .. code-block:: bash
-   :name: cb-add-pagerduty-sink
+   :name: cb-add-pagerduty-sink-changes
 
     helm upgrade robusta robusta/robusta --values=generated_values.yaml
 

diff --git a/docs/configuration/sinks/RobustaUI.rst b/docs/configuration/sinks/RobustaUI.rst
@@ -32,7 +32,7 @@ Use the ``robusta`` CLI to generate a token:
 Add a new sink to your Helm values (``generated_values.yaml``), under ``sinksConfig``, with the token you generated:
 
 .. code-block:: bash
-  :name: cb-robusta-ui-sink-config
+  :name: cb-robusta-ui-sink-config-basic
 
   sinksConfig:
   - robusta_sink:
@@ -51,7 +51,7 @@ If you have many short-lived clusters, you can remove them from the UI automatic
 To do so, configure a shorter retention period by setting the ``ttl_hours`` in the Robusta UI sink settings:
 
 .. code-block:: bash
-  :name: cb-robusta-ui-sink-config
+  :name: cb-robusta-ui-sink-config-ttl
 
   sinksConfig:
   - robusta_sink:

diff --git a/docs/configuration/sinks/slack.rst b/docs/configuration/sinks/slack.rst
@@ -7,23 +7,27 @@ Robusta can proxy Prometheus alerts to Slack, adding powerful features like :ref
    :width: 600px
    :align: center
 
-Optionally, Robusta can monitor Kubernetes directly and send notifications on deployment changes or Kubernetes errors.
+Robusta can send both Prometheus alerts and direct Kubernetes notifications (pod crashes, deployment changes, etc.) to Slack.
 
 .. warning::
 
    If you are using the Slack sink and a Robusta version prior to 0.10.29, we **highly recommend** `upgrading <https://docs.robusta.dev/master/setup-robusta/upgrade.html>`_, as Slack has deprecated their older APIs. This older API will be sundown March 11, 2025. This will cause the slack sink to stop working for older versions of Robusta. 
 
    Follow `these steps <https://docs.robusta.dev/master/setup-robusta/upgrade.html#helm-upgrade>`_ to upgrade.
 
-Connecting Slack
+Quick Start
 ------------------------------------------------
 
-When installing Robusta, run ``robusta gen-config`` and follow the prompt to create a Slack API key. This will use our `official
+**Option 1: Automatic Setup (Recommended)**
+
+When installing Robusta, run ``robusta gen-config`` and follow the prompts. This automatically configures Slack using our `official
 Slack app <https://slack.com/apps/A0214S5PHB4-robusta?tab=more_info>`_.
 
-**Note: Robusta can only write messages and doesn't require read permissions.**
+Note: Robusta can only write messages and doesn't require read permissions.
+
+**Option 2: Manual Configuration**
 
-You can also generate a Slack API key by running ``robusta integrations slack`` and setting the following Helm values in your ``generated_values.yaml``:
+Generate a Slack API key by running ``robusta integrations slack``, then add to your ``generated_values.yaml``:
 
 .. code-block:: yaml
 

diff --git a/docs/how-it-works/alert-builtin-enrichment.rst b/docs/how-it-works/alert-builtin-enrichment.rst
@@ -25,14 +25,14 @@ Testing out Prometheus alerts
 1. Deploy a broken pod that will be stuck in pending state:
 
 .. code-block:: bash
-   :name: cb-apply-crashpod
+   :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:
 
 .. code-block:: bash
-   :name: cb-apply-crashpod
+   :name: cb-trigger-prometheus-alert
 
    robusta playbooks trigger prometheus_alert alert_name=KubePodCrashLooping namespace=default pod_name=example-pod
 
@@ -47,7 +47,7 @@ Testing out APIServer alerts
 Let's deploy a crashing pod:
 
 .. code-block:: bash
-   :name: cb-apply-crashpod
+   :name: cb-apply-crashpod-apiserver
 
    kubectl apply -f https://gist.githubusercontent.com/robusta-lab/283609047306dc1f05cf59806ade30b6/raw
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -52,7 +52,7 @@
    playbook-reference/index
    configuration/alertmanager-integration/alert-custom-prometheus
    Cost Savings - KRR <configuration/resource-recommender>
-   K8s Misconfigurations - Popeye <configuration/cluster-misconfigurations>
+   K8s Misconfigurations - Popeye <playbook-reference/actions/scans>
 
 .. toctree::
    :maxdepth: 4
@@ -91,7 +91,7 @@ Robusta transforms basic Prometheus alerts into actionable insights with full Ku
         * **Smart Grouping** - Reduce notification spam
         * **AI Investigation** - Kickstart alert investigation with AI
         * **Alert Enrichment** - Pod logs, events and more alongside alerts
-        * **Advanced Routing** - Based on team, namespace, and more
+
 
         Connect to your existing Prometheus or install our all-in-one bundle (based on kube-prometheus-stack). Need to go beyond Kubernetes? `Try Robusta Pro <https://home.robusta.dev>`_.
 

diff --git a/docs/notification-routing/disable-oomkill-notifications.rst b/docs/notification-routing/disable-oomkill-notifications.rst
@@ -8,4 +8,4 @@ Configure Robusta to not send OOMKill notifications by disabling the built-in OO
     disabledPlaybooks:
     - PodOOMKill
 
-Similarly you can to disable any built-in notification using the name of the playbook. Find all the built-in playbooks `here <https://github.com/robusta-dev/robusta/blob/master/helm/robusta/values.yaml#L113>`_ and `here <https://github.com/robusta-dev/robusta/blob/master/helm/robusta/values.yaml#L169>`_
+Similarly you can to disable any built-in notification using the name of the playbook. Find all the built-in playbooks `here (prometheus) <https://github.com/robusta-dev/robusta/blob/master/helm/robusta/values.yaml#L113>`_ and `here (kubernetes) <https://github.com/robusta-dev/robusta/blob/master/helm/robusta/values.yaml#L169>`_
diff --git a/docs/notification-routing/notification-grouping.rst b/docs/notification-routing/notification-grouping.rst
@@ -3,14 +3,13 @@
 Notification Grouping (Slack Only)
 =========================================================
 
-You can consolidate alerts into Slack threads to reduce the number of notifications.
-Each thread begins with a summary message that updates in real time as new alerts are received.
+Reduce alert noise by grouping related notifications into Slack threads. Instead of flooding channels with individual alerts, Robusta creates summary messages with threaded details.
 
 .. image:: /images/notification-grouping.png
    :width: 600px
    :align: center
 
-*Example: Alerts from a cluster are consolidated into a daily summary message, with individual alerts in the thread.*
+*Example: Multiple alerts consolidated into a daily summary with individual alerts in the thread.*
 
 Configuring Notification Grouping
 ----------------------------------

diff --git a/docs/playbook-reference/actions/event-enrichment.rst b/docs/playbook-reference/actions/event-enrichment.rst
@@ -1,7 +1,7 @@
 Event Enrichment
 ####################################
 
-The actions are used to gather extra data on errors, alerts, and other cluster events.
+Enrichment actions automatically gather context when alerts fire. They fetch logs, metrics, events, and diagnostic data to help you understand and resolve issues faster.
 
 Use them as building blocks in your own automations, or write :ref:`your own enrichment actions in Python <Developing New Actions>`.
 

diff --git a/docs/playbook-reference/kubernetes-examples/playbook-track-secrets.rst b/docs/playbook-reference/kubernetes-examples/playbook-track-secrets.rst
@@ -1,4 +1,5 @@
 .. _track-secrets-overview:
+
 Track Kubernetes Secret Changes
 ############################################
 

diff --git a/docs/setup-robusta/installation/_see_robusta_in_action-2.rst b/docs/setup-robusta/installation/_see_robusta_in_action-2.rst
@@ -1,6 +1,7 @@
 .. currently unused, I hope to clean this up and integrate it later
 
 :orphan:
+
 See Robusta in action
 ------------------------------