sideby 0.11.0 → 0.12.0

package/README.md

@@ -29,7 +29,7 @@ sideby quota setup claude --yes  # Claude quota in the panel; undo: sideby quota
 sideby ui                        # every account's quota at http://127.0.0.1:17420
 ```
 
-`sideby run claude:main` keeps using `~/.claude` in another terminal at the same time. Arguments after `--` go to the Host: `sideby run work -- --resume`. To try it without installing, run `npx sideby`.
+`sideby update` installs a newer sideby when there is one; sideby says so after a command and in the panel. `sideby run claude:main` keeps using `~/.claude` in another terminal at the same time. Arguments after `--` go to the Host: `sideby run work -- --resume`. To try it without installing, run `npx sideby`.
 
 ## Set up with your AI agent
 
@@ -110,7 +110,7 @@ macOS and Linux. CI runs the suite on `ubuntu-latest` and `macos-latest`, Node 2
 ## Safe by design
 
 - It never edits a Host's global config to switch accounts. It moves a task to another account only when you turn on Auto Handoff, and never proxies requests or pools logins.
-- It never reads, prints or sends a credential value. Nothing leaves your machine: sideby calls no remote service.
+- It never reads, prints or sends a credential value. Nothing about your accounts leaves your machine: the only request sideby makes on its own is a daily check of the npm registry for its newest version (off with `NO_UPDATE_NOTIFIER=1`; see [Updates](docs/guide/configuration.md#updates)).
 - `doctor --fix` never replaces a real file and never changes where a link points.
 
 Details and the terms-of-service question are in the [FAQ](docs/guide/faq.md).

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261016T040419-834a8d"}
+{"id":"20261016T071613-e5f0f1"}

package/dist/src/cli/commands.d.ts

@@ -61,6 +61,13 @@ export declare function cmdHandoff(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdPlugins(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdShellInit(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdUi(a: ParsedArgs, io: Io): Promise<number>;
+/**
+ * `sideby update [--yes] [--json]` (spec §3.23): asks the registry now, shows what an Update runs, and runs it with
+ * `--yes` (exit 10 before). An install sideby cannot update gets the command to run and exit 1.
+ */
+export declare function cmdUpdate(a: ParsedArgs, io: Io): Promise<number>;
+/** The internal `sideby update-check` the CLI starts detached: one Update Check, then Auto Update if it is on. */
+export declare function cmdUpdateCheck(_a: ParsedArgs, _io: Io): Promise<number>;
 export declare function cmdApp(a: ParsedArgs, io: Io): Promise<number>;
 /**
  * `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20); `sideby desktop grok-bot:<name>`:

package/dist/src/cli/commands.js

@@ -17,8 +17,22 @@ import { suggestAlias, suggestName } from '../panel/page-logic.js';
 import { createRuntime, UnknownFamilyError } from '../runtime.js';
 import { UsageError } from './args.js';
 import { c, clock, compactNumber, quotaText, table, tuningLines, usageText } from './format.js';
+/** Runs `fn` while a record under the state directory says a Host runs (also for `login`), so an Auto Update waits (spec §3.23). */
+async function whileRunning(rt, fn) {
+    const { markRunning } = await import('../core/update.js');
+    const done = await markRunning(rt.paths);
+    try {
+        return await fn();
+    }
+    finally {
+        await done().catch(() => { });
+    }
+}
 /** Runs the Account with Auto Handoff when it applies (spec §3.17), else the Host as usual. */
 async function runAccount(rt, ref, args, io) {
+    return whileRunning(rt, () => runAccountNow(rt, ref, args, io));
+}
+async function runAccountNow(rt, ref, args, io) {
     const handed = await runWithHandoff(rt, ref, args, {
         err: (l) => io.err(c.dim(l)),
         stdin: io.stdin ?? process.stdin,
@@ -208,7 +222,7 @@ export async function cmdRun(a, io, command) {
     const prepared = await rt.prepareLaunch(ref, [...extra, ...a.rest], command);
     if (prepared.notice)
         io.err(c.cyan(prepared.notice));
-    return runHost(prepared);
+    return whileRunning(rt, () => runHost(prepared));
 }
 /**
  * `sideby resume <family>`: what the Host-named shell function calls (spec §3.15). Starts the Account that holds the
@@ -224,7 +238,7 @@ export async function cmdResume(a, io) {
         io.err(c.dim(`sideby: session ${route.sessionId} was never saved; starting a new session in ${route.account.ref}`));
     else if (route.account)
         io.err(c.dim(`sideby: session ${route.sessionId} is in ${route.account.ref}; starting it there`));
-    return runHost(route.launch);
+    return whileRunning(rt, () => runHost(route.launch));
 }
 /** Quotes a Host argument for a command line the user may paste; plain words stay as they are. */
 function shellQuote(arg) {
@@ -1003,6 +1017,84 @@ export async function cmdUi(a, io) {
     });
     return 0;
 }
+/**
+ * `sideby update [--yes] [--json]` (spec §3.23): asks the registry now, shows what an Update runs, and runs it with
+ * `--yes` (exit 10 before). An install sideby cannot update gets the command to run and exit 1.
+ */
+export async function cmdUpdate(a, io) {
+    if (a.positionals.length)
+        throw new UsageError('usage: sideby update [--yes] [--json]');
+    const u = await import('../core/update.js');
+    const { SKILL_INSTALL } = await import('../core/skill-check.js');
+    const { backgroundPanelPort } = await import('../panel/background.js');
+    const paths = resolvePaths(process.env);
+    const asJson = a.flags.has('json');
+    const plan = await u.planUpdate(paths, process.env);
+    const shown = u.shownPlan(plan);
+    if (!plan.available) {
+        if (asJson)
+            json(io, { ...shown, updated: false });
+        else
+            io.out(`${c.green('✓')} sideby ${plan.current} is the latest version.`);
+        return 0;
+    }
+    if (!plan.canRun) {
+        if (asJson)
+            json(io, { ...shown, updated: false });
+        else {
+            io.out(`sideby ${c.bold(plan.latest)} is available (you have ${plan.current}). What changed: ${plan.releaseNotes}`);
+            io.err(c.yellow(`sideby cannot update itself: ${plan.method.reason}. Run it yourself:\n  ${plan.command}`));
+        }
+        return 1;
+    }
+    if (!a.flags.has('yes')) {
+        if (asJson)
+            json(io, { ...shown, updated: false });
+        else {
+            io.out(`sideby ${c.bold(plan.latest)} is available (you have ${plan.current}). What changed: ${plan.releaseNotes}`);
+            io.out(`\nUpdating runs:\n  ${plan.command}`);
+            io.out(c.cyan('\nRun it with `sideby update --yes`.'));
+        }
+        return 10;
+    }
+    if (!asJson)
+        io.out(c.dim(`$ ${plan.command}`));
+    const r = await u.applyUpdate(paths, plan, process.env, {
+        ...(asJson ? {} : { onOutput: (text) => process.stderr.write(text) }),
+        panelPort: () => backgroundPanelPort(paths),
+    });
+    if (asJson) {
+        json(io, {
+            ...shown,
+            updated: r.ok,
+            message: r.message,
+            restartedPanel: r.restartedPanel,
+            skill: SKILL_INSTALL,
+            ...(r.ok ? {} : { output: r.output }),
+        });
+        return r.ok ? 0 : 1;
+    }
+    if (!r.ok) {
+        io.err(c.red(`✗ ${r.message}`));
+        return 1;
+    }
+    io.out(`${c.green('✓')} ${r.message}.`);
+    if (r.restartedPanel)
+        io.out('  The background panel is restarting with the new version; open pages reload by themselves.');
+    io.out('  A `sideby ui` running in a terminal and sessions already running keep the old version until you restart them.');
+    io.out(`  If you use the sideby skill, update it too: ${SKILL_INSTALL}`);
+    return 0;
+}
+/** The internal `sideby update-check` the CLI starts detached: one Update Check, then Auto Update if it is on. */
+export async function cmdUpdateCheck(_a, _io) {
+    const { backgroundCheck } = await import('../core/update.js');
+    const { loadConfig } = await import('../core/config.js');
+    const { backgroundPanelPort } = await import('../panel/background.js');
+    const paths = resolvePaths(process.env);
+    const config = await loadConfig(paths.configFile).catch(() => ({}));
+    await backgroundCheck(paths, process.env, config, () => backgroundPanelPort(paths));
+    return 0;
+}
 export async function cmdApp(a, io) {
     const sub = a.positionals[0];
     const usage = 'usage: sideby app install [--url <url>] | sideby app uninstall';

package/dist/src/cli/json-schemas.js

@@ -491,6 +491,31 @@ export const OUTPUT_SCHEMAS = {
             description: 'False when only the plan was shown; run again with --yes (exit 10).',
         }),
     }, { title: 'sideby desktop grok-bot:<name> --remove --json' }),
+    update: Type.Object({
+        schemaVersion: Version,
+        current: Type.String({ description: 'The running sideby version.' }),
+        latest: Type.String({ description: 'The `latest` version on the npm registry.' }),
+        available: Type.Boolean({ description: '`latest` is newer than `current`.' }),
+        method: Type.Object({
+            kind: Type.Union(['npm', 'pnpm', 'bun', 'volta', 'npx', 'project', 'source'].map((k) => Type.Literal(k)), { description: 'How this copy was installed.' }),
+            canUpdate: Type.Boolean({ description: 'sideby can run the Update itself.' }),
+            reason: Type.Optional(Type.String({ description: 'Why it cannot.' })),
+        }),
+        command: Type.String({
+            description: 'What an Update runs, or what to run by hand when `canRun` is false.',
+        }),
+        canRun: Type.Boolean(),
+        releaseNotes: Type.String({ description: 'The release notes of `latest`.' }),
+        updated: Type.Boolean({
+            description: 'False when only the plan was shown (exit 10 with --yes still to add) or nothing to do.',
+        }),
+        message: Type.Optional(Type.String()),
+        restartedPanel: Type.Optional(Type.Boolean({
+            description: 'A background Panel was running and starts again with the new version.',
+        })),
+        skill: Type.Optional(Type.String({ description: 'The command that updates the sideby skill; sideby never runs it.' })),
+        output: Type.Optional(Type.String({ description: 'What the failed install command printed.' })),
+    }, { title: 'sideby update --json' }),
     error: Type.Object({
         schemaVersion: Version,
         error: Type.String({ description: 'What went wrong and what to do next.' }),

package/dist/src/cli/main.js

@@ -58,10 +58,11 @@ Usage:
   sideby shell-init [zsh|bash] --write
                                       rewrite the config's shellInitFile with them
   sideby plugins                      list loaded plugins and load errors
+  sideby update [--yes]               update sideby to the newest version (shows the command first)
 
 Options:
   --json        machine-readable output (list, new, next, alias, doctor, quota, tune, model, remote-control, handoff,
-                families, plugins, app, desktop)
+                families, plugins, app, desktop, update)
   -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families, desktop
   -v, --version show the version
 
@@ -73,7 +74,10 @@ For AI agents:
   Setup steps and the full contract: https://github.com/Adonis0123/sideby/blob/main/llms.txt
   Run everything else yourself, but hand the user these as one line each: \`sideby login <account>\`
   (browser sign-in), filling in proxy.env, and \`sideby run\` or \`sideby next\` (interactive sessions).
-  Exit 10 means a change was shown: ask the user, then run it again with --yes.`;
+  Exit 10 means a change was shown: ask the user, then run it again with --yes.
+
+Updates: once a day sideby asks the npm registry for its newest version and says so after a command.
+  Turn it off with NO_UPDATE_NOTIFIER=1 or config "update": { "check": false }; "auto": true installs by itself.`;
 /** `sideby <command> --help` for the commands agents use to set up and repair accounts (spec §3.16). */
 const COMMAND_HELP = {
     new: `sideby new <family> <name> [--api] [--alias <short>] [--json]
@@ -203,7 +207,54 @@ const COMMANDS = {
     'shell-init': { flags: ['write'] },
     plugins: { flags: ['json'] },
     families: { flags: ['json'] },
+    update: { flags: ['json', 'yes'] },
+    'update-check': { flags: [] },
 };
+/** Commands that never print an Update Notice: their output is read by a shell or an agent, or they are internal. */
+function noticeAllowed(cmd, parsed) {
+    if (cmd === 'shell-init' || cmd === 'update' || cmd === 'update-check')
+        return false;
+    if (cmd === 'ui' && parsed.flags.has('serve-detached'))
+        return false;
+    if (cmd === 'handoff' && parsed.positionals[0] === 'ready')
+        return false;
+    return true;
+}
+/**
+ * After a command (spec §3.23): print the Update Notice and the result of an Auto Update, each at most once, and
+ * start the next Update Check detached when the last one is a day old. Only on a terminal; never fails the command.
+ */
+async function afterCommand() {
+    if (!process.stderr.isTTY)
+        return;
+    try {
+        const u = await import('../core/update.js');
+        const { resolvePaths } = await import('../core/paths.js');
+        const { loadConfig } = await import('../core/config.js');
+        const { packageVersion } = await import('../core/version.js');
+        const paths = resolvePaths(process.env);
+        const config = await loadConfig(paths.configFile).catch(() => ({}));
+        const cache = await u.readUpdateCache(paths);
+        const plan = u.afterCommandPlan(cache, packageVersion(), config, process.env, new Date());
+        const dim = process.env.NO_COLOR ? (t) => t : (t) => `\x1b[2m${t}\x1b[22m`;
+        for (const l of plan.lines)
+            console.error(dim(l));
+        if (plan.record)
+            await u.updateUpdateCache(paths, plan.record);
+        if (plan.startCheck) {
+            const { spawn } = await import('node:child_process');
+            const child = spawn(process.execPath, [fileURLToPath(import.meta.url), 'update-check'], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.on('error', () => { });
+            child.unref();
+        }
+    }
+    catch {
+        // an Update Notice is never worth failing a command
+    }
+}
 export async function main(argv) {
     const [first, ...rest] = argv;
     // Claude Code runs this on every status-line refresh. It must still launch the original command when Node is
@@ -274,47 +325,10 @@ export async function main(argv) {
             return 0;
         }
         const cmds = await import('./commands.js');
-        switch (cmd) {
-            case 'list':
-                return await cmds.cmdList(parsed, io);
-            case 'run':
-                return await cmds.cmdRun(parsed, io, 'run');
-            case 'login':
-                return await cmds.cmdRun(parsed, io, 'login');
-            case 'resume':
-                return await cmds.cmdResume(parsed, io);
-            case 'next':
-                return await cmds.cmdNext(parsed, io);
-            case 'new':
-                return await cmds.cmdNew(parsed, io);
-            case 'alias':
-                return await cmds.cmdAlias(parsed, io);
-            case 'doctor':
-                return await cmds.cmdDoctor(parsed, io);
-            case 'quota':
-                return await cmds.cmdQuota(parsed, io);
-            case 'tune':
-                return await cmds.cmdTune(parsed, io);
-            case 'model':
-                return await cmds.cmdModel(parsed, io);
-            case 'remote-control':
-                return await cmds.cmdRemoteControl(parsed, io);
-            case 'handoff':
-                return await cmds.cmdHandoff(parsed, io);
-            case 'ui':
-                return await cmds.cmdUi(parsed, io);
-            case 'app':
-                return await cmds.cmdApp(parsed, io);
-            case 'desktop':
-                return await cmds.cmdDesktop(parsed, io);
-            case 'shell-init':
-                return await cmds.cmdShellInit(parsed, io);
-            case 'plugins':
-                return await cmds.cmdPlugins(parsed, io);
-            case 'families':
-                return await cmds.cmdFamilies(parsed, io);
-        }
-        return 2;
+        const code = await dispatch(cmd, parsed, io, cmds);
+        if (!wantsJson && noticeAllowed(cmd, parsed))
+            await afterCommand();
+        return code;
     }
     catch (err) {
         const usage = err instanceof UsageError;
@@ -331,6 +345,53 @@ export async function main(argv) {
         return usage ? 2 : 1;
     }
 }
+async function dispatch(cmd, parsed, io, cmds) {
+    switch (cmd) {
+        case 'list':
+            return await cmds.cmdList(parsed, io);
+        case 'run':
+            return await cmds.cmdRun(parsed, io, 'run');
+        case 'login':
+            return await cmds.cmdRun(parsed, io, 'login');
+        case 'resume':
+            return await cmds.cmdResume(parsed, io);
+        case 'next':
+            return await cmds.cmdNext(parsed, io);
+        case 'new':
+            return await cmds.cmdNew(parsed, io);
+        case 'alias':
+            return await cmds.cmdAlias(parsed, io);
+        case 'doctor':
+            return await cmds.cmdDoctor(parsed, io);
+        case 'quota':
+            return await cmds.cmdQuota(parsed, io);
+        case 'tune':
+            return await cmds.cmdTune(parsed, io);
+        case 'model':
+            return await cmds.cmdModel(parsed, io);
+        case 'remote-control':
+            return await cmds.cmdRemoteControl(parsed, io);
+        case 'handoff':
+            return await cmds.cmdHandoff(parsed, io);
+        case 'ui':
+            return await cmds.cmdUi(parsed, io);
+        case 'app':
+            return await cmds.cmdApp(parsed, io);
+        case 'desktop':
+            return await cmds.cmdDesktop(parsed, io);
+        case 'shell-init':
+            return await cmds.cmdShellInit(parsed, io);
+        case 'plugins':
+            return await cmds.cmdPlugins(parsed, io);
+        case 'families':
+            return await cmds.cmdFamilies(parsed, io);
+        case 'update':
+            return await cmds.cmdUpdate(parsed, io);
+        case 'update-check':
+            return await cmds.cmdUpdateCheck(parsed, io);
+    }
+    return 2;
+}
 // Run when executed directly, also through symlinks (npm's bin shim, a user alias like `sb`).
 function isEntry() {
     const arg = process.argv[1];

package/dist/src/core/brand-mark.d.ts

@@ -1,29 +1,83 @@
-export type RoundedRect = readonly [x: number, y: number, w: number, h: number, r: number];
-export declare const MARK: {
-    readonly back: readonly [12, 82, 128, 104, 44];
-    readonly front: readonly [116, 70, 128, 116, 46];
-    /** Cut out of the back face (and its eyes) so the two faces never touch. */
-    readonly gap: readonly [104, 58, 152, 140, 58];
-    readonly backEyes: readonly [readonly [45, 119, 14, 26, 7], readonly [83, 119, 14, 26, 7]];
-    readonly frontEyes: readonly [readonly [155, 111, 14, 26, 7], readonly [193, 111, 14, 26, 7]];
+/** An outlined shape of one buddy, as SVG path data on its 64-unit grid. */
+export interface BuddyPath {
+    d: string;
+    /** `body`, `shade`: the buddy's own colours; `none`: an open line. */
+    fill: 'body' | 'shade' | 'none';
+    /** Line colour; `chevron` is the buddy's accent colour. Default ink. */
+    stroke?: 'ink' | 'chevron';
+    /** Line width on the 64-unit grid, before the buddy's scale. Default: the outline width. */
+    width?: number;
+}
+/** A filled ellipse without outline: the eyes and their highlights. */
+export interface BuddyDot {
+    cx: number;
+    cy: number;
+    rx: number;
+    ry: number;
+    fill: 'ink' | 'light';
+}
+/** Back to front: feet, arms, body, then the face. */
+export declare const BUDDY: {
+    paths: readonly BuddyPath[];
+    eyes: readonly BuddyDot[];
 };
+/** The eye highlights sit towards where the buddy looks: `1` right, `-1` left. */
+export declare function highlights(look: 1 | -1): BuddyDot[];
+export interface BuddyColors {
+    body: string;
+    shade: string;
+    chevron: string;
+}
 export declare const MARK_COLORS: {
-    readonly front: '#3f8fc4';
-    readonly back: '#f2b35e';
-    readonly eye: '#1e2a44';
+    readonly blue: {
+        readonly body: '#3f8fc4';
+        readonly shade: '#29658e';
+        readonly chevron: '#f2b35e';
+    };
+    readonly amber: {
+        readonly body: '#f2b35e';
+        readonly shade: '#c98a35';
+        readonly chevron: '#3f8fc4';
+    };
+    readonly ink: '#1e2a44';
+    readonly light: '#f6f0e5';
+};
+export interface PlacedBuddy {
+    colors: BuddyColors;
+    /** Where the buddy looks (and which way its eye highlights sit). */
+    look: 1 | -1;
+    /** 64-unit grid → mark units: translate by (x, y), then scale. */
+    x: number;
+    y: number;
+    scale: number;
+}
+/** The two buddies in mark units, back first. The blue one in front is the one a Portal's `logoColor` recolours. */
+export declare const MARK: {
+    line: number;
+    placedLine: number;
+    back: PlacedBuddy;
+    front: PlacedBuddy;
+};
+/** The square the pair is drawn in, in mark units (the Panel's 40 px tile and the app icon tile). */
+export declare const MARK_VIEWBOX: {
+    readonly x: -2.5;
+    readonly y: 3;
+    readonly size: 69;
 };
-/** The square the mark is drawn in when it sits on a tile (about 78% of the tile is mark). */
-export declare const MARK_TILE_VIEWBOX: {
-    readonly x: -20.5;
-    readonly y: -20.5;
-    readonly size: 297;
+/** The square around one buddy at full size, for the small cut (favicon). */
+export declare const BUDDY_VIEWBOX: {
+    readonly x: 3;
+    readonly y: 10.5;
+    readonly size: 58;
 };
-export declare function roundedRectPath([x, y, w, h, r]: RoundedRect): string;
 /**
- * The mark as SVG children (no outer <svg>). The front face has no fill of its own, so it takes the surrounding
- * `fill` (the Panel's `--logo-fg`, which Portals can set with `logoColor`); the back face and the eyes are fixed.
- * `id` names the gap mask; keep it unique per document.
+ * The mark as SVG children (no outer <svg>). With `front` omitted the blue buddy's body has no fill of its own, so it
+ * takes the surrounding `fill` (the Panel's `--logo-fg`, which Portals set with `logoColor`); everything else is fixed.
  */
-export declare function markSvgBody(id: string, front?: string): string;
+export declare function markSvgBody(front?: string): string;
 /** The Panel's header logo: the mark sized for its 40 px tile. */
 export declare const MARK_SVG: string;
+/** `<basePath>/icon.svg`: the whole mark on a transparent square, for a Portal's tab or menu (ADR-0006 amendment). */
+export declare const ICON_SVG: string;
+/** `<basePath>/favicon.svg`: the small cut, the blue buddy alone, for sizes below about 24 px (ADR-0022). */
+export declare const FAVICON_SVG: string;

package/dist/src/core/brand-mark.js

@@ -1,42 +1,88 @@
-// The sideby mark: two friendly faces side by side, the amber one behind and the blue one in front, cut apart by a
-// gap that follows the front face (ADR-0020). One source for the Panel header, the empty state and the app icon.
-// Geometry is on a 256-unit grid centred on (128, 128); rounded rectangles are [x, y, width, height, radius].
-export const MARK = {
-    back: [12, 82, 128, 104, 44],
-    front: [116, 70, 128, 116, 46],
-    /** Cut out of the back face (and its eyes) so the two faces never touch. */
-    gap: [104, 58, 152, 140, 58],
-    backEyes: [
-        [45, 119, 14, 26, 7],
-        [83, 119, 14, 26, 7],
+// The sideby mark: two buddies side by side, the amber one behind on the left and the blue one in front on the right,
+// looking at each other (ADR-0022, the characters of the intro film). One source for the Panel header, the empty
+// state, the Portal icon, the favicon and the app icon.
+// One buddy is drawn on a 64-unit grid; the mark places two of them with a translate and a scale.
+/** Back to front: feet, arms, body, then the face. */
+export const BUDDY = {
+    paths: [
+        { d: 'M17 48 Q15 58 22 57 Q27 57 27 50 M37 50 Q37 57 42 57 Q49 58 47 48', fill: 'shade' },
+        { d: 'M14 37 C4 32 4 41 14 43 M50 37 C60 32 60 41 50 43', fill: 'body' },
+        {
+            d: 'M12 37 C12 27 17 23 25 23 H39 C47 23 52 27 52 37 C52 48 45 53 32 53 C19 53 12 48 12 37 Z',
+            fill: 'body',
+        },
+        { d: 'M30 27 L34 29.31 L30 31.62', fill: 'none', stroke: 'chevron', width: 2.5 },
+        { d: 'M29 46 Q32 49 35 46', fill: 'none', width: 2.5 },
     ],
-    frontEyes: [
-        [155, 111, 14, 26, 7],
-        [193, 111, 14, 26, 7],
+    eyes: [
+        { cx: 22, cy: 38.5, rx: 4.5, ry: 6, fill: 'ink' },
+        { cx: 42, cy: 38.5, rx: 4.5, ry: 6, fill: 'ink' },
     ],
 };
-export const MARK_COLORS = { front: '#3f8fc4', back: '#f2b35e', eye: '#1e2a44' };
-/** The square the mark is drawn in when it sits on a tile (about 78% of the tile is mark). */
-export const MARK_TILE_VIEWBOX = { x: -20.5, y: -20.5, size: 297 };
-export function roundedRectPath([x, y, w, h, r]) {
-    return (`M${x + r} ${y}H${x + w - r}A${r} ${r} 0 0 1 ${x + w} ${y + r}V${y + h - r}A${r} ${r} 0 0 1 ${x + w - r} ${y + h}` +
-        `H${x + r}A${r} ${r} 0 0 1 ${x} ${y + h - r}V${y + r}A${r} ${r} 0 0 1 ${x + r} ${y}Z`);
+/** The eye highlights sit towards where the buddy looks: `1` right, `-1` left. */
+export function highlights(look) {
+    return BUDDY.eyes.map((e) => ({
+        cx: e.cx + 1.5 * look,
+        cy: e.cy + (look > 0 ? 0.5 : -2),
+        rx: 1.65,
+        ry: 2.1,
+        fill: 'light',
+    }));
+}
+export const MARK_COLORS = {
+    blue: { body: '#3f8fc4', shade: '#29658e', chevron: '#f2b35e' },
+    amber: { body: '#f2b35e', shade: '#c98a35', chevron: '#3f8fc4' },
+    ink: '#1e2a44',
+    light: '#f6f0e5',
+};
+/** The two buddies in mark units, back first. The blue one in front is the one a Portal's `logoColor` recolours. */
+export const MARK = {
+    /** Outline width of a buddy drawn alone, on its 64-unit grid. */
+    line: 2.75,
+    /** Outline width of a placed buddy before its scale, so the outline stays about 2.5 mark units. */
+    placedLine: 3.6,
+    back: { colors: MARK_COLORS.amber, look: 1, x: -2, y: 2, scale: 0.7 },
+    front: { colors: MARK_COLORS.blue, look: -1, x: 22, y: 16, scale: 0.7 },
+};
+/** The square the pair is drawn in, in mark units (the Panel's 40 px tile and the app icon tile). */
+export const MARK_VIEWBOX = { x: -2.5, y: 3, size: 69 };
+/** The square around one buddy at full size, for the small cut (favicon). */
+export const BUDDY_VIEWBOX = { x: 3, y: 10.5, size: 58 };
+function buddySvg(b, line, bodyFill) {
+    const color = (fill) => {
+        if (fill === 'none')
+            return ' fill="none"';
+        if (fill === 'shade')
+            return ` fill="${b.colors.shade}"`;
+        return bodyFill === null ? '' : ` fill="${bodyFill ?? b.colors.body}"`;
+    };
+    const paths = BUDDY.paths
+        .map((p) => {
+        const stroke = p.stroke === 'chevron' ? ` stroke="${b.colors.chevron}"` : '';
+        const width = p.width ? ` stroke-width="${p.width}"` : '';
+        return `<path d="${p.d}"${color(p.fill)}${stroke}${width}/>`;
+    })
+        .join('');
+    const dots = [...BUDDY.eyes, ...highlights(b.look)]
+        .map((e) => `<ellipse cx="${e.cx}" cy="${e.cy}" rx="${e.rx}" ry="${e.ry}" fill="${e.fill === 'ink' ? MARK_COLORS.ink : MARK_COLORS.light}"/>`)
+        .join('');
+    const transform = b.scale === 1 && b.x === 0 && b.y === 0 ? '' : ` transform="translate(${b.x} ${b.y}) scale(${b.scale})"`;
+    return `<g${transform} stroke-width="${line}">${paths}<g stroke="none">${dots}</g></g>`;
 }
+const OUTLINE = `stroke="${MARK_COLORS.ink}" stroke-linecap="round" stroke-linejoin="round"`;
 /**
- * The mark as SVG children (no outer <svg>). The front face has no fill of its own, so it takes the surrounding
- * `fill` (the Panel's `--logo-fg`, which Portals can set with `logoColor`); the back face and the eyes are fixed.
- * `id` names the gap mask; keep it unique per document.
+ * The mark as SVG children (no outer <svg>). With `front` omitted the blue buddy's body has no fill of its own, so it
+ * takes the surrounding `fill` (the Panel's `--logo-fg`, which Portals set with `logoColor`); everything else is fixed.
  */
-export function markSvgBody(id, front) {
-    const eyes = (list) => list.map(roundedRectPath).join('');
-    const frontFill = front ? ` fill="${front}"` : '';
-    return (`<mask id="${id}" maskUnits="userSpaceOnUse" x="0" y="0" width="256" height="256">` +
-        `<rect width="256" height="256" fill="#fff"/><path fill="#000" d="${roundedRectPath(MARK.gap)}"/></mask>` +
-        `<g mask="url(#${id})"><path fill="${MARK_COLORS.back}" d="${roundedRectPath(MARK.back)}"/>` +
-        `<path fill="${MARK_COLORS.eye}" d="${eyes(MARK.backEyes)}"/></g>` +
-        `<path${frontFill} d="${roundedRectPath(MARK.front)}"/>` +
-        `<path fill="${MARK_COLORS.eye}" d="${eyes(MARK.frontEyes)}"/>`);
+export function markSvgBody(front) {
+    return `<g ${OUTLINE}>${buddySvg(MARK.back, MARK.placedLine)}${buddySvg(MARK.front, MARK.placedLine, front ?? null)}</g>`;
 }
-const V = MARK_TILE_VIEWBOX;
+const viewBox = (v) => `${v.x} ${v.y} ${v.size} ${v.size}`;
 /** The Panel's header logo: the mark sized for its 40 px tile. */
-export const MARK_SVG = `<svg viewBox="${V.x} ${V.y} ${V.size} ${V.size}">${markSvgBody('sideby-mark-gap')}</svg>`;
+export const MARK_SVG = `<svg viewBox="${viewBox(MARK_VIEWBOX)}">${markSvgBody()}</svg>`;
+/** `<basePath>/icon.svg`: the whole mark on a transparent square, for a Portal's tab or menu (ADR-0006 amendment). */
+export const ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox(MARK_VIEWBOX)}" role="img" aria-label="sideby">` +
+    `${markSvgBody(MARK_COLORS.blue.body)}</svg>`;
+/** `<basePath>/favicon.svg`: the small cut, the blue buddy alone, for sizes below about 24 px (ADR-0022). */
+export const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox(BUDDY_VIEWBOX)}">` +
+    `<g ${OUTLINE}>${buddySvg({ ...MARK.front, x: 0, y: 0, scale: 1 }, MARK.line)}</g></svg>`;

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

@@ -62,6 +62,10 @@ export declare const ConfigSchema: Type.TObject<{
             order: Type.TOptional<Type.TArray<Type.TString>>;
         }>>>;
     }>>;
+    update: Type.TOptional<Type.TObject<{
+        check: Type.TOptional<Type.TBoolean>;
+        auto: Type.TOptional<Type.TBoolean>;
+    }>>;
     shellInitFile: Type.TOptional<Type.TObject<{
         zsh: Type.TOptional<Type.TString>;
         bash: Type.TOptional<Type.TString>;
@@ -85,6 +89,18 @@ export declare function editConfigHandoff(file: string, edit: (current: HandoffC
     before: HandoffConfig | undefined;
     after: HandoffConfig | undefined;
 }>;
+export type UpdateConfig = NonNullable<Config['update']>;
+/**
+ * The Panel's Auto Update switch (spec §3.23): changes the config `update` key with `edit` (see `editConfigKey` for
+ * how the file is written). With `dryRun`, shows the change without writing.
+ */
+export declare function editConfigUpdate(file: string, edit: (current: UpdateConfig) => UpdateConfig, opts?: {
+    dryRun?: boolean;
+}): Promise<{
+    changed: boolean;
+    before: UpdateConfig | undefined;
+    after: UpdateConfig | undefined;
+}>;
 export type AccountsConfig = NonNullable<Config['accounts']>;
 /**
  * `sideby model` (spec §3.19): changes the config `accounts` key with `edit` (see `editConfigKey` for how the file is