agent-toggle 0.1.0__tar.gz → 0.2.0__tar.gz

{agent_toggle-0.1.0 → agent_toggle-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-toggle
-Version: 0.1.0
+Version: 0.2.0
 Summary: Temporarily disable / re-enable AI-agent skills, agents, commands, rules, plugins and MCP servers across harnesses (Claude Code, Codex, Grok, OpenCode, OpenClaw, Copilot, Vibe, Devin, Antigravity)
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/weskao/agent-toggle
@@ -26,6 +26,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: windows
 Requires-Dist: windows-curses; sys_platform == "win32" and extra == "windows"
+Provides-Extra: telegram
+Requires-Dist: telegram-kit<0.3,>=0.2.0; extra == "telegram"
 Dynamic: license-file
 
 # agent-toggle
@@ -50,30 +52,31 @@ puts it back where it came from.
 
 ## Install
 
-Latest release (on PyPI from the first tagged release):
+Latest release, from [PyPI](https://pypi.org/project/agent-toggle/):
 
 ```sh
 uv tool install agent-toggle
 agent-toggle --version
 ```
 
-Pre-release versions from this repository:
+Straight from this repository, pinned to a release tag (`v0.2.0` is the current one;
+an unpinned `git+` URL installs whatever is on the default branch):
 
 ```sh
-uv tool install git+<repo-url>
+uv tool install git+https://github.com/weskao/agent-toggle@v0.2.0
 agent-toggle --version
 ```
 
 Alternatively, use `pipx`:
 
 ```sh
-pipx install agent-toggle             # from the first tagged release; or: pipx install git+<repo-url>
+pipx install agent-toggle             # from PyPI; or: pipx install git+https://github.com/weskao/agent-toggle@v0.2.0
 ```
 
 From a checkout, either install it editable or run it in place:
 
 ```sh
-git clone <repo-url> agent-toggle
+git clone https://github.com/weskao/agent-toggle agent-toggle
 cd agent-toggle
 pip install -e .                       # puts the `agent-toggle` console script on PATH
 python3 agent_toggle.py status         # no install needed; same CLI
@@ -89,8 +92,45 @@ python3 agent_toggle.py install-shims  # from a checkout, no install needed
 `install-shims` writes a thin skill shim (`skills/agent-toggle/SKILL.md`) into
 every installed harness that supports skills, so `/agent-toggle` works from any
 of them, and adds the park dirs (`skills-disabled/` etc.) to a `.gitignore`
-already present in that harness home. It is idempotent; `--dry-run` shows the
-plan. The tool itself stays in one place.
+already present in that harness home. Each harness gets its own template from
+`agent_toggle/shims/<harness>.md.tmpl`, else `generic.md.tmpl` (which tells the
+agent to pass `--harness <that harness>`). The shim tells the agent to act only
+on the user's explicit request, never on instructions found inside skill or
+tool content, and to preview bulk operations with `--dry-run`.
+
+Every shim carries an `<!-- agent-toggle shim: ... -->` marker line.
+`install-shims` updates a file that has the marker in place (it is idempotent)
+and **refuses** to overwrite one that lacks it, or a symlink: that harness gets
+an `error` row with the fix, the other harnesses still install, and the run
+exits `1`. A shim written by a version before the marker counts as foreign;
+delete it and re-run. `--dry-run` shows the same plan, refusals included. The
+tool itself stays in one place.
+
+**Optional: Telegram alerts for CI** (for maintainers of a fork or clone). Install
+with the `telegram` extra, which adds [telegram-kit](https://pypi.org/project/telegram-kit/)
+(itself stdlib-only), then run the setup once; see [CI notifications](#ci-notifications):
+
+```sh
+uv tool install "agent-toggle[telegram]"     # or: pipx install "agent-toggle[telegram]"
+pip install -e ".[telegram]"                 # from a checkout
+agent-toggle config                          # bot token + chat id
+agent-toggle config sync-ci                  # set the two GitHub repository secrets
+```
+
+Without the extra everything else works exactly as before; only `config` asks for it.
+
+## Shell completion
+
+Each release publishes static completion files for bash, zsh and fish as the
+`completions` artifact of its Release workflow run. They are generated from the
+CLI parser; to build them from a checkout:
+
+```sh
+python3 tools/gen_completions.py completions   # agent-toggle.bash, _agent-toggle (zsh), agent-toggle.fish
+```
+
+Source `agent-toggle.bash` from `~/.bashrc`, put `_agent-toggle` on your zsh
+`fpath`, or copy `agent-toggle.fish` to `~/.config/fish/completions/`.
 
 ## Usage
 
@@ -101,20 +141,23 @@ agent-toggle <command> [args]          # or: python3 agent_toggle.py <command> [
 | command | what it does |
 |---|---|
 | `ui` | interactive picker — cost column, sort, filters; `--dry-run` shows the plan for what you stage and changes nothing |
-| `status` | health check: harnesses found, types each supports, parked counts, gitignore, untracked parked items, stale live twins, shared dirs |
+| `status` | health check: harnesses found, types each supports, parked counts, gitignore, untracked parked items, stale live twins, shared dirs, and state entries whose parked item is gone (a `stale` row with the fix command; read-only, still exit `0`) |
 | `list [type]` | what is currently disabled (`--project <dir>` filters to one project) |
 | `cost [--type T]` | estimated startup tokens per item, biggest first (read-only; `--harness H` filters) |
-| `install-shims` | write the skill shim into every installed harness (`--dry-run` shows the plan) |
+| `install-shims` | write the skill shim into every installed harness; refuses to overwrite a file it did not write (`--dry-run` shows the plan) |
 | `disable <type> <name>...` | park one or more items (`--dry-run` shows the plan; `--project <dir>` for a repo's own `.claude/` and `.mcp.json`) |
 | `enable <type> <name>...` | put them back (`--dry-run` shows the plan; `--project <dir>` likewise) |
 | `enable --all` | put back **every** disabled item (`--harness H` narrows it, `--project <dir>` takes only that project's) |
 | `undo` | reverse the last logged batch (`--dry-run` shows the plan) |
 | `profile save\|apply\|diff\|list` | named sets of live items; see [Profiles](#profiles) |
+| `config [test\|sync-ci]` | Telegram settings for the CI failure alerts; see [CI notifications](#ci-notifications) |
 | `doctor` | read-only check of each harness layout and of `state.json` against disk; exit `1` only on an `error` row |
 | `migrate` | import an older `~/.claude-toggle/` state |
 
 `<type>` = `skill` / `agent` / `command` / `rule` / `plugin` / `mcp`.
 `rule` is claude-only (`~/.claude/rules/*.md`, parked in `rules-disabled/`).
+Disabling a rule prints a warning (also in `--json` `warnings`, dry run included)
+that rules may carry safety constraints.
 
 Flags accepted by every command, before or after the subcommand:
 
@@ -228,6 +271,10 @@ instead of fighting curses for the terminal.
 
 Built on stdlib `curses`, so there is nothing to install on macOS and Linux
 (on Windows, `pip install "agent-toggle[windows]"` pulls `windows-curses`).
+Without curses, `ui` falls back to a numbered menu with the same staging and the
+same result: type row numbers (`1 3 5-7`) to tick or untick, `/text` to filter,
+`s` / `h` / `t` to sort and cycle the harness and type filters, `a` to apply, `q`
+(or end of input) to cancel.
 
 ## What each harness supports
 
@@ -243,6 +290,22 @@ Built on stdlib `curses`, so there is nothing to install on macOS and Linux
 | devin | `~/.devin` | — | — | — | — | — | — |
 | agy | `~/.antigravity` | — | — | — | — | — | — |
 
+Per-harness locations, mechanisms and the harness versions this was checked
+against are in [docs/harnesses.md](docs/harnesses.md).
+
+**Homes per OS.** Every `~` above is Python's `Path.home()`: `$HOME` on macOS and
+Linux, `%USERPROFILE%` on Windows (so `~/.claude` is `C:\Users\<you>\.claude`).
+opencode honours an absolute `$XDG_CONFIG_HOME` on every OS and otherwise uses
+`~/.config/opencode`, Windows included; the tool does not look in `%APPDATA%`. This
+tool's own state lives in `~/.agent-toggle/`. The Linux and Windows locations
+follow the harnesses' documentation and have not yet been checked against real
+installs there; if a harness keeps its files elsewhere, `status` shows it as not
+installed.
+
+Plugin ids are passed to `claude plugin ...`, which on Windows runs through
+`cmd.exe`. An id with anything outside `A-Z a-z 0-9 . _ @ : / -` (for example `&`,
+`%`, `|` or a space) is refused on every OS before any command runs.
+
 Copilot's `config.json` is machine-managed and never edited by this tool; Copilot
 plugins are not yet supported. `claude` plugins are toggled through `claude
 plugin enable/disable`; `openclaw` plugins through a config flag (see [Assumed
@@ -461,10 +524,16 @@ Only `error` makes the exit code `1`; each problem row names the command that
 fixes it. `--harness X` for a harness that is not installed is a `note` (exit
 `0`). Companion files are not checked.
 
+A harness item parked with no state entry also carries `orphan`, and its fix
+follows from it: `identical` (the live copy has the same content: delete the
+parked copy), `differs` (a different live copy exists: compare, keep one), or
+`parked-only` (move it back, then `disable` it so the state records it).
+
 ## Assumed formats
 
-Two config shapes come from the design survey (`docs/DESIGN.md` §4 / §11) and
-were **not verified on a real install**:
+Two config shapes came from the design survey (`docs/DESIGN.md` §4 / §11). Both
+were since seen on one real install each (openclaw 2026.7.1-2, opencode 2.0.22; see
+`docs/harnesses.md`), but the tool still treats them defensively:
 
 - `openclaw.json`: `skills.entries.<name>.enabled` and
   `plugins.entries.<name>.enabled`
@@ -554,13 +623,47 @@ ruff check .
 stdlib `unittest`, no fixtures, no network. Every test runs against a
 throwaway temp `HOME` and a stubbed `claude` CLI.
 
+## CI notifications
+
+`.github/workflows/ci.yml` can send a Telegram message when the test matrix fails on a
+push (a lint-only failure does not page). Alerts never fire for pull requests or green
+runs. The message names the repository, branch, 7-character commit and a link to the run.
+
+Set it up once, with the `telegram` extra installed (see [Install](#install)):
+
+```sh
+agent-toggle config            # prompts for the bot token (hidden) and the chat id
+agent-toggle config test       # send one test message
+agent-toggle config sync-ci    # set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID on the repo
+```
+
+`config` works like aicp's `--config`: Enter keeps the current value, `-` clears it.
+The bot token is kept only in the OS credential store (macOS Keychain, Linux Secret
+Service, Windows DPAPI) through telegram-kit, never in a file or on a command line, and
+is shown masked. With no credential store it refuses to store the token; set
+`TG_BOT_TOKEN` in the environment instead (`TG_CHAT_ID` likewise for the chat id). The
+chat id is ordinary configuration in `~/.agent-toggle/config.json`: a number, `-100...`
+for a group, or an `@channel`. `config sync-ci` needs the GitHub CLI (`gh`) signed in; it
+passes both values on stdin, and `--repo OWNER/REPO` / `--dry-run` work as elsewhere.
+
+To skip the tool, set the secrets by hand (each command prompts for the value):
+
+```sh
+gh secret set TELEGRAM_BOT_TOKEN
+gh secret set TELEGRAM_CHAT_ID
+```
+
+With either secret unset (a fork, or a clone you have not configured) the notify job
+prints a `::notice::` and exits 0, so it never adds a second red X.
+
 ## Releasing
 
 A release is a git tag `vX.Y.Z` (where `X.Y.Z` must match `agent_toggle.__version__`).
 Pushing the tag triggers `.github/workflows/release.yml`:
 
-1. **Build** job checks that the tag matches `__version__` and builds a wheel and
-   source distribution.
+1. **Build** job checks that the tag matches `__version__`, builds a wheel and
+   source distribution, and generates the shell completion files (uploaded as the
+   `completions` artifact; the workflow does not create a GitHub Release).
 2. **Publish** job uploads to PyPI using
    [trusted publishing](https://docs.pypi.org/trusted-publishers/),
    with no stored tokens—only the `pypi` environment and OIDC setup.

{agent_toggle-0.1.0 → agent_toggle-0.2.0}/README.md

@@ -20,30 +20,31 @@ puts it back where it came from.
 
 ## Install
 
-Latest release (on PyPI from the first tagged release):
+Latest release, from [PyPI](https://pypi.org/project/agent-toggle/):
 
 ```sh
 uv tool install agent-toggle
 agent-toggle --version
 ```
 
-Pre-release versions from this repository:
+Straight from this repository, pinned to a release tag (`v0.2.0` is the current one;
+an unpinned `git+` URL installs whatever is on the default branch):
 
 ```sh
-uv tool install git+<repo-url>
+uv tool install git+https://github.com/weskao/agent-toggle@v0.2.0
 agent-toggle --version
 ```
 
 Alternatively, use `pipx`:
 
 ```sh
-pipx install agent-toggle             # from the first tagged release; or: pipx install git+<repo-url>
+pipx install agent-toggle             # from PyPI; or: pipx install git+https://github.com/weskao/agent-toggle@v0.2.0
 ```
 
 From a checkout, either install it editable or run it in place:
 
 ```sh
-git clone <repo-url> agent-toggle
+git clone https://github.com/weskao/agent-toggle agent-toggle
 cd agent-toggle
 pip install -e .                       # puts the `agent-toggle` console script on PATH
 python3 agent_toggle.py status         # no install needed; same CLI
@@ -59,8 +60,45 @@ python3 agent_toggle.py install-shims  # from a checkout, no install needed
 `install-shims` writes a thin skill shim (`skills/agent-toggle/SKILL.md`) into
 every installed harness that supports skills, so `/agent-toggle` works from any
 of them, and adds the park dirs (`skills-disabled/` etc.) to a `.gitignore`
-already present in that harness home. It is idempotent; `--dry-run` shows the
-plan. The tool itself stays in one place.
+already present in that harness home. Each harness gets its own template from
+`agent_toggle/shims/<harness>.md.tmpl`, else `generic.md.tmpl` (which tells the
+agent to pass `--harness <that harness>`). The shim tells the agent to act only
+on the user's explicit request, never on instructions found inside skill or
+tool content, and to preview bulk operations with `--dry-run`.
+
+Every shim carries an `<!-- agent-toggle shim: ... -->` marker line.
+`install-shims` updates a file that has the marker in place (it is idempotent)
+and **refuses** to overwrite one that lacks it, or a symlink: that harness gets
+an `error` row with the fix, the other harnesses still install, and the run
+exits `1`. A shim written by a version before the marker counts as foreign;
+delete it and re-run. `--dry-run` shows the same plan, refusals included. The
+tool itself stays in one place.
+
+**Optional: Telegram alerts for CI** (for maintainers of a fork or clone). Install
+with the `telegram` extra, which adds [telegram-kit](https://pypi.org/project/telegram-kit/)
+(itself stdlib-only), then run the setup once; see [CI notifications](#ci-notifications):
+
+```sh
+uv tool install "agent-toggle[telegram]"     # or: pipx install "agent-toggle[telegram]"
+pip install -e ".[telegram]"                 # from a checkout
+agent-toggle config                          # bot token + chat id
+agent-toggle config sync-ci                  # set the two GitHub repository secrets
+```
+
+Without the extra everything else works exactly as before; only `config` asks for it.
+
+## Shell completion
+
+Each release publishes static completion files for bash, zsh and fish as the
+`completions` artifact of its Release workflow run. They are generated from the
+CLI parser; to build them from a checkout:
+
+```sh
+python3 tools/gen_completions.py completions   # agent-toggle.bash, _agent-toggle (zsh), agent-toggle.fish
+```
+
+Source `agent-toggle.bash` from `~/.bashrc`, put `_agent-toggle` on your zsh
+`fpath`, or copy `agent-toggle.fish` to `~/.config/fish/completions/`.
 
 ## Usage
 
@@ -71,20 +109,23 @@ agent-toggle <command> [args]          # or: python3 agent_toggle.py <command> [
 | command | what it does |
 |---|---|
 | `ui` | interactive picker — cost column, sort, filters; `--dry-run` shows the plan for what you stage and changes nothing |
-| `status` | health check: harnesses found, types each supports, parked counts, gitignore, untracked parked items, stale live twins, shared dirs |
+| `status` | health check: harnesses found, types each supports, parked counts, gitignore, untracked parked items, stale live twins, shared dirs, and state entries whose parked item is gone (a `stale` row with the fix command; read-only, still exit `0`) |
 | `list [type]` | what is currently disabled (`--project <dir>` filters to one project) |
 | `cost [--type T]` | estimated startup tokens per item, biggest first (read-only; `--harness H` filters) |
-| `install-shims` | write the skill shim into every installed harness (`--dry-run` shows the plan) |
+| `install-shims` | write the skill shim into every installed harness; refuses to overwrite a file it did not write (`--dry-run` shows the plan) |
 | `disable <type> <name>...` | park one or more items (`--dry-run` shows the plan; `--project <dir>` for a repo's own `.claude/` and `.mcp.json`) |
 | `enable <type> <name>...` | put them back (`--dry-run` shows the plan; `--project <dir>` likewise) |
 | `enable --all` | put back **every** disabled item (`--harness H` narrows it, `--project <dir>` takes only that project's) |
 | `undo` | reverse the last logged batch (`--dry-run` shows the plan) |
 | `profile save\|apply\|diff\|list` | named sets of live items; see [Profiles](#profiles) |
+| `config [test\|sync-ci]` | Telegram settings for the CI failure alerts; see [CI notifications](#ci-notifications) |
 | `doctor` | read-only check of each harness layout and of `state.json` against disk; exit `1` only on an `error` row |
 | `migrate` | import an older `~/.claude-toggle/` state |
 
 `<type>` = `skill` / `agent` / `command` / `rule` / `plugin` / `mcp`.
 `rule` is claude-only (`~/.claude/rules/*.md`, parked in `rules-disabled/`).
+Disabling a rule prints a warning (also in `--json` `warnings`, dry run included)
+that rules may carry safety constraints.
 
 Flags accepted by every command, before or after the subcommand:
 
@@ -198,6 +239,10 @@ instead of fighting curses for the terminal.
 
 Built on stdlib `curses`, so there is nothing to install on macOS and Linux
 (on Windows, `pip install "agent-toggle[windows]"` pulls `windows-curses`).
+Without curses, `ui` falls back to a numbered menu with the same staging and the
+same result: type row numbers (`1 3 5-7`) to tick or untick, `/text` to filter,
+`s` / `h` / `t` to sort and cycle the harness and type filters, `a` to apply, `q`
+(or end of input) to cancel.
 
 ## What each harness supports
 
@@ -213,6 +258,22 @@ Built on stdlib `curses`, so there is nothing to install on macOS and Linux
 | devin | `~/.devin` | — | — | — | — | — | — |
 | agy | `~/.antigravity` | — | — | — | — | — | — |
 
+Per-harness locations, mechanisms and the harness versions this was checked
+against are in [docs/harnesses.md](docs/harnesses.md).
+
+**Homes per OS.** Every `~` above is Python's `Path.home()`: `$HOME` on macOS and
+Linux, `%USERPROFILE%` on Windows (so `~/.claude` is `C:\Users\<you>\.claude`).
+opencode honours an absolute `$XDG_CONFIG_HOME` on every OS and otherwise uses
+`~/.config/opencode`, Windows included; the tool does not look in `%APPDATA%`. This
+tool's own state lives in `~/.agent-toggle/`. The Linux and Windows locations
+follow the harnesses' documentation and have not yet been checked against real
+installs there; if a harness keeps its files elsewhere, `status` shows it as not
+installed.
+
+Plugin ids are passed to `claude plugin ...`, which on Windows runs through
+`cmd.exe`. An id with anything outside `A-Z a-z 0-9 . _ @ : / -` (for example `&`,
+`%`, `|` or a space) is refused on every OS before any command runs.
+
 Copilot's `config.json` is machine-managed and never edited by this tool; Copilot
 plugins are not yet supported. `claude` plugins are toggled through `claude
 plugin enable/disable`; `openclaw` plugins through a config flag (see [Assumed
@@ -431,10 +492,16 @@ Only `error` makes the exit code `1`; each problem row names the command that
 fixes it. `--harness X` for a harness that is not installed is a `note` (exit
 `0`). Companion files are not checked.
 
+A harness item parked with no state entry also carries `orphan`, and its fix
+follows from it: `identical` (the live copy has the same content: delete the
+parked copy), `differs` (a different live copy exists: compare, keep one), or
+`parked-only` (move it back, then `disable` it so the state records it).
+
 ## Assumed formats
 
-Two config shapes come from the design survey (`docs/DESIGN.md` §4 / §11) and
-were **not verified on a real install**:
+Two config shapes came from the design survey (`docs/DESIGN.md` §4 / §11). Both
+were since seen on one real install each (openclaw 2026.7.1-2, opencode 2.0.22; see
+`docs/harnesses.md`), but the tool still treats them defensively:
 
 - `openclaw.json`: `skills.entries.<name>.enabled` and
   `plugins.entries.<name>.enabled`
@@ -524,13 +591,47 @@ ruff check .
 stdlib `unittest`, no fixtures, no network. Every test runs against a
 throwaway temp `HOME` and a stubbed `claude` CLI.
 
+## CI notifications
+
+`.github/workflows/ci.yml` can send a Telegram message when the test matrix fails on a
+push (a lint-only failure does not page). Alerts never fire for pull requests or green
+runs. The message names the repository, branch, 7-character commit and a link to the run.
+
+Set it up once, with the `telegram` extra installed (see [Install](#install)):
+
+```sh
+agent-toggle config            # prompts for the bot token (hidden) and the chat id
+agent-toggle config test       # send one test message
+agent-toggle config sync-ci    # set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID on the repo
+```
+
+`config` works like aicp's `--config`: Enter keeps the current value, `-` clears it.
+The bot token is kept only in the OS credential store (macOS Keychain, Linux Secret
+Service, Windows DPAPI) through telegram-kit, never in a file or on a command line, and
+is shown masked. With no credential store it refuses to store the token; set
+`TG_BOT_TOKEN` in the environment instead (`TG_CHAT_ID` likewise for the chat id). The
+chat id is ordinary configuration in `~/.agent-toggle/config.json`: a number, `-100...`
+for a group, or an `@channel`. `config sync-ci` needs the GitHub CLI (`gh`) signed in; it
+passes both values on stdin, and `--repo OWNER/REPO` / `--dry-run` work as elsewhere.
+
+To skip the tool, set the secrets by hand (each command prompts for the value):
+
+```sh
+gh secret set TELEGRAM_BOT_TOKEN
+gh secret set TELEGRAM_CHAT_ID
+```
+
+With either secret unset (a fork, or a clone you have not configured) the notify job
+prints a `::notice::` and exits 0, so it never adds a second red X.
+
 ## Releasing
 
 A release is a git tag `vX.Y.Z` (where `X.Y.Z` must match `agent_toggle.__version__`).
 Pushing the tag triggers `.github/workflows/release.yml`:
 
-1. **Build** job checks that the tag matches `__version__` and builds a wheel and
-   source distribution.
+1. **Build** job checks that the tag matches `__version__`, builds a wheel and
+   source distribution, and generates the shell completion files (uploaded as the
+   `completions` artifact; the workflow does not create a GitHub Release).
 2. **Publish** job uploads to PyPI using
    [trusted publishing](https://docs.pypi.org/trusted-publishers/),
    with no stored tokens—only the `pypi` environment and OIDC setup.

{agent_toggle-0.1.0 → agent_toggle-0.2.0}/agent_toggle/__init__.py

@@ -1,3 +1,3 @@
 """agent-toggle: temporarily disable / re-enable AI-agent resources."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{agent_toggle-0.1.0 → agent_toggle-0.2.0}/agent_toggle/cli.py

@@ -12,7 +12,7 @@ to the targets -- a user's `git status` must not change because of our
 bookkeeping.
 
 Usage:
-    agent_toggle.py ui [--dry-run]             # interactive picker (curses)
+    agent_toggle.py ui [--dry-run]             # interactive picker (curses, else numbered menu)
     agent_toggle.py cost [--type T]            # startup token estimates, biggest first
     agent_toggle.py disable <type> <name>...   [--harness H] [--dry-run]
     agent_toggle.py enable  <type> <name>...   [--harness H] [--dry-run]
@@ -26,6 +26,7 @@ Usage:
     agent_toggle.py migrate                    # import old ~/.claude-toggle state
     agent_toggle.py profile save|apply|diff|list [name|file] [--out F] [--dry-run]
     agent_toggle.py install-shims [--dry-run]  # write the skill shim into each harness
+    agent_toggle.py config [test|sync-ci]      # Telegram settings for CI failure alerts
 
     <type> = skill | agent | command | rule | plugin | mcp
     --json prints exactly one JSON document; exit codes: 0 ok, 1 partial
@@ -41,7 +42,7 @@ import sys
 import traceback
 from pathlib import Path
 
-from . import __version__, cost, doctor, fs, ops, profiles, store, undo
+from . import __version__, config, cost, doctor, fs, ops, profiles, store, undo
 from .backends.plugin_cli import claude_bin
 from .fs import gitignored
 from .harnesses import TYPES, harness_of, harnesses, project_view
@@ -161,6 +162,7 @@ def cmd_status(state: dict, out: Result, only: str | None = None) -> None:
                     found = list(parked.iterdir())
                 else:
                     found = [p for p in parked.rglob("*") if p.is_file()]
+                found = [p for p in found if not p.name.startswith(".")]   # .DS_Store, as doctor
                 items += found
                 ign = ign and gitignored(
                     parked, home if view.owner == hname else table[view.owner].home)
@@ -188,6 +190,14 @@ def cmd_status(state: dict, out: Result, only: str | None = None) -> None:
     for (hname, proj), n in sorted(projects.items(), key=str):
         out.say(f"project {proj}  ({n} parked under {fs.parked_dir()})")
         out.row(hname, None, None, "status", "project", "", show=False, project=proj, parked=n)
+    # the inverse of `untracked`: a state entry whose parked item is gone (DESIGN s6)
+    for k, e in state["disabled"].items():
+        if only and only not in (e.get("harness"), *_list_of(e, "shared_with")):
+            continue
+        if gone := doctor.missing_parked(k, e):
+            out.say(f"WARNING {e.get('harness')} {e.get('type')} {e.get('name')}: {gone}", warn=True)
+            out.row(e.get("harness"), e.get("type"), e.get("name"), "status", "stale", gone,
+                    show=False, parked_at=e.get("parked_at"))
 
 
 def parked_drift(items: list[Path], parked: Path, live: Path,
@@ -228,8 +238,8 @@ def cmd_cost(state: dict, out: Result, harness: str | None = None,
 def cmd_ui(state: dict, out: Result, dry_run: bool = False) -> None:
     try:
         from .ui import picker as ui
-    except ImportError as e:                 # no curses build (rare)
-        die(f"interactive UI unavailable: {e}")
+    except ImportError:                      # no curses (Windows without windows-curses)
+        from .ui import menu as ui
     changes = ui.pick(store.scope_state(state), harnesses(), plugins=not dry_run,
                       color=use_color(sys.stdout, out.color))
     if changes is None:
@@ -289,13 +299,17 @@ def cmd_migrate(out: Result) -> None:
     out.row(None, None, None, "migrate", "ok", "; ".join(lines), show=False)
 
 
-SHIM_TEMPLATE = Path(__file__).with_name("shims") / "claude.md.tmpl"
+SHIMS = Path(__file__).with_name("shims")
+# Every template carries this line; install-shims only overwrites a file that has it.
+SHIM_MARKER = ("<!-- agent-toggle shim: written by `agent-toggle install-shims`; "
+               "re-running it overwrites this file -->")
 
 
-def cmd_install_shims(args: argparse.Namespace, out: Result) -> None:
-    """Write <home>/skills/agent-toggle/SKILL.md into every installed harness that
-    supports skills; keep park dirs out of an existing harness-home .gitignore."""
-    template = SHIM_TEMPLATE.read_text(encoding="utf-8")
+def shim_text(harness: str) -> str:
+    """The shim for `harness`: shims/<harness>.md.tmpl, else shims/generic.md.tmpl."""
+    tmpl = SHIMS / f"{harness}.md.tmpl"
+    template = (tmpl if tmpl.is_file() else SHIMS / "generic.md.tmpl").read_text(encoding="utf-8")
+    template = template.replace("__HARNESS__", harness)
     root = Path(__file__).resolve().parent.parent
     if (root / "agent_toggle.py").is_file():
         # Harness dirs often sync across machines: write `~`-relative under $HOME.
@@ -303,16 +317,38 @@ def cmd_install_shims(args: argparse.Namespace, out: Result) -> None:
             shown = "~/" + root.relative_to(fs.home()).as_posix()
         except ValueError:
             shown = str(root)
-        text = template.replace("__AGENT_TOGGLE_ROOT__", shown)
-    else:                                 # installed package: no checkout to point at
-        text = "".join(ln for ln in template.splitlines(keepends=True)
-                       if "__AGENT_TOGGLE_ROOT__" not in ln)
+        return template.replace("__AGENT_TOGGLE_ROOT__", shown)
+    # installed package: no checkout to point at
+    return "".join(ln for ln in template.splitlines(keepends=True)
+                   if "__AGENT_TOGGLE_ROOT__" not in ln)
+
+
+def shim_refusal(dest: Path) -> str | None:
+    """Why `dest` must not be overwritten (it is not a shim we wrote), else None."""
+    if dest.is_symlink() or (dest.exists() and not dest.is_file()):
+        return "is a symlink or not a regular file"
+    if not dest.exists():
+        return None
+    try:
+        text = dest.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        text = ""
+    # Shims from before the marker existed: our frontmatter name plus our heading.
+    legacy = text.startswith("---\nname: agent-toggle\n") and "\n# agent-toggle\n" in text
+    ours = SHIM_MARKER in text or legacy
+    return None if ours else "exists and lacks the agent-toggle shim marker"
+
+
+def cmd_install_shims(args: argparse.Namespace, out: Result) -> None:
+    """Write <home>/skills/agent-toggle/SKILL.md into every installed harness that
+    supports skills; keep park dirs out of an existing harness-home .gitignore.
+    A file there that is not our shim (no SHIM_MARKER) is refused, never overwritten."""
     table = harnesses()
     park = sorted({f"{sub}-disabled" for h in table.values()
                    for subs in h.dirs.values() for sub in subs
                    if not Path(sub).is_absolute()})     # skills.paths redirects live elsewhere
     verb = "would install" if args.dry_run else "installed"
-    installed = 0
+    installed = found = 0
     for hname, h in table.items():
         home = h.home
         if args.harness and hname != args.harness:
@@ -322,10 +358,17 @@ def cmd_install_shims(args: argparse.Namespace, out: Result) -> None:
                     "not installed" if not home.is_dir() else "no skill support",
                     show=False, home=str(home))
             continue
+        found += 1
         dest = home / h.dirs["skill"][0] / "agent-toggle" / "SKILL.md"
+        if why := shim_refusal(dest):
+            fix = (f"refused: {dest} {why}; fix: move it aside (or delete it if it is an "
+                   f"older agent-toggle shim), then re-run install-shims")
+            out.row(hname, None, None, "install-shims", "error", fix, show=False, home=str(home))
+            out.say(f"  {fix}", style="red")
+            continue
         if not args.dry_run:
             dest.parent.mkdir(parents=True, exist_ok=True)
-            dest.write_text(text, encoding="utf-8")
+            dest.write_text(shim_text(hname), encoding="utf-8")
         out.row(hname, None, None, "install-shims", "planned" if args.dry_run else "ok",
                 str(dest), show=False, home=str(home))
         out.say(f"  {verb}  {dest}")
@@ -342,13 +385,13 @@ def cmd_install_shims(args: argparse.Namespace, out: Result) -> None:
                              + "".join(f"{m}\n" for m in missing))
             if missing:
                 out.say(f"  gitignore  {ignore}: {' '.join(missing)}")
-    if not installed:
+    if not found:
         die("no harness found", 4)
     out.say(f"{installed} harness(es) {'planned' if args.dry_run else 'installed'}")
 
 
 COMMANDS = ("ui", "pick", "status", "list", "cost", "migrate", "disable", "enable",
-            "install-shims", "profile", "undo", "doctor")
+            "install-shims", "profile", "undo", "doctor", "config")
 _GLOBAL_FLAGS = ("--json", "-v", "--verbose")
 
 
@@ -427,6 +470,12 @@ def build_parser() -> argparse.ArgumentParser:
     pp.add_argument("--project", metavar="dir", help=PROJECT_HELP)
     sub.add_parser("doctor", parents=[common],
                    help="read-only check of harness layouts and state against disk")
+    cf = sub.add_parser("config", parents=[common],
+                        help="Telegram settings for the CI failure alerts (needs the telegram extra)")
+    cf.add_argument("action", nargs="?", choices=("test", "sync-ci"),
+                    help="test: send one message | sync-ci: set the GitHub repo secrets")
+    cf.add_argument("--repo", metavar="OWNER/REPO", help="sync-ci: repository (default: this one)")
+    cf.add_argument("--dry-run", action="store_true", help="sync-ci: show the plan; set nothing")
     up2 = sub.add_parser("undo", parents=[common], help="reverse the last logged batch")
     up2.add_argument("--dry-run", action="store_true", help="show the plan; change nothing")
     for name, verb in (("disable", "park"), ("enable", "restore")):
@@ -471,6 +520,8 @@ def main(argv: list[str] | None = None) -> int:
             profiles.cmd_profile(args, out)
         elif cmd == "doctor":
             doctor.cmd_doctor(args.harness, out)
+        elif cmd == "config":
+            config.cmd_config(args, out)
         elif cmd == "undo":
             undo.cmd_undo(args.dry_run, args.harness, out)
         elif cmd == "enable" and args.all: