meteocat 2.3.0 → 3.1.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,8 +6,14 @@ labels: bug
 assignees: ""
 ---
 
-**IMPORTANT: Please search the issues, including closed issues before opening a new issue.  
-The template is mandatory; failure to use it will result in issue closure.**
+⚠️ **IMPORTANT:**  
+- This template is **only** for reporting bugs, errors, or malfunctions.  
+- Do **not** use it for improvements → use the ♻️ Improvement request template.  
+- Do **not** use it for new features or new API data → use the 🆕 New function template.  
+
+❌ The template is mandatory; failure to follow it will result in the issue being **closed without assistance**.
+
+Before opening a bug report, please search existing issues (including closed ones) and check the [Wiki - Troubleshooting](https://github.com/figorr/meteocat/wiki/Troubleshooting) page.
 
 ---
 

package/.github/ISSUE_TEMPLATE/config.yml

@@ -1 +1,8 @@
 blank_issues_enabled: false
+contact_links:
+  - name: 📖 Wiki - Troubleshooting
+    url: https://github.com/figorr/meteocat/wiki/Troubleshooting
+    about: Please check the Wiki before opening an issue.
+  - name: 💬 Discussions
+    url: https://github.com/figorr/meteocat/discussions
+    about: Ask questions, share ideas, or get help from the community.

package/.github/ISSUE_TEMPLATE/improvement.md

@@ -0,0 +1,39 @@
+---
+name: "♻️ Improvement request"
+about: Suggest an improvement or change to the current behavior of the integration
+title: "[Improvement] "
+labels: enhancement
+assignees: ""
+---
+
+⚠️ **NOTE:** This template is for improvements or changes to the **current behavior of the integration**.  
+
+- It is **not** for bugs, errors, or malfunctions → use the 🐞 Bug report template.  
+- It is **not** for requesting new features or new API data → use the 🆕 New function template.  
+
+❌ Any request that does not follow these rules (e.g. bug reports or feature requests submitted here) will be **closed without assistance**.
+
+---
+
+### Current behavior
+<!-- Describe the current behavior of the integration. -->
+
+### Expected behavior
+<!-- Describe what you would expect instead. -->
+
+### Suggested solution
+<!-- If you have an idea of how it could be improved, describe it here. -->
+
+### Alternatives considered
+<!-- Mention other approaches you thought about. -->
+
+### Additional context
+<!-- Add any other context, screenshots, or examples related to your request. -->
+
+---
+
+### Checklist
+- [ ] I have searched existing issues (including closed ones).
+- [ ] I have checked the [Wiki](https://github.com/figorr/meteocat/wiki).
+- [ ] **I confirm this is not a bug or malfunction, but a request for improvement.**
+- [ ] This request is not a duplicate.

package/.github/ISSUE_TEMPLATE/new_function.md

@@ -0,0 +1,41 @@
+---
+name: "🆕 New function (API-based)"
+about: Suggest a new function that uses data available from the Meteocat API
+title: "[Function] "
+labels: enhancement
+assignees: ""
+---
+
+**IMPORTANT: Please check that the data you are requesting is available in the [Meteocat API Reference](https://apidocs.meteocat.gencat.cat/documentacio/).** 
+
+⚠️ **NOTE:** This template is for new functions or new API data for the **integration**.  
+
+- It is **not** for bugs, errors, or malfunctions → use the 🐞 Bug report template.  
+- It is **not** for requesting improvements or changes to the current behavior of the integration → use the ♻️ Improvement request template.  
+
+❌ Any request that does not follow these rules (e.g. bug reports or improvements requests submitted here) will be **closed without assistance**.
+
+⚠️ **Note on API limits:** Each additional call to retrieve new or extra resources may cause the monthly API quota to be exhausted earlier than expected.  
+Keep in mind that the available limits are relatively low, especially with the basic plan.
+
+---
+
+### Describe the function
+<!-- Clear and concise description of the new function you want to add. -->
+
+### API endpoint / resource
+<!-- Indicate which API endpoint/resource provides this data. -->
+
+### Why is it useful?
+<!-- Explain the value of this function for Home Assistant users. -->
+
+### Additional context
+<!-- Add any other context, screenshots, or examples related to your request. -->
+
+---
+
+### Checklist
+- [ ] I have searched existing issues (including closed ones).
+- [ ] I have checked the [Wiki](https://github.com/figorr/meteocat/wiki).
+- [ ] **I have verified that the requested data is available in the [Meteocat API Reference](https://apidocs.meteocat.gencat.cat/documentacio/).**
+- [ ] This request is not a duplicate.

package/.github/labels.yml

@@ -0,0 +1,63 @@
+- name: breaking-change
+  color: d73a4a
+  description: Indicates a breaking change affecting upgrade or usage.
+
+- name: bug
+  color: d73a4a
+  description: Something isn't working.
+
+- name: documentation
+  color: 0075ca
+  description: Improvements or additions to documentation.
+
+- name: duplicate
+  color: cfd3d7
+  description: This issue or pull request already exists.
+
+- name: enhancement
+  color: a2eeef
+  description: New feature or request.
+
+- name: first read
+  color: 0052cc
+  description: Mandatory reading before opening issues.
+
+- name: good first issue
+  color: 7057ff
+  description: Good for newcomers.
+
+- name: help wanted
+  color: 008672
+  description: Extra attention is needed.
+
+- name: invalid
+  color: e4e669
+  description: This doesn't seem right.
+
+- name: logs required
+  color: b60205
+  description: Logs are required.
+
+- name: merged
+  color: b337b8
+  description: Solution merged.
+
+- name: question
+  color: d876e3
+  description: Further information is requested.
+
+- name: solved
+  color: 0e8a16
+  description: Solved issue.
+
+- name: stale
+  color: ededed
+  description: Marked as stale due to inactivity.
+
+- name: wiki
+  color: fbca04
+  description: Documented at Wiki.
+
+- name: wontfix
+  color: ffffff
+  description: This will not be worked on.

package/.github/workflows/autocloser.yaml

@@ -3,23 +3,25 @@ name: Autocloser
 on:
   issues:
     types: [opened, edited, reopened]
-  issue_comment:
-    types: [created]
 
 jobs:
   autoclose:
     runs-on: ubuntu-latest
     steps:
-      - name: Autoclose issues that did not follow issue template
+      - name: Autoclose issues that did not follow any template
         uses: roots/issue-closer@v1.1
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           issue-close-message: >
-            👋 @${{ github.event.issue.user.login }} this issue was automatically closed because it did not follow the 
-            [issue template](https://github.com/figorr/meteocat/issues/new/choose).  
+            👋 @${{ github.event.issue.user.login }} this issue was automatically closed because it did not follow any of the required templates.
 
-            ⚠️ Reminder:  
-            **IMPORTANT: Please search the issues, including closed issues before opening a new issue.  
-            The template is mandatory; failure to use it will result in issue closure.**
+            ⚠️ Reminder:
+            - Use the [🐞 Bug report template](https://github.com/figorr/meteocat/issues/new?template=bug_report.md) for errors or malfunctions.  
+            - Use the [♻️ Improvement request template](https://github.com/figorr/meteocat/issues/new?template=improvement.md) for changes to current behavior.  
+            - Use the [🆕 New function template](https://github.com/figorr/meteocat/issues/new?template=new_function.md) for API-based new features.  
+
+            The template is mandatory; failure to use it will result in issue closure.
           issue-pattern: >
-            (Describe the bug|To Reproduce|Expected behavior|System details|Debug Logs)
+            (### Describe the bug|### To Reproduce|### Expected behavior|### System details|### Debug Logs|
+            I confirm this is not a bug or malfunction, but a request for improvement|
+            I have verified that the requested data is available)

package/.github/workflows/close-on-label.yml

@@ -0,0 +1,48 @@
+name: Close on labels
+
+on:
+  issues:
+    types:
+      - labeled
+
+jobs:
+  close-and-comment:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Filter relevant labels
+        if: ${{ contains('wiki,solved,merged,duplicate', github.event.label.name) }}
+        id: check
+        run: echo "label=${{ github.event.label.name }}" >> $GITHUB_OUTPUT
+
+      - name: Determine message based on label
+        if: ${{ steps.check.outputs.label }}
+        id: message
+        run: |
+          case "${{ github.event.label.name }}" in
+            wiki)
+              echo "message=👋 This issue is covered in the [Meteocat Wiki](https://github.com/figorr/meteocat/wiki). Please check the documentation there for guidance." >> $GITHUB_OUTPUT
+              ;;
+            solved)
+              echo "message=✅ This issue has been solved. Closing now." >> $GITHUB_OUTPUT
+              ;;
+            merged)
+              echo "message=🔀 This issue has been merged manually. 'Merged manually in master [commit_hash]'." >> $GITHUB_OUTPUT
+              ;;
+            duplicate)
+            echo "message=📄 This issue is marked as a duplicate. 'Closed as duplicate of #<issue_number>'." >> $GITHUB_OUTPUT
+            ;;
+          esac
+
+      - name: Add comment
+        if: ${{ steps.check.outputs.label }}
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue-number: ${{ github.event.issue.number }}
+          body: ${{ steps.message.outputs.message }}
+
+      - name: Close issue if open
+        if: ${{ github.event.issue.state == 'open' && steps.check.outputs.label }}
+        uses: peter-evans/close-issue@v2
+        with:
+          issue-number: ${{ github.event.issue.number }}

package/.github/workflows/force-sync-labels.yml

@@ -0,0 +1,18 @@
+name: Force sync labels
+
+on:
+  workflow_dispatch:   # solo se ejecuta manualmente
+
+jobs:
+  labels:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Force sync GitHub labels
+        uses: crazy-max/ghaction-github-labeler@v5
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          yaml-file: .github/labels.yml
+          skip-delete: false  # elimina labels que no estén en el YAML
+          dry-run: false      # aplica cambios realmente

package/.github/workflows/release.yml

@@ -33,37 +33,7 @@ jobs:
           git config user.name "semantic-release-bot"
           git config user.email "jdcuartero@yahoo.es"
 
-      # Paso 5: Obtener próxima versión (dry-run)
-      - name: Get next version
-        id: nextver
-        run: |
-          version=$(npx semantic-release --dry-run | grep "The next release version is" | awk '{print $NF}')
-          echo "next_version=$version" >> $GITHUB_OUTPUT
-          echo "Next version: $version"
-
-      # Paso 6: Actualizar archivos de versión antes del release
-      - name: Update version in files
-        run: |
-          version=${{ steps.nextver.outputs.next_version }}
-
-          # pyproject.toml
-          sed -i "s/^version = \".*\"/version = \"$version\"/" pyproject.toml
-
-          # manifest.json
-          jq --arg ver "$version" '.version = $ver' custom_components/meteocat/manifest.json > tmp.json && mv tmp.json custom_components/meteocat/manifest.json
-
-          # version.py
-          echo "__version__ = \"$version\"" > custom_components/meteocat/version.py
-
-          # __init__.py
-          sed -i "s/^__version__ = \".*\"/__version__ = \"$version\"/" custom_components/meteocat/__init__.py
-
-          # Commit con [skip ci] para no reiniciar workflow
-          git add pyproject.toml custom_components/meteocat/manifest.json custom_components/meteocat/version.py custom_components/meteocat/__init__.py
-          git commit -m "chore: bump version to $version [skip ci]" || echo "No changes to commit"
-          git push origin master
-
-      # Paso 7: Ejecutar semantic-release (generación de release, changelog, assets)
+      # Paso 5: Ejecutar semantic-release (se encargará de actualizar versiones, changelog, y release)
       - name: Run semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.WORKFLOW_TOKEN }}

package/.github/workflows/sync-gitlab.yml

@@ -3,6 +3,7 @@ name: Sync to GitLab
 on:
   release:
     types: [published]  # Se dispara al publicarse un release en GitHub
+  workflow_dispatch:    # Permite ejecución manual desde la interfaz
 
 jobs:
   sync:
@@ -32,10 +33,22 @@ jobs:
       # Paso 4: Comprobar divergencias en master
       - name: Check for diverging commits
         run: |
-          git fetch gitlab master
-          if ! git merge-base --is-ancestor gitlab/master master; then
-            echo "❌ GitLab master tiene commits que GitHub no tiene. Revisar antes de sincronizar."
-            exit 1
+          # Trae todas las ramas del remoto GitLab y crea referencias locales
+          git fetch gitlab +refs/heads/*:refs/remotes/gitlab/*
+      
+          # Comprueba que la rama gitlab/master exista
+          if git show-ref --verify --quiet refs/remotes/gitlab/master; then
+              # Comprueba si GitLab master tiene commits que GitHub no tiene
+              if ! git merge-base --is-ancestor gitlab/master master; then
+                  echo "❌ GitLab master tiene commits que GitHub no tiene. Revisar antes de sincronizar."
+                  exit 1
+              else
+                  echo "GitLab master está alineado con GitHub master ✅"
+              fi
+          else
+              echo "❌ La rama gitlab/master no se pudo encontrar localmente. Abortando."
+              exit 1
+          fi
 
       # Paso 5: Push de commits y tags a GitLab
       - name: Push commits and tags to GitLab

package/.github/workflows/sync-labels.yml

@@ -0,0 +1,21 @@
+name: Sync labels
+
+on:
+  push:
+    paths:
+      - .github/labels.yml
+  workflow_dispatch:
+
+jobs:
+  labels:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Sync GitHub labels (safe)
+        uses: crazy-max/ghaction-github-labeler@v5
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          yaml-file: .github/labels.yml
+          skip-delete: true   # no elimina labels que no estén en el YAML
+          dry-run: false      # aplica cambios realmente

package/.releaserc

@@ -9,6 +9,27 @@
         "changelogFile": "CHANGELOG.md"
       }
     ],
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "bash ./scripts/update_version.sh ${nextRelease.version}"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "pyproject.toml",
+          "custom_components/meteocat/manifest.json",
+          "custom_components/meteocat/version.py",
+          "custom_components/meteocat/__init__.py",
+          "CHANGELOG.md",
+          "package.json",
+          "package-lock.json"
+        ],
+        "message": "chore(release): v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
     "@semantic-release/npm",
     "@semantic-release/github"
   ],

package/AUTHORS.md

@@ -10,3 +10,4 @@
 
 ## Contributors
 
+- mcasellas [GitHub](https://github.com/mcasellas)

package/CHANGELOG.md

@@ -1,4 +1,60 @@
-# [2.3.0](https://github.com/figorr/meteocat/compare/v2.2.7...v2.3.0) (2025-09-10)
+# [3.1.0](https://github.com/figorr/meteocat/compare/v3.0.0...v3.1.0) (2025-09-27)
+
+
+### Bug Fixes
+
+* fix unknown threshold translation ([6fa7964](https://github.com/figorr/meteocat/commit/6fa79644e3ebbdf9a44826f6071af6009cd2d02d))
+* include Meteocat Card ([513d9ed](https://github.com/figorr/meteocat/commit/513d9ed50fcd9127ac64f0388ed1017db938f378))
+
+
+### Features
+
+* ✨ Add native sunrise and sunset sensors to Meteocat integration ([7bb70c6](https://github.com/figorr/meteocat/commit/7bb70c681c90773275e496f938f455c3688fb4c0))
+
+## [3.0.0](https://github.com/figorr/meteocat/compare/v2.3.0...v3.0.0) (2025-09-14)
+
+
+### ⚠️ BREAKING CHANGES
+
+* Version **3.0.0 and later** introduces a **breaking change** in how entities are identified.
+
+## ⚠️ What this affects
+- This affects any update **from a version prior to 3.0.0** to **any version 3.x or later**. 
+- Entities now use **`town_id`** instead of `region_id` in their `unique_id`.  
+- This change allows multiple integration entries that share the same `region_id` but different towns.  
+
+### ✅ Recommended upgrade procedure
+To avoid issues with duplicated or unavailable entities:
+
+1. **Uninstall** the existing integration (v2.x).  
+2. **Restart** Home Assistant.  
+3. **Install v3.0.0 or later** and configure the integration again.  
+
+### 🚨 If you update directly
+If you update without uninstalling first:
+
+- Old entities will remain as **Unavailable**.  
+- New entities will be created (sometimes with a suffix like `2`).  
+- You may need to manually **remove old entities** and update your automations, dashboards, or scripts to point to the new entities.
+
+### 📑 Additional notes
+
+- This change affects all entity types, including **sensors, diagnostic sensors, and alerts**.  
+- Always backup your **Home Assistant configuration** before performing major upgrades.
+
+ℹ️ More details:  
+- [README – Breaking changes](https://github.com/figorr/meteocat#-breaking-changes---upgrade-to-3x)  
+- [Wiki – Breaking changes](https://github.com/figorr/meteocat/wiki/Breaking-Changes)
+
+### Features
+
+* change unique_id to use town_id ([3a048ce](https://github.com/figorr/meteocat/commit/3a048ce48a0e1f3ee7642c28bbe7ac6e6e3fc298))
+
+### Contributors:  
+- [mcasellas](https://github.com/mcasellas) – contributed [c505f27](https://github.com/figorr/meteocat/commit/c505f27) - Improve Catalan translations
+
+
+## [2.3.0](https://github.com/figorr/meteocat/compare/v2.2.7...v2.3.0) (2025-09-10)
 
 
 ### Features
@@ -15,6 +71,7 @@
 * update README ([9855939](https://github.com/figorr/meteocat/commit/98559398e6bae30e8e9c9ff2b2fe27409a3930bd))
 * update repo files structure ([0778679](https://github.com/figorr/meteocat/commit/0778679d218a89e89bb18791f1245c5c9f7b188f))
 
+
 ## [2.2.7](https://github.com/figorr/meteocat/compare/v2.2.6...v2.2.7) (2025-08-29)
 
 

package/README.md

@@ -6,8 +6,9 @@
 [![Validate](https://github.com/figorr/meteocat/actions/workflows/validate.yaml/badge.svg)](https://github.com/figorr/meteocat/actions/workflows/validate.yaml)
 [![Release](https://github.com/figorr/meteocat/actions/workflows/release.yml/badge.svg)](https://github.com/figorr/meteocat/actions/workflows/release.yml)
 ![GitHub all releases](https://img.shields.io/github/downloads/figorr/meteocat/total)
-![GitHub release (latest by SemVer)](https://img.shields.io/github/downloads/figorr/meteocat/latest/total)
-
+![GitHub release](https://img.shields.io/github/downloads/figorr/meteocat/latest/total)
+![Latest release](https://img.shields.io/github/v/release/figorr/meteocat?label=latest)
+[![Breaking Changes](https://img.shields.io/badge/Breaking%20Changes-critical?logo=data:image/svg+xml;base64,PHN2ZyBpZD0iTGF5ZXJfMSIgZGF0YS1uYW1lPSJMYXllciAxIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjIuODggMTExLjU0Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6IzFhMWExYTt9LmNscy0ye2ZpbGw6I2ZmZWYxMTtmaWxsLXJ1bGU6ZXZlbm9kZDt9PC9zdHlsZT48L2RlZnM+PHRpdGxlPmNhdXRpb248L3RpdGxlPjxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTIuMzUsODQuNDIsNDUuMjgsMTAuMmwuMTctLjI3aDBBMjMsMjMsMCwwLDEsNTIuNSwyLjY5LDE3LDE3LDAsMCwxLDYxLjU3LDBhMTYuNywxNi43LDAsMCwxLDkuMTEsMi42OSwyMi43OSwyMi43OSwwLDAsMSw3LDcuMjZxLjE5LjMyLjM2LjYzbDQyLjIzLDczLjM0LjI0LjQ0aDBhMjIuNDgsMjIuNDgsMCwwLDEsMi4zNywxMC4xOSwxNy42MywxNy42MywwLDAsMS0yLjE3LDguMzUsMTUuOTQsMTUuOTQsMCwwLDEtNi45Myw2LjZjLS4xOS4xLS4zOS4xOC0uNTguMjZhMjEuMTksMjEuMTksMCwwLDEtOS4xMSwxLjc1djBIMTcuNjFjLS4yMiwwLS40NCwwLS42NSwwYTE4LjA3LDE4LjA3LDAsMCwxLTYuMi0xLjE1QTE2LjQyLDE2LjQyLDAsMCwxLDMsMTA0LjI0YTE3LjUzLDE3LjUzLDAsMCwxLTMtOS41NywyMywyMywwLDAsMSwxLjU3LTguNzQsNy42Niw3LjY2LDAsMCwxLC43Ny0xLjUxWiIvPjxwYXRoIGNsYXNzPSJjbHMtMiIgZD0iTTksODguNzUsNTIuMTIsMTQuMTZjNS4yNC04LjI1LDEzLjU0LTguNDYsMTguODcsMGw0Mi40Myw3My42OWMzLjM5LDYuODEsMS43MSwxNi05LjMzLDE1Ljc3SDE3LjYxQzEwLjM1LDEwMy44LDUuNjcsOTcuNDMsOSw4OC43NVoiLz48cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik01Ny41Nyw4Mi42OUE1LjQ4LDUuNDgsMCwwLDEsNjEsODEuMTFhNS42Niw1LjY2LDAsMCwxLDQuNDIsMS42Niw1LjUzLDUuNTMsMCwwLDEsMS42MiwzLjU0QTUuNiw1LjYsMCwwLDEsNjcsODcuNzJhNiw2LDAsMCwxLS40MiwxLjM0LDUuNTMsNS41MywwLDAsMS0yLjkyLDIuODQsNS43OSw1Ljc5LDAsMCwxLTQuNTctLjEsNS41MSw1LjUxLDAsMCwxLTIuODEtMi45NCw1LjMxLDUuMzEsMCwwLDEtLjM2LTEuMjcsNS45LDUuOSwwLDAsMS0uMDYtMS4zMmgwYTYuNDUsNi40NSwwLDAsMSwuNTctMiw0LjYsNC42LDAsMCwxLDEuMTQtMS41NlptOC4xNS0xMC4yNGMtLjE5LDQuNzktOC4zMSw0LjgtOC40OSwwLS44Mi04LjIxLTIuOTItMjcuNy0yLjg2LTM1LjQyLjA3LTIuMzgsMi0zLjc4LDQuNTYtNC4zMmExMS4xOSwxMS4xOSwwLDAsMSwyLjQ5LS4yNCwxMS43NywxMS43NywwLDAsMSwyLjUuMjVjMi42MS41NSw0LjY1LDIsNC42NSw0LjQ0di4yNEw2NS43Miw3Mi40NVoiLz48L3N2Zz4=&logoColor=white)](#-breaking-changes---upgrade-to-3x)
 
 This is a project to obtain meteorological data from the Meteocat API inside the Home Assistant environment.
 
@@ -21,8 +22,40 @@ Commercial use of this project or the data obtained from the API is not allowed
 
 This is a personal project.
 
-Authors:
-- Figorr
+**Authors:**  
+- [Figorr](https://github.com/figorr)
+
+**Contributors:**  
+- [mcasellas](https://github.com/mcasellas) – contributed [c505f27](https://github.com/figorr/meteocat/commit/c505f27) - Improve Catalan translations
+
+## ⚠️ Breaking changes - Upgrade to 3.0.0 or later coming from prior versions
+
+Version **3.0.0 and later** introduces a **breaking change** in how entities are identified.
+
+### ⚠️ What this affects
+- This affects any update **from a version prior to 3.0.0** to **any version 3.x or later**. 
+- Entities now use **`town_id`** instead of `region_id` in their `unique_id`.  
+- This change allows multiple integration entries that share the same `region_id` but different towns.  
+
+### ✅ Recommended upgrade procedure
+To avoid issues with duplicated or unavailable entities:
+
+1. **Uninstall** the existing integration (v2.x).<br>
+  🔗 See [Uninstallation Guide](https://github.com/figorr/meteocat/wiki/Uninstallation) for the proper way of removing prior versions.  
+2. **Restart** Home Assistant.  
+3. **Install v3.0.0 or later** and configure the integration again.  
+
+### 🚨 If you update directly
+If you update without uninstalling first:
+
+- Old entities will remain as **Unavailable**.  
+- New entities will be created (sometimes with a suffix like `2`).  
+- You may need to manually **remove old entities** and update your automations, dashboards, or scripts to point to the new entities.
+
+### 📑 Additional notes
+
+- This change affects all entity types, including **sensors, diagnostic sensors, and alerts**.  
+- Always backup your **Home Assistant configuration** before performing major upgrades.
 
 ## Installation
 
@@ -35,7 +68,6 @@ Authors:
 1. Click `+ Add Integration`
 1. Search for `Meteocat` and follow the configuration instructions
 
-
 #### HACS - Install from the store
 1. Go to `HACS`
 1. Search for `Meteocat` and add it to HACS
@@ -103,7 +135,50 @@ You will see three available options:
   If for any reason some files in the `assets` folder (`towns.json`, `stations.json`, `variables.json`, `symbols.json`, or `stations_<town_id>.json`) are missing or outdated, you can regenerate them directly from the options menu.  
   > ℹ️ If the Meteocat API is not available at that moment, the integration will still start, and you can retry regeneration later.
 
-![Options](images/options.png)
+### Accessing the Options Menu
+
+You can access the Options Menu in two ways, both inside the integration:
+
+- **Setup Options**  
+
+  ![Setup Options menu](images/setup_options.png)
+
+- **System Options**  
+
+  ![System Options menu](images/system_options.png)
+
+  Once you are inside, you will see the following options:  
+
+  ![Available Options](images/options.png)
+
+
+## Uninstallation
+
+To correctly uninstall the integration:
+
+- If you are upgrading due to **breaking changes**, remove all configured entries from  
+  **Settings > Devices & Services > Integrations**, restart Home Assistant, and reinstall the new version.  
+- If you want to **completely remove Meteocat**, after removing the entries and restarting, also uninstall the integration from **HACS > Integrations**.
+
+👉 For detailed steps with screenshots, check the [Uninstallation Guide](https://github.com/figorr/meteocat/wiki/Uninstallation).
+
+## Custom Meteocat Card available
+
+Meteocat integration has its own weather card.
+
+To install the card, please follow the instructions from its own repository, [🎫 Meteocat Card](https://github.com/figorr/meteocat-card).
+
+![Meteocat Card](images/daily_forecast_2_alerts.png)
+
+# Documentation
+
+For more detailed information about:
+- Installation and configuration  
+- Usage examples  
+- Extra attributes in sensors  
+- Known issues and troubleshooting  
+
+please visit the [📖 Meteocat Wiki](https://github.com/figorr/meteocat/wiki).
 
 # Contributing