asher-cli 1.0.2__tar.gz → 1.2.0__tar.gz

asher_cli-1.2.0/.claude/hooks/block-env.py

@@ -0,0 +1,14 @@
+import json
+import sys
+
+try:
+    payload = json.load(sys.stdin)
+    file_path = payload.get("file_path", "")
+except (json.JSONDecodeError, ValueError):
+    sys.exit(0)
+
+if file_path.endswith(".env"):
+    print("Blocked: .env contains real credentials — edit it manually if needed")
+    sys.exit(2)
+
+sys.exit(0)

{asher_cli-1.0.2 → asher_cli-1.2.0}/.claude/settings.json

@@ -37,7 +37,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "powershell -NonInteractive -ExecutionPolicy Bypass -File .claude/hooks/block-env.ps1"
+            "command": "uv run python .claude/hooks/block-env.py"
           }
         ]
       }

asher_cli-1.2.0/.claude/skills/mcp-bridge/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: mcp-bridge
+description: How asher-cli's /mcp command and the asher-mcp-launch credential bridge work. Load before changing asher/mcp_config.py, asher/mcp_bridge.py, or the /mcp slash command.
+user-invocable: false
+---
+
+# MCP bridge (`/mcp`)
+
+pylitterbot ships an optional MCP server (`pip install pylitterbot[mcp]`, run via `python -m pylitterbot.mcp`) that lets an MCP client like Claude Desktop monitor/control the robot directly. Its own docs configure it with plaintext credentials in the client's JSON config — asher-cli avoids that:
+
+- `/mcp on|off|status` (in `asher/commands/__init__.py`, logic in `asher/mcp_config.py`) adds/removes an entry (named by `mcp_config._SERVER_NAME`) in every `claude_desktop_config.json` this OS's Claude Desktop might read (`mcp_config.config_paths()` — on Windows this includes both the standard installer path and any MSIX/Microsoft Store virtualized path). The entry's `command` is `sys.executable -m asher.mcp_bridge` — never the credentials themselves.
+- `/mcp on` also auto-installs pylitterbot's `mcp` extra via `sys.executable -m pip install "pylitterbot[mcp]==<installed version>"` if the `mcp` package isn't importable yet.
+- `asher/mcp_bridge.py` (console script `asher-mcp-launch`) is what Claude Desktop actually spawns. It reads email/password from the OS keyring at process start, sets them as `LITTER_ROBOT_USERNAME`/`LITTER_ROBOT_PASSWORD` (pylitterbot's expected names — note these differ from asher-cli's own `.env` var `LITTER_ROBOT_USER`) in that process's environment only, then execs `python -m pylitterbot.mcp`. No credentials ever touch the on-disk MCP config.
+- `/mcp on` requires keyring credentials. If none are found but `.env` fallback credentials are set, it copies them into the keyring automatically (since the bridge process can't reliably discover a project-relative `.env` — Claude Desktop controls its working directory, not asher-cli).
+- Requires the `mcp` extra: `uv sync --extra mcp` / `pip install asher-cli[mcp]`. Restart Claude Desktop after toggling for the change to take effect.

asher_cli-1.2.0/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [karanshukla]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

{asher_cli-1.0.2 → asher_cli-1.2.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
+      - 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
@@ -30,5 +36,5 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
-      - run: uv sync --dev
+      - run: uv sync --no-default-groups --group dev
       - run: uv run pytest tests/ -v --tb=short

{asher_cli-1.0.2 → asher_cli-1.2.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@6b082c41935b4c8a3b8b0ef85ba4ba4d9eeb8975 # v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'

{asher_cli-1.0.2 → asher_cli-1.2.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@6b082c41935b4c8a3b8b0ef85ba4ba4d9eeb8975 # v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

{asher_cli-1.0.2 → asher_cli-1.2.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
+      - 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.0.2 → asher_cli-1.2.0}/.github/workflows/release.yml

@@ -37,33 +37,36 @@ 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
     needs: [build, publish]
     runs-on: ubuntu-latest
     steps:
-      # Full history (fetch-depth: 0) so git-cliff can walk commits/tags.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          fetch-depth: 0
       - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
         with:
           name: dist
           path: dist/
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
-      - name: Install git-cliff
-        run: uv tool install git-cliff
-      - name: Generate release notes with git-cliff
+      - name: Extract release notes from CHANGELOG.md
         env:
           VERSION: ${{ needs.build.outputs.version }}
         run: |
-          # Explicit -c cliff.toml avoids auto-discovering pyproject.toml.
-          # Pin the just-released version so git-cliff groups its commits under
-          # the right heading even before the tag is fetched, then emit only
-          # that section (--latest) with the header stripped.
-          git cliff -c cliff.toml --tag "v${VERSION}" --latest --strip header -o RELEASE_NOTES.md
+          # CHANGELOG.md is the single source of release prose: it is generated
+          # by git-cliff (see `poe changelog-release`) but may be hand-refined
+          # before the release is cut, and re-deriving the notes from commits
+          # here would silently discard those edits.
+          awk -v hdr="## [${VERSION}]" '
+            index($0, hdr) == 1              { found = 1; next }
+            found && index($0, "## [") == 1  { exit }
+            found                            { print }
+          ' CHANGELOG.md > RELEASE_NOTES.md
+          if [ ! -s RELEASE_NOTES.md ]; then
+            echo "::error::CHANGELOG.md has no '## [${VERSION}]' section." \
+                 "Run 'uv run poe changelog-release ${VERSION}' and commit it before releasing."
+            exit 1
+          fi
       - name: Create release
         env:
           GH_TOKEN: ${{ github.token }}

{asher_cli-1.0.2 → asher_cli-1.2.0}/CHANGELOG.md

@@ -7,6 +7,63 @@ 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.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 command surface + Catppuccin Mocha palette
+
+### 🐛 Bug Fixes
+
+- *(release)* Generate notes against the release tag, not the previous one
+
+### 📚 Documentation
+
+- Point CLAUDE.md at the release process
+
+### 👷 CI/CD
+
+- *(release)* Build release notes from CHANGELOG.md
+
+### 🔧 Miscellaneous
+
+- Trim CLAUDE.md, split MCP bridge docs into a skill, fix env-guard hook
+
 ## [1.0.2] - 2026-08-05
 
 ### 🐛 Bug Fixes
@@ -23,10 +80,6 @@ Generated by [git-cliff](https://git-cliff.org) from conventional commits.
 
 - *(history)* Copy-to-clipboard + discoverable footer hints
 
-### 📚 Documentation
-
-- *(changelog)* Cut v1.0.1
-
 ## [1.0.0] - 2026-08-02
 
 ### 🚀 Features
@@ -38,7 +91,6 @@ Generated by [git-cliff](https://git-cliff.org) from conventional commits.
 
 ### 📚 Documentation
 
-- *(changelog)* Regenerate for next release, trim duplicate README list
 - *(roadmap)* Archive completed sections to docs/roadmap-archive/
 
 ### 🔧 Miscellaneous
@@ -57,7 +109,6 @@ Generated by [git-cliff](https://git-cliff.org) from conventional commits.
 
 ### 📚 Documentation
 
-- *(changelog)* Cut v0.2.0
 - *(commands)* Sync stale command lists in CLAUDE.md and slash-commands docstring
 - *(readme)* Sync command tables with code, add changelog
 

{asher_cli-1.0.2 → asher_cli-1.2.0}/CLAUDE.md

@@ -4,21 +4,9 @@ Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API.
 
 ## Stack
 
-- **Python 3.10+**
-- **Textual** — async TUI framework (`textual>=0.47`)
-- **pylitterbot** — unofficial Whisker API wrapper (`pylitterbot>=3.0`)
-- **python-dotenv** — credential loading (`.env` fallback)
-- **keyring>=24** — OS credential store (Windows Credential Manager / macOS Keychain / Linux Secret Service)
-
-## Tooling
-
-- **uv** — dependency management and task runner (`uv sync`, `uv run`)
-- **poethepoet** — task aliases via `uv run poe <task>`
-- **ruff** — linter and formatter
-- **mypy** — static type checking
-- **pytest + pytest-asyncio + pytest-cov** — tests
-- **textual-dev** — CSS hot reload devtools
-- **watchfiles** — Python auto-restart on file change
+- **keyring** resolves to the OS-native credential store: Windows Credential Manager / macOS Keychain / Linux Secret Service.
+
+See `pyproject.toml` for the full dependency and dev-tooling list (`[project].dependencies`, `[dependency-groups].dev`, `[tool.poe.tasks]`).
 
 ## Entry points
 
@@ -37,8 +25,16 @@ asher/
   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
+  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
@@ -47,9 +43,10 @@ asher/
   mcp_bridge.py     asher-mcp-launch console script — keyring-backed pylitterbot MCP launcher
   faults.py         check_faults(robot) — model-scoped safety/component fault detection (status enum + per-model attr allowlist incl. LR4 USB power fault; hopper never a fault)
   history_view.py   HistoryScreen (ModalScreen) + format_history_rows()/format_history_text() — scrollable activity-history pager pushed by the `history` command; `c` copies the full history (plain text) to the clipboard via action_copy_all()
-  export.py         shared activity-history CSV core + headless export path: build_history_csv(), resolve_dest(), resolve_robot(), _run_headless_export(), ExportError — no Textual imports; both the TUI `export` command and `asher --export` call build_history_csv()
+  export.py         shared activity-history CSV core + exit-code contract: build_history_csv(), resolve_dest(), resolve_robot(), parse_days(), EXIT_*, ExportError — no Textual imports; the TUI `export` command and `asher export` both call build_history_csv()
+  headless.py       headless command surface for `asher <command>` — Session/Result/CommandError, the COMMANDS registry, and run(); plain strings only, no Textual, routes model differences through RobotAdapter
   completion.py     pure helpers for command completion: slash popup (slash_matches, enter_completes, render_completion) + inline ghost text (CommandSuggester) — fed by _registry, no Textual imports except the Suggester base class
-  __main__.py       main() entry point
+  __main__.py       main() entry point — argparse subcommands (headless) vs no-args (TUI); `--export` kept as a deprecated alias
   commands/
     base.py         Command ABC, SlashCommand, CommandRegistry
     __init__.py     CommandsMixin — all command classes + registry + dispatch
@@ -72,11 +69,19 @@ 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
   test_history_view.py    format_history_rows()/format_history_text() + HistoryScreen structure, copy-all + Pilot push/dismiss
-  test_export.py          build_history_csv/resolve_dest/resolve_robot/parse_days (pure) + headless _run_headless_export (no Pilot, mocks _connect_headless)
+  test_export.py          build_history_csv/resolve_dest/resolve_robot/parse_days (pure) + the legacy `--export` flag path (no Pilot, mocks _connect_headless)
+  test_headless.py        headless registry/rendering (pure) + every command handler against mock robots + run() exit codes + the argparse subcommand surface
   test_completion.py      slash_matches/enter_completes/render_completion (pure) + Pilot overlay visibility/navigation/accept
 
 .github/workflows/
@@ -88,45 +93,46 @@ 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()`.
 
-## MCP bridge (`/mcp`)
-
-pylitterbot ships an optional MCP server (`pip install pylitterbot[mcp]`, run via `python -m pylitterbot.mcp`) that lets an MCP client like Claude Desktop monitor/control the robot directly. Its own docs configure it with plaintext credentials in the client's JSON config — asher-cli avoids that:
-
-- `/mcp on|off|status` (in `asher/commands/__init__.py`, logic in `asher/mcp_config.py`) adds/removes an entry (named by `mcp_config._SERVER_NAME`) in every `claude_desktop_config.json` this OS's Claude Desktop might read (`mcp_config.config_paths()` — on Windows this includes both the standard installer path and any MSIX/Microsoft Store virtualized path). The entry's `command` is `sys.executable -m asher.mcp_bridge` — never the credentials themselves.
-- `/mcp on` also auto-installs pylitterbot's `mcp` extra via `sys.executable -m pip install "pylitterbot[mcp]==<installed version>"` if the `mcp` package isn't importable yet.
-- `asher/mcp_bridge.py` (console script `asher-mcp-launch`) is what Claude Desktop actually spawns. It reads email/password from the OS keyring at process start, sets them as `LITTER_ROBOT_USERNAME`/`LITTER_ROBOT_PASSWORD` (pylitterbot's expected names — note these differ from asher-cli's own `.env` var `LITTER_ROBOT_USER`) in that process's environment only, then execs `python -m pylitterbot.mcp`. No credentials ever touch the on-disk MCP config.
-- `/mcp on` requires keyring credentials. If none are found but `.env` fallback credentials are set, it copies them into the keyring automatically (since the bridge process can't reliably discover a project-relative `.env` — Claude Desktop controls its working directory, not asher-cli).
-- Requires the `mcp` extra: `uv sync --extra mcp` / `pip install asher-cli[mcp]`. Restart Claude Desktop after toggling for the change to take effect.
-
 ## Command convention
 
-**Normal commands** (no prefix) — robot actions only:
-`clean`, `status`, `info`, `lock`, `unlock`, `sleep`, `wake`, `night-light on|off|auto`, `night-light-brightness <level>`, `panel-brightness <low|medium|high>`, `wait-time <minutes>`, `power on|off`, `rename <name>`, `insight [days|month]`, `sleep-schedule`, `privacy on|off`, `volume <0-100>`, `camera-audio on|off`, `drawer-reset`, `history [count|all]`, `export [days|month]`, `clear`, `help`, `quit`
+Command names, slash-command names, and their args are not listed here — see the `_registry` in `asher/commands/__init__.py`, which is authoritative; `/help` renders it at runtime. `/mcp`'s credential-bridging design is documented in the `mcp-bridge` skill.
 
-**Slash commands** (`/` prefix) — app management only:
-`/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`
+**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.
 
-> The authoritative list is the `_registry` in `asher/commands/__init__.py`; `/help` renders it at runtime. If you add a command, update the tables in `README.md` and the list in `asher/slash-commands/__init__.py`.
+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
 
-Do not add robot-control commands as slash commands, and do not add app-management commands as bare commands.
+**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.
 
 ## Architecture
 
@@ -163,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 |
@@ -175,17 +185,15 @@ LoginScreen (ModalScreen) — available in auth.py but not the primary auth path
 
 ## Robot compatibility
 
-pylitterbot auto-detects robot type. Commands that differ per model are handled by `RobotAdapter` subclasses in `robot_adapters.py` — `make_adapter(robot)` returns the right one based on `type(robot).__name__`. Status-bar reads use `getattr(..., default)` for graceful degradation on older models. Tested API surface:
+pylitterbot auto-detects robot type. Commands that differ per model are handled by `RobotAdapter` subclasses in `robot_adapters.py` — `make_adapter(robot)` returns the right one based on `type(robot).__name__`. Status-bar reads use `getattr(..., default)` for graceful degradation on older models. See the `pylitterbot-ref` skill for the confirmed API surface.
+
+## Colour
 
-- `robot.name`, `robot.serial`, `robot.is_online`
-- `robot.status` (LitterBoxStatus enum)
-- `robot.waste_drawer_level` (0–100)
-- `robot.sleep_mode_enabled`, `robot.panel_lock_enabled`, `robot.night_light_mode_enabled`
-- `robot.last_seen` (datetime)
-- `robot.refresh()`, `robot.start_cleaning()`
-- `robot.set_sleep_mode(bool)`, `robot.set_panel_lockout(bool)`
-- `robot.set_night_light_brightness(int)` or `robot.set_night_light_mode(NightLightMode)`
-- `robot.get_activity_history(limit=int)` → list of `Activity` objects with `.timestamp` and `.action` (`LitterBoxStatus` enum)
+Every colour comes from `asher/theme.py` (Catppuccin Mocha). Reference the **semantic roles** (`theme.MUTED`, `theme.DANGER`, …), not the raw swatches (`theme.OVERLAY0`) and never a hex literal — a re-flavour then only repoints the roles.
+
+- **Rich styles:** `style=theme.ACCENT`, or `style=f"bold {theme.ACCENT}"`. Prefer building `Text` objects with explicit styles over `Text.from_markup` with inline colours.
+- **`ui/style.tcss`:** use the `$asher-*` variables; `AsherApp.get_css_variables()` supplies them.
+- **Inline `CSS`/`DEFAULT_CSS` on a Screen or Widget:** wrap the block in `theme.apply(...)`, which bakes the `$asher-*` values in at class-definition time. A screen mounted on a host app that isn't `AsherApp` (as the Pilot tests do) would otherwise fail to parse.
 
 ## Code comments
 
@@ -213,26 +221,34 @@ Commands that need a confirmed cloud state before showing a result (e.g. sleep/w
 
 **Add a slash command:** create a class inheriting `SlashCommand` (sets `prefix = "/"`), implement `async def run(self, app, args)`, register it, and document in `asher/slash-commands/__init__.py`.
 
+**Add a headless command:** write `async def _my_command(session, args) -> Result` in `asher/headless.py` and add a `HeadlessCommand(...)` entry to `COMMANDS`. The argparse subparser is generated from the registry — nothing to add in `__main__.py`. Build the `Result` with `_rows()` (read commands) or `_outcome()` (actions) so text and JSON stay in step, and raise `CommandError` rather than printing.
+
 **Change poll interval:** `self.set_interval(300, ...)` in `on_mount`.
 
 **Add a new cat state:** add entry to `CATS` dict in `asher/cats.py` (str for static, list[str] for animated), then call `_set_cat("name", "label")`.
 
 **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
 
-```bash
-uv sync                  # install all deps (including dev group)
-uv run poe dev           # run with CSS hot reload (textual --dev)
-uv run poe watch         # run with Python auto-restart on file change (watchfiles)
-uv run poe test          # run test suite
-uv run poe check         # ruff + mypy + pytest (same as CI)
-uv run poe fix           # auto-fix ruff issues
-uv run poe security      # bandit scan (same config the Bandit workflow uses)
-```
+See `[tool.poe.tasks]` in `pyproject.toml` for the full task list (`uv run poe <task>`).
 
 Pre-push hook (`.githooks/pre-push`) runs: ruff check → ruff format --check → mypy. Tests are not in the hook — run them manually.
 
+## Releasing
+
+Follow [README § Releasing](README.md#releasing) exactly, in order: `uv run poe changelog-release X.Y.Z` and commit the result → `uv run bump-my-version bump <part>` (this commits **and tags**) → `git push && git push --tags` → only then cut and push `release/X.Y.Z`.
+
+Regenerate with `changelog-release X.Y.Z`, never plain `changelog` — the workflow lifts the `## [X.Y.Z]` section out of the committed `CHANGELOG.md` verbatim for the GitHub Release body, and a file still saying `## [Unreleased]` fails the release job. That extraction is also why hand-refinements to a section survive into the release notes, and why re-running either changelog task afterwards silently discards them: regeneration always re-derives from commits. Refine last.
+
 ## Testing notes
 
 - Pilot-based integration tests use `app.run_test()` with `await pilot.pause()` before querying widgets