sideby 0.12.1 → 0.13.1

package/dist/src/core/skill-check.js

@@ -2,7 +2,7 @@
 // sideby version teaches commands this CLI may not have, so a version mismatch is a warning with the
 // reinstall command. Not installed is not a problem.
 import { readFile, realpath } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { mainDirOf } from './accounts.js';
 import { tildify } from './paths.js';
 export const SKILL_INSTALL = 'npx skills add Adonis0123/sideby -g';
@@ -12,6 +12,34 @@ export function skillVersionOf(text) {
     const meta = front && /^metadata:[ \t]*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m.exec(front)?.[1];
     return (meta && /^[ \t]+version:[ \t]*['"]?([^'"\s]+)/m.exec(meta)?.[1]) || null;
 }
+/**
+ * The versions of the sideby skills an agent reads on this machine (`null`: a skill without one): where
+ * `npx skills add -g` puts it (`~/.agents/skills`) and Claude Code's user skills. Read for a `--json` output's
+ * `_notice`, so it looks at two fixed files only; Doctor checks every Family's main directory.
+ */
+export async function installedSkillVersions(home) {
+    return (await installedSkills(home)).map((s) => s.version);
+}
+/** The same skills with the real folder each lives in (for `sideby update`, which may update them). */
+export async function installedSkills(home) {
+    const seen = new Set();
+    const out = [];
+    for (const dir of [join(home, '.agents', 'skills'), join(home, '.claude', 'skills')]) {
+        try {
+            const real = await realpath(join(dir, 'sideby', 'SKILL.md'));
+            if (seen.has(real))
+                continue;
+            seen.add(real);
+            out.push({ dir: dirname(real), version: skillVersionOf(await readFile(real, 'utf8')) });
+        }
+        catch {
+            // not installed there
+        }
+    }
+    return out;
+}
+/** The command `sideby update` runs to update an installed sideby skill: it keeps the agents it was installed for. */
+export const SKILL_UPDATE = ['npx', '-y', 'skills', 'update', 'sideby', '-g', '-y'];
 /**
  * Checks, for each given Family, the sideby skill its Host reads: `<main>/skills/sideby`, and for Codex also
  * `~/.agents/skills/sideby` (where `npx skills add -g` installs and Codex reads user skills). A file is read

package/dist/src/core/update.d.ts

@@ -33,7 +33,7 @@ export interface UpdateCache {
         shown?: boolean;
     };
 }
-export type InstallKind = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'project' | 'source';
+export type InstallKind = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'project' | 'source' | 'local';
 export interface InstallMethod {
     kind: InstallKind;
     /** The installed package folder (real path). */
@@ -63,6 +63,10 @@ export interface UpdateDeps {
     }>;
     /** Starts `sideby ui --background --no-open --port <port>` from the newly installed code, detached; false when it could not start. */
     restartPanel: (env: Env, port: number) => Promise<boolean>;
+    /** Whether `sideby app install` put a desktop app in this home (its files carry the app marker). */
+    appInstalled: (home: string, env: Env) => Promise<boolean>;
+    /** Runs `sideby app install --json` from the newly installed code and waits; false when it failed. */
+    refreshApp: (env: Env) => Promise<boolean>;
 }
 /** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
 export declare function bindUpdateDeps(deps: Partial<UpdateDeps>): () => void;
@@ -84,7 +88,7 @@ type UpdateSettings = {
     };
 };
 /** Why Update Checks are off, or null when they are on (spec §3.23). */
-export declare function checksOff(env: Env, config: UpdateSettings): string | null;
+export declare function checksOff(env: Env, config: UpdateSettings, local?: boolean): string | null;
 export declare function readUpdateCache(paths: Paths): Promise<UpdateCache>;
 /**
  * Merges a change into the cache file. The file is read again first, and `change` may be a function of what is there
@@ -110,6 +114,27 @@ export declare function refreshUpdateCheck(paths: Paths, env: Env): Promise<Upda
 export declare function noticeLine(cache: UpdateCache, current: string, now: Date): string | null;
 /** What the CLI says once about the last Auto Update, or null. */
 export declare function autoUpdateLine(cache: UpdateCache): string | null;
+/** The `_notice` of a `--json` output (spec §3.23): what an agent should mention once its task is done. */
+export interface JsonNotice {
+    update?: {
+        current: string;
+        latest: string;
+        command: string;
+        message: string;
+    };
+    skill?: {
+        installed: string | null;
+        current: string;
+        command: string;
+        message: string;
+    };
+}
+/**
+ * The `_notice` for a `--json` output, from the cached Update Check and the versions of the installed sideby skills
+ * (`null` for one written before skills had a version); null when there is nothing to say or checks are off. It
+ * reads no network: an agent sees what the last check found, as a person sees the Update Notice.
+ */
+export declare function jsonNotice(cache: UpdateCache, current: string, config: UpdateSettings, env: Env, skills: readonly (string | null)[], skillCommand: string): JsonNotice | null;
 /**
  * What the CLI does after a command (spec §3.23), decided from the cache: the lines to print (the Auto Update result,
  * then the Update Notice), the change that records them, and whether to start a background check. The caller prints,
@@ -149,6 +174,8 @@ export interface UpdatePlan {
     command: string;
     canRun: boolean;
     releaseNotes: string;
+    /** The installed sideby skill, which an Update brings along (absent when none is installed). */
+    skill?: SkillUpdatePlan;
 }
 export declare function planFrom(method: InstallMethod, current: string, latest: string, env?: Env): UpdatePlan;
 /** The Install Method as outputs show it: no folder of this machine. */
@@ -170,9 +197,28 @@ export declare function shownPlan(plan: UpdatePlan): {
     command: string;
     canRun: boolean;
     releaseNotes: string;
+    skillUpdate?: SkillUpdatePlan | undefined;
 };
+/** What an Update does to the installed sideby skill (spec §3.23, ADR-0021 amendment 2026-10-17). */
+export interface SkillUpdatePlan {
+    /** Versions of the installed skills (`null`: one without a version). */
+    installed: (string | null)[];
+    /** Some installed skill is for another version than the one sideby will run. */
+    outdated: boolean;
+    command: string;
+    /** False when sideby must not run it; `reason` says why and the user runs `command` where it belongs. */
+    canRun: boolean;
+    reason?: string;
+}
+/** The skill part of an Update toward `target`; null when no sideby skill is installed. Reads two files. */
+export declare function skillUpdatePlan(home: string, target: string): Promise<SkillUpdatePlan | null>;
 /** Asks the registry now (whatever the switches say: the user asked) and returns what an Update would do. */
 export declare function planUpdate(paths: Paths, env: Env): Promise<UpdatePlan>;
+/** Updates the installed sideby skill when the plan says it is outdated and sideby may; null when it did nothing. */
+export declare function applySkillUpdate(plan: SkillUpdatePlan | undefined, env: Env, onOutput?: (text: string) => void): Promise<{
+    ok: boolean;
+    message: string;
+} | null>;
 export interface UpdateResult {
     ok: boolean;
     /** Exit code of the install command; absent when it did not run. */
@@ -181,11 +227,17 @@ export interface UpdateResult {
     message: string;
     /** A background Panel was running and is starting again from the new code. */
     restartedPanel: boolean;
+    /** The desktop app was installed and `sideby app install` ran again from the new code. */
+    refreshedApp: boolean;
     /** Another Update held the lock; nothing ran. */
     busy?: boolean;
+    /** The installed sideby skill was updated too (true), or that failed (false); absent when it was not tried. */
+    skillUpdated?: boolean;
+    skillMessage?: string;
 }
 /**
- * Runs the Update the plan names, then starts a running background Panel again from the new code. The caller has
+ * Runs the Update the plan names, then starts a running background Panel again from the new code and, when the
+ * desktop app is installed, runs `sideby app install` again from the new code. The caller has
  * shown the plan and got a confirmation (or this is an Auto Update). One Update runs at a time on this machine (the
  * CLI, a Panel and an Auto Update share the lock). `panelPort` gives the port of the background Panel to restart, or
  * null when none runs. A successful Update is recorded as said, so no notice for it follows.

package/dist/src/core/update.js

@@ -6,7 +6,8 @@ import { access, constants, mkdir, open, readdir, readFile, realpath, rm, stat }
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeFileAtomic } from './fs-safe.js';
-import { packageVersion } from './version.js';
+import { installedSkills, SKILL_INSTALL, SKILL_UPDATE } from './skill-check.js';
+import { localBuild, packageVersion, parseLocalBuild } from './version.js';
 export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -76,6 +77,20 @@ const realDeps = {
         });
         child.once('error', () => resolve(false));
     }),
+    appInstalled: async (home, env) => {
+        const { appInstalled } = await import('../desktop/app.js');
+        return appInstalled({ home, env, platform: process.platform });
+    },
+    refreshApp: (env) => new Promise((resolve) => {
+        // By name, like restartPanel: the new code records its own Node and entry and draws the current mark.
+        const child = spawn('sideby', ['app', 'install', '--json'], {
+            env: env,
+            stdio: 'ignore',
+            timeout: 120_000,
+        });
+        child.once('error', () => resolve(false));
+        child.once('close', (code) => resolve(code === 0));
+    }),
 };
 let override = {};
 /** Internal, for tests: replaces parts of the machine. Not part of the plugin or Portal contract. */
@@ -137,7 +152,10 @@ const set = (v) => v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !
 /** True in CI, where a notice is noise and a check is a request nobody reads. */
 export const inCi = (env) => set(env.CI) || set(env.CONTINUOUS_INTEGRATION) || set(env.BUILD_NUMBER);
 /** Why Update Checks are off, or null when they are on (spec §3.23). */
-export function checksOff(env, config) {
+export function checksOff(env, config, local = localBuild() !== null) {
+    // A Local Build (ADR-0024) follows the checkout: a notice or an Auto Update would only replace it with npm's.
+    if (local)
+        return 'this is a local build (pnpm local)';
     if (set(env.SIDEBY_NO_UPDATE_NOTIFIER))
         return 'SIDEBY_NO_UPDATE_NOTIFIER is set';
     if (set(env.NO_UPDATE_NOTIFIER))
@@ -334,6 +352,32 @@ export function autoUpdateLine(cache) {
         ? `sideby updated itself from ${a.from} to ${a.to} (${RELEASE_NOTES(a.to)})`
         : `sideby could not update itself to ${a.to}: ${a.message}`;
 }
+/**
+ * The `_notice` for a `--json` output, from the cached Update Check and the versions of the installed sideby skills
+ * (`null` for one written before skills had a version); null when there is nothing to say or checks are off. It
+ * reads no network: an agent sees what the last check found, as a person sees the Update Notice.
+ */
+export function jsonNotice(cache, current, config, env, skills, skillCommand) {
+    if (checksOff(env, config))
+        return null;
+    const out = {};
+    if (isNewer(cache.latest, current))
+        out.update = {
+            current,
+            latest: cache.latest,
+            command: 'sideby update',
+            message: `sideby ${cache.latest} is available (this is ${current}); \`sideby update\` shows what it runs and updates after --yes`,
+        };
+    const stale = skills.find((v) => v !== current);
+    if (stale !== undefined)
+        out.skill = {
+            installed: stale,
+            current,
+            command: skillCommand,
+            message: `the installed sideby skill is ${stale ? `for sideby ${stale}` : 'from before skills had a version'}; this sideby is ${current}. \`${skillCommand}\` updates it`,
+        };
+    return out.update || out.skill ? out : null;
+}
 /**
  * What the CLI does after a command (spec §3.23), decided from the cache: the lines to print (the Auto Update result,
  * then the Update Notice), the change that records them, and whether to start a background check. The caller prints,
@@ -373,6 +417,15 @@ export async function installMethod(env) {
         canUpdate: false,
         ...extra,
     });
+    try {
+        if (parseLocalBuild(JSON.parse(await readFile(join(packageDir, 'dist', 'build.json'), 'utf8'))))
+            return at('local', {
+                reason: 'it is a local build; run `pnpm local --off` in the sideby checkout to go back to npm',
+            });
+    }
+    catch {
+        // no build file: not a Local Build
+    }
     if (p.includes('/_npx/'))
         return at('npx', { reason: 'it runs from the npx cache, which fetches a version per call' });
     // Volta keeps a global package under its own npm prefix; installing there behind its back breaks its records.
@@ -436,6 +489,8 @@ export function updateCommand(method, version, env = {}) {
             return { text: `npm install ${spec}` };
         case 'source':
             return { text: 'git pull && pnpm install' };
+        case 'local':
+            return { text: 'pnpm local --off' };
     }
 }
 // ---- running sessions
@@ -504,17 +559,73 @@ export function shownPlan(plan) {
         command: plan.command,
         canRun: plan.canRun,
         releaseNotes: plan.releaseNotes,
+        ...(plan.skill ? { skillUpdate: plan.skill } : {}),
+    };
+}
+/** The folder holding `dir` that is a git work tree, if any: a skill there is managed by that repository. */
+async function gitRootOf(dir) {
+    for (let d = dir;; d = dirname(d)) {
+        try {
+            await stat(join(d, '.git'));
+            return d;
+        }
+        catch {
+            // keep looking up
+        }
+        if (dirname(d) === d)
+            return null;
+    }
+}
+/** The skill part of an Update toward `target`; null when no sideby skill is installed. Reads two files. */
+export async function skillUpdatePlan(home, target) {
+    const skills = await installedSkills(home);
+    if (!skills.length)
+        return null;
+    const installed = skills.map((s) => s.version);
+    const plan = {
+        installed,
+        outdated: installed.some((v) => v !== target),
+        command: SKILL_UPDATE.join(' '),
+        canRun: true,
     };
+    for (const s of skills) {
+        const root = await gitRootOf(s.dir);
+        if (root) {
+            const at = root.startsWith(home) ? `~${root.slice(home.length)}` : root;
+            return {
+                ...plan,
+                command: SKILL_INSTALL,
+                canRun: false,
+                reason: `the skill is in the git repository ${at}, so sideby leaves it alone; update it where that repository comes from`,
+            };
+        }
+    }
+    return plan;
 }
 /** Asks the registry now (whatever the switches say: the user asked) and returns what an Update would do. */
 export async function planUpdate(paths, env) {
     const latest = await fetchLatest(env);
     const at = deps().now().toISOString();
     await updateUpdateCache(paths, { checkedAt: at, triedAt: at, latest }).catch(() => { });
-    return planFrom(await installMethod(env), packageVersion(), latest, env);
+    const plan = planFrom(await installMethod(env), packageVersion(), latest, env);
+    const skill = await skillUpdatePlan(paths.home, plan.available ? latest : plan.current).catch(() => null);
+    return skill ? { ...plan, skill } : plan;
+}
+/** Updates the installed sideby skill when the plan says it is outdated and sideby may; null when it did nothing. */
+export async function applySkillUpdate(plan, env, onOutput) {
+    if (!plan?.outdated || !plan.canRun)
+        return null;
+    const [file, ...args] = SKILL_UPDATE;
+    const r = await deps()
+        .exec(file, args, { env, ...(onOutput ? { onOutput } : {}) })
+        .catch((e) => ({ code: 1, output: e instanceof Error ? e.message : String(e) }));
+    return r.code === 0
+        ? { ok: true, message: 'updated the sideby skill' }
+        : { ok: false, message: `\`${plan.command}\` failed (exit ${r.code}); run it yourself to see why` };
 }
 /**
- * Runs the Update the plan names, then starts a running background Panel again from the new code. The caller has
+ * Runs the Update the plan names, then starts a running background Panel again from the new code and, when the
+ * desktop app is installed, runs `sideby app install` again from the new code. The caller has
  * shown the plan and got a confirmation (or this is an Auto Update). One Update runs at a time on this machine (the
  * CLI, a Panel and an Auto Update share the lock). `panelPort` gives the port of the background Panel to restart, or
  * null when none runs. A successful Update is recorded as said, so no notice for it follows.
@@ -526,6 +637,7 @@ export async function applyUpdate(paths, plan, env, opts = {}) {
         output: '',
         message,
         restartedPanel: false,
+        refreshedApp: false,
         ...extra,
     });
     if (!cmd.run)
@@ -548,12 +660,20 @@ export async function applyUpdate(paths, plan, env, opts = {}) {
         }).catch(() => { });
         const port = opts.panelPort ? await opts.panelPort().catch(() => null) : null;
         const restarted = port !== null && (await d.restartPanel(env, port).catch(() => false));
+        // The desktop app records the Node and entry it starts and carries the icon of the version that wrote it, so
+        // the new code writes it again. Only where one is installed; a failure here never fails the Update.
+        const installed = await d.appInstalled(paths.home, env).catch(() => false);
+        const refreshed = installed && (await d.refreshApp(env).catch(() => false));
+        // The skill teaches agents this version's commands, so it follows the CLI; a failure there keeps the Update.
+        const skill = await applySkillUpdate(plan.skill, env, opts.onOutput);
         return {
             ok: true,
             code: 0,
             output: r.output,
             message: `updated sideby from ${plan.current} to ${plan.latest}`,
             restartedPanel: restarted,
+            refreshedApp: refreshed,
+            ...(skill ? { skillUpdated: skill.ok, skillMessage: skill.message } : {}),
         };
     }
     finally {

package/dist/src/core/version.d.ts

@@ -7,3 +7,14 @@ export declare function packageVersion(): string;
  * id for tests.
  */
 export declare function buildId(env?: NodeJS.ProcessEnv): string;
+/** What `pnpm local` records about a Local Build (ADR-0024). */
+export interface LocalBuild {
+    commit: string;
+    /** The working tree had changes that were not committed. */
+    dirty: boolean;
+    builtAt: string;
+}
+/** The Local Build fields of a `dist/build.json`, or null for a published build or anything unexpected. */
+export declare function parseLocalBuild(data: unknown): LocalBuild | null;
+/** The running code's Local Build, or null when it was published or runs from source. */
+export declare function localBuild(): LocalBuild | null;

package/dist/src/core/version.js

@@ -44,3 +44,29 @@ export function buildId(env = process.env) {
     cachedBuild = `${packageVersion()}+${id}`;
     return cachedBuild;
 }
+/** The Local Build fields of a `dist/build.json`, or null for a published build or anything unexpected. */
+export function parseLocalBuild(data) {
+    if (!data || typeof data !== 'object')
+        return null;
+    const d = data;
+    if (d.local !== true)
+        return null;
+    return {
+        commit: typeof d.commit === 'string' ? d.commit : '',
+        dirty: d.dirty === true,
+        builtAt: typeof d.builtAt === 'string' ? d.builtAt : '',
+    };
+}
+let cachedLocal;
+/** The running code's Local Build, or null when it was published or runs from source. */
+export function localBuild() {
+    if (cachedLocal !== undefined)
+        return cachedLocal;
+    try {
+        cachedLocal = parseLocalBuild(JSON.parse(readFileSync(new URL('../../build.json', import.meta.url), 'utf8')));
+    }
+    catch {
+        cachedLocal = null;
+    }
+    return cachedLocal;
+}

package/dist/src/desktop/app.d.ts

@@ -56,5 +56,7 @@ export interface LauncherSpec {
 export declare function launcherScript(s: LauncherSpec): string;
 export declare function infoPlist(version: string): string;
 export declare function desktopEntry(launcher: string): string;
+/** Whether a sideby desktop app is installed for this home: its main file exists and carries APP_MARKER. */
+export declare function appInstalled(ctx: AppContext): Promise<boolean>;
 export declare function installApp(ctx: AppContext, opts: InstallOptions): Promise<InstallResult>;
 export declare function uninstallApp(ctx: AppContext): Promise<UninstallResult>;

package/dist/src/desktop/app.js

@@ -39,7 +39,7 @@ export function launcherScript(s) {
         : `command -v notify-send >/dev/null 2>&1 && notify-send "sideby could not start" "Run sideby app install again in a terminal. Details: $LOG"`;
     const lines = [
         '#!/bin/sh',
-        `# ${APP_MARKER}: written by \`sideby app install\`. Run that again after upgrading sideby or Node.`,
+        `# ${APP_MARKER}: written by \`sideby app install\` (\`sideby update\` runs it again). Run it yourself after upgrading Node.`,
         `NODE=${shq(s.node)}`,
         `ENTRY=${shq(s.entry)}`,
         `URL=${shq(s.url ?? '')}`,
@@ -185,6 +185,38 @@ async function ownership(entry) {
     }
     return markerTest(entry)(data) ? { state: 'ours' } : foreign(entry, NOT_OURS);
 }
+/** The launcher script inside what install writes: the bundle's executable on macOS, the launcher file on Linux. */
+function launcherPath(l, platform) {
+    return platform === 'darwin' ? join(l.primary, 'Contents', 'MacOS', APP_NAME) : l.linux.launcher;
+}
+/** The `URL='…'` an earlier install wrote into the launcher, when it is a valid http(s) address; never follows a link. */
+async function recordedUrl(launcher) {
+    let text;
+    try {
+        text = (await readNoFollow(launcher)).toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    if (text.split('\n', 2)[1]?.startsWith(`# ${APP_MARKER}: `) !== true)
+        return undefined;
+    const m = /^URL='((?:[^']|'\\'')*)'$/m.exec(text);
+    const value = m?.[1]?.replace(/'\\''/g, "'");
+    if (!value)
+        return undefined;
+    try {
+        return checkAppUrl(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether a sideby desktop app is installed for this home: its main file exists and carries APP_MARKER. */
+export async function appInstalled(ctx) {
+    if (ctx.platform !== 'darwin' && ctx.platform !== 'linux')
+        return false;
+    return (await ownership(layout(ctx, ctx.platform).primary)).state === 'ours';
+}
 /** Refuses to replace anything at `entry` that `sideby app install` did not write; true when it is ours. */
 async function assertOwned(entry, verb) {
     const o = await ownership(entry);
@@ -199,12 +231,14 @@ export async function installApp(ctx, opts) {
     const run = ctx.run ?? defaultRunner;
     if (!isAbsolute(opts.node) || !isAbsolute(opts.entry))
         throw new UserError('node and the sideby entry must be absolute paths');
-    const url = opts.url === undefined ? undefined : checkAppUrl(opts.url);
     const l = layout(ctx, platform);
     let updated = false;
     for (const e of l.entries)
         if (await assertOwned(e, 'install'))
             updated = true;
+    // Without --url, a reinstall (by hand or after `sideby update`) keeps the address an earlier --url recorded.
+    const kept = opts.url === undefined && updated ? await recordedUrl(launcherPath(l, platform)) : undefined;
+    const url = opts.url === undefined ? kept : checkAppUrl(opts.url);
     const xdg = {};
     for (const k of ['XDG_CONFIG_HOME', 'XDG_STATE_HOME']) {
         const v = ctx.env[k];
@@ -274,8 +308,10 @@ export async function installApp(ctx, opts) {
     }
     if (url)
         hints.push(`The app opens ${url}.`);
+    if (kept)
+        hints.push('Kept the address from the earlier install; to start the panel instead, run `sideby app uninstall`, then `sideby app install`.');
     else
-        hints.push('The app starts the panel in the background and opens it; stop the panel with `sideby ui --stop`.', 'Run `sideby app install` again after upgrading sideby or Node, so the app starts the new version.');
+        hints.push('The app starts the panel in the background and opens it; stop the panel with `sideby ui --stop`.', '`sideby update` refreshes the app; run `sideby app install` again after upgrading Node or installing sideby another way.');
     if (/[/\\]_npx[/\\]/.test(opts.entry))
         hints.push('sideby runs from the npx cache, which npm may clear; install it with `npm i -g sideby` and run this again.');
     return {

package/dist/src/families/browser.d.ts

@@ -0,0 +1,20 @@
+import type { Account } from '../types.ts';
+export interface WebsiteDef {
+    /** The Family id. */
+    family: string;
+    /** Where "Open in browser" goes. */
+    url: string;
+    /**
+     * The Local Storage origin whose key names may hold `signInId`, and the reader of that id from the Host's login
+     * file. The id is compared in memory only; it is never shown, returned, logged or cached. Missing when the website
+     * keeps no id the Host also has (grok.com), so the Account can only be opened in a Browser Profile the user picks.
+     */
+    match?: {
+        origin: string;
+        signInId(account: Account): Promise<string | undefined>;
+    };
+}
+/** The website of a built-in Family id, if it has one. */
+export declare function websiteDef(familyId: string): WebsiteDef | undefined;
+/** Every website that can be matched, for the origins to read. */
+export declare function matchedOrigins(): string[];

package/dist/src/families/browser.js

@@ -0,0 +1,23 @@
+import { claudeSignInId } from './claude/browser.js';
+import { codexSignInId } from './codex/browser.js';
+const WEBSITES = new Map([
+    {
+        family: 'claude',
+        url: 'https://claude.ai',
+        match: { origin: 'https://claude.ai', signInId: claudeSignInId },
+    },
+    {
+        family: 'codex',
+        url: 'https://chatgpt.com',
+        match: { origin: 'https://chatgpt.com', signInId: codexSignInId },
+    },
+    { family: 'grok', url: 'https://grok.com' },
+].map((w) => [w.family, w]));
+/** The website of a built-in Family id, if it has one. */
+export function websiteDef(familyId) {
+    return WEBSITES.get(familyId);
+}
+/** Every website that can be matched, for the origins to read. */
+export function matchedOrigins() {
+    return [...WEBSITES.values()].flatMap((w) => (w.match ? [w.match.origin] : []));
+}

package/dist/src/families/claude/browser.d.ts

@@ -0,0 +1,3 @@
+import type { Account } from '../../types.ts';
+/** `oauthAccount.accountUuid` of `.claude.json`, only for matching; every other field is dropped at once. */
+export declare function claudeSignInId(account: Account): Promise<string | undefined>;

package/dist/src/families/claude/browser.js

@@ -0,0 +1,14 @@
+// The Claude account id that claude.ai's Local Storage key names also carry (spec §3.24, ADR-0023).
+import { readFile } from 'node:fs/promises';
+import { claudeJsonOf } from './index.js';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `oauthAccount.accountUuid` of `.claude.json`, only for matching; every other field is dropped at once. */
+export async function claudeSignInId(account) {
+    try {
+        const id = JSON.parse(await readFile(claudeJsonOf(account), 'utf8'))?.oauthAccount?.accountUuid;
+        return typeof id === 'string' && UUID.test(id) ? id.toLowerCase() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/families/claude/desktop.js

@@ -23,6 +23,7 @@ export const claudeDesktop = {
         {
             path: 'claude_desktop_config.json',
             mainPath: 'Library/Application Support/Claude/claude_desktop_config.json',
+            key: 'mcpServers',
         },
     ],
 };

package/dist/src/families/codex/browser.d.ts

@@ -0,0 +1,7 @@
+import type { Account } from '../../types.ts';
+/**
+ * `chatgpt_user_id` (else `user_id`, as Codex itself falls back: codex-rs/login/src/token_data.rs) under the auth
+ * claim of `tokens.id_token`, only for matching. The payload is decoded as for the email (core/identity.ts); the
+ * token and every other claim are dropped at once. `tokens.account_id` is the workspace and is not used.
+ */
+export declare function codexSignInId(account: Account): Promise<string | undefined>;

package/dist/src/families/codex/browser.js

@@ -0,0 +1,26 @@
+// The ChatGPT user id that chatgpt.com's Local Storage key names also carry (spec §3.24, ADR-0023).
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const USER_ID = /^user-[A-Za-z0-9]{8,64}$/;
+const AUTH_CLAIM = 'https://api.openai.com/auth';
+/**
+ * `chatgpt_user_id` (else `user_id`, as Codex itself falls back: codex-rs/login/src/token_data.rs) under the auth
+ * claim of `tokens.id_token`, only for matching. The payload is decoded as for the email (core/identity.ts); the
+ * token and every other claim are dropped at once. `tokens.account_id` is the workspace and is not used.
+ */
+export async function codexSignInId(account) {
+    try {
+        const token = JSON.parse(await readFile(join(account.dir, 'auth.json'), 'utf8'))?.tokens?.id_token;
+        if (typeof token !== 'string')
+            return undefined;
+        const payload = token.split('.')[1];
+        if (!payload)
+            return undefined;
+        const auth = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'))?.[AUTH_CLAIM];
+        const id = auth?.chatgpt_user_id ?? auth?.user_id;
+        return typeof id === 'string' && USER_ID.test(id) ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/families/desktop.d.ts

@@ -17,10 +17,14 @@ export interface DesktopAppDef {
     clearVars: readonly string[];
     /** The first sign-in happens inside the app, through a URL callback another running instance may catch. */
     signInInApp: boolean;
-    /** Files of the App Data shared from the Main Account's default App Data as links (`mainPath` relative to HOME). */
+    /**
+     * Files of the App Data shared from the Main Account's default App Data as links (`mainPath` relative to HOME).
+     * With `key`, a real file the app made in place of the link is fine while that JSON key matches the main one.
+     */
     sharedFiles: readonly {
         path: string;
         mainPath: string;
+        key?: string;
     }[];
 }
 /** The Desktop App of a built-in Family id, if it has one. */

package/dist/src/families/pi/index.js

@@ -28,6 +28,8 @@ export const piFamily = {
     logo: BUILTIN_LOGOS.pi,
     bin: 'pi',
     installUrl: 'https://github.com/earendil-works/pi',
+    // The managed install stages and smoke-tests each release before switching to it; npm upgrades in place.
+    installCommand: 'curl -fsSL https://pi.dev/install.sh | sh',
     selectVar: 'PI_CODING_AGENT_DIR',
     secretFileMeansApi: false,
     layout: { main: '.pi/agent', account: '.pi-<name>/agent' },