lattris 0.1.2 → 0.1.3

package/dist/build.json

@@ -1,4 +1 @@
-{
-  "commit": "e813390b3f7e3c6eed78e607fed6125a10c9cf2c",
-  "builtAt": "2026-09-12T04:33:05.921Z"
-}
+{"commit":"cecf7e60eb450bce092dc992155ff77002fc1379","builtAt":"2026-09-15T22:27:41Z"}

package/dist/main.js

@@ -1019,6 +1019,18 @@ export const validAccessToken = async (cfg) => {
         throw new Error('not-logged-in');
     }
 };
+// An absent or unrefreshable session sends no Authorization header, since the
+// API refuses any present invalid bearer by its own rule.
+export const optionalAccessToken = async (cfg) => {
+    try {
+        return await validAccessToken(cfg);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'not-logged-in')
+            return undefined;
+        throw error;
+    }
+};
 // Render a door to STDERR (stdout stays clean for piped data):
 //   <message>
 //   Run: lattris <next.action>
@@ -1174,10 +1186,13 @@ export const edgeRefusal = (status, headers, bytes) => {
 // ALREADY rendered the door and the caller just propagates the exit code. 204 (the
 // delete route's success) has no body to parse.
 const HTTP_NO_CONTENT = 204;
-export const apiFetch = async (accessToken, url, init = {}) => {
+export const apiFetch = async (accessToken, url, init = {}, addressKind = 'api') => {
+    const headers = { ...init.headers };
+    if (accessToken !== undefined)
+        headers.Authorization = `Bearer ${accessToken}`;
     const res = await fetch(url, {
         ...init,
-        headers: { ...init.headers, Authorization: `Bearer ${accessToken}` }
+        headers
     });
     if (!res.ok) {
         // Bytes, not text: the edge excerpt is cut by byte before decoding, and
@@ -1203,11 +1218,8 @@ export const apiFetch = async (accessToken, url, init = {}) => {
         data = JSON.parse(rawText);
     }
     catch {
-        // A 200 that is not JSON is not the API — almost always a gateway
-        // falling through to the SPA because the environment's `api` URL is
-        // wrong; without this branch it surfaces as "Unexpected token '<'"
-        // AFTER a successful login.
-        process.stderr.write('The server answered with a web page, not the API — check the environment\u2019s `api` URL.\n');
+        // A gateway fallthrough can be 200 HTML; it must not pass as a JSON read.
+        process.stderr.write(`The server answered with a web page, not the API — check the environment\u2019s \`${addressKind}\` URL.\n`);
         return { ok: false, body: {}, exit: EXIT.GENERIC };
     }
     return { ok: true, data, rawText };
@@ -1756,13 +1768,13 @@ export const buildCreateNoteBody = (content, flags, allowBannedWords = false) =>
 // receipt. Not cosmetic: capturedAt is uneditable (PATCH carries only title/content),
 // so this is the person's ONE immediate chance to catch a wrong-as-recorded
 // timestamp — the only remedy past this point is delete + recapture.
-export const formatSaved = (b) => {
+export const formatSaved = (b, address) => {
     const lines = [`Saved memory ${b.id}  (type: ${b.type})`];
     if (b.intent)
         lines.push(`  intent       ${b.intent}`);
     // title is echoed back from the caller's own --title — sanitized like every
-    // other rendered title (finding 2's principle: this receipt always prints as
-    // text, TTY or not, so it is never the wire-verbatim channel).
+    // other rendered title. The machine receipt is JSON; this formatter is only
+    // the terminal channel.
     if (b.title)
         lines.push(`  title        ${sanitizeForTerminal(b.title)}`);
     if (b.aiSummary)
@@ -1772,6 +1784,8 @@ export const formatSaved = (b) => {
         lines.push(`  fingerprint  ${b.fingerprint}`);
     if (b.revisionNo)
         lines.push(`  revisionNo   ${b.revisionNo}`);
+    if (address)
+        lines.push(`  address      ${address}`);
     return lines.join('\n');
 };
 // Read all of stdin. Strips a SINGLE trailing newline — the ubiquitous echo/heredoc
@@ -2317,14 +2331,22 @@ const captureMemory = async (cfg, args) => {
         process.exitCode = result.exit;
         return;
     }
-    process.stdout.write(`${formatSaved(result.data)}\n`);
+    const record = result.data;
+    const address = await composeAddressFor(cfg, accessToken, record);
+    const { href, ...fields } = record;
+    const receipt = {
+        ...fields,
+        ...(href === undefined ? {} : { href }),
+        ...(address === undefined ? {} : { address })
+    };
+    emit(receipt, JSON.stringify(receipt), () => formatSaved(record, address));
     // Capture-and-link: a CLI-side composition of the two doors the wire
     // actually has (capture, then edge) — never a pretended atomicity.
     if (flags.linkedFrom !== undefined || flags.linksTo !== undefined) {
         // --linked-from: the existing node points AT the new one; --links-to:
         // the new node points outward.
-        const fromRef = flags.linkedFrom ?? result.data.id;
-        const toId = flags.linkedFrom !== undefined ? result.data.id : flags.linksTo;
+        const fromRef = flags.linkedFrom ?? record.id;
+        const toId = flags.linkedFrom !== undefined ? record.id : flags.linksTo;
         const edge = await apiFetch(accessToken, `${cfg.apiUrl}/memories/${encodeURIComponent(fromRef)}/edges`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -2380,10 +2402,30 @@ export const composeAddress = (webUrl, personHandle, block) => {
     const ref = slug ? `${slug}-${block.handle}` : block.handle;
     return `${webUrl}/by/${personHandle}/memories/${ref}`;
 };
-// The caller's own handle, fetched quietly for the address line. Every failure
-// — no session, a 500, a shape that is not what we expect — resolves to "no
-// address", never to an error the person did not ask for.
-const composeAddressFor = async (cfg, accessToken, block) => {
+export const parseWebsiteMemoryAddress = (webUrl, value) => {
+    try {
+        const base = new URL(webUrl);
+        const address = new URL(value);
+        if (address.origin !== base.origin || address.username || address.password)
+            return undefined;
+        const basePath = stripTrailingSlash(base.pathname);
+        const route = address.pathname.slice(basePath.length);
+        if (!address.pathname.startsWith(`${basePath}/by/`))
+            return undefined;
+        const parts = route.split('/');
+        if (parts.length !== 5 || parts[1] !== 'by' || parts[3] !== 'memories')
+            return undefined;
+        const ownerHandle = decodeURIComponent(parts[2]);
+        const ref = decodeURIComponent(parts[4]);
+        if (!ownerHandle || !ref || ownerHandle.includes('/') || ref.includes('/'))
+            return undefined;
+        return { ownerHandle, ref };
+    }
+    catch {
+        return undefined;
+    }
+};
+const ownHandleFor = async (cfg, accessToken) => {
     try {
         const res = await fetch(`${cfg.apiUrl}/person/me`, {
             headers: { Authorization: `Bearer ${accessToken}` }
@@ -2391,12 +2433,17 @@ const composeAddressFor = async (cfg, accessToken, block) => {
         if (!res.ok)
             return undefined;
         const { handle } = (await res.json());
-        return handle ? composeAddress(cfg.webUrl, handle, block) : undefined;
+        return typeof handle === 'string' && handle.length > 0 ? handle : undefined;
     }
     catch {
         return undefined;
     }
 };
+// A missing convenience address must not fail the record already in hand.
+const composeAddressFor = async (cfg, accessToken, block) => {
+    const handle = await ownHandleFor(cfg, accessToken);
+    return handle ? composeAddress(cfg.webUrl, handle, block) : undefined;
+};
 // title/content are the caller's own free text — sanitized before a TTY ever
 // renders them (piped JSON stays wire-verbatim; that channel is machine data by
 // contract, sanitization is a rendering concern, not a storage one). id/type/
@@ -2524,8 +2571,8 @@ export const formatNodeWalk = (w, address) => {
 // no other lever restores the bare pre-walk read, byte-identical on the
 // wire. Lever values ride through verbatim — the API owns validation (depth
 // range, depth-requires-links); the client makes no decisions.
-export const buildGetMemoryUrl = (apiUrl, idOrPrefix, flags) => {
-    const url = new URL(`${apiUrl}/memories/${encodeURIComponent(idOrPrefix)}`);
+export const buildGetMemoryUrl = (webUrl, ownerHandle, ref, flags) => {
+    const url = new URL(`${webUrl}/by/${encodeURIComponent(ownerHandle)}/memories/${encodeURIComponent(ref)}`);
     const links = flags.links ?? '1';
     const bare = links === '0' && flags.depth === undefined && flags.content === undefined;
     if (!bare) {
@@ -2537,51 +2584,63 @@ export const buildGetMemoryUrl = (apiUrl, idOrPrefix, flags) => {
     }
     return url;
 };
-const getMemory = async (cfg, idOrPrefix, flags) => {
+const getMemory = async (cfg, idOrAddress, flags, by) => {
+    const isAddress = /^https?:\/\//i.test(idOrAddress);
+    const address = isAddress ? parseWebsiteMemoryAddress(cfg.webUrl, idOrAddress) : undefined;
+    if (isAddress && !address) {
+        process.stderr.write(`The memory address must be on ${cfg.webUrl}/by/<owner>/memories/<ref>.\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    if (address && by && address.ownerHandle !== by) {
+        process.stderr.write('--by must name the same owner as the memory address.\n');
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const storedSession = loadSession();
+    let ownerHandle = address?.ownerHandle ?? by ?? storedSession?.handle;
     let accessToken;
-    try {
-        accessToken = await validAccessToken(cfg);
+    if (!ownerHandle && storedSession) {
+        accessToken = await optionalAccessToken(cfg);
+        if (accessToken) {
+            ownerHandle = await ownHandleFor(cfg, accessToken);
+            if (ownerHandle) {
+                const currentSession = loadSession();
+                if (currentSession && currentSession.handle !== ownerHandle) {
+                    saveSession({ ...currentSession, handle: ownerHandle });
+                }
+            }
+        }
     }
-    catch {
-        renderNotLoggedIn();
-        process.exitCode = EXIT.NOAUTH;
+    if (!ownerHandle) {
+        process.stderr.write('A memory id needs its wall: use get memory <website-address> or get memory <id> --by <owner-handle>.\n');
+        process.exitCode = EXIT.USAGE;
         return;
     }
-    const url = buildGetMemoryUrl(cfg.apiUrl, idOrPrefix, flags);
+    accessToken ??= await optionalAccessToken(cfg);
+    const url = buildGetMemoryUrl(cfg.webUrl, ownerHandle, address?.ref ?? idOrAddress, flags);
     const enveloped = url.search !== '';
-    const result = await apiFetch(accessToken, url);
+    const result = await apiFetch(accessToken, url, {
+        headers: { Accept: 'application/json' }
+    }, 'web');
     if (!result.ok) {
         renderAmbiguousIfPresent(result.body);
+        if (result.body.code === 'memory:not-found' && !address && !by) {
+            process.stderr.write('For another wall, use get memory <website-address> or get memory <id> --by <owner-handle>.\n');
+        }
         process.exitCode = result.exit;
         return;
     }
-    // The address needs the caller's OWN handle, which this response does not
-    // carry — so it costs a second request. Paid ONLY at a TTY: piped output is
-    // the wire verbatim and gains nothing from an address, so a script never
-    // pays for a line it will not receive. Fetched rather than cached: caching
-    // would be safe (a handle is assigned once and never reassigned, so it
-    // cannot go stale), but it would mean writing state from a read path and
-    // carrying a miss-path for sessions that predate it — for one extra request
-    // on an interactive command that is already making one. Cache later if it
-    // ever matters; the immutability that makes it safe is not going anywhere.
-    //
-    // Deliberately NOT through apiFetch: that renders a door on failure and hands
-    // back an exit code, which is right for a call the caller asked for and wrong
-    // for this one. The record is already in hand; a convenience that cannot be
-    // built should vanish quietly, not print "Session invalid or expired" over a
-    // memory that printed perfectly well.
-    // Bare or enveloped, the block whose address we'd compose is the same
-    // record — the envelope's anchor carries handle+title either way.
     const record = enveloped ? result.data.node : result.data;
-    let address;
-    if (process.stdout.isTTY) {
-        address = await composeAddressFor(cfg, accessToken, record);
-    }
+    const displayAddress = process.stdout.isTTY
+        ? composeAddress(cfg.webUrl, ownerHandle, record)
+        : undefined;
     emit(result.data, result.rawText, () => enveloped
-        ? formatNodeWalk(result.data, address)
-        : formatMemoryDetail(result.data, address));
+        ? formatNodeWalk(result.data, displayAddress)
+        : formatMemoryDetail(result.data, displayAddress));
 };
 const GET_FLAG_NAMES = {
+    '--by': 'by',
     '--revision': 'revision',
     '--type': 'type',
     '--intent': 'intent',
@@ -2661,23 +2720,51 @@ const getMemories = async (cfg, flags) => {
         process.stderr.write(`More: ${renderRunHint(argv)}\n`);
     }
 };
+const getWallMemories = async (cfg, ownerHandle, flags) => {
+    const accessToken = await optionalAccessToken(cfg);
+    const url = new URL(`${cfg.webUrl}/by/${encodeURIComponent(ownerHandle)}/memories`);
+    if (flags.limit !== undefined)
+        url.searchParams.set('limit', flags.limit);
+    if (flags.cursor !== undefined)
+        url.searchParams.set('cursor', flags.cursor);
+    if (flags.content !== undefined)
+        url.searchParams.set('content', flags.content);
+    const result = await apiFetch(accessToken, url, {
+        headers: { Accept: 'application/json' }
+    }, 'web');
+    if (!result.ok) {
+        process.exitCode = result.exit;
+        return;
+    }
+    emit(result.data, result.rawText, formatMemoryPage);
+    if (result.data.nextCursor) {
+        const argv = ['get', 'memories', '--by', ownerHandle];
+        if (flags.limit !== undefined)
+            argv.push('--limit', flags.limit);
+        if (flags.content !== undefined)
+            argv.push('--content', flags.content);
+        argv.push('--cursor', result.data.nextCursor);
+        process.stderr.write(`More: ${renderRunHint(argv)}\n`);
+    }
+};
 // Printed by bare `lattris get` and `lattris get --help` (spec: everything the
 // tool accepts is discoverable from the tool). Same discovery-by-depth pattern
 // capture uses, one level: get has no separate "form" to go deeper into, so the
 // nouns, the positional, and the flags all live at this one level.
 export const GET_HELP = [
-    'get — read your memories back.',
+    'get — read your memories or a public wall.',
     '',
     'Nouns:',
-    '  memories   list, newest first',
-    '  memory     one, by full id or a >=4-char prefix \u2014 its edges ride along',
+    '  memories   your list, or one wall with --by <owner-handle>',
+    '  memory     one, by website address or id with --by <owner-handle> \u2014 its edges ride along',
     '  history    one note\u2019s history: every change, newest first, and the head fingerprint',
     '  deleted    your deleted items, with the fingerprint restore and erase need',
     '  questions  the questions left on your tree, open first',
     '',
     'Usage:',
     '  lattris get memories [--shared-with-me] [--q <words>] [--type <name>] [--intent <name>] [--with <audience>] [--limit <n>] [--cursor <token>] [--content 0|1]',
-    '  lattris get memory <id-or-prefix> [--links 0|1] [--depth <n>] [--content 0|1]',
+    '  lattris get memories --by <owner-handle> [--limit <n>] [--cursor <token>] [--content 0|1]',
+    '  lattris get memory <website-address|id> [--by <owner-handle>] [--links 0|1] [--depth <n>] [--content 0|1]',
     '  lattris get memory <id-or-prefix> --revision <n>      one revision, as history kept it',
     '  lattris get history <id-or-prefix> [--limit <n>] [--before <operation-id>]',
     '  lattris get deleted [--limit <n>] [--cursor <token>]',
@@ -2694,6 +2781,8 @@ export const GET_HELP = [
     '                       (private — no grant at all)',
     '  --limit    <n>       page size, 1-100 (default 50)',
     '  --cursor   <token>   the nextCursor from a previous page',
+    '  --by      <handle>  one wall on the website address; an id without a',
+    '                       session needs it, while a full address carries it',
     '  --shared-with-me     list memories other people granted to you; each row',
     '                       names its owner and whether it is on your graph',
     '',
@@ -2716,11 +2805,11 @@ export const GET_HELP = [
     '',
     'Every read of a note prints its fingerprint (the head of its history) and',
     'revisionNo; every read prints structureHash, a hash of the block\u2019s links and',
-    'grants as YOU see them. An edit sends the fingerprint back as --base-fingerprint.',
+    'grants as this reader sees them. An edit sends the fingerprint back as --base-fingerprint.',
     '',
-    "A memory's web address is <site>/by/<your-handle>/memories/<memory-handle> —",
-    'the handle column above, after your own from whoami. `get memory` prints the',
-    'finished address; the site adds the readable title itself, so the bare form lands.',
+    "A memory's web address is <site>/by/<owner-handle>/memories/<slug>-<memory-handle>.",
+    'A /by read asks for JSON with Accept: application/json; it sends a bearer',
+    'only when the session has a live one. `get memory` prints the address at a TTY.',
     '',
     'Aliases: read, show, view, fetch → get'
 ].join('\n');
@@ -2747,21 +2836,113 @@ const GET_NOUNS = new Set([
 // when the build wrote one, and is ABSENT rather than guessed when it did not —
 // `tsc` alone does not write that stamp, the install path does, so a package
 // built by CI carries it only if CI writes it.
+const runtimeJson = (path) => {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+const currentPackageVersion = () => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = runtimeJson(join(here, '..', 'package.json'));
+    return typeof pkg?.version === 'string' ? pkg.version : 'unknown';
+};
 const printVersion = () => {
     const here = dirname(fileURLToPath(import.meta.url));
-    const readJson = (path) => {
+    const build = runtimeJson(join(here, 'build.json'));
+    const version = currentPackageVersion();
+    const commit = typeof build?.commit === 'string' ? build.commit.slice(0, 12) : undefined;
+    process.stdout.write(commit ? `lattris ${version} (${commit})\n` : `lattris ${version}\n`);
+};
+const VERSION_CHECK_URL = 'https://registry.npmjs.org/lattris/latest';
+const VERSION_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+const VERSION_CHECK_TIMEOUT_MS = 1500;
+const parseVersion = (version) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+    if (!match)
+        return undefined;
+    return {
+        core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+        prerelease: match[4] === undefined ? null : match[4].split('.')
+    };
+};
+// SemVer precedence without adding a runtime dependency to the zero-dependency
+// CLI. Returns negative when left is older, positive when it is newer.
+const compareVersions = (left, right) => {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    if (!a || !b)
+        return undefined;
+    for (let i = 0; i < a.core.length; i++) {
+        if (a.core[i] < b.core[i])
+            return -1;
+        if (a.core[i] > b.core[i])
+            return 1;
+    }
+    if (a.prerelease === null && b.prerelease === null)
+        return 0;
+    if (a.prerelease === null)
+        return 1;
+    if (b.prerelease === null)
+        return -1;
+    const length = Math.max(a.prerelease.length, b.prerelease.length);
+    for (let i = 0; i < length; i++) {
+        const av = a.prerelease[i];
+        const bv = b.prerelease[i];
+        if (av === undefined)
+            return -1;
+        if (bv === undefined)
+            return 1;
+        if (av === bv)
+            continue;
+        const aNumber = /^\d+$/.test(av);
+        const bNumber = /^\d+$/.test(bv);
+        if (aNumber && bNumber)
+            return BigInt(av) < BigInt(bv) ? -1 : 1;
+        if (aNumber !== bNumber)
+            return aNumber ? -1 : 1;
+        return av < bv ? -1 : 1;
+    }
+    return 0;
+};
+// A courtesy, never a gate: every read, request, parse and write failure is
+// swallowed, and this function never changes the command's exit code. Startup
+// launches it without awaiting it, so the command begins while the registry
+// request is in flight; the bounded request cannot hold a quick command open
+// indefinitely.
+export const checkForNewVersion = async ({ currentVersion, stateDir, now = Date.now(), fetchImpl = fetch }) => {
+    try {
+        const cachePath = join(stateDir, 'version-check.json');
+        const cache = runtimeJson(cachePath);
+        if (typeof cache?.checkedAt === 'number' && now - cache.checkedAt <= VERSION_CHECK_TTL_MS) {
+            return;
+        }
+        const response = await fetchImpl(VERSION_CHECK_URL, {
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(VERSION_CHECK_TIMEOUT_MS)
+        });
+        if (!response.ok)
+            return;
+        const body = (await response.json());
+        if (typeof body.version !== 'string' || parseVersion(body.version) === undefined)
+            return;
         try {
-            return JSON.parse(readFileSync(path, 'utf8'));
+            mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+            writeFileSync(cachePath, `${JSON.stringify({ checkedAt: now, latestVersion: body.version })}\n`, { mode: 0o600 });
         }
         catch {
-            return undefined;
+            // An unwritable cache means a later startup may retry; it never makes
+            // this command fail or hides an update the registry already answered.
         }
-    };
-    const pkg = readJson(join(here, '..', 'package.json'));
-    const build = readJson(join(here, 'build.json'));
-    const version = typeof pkg?.version === 'string' ? pkg.version : 'unknown';
-    const commit = typeof build?.commit === 'string' ? build.commit.slice(0, 12) : undefined;
-    process.stdout.write(commit ? `lattris ${version} (${commit})\n` : `lattris ${version}\n`);
+        if (compareVersions(currentVersion, body.version) === -1) {
+            process.stderr.write(`lattris ${currentVersion} → ${body.version} available: npm update -g lattris\n`);
+        }
+    }
+    catch {
+        // Offline, timed out, malformed response, unreadable cache: all silent.
+    }
 };
 const HELP_TOKENS = new Set(['--help', '-h', 'help']);
 export const LOGIN_HELP = [
@@ -2933,6 +3114,11 @@ const get = async (cfg, noun, rest) => {
             return;
         }
         if (flags.revision !== undefined) {
+            if (flags.by !== undefined || /^https?:\/\//i.test(id)) {
+                process.stderr.write('A revision read uses your own id or prefix; --by and website addresses do not apply.\n');
+                process.exitCode = EXIT.USAGE;
+                return;
+            }
             const walkFlag = ['links', 'depth', 'content'].find((k) => flags[k] !== undefined);
             if (walkFlag !== undefined) {
                 process.stderr.write(`--${walkFlag} does not apply to a revision read.\n`);
@@ -2942,7 +3128,7 @@ const get = async (cfg, noun, rest) => {
             await getRevision(cfg, id, flags.revision);
             return;
         }
-        await getMemory(cfg, id, { links: flags.links, depth: flags.depth, content: flags.content });
+        await getMemory(cfg, id, { links: flags.links, depth: flags.depth, content: flags.content }, flags.by);
     }
     else if (noun === 'memories') {
         // The symmetric refusal: a walk lever on a list would be parsed clean and
@@ -2953,10 +3139,22 @@ const get = async (cfg, noun, rest) => {
             process.exitCode = EXIT.USAGE;
             return;
         }
-        await getMemories(cfg, flags);
+        if (flags.by !== undefined) {
+            const ownerOnly = ['type', 'intent', 'q', 'with', 'sharedWithMe'].find((key) => flags[key] !== undefined);
+            if (ownerOnly !== undefined) {
+                const flagName = ownerOnly === 'sharedWithMe' ? 'shared-with-me' : ownerOnly;
+                process.stderr.write(`--${flagName} does not apply to a wall listing.\n`);
+                process.exitCode = EXIT.USAGE;
+                return;
+            }
+            await getWallMemories(cfg, flags.by, flags);
+        }
+        else {
+            await getMemories(cfg, flags);
+        }
     }
     else {
-        process.stderr.write('An id (or unique prefix) is required for a single memory. To list them all: lattris get memories\n');
+        process.stderr.write('A website address or id is required for a single memory. To list your own: lattris get memories\n');
         process.exitCode = EXIT.USAGE;
     }
 };
@@ -6606,10 +6804,14 @@ export const main = async () => {
             ? VERB_ALIASES[rawCommand]
             : rawCommand
         : rawCommand;
-    // HELP BEFORE EVERYTHING: a help token in the subcommand's args means
-    // help — never a session check, never a network call, exit 0. Commands
-    // whose own handler already treats help first return null and fall
-    // through unchanged.
+    void checkForNewVersion({
+        currentVersion: currentPackageVersion(),
+        stateDir: join(stateHome(), 'lattris')
+    });
+    // HELP BEFORE COMMAND WORK: a help token in the subcommand's args means
+    // help — never a session or API call, exit 0. The best-effort registry
+    // courtesy above is startup work rather than command work. Commands whose
+    // own handler already treats help first return null and fall through unchanged.
     const subArgs = argv.slice(3);
     if (command !== undefined && subArgs.some((t) => HELP_TOKENS.has(t))) {
         const help = commandHelpText(command, subArgs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lattris",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "First-party CLI for Lattris — sign in, capture notes and sessions, and read your own tree from the terminal.",
   "keywords": [