nanoleaf-kde-sync 1.9.3__tar.gz

nanoleaf_kde_sync-1.9.3/LICENSE

@@ -0,0 +1,27 @@
+Nanoleaf Source-Available Non-Commercial License
+Copyright (c) 2026 SpinGiantCRM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, merge, and distribute the Software, subject to the following
+conditions:
+
+1. The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+2. Redistribution of the Software must be at no charge.
+
+3. Any use, distribution, sublicensing, hosting, bundling, sale, or other
+   activity involving the Software that is intended for or directed toward
+   commercial advantage or monetary compensation is prohibited without prior
+   written permission from the copyright holder.
+
+4. All commercial rights are reserved to the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nanoleaf_kde_sync-1.9.3/MANIFEST.in

@@ -0,0 +1,3 @@
+include VERSION
+graft assets
+recursive-include src/nanoleaf_sync/ui *.qss

nanoleaf_kde_sync-1.9.3/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: nanoleaf-kde-sync
+Version: 1.9.3
+Summary: Nanoleaf screen mirroring for KDE Plasma on Linux.
+License-Expression: LicenseRef-Nanoleaf-Source-Available-Non-Commercial
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.21
+Requires-Dist: PyQt6<7,>=6.0
+Requires-Dist: dbus-next<1,>=0.2.0
+Requires-Dist: hidapi<1,>=0.14.0
+Requires-Dist: dacite<2,>=1.8.1
+Requires-Dist: tomli-w<2,>=1.0.0
+Requires-Dist: packaging<26,>=24.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: pytest-timeout>=2.3; extra == "test"
+Requires-Dist: ruff>=0.6; extra == "test"
+Requires-Dist: mypy>=1.0; extra == "test"
+Requires-Dist: pre-commit>=4.0; extra == "test"
+Provides-Extra: portal
+Requires-Dist: pipewire; extra == "portal"
+Provides-Extra: gstreamer
+Requires-Dist: pygobject; extra == "gstreamer"
+Dynamic: license-file
+
+# Nanoleaf Screen Mirror for KDE
+
+Public Nanoleaf USB screen mirroring app for KDE Plasma 6 on Linux (Arch / CachyOS and other distros via source install).
+
+Mirrors your display edge colors to supported Nanoleaf USB strips in real time, with a tray app, setup wizard, calibration, and diagnostics.
+
+## What you need
+
+- Linux with KDE Plasma 6 (Wayland recommended)
+- A supported Nanoleaf USB strip: `NL82K1` (`0x37fa:0x8201`) or `NL82K2` (`0x37fa:0x8202`)
+- USB permissions via udev (see [Hardware setup](docs/HARDWARE_SETUP.md))
+
+## Install (Arch / CachyOS)
+
+**When published on AUR:**
+
+```bash
+paru -S --needed python-dacite nanoleaf-kde-sync
+paru -Syu
+```
+
+**Until AUR account is available — local build from this repo:**
+
+```bash
+paru -S --needed python-dacite
+./scripts/build_arch_package.sh
+```
+
+Install udev rules after package install:
+
+```bash
+./scripts/setup_udev.sh
+```
+
+## Quick start
+
+```bash
+nanoleaf-kde-sync-init-config
+nanoleaf-kde-sync-doctor
+nanoleaf-kde-sync-smoke-test
+nanoleaf-kde-sync
+```
+
+Service-only mode:
+
+```bash
+nanoleaf-kde-sync-service
+```
+
+## Core commands
+
+- `nanoleaf-kde-sync` — tray app (recommended)
+- `nanoleaf-kde-sync-service` — headless runtime service
+- `nanoleaf-kde-sync-init-config` — generate default config
+- `nanoleaf-kde-sync-doctor` — environment/device diagnostics
+- `nanoleaf-kde-sync-smoke-test` — quick functional sanity check
+- `nanoleaf-kde-sync-autostart` — manage KDE autostart integration
+- `nanoleaf-kde-sync-reset` — reset config/calibration/diagnostic cache safely
+
+## First-run setup
+
+1. Start the tray app (`nanoleaf-kde-sync`).
+2. Complete the setup wizard.
+3. Keep **manual strip zone count** set to your real hardware value.
+4. Run a calibration test pattern and assign TL/TR/BR/BL anchors.
+
+Manual strip count is authoritative for runtime, mapping, and calibration. Device-reported count is diagnostics-only unless you explicitly apply a new value.
+
+See the [User guide](docs/USER_GUIDE.md) for a full walkthrough.
+
+## HDR / SDR notes
+
+- `Display preset = SDR`: SDR-safe defaults.
+- `Display preset = HDR`: HDR-first defaults.
+- `Display preset = Auto`: follows compositor capability.
+
+On Plasma HDR desktops, verify SDR white reference and compositor HDR settings in app diagnostics before tuning brightness.
+
+## Fresh install / reinstall / uninstall helpers
+
+Pacman-managed reinstall from a local checkout:
+
+```bash
+./scripts/reinstall_local.sh
+./scripts/uninstall_local.sh
+# optional full purge:
+./scripts/uninstall_local.sh --purge-config
+```
+
+See [Arch / AUR packaging](docs/PACKAGING_AUR.md) for maintainer and AUR publish steps.
+
+## Reset commands
+
+```bash
+nanoleaf-kde-sync-reset app-config --stop-runtime
+nanoleaf-kde-sync-reset calibration --stop-runtime
+nanoleaf-kde-sync-reset diagnostics --stop-runtime
+```
+
+## Documentation
+
+- [User guide](docs/USER_GUIDE.md)
+- [Hardware setup](docs/HARDWARE_SETUP.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Smoke test](docs/SMOKE_TEST.md)
+- [Security](docs/SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+Installed packages also ship docs under `/usr/share/doc/nanoleaf-kde-sync/`.
+
+## Release gate
+
+Run `./scripts/release_gate.sh` before tagging a release. CI must be green on `main`.
+
+## Developer setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[test]
+pre-commit install
+pre-commit run --all-files
+```
+
+## Supported environment
+
+- Linux
+- KDE Plasma 6 (Wayland recommended)
+- Supported Nanoleaf USB strips: `NL82K1` (`0x37fa:0x8201`), `NL82K2` (`0x37fa:0x8202`)
+
+## Known limitations
+
+- Single-monitor flow only (no multi-monitor support).
+- Device strip count auto-detection is diagnostics-only; not auto-applied.
+- Desktop-entry launch context is still preferred for reliable KWin authorization.
+
+## License
+
+Source-available non-commercial license — see [LICENSE](LICENSE). Redistribution terms apply; read before packaging or mirroring.

nanoleaf_kde_sync-1.9.3/README.md

@@ -0,0 +1,139 @@
+# Nanoleaf Screen Mirror for KDE
+
+Public Nanoleaf USB screen mirroring app for KDE Plasma 6 on Linux (Arch / CachyOS and other distros via source install).
+
+Mirrors your display edge colors to supported Nanoleaf USB strips in real time, with a tray app, setup wizard, calibration, and diagnostics.
+
+## What you need
+
+- Linux with KDE Plasma 6 (Wayland recommended)
+- A supported Nanoleaf USB strip: `NL82K1` (`0x37fa:0x8201`) or `NL82K2` (`0x37fa:0x8202`)
+- USB permissions via udev (see [Hardware setup](docs/HARDWARE_SETUP.md))
+
+## Install (Arch / CachyOS)
+
+**When published on AUR:**
+
+```bash
+paru -S --needed python-dacite nanoleaf-kde-sync
+paru -Syu
+```
+
+**Until AUR account is available — local build from this repo:**
+
+```bash
+paru -S --needed python-dacite
+./scripts/build_arch_package.sh
+```
+
+Install udev rules after package install:
+
+```bash
+./scripts/setup_udev.sh
+```
+
+## Quick start
+
+```bash
+nanoleaf-kde-sync-init-config
+nanoleaf-kde-sync-doctor
+nanoleaf-kde-sync-smoke-test
+nanoleaf-kde-sync
+```
+
+Service-only mode:
+
+```bash
+nanoleaf-kde-sync-service
+```
+
+## Core commands
+
+- `nanoleaf-kde-sync` — tray app (recommended)
+- `nanoleaf-kde-sync-service` — headless runtime service
+- `nanoleaf-kde-sync-init-config` — generate default config
+- `nanoleaf-kde-sync-doctor` — environment/device diagnostics
+- `nanoleaf-kde-sync-smoke-test` — quick functional sanity check
+- `nanoleaf-kde-sync-autostart` — manage KDE autostart integration
+- `nanoleaf-kde-sync-reset` — reset config/calibration/diagnostic cache safely
+
+## First-run setup
+
+1. Start the tray app (`nanoleaf-kde-sync`).
+2. Complete the setup wizard.
+3. Keep **manual strip zone count** set to your real hardware value.
+4. Run a calibration test pattern and assign TL/TR/BR/BL anchors.
+
+Manual strip count is authoritative for runtime, mapping, and calibration. Device-reported count is diagnostics-only unless you explicitly apply a new value.
+
+See the [User guide](docs/USER_GUIDE.md) for a full walkthrough.
+
+## HDR / SDR notes
+
+- `Display preset = SDR`: SDR-safe defaults.
+- `Display preset = HDR`: HDR-first defaults.
+- `Display preset = Auto`: follows compositor capability.
+
+On Plasma HDR desktops, verify SDR white reference and compositor HDR settings in app diagnostics before tuning brightness.
+
+## Fresh install / reinstall / uninstall helpers
+
+Pacman-managed reinstall from a local checkout:
+
+```bash
+./scripts/reinstall_local.sh
+./scripts/uninstall_local.sh
+# optional full purge:
+./scripts/uninstall_local.sh --purge-config
+```
+
+See [Arch / AUR packaging](docs/PACKAGING_AUR.md) for maintainer and AUR publish steps.
+
+## Reset commands
+
+```bash
+nanoleaf-kde-sync-reset app-config --stop-runtime
+nanoleaf-kde-sync-reset calibration --stop-runtime
+nanoleaf-kde-sync-reset diagnostics --stop-runtime
+```
+
+## Documentation
+
+- [User guide](docs/USER_GUIDE.md)
+- [Hardware setup](docs/HARDWARE_SETUP.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Smoke test](docs/SMOKE_TEST.md)
+- [Security](docs/SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+Installed packages also ship docs under `/usr/share/doc/nanoleaf-kde-sync/`.
+
+## Release gate
+
+Run `./scripts/release_gate.sh` before tagging a release. CI must be green on `main`.
+
+## Developer setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[test]
+pre-commit install
+pre-commit run --all-files
+```
+
+## Supported environment
+
+- Linux
+- KDE Plasma 6 (Wayland recommended)
+- Supported Nanoleaf USB strips: `NL82K1` (`0x37fa:0x8201`), `NL82K2` (`0x37fa:0x8202`)
+
+## Known limitations
+
+- Single-monitor flow only (no multi-monitor support).
+- Device strip count auto-detection is diagnostics-only; not auto-applied.
+- Desktop-entry launch context is still preferred for reliable KWin authorization.
+
+## License
+
+Source-available non-commercial license — see [LICENSE](LICENSE). Redistribution terms apply; read before packaging or mirroring.

nanoleaf_kde_sync-1.9.3/VERSION

@@ -0,0 +1 @@
+1.9.3

nanoleaf_kde_sync-1.9.3/assets/icons/hicolor/scalable/apps/nanoleaf-kde-sync.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="nanoleaf-kde-sync">
+  <defs>
+    <linearGradient id="brand" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#3ddc97"/>
+      <stop offset="1" stop-color="#30a7ff"/>
+    </linearGradient>
+    <linearGradient id="screen" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#e05c5c" stop-opacity="0.82"/>
+      <stop offset="0.5" stop-color="#3ddc97" stop-opacity="0.82"/>
+      <stop offset="1" stop-color="#30a7ff" stop-opacity="0.82"/>
+    </linearGradient>
+  </defs>
+  <rect x="4" y="4" width="120" height="120" rx="22" fill="#1c202e"/>
+  <rect x="12" y="14" width="104" height="70" rx="9" fill="none" stroke="url(#brand)" stroke-width="4.5"/>
+  <rect x="19" y="21" width="90" height="56" rx="5" fill="url(#screen)"/>
+  <rect x="55" y="84" width="18" height="9" rx="4" fill="#3ddc97" opacity="0.75"/>
+  <rect x="40" y="93" width="48" height="7" rx="3.5" fill="#3ddc97" opacity="0.6"/>
+  <rect x="12" y="109" width="28" height="14" rx="7" fill="#e05c5c" opacity="0.92"/>
+  <rect x="50" y="109" width="28" height="14" rx="7" fill="#3ddc97" opacity="0.92"/>
+  <rect x="88" y="109" width="28" height="14" rx="7" fill="#30a7ff" opacity="0.92"/>
+</svg>

nanoleaf_kde_sync-1.9.3/assets/udev/60-nanoleaf-kde-sync.rules

@@ -0,0 +1,7 @@
+# Nanoleaf USB Screen Mirror Light Strip and Pegboard Desk Dock
+# Gives local users access via the `plugdev` group.
+SUBSYSTEM=="hidraw", ATTRS{idVendor}=="37fa", ATTRS{idProduct}=="8201", MODE="0660", GROUP="plugdev", TAG+="uaccess"
+SUBSYSTEM=="hidraw", ATTRS{idVendor}=="37fa", ATTRS{idProduct}=="8202", MODE="0660", GROUP="plugdev", TAG+="uaccess"
+
+# Disable USB autosuspend so HID resume latency does not drop frames at 60 FPS.
+ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="37fa", ATTR{idProduct}=="8201|8202", ATTR{power/control}="on"

nanoleaf_kde_sync-1.9.3/pyproject.toml

@@ -0,0 +1,129 @@
+[build-system]
+requires = ["setuptools>=77.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nanoleaf-kde-sync"
+dynamic = ["version"]
+description = "Nanoleaf screen mirroring for KDE Plasma on Linux."
+readme = "README.md"
+license = "LicenseRef-Nanoleaf-Source-Available-Non-Commercial"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+  "numpy>=1.21,<3",
+  "PyQt6>=6.0,<7",
+  "dbus-next>=0.2.0,<1",
+  "hidapi>=0.14.0,<1",
+  "dacite>=1.8.1,<2",
+  "tomli-w>=1.0.0,<2",
+  "packaging>=24.0,<26",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+  "pytest-cov>=5",
+  "pytest-timeout>=2.3",
+  "ruff>=0.6",
+  "mypy>=1.0",
+  "pre-commit>=4.0",
+]
+portal = [
+  "pipewire",
+]
+gstreamer = [
+  "pygobject",
+]
+
+[project.scripts]
+nanoleaf-kde-sync = "nanoleaf_sync.ui.tray_app:main"
+nanoleaf-kde-sync-service = "nanoleaf_sync.service:main"
+nanoleaf-kde-sync-doctor = "nanoleaf_sync.tools.doctor:main"
+nanoleaf-kde-sync-smoke-test = "nanoleaf_sync.tools.smoke_test:main"
+nanoleaf-kde-sync-init-config = "nanoleaf_sync.tools.config_init:main"
+nanoleaf-kde-sync-autostart = "nanoleaf_sync.tools.autostart:main"
+nanoleaf-kde-sync-reset = "nanoleaf_sync.tools.reset:main"
+
+
+[tool.setuptools.dynamic]
+version = {file = ["VERSION"]}
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["nanoleaf_sync*"]
+
+[tool.setuptools.package-data]
+nanoleaf_sync = [
+  "VERSION",
+  "ui/style.qss",
+  "assets/icons/**/*",
+  "assets/udev/60-nanoleaf-kde-sync.rules",
+  "capture/nanoleaf_drm_helper",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+omit = [
+  "src/nanoleaf_sync/ui/settings_dialog.py",
+  "src/nanoleaf_sync/ui/display_configurator.py",
+  "src/nanoleaf_sync/ui/live_diagnostics.py",
+  "src/nanoleaf_sync/ui/led_color_calibration_dialog.py",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["N802", "N803", "N806"]
+"src/nanoleaf_sync/tools/doctor.py" = ["E402"]
+"src/nanoleaf_sync/tools/smoke_test.py" = ["E402"]
+"src/nanoleaf_sync/tools/autostart.py" = ["E402"]
+"src/nanoleaf_sync/capture/kwin_dbus.py" = ["E402"]
+"src/nanoleaf_sync/config/store.py" = ["E402"]
+"src/nanoleaf_sync/device/hid_transport.py" = ["E402"]
+"src/nanoleaf_sync/ui/settings_dialog.py" = ["E402", "N802", "N803", "N806"]
+"src/nanoleaf_sync/ui/display_configurator.py" = ["N802", "N803", "N806"]
+"src/nanoleaf_sync/ui/calibration_widget.py" = ["N806"]
+"src/nanoleaf_sync/ui/led_color_calibration_dialog.py" = ["N806"]
+"src/nanoleaf_sync/capture/_drm_zone_sampler.py" = ["N802", "N806"]
+"src/nanoleaf_sync/color/hdr.py" = ["N806"]
+"src/nanoleaf_sync/color/primaries.py" = ["N806"]
+
+[tool.ruff.format]
+line-ending = "lf"
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+exclude = ["src/nanoleaf_sync/ui/"]
+files = ["src/nanoleaf_sync"]
+
+[[tool.mypy.overrides]]
+module = [
+  "nanoleaf_sync.capture.*",
+  "nanoleaf_sync.runtime.*",
+  "nanoleaf_sync.device.*",
+  "nanoleaf_sync.service",
+  "nanoleaf_sync.desktop_entry",
+  "nanoleaf_sync.color.hdr",
+  "nanoleaf_sync.color.zone_mapper",
+  "nanoleaf_sync.tools.portal_tools",
+  "nanoleaf_sync.tools.color_kmeans",
+]
+ignore_errors = true
+
+[tool.bandit]
+exclude_dirs = ["tests", "build", "dist", ".venv"]
+skips = ["B101", "B108", "B110", "B311", "B324", "B404", "B603", "B607", "B608"]

nanoleaf_kde_sync-1.9.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nanoleaf_kde_sync-1.9.3/src/nanoleaf_kde_sync.egg-info/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: nanoleaf-kde-sync
+Version: 1.9.3
+Summary: Nanoleaf screen mirroring for KDE Plasma on Linux.
+License-Expression: LicenseRef-Nanoleaf-Source-Available-Non-Commercial
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.21
+Requires-Dist: PyQt6<7,>=6.0
+Requires-Dist: dbus-next<1,>=0.2.0
+Requires-Dist: hidapi<1,>=0.14.0
+Requires-Dist: dacite<2,>=1.8.1
+Requires-Dist: tomli-w<2,>=1.0.0
+Requires-Dist: packaging<26,>=24.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Requires-Dist: pytest-timeout>=2.3; extra == "test"
+Requires-Dist: ruff>=0.6; extra == "test"
+Requires-Dist: mypy>=1.0; extra == "test"
+Requires-Dist: pre-commit>=4.0; extra == "test"
+Provides-Extra: portal
+Requires-Dist: pipewire; extra == "portal"
+Provides-Extra: gstreamer
+Requires-Dist: pygobject; extra == "gstreamer"
+Dynamic: license-file
+
+# Nanoleaf Screen Mirror for KDE
+
+Public Nanoleaf USB screen mirroring app for KDE Plasma 6 on Linux (Arch / CachyOS and other distros via source install).
+
+Mirrors your display edge colors to supported Nanoleaf USB strips in real time, with a tray app, setup wizard, calibration, and diagnostics.
+
+## What you need
+
+- Linux with KDE Plasma 6 (Wayland recommended)
+- A supported Nanoleaf USB strip: `NL82K1` (`0x37fa:0x8201`) or `NL82K2` (`0x37fa:0x8202`)
+- USB permissions via udev (see [Hardware setup](docs/HARDWARE_SETUP.md))
+
+## Install (Arch / CachyOS)
+
+**When published on AUR:**
+
+```bash
+paru -S --needed python-dacite nanoleaf-kde-sync
+paru -Syu
+```
+
+**Until AUR account is available — local build from this repo:**
+
+```bash
+paru -S --needed python-dacite
+./scripts/build_arch_package.sh
+```
+
+Install udev rules after package install:
+
+```bash
+./scripts/setup_udev.sh
+```
+
+## Quick start
+
+```bash
+nanoleaf-kde-sync-init-config
+nanoleaf-kde-sync-doctor
+nanoleaf-kde-sync-smoke-test
+nanoleaf-kde-sync
+```
+
+Service-only mode:
+
+```bash
+nanoleaf-kde-sync-service
+```
+
+## Core commands
+
+- `nanoleaf-kde-sync` — tray app (recommended)
+- `nanoleaf-kde-sync-service` — headless runtime service
+- `nanoleaf-kde-sync-init-config` — generate default config
+- `nanoleaf-kde-sync-doctor` — environment/device diagnostics
+- `nanoleaf-kde-sync-smoke-test` — quick functional sanity check
+- `nanoleaf-kde-sync-autostart` — manage KDE autostart integration
+- `nanoleaf-kde-sync-reset` — reset config/calibration/diagnostic cache safely
+
+## First-run setup
+
+1. Start the tray app (`nanoleaf-kde-sync`).
+2. Complete the setup wizard.
+3. Keep **manual strip zone count** set to your real hardware value.
+4. Run a calibration test pattern and assign TL/TR/BR/BL anchors.
+
+Manual strip count is authoritative for runtime, mapping, and calibration. Device-reported count is diagnostics-only unless you explicitly apply a new value.
+
+See the [User guide](docs/USER_GUIDE.md) for a full walkthrough.
+
+## HDR / SDR notes
+
+- `Display preset = SDR`: SDR-safe defaults.
+- `Display preset = HDR`: HDR-first defaults.
+- `Display preset = Auto`: follows compositor capability.
+
+On Plasma HDR desktops, verify SDR white reference and compositor HDR settings in app diagnostics before tuning brightness.
+
+## Fresh install / reinstall / uninstall helpers
+
+Pacman-managed reinstall from a local checkout:
+
+```bash
+./scripts/reinstall_local.sh
+./scripts/uninstall_local.sh
+# optional full purge:
+./scripts/uninstall_local.sh --purge-config
+```
+
+See [Arch / AUR packaging](docs/PACKAGING_AUR.md) for maintainer and AUR publish steps.
+
+## Reset commands
+
+```bash
+nanoleaf-kde-sync-reset app-config --stop-runtime
+nanoleaf-kde-sync-reset calibration --stop-runtime
+nanoleaf-kde-sync-reset diagnostics --stop-runtime
+```
+
+## Documentation
+
+- [User guide](docs/USER_GUIDE.md)
+- [Hardware setup](docs/HARDWARE_SETUP.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Smoke test](docs/SMOKE_TEST.md)
+- [Security](docs/SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+Installed packages also ship docs under `/usr/share/doc/nanoleaf-kde-sync/`.
+
+## Release gate
+
+Run `./scripts/release_gate.sh` before tagging a release. CI must be green on `main`.
+
+## Developer setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[test]
+pre-commit install
+pre-commit run --all-files
+```
+
+## Supported environment
+
+- Linux
+- KDE Plasma 6 (Wayland recommended)
+- Supported Nanoleaf USB strips: `NL82K1` (`0x37fa:0x8201`), `NL82K2` (`0x37fa:0x8202`)
+
+## Known limitations
+
+- Single-monitor flow only (no multi-monitor support).
+- Device strip count auto-detection is diagnostics-only; not auto-applied.
+- Desktop-entry launch context is still preferred for reliable KWin authorization.
+
+## License
+
+Source-available non-commercial license — see [LICENSE](LICENSE). Redistribution terms apply; read before packaging or mirroring.