sideby 0.14.0 → 0.15.0

package/schemas/quota-check.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/quota-check.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "family",
+    "on",
+    "changed"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "family": {
+      "type": "string"
+    },
+    "on": {
+      "type": "boolean"
+    },
+    "changed": {
+      "type": "boolean"
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
+    }
+  }
+}

package/schemas/quota-setup.json

@@ -107,7 +107,7 @@
             },
             "command": {
               "type": "string",
-              "description": "Updates the installed sideby skill (run it after the user agrees)."
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
             },
             "message": {
               "type": "string"

package/schemas/quota-teardown.json

@@ -77,7 +77,7 @@
             },
             "command": {
               "type": "string",
-              "description": "Updates the installed sideby skill (run it after the user agrees)."
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
             },
             "message": {
               "type": "string"

package/schemas/quota.json

@@ -273,7 +273,7 @@
             },
             "command": {
               "type": "string",
-              "description": "Updates the installed sideby skill (run it after the user agrees)."
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
             },
             "message": {
               "type": "string"

package/schemas/remote-control.json

@@ -176,7 +176,7 @@
             },
             "command": {
               "type": "string",
-              "description": "Updates the installed sideby skill (run it after the user agrees)."
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
             },
             "message": {
               "type": "string"

package/schemas/tune-change.json

@@ -173,7 +173,7 @@
             },
             "command": {
               "type": "string",
-              "description": "Updates the installed sideby skill (run it after the user agrees)."
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
             },
             "message": {
               "type": "string"

package/schemas/tune.json

@@ -295,7 +295,7 @@
             },
             "command": {
               "type": "string",
-              "description": "Updates the installed sideby skill (run it after the user agrees)."
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
             },
             "message": {
               "type": "string"

package/schemas/unpin.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/unpin.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "ref",
+    "pinned",
+    "changed",
+    "message",
+    "display"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "ref": {
+      "type": "string"
+    },
+    "pinned": {
+      "type": "boolean"
+    },
+    "changed": {
+      "type": "boolean"
+    },
+    "message": {
+      "type": "string"
+    },
+    "display": {
+      "type": "object",
+      "properties": {
+        "families": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "accounts": {
+          "type": "object",
+          "patternProperties": {
+            "^.*$": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "pinned": {
+          "type": "object",
+          "patternProperties": {
+            "^.*$": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
+    }
+  }
+}

package/schemas/update-auto.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/update-auto.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "auto",
+    "changed"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "auto": {
+      "type": "boolean"
+    },
+    "changed": {
+      "type": "boolean"
+    },
+    "_notice": {
+      "type": "object",
+      "properties": {
+        "update": {
+          "type": "object",
+          "required": [
+            "current",
+            "latest",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "current": {
+              "type": "string"
+            },
+            "latest": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "Run it after the user agrees: it shows the plan and exits 10; then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "skill": {
+          "type": "object",
+          "required": [
+            "installed",
+            "current",
+            "command",
+            "message"
+          ],
+          "properties": {
+            "installed": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The skill's version; null when it has none."
+            },
+            "current": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string",
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "description": "Not the answer to the task: mention it briefly afterwards and offer to update."
+    }
+  }
+}

package/schemas/update.json

@@ -66,6 +66,10 @@
             {
               "type": "string",
               "const": "source"
+            },
+            {
+              "type": "string",
+              "const": "local"
             }
           ],
           "description": "How this copy was installed."
@@ -77,6 +81,43 @@
         "reason": {
           "type": "string",
           "description": "Why it cannot."
+        },
+        "reasonCode": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "local-build"
+            },
+            {
+              "type": "string",
+              "const": "npx"
+            },
+            {
+              "type": "string",
+              "const": "volta"
+            },
+            {
+              "type": "string",
+              "const": "not-writable"
+            },
+            {
+              "type": "string",
+              "const": "project"
+            },
+            {
+              "type": "string",
+              "const": "source"
+            },
+            {
+              "type": "string",
+              "const": "skill-in-git"
+            }
+          ],
+          "description": "Why, as a code a page can say in its own language."
+        },
+        "reasonAt": {
+          "type": "string",
+          "description": "The folders that are not writable (`not-writable`)."
         }
       }
     },
@@ -146,6 +187,43 @@
         },
         "reason": {
           "type": "string"
+        },
+        "reasonCode": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "local-build"
+            },
+            {
+              "type": "string",
+              "const": "npx"
+            },
+            {
+              "type": "string",
+              "const": "volta"
+            },
+            {
+              "type": "string",
+              "const": "not-writable"
+            },
+            {
+              "type": "string",
+              "const": "project"
+            },
+            {
+              "type": "string",
+              "const": "source"
+            },
+            {
+              "type": "string",
+              "const": "skill-in-git"
+            }
+          ],
+          "description": "Why, as a code a page can say in its own language."
+        },
+        "reasonAt": {
+          "type": "string",
+          "description": "The git repository that owns the skill (`skill-in-git`)."
         }
       },
       "description": "The installed sideby skill, which the Update brings along; absent when none is installed."
@@ -210,7 +288,7 @@
             },
             "command": {
               "type": "string",
-              "description": "Updates the installed sideby skill (run it after the user agrees)."
+              "description": "`sideby update`, which updates the skill with sideby: run it after the user agrees; it shows the plan and exits 10, then --yes."
             },
             "message": {
               "type": "string"

package/skills/sideby/SKILL.md

@@ -2,7 +2,7 @@
 name: sideby
 description: Use when the user runs, or wants to run, several AI coding accounts (Claude Code, Codex, Grok Build, pi) side by side. Covers installing sideby and setting up a new account ("install sideby", "set up another Claude account", "add cc008", "配置一个 cc00x", "再加一个 Codex 账号"), explaining what accounts share and what stays separate ("what do my accounts share?", "这些账号共享了什么"), showing which account a session is ("show [cc001] in the status line", "加上账号标识"), seeing accounts, quota and usage, moving on when one hits its 5-hour or weekly limit, moving the current task to another account ("用 cc008 继续", "交回 cc008"), adding a short command (alias), and repairing drifted account directories (skills, hooks, rules or settings not shared, wrong symlinks, credential file permissions). Drives the `sideby` CLI with `--json`; the agent does every step except browser sign-in, filling in secrets and starting interactive sessions, which it hands to the user as one command (inside an Auto Handoff session, `sideby handoff ready --to` moves the task itself).
 metadata:
-  version: "0.14.0"
+  version: "0.15.0"
   requires:
     bins: [sideby, node]
   cliHelp: sideby --help
@@ -41,6 +41,10 @@ Account refs are `<family>:<name>`; a bare `<name>` works only when it is unique
 | Show which account a session is (`[cc001]` in the status line or tab title) | `sideby list --json` for the labels | `references/badge.md` |
 | Know what accounts share and what stays separate | `sideby families <family> --json` | `references/sharing.md` |
 | See accounts, health, quota and usage | `sideby list --json`, `sideby doctor --json`, `sideby quota --json` | `references/diagnose.md` |
+| Pin accounts or arrange their Display Order | `sideby order --json`, `sideby pin <ref> --json`, `sideby unpin <ref> --json` | `references/panel.md` |
+| Turn quota checks on or off, or refresh fetched quota | `sideby quota check <family> on|off --json`, `sideby quota [family] --refresh --json` | `references/quota.md` |
+| Set the model, effort or Remote Control | `sideby model <ref> --json`, `sideby remote-control --json` | `references/panel.md` |
+| Turn Auto Update on or off | `sideby update --auto on|off --json` | `references/update.md` |
 | Repair drift or permissions | `sideby doctor [ref] --json`, then `--fix` after they agree | `references/diagnose.md` |
 | Keep working because an account hit its limit | `sideby next <family> --json` | `references/handoff.md` |
 | Turn on Auto Handoff ("自动交接", "hand over when quota runs low"), see what it still needs, hand this session over now, or pick an account with room for a subtask | `sideby handoff status --json`, `sideby handoff enable --json` (exit 10 first), `sideby handoff ready`, `sideby next <family> --json` | `references/handoff.md` |
@@ -65,13 +69,13 @@ To open Claude Desktop or the Codex app as one account (macOS, subscription acco
 
 Grok Bot is not a grok account's app: it signs in with a Cursor account, apart from Grok Build. For several Grok Bot windows at once, run `sideby desktop grok-bot:<name> --json` (a new name makes a new, signed-out window; `grok-bot` is its default one) and relay the notice: sign in inside the new window with the account meant for it, with the other Grok Bot windows closed. `sideby list --json` lists them under `appProfiles`. Removing one (`--remove --yes`) signs it out and deletes its data: do it only when the user asks, after they quit that window.
 
-To find which Chrome browser user the user signed in to an account's website with, or to open claude.ai, chatgpt.com or grok.com there, run `sideby browser --json` and `sideby browser open <ref> --json`. Finding is off until the user agrees: run `sideby browser --enable` to show them what it reads (all on this computer), and add `--yes` only after they say yes. A match may be left over from before a sign-out; say so. Grok accounts need `--profile <name>`.
+To find which Chrome browser user the user signed in to an account's website with, or to open claude.ai, chatgpt.com or grok.com there, run `sideby browser --json` and `sideby browser open <ref> --json`. Finding is off until the user agrees: run `sideby browser --enable` to show them what it reads (all on this computer), and add `--yes` only after they say yes. To stop reading Browser Sign-ins, use `sideby browser --disable --json`, show its preview, then add `--yes` after approval. A match may be left over from before a sign-out; say so. Grok accounts need `--profile <name>`.
 
 For someone who would rather double-click than use a terminal, `sideby app install` adds a panel app (macOS `~/Applications/sideby.app`, Linux app menu) that runs `sideby ui --background`; `sideby ui --stop` stops it and `sideby app uninstall` removes the app. Ask before `app install`: it writes outside sideby's own directories.
 
 ## Updating sideby
 
-To update sideby, run `sideby update --json` yourself: it shows `current`, `latest`, the `command` and whether sideby can run it (`canRun`; exit 10). Ask the user, then run `sideby update --yes --json`. When `canRun` is false (npx, a project dependency, a source checkout, a global folder they cannot write), hand them the `command` as one line instead. Updating restarts a background panel by itself and reinstalls an installed panel app (`refreshedApp`), so do not run `app install` again after an update; a `sideby ui` in a terminal and running sessions keep the old version until restarted. sideby checks the registry once a day on its own and turns that off with `NO_UPDATE_NOTIFIER=1` or config `"update": { "check": false }`; `"update": { "auto": true }` (off by default) installs new non-major versions by itself. Never turn Auto Update on without the user asking.
+To update sideby, run `sideby update --json` yourself: it shows `current`, `latest`, the `command` and whether sideby can run it (`canRun`; exit 10). Ask the user, then run `sideby update --yes --json`. When `canRun` is false (npx, a project dependency, a source checkout, a global folder they cannot write), hand them the `command` as one line instead. Updating restarts a background panel by itself and reinstalls an installed panel app (`refreshedApp`), so do not run `app install` again after an update; a `sideby ui` in a terminal and running sessions keep the old version until restarted. sideby checks the registry once a day on its own and turns that off with `NO_UPDATE_NOTIFIER=1` or config `"update": { "check": false }`; `"update": { "auto": true }` (off by default) installs new non-major versions by itself. Use `sideby update --auto on|off --json` to save that switch without installing anything (`references/update.md`). Never turn Auto Update on without the user asking.
 
 ## Keeping this skill current
 

package/skills/sideby/references/handoff.md

@@ -61,3 +61,11 @@ Before you delegate work to another account (for example a review in a headless
 
 - Switch accounts by editing config or environment, copy session files between account directories, or read any credential.
 - Start an interactive session for the user.
+
+## Settings and overview
+
+`sideby handoff enable --threshold 95 --prepare-at 80 --wait-minutes 30 --countdown 10 --json` previews the settings. `--threshold` is the quota percentage to hand over, `--prepare-at` the percentage to prepare the Brief, `--wait-minutes` the longest reset wait, and `--countdown` the seconds before handing over. Read the validated `settings` and `diff`; on exit 10, show the change and confirm before repeating with `--yes`. Keep the user's chosen `--same-family` and `--order` options in the confirmed command.
+
+`sideby handoff status --json` also includes `overview`: `settings`, `takeover` (each account's `ref`, `family`, `starts`, `decision`) and `recent` (the last hand-overs' `from`, `to`, `at`, `trigger`, `briefSource`). A decision is `pick` with `ref`, `wait` with `until`, or `none` with `reason`; optional `skipped` and `earliestReset` explain exclusions and resets. An empty takeover list while Auto Handoff is off is expected. No Brief text is returned.
+
+`sideby handoff teardown grok --json` removes the hook installed by setup only while it still matches. It does not turn Auto Handoff off; use `handoff disable` for that. Relay any refusal instead of removing modified files manually.

package/skills/sideby/references/panel.md

@@ -0,0 +1,28 @@
+# Panel settings from the CLI
+
+Use these commands for the same persistent settings as the Panel. Prefer account refs from `sideby list --json`; commands taking an account also accept its short command. Every JSON response has `schemaVersion: 1`.
+
+## Pinned Accounts and Display Order
+
+- `sideby order --json` returns `display` (saved `families`, `accounts`, `pinned`) and `families` in their effective order. Each family has `accounts` with `name`, `ref`, `pinned`; a family with no accounts has an empty array.
+- `sideby pin claude:work --json` and `sideby unpin claude:work --json` return `ref`, `pinned`, `changed`, `message`, `display`. They save immediately. Repeating a pin or unpin is a no-op. A Same Login is pinned/unpinned together and counts once; at most three per Family. If full, ask which one to unpin first. A new pin goes last among pins.
+- `sideby order claude work main --json` sets that Family's account order using names, not refs or short commands. Unlisted accounts follow in the default order; pins still lead. Unknown or repeated names fail without saving.
+- `sideby order --families codex claude --json` sets the Family order; unlisted Families follow.
+- `sideby order --reset --json` forgets Family and account order, keeping pins. Save the old `display` from `order --json` before rearranging if the user may want to undo; restore Family/account lists with `order`, and pins with `unpin` then `pin` in their old order.
+
+- Same Login row name: the Panel shows two directories of one login as one row, named after the one that comes first in the order. To show `001` instead of `main`, run `sideby order claude 001` (the rest follows). `order --reset` brings back the main directory's name.
+- Desktop app windows (Grok Bot, id `grok-bot`) are a group in the same order: `sideby order --families claude grok-bot codex` places the group, `sideby order grok-bot 001 main` orders its windows. They cannot be pinned.
+
+These affect display only, never Handoff Order. Saving removes names that no longer exist. The existing Same Login rules apply (Claude groups by email and organization; Codex accounts remain separate).
+
+## Model and effort
+
+`sideby model claude:work --json` shows `account`, `family`, `settable`, optional `reason`, available `models` and `efforts`, and `sideby`, `host`, `last` choices. Effective `model` and `effort` have `{ value, from }`.
+
+To change them, run `sideby model claude:work opus --effort high --json`; `default` removes a sideby override. Read `change.diff`, `change.args` and `change.applied`. Exit 10 is a preview waiting for `--yes`: show it to the user and confirm before applying the same command with `--yes`. Only sideby's account arguments change, never the Host config. If `settable` is false, relay `reason`.
+
+## Remote Control
+
+`sideby remote-control --json` returns `action` and `groups`: each has `file`, `accounts`, `state`, `undo` and optional `reason`. `state` is `on`, `default`, `off`, `missing` or `blocked`.
+
+Use `sideby remote-control off --json`, `on --json` or `undo --json`. Exit 10 shows the affected groups and waits for `--yes`; confirm before applying. A result has `applied`, optional `results` (`file`, `accounts`, `ok`, `message`) and optional `message`. Only turn it on when asked. Changes affect new sessions; running sessions remain connected until restarted. Undo restores the earlier value only while the key still holds what sideby wrote.

package/skills/sideby/references/quota.md

@@ -18,3 +18,9 @@ Grok quota needs no setup: sideby asks the `grok` CLI of each signed-in account
 A window with a `name` (a plugin's Cursor "Other models") covers only some models: show it, but it does not make the account full.
 
 Usage (7-day tokens) is read by sideby itself from Claude Code and Codex local records; no ccusage is needed. Grok and pi have no usage source; pi has no quota either.
+
+## Quota checks and refresh
+
+`sideby quota check <family> on|off --json` saves the fetching switch immediately, returning `family`, `on`, `changed`. For example, `sideby quota check grok off --json`. Only Families with a quota fetcher support it; the error tells you to choose one through `sideby families`. Turning it off keeps local readings available. CI still blocks fetching when the switch is on.
+
+`sideby quota [account|family] --refresh --json` refreshes every selected Family that fetches quota, including plugin Families; without a target it refreshes all. It does not override a disabled check or CI. Read the returned accounts' `quota` and `usage`, including `fetchError` and observation time; do not call stale data a successful refresh.

package/skills/sideby/references/update.md

@@ -3,7 +3,7 @@
 Every `--json` output can carry `_notice` (it comes from sideby's daily Update Check and the installed skill, and reads no network itself):
 
 - `_notice.update`: `{ current, latest, command: "sideby update", message }`, a newer sideby is out.
-- `_notice.skill`: `{ installed, current, command, message }`, the sideby skill agents read here is for another version (`installed: null` when it has no version), so it may describe commands this CLI does not have.
+- `_notice.skill`: `{ installed, current, command: "sideby update", message }`, the sideby skill agents read here is for another version (`installed: null` when it has no version), so it may describe commands this CLI does not have.
 
 What to do:
 
@@ -12,5 +12,9 @@ What to do:
 3. When they agree:
    - Run `sideby update --json`. It shows the version, the install method and the command it would run, and exits `10`. Show that to the user; after their yes, run `sideby update --yes --json`.
    - If it exits `1` with `canRun: false` (npx, Volta, a project dependency, a source checkout, a Local Build), sideby cannot update itself: give the user the `command` it printed as one line to run.
-   - The same command updates the installed sideby skill (`skillUpdate` in the plan, `skillUpdated` in the result), so do not run a skill command yourself. With sideby already current and only the skill old (`_notice.skill`), `sideby update` updates the skill alone, after the same preview. When `skillUpdate.canRun` is false (the skill lives in a git repository), tell the user `reason` and give them `command`. Tell them that sessions already running keep the old version until they start again.
+   - The same command updates the installed sideby skill (`skillUpdate` in the plan, `skillUpdated` in the result), so do not run a skill command yourself. With sideby already current and only the skill old (`_notice.skill`), `sideby update` updates the skill alone, after the same preview. When `skillUpdate.canRun` is false (the skill lives in a git repository the skills tool did not install it into), tell the user `reason` and give them `command`. Tell them that sessions already running keep the old version until they start again.
 4. The user can turn notices off with `SIDEBY_NO_UPDATE_NOTIFIER=1` (or config `update.check: false`); set it for one command when a script needs JSON without `_notice`. A Local Build (`pnpm local`) never has one.
+
+## Auto Update
+
+When the user asks to change Auto Update, run `sideby update --auto on|off --json`. It saves immediately and returns `auto` and `changed` (exit 0, including no-op). It keeps the Update Check setting and does not check or install in this invocation. It needs no `--yes`; ordinary `sideby update --json` still previews an installation with exit 10. Never enable Auto Update unless the user asks.