sideby 0.1.0 → 0.2.2

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/panel/page-styles.js

@@ -3,9 +3,8 @@
 import { resolveTheme } from './theme.js';
 // Colors defined from other tokens; repeated in both schemes so they follow that scheme's base colors.
 const DERIVED_COLORS = `
-  --primary-border: var(--primary); --primary-hover-border: var(--primary-hover); --btn-text: var(--text);
-  --btn-hover-border: var(--border-strong); --btn-hover-text: var(--text); --check: var(--primary);
-  --logo-bg: var(--text); --logo-fg: var(--bg); --logo-line: transparent;
+  --btn-text: var(--text); --btn-hover-text: var(--accent); --check: var(--focus);
+  --logo-bg: var(--accent-soft); --logo-fg: var(--focus); --logo-line: var(--border);
   --focus-outline: 2px solid var(--focus); --focus-ring: none;`;
 // Design tokens. A host theme (theme.ts) layers its values over these: light values after LIGHT_TOKENS, dark values after
 // DARK_TOKENS. DARK_TOKENS sets every color token again, so a host's light colors never leak into dark mode, while
@@ -16,22 +15,24 @@ const LIGHT_TOKENS = `
   --title-weight: 750; --heading-weight: 650; --strong-weight: 600; --button-weight: 600; --primary-weight: var(--button-weight);
   --radius: 14px; --ctl-radius: 8px; --chip-radius: 999px; --ctl-h: 34px; --ctl-h-sm: 28px; --field-h: 36px;
   --content-width: 1180px; --gutter: 24px;
-  --bg: #f5f6f8; --surface: #ffffff; --surface-2: #f0f2f5; --border: #e2e5ea; --border-strong: #cfd4dc;
-  --text: #15171c; --muted: #5b6372; --faint: #8b93a1; --accent: #4f46e5; --accent-soft: #eef0ff;
-  --primary: #4f46e5; --primary-hover: #4338ca; --primary-active: #3730a3; --on-primary: #ffffff;
-  --hover: #eceef2; --active: #e2e5ea; --focus: #6366f1;
+  --bg: #f2f8fc; --surface: #fcfcfa; --surface-2: #f6fafd; --border: #dce8f0; --border-strong: #c5d7e4;
+  --text: #15171c; --muted: #555b63; --faint: #8b93a1; --accent: #27658f; --accent-soft: #e5f2fb;
+  --primary: #e1f0fb; --primary-hover: #d2e8f9; --primary-active: #c3e0f6; --on-primary: #1f6396;
+  --primary-border: #b9d8ef; --primary-hover-border: #9cc7e8; --btn-hover-border: #8fbde3;
+  --hover: #f0f7fc; --active: #e6f1fa; --focus: #3f8fc4;
   --ok: #15803d; --ok-bar: #22c55e; --ok-soft: #e8f7ee; --warn: #b45309; --warn-bar: #f59e0b; --warn-soft: #fdf3e2;
-  --fail: #c81e1e; --fail-bar: #ef4444; --fail-soft: #fdecec; --track: #e9ecf1;
+  --fail: #c81e1e; --fail-bar: #ef4444; --fail-soft: #fdecec; --track: #e4edf4;
   --spark: oklch(from var(--accent) clamp(0.55, l, 0.62) max(c, 0.14) h); --spark-soft: oklch(from var(--accent) 0.83 calc(max(c, 0.14) * 0.6) h);
   --shadow: 0 1px 2px rgba(16,24,40,.04), 0 2px 8px rgba(16,24,40,.05);
   --float-shadow: 0 10px 30px rgba(16,24,40,.14), 0 2px 6px rgba(16,24,40,.06);${DERIVED_COLORS}`;
 const DARK_TOKENS = `
-  --bg: #0d0f12; --surface: #15181d; --surface-2: #1c2026; --border: #262b33; --border-strong: #353c47;
-  --text: #e7e9ee; --muted: #a0a8b5; --faint: #6c7480; --accent: #8b87ff; --accent-soft: #23224a;
-  --primary: #5b54e8; --primary-hover: #6a64ef; --primary-active: #4f46e5; --on-primary: #ffffff;
-  --hover: #22272e; --active: #2a3038; --focus: #8b87ff;
+  --bg: #0e1621; --surface: #141e2a; --surface-2: #111a25; --border: #233244; --border-strong: #30455b;
+  --text: #e6edf3; --muted: #9aa9b8; --faint: #6b7a8a; --accent: #8cc4ee; --accent-soft: #16314a;
+  --primary: #173a58; --primary-hover: #1d4769; --primary-active: #22537a; --on-primary: #d3e9fa;
+  --primary-border: #2b5b82; --primary-hover-border: #3a6f99; --btn-hover-border: #4a7fa8;
+  --hover: #182736; --active: #1c2f42; --focus: #5aa7dc;
   --ok: #4ade80; --ok-bar: #22c55e; --ok-soft: #13291c; --warn: #fbbf24; --warn-bar: #f59e0b; --warn-soft: #2d2410;
-  --fail: #f87171; --fail-bar: #ef4444; --fail-soft: #331717; --track: #252a32;
+  --fail: #f87171; --fail-bar: #ef4444; --fail-soft: #331717; --track: #1f2c3a;
   --spark: oklch(from var(--accent) clamp(0.7, l, 0.78) max(c, 0.14) h); --spark-soft: oklch(from var(--accent) 0.45 calc(max(c, 0.14) * 0.6) h);
   --shadow: 0 1px 2px rgba(0,0,0,.3); --float-shadow: 0 12px 32px rgba(0,0,0,.5), 0 2px 6px rgba(0,0,0,.3);${DERIVED_COLORS}`;
 /**

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.2",
   "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"