ha-deploy-kit 0.1.0__tar.gz

ha_deploy_kit-0.1.0/.coveragerc-ha

@@ -0,0 +1,10 @@
+# Separate coverage config for the HA adapter, run under the dev-ha env.
+# Deterministic, env-independent gate scoped to the HA adapter only.
+[run]
+branch = true
+source =
+    ha_deploy_kit.ha
+
+[report]
+fail_under = 90
+show_missing = true

ha_deploy_kit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: release
+
+# Automated release. On every push to main (i.e. a merged PR),
+# python-semantic-release reads the Conventional Commit messages since the last
+# release and, if there is anything to release, bumps project.version, updates the
+# changelog, commits that back to main ([skip ci]), tags v<version>, creates a
+# GitHub release, and builds the artifacts. The publish job then uploads to PyPI
+# via Trusted Publishing (OIDC) — no long-lived API token is stored anywhere.
+# See docs/releasing.md for the one-time PyPI setup and the manual fallback.
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # push the bump commit + tag to main, create the GH release
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history so commit analysis can find the last tag
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Upload artifacts
+        if: steps.release.outputs.released == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC token for Trusted Publishing; replaces an API token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ha_deploy_kit-0.1.0/.github/workflows/validate.yml

@@ -0,0 +1,43 @@
+# CI for ha-deploy-kit.
+#
+# This is a Python LIBRARY, not a Home Assistant integration, so there is no
+# HACS / hassfest job. Two independent test jobs mirror the two dependency
+# groups and Python environments:
+#   - tests-core: HA-free, runs on Python 3.10/3.11/3.12 with the dev-core group.
+#   - tests-ha:   the HA adapter, runs on the HA dev Python with the dev-ha group.
+# Every `uses:` is pinned to a 40-char commit SHA. A later per-consumer example
+# may validate separately.
+name: validate
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  tests-core:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v3.1.7
+      - name: Run core tests
+        run: uv run --python ${{ matrix.python-version }} --group dev-core pytest tests --ignore=tests/ha -m "not ha" --cov --cov-report=term-missing
+      - name: Lint
+        run: |
+          uv run --group dev-core ruff check
+          uv run --group dev-core ruff format --check
+
+  tests-ha:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v3.1.7
+      - name: Run HA adapter tests
+        run: uv run --python 3.14 --group dev-ha --extra ha pytest tests/ha --cov --cov-config=.coveragerc-ha --cov-report=term-missing

ha_deploy_kit-0.1.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries. ha-deploy-kit is a library, so the lock is ignored.
+uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+
+.plans
+.vscode

ha_deploy_kit-0.1.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# CHANGELOG
+
+
+## v0.1.0 (2026-10-29)
+
+### Bug Fixes
+
+- **notify**: Verify TLS against a real CA trust store (truststore/certifi)
+  ([`cc95ca9`](https://github.com/latrekc-meta/ha-deploy-kit/commit/cc95ca97546118c8620bb8fb1ba0f383270a7180))
+
+The HTTPS notification used Python's default SSL context, which has no usable CA store on macOS /
+  python.org / fresh venvs and misreported valid certs as tls-error. Add _verifying_ssl_context()
+  (truststore -> certifi -> stdlib, all strictly verifying) and pass it to both the service POST and
+  the probe. Add certifi + truststore as runtime deps; tls-error now reflects genuine failures.
+
+### Continuous Integration
+
+- Automate semantic versioning and PyPI publishing on merge to main
+  ([`38ac841`](https://github.com/latrekc-meta/ha-deploy-kit/commit/38ac841e33421bae630c165fc834cd639f217a15))
+
+python-semantic-release derives the next version from Conventional Commit messages on each push to
+  main, bumps project.version, tags, changelogs, and builds; a publish job then uploads to PyPI via
+  Trusted Publishing (OIDC, no token). allow_zero_version + major_on_zero=false keep 0.x semantics,
+  so the first merge publishes 0.1.0 and tags v0.1.0 automatically. Docs make PyPI the primary
+  install path and document the one-time PyPI/environment setup.
+
+### Documentation
+
+- Readme, install, configuration, and generic adoption guide
+  ([`9a5c9a0`](https://github.com/latrekc-meta/ha-deploy-kit/commit/9a5c9a04d75812025379202b9450c0f894139834))
+
+### Features
+
+- Cli orchestration gated on backend changes
+  ([`e6baa76`](https://github.com/latrekc-meta/ha-deploy-kit/commit/e6baa76a3bf7a31ab828902cf6069ae876b8a790))
+
+- Config loading without global env mutation
+  ([`22eeb50`](https://github.com/latrekc-meta/ha-deploy-kit/commit/22eeb505623ffa56bffd00c5fc222c928b937d7b))
+
+- Ha adapter (service, repairs issue, opt-in fix flow, card serving)
+  ([`fb11c1c`](https://github.com/latrekc-meta/ha-deploy-kit/commit/fb11c1c7a256d76a0e4207d9076b03716c5bdf07))
+
+- Ha-deploy-kit package skeleton and settings
+  ([`5df5334`](https://github.com/latrekc-meta/ha-deploy-kit/commit/5df533432d773eb2b04498077d9a29949e69bb66))
+
+- Local inventory with component-relative keys
+  ([`0cd1f7a`](https://github.com/latrekc-meta/ha-deploy-kit/commit/0cd1f7a3739d89077ee021b64afdb1786759f094))
+
+- Optional frontend profile (publish + run, no restart)
+  ([`07d5418`](https://github.com/latrekc-meta/ha-deploy-kit/commit/07d54181bd6886a7b3a1923160cbf75e795eaa00))
+
+- Remote inventory wire format and comparison plan
+  ([`16f3461`](https://github.com/latrekc-meta/ha-deploy-kit/commit/16f3461283fa4a18bcd97e60102825e2ed8351b8))
+
+- Sanitized HTTP notification client with status taxonomy
+  ([`22d7f21`](https://github.com/latrekc-meta/ha-deploy-kit/commit/22d7f218cf4a9b1de801e1fe967e319cda6cc9db))
+
+- Ssh/tar transport with path validation
+  ([`211ccd0`](https://github.com/latrekc-meta/ha-deploy-kit/commit/211ccd0154690791191614680a736293d65411b1))
+
+- **cli**: Make run frontend-aware so card consumers need no pipeline
+  ([`6eb8c3f`](https://github.com/latrekc-meta/ha-deploy-kit/commit/6eb8c3f154b5164c9b8ae6fee87e8fa628cc1f7d))
+
+run now publishes the changed card (frontend_run) and applies a REMOTE_CONFIG env override via
+  dataclasses.replace, in addition to deploying the changed backend and notifying. A frontend-only
+  change publishes the card but never raises a restart. The three examples collapse to
+  build_settings(root)+run(), and frontend_run drops its now-contradictory backend-pending note.
+
+- **ha**: Optional fixable flag for one-click restart Repairs card
+  ([`d2aaee2`](https://github.com/latrekc-meta/ha-deploy-kit/commit/d2aaee23ad01d87b4fe4ff564bbf917f0f7b3d05))
+
+async_register_restart_service gains a keyword-only fixable (default False), forwarded as is_fixable
+  to the raised issue so a wired fix flow is reachable. Backend-only/notification-only behavior is
+  unchanged; the frontend_card example and docs now register fixable=True.
+
+### Testing
+
+- Installed-wheel smoke test; fix py3.10 tomllib floor; ruff-format doc code blocks
+  ([`c7ef321`](https://github.com/latrekc-meta/ha-deploy-kit/commit/c7ef3214363e57e53a338b91fdb1dfa63b0cca26))
+
+- Real HTTP-to-service proof (notify + HA adapter integrate)
+  ([`13b366f`](https://github.com/latrekc-meta/ha-deploy-kit/commit/13b366f6dab46e6333f49cad452ab1249bc5d902))

ha_deploy_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 latrekc-meta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

ha_deploy_kit-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.5
+Name: ha-deploy-kit
+Version: 0.1.0
+Summary: HA-free SSH deploy / compare / notify / optional-frontend toolkit for Home Assistant custom components
+Project-URL: Homepage, https://github.com/latrekc-meta/ha-deploy-kit
+Project-URL: Repository, https://github.com/latrekc-meta/ha-deploy-kit
+Project-URL: Issues, https://github.com/latrekc-meta/ha-deploy-kit/issues
+Author: latrekc-meta
+License: MIT License
+        
+        Copyright (c) 2026 latrekc-meta
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        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.
+License-File: LICENSE
+Keywords: custom-component,deploy,home-assistant,homeassistant,lovelace,ssh
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Requires-Dist: certifi
+Requires-Dist: truststore>=0.9
+Provides-Extra: ha
+Requires-Dist: homeassistant; extra == 'ha'
+Description-Content-Type: text/markdown
+
+# ha-deploy-kit
+
+A small, reusable library for deploying a Home Assistant custom integration's
+code to a running HA host over SSH, and (optionally) wiring the HA-side restart
+notification. The core is Home-Assistant-free and standard-library only, so a
+deploy script can import it without pulling in Home Assistant; the HA adapter is
+a separate, explicitly-imported subpackage.
+
+One process can deploy several integrations without cross-talk: all per-consumer
+state lives in a frozen `DeploySettings` passed by argument — no module globals
+and no `os.environ` mutation.
+
+## What it does
+
+- Builds a content-hash inventory of your `custom_components/<domain>` tree and
+  compares it to the remote tree, deploying only the changed files.
+- Leaves remote-only files untouched (never deletes on the host).
+- Streams files over SSH with an uncompressed, path-validated tar — no backups,
+  no lock files, no rollback, no auto-restart.
+- Optionally publishes a separately-served Lovelace card.
+- Optionally raises a Home Assistant *Repairs* issue (via an HA service) telling
+  the user a restart is needed. The engine never restarts HA itself; restart is
+  opt-in and happens only when a user confirms a Repairs fix flow.
+
+## Install
+
+Published on PyPI. Pin an exact version.
+
+```sh
+pip install "ha-deploy-kit==0.1.0"
+```
+
+The HA adapter needs Home Assistant, which is an optional extra:
+
+```sh
+pip install "ha-deploy-kit[ha]==0.1.0"
+```
+
+- **Core** requires Python **3.10+** and only the standard library (plus a CA
+  trust store: `certifi`/`truststore`).
+- **The `ha` adapter** requires the Python version Home Assistant itself
+  requires; install it in the HA runtime, not in your deploy tooling.
+- **Home Assistant integrations** must pin a versioned PyPI requirement
+  (`"ha-deploy-kit==0.1.0"` in `manifest.json`), **never** a `git+…` VCS URL — HA
+  installs requirements in its own credential-less environment and treats URL
+  requirements as never-satisfied, retrying every startup.
+
+See [docs/install.md](docs/install.md) for `pyproject.toml`, HA `manifest.json`,
+and air-gapped host instructions, and [docs/releasing.md](docs/releasing.md) for
+how releases are published.
+
+## Public API
+
+| Symbol | Import | Purpose |
+| --- | --- | --- |
+| `DeploySettings` | `ha_deploy_kit` | Frozen per-consumer settings (domain, source root, remote config, optional frontend, timeouts). |
+| `FrontendAsset` | `ha_deploy_kit` | Optional served-card mapping (`source_rel`, `published_remote`). |
+| `DeployError` | `ha_deploy_kit` | Raised for recoverable, sanitized deployment errors. |
+| `run(settings, argv, ssh=None, environ=None)` | `ha_deploy_kit.cli` | Orchestrate end to end: compare, report, publish the changed card, deploy the changed backend, notify. Honors a `REMOTE_CONFIG` env override. |
+| `raise_restart_issue(base_url, token, settings)` | `ha_deploy_kit.notify` | POST to the HA restart service; returns a sanitized status string. |
+| `frontend_run(settings, plan, ssh, *, check)` | `ha_deploy_kit.frontend` | Deploy the card into the tree and/or publish the served copy. |
+| `ha.async_register_restart_service(hass, domain, ...)` | `ha_deploy_kit.ha` | Idempotently register the restart service (empty schema). Pass `fixable=True` for a one-click Repairs card (pair with the fix flow). |
+| `ha.async_raise_restart_issue(hass, domain, ...)` | `ha_deploy_kit.ha` | Raise the deduplicated, non-persistent restart Repairs issue. |
+| `ha.async_clear_restart_issue(hass, domain, ...)` | `ha_deploy_kit.ha` | Clear the restart issue. |
+| `ha.async_create_restart_fix_flow(hass, issue_id, ...)` | `ha_deploy_kit.ha` | Optional opt-in confirm-and-restart flow (restart only on submit). |
+| `ha.register_card_serving(hass, domain, lovelace_dir, card_url)` | `ha_deploy_kit.ha` | Serve the card and register it as a frontend module. |
+
+## CLI
+
+The package installs a `ha-deploy` console script. It deploys by default; pass
+`--check` (or its alias `--dry-run`) to preview without writing anything.
+
+```sh
+ha-deploy                 # deploy changed backend files, then notify
+ha-deploy --check         # compare and report only; no writes, no notify
+ha-deploy --root /path/to/your/repo
+```
+
+The source root is resolved from `--root`, then `HA_DEPLOY_SOURCE_ROOT`, then
+the current directory. The domain is read from `HA_DEPLOY_DOMAIN`, or inferred
+when the root has exactly one `custom_components/<domain>` subdirectory.
+
+### One-liner for your own deploy script
+
+`run` is fully frontend-aware, so a consumer's `deploy.py` is just settings + a
+call — no pipeline to copy. It publishes a changed card and deploys a changed
+backend; a frontend-only change publishes the card but never notifies a restart.
+
+```python
+import sys
+from pathlib import Path
+
+from ha_deploy_kit import DeploySettings, FrontendAsset
+from ha_deploy_kit.cli import run
+
+settings = DeploySettings(
+    domain="your_domain",
+    source_root=Path(__file__).resolve().parent,
+    frontend=FrontendAsset(  # omit entirely for backend-only
+        source_rel="lovelace/your-card.js",
+        published_remote="www/your_domain/your-card.js",
+    ),
+)
+raise SystemExit(run(settings, sys.argv[1:]))
+```
+
+`TARGET`/`HA_BASE_URL`/`HA_TOKEN` and an optional `REMOTE_CONFIG` override come
+from `.env` or the process environment; `run` applies `REMOTE_CONFIG` for you.
+
+See [docs/configuration.md](docs/configuration.md) for settings and `.env`, and
+[docs/adopting.md](docs/adopting.md) for a step-by-step adoption guide.
+
+## Design notes
+
+This library deliberately differs from typical hand-rolled HA deploy scripts.
+Each choice below is intentional:
+
+- **No positional target and no `--restart` / `--no-restart` / `--card-only`
+  flags.** The target comes from the environment; the engine never restarts HA,
+  so there is no restart flag to pass.
+- **The engine never executes a restart.** It can only raise a Repairs issue;
+  the actual restart is opt-in behind a user-confirmed fix flow.
+- **A frontend-only change never notifies a backend restart.** Backend and
+  frontend are separate concerns.
+- **Structured remote inventory.** The remote probe returns an explicit
+  four-field result (hashes, stale files, a missing-tree flag, published hash)
+  rather than guessing from text.
+- **Environment precedence is explicit.** Process environment overrides `.env`;
+  the library never mutates `os.environ`.
+- **Path validation.** Tar members are rejected if absolute, containing `..`,
+  NUL, or newlines, or escaping the component directory.
+- **No backups, lock files, rollback, or auto-restart**, and tokens, raw bodies,
+  and secret-bearing errors are never printed. TLS and SSH verification are
+  never weakened.
+- **Real CA trust store for the notification.** The HTTPS call to Home Assistant
+  verifies against the OS trust store via `truststore` (matching `curl`), falling
+  back to `certifi` then the stdlib default — all strictly verifying
+  (`CERT_REQUIRED` + hostname check). This avoids misreporting a valid cert as
+  `tls-error` on platforms whose default context has no usable CA store (macOS,
+  python.org, fresh venvs); `tls-error` is reserved for genuine failures.
+
+## Releases
+
+Releases are automated: every merge to `main` runs semantic-release, which picks
+the next version from the [Conventional Commit] messages (`fix:` → patch,
+`feat:` → minor, `feat!:`/`BREAKING CHANGE:` → major; `docs:`/`chore:`/`test:`
+publish nothing) and publishes to PyPI via Trusted Publishing. Write PR
+titles/commits in that form. See [docs/releasing.md](docs/releasing.md) for the
+one-time setup and the manual fallback.
+
+[Conventional Commit]: https://www.conventionalcommits.org/