sideby 0.1.0 → 0.2.1

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.