Resolve leave_dark_blue config and documentation mismatch #47

New issue

Closed

opened 2026-05-12 00:49:43 -04:00 by JackFrostbyte · 0 comments

JackFrostbyte commented

2026-05-12 00:49:43 -04:00

Owner

Context

There is a mismatch between the documented safe shutdown behavior and the default runtime configuration.

docs/safe-failure-modes.md describes clean shutdown restoring controlled RGB Aura zones to a known dark-blue state when possible, but config/runtime_config.json currently ships with:

"leave_dark_blue": false

Systemd users are covered because the unit passes --leave-dark-blue, but users running from the default config may not get the documented behavior.

Decision needed

Preferred direction:

Change the default config to "leave_dark_blue": true.

Alternative:

Keep the default false, but clearly document that clean shutdown restore must be enabled through config or CLI.

Scope

Decide and apply the intended default behavior.
Update docs to match the actual default.
Update examples if needed.
Confirm systemd documentation still matches the service file.

Acceptance criteria

config/runtime_config.json and documentation agree.
Systemd service behavior remains documented correctly.
Manual runtime behavior is clear for users.
ruff format passes where applicable.
ruff check passes where applicable.

Branch workflow

Base branch:

develop

Suggested work branch:

fix/issue-47-leave-dark-blue-default-docs

Pull request target:

develop

Do not merge directly into main. main should only receive tested release-ready changes from develop.

## Context There is a mismatch between the documented safe shutdown behavior and the default runtime configuration. `docs/safe-failure-modes.md` describes clean shutdown restoring controlled RGB Aura zones to a known dark-blue state when possible, but `config/runtime_config.json` currently ships with: `"leave_dark_blue": false` Systemd users are covered because the unit passes `--leave-dark-blue`, but users running from the default config may not get the documented behavior. ## Decision needed Preferred direction: - Change the default config to `"leave_dark_blue": true`. Alternative: - Keep the default false, but clearly document that clean shutdown restore must be enabled through config or CLI. ## Scope - Decide and apply the intended default behavior. - Update docs to match the actual default. - Update examples if needed. - Confirm systemd documentation still matches the service file. ## Acceptance criteria - `config/runtime_config.json` and documentation agree. - Systemd service behavior remains documented correctly. - Manual runtime behavior is clear for users. - `ruff format` passes where applicable. - `ruff check` passes where applicable. ## Branch workflow Base branch: `develop` Suggested work branch: `fix/issue-47-leave-dark-blue-default-docs` Pull request target: `develop` Do not merge directly into `main`. `main` should only receive tested release-ready changes from `develop`.

JackFrostbyte added this to the v1.0.1 - Maintenance and startup reliability milestone

2026-05-12 01:02:25 -04:00