sideby 0.13.1 → 0.15.0

package/skills/sideby/references/diagnose.md

@@ -29,7 +29,8 @@ Shared Items the Main Account does not have are skipped: no Finding, not counted
 | `problems` on an account in `list --json` | A plugin failed while reading it (for example a settings file that is not valid JSON) | Show the message; the account itself still works |
 | quota `unavailable` / `not-enabled` | Claude quota source is off | Offer `sideby quota setup claude` |
 | quota `unavailable` / `no-session` | No session since the source was enabled | Ask the user to start one session with that account |
-| quota `unavailable` / `no-source` | Grok, pi: the Host has no public source | Nothing to fix |
+| quota `unavailable` / `no-source` | pi: the Host has no public source | Nothing to fix |
+| quota `unavailable` / `fetch-failed` | Grok: its CLI could not get the quota | Follow `detail` (update Grok, `sideby login grok:<name>`), then `sideby quota grok --refresh` |
 | quota `unavailable` / `api-account` | API accounts have no quota | Nothing to fix |
 | quota `unavailable` / `unrecognized` | Host changed its file format | Report it; suggest filing an issue with the Host version |
 | host not installed | Accounts exist but the CLI is missing | Point to the Host's install docs; do not install it unasked |

package/skills/sideby/references/handoff.md

@@ -29,7 +29,7 @@ Use this when the user says an account hit its 5-hour or weekly limit ("usage li
 
 ## Other answers
 
-- Error `code: "no-quota-source"` (Grok, pi): the Host publishes no quota. The message lists the family's accounts; let the user choose one for `sideby run <ref>`.
+- Error `code: "no-quota-source"` (pi, or a plugin family without quota): the Host publishes no quota. The message lists the family's accounts; let the user choose one for `sideby run <ref>`.
 - Error `code: "no-accounts"`: the family has no account yet; see creating accounts.
 - Many `unknown` Claude accounts: Claude quota may be off. `sideby quota --json` shows `not-enabled`; the one-time setup turns it on.
 - Host arguments the user wants (another model, say) go after `--`: `sideby next claude -- --model opus`.
@@ -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

@@ -13,4 +13,14 @@ After setup, each account shows quota once it has had one session with a reply.
 
 Two Claude accounts signed in as the same login (same email and organization; `sameLogin` in `sideby list --json`) share one quota: both show the freshest reading, and `quota.from` names the account it was read from. Explain that to the user rather than calling the numbers wrong; usage stays per account, and sideby never merges or deletes either directory.
 
-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 quota or usage source.
+Grok quota needs no setup: sideby asks the `grok` CLI of each signed-in account (`grok agent --no-leader stdio`, the Host makes the request with its own login; sideby never reads `auth.json`) at most every 15 minutes, and also reads the quota Grok logs after each turn. `sideby quota grok --refresh` asks again now. `quota.status: "unavailable"` with `reason: "fetch-failed"` carries the cause and next step in `detail` (update Grok, `sideby login grok:<name>`); `"not-enabled"` means the user turned it off (config `quota.check.grok: false`, or the Panel's Settings) or it runs in CI. A reading with `fetchError` is the last good one; say it may be old.
+
+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.