docs(deployment): refine for clarity and consistency

This commit improves the documentation across several files by enhancing clarity and consistency in language.

Author: fbeneventi

dashboards/legacy/README.md

@@ -6,7 +6,7 @@ deployment and have not migrated to the Kubernetes-based v0.5.0+ stack.
 
 ## What's here
 
-- `Examon Test - Random Sensor.json` — random-sensor verification dashboard
+- `Examon Test - Random Sensor.json`: random-sensor verification dashboard
   compatible with Grafana 7.3.10 and the AngularJS-based
   `grafana-kairosdb-datasource` plugin, both shipped by `docker-compose.yml`.
 
@@ -22,4 +22,4 @@ Use the dashboards in the parent `dashboards/` folder. They are compatible
 with Grafana 10+ / 11+ (the Kubernetes Helm chart deploys current Grafana)
 and the React-based `arpnetworking-kairosdb-datasource` plugin. The bundled
 "Examon Test - Random Sensor" dashboard is also auto-provisioned by the
-Helm chart via the Grafana dashboard sidecar — no manual import needed.
+Helm chart via the Grafana dashboard sidecar: no manual import needed.

deploy/helm/examon/dashboards/README.md

@@ -1,7 +1,7 @@
 # Chart-bundled Grafana dashboards
 
 > **Most users should NOT add files here.** To ship a custom dashboard,
-> create a `ConfigMap` labeled `grafana_dashboard=1` in any namespace —
+> create a `ConfigMap` labeled `grafana_dashboard=1` in any namespace;
 > the Grafana sidecar will load it automatically without a `helm
 > upgrade`. See
 > [Grafana Dashboards](../../../../docs/Deployment/kubernetes.md#grafana-dashboards)

docs/Deployment/change-propagation.md

@@ -72,7 +72,7 @@ umbrella file, which wins over the subchart default.
    all environments unless they override it.
 3. If **environment-specific**: edit the relevant `values-<env>.yaml`.
 4. **Check all three environment files** to verify they are consistent.
-   Values files only override fields they explicitly set — if a file doesn't
+   Values files only override fields they explicitly set; if a file doesn't
    mention a field, it inherits from `values.yaml`.
 
 **Checklist for value changes:**
@@ -110,7 +110,7 @@ deploy/helm/examon/subcharts/<service>/templates/
     _helpers.tpl        # Template helper functions
 ```
 
-**Critical step — subchart packaging:**
+**Critical step: subchart packaging.**
 
 Helm does **not** read templates directly from `subcharts/`. Instead, it uses
 pre-packaged `.tgz` archives inside `deploy/helm/examon/charts/`. You must
@@ -191,7 +191,7 @@ the same tag (e.g. `latest`), nodes with `imagePullPolicy: IfNotPresent`
 For production images on GHCR, use semantic versioning (e.g. `1.3.0`,
 `1.3.1`). For development, use descriptive suffixes (e.g. `1.3.0-fix3`).
 
-**What to propagate — image tag changes:**
+**What to propagate when changing image tags:**
 
 | File | Update |
 |------|--------|
@@ -223,23 +223,23 @@ For production images on GHCR, use semantic versioning (e.g. `1.3.0`,
 
 This is the most complex scenario because it touches every layer:
 
-**Step 1 — Subchart template:**
+**Step 1: Subchart template.**
 Edit `subcharts/examon-server/templates/configmap.yaml` to render the new
 field:
 
 ```yaml
 CASSANDRA_TIMEOUT = {{ .Values.config.cassandraTimeout }}
 ```
 
-**Step 2 — Subchart default:**
+**Step 2: Subchart default.**
 Edit `subcharts/examon-server/values.yaml`:
 
 ```yaml
 config:
   cassandraTimeout: 30
 ```
 
-**Step 3 — Umbrella default:**
+**Step 3: Umbrella default.**
 Edit `values.yaml`:
 
 ```yaml
@@ -248,7 +248,7 @@ examon-server:
     cassandraTimeout: 30
 ```
 
-**Step 4 — Environment overrides (if needed):**
+**Step 4: Environment overrides (if needed).**
 Edit `values-production.yaml`:
 
 ```yaml
@@ -257,21 +257,21 @@ examon-server:
     cassandraTimeout: 120
 ```
 
-**Step 5 — Rebuild and deploy:**
+**Step 5: Rebuild and deploy.**
 
 ```bash
 cd deploy/helm/examon && helm dependency update && cd ../../..
 helm upgrade examon ./deploy/helm/examon \
   -f ./deploy/helm/examon/values-<env>.yaml -n examon
 ```
 
-**Step 6 — Verify:**
+**Step 6: Verify.**
 
 ```bash
 helm get manifest examon -n examon | grep CASSANDRA_TIMEOUT
 ```
 
-**Step 7 — Documentation:**
+**Step 7: Documentation.**
 Update `docs/Deployment/configuration.md` with the new parameter.
 
 ---
@@ -280,14 +280,14 @@ Update `docs/Deployment/configuration.md` with the new parameter.
 
 | What you changed | Rebuild image | `helm dependency update` | `helm upgrade` | Update values files |
 |------------------|:---:|:---:|:---:|:---:|
-| Value in `values-<env>.yaml` only | | | Yes | — |
+| Value in `values-<env>.yaml` only | | | Yes | N/A |
 | Value in umbrella `values.yaml` | | | Yes | Check env files |
 | Subchart template (`subcharts/*/templates/`) | | **Yes** | Yes | If new field |
 | Subchart `values.yaml` (defaults) | | **Yes** | Yes | Check umbrella + env files |
 | Dockerfile or container scripts | **Yes** | | Yes | Update image tags |
-| K3d/K8s cluster config (`deploy/k3d/`) | — | — | Recreate cluster | — |
-| External chart version (`Chart.yaml`) | | **Yes** | Yes | — |
-| K8ssandra operator version | | | `helm upgrade k8ssandra-operator` | — |
+| K3d/K8s cluster config (`deploy/k3d/`) | N/A | N/A | Recreate cluster | N/A |
+| External chart version (`Chart.yaml`) | | **Yes** | Yes | N/A |
+| K8ssandra operator version | | | `helm upgrade k8ssandra-operator` | N/A |
 
 !!! note "K8ssandra operator is a separate Helm release"
     The K8ssandra operator is **not** listed in `Chart.yaml`. It is installed
@@ -389,7 +389,7 @@ The only secret that still requires `--set` is the **Grafana admin password**:
     `deploy/helm/examon/values-*.secret.yaml` and will never be committed:
 
     ```yaml
-    # values-local.secret.yaml — DO NOT COMMIT
+    # values-local.secret.yaml: DO NOT COMMIT
     grafana:
       adminPassword: "my-grafana-password"
     ```

docs/Deployment/docker-compose.md

@@ -49,7 +49,7 @@ This Docker Compose stack runs Grafana 7.3.10 with the legacy AngularJS
 snapshot from `dashboards/legacy/Examon Test - Random Sensor.json`.
 
 The dashboards directly under `dashboards/` target the Kubernetes
-(v0.5.0+) stack instead — they use the React-based
+(v0.5.0+) stack instead: they use the React-based
 `arpnetworking-kairosdb-datasource` plugin and are not compatible with
 Grafana 7.x.
 

docs/Deployment/kubernetes-local.md

@@ -64,7 +64,7 @@ echo "127.0.0.1 examon-registry" | sudo tee -a /etc/hosts
 
 !!! note
     The automated setup script (`k8s-local-setup.sh`) performs this step
-    automatically. You only need to do this once per machine — the entry
+    automatically. You only need to do this once per machine; the entry
     persists across cluster recreations.
 
 ### Step 3: Build and Push Images
@@ -134,7 +134,7 @@ initial deployment, a superuser secret is automatically generated.
 
 Both **KairosDB** and **examon-server** read these credentials automatically
 from the K8ssandra secret via `secretKeyRef` environment variables. No
-manual `--set` flags or second `helm upgrade` is needed — the pods pick up
+manual `--set` flags or second `helm upgrade` is needed: the pods pick up
 credentials on startup once the secret exists.
 
 `examon-server` uses env var overrides (`CASSANDRA_USER`, `CASSANDRA_PASSWORD`)
@@ -151,7 +151,7 @@ examon-server:
 !!! note "Bootstrap restarts"
     On a fresh install, `examon-server` and `kairosdb` may restart a few
     times while Cassandra initializes and creates the superuser secret.
-    This is expected — Kubernetes restarts them automatically and they
+    This is expected: Kubernetes restarts them automatically and they
     connect once Cassandra is ready.
 
 ### Step 8: Verify
@@ -226,7 +226,7 @@ kubectl logs -l app.kubernetes.io/name=grafana -c grafana-sc-dashboard -n examon
 ## Accessing Services
 
 All user-facing services are exposed directly on the host via the K3d load
-balancer and `NodePort` services — no `kubectl port-forward` or Kubernetes
+balancer and `NodePort` services. No `kubectl port-forward` or Kubernetes
 knowledge required. External clients (e.g. `examon-client` on user laptops,
 admins accessing Grafana) connect to these addresses just like with Docker
 Compose:
@@ -279,8 +279,8 @@ examon-server:
 
 KairosDB 1.3.0 loads two configuration files:
 
-1. **`kairosdb.properties`** — legacy Java properties format
-2. **`kairosdb.conf`** — HOCON format (takes precedence)
+1. **`kairosdb.properties`**: legacy Java properties format
+2. **`kairosdb.conf`**: HOCON format (takes precedence)
 
 The `config-kairos.sh` entrypoint script patches both files at startup using
 environment variables (`CASSANDRA_HOST_LIST`, `CASSANDRA_USER`,
@@ -295,9 +295,9 @@ built on the `ExamonApp` framework from the `examon-common` library. They
 expect their configuration in `.conf` files (INI format) mounted in the
 working directory:
 
-- `random_pub.conf` — mounted from ConfigMap via Helm
-- `mqtt2kairosdb.conf` — mounted from ConfigMap via Helm
-- `server.conf` — mounted from ConfigMap via Helm
+- `random_pub.conf`: mounted from ConfigMap via Helm
+- `mqtt2kairosdb.conf`: mounted from ConfigMap via Helm
+- `server.conf`: mounted from ConfigMap via Helm
 
 These are generated from the Helm `values.yaml` settings by each subchart's
 `configmap.yaml` template.
@@ -322,7 +322,7 @@ to pull the image based on the Kubernetes `imagePullPolicy`:
 
 `values-local.yaml` sets `pullPolicy: Always` for all custom ExaMon images.
 This means the standard build-push-restart cycle works reliably with the
-`:latest` tag — no stale cache surprises.
+`:latest` tag, with no stale cache surprises.
 
 ### Scenario 1: Application Code Change
 
@@ -457,7 +457,7 @@ well with K3d and Helm charts:
   pipeline, supports file syncing, and integrates with CI/CD.
 
 Both tools work with ExaMon's Helm chart structure out of the box. They
-are optional power-ups — the manual workflow above is sufficient for most
+are optional power-ups; the manual workflow above is sufficient for most
 development tasks.
 
 ### Teardown

docs/Deployment/kubernetes-production.md

@@ -1,6 +1,6 @@
 # Production Deployment
 
-Production targets a real Kubernetes cluster — on-premises (OpenStack,
+Production targets a real Kubernetes cluster: on-premises (OpenStack,
 RKE2, kubeadm) or cloud-managed (EKS, GKE, AKS).
 
 ## Service Exposure Architecture
@@ -265,7 +265,7 @@ helm install examon ./deploy/helm/examon \
   -n examon --wait --timeout 20m
 ```
 
-Cassandra credentials are injected automatically — both KairosDB and
+Cassandra credentials are injected automatically. Both KairosDB and
 examon-server read them from the K8ssandra-generated secret
 (`examon-cassandra-superuser`) via `secretKeyRef` environment variables.
 No second `helm upgrade` is needed.
@@ -316,7 +316,7 @@ Create DNS records pointing to the services:
 ### Configure Grafana Data Source
 
 The KairosDB data source is **fully auto-provisioned** by the chart on
-every deploy — no manual setup is required. The umbrella chart:
+every deploy; no manual setup is required. The umbrella chart:
 
 1. Installs the React-based [ArpNetworking
    KairosDB data source plugin](https://github.com/ArpNetworking/kairosdb-datasource)
@@ -354,8 +354,8 @@ both to monitor ExaMon itself and to scrape Cassandra.
 **Cassandra metrics (K8ssandra-native):** the umbrella chart exposes
 `cassandra.telemetry.prometheus.*`, which is wired straight into the
 K8ssandra `CassandraDatacenter` CR. When enabled, K8ssandra creates a
-`ServiceMonitor` for the Cassandra metric endpoint — no extra manifest to
-maintain. Requires the `ServiceMonitor` CRD (shipped by
+`ServiceMonitor` for the Cassandra metric endpoint, with no extra manifest
+to maintain. Requires the `ServiceMonitor` CRD (shipped by
 `kube-prometheus-stack`):
 
 ```yaml
@@ -397,7 +397,7 @@ kubectl scale deployment examon-kairosdb --replicas=3 -n examon
 kubectl scale deployment examon-examon-server --replicas=3 -n examon
 ```
 
-Cassandra scaling is managed via the K8ssandraCluster CR — update the
+Cassandra scaling is managed via the K8ssandraCluster CR: update the
 datacenter `size` in `values-production.yaml` and run `helm upgrade`.
 
 ## Platform-Specific Notes

docs/Deployment/kubernetes-staging.md

@@ -155,7 +155,7 @@ kubectl exec -it examon-cassandra-dc1-default-sts-0 -c cassandra -n examon \
 
 All user-facing services are exposed directly on the host via the K3d load
 balancer and `NodePort` services. External clients connect to the VM's
-IP/hostname — no Kubernetes knowledge required:
+IP/hostname; no Kubernetes knowledge required:
 
 | Service | Address | Protocol | Users |
 |---------|---------|----------|-------|