sideby 0.1.0 → 0.2.1

package/dist/src/families/shared/sessions.js

@@ -0,0 +1,70 @@
+// Reading which session a Host command resumes, and whether an Account holds it (ADR-0007).
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const isSessionId = (s) => s !== undefined && SESSION_ID.test(s);
+/** Arguments before the first `--`, the ones the Host reads as its own options. */
+const options = (args) => {
+    const end = args.indexOf('--');
+    return end === -1 ? args : args.slice(0, end);
+};
+/** The id after `--resume <id>`, `--resume=<id>` or `-r <id>`; Claude Code and Grok Build share this form. */
+export function resumeFlagSession(args) {
+    const opts = options(args);
+    for (let i = 0; i < opts.length; i++) {
+        const a = opts[i];
+        const id = a.startsWith('--resume=')
+            ? a.slice('--resume='.length)
+            : a === '--resume' || a === '-r'
+                ? opts[i + 1]
+                : undefined;
+        if (isSessionId(id))
+            return id;
+    }
+    return undefined;
+}
+/** The first UUID after the `resume` subcommand (`codex resume [options] <id>`). */
+export function resumeSubcommandSession(args) {
+    const opts = options(args);
+    const at = opts.indexOf('resume');
+    return at === -1 ? undefined : opts.slice(at + 1).find(isSessionId);
+}
+/** Modification time in ms of the first of `paths` that exists with the wanted type. */
+async function firstWrittenAt(paths, type) {
+    for (const p of paths) {
+        try {
+            const st = await stat(p);
+            if (type === 'file' ? st.isFile() : st.isDirectory())
+                return st.mtimeMs;
+        }
+        catch {
+            // not here
+        }
+    }
+    return undefined;
+}
+async function subdirs(dir) {
+    try {
+        return (await readdir(dir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => join(dir, e.name));
+    }
+    catch {
+        return [];
+    }
+}
+/** `<dir>/*` + `/<entry>`: one level of grouping directories (Claude projects, Grok working directories). */
+export async function groupedEntryWrittenAt(dir, entry, type) {
+    return firstWrittenAt((await subdirs(dir)).map((d) => join(d, entry)), type);
+}
+/** A file anywhere under `dir` whose name ends with `suffix` (Codex `sessions/YYYY/MM/DD/rollout-…-<id>.jsonl`). */
+export async function nestedFileWrittenAt(dir, suffix) {
+    let names;
+    try {
+        names = await readdir(dir, { recursive: true });
+    }
+    catch {
+        return undefined;
+    }
+    return firstWrittenAt(names.filter((n) => n.endsWith(suffix)).map((n) => join(dir, n)), 'file');
+}

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 export { createPanelHandler, type PanelFamily, type PanelHandler, type PanelHandlerOptions, type PanelState, } from './panel/handler.ts';
 export { startPanelServer } from './panel/server.ts';
 export type { PanelTheme, PanelThemeTokens } from './panel/theme.ts';
-export { type AccountStatus, createRuntime, type DoctorOptions, type FamilyInfo, type Runtime, } from './runtime.ts';
+export { type AccountStatus, createRuntime, type DoctorOptions, type FamilyDetail, type FamilyInfo, type Runtime, type SharedItemInfo, } from './runtime.ts';
 export type * from './types.ts';

package/dist/src/panel/handler.d.ts

@@ -54,8 +54,6 @@ export declare function healthByAccount(history: DoctorHistory | undefined): Map
     fail: number;
     warn: number;
 }>;
-/** Alias names per Account ref, sorted. An alias whose target matches no Account is left out. */
-export declare function aliasesByAccount(aliases: Readonly<Record<string, string>> | undefined, accounts: readonly Account[]): Map<string, string[]>;
 /** A Family as the page sees it: FamilyInfo plus the mark from its FamilyDef. */
 export type PanelFamily = FamilyInfo & {
     logo?: FamilyLogo;

package/dist/src/panel/handler.js

@@ -1,6 +1,6 @@
 // HTTP handler for the local Panel. Mountable under any basePath; standalone and embedded use the same rules.
 import { randomBytes, timingSafeEqual } from 'node:crypto';
-import { resolveRef } from '../core/accounts.js';
+import { aliasesByAccount } from '../core/accounts.js';
 import { aliasArgs, aliasRefs } from '../core/config.js';
 import { UserError } from '../core/errors.js';
 import { planHandoff } from '../core/handoff.js';
@@ -31,21 +31,6 @@ export function healthByAccount(history) {
         });
     return out;
 }
-/** Alias names per Account ref, sorted. An alias whose target matches no Account is left out. */
-export function aliasesByAccount(aliases, accounts) {
-    const out = new Map();
-    for (const [alias, target] of Object.entries(aliases ?? {})) {
-        let ref;
-        try {
-            ref = resolveRef(target, accounts).ref;
-        }
-        catch {
-            continue;
-        }
-        out.set(ref, [...(out.get(ref) ?? []), alias].sort());
-    }
-    return out;
-}
 /** The `handoff` map of the Panel state, from the statuses and Quota already read for the page. */
 export function handoffByFamily(rt, accounts, now) {
     const out = {};

package/dist/src/runtime.d.ts

@@ -5,12 +5,20 @@ import { type DoctorReport } from './core/doctor.ts';
 import { UserError } from './core/errors.ts';
 import { type HandoffPlan } from './core/handoff.ts';
 import { type DoctorHistory } from './core/last-doctor.ts';
-import { type PreparedLaunch } from './core/launch.ts';
+import { type HostLaunch, type PreparedLaunch } from './core/launch.ts';
 import { type Paths } from './core/paths.ts';
 import { type Shell, type ShellInitWrite } from './core/shell-init.ts';
 import { type BuiltinPlugin, type LoadedPlugin, type PluginLoadError } from './plugins/loader.ts';
-import type { Account, AccountIdentity, Env, FamilyDef, LoginState, QuotaResult, QuotaSetupPlan, ReadContext, UsageResult } from './types.ts';
+import type { Account, AccountIdentity, Env, FamilyDef, LoginState, QuotaResult, QuotaSetupPlan, ReadContext, ShareMode, UsageResult } from './types.ts';
 export type { AccountIdentity, AccountRefError, DoctorHistory, Shell, ShellInitWrite };
+/** How `sideby resume` starts the Host (spec §3.15). */
+export interface ResumeLaunch {
+    launch: HostLaunch;
+    /** The session the Host arguments resume by id, when they name one. */
+    sessionId?: string;
+    /** Set when the session lives in a non-main Account and `launch` starts that Account as `run` would. */
+    account?: Account;
+}
 /** What happened to the alias asked for with a new Account. */
 export interface AliasResult {
     name: string;
@@ -45,6 +53,37 @@ export interface FamilyInfo {
     /** Plugin that provides the Family. */
     plugin: string;
 }
+/** One Shared Item as `sideby families` reports it (spec §3.16). */
+export interface SharedItemInfo {
+    path: string;
+    mode: ShareMode;
+    key?: string;
+    mainPath?: string;
+    credential?: boolean;
+    noSymlink?: boolean;
+    /** `family` from the FamilyDef, `config` from `extraSharedItems`. */
+    source: 'family' | 'config';
+    /** What the item looks like in an Account, in one fixed sentence. */
+    meaning: string;
+}
+/** A Family's facts for agents and docs: FamilyInfo plus layout, sign-in, sources and Shared Items (spec §3.16). */
+export interface FamilyDetail extends FamilyInfo {
+    /** Relative to HOME: `{ main: '.claude', account: '.claude-<name>' }`. */
+    layout: {
+        main: string;
+        account: string;
+    };
+    selectVar: string;
+    /** `args` is null when sign-in happens inside the Host. */
+    login: {
+        args: string[] | null;
+        hint: string;
+    };
+    quota: boolean;
+    usage: boolean;
+    quotaSetup: boolean;
+    shared: SharedItemInfo[];
+}
 export interface AccountStatus extends Account {
     familyTitle: string;
     hostInstalled: boolean;
@@ -84,6 +123,8 @@ export interface Runtime {
     plugins: readonly LoadedPlugin[];
     pluginErrors: readonly PluginLoadError[];
     familyInfo(): Promise<FamilyInfo[]>;
+    /** Every loaded Family with its layout, sign-in, quota support and Shared Items (config extras included). */
+    familyDetails(): Promise<FamilyDetail[]>;
     accounts(): Promise<Account[]>;
     resolve(ref: string): Promise<Account>;
     status(account: Account): Promise<AccountStatus>;
@@ -129,6 +170,11 @@ export interface Runtime {
     /** Rewrites the configured `shellInitFile` of each shell (all configured ones by default). */
     writeShellInitFiles(shells?: readonly Shell[]): Promise<ShellInitWrite[]>;
     prepareLaunch(ref: string, userArgs: readonly string[], command: 'run' | 'login'): Promise<PreparedLaunch>;
+    /**
+     * Starts the non-main Account that holds the session the Host arguments resume, or else the Host unchanged
+     * (spec §3.15). Throws UnknownFamilyError, or a UserError when the Family cannot route sessions.
+     */
+    resumeLaunch(familyId: string, userArgs: readonly string[]): Promise<ResumeLaunch>;
     quota(account: Account): Promise<QuotaResult>;
     usage(account: Account): Promise<UsageResult>;
     /**

package/dist/src/runtime.js

@@ -9,6 +9,8 @@ import { identityOf } from './core/identity.js';
 import { mergeDoctorHistory, readDoctorHistory, writeDoctorHistory, } from './core/last-doctor.js';
 import { prepareLaunch, which } from './core/launch.js';
 import { resolvePaths } from './core/paths.js';
+import { findResumeRoute } from './core/resume.js';
+import { shareMeaning } from './core/share-meaning.js';
 import { SHELLS, shellInitScript, writeShellInitFile, } from './core/shell-init.js';
 import { packageVersion } from './core/version.js';
 import { BUILTIN_PLUGINS } from './families/index.js';
@@ -103,6 +105,32 @@ export async function createRuntime(opts = {}) {
                 plugin: loaded.familyOwner.get(f.id) ?? 'unknown',
             })));
         },
+        async familyDetails() {
+            const info = new Map((await rt.familyInfo()).map((f) => [f.id, f]));
+            return [...families.values()].map((f) => {
+                // The merged list holds the config's own objects, so identity tells which ones came from `extraSharedItems`.
+                const fromConfig = new Set(config.extraSharedItems?.[f.id] ?? []);
+                return {
+                    ...info.get(f.id),
+                    layout: { main: f.layout.main, account: f.layout.account },
+                    selectVar: f.selectVar,
+                    login: { args: f.login.args ? [...f.login.args] : null, hint: f.login.hint },
+                    quota: Boolean(f.readQuota),
+                    usage: Boolean(f.readUsage),
+                    quotaSetup: Boolean(f.quotaSetup),
+                    shared: f.sharedItems.map((item) => ({
+                        path: item.path,
+                        mode: item.mode,
+                        ...(item.key ? { key: item.key } : {}),
+                        ...(item.mainPath ? { mainPath: item.mainPath } : {}),
+                        ...(item.credential ? { credential: true } : {}),
+                        ...(item.noSymlink ? { noSymlink: true } : {}),
+                        source: fromConfig.has(item) ? 'config' : 'family',
+                        meaning: shareMeaning(item),
+                    })),
+                };
+            });
+        },
         accounts,
         async resolve(ref) {
             return resolveRef(ref, await accounts(), aliasRefs(config.aliases));
@@ -291,7 +319,14 @@ export async function createRuntime(opts = {}) {
             return null;
         },
         async shellInitScript() {
-            return shellInitScript(await accounts(), config.aliases);
+            const list = await accounts();
+            // Routing helps only a Family that can route and has somewhere else to route to (spec §3.15).
+            const routes = config.resumeRouting
+                ? [...families.values()]
+                    .filter((f) => f.resumedSession && f.sessionWrittenAt && list.some((a) => a.family === f.id && !a.isMain))
+                    .map((f) => ({ family: f.id, bin: f.bin, selectVar: f.selectVar }))
+                : [];
+            return shellInitScript(list, config.aliases, routes);
         },
         async writeShellInitFiles(shells = SHELLS) {
             const out = [];
@@ -315,6 +350,24 @@ export async function createRuntime(opts = {}) {
                 bus,
             });
         },
+        async resumeLaunch(familyId, userArgs) {
+            const family = familyOf(familyId);
+            if (!family.resumedSession || !family.sessionWrittenAt)
+                throw new UserError(`${family.title} sessions cannot be routed; start an account yourself with \`sideby run <account> -- …\``);
+            const host = { family, bin: family.bin, args: [...userArgs], env };
+            // A select variable already set means an Account was chosen on purpose: run the Host as it is.
+            if (env[family.selectVar])
+                return { launch: host };
+            const route = await findResumeRoute(family, await accounts(), userArgs);
+            const id = route.sessionId ? { sessionId: route.sessionId } : {};
+            if (!route.account || route.account.isMain)
+                return { launch: host, ...id };
+            return {
+                launch: await rt.prepareLaunch(route.account.ref, userArgs, 'run'),
+                ...id,
+                account: route.account,
+            };
+        },
         async quota(account) {
             if (account.kind === 'api')
                 return { status: 'unavailable', reason: 'api-account' };

package/dist/src/types.d.ts

@@ -79,6 +79,13 @@ export interface FamilyDef {
     readUsage?(account: Account, ctx: ReadContext): Promise<UsageResult>;
     /** One-time, reversible change that lets the Host report Quota (Claude: status line wrapper). */
     quotaSetup?: QuotaSetup;
+    /**
+     * The session these Host arguments resume by id (UUID-shaped), or undefined when they start a new session or
+     * pick one another way. With `sessionWrittenAt` it lets `sideby resume` find the Account (ADR-0007).
+     */
+    resumedSession?(args: readonly string[]): string | undefined;
+    /** When the Account holds the session, the last write time of its file in ms; otherwise undefined. */
+    sessionWrittenAt?(account: Account, sessionId: string): Promise<number | undefined>;
 }
 /** Identity fields of a signed-in Account. */
 export interface AccountIdentity {

package/dist/testing/index.js

@@ -55,8 +55,9 @@ export async function fakeHost(h, name, opts = {}) {
 const fs = require('node:fs')
 const log = ${JSON.stringify(log)}
 const rec = (o) => fs.appendFileSync(log, JSON.stringify(o) + '\\n')
-rec({ argv: process.argv.slice(2), env: process.env, pid: process.pid })
+// Handlers first: tests signal the Host as soon as the start record appears.
 for (const s of ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']) process.on(s, () => { rec({ signal: s }); process.exit(${opts.sleep ? 100 : 0}) })
+rec({ argv: process.argv.slice(2), env: process.env, pid: process.pid })
 const finish = () => {
   ${opts.selfSignal ? `process.removeAllListeners(${JSON.stringify(opts.selfSignal)}); process.kill(process.pid, ${JSON.stringify(opts.selfSignal)})` : `process.exit(${opts.exitCode ?? 0})`}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sideby",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Run every AI coding account side by side: Claude Code, Codex, Grok and pi, with one shared config and a quota panel.",
   "license": "MIT",
   "type": "module",

package/schemas/config.json

@@ -145,6 +145,10 @@
         }
       }
     },
+    "resumeRouting": {
+      "type": "boolean",
+      "description": "Make `sideby shell-init` also define Host-named functions (`claude`, `codex`, `grok`) that resume a session by id in the Account that holds it. Off by default."
+    },
     "shellInitFile": {
       "type": "object",
       "properties": {

package/schemas/families.json

@@ -0,0 +1,205 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/families.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "families"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "families": {
+      "type": "array",
+      "items": {
+        "allOf": [
+          {
+            "type": "object",
+            "required": [
+              "id",
+              "title",
+              "bin",
+              "installUrl",
+              "installed",
+              "plugin"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "title": {
+                "type": "string"
+              },
+              "bin": {
+                "type": "string"
+              },
+              "installUrl": {
+                "type": "string"
+              },
+              "installed": {
+                "type": "boolean"
+              },
+              "plugin": {
+                "type": "string"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "layout",
+              "selectVar",
+              "login",
+              "quota",
+              "usage",
+              "quotaSetup",
+              "shared"
+            ],
+            "properties": {
+              "layout": {
+                "type": "object",
+                "required": [
+                  "main",
+                  "account"
+                ],
+                "properties": {
+                  "main": {
+                    "type": "string"
+                  },
+                  "account": {
+                    "type": "string"
+                  }
+                },
+                "description": "Relative to HOME, for example `.claude` and `.claude-<name>`."
+              },
+              "selectVar": {
+                "type": "string",
+                "description": "Environment variable that selects a non-main Account directory."
+              },
+              "login": {
+                "type": "object",
+                "required": [
+                  "args",
+                  "hint"
+                ],
+                "properties": {
+                  "args": {
+                    "anyOf": [
+                      {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "Arguments of the Host's sign-in command; null when sign-in happens inside the Host."
+                  },
+                  "hint": {
+                    "type": "string"
+                  }
+                }
+              },
+              "quota": {
+                "type": "boolean"
+              },
+              "usage": {
+                "type": "boolean"
+              },
+              "quotaSetup": {
+                "type": "boolean",
+                "description": "Quota needs `sideby quota setup <family>` once."
+              },
+              "shared": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "path",
+                    "mode",
+                    "source",
+                    "meaning"
+                  ],
+                  "properties": {
+                    "path": {
+                      "type": "string"
+                    },
+                    "mode": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "const": "link"
+                        },
+                        {
+                          "type": "string",
+                          "const": "copy"
+                        },
+                        {
+                          "type": "string",
+                          "const": "link-or-copy"
+                        },
+                        {
+                          "type": "string",
+                          "const": "link-or-local"
+                        },
+                        {
+                          "type": "string",
+                          "const": "local"
+                        },
+                        {
+                          "type": "string",
+                          "const": "local-if-api"
+                        },
+                        {
+                          "type": "string",
+                          "const": "info"
+                        },
+                        {
+                          "type": "string",
+                          "const": "json-key"
+                        }
+                      ]
+                    },
+                    "key": {
+                      "type": "string"
+                    },
+                    "mainPath": {
+                      "type": "string"
+                    },
+                    "credential": {
+                      "type": "boolean"
+                    },
+                    "noSymlink": {
+                      "type": "boolean"
+                    },
+                    "source": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "const": "family"
+                        },
+                        {
+                          "type": "string",
+                          "const": "config"
+                        }
+                      ]
+                    },
+                    "meaning": {
+                      "type": "string",
+                      "description": "What the item looks like in each Account, in one fixed sentence."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "title": "sideby families --json"
+}

package/schemas/new.json

@@ -175,6 +175,24 @@
         }
       },
       "description": "One entry per config `shellInitFile`, rewritten after the change."
+    },
+    "suggestion": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "alias": {
+          "type": "string"
+        },
+        "aliasProblem": {
+          "type": "string"
+        }
+      },
+      "description": "Only with `--next`: the picked name, the short command that follows the existing pattern, or why that short command was left out."
     }
   },
   "title": "sideby new --json"

package/skills/sideby/SKILL.md

@@ -1,22 +1,27 @@
 ---
 name: sideby
-description: Use when the user runs several AI coding accounts (Claude Code, Codex, Grok Build, pi) and wants to see them, check how much quota or usage each has left, move on to another account because one hit its 5-hour or weekly limit, create an account or API account, add a short command (alias) for one, or repair a broken or drifted account directory (skills, hooks, rules or settings not shared, wrong symlinks, credential file permissions). Drives the `sideby` CLI with `--json` and leaves sign-in, credentials and starting sessions to the user.
+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.1.0"
+  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`). Use `npx sideby` if the command is not installed. Requires Node 22.18+.
+`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.** Tell them to run `sideby login <ref>` in their own terminal. OAuth needs their browser and their decision.
+- **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.
-- **Show before you change.** Read-only commands first; changes only after the user has seen what will change.
+- **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
@@ -31,10 +36,12 @@ Account refs are `<family>:<name>`; a bare `<name>` works only when it is unique
 
 | 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, an API account or a short command | `sideby new`, `sideby alias add` | `references/accounts.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]` | — |
@@ -45,6 +52,8 @@ Read only the reference the task needs.
 
 `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

package/skills/sideby/references/accounts.md

@@ -10,7 +10,7 @@ sideby new claude deepseek --api     # API account: ~/.claude-deepseek with a pr
 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; follow their existing pattern (`cc001`…`cc007` for `claude:001`…`claude:007` suggests `cc008`). 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.
+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: