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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-toggle
-Version: 0.2.0
+Version: 0.6.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
@@ -27,7 +27,7 @@ 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"
+Requires-Dist: telegram-kit<0.3,>=0.2.2; extra == "telegram"
 Dynamic: license-file
 
 # agent-toggle
@@ -59,18 +59,18 @@ uv tool install agent-toggle
 agent-toggle --version
 ```
 
-Straight from this repository, pinned to a release tag (`v0.2.0` is the current one;
+Straight from this repository, pinned to a release tag (`v0.5.1` is the current one;
 an unpinned `git+` URL installs whatever is on the default branch):
 
 ```sh
-uv tool install git+https://github.com/weskao/agent-toggle@v0.2.0
+uv tool install git+https://github.com/weskao/agent-toggle@v0.5.1
 agent-toggle --version
 ```
 
 Alternatively, use `pipx`:
 
 ```sh
-pipx install agent-toggle             # from PyPI; or: pipx install git+https://github.com/weskao/agent-toggle@v0.2.0
+pipx install agent-toggle             # from PyPI; or: pipx install git+https://github.com/weskao/agent-toggle@v0.5.1
 ```
 
 From a checkout, either install it editable or run it in place:
@@ -97,6 +97,12 @@ already present in that harness home. Each harness gets its own template from
 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`.
+OpenCode's shim goes into the first `skills.paths` dir when one is set (and its
+parent exists), else `skills/`. OpenCode also scans `~/.claude/skills` and
+`~/.agents/skills`: when one of them already holds the very same shim text, the
+OpenCode shim is skipped (`covered by <path>`); a different shim there (the
+claude one, whose default harness is `claude`) is noted and OpenCode's own is
+still written.
 
 Every shim carries an `<!-- agent-toggle shim: ... -->` marker line.
 `install-shims` updates a file that has the marker in place (it is idempotent)
@@ -113,11 +119,14 @@ with the `telegram` extra, which adds [telegram-kit](https://pypi.org/project/te
 ```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                          # settings menu: bot token + chat id live under Notifications
 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.
+Without the extra everything else works exactly as before. Only `config test`,
+`config sync-ci` (both exit `4` without it) and the Telegram rows of the
+[settings menu](#settings--config-menu) need it; bare `config` still opens, and
+those rows read `install agent-toggle[telegram]`.
 
 ## Shell completion
 
@@ -140,20 +149,24 @@ 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 |
+| `ui` (alias `pick`) | interactive picker — harness tabs, type groups, cost bars, search, sort, profiles (`p`); `--dry-run` shows the plan for what you stage and changes nothing; `--project <dir>` picks in a repo's own scope; see [Interactive picker](#interactive-picker) |
 | `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; refuses to overwrite a file it did not write (`--dry-run` shows the plan) |
+| `cost [--type T]` | estimated startup tokens per item, biggest first (read-only; `--harness H` filters; `--project <dir>` prices a repo's `.claude/` and `.mcp.json` instead of user scope) |
+| `install-shims` | write the skill shim into every installed harness that is on in the settings (an off one is skipped unless named with `--harness`); refuses to overwrite a file it did not write (`--dry-run` shows the plan); on a terminal, then asks y/n for each problem `doctor` can fix (see [Fixing](#fixing)) |
 | `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 |
+| `config` | settings menu (curses, else a numbered list); `config --json` lists every setting and the package version; see [Settings & config menu](#settings--config-menu) |
+| `config test\|sync-ci` | send one Telegram test message / set the GitHub CI secrets; needs the `[telegram]` extra; see [CI notifications](#ci-notifications) |
+| `help [command]` | styled help; `help ui` = `--help ui` = `ui --help`; see [Help](#help) |
+| `doctor` | check each harness layout and `state.json` against disk; exit `1` only on an `error` row; on a terminal, asks y/n per fix it can run itself |
 | `migrate` | import an older `~/.claude-toggle/` state |
 
+Every command also works with a leading `--` (`agent-toggle --status`, `--help`, `--config`); this README uses the plain form.
+
 `<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)
@@ -169,9 +182,12 @@ Flags accepted by every command, before or after the subcommand:
   `{ExceptionType}: {message}` -- always emit it, with `"ok": false`.
   Exception: `--help` / `--version` print plain text even with `--json`, and
   `ui` is interactive so it rejects `--json` (exit 2).
-- `--project <dir>` (`disable` / `enable` / `enable --all` / `list` / `profile
+- `--project <dir>` (`disable` / `enable` / `enable --all` / `list` / `ui` / `cost` / `profile
   save|apply|diff`) switches to project scope; see [Project scope](#project-scope).
 - `--version` prints the version.
+- `AGENT_TOGGLE_CLI_TIMEOUT=<seconds>` overrides the timeout of every `claude` CLI call
+  (default 30 s for read-only `plugin list`, 120 s for every other call); a
+  non-positive or non-numeric value is ignored with a warning.
 - `-v` / `--verbose` (or `AGENT_TOGGLE_DEBUG=1`) adds a traceback on stderr for
   unexpected errors; otherwise they are a single `error:` line.
 - `--color auto|always|never` sets ANSI color for human output: green ok, red errors,
@@ -180,6 +196,8 @@ Flags accepted by every command, before or after the subcommand:
   and stays monochrome when the terminal has no colors). `--json` is never colored.
   `never` turns it off and `always` forces it even when piped; `auto` (default) checks
   `NO_COLOR`, then `FORCE_COLOR`, then `TERM=dumb`, and otherwise colors only on a TTY.
+  Precedence: `--color` flag > `AGENT_TOGGLE_COLOR` > the `color` [setting](#settings--config-menu)
+  > `auto`; `NO_COLOR` still wins over `auto`.
   `always` still stays plain on a Windows console that cannot do ANSI.
 
 Extra row fields: `list` rows carry `at`, `mechanism`, `companions`; `cost` rows
@@ -224,57 +242,186 @@ A colon addresses nesting: `demo:batch` is `commands/demo/batch.md`.
 ## Interactive picker
 
 ```sh
-agent-toggle ui
+agent-toggle ui          # alias: agent-toggle pick
+agent-toggle             # same, on a terminal; elsewhere prints help and exits 2
 ```
 
 ```
- filter: telegram█
- *[x]    (92)  claude   command telegram-summary
-  [ ]    (61)  claude   skill   telegram-display
-  [x]      48   claude   skill   telegram-group-send
-  [x]      20   claude   mcp     telegram-example
-
- 4 shown  |  ~68 tok  |  harness:all type:all sort:name  |  1 staged -- Enter to apply
- Tab tick  Enter apply  Esc cancel  s sort  h/t filter  ? keys  / type to filter
+ agent-toggle  v0.5.1                                 5 resources · ~6.3k tok live · 1 staged (+300 tok)
+ All 5 │ claude 4 │ codex 2
+ 🔍 Type to search (name, path, fuzzy)                                           type: All  sort: name
+ Skills 3 ─────────────────────────────────────────────────────────────│ beta
+  ●   alpha                             claude      1.2k █▎            │
+› ● + beta                              claude     (300) ▎             │ harness    claude
+  ●   zeta                              claude      5.0k █████         │ type       skill
+ Agents 1 ─────────────────────────────────────────────────────────────│ state      ○ parked
+  ●   gamma                             claude        50 ▏     +shared │            staged → live
+ Commands 1 ───────────────────────────────────────────────────────────│ path       ~/.claude/skills-disabled/beta
+  ●   delta                             codex         10 ▏             │ cost       0 now; ~300 tok if restored
+                                                                       │ since      2026-09-19 10:00:00
+ 5 of 5 shown · 2/5
+ Space toggle  Enter apply  Esc cancel  ? help  / search  ←→ harness  t type  s sort  p profile  a all
 ```
 
-The number column is the estimated startup tokens (chars / 4, about +-25 %);
-a parked row shows `(N)`, what restoring it would load. Plugins appear as rows
-too (via `claude plugin list --json`; skipped under `ui --dry-run`, which never
-shells out).
+What is on screen:
+
+- **Title bar**: version and a summary (resources, live tokens, staged changes and their token effect).
+- **Harness tab bar**: `All` plus each enabled harness, with counts. Harnesses switched off in
+  the [settings](#settings--config-menu) are hidden.
+- **Rows grouped by type** (Skills, Agents, Commands, ...) under a heading with a count.
+  `●` is live, `○` parked (`*` / `o` in ASCII); a `+` / `-` before the name marks a staged change,
+  and `+shared` marks a directory another harness also reads.
+- **Cost column**: estimated startup tokens (chars / 4, about +-25 %) with a colored bar. A parked
+  row shows `(N)` in brackets, what restoring it would load. Plugins appear as rows too (via
+  `claude plugin list --json`; skipped under `ui --dry-run`, which never shells out).
+- **Detail pane** at 100 columns or wider: the file's frontmatter `description` (skills,
+  agents, commands, rules), then harness, type, state, staged, path, cost, since,
+  mechanism, and what it is shared with.
+- **Search bar** (🔍; plain `/` on terminals that cannot draw emoji: the Linux console, the legacy
+  Windows console, non-UTF-8 locales) under the tabs, always visible.
+- **Per-harness colors** on the harness column, matching `ai-accounts list` (claude orange on
+  256-color terminals, codex cyan, agy blue, grok yellow, vibe green, copilot red, opencode magenta).
+- **Key-chip footer** and a `?` help overlay. A spinner shows on stderr while the list loads
+  (only on a TTY; off with `NO_COLOR`). The mouse wheel scrolls (xterm alternate-scroll mode).
 
 | key | action |
 |---|---|
-| `s` | cycle sort: name, cost (biggest first) |
-| `h` | cycle the harness filter |
+| `Space` | toggle the highlighted row (live / parked) and stay on it (while filtering, `Space` types a space) |
+| `Tab` | toggle the highlighted row and advance to the next |
+| `Enter` | apply every staged change (with `--dry-run`: show the plan) |
+| `Esc` / `Ctrl-C` | cancel; nothing is applied |
+| `↑` `↓` `PgUp` `PgDn` `Home` `End`, `Ctrl-P` / `Ctrl-N` | move |
+| `/` | start a search; any other non-command letter starts one too. Terms are ANDed, case-insensitive, and match the harness/type/name and the path; when nothing matches, letters-in-order (fuzzy) is tried: `ctxmd` finds `context-md`, and the bar says `≈ fuzzy match` |
+| `Backspace` / `Ctrl-U` | delete one character / clear the filter |
+| `←` `→` | switch harness tab (also while typing a filter); `0` = All, `1`-`9` = that tab, `h` = next tab |
 | `t` | cycle the type filter |
+| `s` | cycle sort: name, cost (biggest first); applies within each type group |
+| `p` | profiles: stage a saved one, or save the live state (see below) |
 | `?` | show the key list |
-| `/` | start typing a filter |
-| any other printable character | appends to the filter (terms are ANDed, case-insensitive) |
-| `Backspace` / `Ctrl-U` | delete one character / clear the filter |
-| `↑` `↓` / `Ctrl-P` `Ctrl-N` | move; `PgUp`/`PgDn` jump a screen |
-| `Tab` | tick / untick the highlighted row |
-| `Enter` | apply every staged change (with `--dry-run`: show the plan) |
-| `Esc` / `Ctrl-C` | cancel — nothing is applied |
+| `a` / `Ctrl-A` | toggle every visible row |
+
+The command keys (`t`, `s`, `p`, `h`, `a`, `0`-`9`, `?`) act only while no filter is active.
+Press `/` first to type a filter that begins with one of them; once the filter is non-empty,
+every letter just types.
 
-`s`, `h`, `t` and `?` are commands while the filter is empty. Press `/` first
-to type a filter that begins with one of them (the example above is typed
-`/telegram`); once the filter is non-empty, every letter just types.
+The start view (sort, harness tab, type filter) comes from the `picker_sort`, `picker_harness`
+and `picker_type` [settings](#settings--config-menu). A profile skips harnesses that are hidden
+and counts those items as `hidden by settings`; `ui --harness <name>` shows that harness even
+when it is switched off.
 
-The checkbox shows the **enabled** state: `[x]` is live, `[ ]` is parked. A
-`*` marks a row you changed.
+`p` opens a prompt over the list of saved profiles: type a number or name (or
+`apply <name>`) and Enter to **stage** that profile's changes (only the items it
+mentions; ones this machine lacks are skipped), then Enter in the picker applies
+them like any other change, so `ui --dry-run` previews a profile and a stray
+`p` changes nothing. `save <name>` writes the live state (not your staged changes) as
+a profile, with the same name rules and project scope as `profile save`; it is
+off under `--dry-run`. Esc closes the prompt.
 
 Nothing happens while the picker is open. Changes are staged, the screen is
-torn down, and only then do the real operations run — so their output (which
+torn down, and only then do the real operations run, so their output (which
 companion files moved, which were kept because they are shared) is readable
 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.
+same result. It is grouped by type, with the same glyphs and color: type row
+numbers (`1 3 5-7`) to tick or untick, `/text` to filter (`/` alone clears it),
+`s` / `h` / `t` to sort and cycle the harness and type filters, `p` to list profiles,
+`p <number|name>` to stage one and `p save <name>` to save the live state, `a` to
+apply, `q` (or end of input) to cancel.
+
+The chrome (title, tabs, footer, help, detail labels) is translated when `language` is
+`zh-TW`; item names and paths are never translated.
+
+## Settings & config menu
+
+```sh
+agent-toggle config           # or: agent-toggle --config
+agent-toggle config --json    # every setting with its value and source, plus the package version; the token is masked
+```
+
+`config` opens the settings menu: curses on a terminal, a numbered list otherwise. The title
+shows the package version. Each change is saved the moment you make it. On a numbered list,
+end of input, `q` or an empty line exits `0`
+(safe in CI; note it reads piped digits, so an open stdin pipe waits).
+
+| group | rows |
+|---|---|
+| General | Check for updates, Color, Language, Default harness |
+| Harnesses | one On/Off per harness, with `found ~/.x` or `not on this machine` |
+| Picker | default sort, harness filter, type filter |
+| Notifications | Telegram bot token (masked), Telegram chat ID |
+| Tools | Health check (`doctor`; then asks y/n per fix it can run), Install shims, Undo last change (asks y/n), Send test message, Sync CI secrets (asks y/n); their output shows in an overlay |
+
+Keys: `↑` `↓` move (wraps, skips headings), `←` `→` cycle a value, `Enter` / `Space` change or run
+the row, `r` reset the row, `R` reset everything (asks y/n), `q` / `Esc` / `Ctrl-C` quit. In an
+inline text field `Enter` commits, `Esc` cancels and `-` then `Enter` clears. A dim `env` tag
+marks a row whose value is overridden by an environment variable. The Language row switches the
+UI live.
+
+Settings live in `~/.agent-toggle/config.json` (mode `0600`, written atomically; keys the
+tool does not know are kept):
+
+| key | values | default | env override |
+|---|---|---|---|
+| `update_check` | `true` / `false` | `true` | `AGENT_TOGGLE_UPDATE_CHECK` |
+| `color` | `auto` / `always` / `never` | `auto` | `AGENT_TOGGLE_COLOR` |
+| `language` | `en` / `zh-TW` | `en` | `AGENT_TOGGLE_LANG` |
+| `default_harness` | a harness name | `claude` | `AGENT_TOGGLE_DEFAULT_HARNESS` |
+| `harness.<name>` | `true` / `false`, for `claude` `codex` `grok` `opencode` `openclaw` `copilot` `vibe` `devin` `agy` | `true` | |
+| `picker_sort` | `name` / `cost` | `name` | |
+| `picker_harness` | `all` or a harness name | `all` | |
+| `picker_type` | `all` or a type | `all` | |
+| `telegram_chat_id` | a number, `-100...` or `@channel` | unset | `TG_CHAT_ID` |
+
+The bot token is not in this file: it is in the OS keystore through telegram-kit
+(`TG_BOT_TOKEN` overrides it). An environment variable always beats the file; an
+invalid value in either is ignored with one warning on stderr.
+
+- `harness.<name>` off hides that harness from `ui`, `list`, `status` and `cost` (`list`, `status` and
+  `cost` print a dim `N hidden by settings` note, and `--json` carries it in `warnings`; an item shared with a harness that is still
+  on stays listed) and `install-shims` skips it; an explicit
+  `--harness <name>` still reaches it, `ui --harness <name>` included.
+- `default_harness` is what `disable` / `enable` act on without `--harness`, even when that
+  harness is switched off (with one warning on stderr);
+  `disable` / `enable --project` without `--harness` still default to `claude`.
+- `language` translates the config menu, help, update prompt and picker chrome; command output stays English.
+- Bare `config` works without the `[telegram]` extra; `config test` and `config sync-ci` are
+  unchanged and need it (exit `4` without it).
+
+## Update check
+
+On every invocation (unless disabled) agent-toggle checks PyPI for a newer release. It starts
+before the command and is offered after it, on every exit path; it overlaps the command and waits at most 0.8 s afterwards.
+
+- **On a terminal** (stdin and stderr are TTYs, no `--json`): a panel on stderr, "agent-toggle X
+  is available (you have Y)", with `Update now`, `Skip` and `Skip until next version`, a release
+  notes link, and `↑` `↓` `Enter` `q`. `Update now` runs `uv tool upgrade agent-toggle`; if that
+  fails you get a yellow warning with the command to run yourself.
+- **Off a terminal**: two stderr lines, `agent-toggle X is available (you have Y)` and
+  `  uv tool upgrade agent-toggle`.
+- It never changes the exit code or stdout, so `--json` output stays one document.
+
+It is one `GET https://pypi.org/pypi/agent-toggle/json` on a background thread with a 0.8 s
+timeout, cached for 10 minutes in `~/.agent-toggle/update-check.json`. Nothing is sent beyond a
+normal HTTP request with the User-Agent `agent-toggle-update-check`. See `SECURITY.md`
+for the hardening. To turn it off, set `AGENT_TOGGLE_UPDATE_CHECK=0` or the `update_check` setting
+to off (the settings menu's "Check for updates").
+
+## Help
+
+```sh
+agent-toggle help               # grouped overview
+agent-toggle help config        # one command; same as: --help config, config --help
+```
+
+Help is grouped as Toggle (`ui`, `disable`, `enable`, `undo`, `profile`), Inspect (`status`,
+`list`, `cost`, `doctor`) and Setup (`config`, `install-shims`, `migrate`), with the global
+options, examples and exit codes. `help <command>` shows that command's usage, arguments,
+options and examples; `help help` is the overview, `help version` shows how to print the version,
+and an unknown command exits `2`. It honours `--color` and `NO_COLOR`, and is
+translated when `language` is `zh-TW`.
 
 ## What each harness supports
 
@@ -330,16 +477,19 @@ rather than guessing.
 ### Shared directories
 
 OpenCode may read skills from another harness's directory through
-`opencode.json` → `skills.paths` (absolute, `~/`-prefixed or relative-to-the-
-opencode-dir entries; a bare `~` or `$HOME/...` is not expanded, and
-`opencode.jsonc` is not read). Such a directory is **one** item, filed under
+`opencode.json` → `skills.paths` (absolute, `~`, `$HOME/...`
+and `${HOME}/...` entries; read from `opencode.json`, else `opencode.jsonc`;
+relative entries are skipped, since OpenCode resolves them against the session
+directory). OpenCode also always scans `~/.claude/skills` and `~/.agents/skills`,
+so claude's skills count as shared with it. Such a directory is **one** item, filed under
 its owner (the harness whose home really holds it): it is
 parked once, tracked once, and every row reports `shared_with`, the other
 harnesses it also affects. `status` prints `shared dir with: ...`.
 
 If the live directory carries `.synced-from-*` markers, a sync job may
-re-create what you parked; `status` warns about it. Park in the source harness
-instead. The warning is printed once per harness that views the directory.
+re-create what you parked; `status` and `disable` warn about it. Park in the
+source harness instead. The warning is printed once per real directory, naming
+every harness that views it.
 
 ## Companion files
 
@@ -461,8 +611,10 @@ bulk operations with `--dry-run`.
 Claude layout only: `--harness codex --project ...` exits `4`, as does a
 missing directory or one with neither `.claude/` nor `.mcp.json`. `$HOME`, its
 ancestors, the tool's own state dir and the harness homes are refused (exit
-`2`) -- that is user scope. `list` and `enable --all` run the same checks. `cost` and
-`ui` are user-scope only.
+`2`) -- that is user scope. `list`, `enable --all`, `cost` and `ui` run the same
+checks. `cost --project` prices that project's items only (no plugins), and
+`ui --project` stages and applies in project scope (its `p` key saves and applies
+project profiles).
 
 ```sh
 agent-toggle disable skill demo-skill --project .
@@ -485,18 +637,21 @@ agent-toggle enable --all --project .
   Restore with that command, or `git checkout`; do not commit the deletion if
   the repo is shared.
 - `.mcp.json` is edited directly (no `claude` CLI) and must be **strict JSON**:
-  a BOM, comments or trailing commas are refused. `disable` rewrites the file in
-  its detected layout (tabs or 2 spaces, LF or CRLF) and saves a verbatim backup
-  at `mcp-backups/<sha8>__claude__<name>.json` (mode `0600`; it holds the file
-  text, so it may hold auth headers). `enable` restores the file byte for byte
-  if it is unchanged since the disable, otherwise merges the entry back in and
-  reformats.
-- Moves across filesystems fall back to copy + delete (not atomic). An empty
-  `parked/<sha8>/*-disabled` dir may remain after `enable`; `doctor` ignores it.
+  a BOM, comments or trailing commas are refused. `disable` cuts only that
+  server's entry, leaving every other byte as it was, and saves a backup at
+  `mcp-backups/<sha8>__claude__<name>.json` (mode `0600`) holding only that entry
+  -- its own headers, never another server's. `enable` puts the entry's bytes
+  back into the current file (an unchanged file comes back byte for byte; after
+  other edits it goes after its old neighbour, else at the end, indented like the
+  file) and checks that nothing else changed.
+- A move across filesystems copies into a temp dir beside the target, renames it
+  into place, then deletes the source, so a killed run leaves either the source
+  intact or the target complete, and the next run settles it (see "Where state
+  lives"). `enable` removes the emptied `parked/<sha8>/*-disabled` and
+  `parked/<sha8>` dirs; a dir that still holds anything is kept.
 - `status` prints one `project <dir>` line per project holding parked items.
-  A project with only `.mcp.json` saves only its parked servers in
-  `profile save --project`; live ones are not listed (the inventory needs
-  `.claude/`).
+  A project with only `.mcp.json` has its live servers listed too in
+  `profile save --project`, next to its parked ones.
 
 ## Doctor
 
@@ -504,31 +659,56 @@ agent-toggle enable --all --project .
 agent-toggle doctor [--harness H] [--json]
 ```
 
-Read-only: no lock, no state write-back, no `claude` CLI call. For each
+The check is read-only: no lock, no state write-back, no `claude` CLI call. For each
 installed harness it compares the live layout with the table row (expected
 dirs and config keys), then cross-checks `state.json` against disk (parked
 item present, origin dir present, backup present, project dir present, entry
-passes the same tamper checks `enable` runs, modes no looser than `0600` /
-`0700`). Rows (`action: doctor`) carry a status:
+passes the same tamper checks `enable` runs, companion files present and not also
+live, modes no looser than `0600` / `0700`). Rows (`action: doctor`) carry a status:
 
 | status | meaning |
 |---|---|
 | `ok` | matches |
 | `absent` | a dir, config file or key the row expects is not there (an MCP file never created, a missing `mcpServers` key) -- informational, exit `0` |
 | `note` | worth knowing: shared dir, orphan backup, JSONC `openclaw.json` / `opencode.json`, a `--harness` that is not installed |
-| `unverified` | could not be parsed here (an existing codex/grok `config.toml` on Python 3.10, which has no `tomllib`) |
-| `warn` | loose file modes; a parked item with no state entry; a leftover `parked/<sha8>` dir that still holds files (an empty one after `enable` is ignored) |
-| `error` | needs fixing: a config that exists but is unparseable or unsupported (`layout changed`), a state entry whose files are gone or fail the tamper checks, a flag re-enabled outside the tool |
+| `unverified` | no version could be read, or the row has nothing to check |
+| `warn` | loose file modes; a parked item or companion file with no state entry; a leftover `parked/<sha8>` dir that still holds files (an empty one is ignored); an op a killed run left in flight that the next change settles (`pending: done` / `undone`) |
+| `error` | needs fixing: a config that exists but is unparseable or unsupported (`layout changed`), a state entry whose files (companions included) are gone or fail the tamper checks, a companion both live and parked, a flag re-enabled outside the tool, an op a killed run left in flight that needs you (`pending: stuck`, with the exact fix) |
 
 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.
+`0`).
 
 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).
 
+### Fixing
+
+`install-shims` (and so `./install.sh`) runs the same check silently after
+writing the shims and asks only about these fixable problems, each shown first.
+
+On a terminal (stdin and stdout both a TTY, no `--json`) doctor then asks
+`(y/n)` for each problem it can fix without a judgment call, and runs each yes
+under the run lock; anything else keeps its `fix:` hint for you. A fixed row's
+status becomes `fixed` and no longer counts toward the exit code; a failed fix
+adds an `error` row. Piped, `--json`, or run by an agent through a shim, doctor
+stays read-only.
+
+| problem | fix it offers |
+|---|---|
+| loose mode on the state dir, `state.json` or a backup | `chmod 700` / `chmod 600` |
+| backup with no state entry, server configured again in its harness | delete the backup (not offered while the server is missing, nor for project backups) |
+| flag re-enabled outside the tool | `enable` the item, which clears the stale entry |
+| origin dir gone | recreate it, then `enable` the item |
+| op a killed run left in flight (`pending: done` / `undone`) | settle it now, as the next change would |
+| orphan parked item, `identical` | delete the parked copy |
+| orphan parked item, `parked-only` | move it back (restores it) |
+
+Not offered: `differs` orphans, missing parked items or backups, a gone project
+dir, tamper refusals, `pending: stuck`, companion conflicts, unparseable configs.
+
 ## Assumed formats
 
 Two config shapes came from the design survey (`docs/DESIGN.md` §4 / §11). Both
@@ -540,14 +720,16 @@ were since seen on one real install each (openclaw 2026.7.1-2, opencode 2.0.22;
 - `opencode.json`: `mcp.<name>.enabled`
 
 The edit changes one boolean token and nothing else, is verified after writing
-and rolled back on any mismatch (bytes and file mode). Files that are not
-strict JSON (JSONC / JSON5 -- comments, trailing commas) or that repeat a key are
-**refused**, never rewritten; a leading BOM is kept as is; a missing key is
-refused, never invented. An openclaw skill
+and rolled back on any mismatch (bytes and file mode). JSONC (`//` and `/* */`
+comments, trailing commas) is edited the same way: only the flag token changes,
+comments and commas are kept. JSON5 (unquoted keys, single quotes, hex) and files
+that repeat a key are **refused**, never rewritten; a leading BOM is kept as is; a
+missing key is refused, never invented. An openclaw skill
 uses the flag only when `skills.entries.<name>` already exists, otherwise its
-directory is moved. If a run is killed between the flag write and the state
-save, the flag is `false` with no state entry: `enable` then tells you to set it
-back by hand. Please report a real install that differs.
+directory is moved. The state entry (with the flag's previous value) is saved
+before the flag is written, so a run killed in between is settled by the next
+run, never guessed (see "Where state lives"). Please report a real install that
+differs.
 
 ## Safety checks
 
@@ -559,8 +741,9 @@ back by hand. Please report a real install that differs.
   invalid codex `config.toml` makes an MCP edit fail and roll back instead of
   being rewritten. A codex `config.toml` edit also fails (and is left as the other
   tool wrote it) if the file changed between read and write, and CRLF files keep their
-  line endings. On Python 3.10 (no `tomllib`) the TOML check is textual only: it checks
-  against the original text that only the one block changed, but cannot parse.
+  line endings. On Python 3.10 (no `tomllib`) the edit is parse-checked by a stdlib structural
+  validator (`agent_toggle/toml_check.py`, differentially tested against `tomllib`),
+  on top of the textual check that only the one block changed.
 - Profiles and project dirs are validated like command-line input.
 
 ## Where state lives
@@ -571,13 +754,29 @@ bookkeeping.
 
 | file | contents |
 |---|---|
-| `state.json` | current disabled list (schema v3; atomic write, mode `0600`) |
-| `lock` | held by `disable` / `enable` / `enable --all` / `undo` / `profile apply` / `migrate` / `ui` for the whole batch; a second run waits 5 s then exits `3` (stale after 10 min *and* its PID is gone; a live batch refreshes it per item) |
+| `state.json` | current disabled list (schema v3; atomic write, mode `0600`), saved before each flag write or dir move with the op in flight under an optional `pending` key, and after each MCP / plugin item |
+| `lock` | held by `disable` / `enable` / `enable --all` / `undo` / `profile apply` / `migrate` / `ui` for the whole batch; a second run waits 5 s then exits `3` (stale after 10 min *and* its PID is gone; a live batch refreshes it per item; the error says when its PID is gone, i.e. a killed run left it) |
 | `log.jsonl` | one line per operation (mode `0600`), see below |
 | `mcp-backups/` | `<harness>__<server>.json`, or `<sha8>__<harness>__<server>.json` for a project `.mcp.json` (mode `0600` -- may hold auth headers) |
 | `companions/` | parked exclusive helper files |
 | `parked/<sha8>/` | items parked by `--project` (`<sha8>` = first 8 hex of the SHA-1 of the resolved project dir) |
 | `profiles/` | `<name>.json` profiles (dir `0700`, files `0600`) |
+| `config.json` | [settings](#settings--config-menu) and the Telegram chat id (mode `0600`, atomic write, unknown keys kept) |
+| `update-check.json` | the [update check](#update-check)'s 10-minute cache (mode `0600`, atomic write) |
+
+A killed run loses at most the one item in flight. If that was a flag write or a
+dir move (with its companions), its `pending` record (the full entry, a flag's
+previous value included) lets the next `disable` / `enable` / `enable --all` /
+`undo` / ... finish it (it reached disk: recorded) or drop it (it did not), with
+a warning and a `recovered` log row (which `undo` does not reverse). `status` and
+`doctor` report it, with `agent-toggle enable ...` when the item ends up
+disabled. The one case left to you is a cross-filesystem move killed between its
+two renames: both copies are complete, and the report names the `diff -r` to
+check and the `rm -rf` that keeps either one. MCP and plugin items are saved
+per item (when the next one starts), without a `pending` record (a project `.mcp.json`
+edit has one): a kill inside that window
+leaves the change unrecorded (an MCP server's backup stays in `mcp-backups/`).
+A killed run also leaves its `lock`; the next run's error says so.
 
 Each `log.jsonl` row is `{ts, harness, type, name, action, result, batch,
 project, scope, detail}`. `batch` is one id per run (what `undo` reverses);
@@ -599,7 +798,9 @@ path exists as a *file*, so the `is_dir()` check has to come **before** the
 `mkdir` or it is unreachable.
 
 **2. Park dirs that are not gitignored get a warning.** Without it, every
-disable leaves dozens of deletion lines in `git status`.
+disable leaves dozens of deletion lines in `git status`. The warning is shown once
+per park dir, and only for a dir inside a git work tree (elsewhere `git status`
+cannot be dirtied and the `.gitignore` fix would not apply).
 
 ## Paths are resolved before comparison
 
@@ -632,19 +833,21 @@ runs. The message names the repository, branch, 7-character commit and a link to
 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            # settings menu: Notifications has the bot token (hidden) and 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.
+In the [settings menu](#settings--config-menu) an inline field commits on `Enter`, cancels on
+`Esc`, and clears on `-` then `Enter`; the Tools group also has Send test message and Sync CI
+secrets (the same as `config test` / `config sync-ci`, and they need the extra). 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 (`telegram_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):