yeelight-home 0.1.0 → 0.1.2

package/CONFIG.md

@@ -1,63 +1,225 @@
 # Configuration
 
+`yeelight-home` separates secret credentials from ordinary profile metadata.
+
+- Tokens are stored in the system credential store when available, or in a protected local fallback.
+- Profile metadata stores non-secret values: profile name, region, selected home, and QR device identity.
+- User-facing commands do not require a client id. When QR login returns a service client id, the Runtime may keep it internally for API compatibility.
+
 ## Precedence
 
 Runtime configuration is resolved in this order:
 
-1. Command flags: `--profile`, `--region`, `--client-id`, `--house-id`
-2. Environment variables: `YEELIGHT_HOME_PROFILE`, `YEELIGHT_CLOUD_REGION`, `YEELIGHT_HOME_CLIENT_ID`, `YEELIGHT_HOME_HOUSE_ID`, `YEELIGHT_HOME_ACCESS_TOKEN`
-3. Active profile, profile metadata, and credential store
-4. Defaults: profile `default`, region `dev`
+1. Command flags.
+2. Environment variables.
+3. Active profile metadata and credential store.
+4. Defaults.
+
+Defaults:
+
+| Setting | Default |
+| --- | --- |
+| Profile | `default` |
+| Region | `cn` |
+| Home | unset; optional until a house-scoped operation needs a default home |
+
+## Regions
 
-`YEELIGHT_API_BASE_URL` is a developer override for local testing. Do not expose it in Skill responses or user-facing automation.
+Supported region values:
+
+| Region | Meaning |
+| --- | --- |
+| `cn` | China cloud, default. |
+| `sg` | Singapore cloud. |
+| `us` | United States cloud. |
+| `eu` | Europe cloud. |
+| `dev` | Development cloud. Use only for internal validation. |
+
+Examples:
+
+```sh
+yeelight-home doctor --json
+yeelight-home doctor --json --region sg
+YEELIGHT_CLOUD_REGION=eu yeelight-home home list --json
+```
 
 ## Profiles
 
+Profiles let one machine keep separate local metadata for different accounts, homes, or regions.
+
 ```sh
 yeelight-home profile list --json
 yeelight-home profile show --profile default --json
-yeelight-home profile use --profile family --region cn --client-id <client-id> --house-id <house-id>
+yeelight-home profile use --profile family --region cn
+yeelight-home profile use --profile family --region cn --house-id <house-id>
 yeelight-home profile delete --profile family
 ```
 
-`profile use` saves metadata and sets the active local profile. Profile metadata is stored in `~/.yeelight-home/config/profiles.json` by default. It contains active profile, region, client id, house id, and QR device metadata. It must not contain access tokens.
+Selection rules:
+
+- `--profile <name>` applies to one command.
+- `YEELIGHT_HOME_PROFILE=<name>` applies to one process and overrides the active profile.
+- `profile use --profile <name>` persists the active profile for later commands.
+- Without any of the above, `default` is used.
 
-## Credentials
+## Authentication
 
-Preferred login:
+### QR Login
 
 ```sh
-yeelight-home auth login --qr --region cn --profile default
+yeelight-home auth login --qr --profile default
+yeelight-home auth login --qr --profile default --region sg
+yeelight-home auth login --qr --profile default --qr-png /tmp/yeelight-login.png
 ```
 
-Manual token import:
+`--region` defaults to `cn`. `--house-id` is optional and can be passed when a specific home should be carried into the QR login payload.
+
+### Manual Token Import
 
 ```sh
-yeelight-home auth token set --profile default --token <access-token> --region cn --client-id <client-id> --house-id <house-id>
+yeelight-home auth token set --profile default --token <access-token> --region cn
+yeelight-home auth token set --profile default --token <access-token> --region cn --house-id <house-id>
+yeelight-home auth token delete --profile default
 ```
 
-Status:
+Use token import only outside AI chat. Tokens are redacted from normal output and are not written to profile metadata.
+Token-only setup is valid. Omit `--house-id` when you only need account-level commands or will choose a default home later.
+
+### Status
 
 ```sh
 yeelight-home auth status --json
+yeelight-home auth status --json --profile family
 ```
 
-Tokens are loaded from `YEELIGHT_HOME_ACCESS_TOKEN` first, then from the local credential store. Status and doctor output only report whether a token is present.
+The status output includes token presence and source, not token values.
 
 ## Home Selection
 
 ```sh
 yeelight-home home list --json
-yeelight-home home select --house-id <house-id> --profile default
+yeelight-home home list --json --region eu
+yeelight-home home select --house-id <house-id>
+yeelight-home home select --profile family --house-id <house-id> --region cn
+```
+
+`home select` writes the selected home id into profile metadata. A process can temporarily override it with `--house-id` or `YEELIGHT_HOME_HOUSE_ID`.
+The selected home is a default context, not an authentication requirement. Account-level commands such as `auth status`, `doctor`, `api smoke`, `home list`, home summary/search, and account info work with token-only profiles. Device, room, area, group, scene, automation, gateway, favorite, lighting, and other house-scoped operations require `houseId` at the request, environment, or profile layer.
+
+## Config Commands
+
+```sh
+yeelight-home config get --json
+yeelight-home config set --profile family --region cn --house-id <house-id> --json
+yeelight-home config unset --profile family --house-id --json
+```
+
+`config set` and `config unset` update non-secret profile metadata only.
+
+Supported metadata flags:
+
+| Flag | Purpose |
+| --- | --- |
+| `--profile <name>` | Selects profile. |
+| `--region <region>` | Stores region for the profile. |
+| `--house-id <id>` | Stores selected home for the profile; optional until house-scoped operations need it. |
+| `--qr-device <mac>` | Advanced: stores a stable QR device identity for QR login. |
+
+## Environment Variables
+
+| Variable | Scope | Notes |
+| --- | --- | --- |
+| `YEELIGHT_HOME_BIN` | Skill wrapper lookup | Absolute CLI path used by Skills. |
+| `YEELIGHT_HOME_PROFILE` | Profile | Overrides active profile for this process. |
+| `YEELIGHT_CLOUD_REGION` | Region | Overrides profile region for this process. |
+| `YEELIGHT_HOME_HOUSE_ID` | Home | Overrides selected home for this process. |
+| `YEELIGHT_HOME_ACCESS_TOKEN` | Credential | Temporary token for local smoke tests or CI. |
+| `YEELIGHT_HOME_DIR` | Storage | Overrides Runtime home directory. |
+| `YEELIGHT_API_BASE_URL` | Development | Overrides API base URL; do not expose in Skills. |
+
+`YEELIGHT_HOME_ACCESS_TOKEN` has higher priority than the credential store, but it is never persisted by `config` commands.
+
+## Storage Paths
+
+Default paths are platform-specific:
+
+| OS | Runtime home |
+| --- | --- |
+| macOS | `~/Library/Application Support/yeelight-home` plus cache/data under standard user directories |
+| Linux | `~/.yeelight-home` or XDG-compatible directories depending on environment |
+| Windows | `%LOCALAPPDATA%\YeelightHome` |
+
+Run `yeelight-home doctor --json` to see the exact paths on the current machine.
+
+## Skill Integration
+
+Skill packages call:
+
+```sh
+yeelight-home invoke --stdin
+```
+
+Skill wrappers find the CLI in this order:
+
+1. `YEELIGHT_HOME_BIN`
+2. Development-only source checkout binary
+3. `yeelight-home` on `PATH`
+
+After installation:
+
+```sh
+yeelight-home auth status --json
+yeelight-home auth login --qr
+yeelight-home home list --json
+# Optional default home for house-scoped operations:
+yeelight-home home select --house-id <house-id>
+```
+
+## Troubleshooting
+
+### Runtime missing
+
+Install the CLI from GitHub Releases or a package manager, then restart the host application if it inherited an old `PATH`.
+
+### Auth required
+
+Run:
+
+```sh
+yeelight-home auth status --json
+yeelight-home auth login --qr
+```
+
+### Wrong region
+
+Use a one-time override:
+
+```sh
+yeelight-home home list --json --region sg
+```
+
+Or persist it:
+
+```sh
+yeelight-home profile use --profile default --region sg
+```
+
+### Wrong home
+
+List homes and select the correct one:
+Only do this when the failed operation is house-scoped or when you want to change the default home.
+
+```sh
+yeelight-home home list --json
+yeelight-home home select --house-id <house-id>
 ```
 
-`home select` changes only local profile metadata. It does not modify Yeelight cloud home data.
+### Need a diagnostic bundle
 
-## Diagnostics
+Run:
 
 ```sh
 yeelight-home doctor --json
-yeelight-home api smoke --json --region cn --profile default
 ```
 
-`doctor` checks local installation, paths, profile, region, token presence, and Runtime storage status. `api smoke` performs read-only cloud checks when credentials are configured.
+Share only redacted diagnostic output. Do not share token files or credential store exports.

package/DISTRIBUTION.md

@@ -1,25 +1,145 @@
 # Distribution
 
-`yeelight-home` is distributed as a standalone CLI. The public source and release repository is `Yeelight/yeelight-home`; Skill packages should depend on the installed CLI through `YEELIGHT_HOME_BIN` or `PATH`.
+`yeelight-home` is distributed as a standalone CLI. Skill packages should not carry Runtime binaries. They depend on `YEELIGHT_HOME_BIN` or `yeelight-home` on `PATH`.
 
-## Channels
+## Channel Model
 
-| Channel | Status | User install path |
+| Channel | GoReleaser role | User install path |
 | --- | --- | --- |
-| GitHub Releases | Published | `curl -fsSL https://github.com/yeelight/yeelight-home/releases/latest/download/install.sh \| sh` |
-| Homebrew | Published | `brew install Yeelight/tap/yeelight-home` |
-| Scoop | Published | `scoop bucket add yeelight https://github.com/Yeelight/scoop-bucket && scoop install yeelight-home` |
-| Debian package | Published | Download `yeelight-home_0.1.0_amd64.deb` or `yeelight-home_0.1.0_arm64.deb` from GitHub Releases |
-| Winget | Submitted | `winget install Yeelight.yeelight-home` after microsoft/winget-pkgs PR 392555 is merged |
-| npm | Published | `npm install -g yeelight-home` |
+| GitHub Releases | Primary release target for archives, installers, checksums, SBOMs, packages, and metadata. | `curl -fsSL https://github.com/Yeelight/yeelight-home/releases/latest/download/install.sh \| sh` |
+| Homebrew tap | Updates cask metadata in `Yeelight/homebrew-tap`. | `brew install Yeelight/tap/yeelight-home` |
+| Scoop bucket | Updates manifest metadata in `Yeelight/scoop-bucket`. | `scoop bucket add yeelight https://github.com/Yeelight/scoop-bucket && scoop install yeelight-home` |
+| npm wrapper | Publishes the launcher package after GoReleaser assets exist. | `npm install -g yeelight-home` |
+| Linux packages | Builds `.deb`, `.rpm`, `.apk`, and Arch package artifacts through nFPM. | Download package assets from GitHub Releases. |
+| Winget | Generates or supports the Microsoft registry submission path. | `winget install Yeelight.yeelight-home` after registry acceptance. |
+| AUR | Publishes `yeelight-home-bin` only when AUR SSH is configured. | `yay -S yeelight-home-bin` after publication. |
+| Snap | Builds/publishes only when Snapcraft credentials and store review are ready. | `sudo snap install yeelight-home` after store visibility. |
+| Docker GHCR | Publishes multi-arch images when registry credentials are available. | `docker run --rm ghcr.io/yeelight/yeelight-home:latest version` |
+| Docker Hub | Publishes multi-arch images when Docker Hub credentials are available. | `docker run --rm yeelight/yeelight-home:latest version` |
+| pkg.go.dev | Indexes public `v*` module tags. | `https://pkg.go.dev/github.com/yeelight/yeelight-home` |
 
 ## Repository Layout Policy
 
-- Keep `Yeelight/yeelight-home` as the public Runtime source and release repository.
-- Keep `Yeelight/homebrew-tap` as a shared Homebrew tap for all Yeelight formulas. This is conventional because GitHub taps use the `homebrew-` prefix for the short `brew tap Yeelight/tap` form.
-- Scoop does not require a Yeelight organization repository or a dedicated repository. It only needs a Git bucket repository containing JSON manifests. `Yeelight/scoop-bucket` is valid and already published; if repository count becomes a problem, future Scoop manifests can move into a consolidated distribution repository, but the existing bucket should remain as a compatibility pointer.
-- Winget does not require a Yeelight repository. Official publication happens through `microsoft/winget-pkgs`; any personal fork is only a PR workspace.
-- npm does not require a GitHub repository. It requires an npm account or automation token with permission to publish `yeelight-home` or the chosen scoped package.
+- `Yeelight/yeelight-home` is the public Runtime source and release repository.
+- The monorepo remains the source of truth. Do not put a nested `.git` repository under `yeelight-smart-home/runtime`.
+- Runtime-only source is exported by `scripts/export-runtime-public.sh`.
+- `Yeelight/homebrew-tap` is a conventional shared Homebrew tap. It is not a runtime source repo, should stay small, and should contain only package manager metadata generated or reviewed for release.
+- `Yeelight/scoop-bucket` is a conventional shared Scoop bucket. Scoop can live in one consolidated Yeelight bucket repository; it does not need one repository per app.
+- Winget does not need a Yeelight organization repository. Publication happens through `microsoft/winget-pkgs`; any fork is only a PR workspace.
+- AUR does require an AUR Git repository per package, but that repository is not in the GitHub organization.
+- Snap is managed through Snapcraft, not a GitHub distribution repo.
+- Docker Hub and GHCR are image registries, not source repositories.
+
+## GoReleaser Decision
+
+Use GoReleaser for the public runtime release pipeline.
+
+Reasoning:
+
+- GoReleaser standardizes cross-platform Go builds, archives, checksums, Linux packages, Homebrew, Scoop, Docker images, SBOMs, AUR, Snap, and Winget workflows.
+- It replaces the old monorepo hand-written cross-compile/package/release workflow. The monorepo now mirrors source only; public release builds happen in `Yeelight/yeelight-home`.
+- It aligns with Go CLI user expectations and improves discoverability through package managers.
+- It still does not remove external gates: Winget review, AUR account/SSH, Snapcraft credentials, Docker Hub credentials, and Homebrew/Scoop write tokens are still required.
+- The public workflow automatically skips channels whose secrets are not configured, so optional channels do not block core GitHub Release assets, checksums, install scripts, npm wrapper assets and Linux package assets.
+- GoReleaser v2.16 marks Homebrew formula generation as deprecated. New automation uses Homebrew Casks; the existing Formula entry can remain as a compatibility install path if already published.
+
+Scope:
+
+- Use GoReleaser in the public `Yeelight/yeelight-home` repository.
+- Keep the monorepo export workflow responsible only for validating and pushing runtime-only public repo content.
+- Use standard public runtime tags such as `v0.1.1` for Go ecosystem compatibility.
+- Keep previous `yeelight-home-v*` release tags installable where they already exist, but do not use that prefix for future public runtime tags.
+
+## Tap And Bucket Retention
+
+Keep `Yeelight/homebrew-tap` and `Yeelight/scoop-bucket`.
+
+They remain useful and standard even after GoReleaser adoption:
+
+- Homebrew and Scoop install flows require a tap or bucket repository unless the package is accepted into broader upstream registries.
+- GoReleaser updates those repositories automatically; maintainers should not hand-edit generated version URLs and checksums except for emergency repair.
+- A shared `homebrew-tap` and `scoop-bucket` is cleaner than one repository per CLI. These repositories should contain only package metadata for Yeelight public tools.
+- They must not contain Runtime source, Skill assets, raw docs, credentials, generated release archives, or development governance material.
+
+Do not create extra Yeelight organization repositories for Winget, Snap, Docker, or pkg.go.dev. Those channels use external registries or the existing public Runtime repository.
+
+## Release Automation Targets
+
+GoReleaser configuration lives at:
+
+```text
+runtime/.goreleaser.yaml
+```
+
+The exported public repo includes:
+
+```text
+.goreleaser.yaml
+Dockerfile
+README.md
+INSTALL.md
+CONFIG.md
+DISTRIBUTION.md
+RELEASING.md
+cmd/
+internal/
+npm/
+scripts/
+go.mod
+go.sum
+```
+
+Target artifacts:
+
+- Archives:
+  - `darwin/amd64`
+  - `darwin/arm64`
+  - `linux/amd64`
+  - `linux/arm64`
+  - `linux/arm/v7`
+  - `windows/amd64`
+  - `windows/arm64`
+- Checksums:
+  - `checksums.txt`
+- Linux packages:
+  - `.deb`
+  - `.rpm`
+  - `.apk`
+  - Arch package artifact
+- Package-manager manifests:
+  - Homebrew cask in `Yeelight/homebrew-tap`
+  - Scoop manifest in `Yeelight/scoop-bucket`
+  - Winget manifest or PR flow once enabled
+  - AUR `yeelight-home-bin` once AUR SSH is configured
+  - Snap package once Snapcraft is configured
+- Container images:
+  - `ghcr.io/yeelight/yeelight-home`
+  - `yeelight/yeelight-home`
+
+## Required Release Settings
+
+GitHub Actions provides `GITHUB_TOKEN` automatically for GitHub Releases and GHCR publishing. Do not create a repository secret named `GITHUB_TOKEN`.
+
+| Secret | Purpose |
+| --- | --- |
+| `HOMEBREW_TAP_GITHUB_TOKEN` | Push Homebrew cask to `Yeelight/homebrew-tap`. |
+| `SCOOP_BUCKET_GITHUB_TOKEN` | Push Scoop manifest to `Yeelight/scoop-bucket`. |
+| `NPM_TOKEN` | Publish npm wrapper package. |
+| `DOCKERHUB_USERNAME` | Docker Hub login. |
+| `DOCKERHUB_TOKEN` | Docker Hub publish token. |
+| `AUR_KEY` | AUR SSH private key for `yeelight-home-bin`. |
+| `SNAPCRAFT_STORE_CREDENTIALS` | Snap store publish credentials. |
+| `WINGET_GITHUB_TOKEN` | Winget manifest PR token. |
+
+| Repository Variable | Purpose |
+| --- | --- |
+| `WINGET_REPOSITORY_OWNER` | Winget PR workspace fork owner. |
+| `WINGET_REPOSITORY_NAME` | Winget PR workspace fork name. |
+| `WINGET_REPOSITORY_BRANCH` | Optional Winget PR branch. Defaults to a release-specific branch. |
+| `AUR_GIT_URL` | Optional AUR Git URL override. Defaults to `ssh://aur@aur.archlinux.org/yeelight-home-bin.git`. |
+
+Only configure settings for channels that are ready to publish.
+Without Winget token and PR workspace variables, the public release workflow skips Winget and still publishes core GitHub Release artifacts.
 
 ## npm Package Model
 
@@ -33,6 +153,29 @@ The npm package is a thin installer and launcher:
 Environment overrides:
 
 - `YEELIGHT_HOME_REPO=owner/repo`
-- `YEELIGHT_HOME_VERSION=yeelight-home-v0.1.0` or `latest`
+- `YEELIGHT_HOME_VERSION=v0.1.1` or `latest`
 - `YEELIGHT_HOME_NPM_CACHE_DIR=/custom/cache`
 - `YEELIGHT_HOME_NPM_SKIP_INSTALL=1`
+
+## Skill Distribution Contract
+
+Skill packages include only:
+
+- Skill instructions.
+- Skill references and schemas.
+- Wrapper scripts that call `yeelight-home invoke --stdin`.
+
+Skill packages must not include:
+
+- Runtime source.
+- Runtime binaries.
+- Installer scripts.
+- Development docs.
+- Raw API docs or compatibility-service references.
+
+When Runtime is missing, the Skill should guide users to install `yeelight-home` from a public channel and then run:
+
+```sh
+yeelight-home auth status --json
+yeelight-home auth login --qr
+```

package/INSTALL.md

@@ -1,80 +1,247 @@
 # Installation
 
+This document is for users installing the standalone `yeelight-home` CLI.
+
+## Verify An Existing Install
+
+```sh
+yeelight-home version
+yeelight-home doctor --json
+```
+
+After installing, authenticate locally:
+
+```sh
+yeelight-home auth status --json
+yeelight-home auth login --qr
+```
+
+The default region is `cn`. Use `--region sg`, `--region us`, or `--region eu` when needed.
+
 ## GitHub Releases
 
+GitHub Releases are the canonical fallback channel for all platforms.
+
 macOS and Linux:
 
 ```sh
-curl -fsSL https://github.com/yeelight/yeelight-home/releases/latest/download/install.sh | sh
+curl -fsSL https://github.com/Yeelight/yeelight-home/releases/latest/download/install.sh | sh
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://github.com/yeelight/yeelight-home/releases/latest/download/install.ps1 -UseB | iex
+iwr https://github.com/Yeelight/yeelight-home/releases/latest/download/install.ps1 -UseB | iex
 ```
 
-Override the install source when testing a fork:
+Installer overrides:
 
 ```sh
-YEELIGHT_HOME_REPO=owner/repo YEELIGHT_HOME_VERSION=yeelight-home-v1.0.0 sh install.sh
+YEELIGHT_HOME_REPO=Yeelight/yeelight-home \
+YEELIGHT_HOME_VERSION=v0.1.1 \
+YEELIGHT_HOME_INSTALL_DIR="$HOME/.local/bin" \
+sh install.sh
 ```
 
 PowerShell:
 
 ```powershell
-$env:YEELIGHT_HOME_REPO="owner/repo"
-$env:YEELIGHT_HOME_VERSION="yeelight-home-v1.0.0"
+$env:YEELIGHT_HOME_REPO="Yeelight/yeelight-home"
+$env:YEELIGHT_HOME_VERSION="v0.1.1"
+$env:YEELIGHT_HOME_INSTALL_DIR="$env:LOCALAPPDATA\Programs\YeelightHome\bin"
 .\install.ps1
 ```
 
-## Package Managers
+The installers verify `checksums.txt` before copying the binary.
 
-Homebrew:
+## macOS And Linux: Homebrew
 
 ```sh
 brew install Yeelight/tap/yeelight-home
 ```
 
-Scoop:
+Upgrade:
+
+```sh
+brew update
+brew upgrade yeelight-home
+```
+
+Uninstall:
+
+```sh
+brew uninstall yeelight-home
+```
+
+## Windows: Scoop
 
 ```powershell
 scoop bucket add yeelight https://github.com/Yeelight/scoop-bucket
 scoop install yeelight-home
 ```
 
-Debian/Ubuntu:
+Upgrade:
 
-```sh
-curl -LO https://github.com/Yeelight/yeelight-home/releases/download/yeelight-home-v0.1.0/yeelight-home_0.1.0_amd64.deb
-sudo apt install ./yeelight-home_0.1.0_amd64.deb
+```powershell
+scoop update yeelight-home
 ```
 
-Winget:
+Uninstall:
 
-- Submitted for review: https://github.com/microsoft/winget-pkgs/pull/392555
-- After merge: `winget install Yeelight.yeelight-home`
+```powershell
+scoop uninstall yeelight-home
+```
 
-npm:
+## Windows: Winget
+
+Winget is published through `microsoft/winget-pkgs`.
+
+After the Yeelight package is accepted:
+
+```powershell
+winget install Yeelight.yeelight-home
+winget upgrade Yeelight.yeelight-home
+winget uninstall Yeelight.yeelight-home
+```
+
+If Winget cannot find the package yet, use GitHub Releases, Scoop, Homebrew on WSL, or npm.
+
+## npm Wrapper
+
+The npm package is a thin launcher. It downloads the matching GitHub Release binary on install or first run and verifies the checksum.
 
 ```sh
 npm install -g yeelight-home
+yeelight-home version
+```
+
+Environment overrides:
+
+| Variable | Purpose |
+| --- | --- |
+| `YEELIGHT_HOME_REPO` | Release repository, default `Yeelight/yeelight-home`. |
+| `YEELIGHT_HOME_VERSION` | Release tag or `latest`. |
+| `YEELIGHT_HOME_NPM_CACHE_DIR` | Binary cache directory. |
+| `YEELIGHT_HOME_NPM_SKIP_INSTALL=1` | Skip binary download during npm install. |
+
+## Linux Packages
+
+GoReleaser produces Linux packages through nFPM:
+
+- Debian/Ubuntu: `.deb`
+- Fedora/RHEL/openSUSE: `.rpm`
+- Alpine: `.apk`
+- Arch package artifact
+
+Debian/Ubuntu example:
+
+```sh
+curl -LO https://github.com/Yeelight/yeelight-home/releases/download/v0.1.1/yeelight-home_0.1.1_linux_amd64.deb
+sudo apt install ./yeelight-home_0.1.1_linux_amd64.deb
 ```
 
-## Verify
+RPM example:
 
 ```sh
-yeelight-home version
-yeelight-home doctor --json
+curl -LO https://github.com/Yeelight/yeelight-home/releases/download/v0.1.1/yeelight-home_0.1.1_linux_amd64.rpm
+sudo rpm -i ./yeelight-home_0.1.1_linux_amd64.rpm
 ```
 
+Package filenames can vary by GoReleaser version. Check the release asset list when installing a pinned version.
+
+## Arch Linux AUR
+
+The planned package name is:
+
+```sh
+yay -S yeelight-home-bin
+```
+
+AUR publication requires an AUR package repository and deploy key. Until that is enabled, install from GitHub Releases or use the generated Arch package artifact from the release.
+
+## Snap
+
+The planned Snap name is:
+
+```sh
+sudo snap install yeelight-home
+```
+
+Snap publication requires Snapcraft credentials and store review. Until the Snap is visible in the store, install from GitHub Releases, Homebrew, npm, or Linux package assets.
+
+## Docker And Container Images
+
+Container images are intended for NAS, server, Raspberry Pi, and scheduled automation environments.
+
+GHCR:
+
+```sh
+docker run --rm ghcr.io/yeelight/yeelight-home:latest version
+```
+
+Docker Hub:
+
+```sh
+docker run --rm yeelight/yeelight-home:latest version
+```
+
+Persist local config and credentials:
+
+```sh
+docker run --rm -it \
+  -v "$HOME/.yeelight-home:/home/nonroot/.yeelight-home" \
+  ghcr.io/yeelight/yeelight-home:latest doctor --json
+```
+
+Supported image platforms:
+
+- `linux/amd64`
+- `linux/arm64`
+- `linux/arm/v7`
+
+## Go Ecosystem Discovery
+
+For Go tooling and pkg.go.dev discovery, the public repository should use standard semantic tags such as `v0.1.1` and module path `github.com/yeelight/yeelight-home`.
+
+Once a tag exists publicly:
+
+```sh
+GOPROXY=https://proxy.golang.org go list -m github.com/yeelight/yeelight-home@v0.1.1
+```
+
+pkg.go.dev indexes the module from the public repository and tag.
+
+## PATH And Skill Hosts
+
+Most package managers put `yeelight-home` on `PATH`. If a Skill host cannot find it:
+
+```sh
+export YEELIGHT_HOME_BIN="$(command -v yeelight-home)"
+```
+
+Windows PowerShell:
+
+```powershell
+$env:YEELIGHT_HOME_BIN=(Get-Command yeelight-home).Source
+```
+
+Restart the host application after changing user PATH.
+
 ## Uninstall
 
-Remove the binary from the install directory and delete local Runtime data only when you intend to remove credentials and local preferences:
+Remove the binary through the same installer or package manager that installed it.
+
+Manual GitHub installer cleanup:
 
 ```sh
 rm -f /usr/local/bin/yeelight-home
+rm -f "$HOME/.local/bin/yeelight-home"
+```
+
+Local Runtime data and credentials are separate. Delete them only when you intend to remove local preferences and credentials:
+
+```sh
 rm -rf ~/.yeelight-home
 ```
 
-On Windows, remove `%LOCALAPPDATA%\Programs\YeelightHome\bin\yeelight-home.exe` and remove that directory from the user `Path` if it was added by the installer.
+On Windows, remove `%LOCALAPPDATA%\YeelightHome` after deleting the package or binary.

package/README.md

@@ -1,19 +1,32 @@
 # yeelight-home
 
-`yeelight-home` is the local Runtime CLI for Yeelight smart-home Skills. It keeps credentials on the user's machine, resolves semantic Skill requests, calls Yeelight cloud APIs directly, and returns redacted structured results.
+`yeelight-home` is the standalone local Runtime CLI for Yeelight smart-home Skills and automation scripts. It runs on the user's machine, keeps credentials local, resolves semantic smart-home requests, calls Yeelight cloud APIs directly, and returns redacted structured results.
+
+The Runtime is intentionally not bundled inside Skills. A Skill finds `yeelight-home` through `YEELIGHT_HOME_BIN` or `PATH` and sends one JSON request to `yeelight-home invoke --stdin`.
+
+## Features
+
+- Direct Yeelight cloud API access for homes, rooms, areas, devices, groups, gateways, scenes, automations, diagnostics, lighting design, memory, and personalization.
+- Guarded write model for persistent changes: risky changes create a local pending plan first, and `plan.commit` executes only a stored `planId`.
+- Local credential handling: access tokens are stored in the system credential store when available, with a protected local fallback.
+- Multiple profiles for different accounts, regions, or homes.
+- Region-aware cloud endpoints with default region `cn`.
+- Redacted JSON output for Skill hosts and diagnostics.
+- Cross-platform distribution through the GoReleaser-backed GitHub Releases pipeline, with Homebrew, Scoop, npm, Linux packages, and optional container/package-manager channels.
+- Optional Docker/GHCR and Docker Hub images for NAS, server, and scheduled automation use.
 
 ## Install
 
-Install from the public runtime release repository:
+macOS and Linux:
 
 ```sh
-curl -fsSL https://github.com/yeelight/yeelight-home/releases/latest/download/install.sh | sh
+curl -fsSL https://github.com/Yeelight/yeelight-home/releases/latest/download/install.sh | sh
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://github.com/yeelight/yeelight-home/releases/latest/download/install.ps1 -UseB | iex
+iwr https://github.com/Yeelight/yeelight-home/releases/latest/download/install.ps1 -UseB | iex
 ```
 
 Homebrew:
@@ -29,47 +42,194 @@ scoop bucket add yeelight https://github.com/Yeelight/scoop-bucket
 scoop install yeelight-home
 ```
 
-Debian/Ubuntu users can download the `yeelight-home_0.1.0_amd64.deb` or `yeelight-home_0.1.0_arm64.deb` asset from the GitHub Release and install it with `apt` or `dpkg`.
-
-Npm:
+npm wrapper:
 
 ```sh
 npm install -g yeelight-home
 ```
 
-Winget publication is submitted for review at https://github.com/microsoft/winget-pkgs/pull/392555. Until it is merged, use GitHub Releases, Homebrew, Scoop, or set `YEELIGHT_HOME_BIN` to an absolute `yeelight-home` executable path.
+Debian, Ubuntu, Fedora, Arch, AUR, Snap, Docker, GHCR, Docker Hub, and Winget channel details are maintained in [INSTALL.md](INSTALL.md) and [DISTRIBUTION.md](DISTRIBUTION.md).
 
 ## Quick Start
 
 ```sh
 yeelight-home version
+yeelight-home doctor --json
 yeelight-home auth status --json
-yeelight-home auth login --qr --region dev
+yeelight-home auth login --qr
 yeelight-home home list --json
+# Optional: choose a default home before house-scoped device, room, scene, or automation operations.
 yeelight-home home select --house-id <house-id>
-yeelight-home doctor --json
 ```
 
+The default region is `cn`. Pass `--region sg`, `--region us`, or `--region eu` when your Yeelight account belongs to another cloud region.
+
 For non-interactive local setup, import a token outside chat:
 
 ```sh
-yeelight-home auth token set --token <access-token> --region cn --client-id <client-id> --house-id <house-id>
+yeelight-home auth token set --token <access-token> --region cn
 ```
 
-Do not paste tokens into AI chat. The CLI stores tokens in the system credential store when available, and otherwise in a protected local credential fallback under the Runtime config directory.
+Token-only setup is valid. `houseId` is optional profile metadata for the default home. Account-level commands such as `auth status`, `doctor`, `api smoke`, `home list`, `home.summary`, `home.search`, and `account.info` do not require it. House-scoped operations such as device, room, scene, group, gateway, favorite, and automation actions require a `houseId` from the request, `YEELIGHT_HOME_HOUSE_ID`, or the selected profile.
 
-## Skill Integration
+Do not paste tokens into AI chat. The CLI stores tokens locally and never prints token values in normal status or doctor output.
+
+## Configuration Model
+
+Runtime settings are resolved in this order:
+
+1. Command flags.
+2. Environment variables.
+3. Active profile metadata and credential store.
+4. Defaults.
+
+Default values:
+
+- Profile: `default`
+- Region: `cn`
+- Home: unset until selected, and only required for house-scoped operations
+
+Common environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `YEELIGHT_HOME_BIN` | Absolute path used by Skills to find the CLI. |
+| `YEELIGHT_HOME_PROFILE` | Selects a profile for this process. |
+| `YEELIGHT_CLOUD_REGION` | Overrides region for this process: `cn`, `sg`, `us`, `eu`, or `dev` for development. |
+| `YEELIGHT_HOME_HOUSE_ID` | Temporarily overrides selected home. |
+| `YEELIGHT_HOME_ACCESS_TOKEN` | Temporary token for local smoke tests or CI; not written to profile metadata. |
+| `YEELIGHT_HOME_DIR` | Overrides Runtime home directory. |
+| `YEELIGHT_API_BASE_URL` | Developer-only API base URL override. Do not use in Skill prompts or user automation. |
+
+See [CONFIG.md](CONFIG.md) for full command and precedence details.
+
+## Command Reference
+
+### `doctor`
+
+```sh
+yeelight-home doctor --json [--profile <name>] [--region <region>] [--house-id <id>]
+```
+
+Reports installation, config directories, selected profile, selected region, selected home, token presence, and warnings. Token values are never printed.
+The selected home may be empty; that is healthy for token-only account-level use.
+
+### `auth status`
+
+```sh
+yeelight-home auth status --json [--profile <name>]
+```
+
+Reports whether the selected profile has a usable local credential.
 
-Skills should call only:
+### `auth login`
+
+```sh
+yeelight-home auth login --qr [--profile <name>] [--region <region>] [--house-id <id>] [--json] [--qr-png <path>]
+```
+
+Starts the local QR login flow. If `--region` is omitted, `cn` is used.
+`--house-id` is optional and should be used only when a home context must be carried into the login payload.
+
+### `auth token set`
+
+```sh
+yeelight-home auth token set --token <access-token> [--profile <name>] [--region <region>] [--house-id <id>] [--json]
+```
+
+Imports a token into the local credential store. It never writes the token into the profile metadata file.
+`--house-id` is optional. Omit it when you only need account-level commands or plan to select a home later.
+
+### `profile`
+
+```sh
+yeelight-home profile list [--json]
+yeelight-home profile show [--profile <name>] [--json]
+yeelight-home profile use --profile <name> [--region <region>] [--house-id <id>] [--json]
+yeelight-home profile delete --profile <name> [--json]
+```
+
+Profiles isolate account metadata and selected home. Use `YEELIGHT_HOME_PROFILE` or `--profile` for temporary selection.
+The selected home can be empty in a profile.
+
+### `config`
+
+```sh
+yeelight-home config get [--profile <name>] [--region <region>] [--house-id <id>] [--json]
+yeelight-home config set [--profile <name>] [--region <region>] [--house-id <id>] [--qr-device <mac>] [--json]
+yeelight-home config unset [--profile <name>] [--region] [--house-id] [--qr-device] [--json]
+```
+
+`config` changes non-secret profile metadata only.
+
+### `home`
+
+```sh
+yeelight-home home list [--profile <name>] [--region <region>] [--json]
+yeelight-home home select --house-id <id> [--profile <name>] [--region <region>] [--json]
+```
+
+Lists homes available to the selected credential and stores the default home for later Skill calls.
+Run `home select` only when you want future house-scoped commands to use a default home. You can also pass a one-time `--house-id` or `YEELIGHT_HOME_HOUSE_ID`.
+
+### `invoke`
 
 ```sh
 yeelight-home invoke --stdin
 ```
 
-The Yeelight Smart Home Skill wrapper resolves the Runtime in this order:
+Reads a SkillRequest JSON object from stdin and writes a SkillResponse JSON object to stdout. This is the only command Skills should call for smart-home operations.
+
+### `api smoke`
+
+```sh
+yeelight-home api smoke --json [--profile <name>] [--region <region>] [--house-id <id>]
+```
+
+Runs a local cloud smoke check using the selected credential. This is intended for installation and support diagnostics.
+
+## Skill Integration
+
+Skill wrapper lookup order:
 
 1. `YEELIGHT_HOME_BIN`
-2. development-only bundled binary when present in a source checkout
+2. Development-only source checkout binary
 3. `yeelight-home` on `PATH`
 
-No Skill should call raw URLs, headers, curl, MCP compatibility services, or token-bearing commands.
+When the Runtime is missing, install it from a published public channel, then run:
+
+```sh
+yeelight-home auth status --json
+yeelight-home auth login --qr
+yeelight-home home list --json
+```
+
+Skills must not call raw URLs, raw headers, curl, compatibility services, or token-bearing commands.
+
+## Release And Packaging
+
+`yeelight-home` uses a runtime-only public repository at `Yeelight/yeelight-home`. The source-of-truth code remains under `yeelight-smart-home/runtime` and is exported by automation.
+
+The public runtime release pipeline uses GoReleaser from `Yeelight/yeelight-home`. The monorepo mirror workflow only validates and exports runtime source; it no longer builds or publishes CLI binaries.
+
+One tagged public `v*` release can produce:
+
+- macOS, Linux, Windows archives for `amd64`, `arm64`, and Linux `armv7`.
+- Checksums and release metadata.
+- Homebrew tap cask automation, with existing Formula compatibility where already published.
+- Scoop bucket manifest.
+- Linux packages through nFPM: `.deb`, `.rpm`, `.apk`, and Arch package artifacts.
+- Docker/GHCR and Docker Hub multi-arch images.
+- Snap and AUR artifacts or publication when required credentials are configured.
+- Winget manifest or PR flow when the Windows package route is enabled.
+
+`Yeelight/homebrew-tap` and `Yeelight/scoop-bucket` remain standard package-manager metadata repositories. They should be updated by GoReleaser, not used as Runtime source repositories.
+
+See [DISTRIBUTION.md](DISTRIBUTION.md) and [RELEASING.md](RELEASING.md).
+
+## Security Notes
+
+- Do not paste tokens, passwords, or account secrets into AI chat.
+- `auth status`, `doctor`, and `invoke` responses are redacted.
+- Profile metadata contains non-secret values such as profile name, region, selected home, and QR device identity. Tokens stay in credential storage.
+- Persistent writes use the Runtime pending-plan model; the model cannot execute arbitrary raw API payloads.

package/npm/lib/runtime-installer.js

@@ -43,7 +43,8 @@ function resolveTarget() {
   };
   const archMap = {
     x64: "amd64",
-    arm64: "arm64"
+    arm64: "arm64",
+    arm: "armv7"
   };
 
   const goos = platformMap[process.platform];
@@ -51,9 +52,12 @@ function resolveTarget() {
   if (!goos || !goarch) {
     throw new Error(`unsupported platform: ${process.platform}/${process.arch}`);
   }
+  if (goarch === "armv7" && process.platform !== "linux") {
+    throw new Error(`unsupported platform: ${process.platform}/${process.arch}`);
+  }
 
   const repo = process.env.YEELIGHT_HOME_REPO || "Yeelight/yeelight-home";
-  const version = process.env.YEELIGHT_HOME_VERSION || `yeelight-home-v${packageInfo.version}`;
+  const version = process.env.YEELIGHT_HOME_VERSION || `v${packageInfo.version}`;
   const extension = goos === "windows" ? "zip" : "tar.gz";
   const assetName = `yeelight-home-${goos}-${goarch}.${extension}`;
   const releasePath = version === "latest" ? "latest/download" : `download/${version}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yeelight-home",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local Yeelight Home Runtime CLI installer and launcher.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/Yeelight/yeelight-home#readme",
@@ -15,7 +15,9 @@
     "yeelight-home": "npm/bin/yeelight-home.js"
   },
   "files": [
-    "npm/",
+    "npm/bin/",
+    "npm/lib/",
+    "npm/install.js",
     "README.md",
     "INSTALL.md",
     "CONFIG.md",
@@ -35,7 +37,8 @@
   ],
   "cpu": [
     "x64",
-    "arm64"
+    "arm64",
+    "arm"
   ],
   "publishConfig": {
     "access": "public"

package/npm/bin/yeelight-home.js

@@ -1,24 +0,0 @@
-#!/usr/bin/env node
-
-"use strict";
-
-const { spawnSync } = require("node:child_process");
-const { ensureRuntimeBinary } = require("../lib/runtime-installer");
-
-const result = ensureRuntimeBinary();
-if (!result.ok) {
-  console.error(result.message);
-  process.exit(result.code || 1);
-}
-
-const child = spawnSync(result.binaryPath, process.argv.slice(2), {
-  stdio: "inherit",
-  windowsHide: false
-});
-
-if (child.error) {
-  console.error(child.error.message);
-  process.exit(1);
-}
-
-process.exit(child.status === null ? 1 : child.status);