some edits

Author: mpfuster

advocacy_docs/supported-open-source/warehousepg/wem/get-started.mdx

@@ -12,13 +12,13 @@ Once WarehousePG Enterprise Manager (WEM) is installed and the backend services
 To start using the interface:
 1. Navigate to your WEM server URL (e.g., `http://your-server:8080`).
 2. Enter your credentials on the login screen.
-3. Click **Sign in**.
+3. Select **Sign in**.
 
-For security, sessions automatically expire after a period of inactivity; if a timeout occurs, the system will display a "Session Expired" message and redirect you to the login screen. You can also manually terminate your session at any time by clicking the Logout icon located in the sidebar footer.
+For security, sessions automatically expire after a period of inactivity; if a timeout occurs, the system will display a "Session Expired" message and redirect you to the login screen. You can also manually terminate your session at any time by selecting the **Logout** icon located in the sidebar footer.
 
 ## Configuring WEM settings post-installation
 
-Once you have installed WEM, you may need to fine-tune how WEM connects to your cluster or external services (like Prometheus and Alertmanager). There are two primary ways to manage these configurations:
+Once you have installed WEM, you might need to fine-tune how WEM connects to your cluster or external services (like Prometheus and Alertmanager). There are two primary ways to manage these configurations:
 
 1. Using the WEM settings tab
 
@@ -76,8 +76,8 @@ Five high-level indicators provide an immediate status check:
 * **Last sync**: The timestamp of the most recent data ingestion from the cluster.
 
 ### Status and resource summaries
-* **Segment status card**: Displays the overall operational state of the data plane. It tracks the count of healthy vs. unhealthy segments and provides a visual health bar. Click this card to access the **Cluster Overview** panel.
-* **Disk usage summary**: Provides a high-level view of storage utilization for both the coordinator and the segment nodes. Click this card to access the **Storage** panel.
+* **Segment status card**: Displays the overall operational state of the data plane. It tracks the count of healthy vs. unhealthy segments and provides a visual health bar. Select this card to access the **Cluster Overview** panel.
+* **Disk usage summary**: Provides a high-level view of storage utilization for both the coordinator and the segment nodes. Select this card to access the **Storage** panel.
 
 ### Real-time performance charts
 The dashboard includes three live charts that begin streaming data upon page load:

advocacy_docs/supported-open-source/warehousepg/wem/index.mdx

@@ -14,22 +14,44 @@ navigation:
 navRootedTo: /supported-open-source/warehousepg/
 ---
 
-WarehousePG Enterprise Manager (WEM) is the centralized management and monitoring interface for WarehousePG (WHPG) clusters. By integrating with Prometheus, Grafana, and Loki, WEM provides real-time visibility into host-level metrics, cluster health, and query performance.
+WarehousePG Enterprise Manager (WEM) is a comprehensive management, monitoring, and administration platform designed specifically for WarehousePG (WHPG) clusters. By integrating real-time telemetry, AI-assisted development, and interactive configuration tools into a single interface, WEM transforms complex distributed database operations into a streamlined, visual experience. Whether you are auditing cluster health, tuning SQL performance, or managing security, WEM provides the single pane of glass necessary to maintain a high-performance distributed environment.
 
-- [Release notes:](release_notes) Review the latest feature updates, bug fixes, and maintenance improvements for the current version of WEM.
+## Why WEM?
 
-- [Overview:](overview) Understand the core architecture of the platform, check software compatibility requirements, and review any known issues. 
+Managing a distributed database manually across multiple segment nodes and coordinators can be resource-intensive and error-prone. WEM solves these challenges by providing:
+- **Unified visibility:** Move beyond per-node SSH sessions. WEM aggregates host metrics, SQL statistics, and system logs into one centralized location.
 
-- [Installing:](installing) Follow the step-by-step requirements and procedures to deploy WEM and integrate it with your database nodes.
+- **Reduced operational fisk:** With features like the interactive HBA editor and automatic configuration backups, WEM provides a safety net for critical administrative changes.
 
-- [Getting started:](get-started) Learn how to access the console, navigate the interface structure, and understand how user roles affect your view.
+- **AI-driven optimization:** Leverage built-in AI intelligence to explain execution plans and suggest query optimizations, lowering the barrier to entry for managing complex distributed workloads.
 
-- [Observing system events:](monitoring) Maintaining operational awareness through log auditing, alert tracking, and health monitoring.
+- **Proactive resilience:** Integrated Canary checks and automated alerting ensure you are notified of potential bottlenecks or connectivity issues before they impact your users.
 
-- [Optimizing system performance:](performance) Tuning the workload and infrastructure to ensure consistent high-speed execution.
 
-- [Securing the environment:](security) Establishing safety protocols and managing access to sensitive data.
+### Key capabilities
 
-- [Troubleshooting:](troubleshooting) Identify and resolve common configuration errors, connectivity issues, and performance bottlenecks.
+WEM introduces a robust suite of tools for the modern database administrator and developer:
 
-- [Reference:](reference) Access technical specifications, command-line tool documentation, and the full role-permissions matrix.
+- **Observability & health**
+    - **Real-time & historical metrics:** Monitor live cluster pulse via the integrated Exporter or analyze long-term trends using Prometheus data.
+
+    - **Cluster overview:** A dedicated dashboard for the immediate health status of your coordinator and segment architecture.
+
+    - **Log management:** Searchable, aggregated log streams powered by Loki for rapid root-cause analysis.
+
+- **Intelligence & analysis**
+    - **Query monitor & editor:** A full-featured SQL editor featuring an AI Assistant to help write, optimize, and explain distributed queries.
+
+    - **Data skew analysis:** Deep-dive tools to analyze table distribution and storage efficiency across the cluster segments.
+
+- **Cluster administration**
+    - **Access management:** An interactive HBA editor for `pg_hba.conf` and a centralized user interface for user/password management.
+
+    - **Resource management:** Real-time tracking of CPU, Memory, and I/O consumption across the entire cluster.
+
+    - **System settings audit:** A searchable interface to verify and audit cluster-level GUC parameters.
+
+- **Data protection**
+    - **Backup & recovery:** Centralized monitoring of backup schedules, recovery points, and success rates.
+
+    - ***Canary checks:** Automated "heartbeat" tests that proactively verify cluster connectivity and query responsiveness.

advocacy_docs/supported-open-source/warehousepg/wem/installing/collector.mdx

@@ -49,14 +49,17 @@ Install the WarehousePG (WHPG) Collector on your WHPG cluster coordinator.
 
 ## Configuring the Collector 
 
-On the coordinator, edit the file `/var/lib/whpg-observability-collector/collector.conf` and configure the following parameters:
+Once the Collector packages are installed, edit the file `/var/lib/whpg-observability-collector/collector.conf` on the coordinator and configure the following parameters:
 
-- `WHPG_OBS_DSN`: Specify your WHPG cluster connection details. You can specify any database on your WHPG cluster. However, the user must hold the superuser role. For example:
+- `WHPG_OBS_DSN`: Specify your WHPG cluster connection details. For example:
 
     ```ini
     WHPG_OBS_DSN="host=whpg-coordinator-host port=5432 dbname=postgres user=gpadmin password=postgres sslmode=disable"
     ```
 
+!!! Note
+    You can specify any database on your WHPG cluster. However, the user must hold the superuser role.
+
 - `LOKI_ENDPOINT`: Point to your configured Loki endpoint for log files. For example:
 
     ```ini

advocacy_docs/supported-open-source/warehousepg/wem/installing/prerequisites.mdx

@@ -16,8 +16,8 @@ This guide assumes you have installed Prometheus and Loki.
 - [Loki](https://grafana.com/docs/loki/latest/setup/install/) 3.5 or later.
 - [Prometheus](https://prometheus.io/docs/prometheus/latest/installation/) 3.5.0 or later.
 - A database user that holds the superuser role and is able to connect to your WHPG cluster from the WEM host.
-- An active Anthropic account and a valid API key are required to enable the AI Assistant query writing and optimization.
-- An active installation of [Prometheus Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) version 0.28.1 or later is required to enable centralized alert handling and notifications within WEM.
+- Optional: An active Anthropic account and a valid API key are required to enable the AI Assistant for query writing and optimization.
+- Optional: An active installation of [Prometheus Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) version 0.28.1 or later is required to enable centralized alert handling and notifications within WEM.
 
 !!! Warning 
     WEM is not supported for installation on Red Hat Enterprise Linux 7 (RHEL 7). This limitation applies only to where the WEM application itself is deployed; WEM is fully capable of monitoring WHPG clusters that are running on RHEL 7 nodes.

advocacy_docs/supported-open-source/warehousepg/wem/installing/wem.mdx

@@ -2,6 +2,7 @@
 title: Installing WEM
 navTitle: Installing WEM
 description: Learn how to install the WarehousePG Enterprise Manager service.
+deepToC: true
 ---
 
 Install the WarehousePG Enterprise Manager (WEM) package on your designated host.
@@ -23,12 +24,12 @@ Install the WarehousePG Enterprise Manager (WEM) package on your designated host
     sudo dnf install -y whpg-enterprise-manager
     ```
 
-## Configuring WEM options
+## Configuring WEM
 
 Edit the configuration file `/etc/wem/wem.conf` and configure the following parameters:
 
 
-1. Set the values of `WHPG_HOST`, `WHPG_PORT`, `WHPG_DATABASE`, `WHPG_USER` , and `WHPG_PASSWORD` to point to your WHPG cluster. You can specify any database on your WHPG cluster. However, the user must hold the superuser role. For example:
+1. Set the values of `WHPG_HOST`, `WHPG_PORT`, `WHPG_DATABASE`, `WHPG_USER` , and `WHPG_PASSWORD` to point to your WHPG cluster. For example:
 
     ```ini
     WHPG_HOST=whpg-coordinator-host
@@ -37,15 +38,17 @@ Edit the configuration file `/etc/wem/wem.conf` and configure the following para
     WHPG_USER=gpadmin
     WHPG_PASSWORD=postgres
     ```
-    
+
+    !!! Note
+        You can specify any database on your WHPG cluster. However, the user must hold the superuser role.
+
 1. Set the values of the Prometheus and Loki endpoints. For example:
 
     ```ini
     PROMETHEUS_URL="http://prometheus.hostname:9090"
     LOKI_URL="http://loki.hostname:3100"
     ```
 
-
 1. To enable the AI Assistant for query writing and optimization, configure the `ANTHROPIC_API_KEY` parameter. Note that this requires an active Anthropic account. 
 
 1. To enable centralized alert handling and notifications with Alertmanager, configure the `ALERTMANAGER_URL` parameter to point to your Alertmanager endpoint.
@@ -55,41 +58,44 @@ Edit the configuration file `/etc/wem/wem.conf` and configure the following para
 
 ### Configuring WEM portal access
 
-Define how you access the WEM portal and establish the initial administrative credentials by configuring the following parameters in your environment file:
+Define how you access the WEM portal by configuring the following parameters in the WEM configuration file:
 
 ```ini
 WEM_HOST=wem-hostname
 WEM_USER=admin
 WEM_PORT=8080
 ```
 
-To configure the administrator password, choose one of the three following methods:
+To establish the initial administrative credentials, choose one of the three following methods:
+
+!!! Note
+    The methods outlined below are strictly for the **initial setup** of the administrator password. Once the WEM portal is initialized and you have logged in for the first time, all subsequent user management—including adding new users, modifying roles, and updating passwords—must be handled directly through the WEM user interface.
 
 1. **Option 1: Interactive setup** This is the simplest method for manual installations. You do not need to modify the configuration file manually; the system will prompt you for the password and handle the internal setup.
 
-    Run the setup command and follow the prompt to enter your desired password:
+    Run the `wem setup` command and follow the prompt to enter your desired password:
 
     ```bash
     wem setup --interactive
     ```
 
-1. **Option 2: Static configuration** Use this method to define your administrative password directly within the configuration file.
+1. **Option 2: Static configuration** Use this method to define your administrative password directly within the WEM configuration file.
 
     ```ini
-    WEM_ADMIN_PASSWORD=admin123
+    WEM_ADMIN_PASSWORD=your-secure-password
     ```
 
-1. **Option 3: File-based configuration** For enhanced security, manage the password via an external file. This is ideal for automated deployments or keeping secrets out of main config files.
+1. **Option 3: File-based configuration** For enhanced security, manage the password via an external file. This is ideal for automated deployments or keeping secrets out of configuration files.
 
-    1. Provide a  password by creating a file containing your password. Then, set the following parameter in your configuration:
+    1. Create a file containing your password:
 
         ```bash
        echo "your-secure-password" > /etc/wem/admin.pw
         ```
 
-        Point WEM to the file:
+        Set the following parameter in the WEM configuration file:
 
-        ```bash
+        ```ini
         WEM_ADMIN_PASSWORD_FILE=/etc/wem/admin.pw
         ```
 
@@ -112,13 +118,13 @@ sudo systemctl status wem
 
 After starting the service, use these diagnostic tools to ensure all WEM components are communicating correctly and the environment is healthy:
 
-- Connectivity Check: Run the verification tool to test the portal's link to the backend:
+- Run `wem setup` to test WEM configuration settings:
 
 ```bash
 wem setup --verify
 ```
 
-- System Health Audit: Perform a comprehensive "doctor" check to identify potential configuration errors, missing dependencies, or connectivity issues:
+- Perform a comprehensive "doctor" check to identify potential configuration errors, missing dependencies, or connectivity issues:
 
 ```bash
 wem doctor

advocacy_docs/supported-open-source/warehousepg/wem/monitoring/alerts.mdx

@@ -23,7 +23,7 @@ Alerts are automatically generated from several monitoring vectors:
 
 WEM displays severity levels to help you prioritize your operational workflow:
 - **Critical:** Indicates a severe failure or a total loss of service. These require immediate attention.
-- **Warning:** Highlights performance degradation or resource pressure. These should be investigated to prevent escalation.
+- **Warning:** Highlights performance degradation or resource pressure. These must be investigated to prevent escalation.
 - **Info:** Routine informational notices regarding system changes or successful task completions.
 
 
@@ -33,4 +33,4 @@ Use the specialized tabs to move through the stages of alert detection, suppress
 - **Suppress noise during maintenance:** Use the **Silences** tab to temporarily mute specific alerts. This is essential during scheduled maintenance or segment recovery windows to prevent alert fatigue and ensure that your notification channels remain focused on unexpected issues.
 - **Audit dispatch history:** Review the **Notifications** tab to see exactly when and where alerts were sent (e.g., Slack, Email, or PagerDuty). Use this to verify that the correct stakeholders were notified during an incident.
 - **Evaluate detection logic:** Browse the **Alert Rules** tab to inspect the active triggers defined in your Prometheus configuration. This view allows you to verify the technical conditions (thresholds, durations, and labels) that govern how WEM identifies system degradation.
-- **Perform retrospective analysis:** Use the **Alert History** tab to identify recurring patterns. By auditing resolved alerts, you can isolate intermittent hardware failures or recurring resource pressure that may require long-term capacity planning.
+- **Perform retrospective analysis:** Use the **Alert History** tab to identify recurring patterns. By auditing resolved alerts, you can isolate intermittent hardware failures or recurring resource pressure that might require long-term capacity planning.

advocacy_docs/supported-open-source/warehousepg/wem/monitoring/cluster-overview.mdx

@@ -1,7 +1,7 @@
 ---
 title: Verifying the cluster health
 navTitle: Verifying the cluster health
-description: Use the Cluster panel to monitor real-time WarehousePG cluster health, verify node availability, and track critical connectivity metrics to ensure high availability
+description: Use the Cluster Overview panel to monitor real-time WarehousePG cluster health, verify node availability, and track critical connectivity metrics to ensure high availability
 deepToC: true
 ---
 
@@ -35,5 +35,5 @@ WarehousePG relies on a distributed architecture where primary segments handle t
 
 Identify which specific databases are consuming cluster resources to prevent one tenant from impacting others:
 
-- **Compare database sizes:** Identify rapidly growing databases that may require storage expansion or data vacuuming.
+- **Compare database sizes:** Identify rapidly growing databases that might require storage expansion or data vacuuming.
 - **Track session distribution:** Monitor connection counts per database to identify unauthorized access or application connection leaks.