sideby 0.14.0 → 0.16.0

package/schemas/pin.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/pin.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/plugins.json

@@ -121,7 +121,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-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.16.0"
   requires:
     bins: [sideby, node]
   cliHelp: sideby --help
@@ -41,6 +41,11 @@ 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` |
+| Switch between a local build of sideby and the release ("切换到正式版", "切回 dev 版本") | `sideby local --json`, `sideby local on|off --json` (exits 10 first) | `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 +70,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.