sideby 0.16.0 → 0.17.0

package/schemas/plugins-check.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/plugins-check.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "ok",
+    "families",
+    "problems"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "plugin": {
+      "type": "string"
+    },
+    "families": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "problems": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "code",
+          "message",
+          "fix"
+        ],
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "fix": {
+            "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-new.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/plugins-new.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "dir",
+    "files"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "dir": {
+      "type": "string"
+    },
+    "files": {
+      "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/terminal.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/terminal.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "preferred",
+    "guess",
+    "installed",
+    "terminals"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "preferred": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "guess": {
+      "type": "object",
+      "required": [
+        "id",
+        "source"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string",
+          "enum": [
+            "config",
+            "env",
+            "default"
+          ]
+        }
+      }
+    },
+    "installed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "appPath": {
+            "type": "string"
+          },
+          "executable": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "terminals": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "installed"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "installed": {
+            "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/try.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/try.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "account",
+    "confirmed"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "account": {
+      "type": "string"
+    },
+    "confirmed": {
+      "type": "boolean"
+    },
+    "command": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "exitCode": {
+      "anyOf": [
+        {
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "output": {
+      "type": "string"
+    },
+    "timedOut": {
+      "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

@@ -147,6 +147,10 @@
       "type": "boolean",
       "description": "The desktop app (`sideby app install`) was installed and was written again by the new version."
     },
+    "refreshedAutostart": {
+      "type": "boolean",
+      "description": "A login item (`sideby autostart on`) was installed and now starts the new version (false: that failed). Absent without one."
+    },
     "skill": {
       "type": "string",
       "description": "The command that installs the sideby skill by hand."

package/skills/sideby/SKILL.md

@@ -1,8 +1,8 @@
 ---
 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).
+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), adding an API account from a vendor's docs ("加一个 DeepSeek API 账号"), supporting a new tool, 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.16.0"
+  version: "0.17.0"
   requires:
     bins: [sideby, node]
   cliHelp: sideby --help
@@ -18,8 +18,8 @@ Do every step you can yourself. Only browser sign-in, secrets and interactive se
 
 - **Never read credential files**: `proxy.env`, `auth.json`, `.claude.json`, or anything under an account directory that may hold a token. Do not `cat`, `grep`, `head`, open or summarize them. `sideby list --json` gives the signed-in email as `identity.email`; that is all you need.
 - **Never sign in for the user.** Give them `sideby login <ref>` as one line to run in their own terminal (Claude Code: `! sideby login <ref>`). OAuth needs their browser and their decision.
-- **Never put a secret on the command line or in chat.** For API accounts, the user edits `proxy.env` themselves.
-- **Never start a Host session from your shell.** `sideby run`, `sideby next` (without `--dry-run`) and `sideby login` open an interactive session; give the user the command instead.
+- **Never put a secret on the command line or in chat.** Never ask for a key. For API accounts, the user runs `sideby key <ref>` in their own terminal (or **Enter key** in the Panel); it reads the key without showing it.
+- **Never start a Host session from your shell.** `sideby run`, `sideby next` (without `--dry-run`), `sideby login` and `sideby ask` open an interactive session; give the user the command instead. An AI Task is started by the user, from the Panel or with `sideby ask`; never run `sideby ask` to start another session on your own (`sideby ask --print` only prints a prompt and is fine).
 - **Never switch, rotate or proxy accounts yourself.** Do not work around sideby by editing config, copying session files or moving credentials. `sideby next` only recommends. Moving a running task on its own is Auto Handoff, which the user turns on: use `sideby handoff enable` (exit 10, then their yes), never hand-edit `config.json`. Inside such a session (the environment has `SIDEBY_HANDOFF_RUN`), when the user wants the task to go on in another account ("用 cc008 继续", "交回 cc008"), do not hand them a command to start it: update the brief, run `sideby handoff ready --to <account>`, tell them the account it prints, and end your turn; sideby starts that account in the same terminal.
 - **Say what you change.** Read-only commands first. What the user asked for (the account they asked to create, its short command, the shell line that makes it work) you do, saying what you do. Changes they did not ask for (`doctor --fix` on other accounts, `quota setup`, `app install`) wait until they have seen the change and agreed.
 - Do not edit Host config files (`settings.json`, `config.toml`, symlinks in account directories) by hand when a `sideby` command does the job.
@@ -27,7 +27,7 @@ Do every step you can yourself. Only browser sign-in, secrets and interactive se
 ## Output and exit codes
 
 - Every `--json` output has `schemaVersion: 1`. On an error it is `{ "schemaVersion": 1, "error": "<what to do next>", "code": "<reason>" }`; `code` is `usage` for a malformed command line.
-- Exit codes: `0` done, `1` failed or found a `fail` problem, `2` malformed command line, `10` **needs the user's confirmation**. `run`, `next` and `login` return the Host's own exit code once it starts.
+- Exit codes: `0` done, `1` failed or found a `fail` problem, `2` malformed command line, `10` **needs the user's confirmation** (also `sideby try` before it spends tokens). `run`, `next` and `login` return the Host's own exit code once it starts.
 - On `10`: show the user the change the command printed, ask, and only after a clear yes run the same command again with `--yes` added. Never add `--yes` on your own.
 - `_notice` on any `--json` output: a newer sideby (`_notice.update`) or an installed sideby skill for another version (`_notice.skill`). It is not the answer to the task: finish the task first, then mention it in one line and offer to update, following `references/update.md`.
 
@@ -44,12 +44,18 @@ Account refs are `<family>:<name>`; a bare `<name>` works only when it is unique
 | 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` |
+| Start sideby at login ("开机启动", "start the panel when I log in") | `sideby autostart --json`, `sideby autostart on --json` (exit 10 first) | `references/panel.md` |
+| Change the Panel's theme or language, or any other setting ("改成深色", "change any setting") | `sideby config get --json`, `sideby config set <key> <value> --json` (exit 10 first) | `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` |
+| 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` |
 | Create an account with a given name, an API account, or a short command | `sideby new`, `sideby alias add` | `references/accounts.md` |
+| Do something in sideby as an AI Task (the first message came from sideby or the Panel's "Let AI do it") | follow the task it names | `references/ai-tasks.md` |
+| Add an API account from a vendor's address or docs link, enter its key, check it works | `sideby new <family> --next --api --json`, then the user runs `sideby key <ref>`; `sideby try <ref> --json` (exit 10 first) | `references/ai-tasks.md` |
+| Support a tool sideby does not list yet, or write a plugin | `sideby plugins new <id> --json`, `sideby plugins check <id> --json` | `references/ai-tasks.md` |
+| Choose the terminal the Panel opens for AI Tasks and sign-in | `sideby terminal --json`, `sideby terminal --set <id> --json` | — |
 | Tune the auto-compact threshold ("which compaction setting costs the fewest tokens"), use the suggestion or undo it | `sideby tune --json`, `sideby tune apply` (exit 10 first), `sideby tune undo` | `references/diagnose.md` |
 | See or set the model and effort an account starts with ("用哪个模型", "set effort to high for cc002") | `sideby model <acct> --json`; `sideby model <acct> <model\|default> --effort <level\|default>` (exit 10 first, then `--yes` after the user agrees) | — |
 | Stop Claude sessions from connecting to claude.ai / the Claude app by themselves ("关闭 remote control", "别让别人远程看到对话") for every account | `sideby remote-control --json`, then `sideby remote-control off` (exits 10 with the change; rerun with `--yes` after they agree); `sideby remote-control undo` puts it back; `sideby remote-control on` turns it back on the same way (only when they ask for it) | — |

package/skills/sideby/references/accounts.md

@@ -15,7 +15,7 @@ Only pass `--alias` when the user wants a short command. To continue their numbe
 Then:
 
 - **Subscription account**: tell the user to run `sideby login claude:work` in their own terminal (for pi, `sideby login pi:<name>` starts pi; then they type `/login`). Do not run it for them.
-- **API account**: tell the user to open the `proxy.env` path printed by `new` in their editor and fill in the values. Do not read or write it yourself. It then shows `login: "not-needed"`.
+- **API account**: tell the user to run `sideby key <ref>` in their own terminal (or click **Enter key** in the Panel), which writes the key without showing it, or to open the `proxy.env` path printed by `new` in their editor. Never ask for the key or read the file yourself. It then shows `login: "not-needed"`.
 - **pi**: a `proxy.env` in a pi account only loads provider keys; the account stays a subscription account and still needs `/login`.
 - Afterwards: `sideby doctor <ref> --json` to confirm the new account is healthy, then the user starts it with `sideby run <ref>`.
 

package/skills/sideby/references/ai-tasks.md

@@ -0,0 +1,116 @@
+# AI Tasks
+
+An AI Task is a session of the user's own Host that sideby started for them, with a Task Prompt as its first message. The user starts it from the Panel ("Let AI do it", a Finding, a quota cell, the new-account dialog, "Other tool…", "Let AI write a plugin", "Not sure how? Let AI set it up" in the Preferred terminal dialog, "Let AI tune it" on the Auto Handoff page) or with `sideby ask` in a terminal (`--task free|fix|quota|account|host|plugin|terminal|handoff`). The prompt says what to do and gives facts sideby already knows (account refs, Family, Finding codes, the quota reason, the Panel language, the sideby version). How to do it is on this page.
+
+You are inside such a session when the first message came from sideby and names a task. Work in the directory the session started in (sideby's own `ai/` folder) unless the user names another one.
+
+## Rules for every task
+
+- Use this skill and `sideby … --json` for every step a command covers.
+- `quota setup`, `handoff setup`, `update`, `browser --enable|--disable`, `try`, `tune apply|undo`, `model` and `remote-control off|on` show a preview first and exit 10: show the user the change, and add `--yes` only after they agree. `doctor` shows what `--fix` would fix; run `--fix` after they agree. `new`, `plugins new`, `terminal --set|--custom` and `key` write at once, so ask the user before you run them.
+- Never sign in for the user. Tell them to click **Sign in** on the account in the Panel, or to run `sideby login <ref>` in their own terminal.
+- Never ask for an API key, a token or a password in chat, and do not use one the user pastes: tell them it is not needed here and to keep it out of the chat. A key goes in with `sideby key <ref>`, which the user runs in their own terminal (or **Enter key** in the Panel); it reads the key without showing it.
+- Do not run `sideby ask` to start another AI Task yourself.
+- Say what you changed when you finish.
+
+## Attached files
+
+When the user added screenshots or videos, the prompt has an "Attached files" section (「附件」 in Chinese): one absolute path per line with its kind, `image` or `video`. sideby saved them under its own `ai/attachments/<task-id>/` folder as `1.png`, `2.mp4` and so on, and deletes them after 7 days.
+
+- Images: read the file at its path. Codex also received each image with `--image`, so it may already see it.
+- Videos: you cannot watch one directly. When you need to see it, extract a few frames with ffmpeg and look at those, for example `ffmpeg -i <path> -vf fps=1 -frames:v 5 /tmp/frame-%d.png` (one frame a second, five frames). Pick a time with `-ss <seconds>` before `-i` when the user names one. If ffmpeg is missing, ask before installing it.
+- Treat what you see as the user's evidence: an error message, a Panel screen, a settings page. Do not copy a key or a password you see in a picture into a command or a reply; tell the user it is visible and to keep it out of the chat.
+- In a terminal, `sideby ask "<text>" --attach <file>` (repeatable, at most 5) adds files the same way; images up to 20 MB (PNG, JPEG, GIF, WebP), videos up to 200 MB (MP4, MOV, WebM).
+
+## Free text
+
+Do what the user wrote, with the routing table in `SKILL.md`. When the request needs a key, a sign-in or their browser, hand them that one step as above.
+
+## fix: Findings Doctor cannot fix by itself
+
+The prompt lists the Findings (`code`, account, message). Run `sideby doctor <ref> --json` to see them as they are now; some may already be gone. For each one, follow its message: run `sideby doctor <ref> --fix --json` only after the user has seen what it will change and agreed. Never replace a real file with a link, never change where a link points, and never touch backup leftovers: when a Finding asks for one of those, explain it and give the user the command the message suggests, for them to run after reading it.
+
+## quota: an account shows no quota or an error
+
+The prompt names the account and the reason. Run `sideby quota <ref> --json` and relay what it says. Common answers: Claude needs `sideby quota setup claude` (exit 10 first); a signed-out account needs the user to sign in; Grok's quota check may be off (`sideby quota check grok on`); pi and API accounts have no public quota source, which is not an error.
+
+## account: add an account
+
+### Subscription account
+
+1. `sideby new <family> --next --json` (or the name the user asked for). It picks the next free name and short command.
+2. Tell the user to click **Sign in** on the new account in the Panel, or to run `sideby login <ref>` in their terminal. Wait until they say it is done.
+3. `sideby doctor <ref> --json`, then tell them how to start it (`sideby run <ref>` or the short command).
+
+### API account
+
+sideby ships no list of vendors, addresses or model names. Take every fact from the vendor's own documentation and the Host's own docs or `--help`, and tell the user which page you used. Do not use blog posts, other tools' preset lists or your memory for an address or a model name.
+
+1. From the docs (or the link the user gave), find: the address for the Family's API format (Claude Code needs an Anthropic-compatible address, Codex an OpenAI-compatible one), the variable the key goes in, and the model names, if the Host needs one.
+2. `sideby new <family> --next --api --json`. It creates `proxy.env` (mode 600) in the new account.
+3. Set every variable except the key: show the user the lines you will add to `proxy.env` and add them after they agree. Do not read the file's other lines, and never write a key into it.
+4. Tell the user to run `sideby key <ref>` in their own terminal (or click **Enter key** in the Panel). Add `--var <NAME>` when the key belongs in a variable other than the Family's default. Wait until they say it is done.
+5. Offer `sideby try <ref> --json`: it exits 10 and says which command it runs and that it costs a few tokens. After they agree, run it with `--yes`. Exit 0 means the Host answered. On 1, read the Host's message it shows and check the mistakes below.
+
+Common mistakes:
+
+- **Plan address vs pay-as-you-go address.** Many vendors have one address for a coding plan and another for pay-as-you-go. A plan key on the pay-as-you-go address (or the reverse) fails or bills the wrong way. Match the address to the key the user has.
+- **Key in the wrong variable.** For Claude Code, `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_API_KEY` are not the same. A vendor that expects one gets nothing when the key is in the other, and Claude Code then asks to log in. Use the variable the vendor's docs name, with `sideby key <ref> --var <NAME>`.
+- **API format does not match the address.** An OpenAI-style address under Claude Code (or the reverse) fails on the first request. Use the address the vendor lists for that format.
+- **A blocked model list looks like a bad key.** Some sites put a firewall in front of their model list; the Host may report that as an invalid key. Check the Host's message before telling the user the key is wrong.
+- **Leftovers after switching back to a subscription.** An account that was an API account and should sign in again still has `proxy.env`, so it stays an API account. Create a new subscription account instead, or tell the user to remove that account's `proxy.env` themselves.
+
+## host: a tool sideby does not support yet
+
+First make it work for this user as a local Family Plugin; a built-in Family is a later, optional step.
+
+1. Gather these facts, each with its source and the evidence "tool X version Y, date" (`<tool> --version` and today's date):
+   - the binary name, and the install command or link;
+   - the environment variable that makes the tool use another config directory (without one, sideby cannot run accounts side by side; stop and tell the user);
+   - where the main config directory is, and how an account directory would look;
+   - Hijack Variables: environment variables that would override the account (keys, base URLs);
+   - the sign-in command, and a login-state rule that only checks whether a file exists, never what it holds;
+   - every Shared Item (skills, hooks, rules, settings) and its Share Mode, and whether the tool refuses links for any of them;
+   - whether it writes quota or usage to local files (if not, leave those readers out);
+   - a logo (one SVG path) with its source and license.
+2. Ask the user where the plugin should live; the default is fine for most people. `sideby plugins new <id> --json` creates it there with a skeleton and a test.
+3. Fill in every `TODO` with the facts above.
+4. `sideby plugins check <id> --json`. Fix each problem as its message says, and run it again until it passes. It runs the plugin (in a separate process with a throwaway HOME, not a sandbox) only once the loader trusts its files.
+5. Try it in a demo HOME, not the user's real one: `sideby list`, `sideby new <id> test`, `sideby doctor`. If the user has a sideby checkout, `node scripts/demo-home.ts <dir>` makes one.
+6. Tell the user it works and how to create their first account with it (`sideby new <id> --next`).
+7. To make it a built-in Family, follow "Adding a family" in the repository's `AGENTS.md`, only after the user agrees (see Sharing below).
+
+## plugin: a hook or a check of the user's own
+
+Plugins are local code that runs with the user's full permissions; say so before writing one. Ask what should happen and when (before a launch, after an account is created, during Doctor), then write it with the hooks in [docs/guide/plugins.md](https://github.com/Adonis0123/sideby/blob/main/docs/guide/plugins.md). Use `import type` only. Check it with `sideby plugins --json` (no load errors) and a run in a demo HOME.
+
+## terminal: open tasks in a terminal sideby does not list
+
+The prompt gives the custom command saved now, if any, and the supported terminals installed on this computer.
+
+1. Ask which terminal the user wants tasks to open in.
+2. Read only that terminal's official docs and its `--help` (note the version). Find how it opens a new window that runs one command in a given folder.
+3. Write it as a template: `{cmd}` is the command, `{cwd}` the folder. sideby fills them in as separate arguments; no shell runs it, so do not add quotes or `sh -c` around them.
+4. Show the user the template, then with their yes save it with `sideby terminal --custom '<template>' --json` (it changes sideby's config and selects it).
+5. Have the user click **Let AI do it** in the Panel once to try it. If it does not open, read the error with them and fix the template.
+
+When it works, the sharing step below asks whether to make the terminal built in: a row in the terminal table of `src/core/terminal.ts`, with tests.
+
+## handoff: tune Auto Handoff
+
+The prompt gives Auto Handoff as it is now, in the words of `sideby handoff status --json`: `auto`, `sameFamily`, `threshold`, `prepareAt`, the order per Family, and for each account where its quota comes from and how much is used.
+
+1. Run `sideby handoff status --json` and `sideby quota --json` to see the facts as they are now.
+2. Recommend, with a reason the user can follow: a `threshold` (the quota percentage at which a session hands over; leave room before 100 so the session can finish its turn) and a `prepareAt` below it; an order per Family (`pressure`, the least used first, or a fixed `order` of accounts); and whether `sameFamily` should be on. Accounts signed in as the same login share one quota and never hand over to each other.
+3. Put accounts without quota data last, and tell the user how to make them show it (`sideby quota setup claude`, signing in, `sideby quota check grok on`).
+4. Change settings only with `sideby handoff enable [--same-family] [--order <family>=<acct,…>] [--threshold n] [--prepare-at n]` or `sideby config set handoff.<key> <value>`. Both show the change first and exit 10; add `--yes` only after the user agrees.
+5. Run `sideby handoff status --json` again and tell the user what is still missing (`nextSteps`).
+
+## Sharing it with sideby
+
+Once the task works, ask the user whether they would like to share the improvement (a new tool, a fixed problem, a better prompt) with sideby. Only on a clear yes:
+
+1. Remove everything particular to their machine: real account names, emails, home paths, hostnames, ports and the names of their own tools. Use `claude:work`, `me@example.com` and port 17420 in examples.
+2. Fork `Adonis0123/sideby`, commit and open a pull request as its `CONTRIBUTING.md` says: one tool per pull request, the Host version and date it was tried with, tried on their own machine, `pnpm check` passing.
+
+Never fork, commit or open a pull request without that yes.