From a22286ede5a7e6e52898724e58a38dda67446809 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kamil=20Bregu=C5=82a?= <mik-laj@users.noreply.github.com>
Date: Fri, 26 Dec 2025 15:45:24 +0100
Subject: [PATCH 1/2] Enhance gios integration documentation

Added use cases, supported functionality, examples, and troubleshooting section for the gios integration.
---
 source/_integrations/gios.markdown | 69 ++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/source/_integrations/gios.markdown b/source/_integrations/gios.markdown
index f840272ca0a4..2ba053812efb 100644
--- a/source/_integrations/gios.markdown
+++ b/source/_integrations/gios.markdown
@@ -17,6 +17,12 @@ ha_integration_type: service
 
 The `gios` integration uses the [GIOŚ](http://powietrze.gios.gov.pl/pjp/current) web service as a source for air quality data for your location.
 
+## Use cases
+
+- Monitor outdoor air quality.
+- Warn to close windows when CO2 levels are too high.
+- Control ventilation systems based on air quality.
+
 {% include integrations/config_flow.md %}
 
 {% configuration_basic %}
@@ -24,6 +30,69 @@ Measuring station:
   description: "Select a measuring station from the list."
 {% endconfiguration_basic %}
 
+## Supported functionality
+
+Below is a complete overview of the entities this integration provides.
+
+### Available sensors
+
+The integration provides the following sensors:
+
+- Air quality index
+- Benzene
+- Carbon monoxide
+- Nitrogen dioxide
+- Nitrogen dioxide index
+- Nitrogen monoxide
+- Nitrogen oxides
+- Ozone
+- Ozone index
+- PM10
+- PM10 index
+- PM2.5
+- PM2.5 index
+- Sulphur dioxide
+- Sulphur dioxide index
+
+The available sensors and data refresh rate depend on the selected measurement station.
+
+## Data updates
+
+By default, the integration {% term polling polls %} data from the API every 30 minutes.
+
+## Examples
+
+The following examples show how to use the integration in Home Assistant automations. These examples are just a starting point, and you can use them as inspiration to create your own automations.
+
+### Notify when the PM10 level is too high
+
+The following example sends a notification to your mobile device when the PM10 level exceeds 100 ppm.
+
+{% raw %}
+
+```yaml
+automation:
+  - alias: "Notify when PM10 level is too high"
+    triggers:
+      - trigger: numeric_state
+        entity_id: sensor.czerniawa_pm10
+        above: 100
+
+    actions:
+      - action: notify.mobile_app_your_device
+        data:
+          title: "High CO2 Level Alert"
+          message: >
+            The PM10 level is too high at {{ states('sensor.czerniawa_pm10') }} ppm.
+            Avoid going outside.
+```
+
+{% endraw %}
+
+## Troubleshooting
+
+Before reporting an issue, enable [debug logging](/docs/configuration/troubleshooting/#debug-logs-and-diagnostics) and restart the integration. As soon as the issue re-occurs, stop the debug logging again (_download of debug log file will start automatically_). Further, _if still possible_, download the {% term diagnostics %} data. If you have collected the debug log and the diagnostics data, include them in the issue report.
+
 ## Removing the integration
 
 This integration follows standard integration removal, no extra steps are required.

From ac14aca387377f6dd57b67d0c4606ec7b667da2c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kamil=20Bregu=C5=82a?= <mik-laj@users.noreply.github.com>
Date: Fri, 26 Dec 2025 15:55:27 +0100
Subject: [PATCH 2/2] Update air quality metrics and notification details

---
 source/_integrations/gios.markdown | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/source/_integrations/gios.markdown b/source/_integrations/gios.markdown
index 2ba053812efb..cf452dcb006e 100644
--- a/source/_integrations/gios.markdown
+++ b/source/_integrations/gios.markdown
@@ -20,9 +20,10 @@ The `gios` integration uses the [GIOŚ](http://powietrze.gios.gov.pl/pjp/current
 ## Use cases
 
 - Monitor outdoor air quality.
-- Warn to close windows when CO2 levels are too high.
+- Warn to close windows when air quality is poor.
 - Control ventilation systems based on air quality.
 
+
 {% include integrations/config_flow.md %}
 
 {% configuration_basic %}
@@ -66,7 +67,7 @@ The following examples show how to use the integration in Home Assistant automat
 
 ### Notify when the PM10 level is too high
 
-The following example sends a notification to your mobile device when the PM10 level exceeds 100 ppm.
+The following example sends a notification to your mobile device when the PM10 level exceeds 100 µg/m³.
 
 {% raw %}
 
@@ -81,9 +82,9 @@ automation:
     actions:
       - action: notify.mobile_app_your_device
         data:
-          title: "High CO2 Level Alert"
+          title: "High PM10 Level Alert"
           message: >
-            The PM10 level is too high at {{ states('sensor.czerniawa_pm10') }} ppm.
+            The PM10 level is too high at {{ states('sensor.czerniawa_pm10') }} µg/m³.
             Avoid going outside.
 ```