asher-cli 1.1.0__tar.gz → 1.3.0__tar.gz

{asher_cli-1.1.0 → asher_cli-1.3.0}/.github/workflows/bandit.yml

@@ -31,7 +31,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
 
       - name: Bandit scan
         # --exit-zero: findings must not fail the job, or the upload step below
@@ -41,7 +41,7 @@ jobs:
           -c pyproject.toml -r . -f sarif -o bandit.sarif --exit-zero
 
       - name: Upload SARIF to code scanning
-        uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
+        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
         with:
           sarif_file: bandit.sarif
           category: bandit

{asher_cli-1.1.0 → asher_cli-1.3.0}/.github/workflows/ci.yml

@@ -8,13 +8,19 @@ on:
 permissions:
   contents: read
 
+# `uv run` re-syncs to the default groups on every invocation, which would drag
+# the `tray` group (and so a PyGObject/pycairo source build) back in after the
+# explicit sync below deliberately left it out. Sync once, then never re-sync.
+env:
+  UV_NO_SYNC: "1"
+
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
-      - run: uv sync --dev
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - run: uv sync --no-default-groups --group dev
       - run: uv run ruff check .
       - run: uv run ruff format --check .
       - run: uv run mypy asher/ --ignore-missing-imports
@@ -29,6 +35,6 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
-      - run: uv sync --dev
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - run: uv sync --no-default-groups --group dev
       - run: uv run pytest tests/ -v --tb=short

{asher_cli-1.1.0 → asher_cli-1.3.0}/.github/workflows/claude-code-review.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Run Claude Code Review
         id: claude-review
-        uses: anthropics/claude-code-action@be7b93b1907a4abad570368f3c74b6fe3807510b # v1
+        uses: anthropics/claude-code-action@9d7150bc8a3dae8149739a88019d192b579ad90c # v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'

{asher_cli-1.1.0 → asher_cli-1.3.0}/.github/workflows/claude.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@be7b93b1907a4abad570368f3c74b6fe3807510b # v1
+        uses: anthropics/claude-code-action@9d7150bc8a3dae8149739a88019d192b579ad90c # v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

{asher_cli-1.1.0 → asher_cli-1.3.0}/.github/workflows/coverage.yml

@@ -8,13 +8,18 @@ on:
 permissions:
   contents: read
 
+# See ci.yml: `uv run` would otherwise re-sync the `tray` group back in and try
+# to build PyGObject from source.
+env:
+  UV_NO_SYNC: "1"
+
 jobs:
   coverage:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
-      - run: uv sync --dev
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - run: uv sync --no-default-groups --group dev
       - name: Run tests with coverage
         run: uv run pytest tests/ --cov=asher --cov-report=lcov --cov-report=term-missing
       - name: Upload to Coveralls

{asher_cli-1.1.0 → asher_cli-1.3.0}/.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Extract version from branch name
         id: version
         run: echo "version=${GITHUB_REF_NAME#release/}" >> "$GITHUB_OUTPUT"
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv build
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
@@ -37,7 +37,7 @@ jobs:
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # release/v1
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
 
   github-release:
     name: Create GitHub Release

{asher_cli-1.1.0 → asher_cli-1.3.0}/CHANGELOG.md

@@ -7,12 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [git-cliff](https://git-cliff.org) from conventional commits.
 
+## [1.3.0] - 2026-08-23
+
+### 🚀 Features
+
+- *(commands)* Close the remaining robot-command gaps in the roadmap
+- *(monitoring)* Shorten cat-panel status labels that overflow the panel width
+
+### 🐛 Bug Fixes
+
+- *(monitoring)* Render readable status text in cat panel, not raw cloud code
+
+### 🧪 Tests
+
+- *(version)* Keep the /version pilot tests off the network
+
+## [1.2.0] - 2026-08-16
+
+### 🚀 Features
+
+- Drop "Clean now" from the tray menu
+- Refuse to start a watcher that has no credentials
+- Open the dashboard from the tray
+- Tone the tray icon to the desktop panel, and stop repeating the drawer
+- [**breaking**] Take credentials only from the keyring outside dev mode
+- Start the watcher at login, and notify (never install) on new releases
+- Background watcher and system-tray icon for notifications
+
+### 🐛 Bug Fixes
+
+- Keep the tray installed across a plain `uv run`
+- Read the selected completion row against its own background
+- *(deps)* Update dependency pylitterbot to v2025.6.4
+
+### 📚 Documentation
+
+- Trim the README, move the packaging detail to CLAUDE.md
+- Cover the tray's new behaviour and keyring-only credentials
+
+### 🧪 Tests
+
+- Stop four tests reading the developer's own machine
+- Cover the notifier fallback on every platform
+- Stop the notification tests toasting the desktop
+- Compare the Windows Run command against its normalised path
+- Pin platform branches in the daemon tests
+
+### 👷 CI/CD
+
+- Stop `uv run` re-syncing the tray group back in
+
 ## [1.1.0] - 2026-08-09
 
 ### 🚀 Features
 
-- *(headless)* Every robot command now runs without the TUI as `asher <command>`, with `--json` output and `--robot` selection; `--export` stays as a deprecated alias
-- *(theme)* Catppuccin Mocha throughout — one palette in `asher/theme.py` drives the TUI stylesheet and every Rich style, replacing ad-hoc hexes across eleven modules
+- Headless command surface + Catppuccin Mocha palette
+
+### 🐛 Bug Fixes
+
+- *(release)* Generate notes against the release tag, not the previous one
 
 ### 📚 Documentation
 

{asher_cli-1.1.0 → asher_cli-1.3.0}/CLAUDE.md

@@ -23,11 +23,18 @@ asher/
   __init__.py
   app.py            AsherApp class (thin orchestrator — composes mixins)
   auth.py           LoginScreen modal (ModalScreen[tuple[str,str]]) — available, not primary flow
-  helpers.py        fmt_ago(), drawer_bar(), ts(), robot_model()  (pure, testable)
-  constants.py      STATUS_COLORS, ROBOT_MODELS
+  helpers.py        fmt_ago(), fmt_until(), drawer_bar(), ts(), robot_model(), status_text() + argument parsing shared by the TUI and headless surfaces: hex_colour(), parse_clock(), parse_day(), split_type_flag(), activity_type()  (pure, testable)
+  constants.py      STATUS_COLORS, CAT_PANEL_STATUS_LABELS, ACTIVITY_TYPES, ROBOT_MODELS
   theme.py          Catppuccin Mocha palette + semantic roles (BACKGROUND, MUTED, DANGER, …) + CSS_VARIABLES/apply() — the only place a hex literal belongs
   config.py         runtime settings persistence — load()/save()/update() over ~/.asher-cli/config.json; holds poll interval, cat-panel visibility/colour, active pet index, notification settings (non-secret UI prefs only; credentials stay in keyring)
-  notifications.py  desktop toast + audible alert façade over plyer (fire/beep, always-safe no-op on failure/headless)
+  notifications.py  desktop toast + audible alert façade — plyer first, then the platform's own tool (osascript/notify-send); fire/beep are always-safe no-ops on failure/headless
+  watcher.py        background notification loop with no TUI — pure WatchState (robot snapshots → Alert list) + supervising watch() that reconnects with backoff, plus WatcherRunner (asyncio on a worker thread, for the tray)
+  daemon.py         detached watcher process control — `start` pre-flights `connection.credentials_available()` (presence only, no network, so starting offline still works) because the watcher claims the pid file *before* authenticating and would otherwise report a pid for a process that stops a moment later — pid file/log in ~/.asher-cli, start/stop/status/run, cross-platform detach + liveness (os.kill would *terminate* on Windows)
+  tray.py           optional pystray/Pillow system-tray icon over WatcherRunner; every path degrades to a headless watcher. Icon is a panel-toned silhouette + status dot — colour rides the badge, never the whole glyph
+  launcher.py       open_app() — start the TUI in a new terminal from the tray (a detached tray has none): new console on Windows, Terminal.app via AppleScript on macOS, first installed emulator on Linux (desktop's own preferred)
+  desktoptheme.py   panel_is_dark() — is the tray/menu-bar background dark? kdeglobals luma / gsettings / AppleInterfaceStyle / the Personalize registry keys, behind a TTL cache; every probe degrades to a fallback, never raises
+  autostart.py      login items — AutostartBackend ABC + launchd/systemd-user/registry subclasses + backend() factory; all per-user, no admin rights, disable() removes exactly what enable() wrote
+  updates.py        PyPI release check — read-only over HTTPS, once a day, reports only. Never installs (see its docstring for why that stays manual)
   cats.py           CATS dict (ASCII art)
   login_flow.py     LoginFlow state machine — inline email/password prompt in command bar
   robot_protocol.py RobotProtocol structural Protocol for pylitterbot robot objects
@@ -62,6 +69,13 @@ tests/
   test_mcp_config.py      Claude Desktop config read/write
   test_config.py          runtime settings persistence — load/save/update over defaults
   test_notifications.py   plyer toast + beep façade — always-safe no-op paths
+  test_watcher.py         WatchState alert transitions + snapshot/deliver (pure) + watch() against a patched open_session + WatcherRunner threading
+  test_daemon.py          pid-file bookkeeping, start/stop/status/dispatch with Popen and os.kill mocked
+  test_tray.py            availability probing, menu/title text, icon rendering (tone inversion + status badge), and the headless fallbacks
+  test_launcher.py        every platform's open path driven directly (Popen always mocked), terminal preference/fallback order
+  test_desktoptheme.py    all four panel-tone probes driven directly (so each is covered on every runner) with the readers/registry mocked, plus the TTL cache
+  test_autostart.py       all three login-item backends driven directly (so each is covered on every runner) with launchctl/systemctl/winreg mocked
+  test_updates.py         version comparison, the once-a-day cache, HTTPS-only fetching, and a guard that the module spawns no process
   test_mcp_bridge.py      mcp_bridge launcher credential/subprocess handling
   test_mcp_command.py     /mcp slash command dispatch
   test_faults.py          check_faults() — safety statuses, attribute faults, graceful degradation
@@ -79,16 +93,27 @@ tests/
 
 Priority order on startup:
 
-1. **OS keyring** — set automatically after first interactive login
-2. **`.env` file** — fallback for existing users / CI
+1. **OS keyring** — cached OAuth token, then email/password; set automatically after first interactive login
+2. **`.env` file** — **development only**, gated on `ASHER_CLI_DEV_MODE=true`
 3. **Inline login flow** — shown when no credentials found anywhere (email → password prompt in command bar)
 
-`.env` variable names (for fallback):
+In a real install the keyring is the **only** source of credentials. `.env` is a
+working-copy convenience: without dev mode a stray `LITTER_ROBOT_USER` in a shell
+profile or a checked-out `.env` would silently outrank the keyring and
+authenticate as the wrong account.
+
+`.env` variable names (dev mode only):
 ```
+ASHER_CLI_DEV_MODE=true
 LITTER_ROBOT_USER=...
 LITTER_ROBOT_PASSWORD=...
 ```
 
+Every environment read goes through `_env_credentials()` in
+`asher/connection/__init__.py` — the one place the gate is applied. Don't call
+`os.getenv("LITTER_ROBOT_*")` anywhere else. `helpers.dev_mode()` is the shared
+predicate (it also selects the `dev` version string).
+
 Keyring service name: `asher-cli`, keys `email` and `password`.
 Helper functions in `asher/connection/__init__.py`: `_keyring_load()`, `_keyring_save()`, `_keyring_delete()`.
 
@@ -98,14 +123,14 @@ Command names, slash-command names, and their args are not listed here — see t
 
 **Normal commands** (no prefix) are robot actions only; **slash commands** (`/` prefix) are app management only.
 
-`/refresh`, `/cat`, `/pet`, and `/notify` persist their settings to `~/.asher-cli/config.json` (via `asher.config.update()`), so they survive restarts. Credentials and the preferred-robot serial stay in the OS keyring; the config file holds only non-secret UI preferences.
+`/refresh`, `/cat`, `/pet`, and `/notify` persist their settings to `~/.asher-cli/config.json` (via `asher.config.update()`), so they survive restarts. That file is also the only channel to a running watcher, which re-reads it per alert rather than caching at startup. Credentials and the preferred-robot serial stay in the OS keyring; the config file holds only non-secret UI preferences.
 
 Do not add robot-control commands as slash commands, and do not add app-management commands as bare commands.
 
 **Special cases** (accepted both with and without `/`):
 `exit`, `quit`, `q` — exit the app
 
-**Headless commands** (`asher <command>`) are a parallel registry in `asher/headless.py`: same robot actions, no Textual, plain-string + JSON output. Slash commands have no headless equivalent — they configure the TUI, which isn't running. A robot command worth scripting should exist in both registries; the shared logic lives in `RobotAdapter`, not in either command class.
+**Headless commands** (`asher <command>`) are a parallel registry in `asher/headless.py`: same robot actions, no Textual, plain-string + JSON output. `asher watch` and `asher update` are deliberately *not* in that registry — `watch` manages a long-lived process rather than doing one thing and exiting, and `update` talks to PyPI rather than a robot, so neither should be forced through `open_session()` and made to authenticate. Both declare their subparser directly in `__main__.py`. Slash commands have no headless equivalent — they configure the TUI, which isn't running. A robot command worth scripting should exist in both registries; the shared logic lives in `RobotAdapter`, not in either command class.
 
 > If you add a command, update the tables in `README.md` and the list in `asher/slash-commands/__init__.py`. If it's a robot command, consider adding it to `COMMANDS` in `asher/headless.py` too.
 
@@ -144,6 +169,10 @@ LoginScreen (ModalScreen) — available in auth.py but not the primary auth path
 | `_refresh_faults(robot)` | run `check_faults()`, render `#fault-banner`, log transitions; sets cat mode to `error` while faults active |
 | `_cycling_chip()` / `_start_cycle_timer()` / `_stop_cycle_timer()` / `_tick_cycle()` | `⟳ Cycling M:SS` chip + lazy 1s elapsed timer |
 | `_poll_status_interval()` | `@work` — poll fallback every 300s (5 min); WebSocket is primary |
+| `watcher.watch()` | supervise a cloud session and notify on every change worth interrupting for — the TUI's `_notify_fault` without a TUI |
+| `daemon.start/stop/status()` | detached watcher process control; `running_pid()` also gates the TUI's own toasts so alerts never double up |
+| `daemon.run_foreground()` | the watcher process itself — claims the pid file (`_pid_file_held`) so a login-started watcher is still visible to `status`/`stop`, and refuses to be a second one |
+| `autostart.enable/disable()` | register/remove the platform login item; `describe()` feeds the `watch status` line |
 | `_tick_cat()` | advances multi-frame cat animation every 0.4s |
 | `_dispatch_command(command, args)` | `@work` — calls `command.run(app, args)` from the registry |
 | `on_input_submitted()` | routes input to login flow or `_dispatch_command` via `CommandRegistry`; Enter on a partial `/cmd` completes it instead of submitting |
@@ -200,6 +229,14 @@ Commands that need a confirmed cloud state before showing a result (e.g. sleep/w
 
 **File naming convention:** no underscores in filenames (except Python-required `__init__.py` and `__main__.py`).
 
+## Tray packaging
+
+The `tray` extra is what a published install uses (`pip install "asher-cli[tray]"`). It is **mirrored** as a `tray` dependency-group listed in `[tool.uv] default-groups`, because `uv run` re-syncs the environment to the default *groups* on every invocation and prunes everything else — extras included. Without the group, any plain `uv run` silently removed `pystray` and left the watcher drawing an icon no desktop was hosting. Keep the two lists in step when changing either.
+
+CI opts out with `uv sync --no-default-groups --group dev` (`ci.yml`, `coverage.yml`): PyGObject builds from source and the runners have no GObject-introspection headers. `[tool.uv] default-extras` is not an option — uv 0.11 doesn't support that key.
+
+PyGObject is what selects pystray's `_appindicator` backend. Without it pystray falls back to a legacy XEmbed icon that KDE Plasma and GNOME no longer host: the watcher runs, draws an icon, and nothing shows it, with no error anywhere. Check with `pystray.Icon.__module__`.
+
 ## Dev workflow
 
 See `[tool.poe.tasks]` in `pyproject.toml` for the full task list (`uv run poe <task>`).

{asher_cli-1.1.0 → asher_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: asher-cli
-Version: 1.1.0
+Version: 1.3.0
 Summary: Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API
 Project-URL: Homepage, https://github.com/karanshukla/asher-cli
 Project-URL: Repository, https://github.com/karanshukla/asher-cli
@@ -40,13 +40,18 @@ Classifier: Topic :: Home Automation
 Requires-Python: >=3.10
 Requires-Dist: keyring>=24.0.0
 Requires-Dist: plyer>=2.1.0
-Requires-Dist: pylitterbot==2025.6.2
+Requires-Dist: pylitterbot==2025.6.4
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: textual>=0.47.0
 Requires-Dist: tzlocal>=5.4
 Provides-Extra: mcp
-Requires-Dist: pylitterbot[mcp]==2025.6.2; extra == 'mcp'
+Requires-Dist: mcp<2; extra == 'mcp'
+Requires-Dist: pylitterbot[mcp]==2025.6.4; extra == 'mcp'
+Provides-Extra: tray
+Requires-Dist: pillow>=10.0; extra == 'tray'
+Requires-Dist: pygobject>=3.42; (sys_platform == 'linux') and extra == 'tray'
+Requires-Dist: pystray>=0.19; extra == 'tray'
 Description-Content-Type: text/markdown
 
 # Asher CLI
@@ -70,12 +75,14 @@ A Claude Code-style terminal dashboard for monitoring and controlling Litter Rob
 - Real-time cycling indicator with elapsed time (`⟳ Cycling  M:SS`)
 - Fault & safety monitoring — model-scoped in-panel alerts for cat detected, pinch, motor/position/gas faults (LR5: bonnet/laser/drawer); press `d` to dismiss
 - Cat panel with mode label + status badges (status chip, lock, night light, sleep, wait time) under the art
-- Scrollable activity-history pager — `history [count|all]` opens a full-screen, paginated view (arrow keys, `Page Up`/`Page Down`, `Home`/`End`); `c` copies the whole history to the clipboard; `q`/`Esc`/`Enter` to close
-- Commands: `clean`, `status`, `info`, `lock`, `unlock`, `sleep`, `wake`, `night-light on|off|auto`, `night-light-brightness`, `panel-brightness <low|medium|high>` (LR4/LR5), `wait-time`, `power on|off`, `rename`, `insight`, `sleep-schedule`, plus LR5 extras (`privacy`, `volume`, `camera-audio`, `drawer-reset`), `history [count|all]`, `export [days|month]`, `help`, `quit`
-- Slash commands for app management: `/login`, `/logout`, `/robots`, `/robot <index|name>`, `/pets`, `/pet <index|name>`, `/cat on|off|colour <hex>`, `/refresh [seconds|off]`, `/config`, `/notify on|off|sound on|off|test`, `/version`, `/mcp on|off|status`, `/exit`
+- Scrollable activity-history pager — `history [count|all] [--type <kind>]` opens a full-screen, paginated view (arrow keys, `Page Up`/`Page Down`, `Home`/`End`); `c` copies the whole history to the clipboard; `q`/`Esc`/`Enter` to close
+- Commands: `clean`, `status`, `info`, `lock`, `unlock`, `sleep`, `wake`, `night-light on|off|auto|color <hex>`, `night-light-brightness`, `panel-brightness <low|medium|high>` (LR4/LR5), `wait-time`, `power on|off`, `rename`, `insight`, `sleep-schedule [set|disable]`, plus LR5 extras (`privacy`, `volume`, `camera-audio`, `drawer-reset`), `history [count|all] [--type <kind>]`, `export [days|month]`, `help`, `quit`
+- Slash commands for app management: `/login`, `/logout`, `/robots`, `/robot <index|name>`, `/pets`, `/pet <index|name>`, `/cat on|off|colour <hex>`, `/refresh [seconds|off]`, `/config`, `/notify on|off|sound on|off|test`, `/watch start|stop|status|enable|disable`, `/version`, `/mcp on|off|status`, `/exit`
 - Slash-command tab completion — type `/` and a Claude Code-style overlay lists matching commands; `↑`/`↓` to move, `Tab` or `Enter` to accept, `Esc` to dismiss
 - Inline ghost-text completion for bare commands — type a prefix (`cle`) and the rest (`an`) appears greyed; `Tab` or `→` to accept → `clean`
 - Headless mode — every robot command also runs without the TUI (`asher status`, `asher clean`, `asher night-light auto`, `asher export 7`), with `--json` output and documented exit codes for cron / Task Scheduler / SSH
+- Background watcher — `asher watch start` detaches a notifier process that keeps toasting faults, a filling drawer, and offline/online changes **after you close the terminal**; `asher watch enable` starts it at login (launchd / systemd / registry); optional system-tray icon shows live status with Open Asher / Notifications / Quit
+- Update notices — checks PyPI once a day and tells you when a newer release exists, with the right upgrade command for how you installed it. It never installs anything itself
 - Catppuccin Mocha throughout — one palette in `asher/theme.py` drives the TUI stylesheet and every Rich style
 - Cat animation panel that reacts to robot state
 - Command history (↑/↓ arrows)
@@ -121,12 +128,7 @@ On first run, type `/login` at the command prompt. Your credentials are saved to
 
 To sign out: `/logout`
 
-`.env` fallback (for CI or existing users):
-
-```env
-LITTER_ROBOT_USER=your@email.com
-LITTER_ROBOT_PASSWORD=yourpassword
-```
+The keyring is the only place an installed copy reads credentials from. Working from a clone, you can use `.env` instead by opting into dev mode (see [Development](#development)).
 
 ## Commands
 
@@ -140,18 +142,21 @@ LITTER_ROBOT_PASSWORD=yourpassword
 | `lock` / `unlock` | Toggle panel lockout |
 | `sleep` / `wake` | Toggle sleep mode |
 | `night-light on\|off\|auto` | Set night light mode |
+| `night-light color <hex>` | Set the LR5 night light colour (`#RRGGBB`, or the 3-digit shorthand) |
 | `night-light-brightness <level>` | Set brightness (LR5: 0-100; LR4: 25/50/100) |
 | `panel-brightness <low\|medium\|high>` | Set control-panel brightness (LR4/LR5 only; shows current if omitted) |
 | `wait-time <minutes>` | Set clean-cycle wait time (shows valid values / current if omitted) |
 | `power on\|off` | Hard-power the unit on or off |
 | `rename <new name>` | Rename the unit in the Whisker cloud |
 | `insight [days\|month]` | Show cycle-usage statistics (default: 30 days) |
-| `sleep-schedule` | Show the per-day sleep schedule (read-only) |
+| `sleep-schedule` | Show the per-day sleep schedule |
+| `sleep-schedule set <day\|all> <HH:MM> <HH:MM>` | Set the sleep → wake window (LR3: one window for every day, wake time fixed; LR4: read-only, use the Whisker app) |
+| `sleep-schedule disable` | Turn every scheduled sleep window off |
 | `privacy on\|off` | Toggle LR5 privacy mode |
 | `volume <0-100>` | Set LR5 sound volume |
 | `camera-audio on\|off` | Toggle LR5 camera audio |
 | `drawer-reset` | Reset the LR5 waste drawer level indicator |
-| `history [count\|all]` | Show recent activity in a scrollable pager (default: 50 events) |
+| `history [count\|all] [--type <kind>]` | Show recent activity in a scrollable pager (default: 50 events); `--type cat\|clean\|litter\|offline\|…` filters on the LR5 |
 | `export [days\|month]` | Export activity history to CSV in `~/Downloads` (default: 30 days) |
 | `clear` | Clear the log |
 | `help` | Show command list |
@@ -170,8 +175,10 @@ LITTER_ROBOT_PASSWORD=yourpassword
 | `/cat on\|off` | Show or hide the cat animation panel |
 | `/cat colour <hex>` | Change the cat art colour (e.g. `/cat colour #ff79c6`); `color` also accepted; `/cat reset` to revert |
 | `/refresh [seconds\|off]` | Change the auto-poll interval or disable it (`/refresh 60`, `/refresh off`) |
-| `/config` | Show current runtime settings (robot, refresh rate, cat panel, active pet, notifications) |
+| `/config` | Show current runtime settings (robot, refresh rate, cat panel, active pet, notifications, watcher) |
 | `/notify on\|off\|sound on\|off\|test` | Toggle desktop toast notifications for fault events (cat detected, pinch, motor fault, drawer full); `test` fires a sample toast |
+| `/watch start\|stop\|status` | Start, stop, or check the background watcher that keeps notifications running after you close the dashboard |
+| `/watch enable\|disable` | Register (or remove) the watcher as a login item so it starts automatically |
 | `/version` | Show version info (asher-cli, Python, pylitterbot, textual) |
 | `/mcp on\|off\|status` | Toggle the Litter-Robot MCP server entry in Claude Desktop |
 | `/exit` | Exit Asher CLI |
@@ -189,6 +196,8 @@ asher clean                              start a clean cycle
 asher night-light auto                   set night light mode
 asher wait-time 7                        set the clean-cycle wait time
 asher history 20                         recent activity, newest first
+asher history 20 --type cat              only cat visits (LR5)
+asher sleep-schedule set all 22:00 07:00 sleep 22:00 → 07:00 every day
 asher insight 7                          cycle-usage statistics
 asher export 7 --output ~/hist.csv       activity history to CSV
 ```
@@ -231,11 +240,80 @@ Exit codes for scripting:
 asher.exe export 7 --output C:\Users\me\litter-history.csv
 ```
 
+### Update notices
+
+```bash
+asher update            # is there a newer release?
+asher update --json
+```
+
+Asher checks PyPI's JSON API once a day (and on `/version`) and tells you when a newer release is published, along with the right command for however you installed it — `pipx upgrade`, `uv tool upgrade`, or `pip install -U`. Exit code is `0` when current, `10` when an update exists, so a script can branch on it.
+
+**It never installs anything.** That's deliberate, not an omission:
+
+- The process can't reliably tell how it was installed, so a self-upgrade would be guessing at the command that owns its own files.
+- Replacing files under a live interpreter can load a mix of old and new modules, and the background watcher is exactly the long-lived process that would be running while its own code got swapped.
+- Most importantly, auto-installing turns one compromised release into code running everywhere with nobody choosing the moment. Checking is safe; applying should be your call.
+
+The check is read-only over HTTPS, fetches no code, and `update_check: false` in `~/.asher-cli/config.json` turns it off entirely.
+
 `asher --export [days]` remains as a deprecated alias for `asher export [days]`, so existing cron entries keep working.
 
+### Background notifications (`asher watch`)
+
+The dashboard only notifies while it's on screen — close the terminal and the toasts stop. `asher watch` runs the same fault monitoring as a detached process, so notifications keep arriving with no terminal open at all.
+
+```bash
+asher watch start        # detach a watcher; the terminal is free to close
+asher watch status       # is one running? plus the last few log lines
+asher watch stop         # shut it down
+asher watch enable       # also start it at every login
+asher watch disable      # stop starting it at login
+asher watch run          # same thing in the foreground, for debugging
+```
+
+You can also drive it from inside the dashboard with `/watch start|stop|status` — handy right before you quit. While a watcher is running the dashboard suppresses its own toasts, so you never get an alert twice.
+
+It notifies on:
+
+- **faults appearing and clearing** — cat detected, pinch, motor/position/gas faults, drawer full (same model-scoped detection as the dashboard's fault banner)
+- **the waste drawer crossing 85%** — an early warning before the robot stops on its own (tune with `watch_drawer_threshold`)
+- **the robot going offline or coming back**
+
+Notifications respect your `/notify` settings, and re-read them on every alert — toggling notifications in the dashboard reaches a watcher that's already running. Faults already showing when the watcher starts are announced immediately; connectivity is only reported when it *changes*, so startup never claims a robot "came back" that was never away.
+
+The watcher is built to be left alone: it reconnects with backoff through Wi-Fi drops, laptop sleeps, expired tokens, and a cloud that's still unreachable at login. Only genuinely missing credentials stop it — sign in with `/login` once first. Its log lives at `~/.asher-cli/watch.log` (`~` is your home directory; `%USERPROFILE%` on Windows).
+
+**System-tray icon** (optional):
+
+```bash
+pip install "asher-cli[tray]"
+```
+
+`asher watch start` then shows a tray icon: a cat silhouette toned to your desktop panel, badged green healthy / red faulted / grey offline, with the full status in its tooltip. The menu offers **Open Asher** (also the left-click action, opens the dashboard in a new terminal), a **Notifications** toggle, and **Quit**. It carries no robot actions on purpose: a misclick next to the clock shouldn't be able to start a cycle. No extras, no desktop session, or no AppIndicator host all fall back to a headless watcher rather than failing. Pass `--no-tray` (or set `watch_tray: false`) to skip the icon.
+
+On Linux the extra pulls in PyGObject, which builds from source and needs your distro's GObject-introspection and Cairo dev packages (`gobject-introspection-devel` + `cairo-gobject-devel` on Fedora, `libgirepository1.0-dev` + `libcairo2-dev` on Debian/Ubuntu).
+
+**Start at login:**
+
+```bash
+asher watch enable      # register a login item, and start watching now
+asher watch disable     # remove it
+```
+
+`enable` uses whatever already runs things at login on your machine, so there's no extra background service to trust:
+
+| Platform | Login item | Where |
+|---|---|---|
+| macOS | launchd user agent | `~/Library/LaunchAgents/com.asher-cli.watcher.plist` |
+| Linux | systemd user unit | `~/.config/systemd/user/asher-watch.service` |
+| Windows | registry Run value | `HKCU\...\CurrentVersion\Run\AsherWatch` |
+
+All three are per-user and need no administrator rights, and `disable` removes exactly what `enable` created. A crashed watcher is restarted; one you stopped with `asher watch stop` stays stopped. `asher watch status` shows whether autostart is registered. If your system has no user-level systemd (some minimal distros, WSL), `enable` says so and points you at putting `asher watch start` in your shell profile instead.
+
 ## Configuration
 
-Runtime settings persist across restarts in `~/.asher-cli/config.json`, so you don't have to re-apply `/refresh 60`, `/cat colour #ff79c6`, or `/pet 1` every launch. The file is auto-created on first change and holds six non-secret UI preferences:
+Runtime settings persist across restarts in `~/.asher-cli/config.json`, so you don't have to re-apply `/refresh 60`, `/cat colour #ff79c6`, or `/pet 1` every launch. The file is auto-created on first change and holds these non-secret UI preferences:
 
 | Setting | Slash command | Default |
 |---|---|---|
@@ -245,6 +323,9 @@ Runtime settings persist across restarts in `~/.asher-cli/config.json`, so you d
 | `active_pet_index` | `/pet <index\|name>` | `0` |
 | `notifications` | `/notify on\|off` | `true` |
 | `notification_sound` | `/notify sound on\|off` | `false` |
+| `watch_tray` | *(file only)* | `true` — set `false` to make `asher watch` always run without a tray icon |
+| `watch_drawer_threshold` | *(file only)* | `85` — drawer % that triggers an early background warning |
+| `update_check` | *(file only)* | `true` — set `false` to stop the daily PyPI version check |
 
 Credentials and the preferred-robot serial stay in the OS keyring; `.env` vars stay as env vars. You generally don't need to edit the file by hand — just use the slash commands — but it's plain JSON and safe to inspect or delete (deleting it restores defaults).
 
@@ -335,11 +416,13 @@ cp .env.example .env
 ```
 
 ```env
+ASHER_CLI_DEV_MODE=true    # shows version as "dev", and opts the two variables below in
 LITTER_ROBOT_USER=your@email.com
 LITTER_ROBOT_PASSWORD=yourpassword
-ASHER_CLI_DEV_MODE=true    # sets version to "dev" instead of the installed package version
 ```
 
+`ASHER_CLI_DEV_MODE` is what makes the credentials below readable at all — outside dev mode the app takes credentials only from the OS keyring.
+
 ### 3. Run with hot reload
 
 **CSS hot reload** — Textual's devtools watch inline `CSS` strings and `.tcss` files and reload them in-place without restarting: