sideby 0.0.0-stage → 0.2.1

package/schemas/plugins.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/plugins.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "plugins",
+    "errors"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "plugins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "version",
+          "source",
+          "families",
+          "configKeys"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "source": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "families": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "configKeys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "where",
+          "message"
+        ],
+        "properties": {
+          "where": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "title": "sideby plugins --json"
+}

package/schemas/quota-setup.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/quota-setup.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "family",
+    "applied",
+    "plan"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "family": {
+      "type": "string"
+    },
+    "applied": {
+      "type": "boolean"
+    },
+    "plan": {
+      "type": "object",
+      "required": [
+        "status",
+        "file",
+        "diff",
+        "message"
+      ],
+      "properties": {
+        "status": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "enabled"
+            },
+            {
+              "type": "string",
+              "const": "ready"
+            },
+            {
+              "type": "string",
+              "const": "blocked"
+            }
+          ]
+        },
+        "file": {
+          "type": "string"
+        },
+        "diff": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "title": "sideby quota setup --json"
+}

package/schemas/quota-teardown.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/quota-teardown.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "family",
+    "ok",
+    "message"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "family": {
+      "type": "string"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "message": {
+      "type": "string"
+    },
+    "diff": {
+      "type": "string"
+    }
+  },
+  "title": "sideby quota teardown --json"
+}

package/schemas/quota.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/quota.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "accounts"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "accounts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "ref",
+          "kind",
+          "quota",
+          "usage"
+        ],
+        "properties": {
+          "ref": {
+            "type": "string"
+          },
+          "kind": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "subscription"
+              },
+              {
+                "type": "string",
+                "const": "api"
+              }
+            ]
+          },
+          "quota": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "status",
+                  "windows",
+                  "observedAt",
+                  "source"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "const": "ok"
+                  },
+                  "windows": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "label",
+                        "windowMinutes",
+                        "usedPercent",
+                        "resetsAt"
+                      ],
+                      "properties": {
+                        "label": {
+                          "type": "string"
+                        },
+                        "windowMinutes": {
+                          "type": "number"
+                        },
+                        "usedPercent": {
+                          "type": "number"
+                        },
+                        "resetsAt": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  },
+                  "observedAt": {
+                    "type": "string"
+                  },
+                  "source": {
+                    "type": "string"
+                  },
+                  "plan": {
+                    "type": "string"
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "required": [
+                  "status",
+                  "reason"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "const": "unavailable"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "detail": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          },
+          "usage": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "status",
+                  "days",
+                  "sessions",
+                  "inputTokens",
+                  "outputTokens",
+                  "cacheReadTokens",
+                  "cacheWriteTokens",
+                  "totalTokens"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "const": "ok"
+                  },
+                  "days": {
+                    "type": "number"
+                  },
+                  "sessions": {
+                    "type": "number"
+                  },
+                  "inputTokens": {
+                    "type": "number"
+                  },
+                  "outputTokens": {
+                    "type": "number"
+                  },
+                  "cacheReadTokens": {
+                    "type": "number"
+                  },
+                  "cacheWriteTokens": {
+                    "type": "number"
+                  },
+                  "totalTokens": {
+                    "type": "number"
+                  },
+                  "daily": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "date",
+                        "totalTokens"
+                      ],
+                      "properties": {
+                        "date": {
+                          "type": "string"
+                        },
+                        "totalTokens": {
+                          "type": "number"
+                        }
+                      }
+                    },
+                    "description": "Tokens per local day (YYYY-MM-DD), oldest first, days without records as 0."
+                  },
+                  "lastActivityAt": {
+                    "type": "string"
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "required": [
+                  "status",
+                  "reason"
+                ],
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "const": "unavailable"
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "detail": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  },
+  "title": "sideby quota --json"
+}

package/skills/sideby/SKILL.md

@@ -0,0 +1,61 @@
+---
+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?", "这些账号共享了什么"), seeing accounts, quota and usage, moving on when one hits its 5-hour or weekly limit, 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.
+metadata:
+  version: "0.2.1"
+  requires:
+    bins: [sideby, node]
+  cliHelp: sideby --help
+---
+
+# sideby
+
+`sideby` runs each AI coding account from its own directory (`~/.claude-work`, `~/.codex-api`, ...) and keeps skills, hooks and rules shared with the Main Account (`~/.claude`, `~/.codex`, `~/.grok`, `~/.pi/agent`). Requires Node 22.18+. If `sideby` is not installed, follow `references/setup.md`; `sideby <command> --help` shows examples for `new`, `alias`, `login`, `doctor` and `families`.
+
+Do every step you can yourself. Only browser sign-in, secrets and interactive sessions belong to the user: hand each to them as exactly one line to run (in Claude Code they can type `! <command>`), then continue once they say it is done.
+
+## Hard rules
+
+- **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 switch, rotate or proxy accounts.** sideby does not do it, and you must not work around that by editing config, copying session files or moving credentials. Choosing the next account is the user's call; `sideby next` only recommends.
+- **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.
+
+## 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.
+- 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.
+
+## What do you want to do
+
+Account refs are `<family>:<name>`; a bare `<name>` works only when it is unique. Families: `claude`, `codex`, `grok`, `pi`.
+
+| The user wants to | Run | Then read |
+|---|---|---|
+| Install sideby, or set up a new account ("add cc008") | `sideby --version`, `sideby list --json`, `sideby new <family> --next --json` | `references/setup.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` |
+| 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` |
+| Create an account with a given name, an API account, or a short command | `sideby new`, `sideby alias add` | `references/accounts.md` |
+| See Claude quota (it shows `not-enabled`) | `sideby quota setup claude` (exits 10) | `references/quota.md` |
+| See everything at once | `sideby ui` (local panel on `127.0.0.1:17420`; `--no-open` prints the address) | — |
+| Start an account | give them `sideby run <ref> [-- host args]` | — |
+
+Read only the reference the task needs.
+
+## Launching and the panel
+
+`eval "$(sideby shell-init zsh)"` defines one function per account (`sideby-claude-work`) plus the config `aliases`. Users who source a file instead set config `shellInitFile` (for example `{ "zsh": "~/.config/sideby/shell-init.zsh" }`); `new` and `alias add|rm` keep it current, and `sideby shell-init zsh --write` rewrites it. New functions work in a new shell.
+
+When a terminal manager such as Orca reopens a pane with a bare `claude --resume <id>` (or `codex resume <id>`, `grok --resume <id>`) and the Host says `No conversation found`, the session lives in another account. Suggest config `"resumeRouting": true` followed by `sideby shell-init --write` (or a new shell with `eval`): `shell-init` then defines Host-named functions that call `sideby resume <family>`, which starts the account holding that session. For a one-off, find it with `ls -d ~/.claude*/projects/*/<id>.jsonl` and run `sideby run <ref> -- --resume <id>`.
+
+For someone who would rather double-click than use a terminal, `sideby app install` adds a desktop 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.
+
+## Keeping this skill current
+
+If `sideby doctor --json` reports `skill.outdated`, this skill was written for another sideby version. Tell the user to update it with `npx skills add Adonis0123/sideby -g`.

package/skills/sideby/references/accounts.md

@@ -0,0 +1,31 @@
+# Create accounts and short commands
+
+## Create an account
+
+Check the name first: `^[a-z0-9][a-z0-9-]{0,31}$`, and not already taken (`sideby list --json`).
+
+```sh
+sideby new claude work               # subscription account: ~/.claude-work
+sideby new claude deepseek --api     # API account: ~/.claude-deepseek with a proxy.env template (mode 600)
+sideby new claude 008 --alias cc008  # also adds the short command cc008 to config aliases
+```
+
+Only pass `--alias` when the user wants a short command. To continue their numbering (`cc001`…`cc007` for `claude:001`…`claude:007`), use `sideby new claude --next --json` instead of a name: it picks `008` and `cc008` the same way the panel does (see `setup.md`). An invalid, reserved or taken alias is refused before anything is created (error `code: "alias-invalid"`). If `alias.added` is false in `--json`, the account exists but the alias is missing: tell the user the message, do not edit the config by hand.
+
+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"`.
+- **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>`.
+
+## Short commands (aliases)
+
+For an account that already exists: `sideby alias add <short> <ref> --json`.
+
+To start one account with fixed Host arguments, such as another model, put them after `--`: `sideby alias add pi-kimi pi:main --json -- --model kimi-coding/k3`. It is the same account (same login, same sessions), not a new one; do not create an account per model. Only `sideby run <short>` adds the arguments.
+
+- `status: "exists"` means it was already there.
+- A refusal names the next step (`sideby alias rm <short>` first).
+- Entry points that need environment variables are not aliases: leave them in the user's shell rc.
+- Do not edit `aliases` in the config by hand.

package/skills/sideby/references/diagnose.md

@@ -0,0 +1,47 @@
+# Diagnose and repair
+
+## Diagnose
+
+Start read-only:
+
+```sh
+sideby list --json        # accounts: ref, family, kind (subscription|api), dir, login, identity.email, model, hostInstalled, problems
+sideby doctor --json      # findings: level ok|warn|fail, account, item, code, message, hint, fixable
+sideby quota --json       # per account: quota windows (5h, 7d, usedPercent, resetsAt, observedAt) and 7-day tokens
+sideby plugins --json     # loaded plugins (setting names only, never values) and load errors
+```
+
+Narrow with an account or family: `sideby doctor claude:work --json`, `sideby doctor codex --json`, `sideby quota work --json`. On an ambiguity error, use the full ref from the candidates listed.
+
+Shared Items the Main Account does not have are skipped: no Finding, not counted in `shared`. A directory such as `~/.claude-code-router` that holds neither `proxy.env` nor any Shared Item is not listed as an account.
+
+| Signal | Meaning | What to do |
+|---|---|---|
+| `fail` / `warn` with `fixable: true` | Safe repair exists | Offer `doctor --fix` (see Repair) |
+| `fixable: false` with a `hint` | sideby will not touch it on purpose (real file where a link belongs, API account item) | Show the hint; the user decides |
+| `warn` `link.other-target` | The link resolves, but not to the Main Account's item; often deliberate | Mention it; change nothing unless the user asks |
+| `fail` `link.dangling` | The link points at nothing | Show the hint (`ls -l <path>`); the user decides how to repair it |
+| `fail` `symlink-forbidden` without `fixable` | The Host needs a real file here, but the link points somewhere other than the Main Account | Show the hint; sideby will not replace a link it did not create |
+| credential item, mode not 600 | `proxy.env`, `auth.json`, `.claude.json` readable by others | `--fix` resets the mode to 600 |
+| `warn` `skill.outdated` (in `general`) | The installed sideby skill is for another sideby version | Tell the user to run `npx skills add Adonis0123/sideby -g` |
+| name looks like a backup (`bak`, `backup`, `old`, `tmp`) | A stray directory was picked up as an account | Suggest adding its ref to `ignore` in `${XDG_CONFIG_HOME:-~/.config}/sideby/config.json` |
+| `login: "not-needed"` (`key` in `sideby list`) | API account; it authenticates with `proxy.env` | Nothing to do |
+| `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` / `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 |
+
+Quota is only as fresh as each account's last session; `observedAt` says when it was recorded. A window whose `resetsAt` has passed has reset.
+
+## Repair
+
+1. Run `sideby doctor [ref] --json` and show the user every finding you plan to fix, grouped by account.
+2. After the user agrees, run `sideby doctor [ref] --fix`, then `sideby doctor [ref] --json` again and report what is still open.
+3. `--force` is only for `json-key` items (for example `.claude.json#mcpServers`) when a fix would remove entries the account already has. Never add `--force` without telling the user exactly which entries would disappear.
+
+`--fix` never replaces a real file with a link, never re-points an existing symlink (wrong or dangling links are only reported), never writes through a link into the Main Account, and never changes credential contents. Findings it skips need a human decision; explain the hint, do not work around it with `rm` or `ln`.
+
+`doctor` exits 1 only when a `fail` finding is left; warnings alone exit 0.

package/skills/sideby/references/handoff.md

@@ -0,0 +1,41 @@
+# Handoff: keep working on another account
+
+Use this when the user says an account hit its 5-hour or weekly limit ("usage limit reached", "rate limited", "resets at …") and wants to keep working, or asks which account has room. sideby recommends the account of the same family with the lowest Quota Pressure (the fullest window that has not reset yet). It never switches by itself; the user starts the next account.
+
+## Steps
+
+1. Run `sideby next <family> --json` (`claude` or `codex`). It only recommends; it starts nothing.
+2. Tell the user the pick and why, from `pick` and `accounts`:
+
+   | `state` | Meaning | Can be picked |
+   |---|---|---|
+   | `ready` | Subscription account with room; `pressure` is its fullest live window in percent | Yes, lowest `pressure` first |
+   | `unknown` | No quota data yet (no session since quota was turned on, or Claude quota is off) | Yes, after `ready` |
+   | `api` | API account, pay per use | Only with `--include-api` |
+   | `full` | A live window is at 85% or more; `resetsAt` is when it is usable again | No |
+   | `logged-out` | Needs `sideby login <ref>` | No |
+
+   Each entry's `observedAt` says when its quota was recorded. If `hasQuota` is `false`, no account has quota data: the pick is only a guess, so say so and suggest turning quota on (see the routing table in SKILL.md) or letting the user choose.
+3. Give the user the command to run in their own terminal: `sideby next <family>` (starts the pick) or `sideby run <pick>`. Host arguments go after `--`. Do not run it yourself.
+4. Offer a handoff note: the new session starts empty, because each account keeps its own sessions. Write a short note the user can paste into it: the goal, what is done, what is in progress, the files involved, and the next step.
+
+## When nothing can be picked
+
+`pick` is `null` and the exit code is 1:
+
+- Every account `full`: tell the user `earliestReset.ref` comes back at `earliestReset.at`.
+- Accounts `logged-out`: the user can sign in with `sideby login <ref>`.
+- Only `api` left: ask whether they want to pay per use before suggesting `sideby next <family> --include-api`.
+
+## 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-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`.
+- Quota is only as fresh as each account's last session. Do not promise an account has room; say what the data shows and when it was recorded.
+
+## Never
+
+- Switch accounts by editing config or environment, copy session files between account directories, or read any credential.
+- Start a session for the user.

package/skills/sideby/references/quota.md

@@ -0,0 +1,14 @@
+# Claude quota
+
+Claude quota needs a one-time change to `~/.claude/settings.json`: the status line command becomes `sideby statusline-tap --orig-b64 <base64 of the original command>`. Claude Code then hands each refresh's official `rate_limits` (5-hour and 7-day used percent and reset time) to sideby, which caches them per account. Nothing is sent anywhere.
+
+1. sideby must be installed globally (`npm i -g sideby`), because Claude Code runs the wrapper on every status line refresh. Setup is refused when `sideby` is missing from PATH or comes from the npx cache; tell the user to install it rather than working around it.
+2. Run `sideby quota setup claude`. It prints the diff, changes nothing and exits **10**: show the diff to the user.
+3. Only after the user approves, run `sideby quota setup claude --yes`.
+4. To undo: `sideby quota teardown claude`. It restores the file byte for byte only if nothing changed since setup. If it refuses, show its diff and tell the user to set `statusLine.command` back to the original command (the base64 after `--orig-b64`), or delete `statusLine` if there was none.
+
+Accounts with their own (not linked) `settings.json` show quota `not-enabled` until that file's status line is wrapped the same way; tell the user instead of editing it.
+
+After setup, each account shows quota once it has had one session with a reply. Codex quota needs no setup: sideby reads it from Codex's own session files.
+
+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.

package/skills/sideby/references/setup.md

@@ -0,0 +1,31 @@
+# Install sideby and set up an account
+
+For "install sideby", "set up another Claude account", "add cc008", "配置一个 cc00x". Do each step yourself unless it says **user**; give the user that step as exactly one line (in Claude Code: `! <command>`) and continue when they say it is done.
+
+1. **Node and sideby.** `node --version` must be 22.18 or newer; otherwise tell the user to upgrade Node and stop. `sideby --version`; when it is missing, run `npm i -g sideby` (Claude quota and shell functions need the global install, not `npx`).
+2. **This skill.** If it was not installed with `npx skills add Adonis0123/sideby -g`, install it that way so it stays current; `sideby doctor` warns when it is for another version.
+3. **Hosts and accounts.** `sideby list --json`. `families[].installed: false` means that Host CLI is not on PATH: give the user its `installUrl` and stop; never install a Host unasked. No `<family>:main` in `accounts` means the Host has never run: ask the user to start it once (for example `claude`), because `new` builds on the Main Account.
+4. **What it will share.** `sideby families <family> --json`, then tell the user in a sentence or two (see `sharing.md`): skills, hooks, rules and settings come from the Main Account; sign-in, sessions and history are the new account's own.
+5. **Create.**
+   - The user gave no name, or said "cc00x" / "the next one": `sideby new <family> --next --json`. It picks the next number (`008` after `001`…`007`) and, when existing short commands show a pattern (`cc007` for `claude:007`), adds the next one (`cc008`). Read `suggestion`: `aliasProblem` means that short command was taken and left out; tell the user.
+   - The user gave a name: `sideby new <family> <name> --json`; a short command they named: add `--alias <short>`.
+   - An API account (DeepSeek, a gateway, …): add `--api`.
+   - A short command the user did not ask for and no pattern suggests: none. Do not invent a prefix.
+6. **user: sign in or fill in the key.**
+   - Subscription account: `sideby login <ref>`. It opens the Host's sign-in in their browser. For pi it starts pi; they type `/login`.
+   - API account: they open the `proxy.env` path that `new` printed and fill in the values. Never read or write it, and never ask for the key in chat.
+7. **Short command in new terminals.** If `~/.config/sideby/config.json` has no `shellInitFile`, and `~/.zshrc` (bash: `~/.bashrc`) has no line containing `sideby shell-init`, say so and append `eval "$(sideby shell-init zsh)"` (or `bash`). It takes effect in new terminals. Skip this when the user wanted no short command.
+8. **Verify.** `sideby doctor <ref> --json` should report no `fail`; fix only the new account with `sideby doctor <ref> --fix`. After the user signed in, `sideby list --json` shows `login: "logged-in"` for it.
+9. **Optional, Claude Code:** for quota in `sideby quota` and the panel, follow `quota.md` (it needs the user's yes).
+
+Finish with how to start it: the short command in a new terminal (`cc008`), or `sideby run <ref>`; and `sideby ui` to see every account's quota.
+
+## When a step fails
+
+| Result | Do |
+|---|---|
+| `new` exit 1, `code: "alias-invalid"` | Nothing was created. Pick another short command with the user, or leave `--alias` out. |
+| `new` says the directory exists | The account is already there: `sideby list --json`, then continue from step 6. |
+| `new` says the Main Account is missing | Step 3: the user starts the Host once. |
+| `npm i -g` fails with `EACCES` | npm's global directory is not writable; tell the user to use a Node version manager (nvm, fnm) rather than `sudo`. |
+| `doctor` reports `link.real-file` | The account already had its own file there; show the hint, do not move it without the user. |

package/skills/sideby/references/sharing.md

@@ -0,0 +1,17 @@
+# What accounts share
+
+Answer from `sideby families [family] --json`, not from memory: it covers plugin families and the user's own `extraSharedItems`. Each `shared[]` entry has `path`, `mode` and `meaning`, a sentence you can quote.
+
+- **Shared** (one copy, from the Main Account): `link` items. A change in the Main Account reaches every account at once.
+- **Kept equal**: `copy` and `link-or-copy` items, a subscription account's `local-if-api` item, and the one key of a `json-key` item (Claude's MCP servers in `.claude.json`). `sideby doctor --fix` brings them back in line after the Main Account changes.
+- **The account's own**: `local` items (copied once, then theirs), an API account's `local-if-api` item (it starts as a copy, so its endpoint and model never change the Main Account's), and `info` items such as `auth.json` (sign-in; never shared, never read).
+- **Not in the list at all**: sessions, history and everything else in the account directory belong to that account. That is why two accounts can run at the same time.
+
+An item the Main Account does not have is skipped: nothing to share, no Finding.
+
+To share one more file or directory (a `scripts` folder, a status line script), add it to config `extraSharedItems`, for example `{ "extraSharedItems": { "claude": [{ "path": "scripts", "mode": "link" }] } }` in `~/.config/sideby/config.json`, then run `sideby doctor claude --fix` to link it into every account. Keep the user's other config keys; never add a path with `..` or an absolute path.
+
+Two answers people often need:
+
+- "Will my new account have my MCP servers?" Claude Code: yes, `new` copies the `mcpServers` entry and `doctor --fix` keeps it equal later; OAuth servers (GitHub, Figma) still need each account to authorize once. Codex: yes for subscription accounts, through the linked `config.toml`.
+- "Will it see my old sessions?" No. Sessions stay in the account that made them; `sideby run <old-account> -- --resume` reopens them there.