lattris 0.1.0 → 0.1.3

package/README.md

@@ -57,22 +57,32 @@ Run `lattris help <command>` for any of them, or `lattris --help` for the full l
 
 ## Where it keeps things
 
-Credentials live in your user config directory and are readable only by you. `lattris
-logout` removes them. Nothing is written to the directory you run it from.
+Credentials live at `~/lattris-machines/<account>/<env>/session.json` and are readable
+only by you. `lattris logout` removes them. Nothing is written to the directory you run
+it from.
 
-## Verifying what you installed
+## Release
 
-Releases published through CI carry [npm provenance](https://docs.npmjs.com/generating-provenance-statements):
-the registry records an attestation linking the tarball to the commit on `main` it was
-built from and the workflow run that built it. The first published version was published
-by hand to claim the name and carries no attestation, so do not assume one — check:
+Releasing has two steps. First, open a normal version-bump PR from a branch:
 
 ```bash
-npm audit signatures
+cd apps/lattris/cli
+npm version patch --no-git-tag-version
+git add package.json
+git commit -m "chore(lattris-cli): bump package version"
 ```
 
-That is a statement about the version you installed from the registry. It says nothing
-about a copy obtained any other way.
+After that PR merges, whoever holds npm publish rights updates a clean local `main` and runs:
+
+```bash
+cd apps/lattris/cli
+pnpm release
+```
+
+The release script fetches `origin/main` and refuses unless the current branch is `main`,
+`HEAD` equals `origin/main`, and the whole working tree is clean. It builds the CLI, writes
+the release commit to `dist/build.json`, publishes to npm, and pushes the annotated
+`lattris-v<version>` tag. `lattris --version` then names that release commit.
 
 ## Source, terms and reporting
 
@@ -82,5 +92,4 @@ Nothing here grants you rights beyond installing and running the tool, and no
 permission should be inferred from the absence of a licence file.
 
 There is no public issue tracker, so this package names none — a link you cannot
-open is worse than no link. For terms, faults or anything else, write to
-series@lattris.com.
+open is worse than no link.

package/dist/build.json

@@ -0,0 +1 @@
+{"commit":"cecf7e60eb450bce092dc992155ff77002fc1379","builtAt":"2026-09-15T22:27:41Z"}

package/dist/main.js

@@ -14,10 +14,11 @@
 // deputy / scoped-grant machinery here. It reuses the exact SPA-minted-Hydra-JWT
 // path the API already validates; zero server-side auth changes.
 //
-// Zero runtime dependencies — Node ≥ 24 built-ins only (global fetch, node:http,
-// node:crypto). Runnable directly via `node --experimental-strip-types
-// src/main.ts <cmd>` (no build step) or as the built `lattris` bin. Functions are
-// exported for unit tests; `main()` runs only when this file is the entry point.
+// Zero runtime dependencies — the compiled bin runs on Node ≥ 22 built-ins only
+// (global fetch, node:http, node:crypto). Running the TypeScript source directly
+// still uses the repo's Node 24 toolchain via `node --experimental-strip-types
+// src/main.ts <cmd>`. Functions are exported for unit tests; `main()` runs only
+// when this file is the entry point.
 // Strip-only mode erases TYPES, never TS-only syntax: no constructor parameter
 // properties, enums, or namespaces anywhere in src/ — a parameter property
 // crashes the no-build run outright (ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX).
@@ -30,11 +31,11 @@ import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { chmodSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { homedir } from 'node:os';
-import { dirname, join, resolve, sep } from 'node:path';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
-import { extractChain } from './extract-claude-jsonl.js';
-import { ChainSaveError, driveChain, loadReceipts, saveReceipts } from './save-session-chain.js';
+import { extractChain } from "./extract-claude-jsonl.js";
+import { ChainSaveError, driveChain, loadReceipts, saveReceipts } from "./save-session-chain.js";
 // ─── exit codes ────────────────────────────────────────────────────────────────
 // Stable, meaningful exit codes so a script can tell failure kinds apart without
 // parsing prose (CLI client-contract spec §3). Code 4 is the machine twin of a
@@ -48,6 +49,18 @@ export const EXIT = {
     DOOR: 4 // a door must be walked first (e.g. person:uninitiated)
 };
 const stripTrailingSlash = (s) => s.replace(/\/+$/, '');
+// A published package contains only the runtime files allow-listed in
+// package.json. A worktree build also contains installed-check.js, whose whole
+// purpose is to judge the repo-backed symlink install. That absent/present seam
+// lets a clean npm install go to the product by default while source and worktree
+// development keep their existing local default. Explicit --env, .lattris and
+// LATTRIS_ENV always win over this fallback.
+export const defaultEnvironmentForEntry = (entryUrl = import.meta.url) => {
+    const entryPath = fileURLToPath(entryUrl);
+    const entryDir = dirname(entryPath);
+    const isBuiltMain = basename(entryPath) === 'main.js' && basename(entryDir) === 'dist';
+    return isBuiltMain && !existsSync(join(entryDir, 'installed-check.js')) ? 'prod' : 'local';
+};
 // The environments registry — a JSON file at a well-known location. Missing
 // file or missing key → the built-in localdev defaults below, so the CLI
 // works out of the box with no registry (the existing behavior).
@@ -646,6 +659,7 @@ export const CLI_COMMAND_WORDS = new Set([
     'invite',
     'share',
     'unshare',
+    'consent',
     'restore',
     'erase',
     'resend',
@@ -1005,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>
@@ -1160,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
@@ -1189,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 };
@@ -1201,11 +1227,10 @@ export const apiFetch = async (accessToken, url, init = {}) => {
 // ─── the client-makes-no-decisions output rule ──────────────────────────────────
 // A person reading a terminal and a program reading a pipe want different things
 // from the SAME response: a person wants the labelled/columnar form, a program
-// wants exactly what the API sent. Piped output is the wire body VERBATIM — BYTE
-// verbatim, not a re-stringify of the parsed object (which is only semantically
-// equal — different key order, whitespace, or number formatting would all still
-// pass a deep-equal test while lying about what actually crossed the wire) — so
-// structured output can never drift from the API (deliberate).
+// wants the API's wire body without re-stringification. Piped output preserves
+// the response bytes (key order, whitespace and number formatting included) and
+// adds only a missing final newline, so successive shell output cannot run into
+// the JSON. A response that already ends in a newline is unchanged.
 // renderHuman picks what a person needs to see; it never changes what a machine
 // receives. An empty human rendering (e.g. no memories) writes nothing rather
 // than a stray blank line.
@@ -1216,7 +1241,7 @@ export const emit = (data, rawText, renderHuman) => {
             process.stdout.write(`${human}\n`);
     }
     else {
-        process.stdout.write(rawText);
+        process.stdout.write(rawText.endsWith('\n') ? rawText : `${rawText}\n`);
     }
 };
 // The product word is "lattris number", never
@@ -1743,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)
@@ -1759,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
@@ -2304,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' },
@@ -2343,7 +2378,9 @@ export const formatAudiences = (audiences) => audiences.length === 0 ? '(private
 // title is the caller's own free text — sanitized before a TTY renders it (the
 // piped/JSON path never calls this formatter). id/capturedAt/intent are all
 // API-constrained shapes, never free text.
-export const formatBlockLine = (b) => `${b.id}  ${b.handle}  ${b.capturedAt}  ${b.intent ?? '-'}  ${b.visibility.public ? 'public' : '-'}  ${sanitizeForTerminal(b.title ?? '(untitled)')}`;
+export const formatBlockLine = (b) => b.ownerHandle === undefined
+    ? `${b.id}  ${b.handle}  ${b.capturedAt}  ${b.intent ?? '-'}  ${b.visibility.public ? 'public' : '-'}  ${sanitizeForTerminal(b.title ?? '(untitled)')}`
+    : `${b.id}  ${b.handle}  ${b.capturedAt}  by ${sanitizeForTerminal(b.ownerDisplayName ?? b.ownerHandle)} (@${b.ownerHandle})  ${b.consented ? 'on graph' : 'off graph'}  ${sanitizeForTerminal(b.title ?? '(untitled)')}`;
 // ─── composing a memory's web address ──────────────────────────────────────────
 // The client COMPOSES an address; only the server RESOLVES one, and it resolves
 // on the block handle alone. That split is why carrying these rules here is
@@ -2365,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}` }
@@ -2376,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/
@@ -2509,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) {
@@ -2522,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',
@@ -2580,7 +2654,7 @@ const GET_FLAG_NAMES = {
 };
 // Which side of get each flag belongs to — the applicability refusals in the
 // dispatcher read these, so a new flag must pick a side to compile at all.
-const LIST_ONLY_FLAGS = ['type', 'intent', 'limit', 'cursor', 'q', 'with'];
+const LIST_ONLY_FLAGS = ['type', 'intent', 'limit', 'cursor', 'q', 'with', 'sharedWithMe'];
 // --content is the shape lever on BOTH reads: on the one memory it drops the
 // words, on the list it drops the excerpts. The rest of these are the walk's.
 const WALK_ONLY_FLAGS = ['links', 'depth', 'revision'];
@@ -2614,16 +2688,15 @@ const getMemories = async (cfg, flags) => {
         url.searchParams.set('audience', flags.with);
     if (flags.content !== undefined)
         url.searchParams.set('content', flags.content);
+    if (flags.sharedWithMe)
+        url.searchParams.set('sharedWithMe', '1');
     const result = await apiFetch(accessToken, url);
     if (!result.ok) {
         process.exitCode = result.exit;
         return;
     }
     emit(result.data, result.rawText, formatMemoryPage);
-    if (result.data.items.length === 0) {
-        process.stderr.write('No memories yet.\n');
-    }
-    else if (result.data.nextCursor) {
+    if (result.data.nextCursor) {
         // Reconstruct the FULL continuation — active filters + the new cursor — so
         // copy-pasting the hint never silently drops back to an unfiltered page.
         // ARGV elements through the one renderer, never a preformed string: a
@@ -2637,6 +2710,35 @@ const getMemories = async (cfg, flags) => {
             argv.push('--q', flags.q);
         if (flags.with !== undefined)
             argv.push('--with', flags.with);
+        if (flags.limit !== undefined)
+            argv.push('--limit', flags.limit);
+        if (flags.content !== undefined)
+            argv.push('--content', flags.content);
+        if (flags.sharedWithMe)
+            argv.push('--shared-with-me');
+        argv.push('--cursor', result.data.nextCursor);
+        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)
@@ -2650,18 +2752,19 @@ const getMemories = async (cfg, flags) => {
 // 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 [--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 [--shared-with-me] [--q <words>] [--type <name>] [--intent <name>] [--with <audience>] [--limit <n>] [--cursor <token>] [--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>]',
@@ -2678,6 +2781,10 @@ 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',
     '',
     '  --links    0|1       edges on the one memory (default 1): direction, verb,',
     '                       reason, and each neighbour\u2019s finding aid. --links 0',
@@ -2698,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');
@@ -2729,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 = [
@@ -2792,6 +2991,8 @@ export const commandHelpText = (command, args) => {
             return ERASE_HELP;
         case 'contact':
             return CONTACT_HELP;
+        case 'consent':
+            return CONSENT_HELP;
         case 'capture': {
             // The form's own help when a form was named — mirroring the
             // sub-dispatcher's routing (positional 'session' OR --type session);
@@ -2871,7 +3072,15 @@ const get = async (cfg, noun, rest) => {
         await getDeleted(cfg, rest);
         return;
     }
-    const { flags, positionals, unknown } = parseArgs(GET_FLAG_NAMES, rest);
+    const sharedWithMeCount = rest.filter((arg) => arg === '--shared-with-me').length;
+    if (sharedWithMeCount > 1) {
+        process.stderr.write('--shared-with-me was given more than once. Send it once.\n');
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const { flags, positionals, unknown } = parseArgs(GET_FLAG_NAMES, rest.filter((arg) => arg !== '--shared-with-me'));
+    if (sharedWithMeCount === 1)
+        flags.sharedWithMe = '1';
     if (unknown) {
         process.stderr.write(`Unknown flag: ${unknown}\n`);
         process.exitCode = EXIT.USAGE;
@@ -2905,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`);
@@ -2914,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
@@ -2925,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;
     }
 };
@@ -2936,6 +3162,10 @@ const get = async (cfg, noun, rest) => {
 // like a note's content. Everything else is API-constrained shape.
 export const formatQuestion = (q) => {
     const lines = [`id           ${q.id}`, `createdAt    ${q.createdAt}`];
+    if (q.kind === 'share') {
+        lines.push(`shared by    @${sanitizeForTerminal(q.sharerHandle ?? '(unknown)')}`, `memory       ${q.aboutBlockId ?? '(missing)'}`, `seen         ${q.seenAt ?? '(unseen)'}`);
+        return lines.join('\n');
+    }
     if (q.aboutBlockId)
         lines.push(`about        ${q.aboutBlockId}`);
     lines.push(q.closedAs === null
@@ -2945,7 +3175,7 @@ export const formatQuestion = (q) => {
     // here, but the same sanitize-before-TTY law applies to any rendered field.
     if (q.closeNote)
         lines.push(`note         ${sanitizeForTerminal(q.closeNote, Infinity)}`);
-    lines.push('', sanitizeForTerminal(q.body, Infinity));
+    lines.push('', sanitizeForTerminal(q.body ?? '', Infinity));
     return lines.join('\n');
 };
 export const formatQuestionList = (qs) => qs.map((q) => formatQuestion(q)).join('\n\n');
@@ -2965,9 +3195,6 @@ const getQuestions = async (cfg, mine) => {
         return;
     }
     emit(result.data, result.rawText, formatQuestionList);
-    if (result.data.length === 0) {
-        process.stderr.write(mine ? 'No questions asked yet.\n' : 'No questions.\n');
-    }
 };
 // ask — POST /by/:handle/questions. THE BODY IS THE GRANT (v1 doctrine): the
 // prose from stdin is exactly what crosses to the tree's owner — no
@@ -4170,9 +4397,9 @@ const update = async (cfg, noun, rest) => {
 // touches it. So a link is not admission, and the CLI says so rather than
 // letting a person discover it at the door.
 //
-// Minting is unrestricted: once you are in, you can mint. There is no quota, and
-// revoking one link does not stop you minting another — the link is dead, the
-// person is not.
+// Minting is open only on accounts with the server-side entitlement. The
+// server's refusal message rides the shared API error path unchanged. There is
+// no quota once open, and revoking one link does not close the door.
 export const INVITE_HELP = [
     'invite — bring one person in.',
     '',
@@ -4185,13 +4412,14 @@ export const INVITE_HELP = [
     'when you send it.',
     '',
     'Usage:',
-    '  lattris invite                       mints, prints the link',
-    '  lattris invite --for "Josh"          the same, with your own label',
+    '  lattris invite <contact-name-or-id> [--yes]',
+    '  lattris invite --for <name-or-id> [--yes]   compatibility spelling',
+    '',
+    'The contact must be one of yours. A name is matched exactly, ignoring case.',
+    'If that name does not exist, a person contact is created before minting.',
+    'Duplicate names are never guessed: use the contact id shown by',
+    '`lattris contact list`.',
     '',
-    '  --for   optional; YOUR label for who this is for, so you can tell your',
-    '          outstanding links apart. It is shown on the invitation page and',
-    '          to you. It is not their name and not contact information — their',
-    '          real name comes from them, at signup.',
     '  --yes   required when not at a terminal (there is no prompt to answer',
     '          there); at a terminal you are always asked.',
     '',
@@ -4218,6 +4446,22 @@ const formatInvite = (cfg, i) => {
         return `revoked${label}\n  minted ${i.createdAt}`;
     return `live${label}\n  ${inviteLink(cfg, i.token)}\n  minted ${i.createdAt}`;
 };
+// Names are labels, so exact duplicate labels must never be guessed. UUIDs are
+// ids, never names: an unknown UUID refuses instead of creating a strangely
+// named contact that only looks like an existing id.
+export const resolveInviteContact = (contacts, selector) => {
+    if (isUuidKey(selector)) {
+        const contact = contacts.find((c) => c.id.toLowerCase() === selector.toLowerCase());
+        return contact ? { kind: 'found', contact } : { kind: 'missing-id' };
+    }
+    const folded = selector.toLowerCase();
+    const matches = contacts.filter((c) => c.displayName.toLowerCase() === folded);
+    if (matches.length === 1)
+        return { kind: 'found', contact: matches[0] };
+    if (matches.length > 1)
+        return { kind: 'ambiguous', matches };
+    return { kind: 'missing-name', displayName: selector };
+};
 const invite = async (cfg, rest) => {
     if (rest.some((t) => HELP_TOKENS.has(t))) {
         process.stdout.write(`${INVITE_HELP}\n`);
@@ -4230,25 +4474,25 @@ const invite = async (cfg, rest) => {
         process.exitCode = EXIT.USAGE;
         return;
     }
-    if (positionals.length > 0) {
-        process.stderr.write(`Unexpected argument: ${positionals[0]}\n`);
+    if (positionals.length > 1 || (positionals.length === 1 && flags.for !== undefined)) {
+        process.stderr.write(`${INVITE_HELP}\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const selector = positionals[0] ?? flags.for;
+    if (selector === undefined || selector.trim().length === 0) {
+        process.stderr.write('A contact name or id is required.\n');
         process.exitCode = EXIT.USAGE;
         return;
     }
     // Same law as delete and born-public capture: an AI proposes, it cannot
-    // commit. A TTY is asked; a non-TTY caller must pass --yes. Minting is not
-    // destructive, but it spends something real — a slot a person will hand to
-    // someone — and it should never happen because a model thought it helpful.
+    // commit. A non-TTY caller must make the person's approval explicit.
     if (!process.stdin.isTTY && !yes) {
         process.stderr.write('Refusing to mint without confirmation. Pass --yes once the person has ' +
             'asked you to invite someone.\n');
         process.exitCode = EXIT.USAGE;
         return;
     }
-    if (process.stdin.isTTY && !(await confirm('Mint an invitation to hand to one person?'))) {
-        process.stdout.write('Not minted.\n');
-        return;
-    }
     let accessToken;
     try {
         accessToken = await validAccessToken(cfg);
@@ -4258,16 +4502,64 @@ const invite = async (cfg, rest) => {
         process.exitCode = EXIT.NOAUTH;
         return;
     }
+    const contactsResult = await apiFetch(accessToken, `${cfg.apiUrl}/contacts`);
+    if (!contactsResult.ok) {
+        process.exitCode = contactsResult.exit;
+        return;
+    }
+    const resolution = resolveInviteContact(contactsResult.data, selector.trim());
+    if (resolution.kind === 'missing-id') {
+        process.stderr.write(`No contact ${sanitizeForTerminal(selector)} among yours. ${renderRunHint(['contact', 'list'])} shows them.\n`);
+        process.exitCode = EXIT.GENERIC;
+        return;
+    }
+    if (resolution.kind === 'ambiguous') {
+        process.stderr.write(`${sanitizeForTerminal(selector)} matches more than one of your contacts:\n${resolution.matches.map((c) => `  ${formatContact(c)}`).join('\n')}\nUse a contact id instead.\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const displayName = resolution.kind === 'found' ? resolution.contact.displayName : resolution.displayName;
+    if (resolution.kind === 'found' && resolution.contact.type !== 'person') {
+        process.stderr.write(`${sanitizeForTerminal(displayName)} is an AI contact. An invitation must go to a person contact.\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const action = resolution.kind === 'missing-name'
+        ? `Create person contact "${sanitizeForTerminal(displayName)}" and mint their invitation?`
+        : `Mint an invitation for ${sanitizeForTerminal(displayName)}?`;
+    if (process.stdin.isTTY && !(await confirm(action))) {
+        process.stdout.write('Not minted.\n');
+        return;
+    }
+    let contact;
+    let createdContact = false;
+    if (resolution.kind === 'missing-name') {
+        const created = await apiFetch(accessToken, `${cfg.apiUrl}/contacts`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ displayName, type: 'person' })
+        });
+        if (!created.ok) {
+            process.exitCode = created.exit;
+            return;
+        }
+        contact = created.data;
+        createdContact = true;
+    }
+    else {
+        contact = resolution.contact;
+    }
     const result = await apiFetch(accessToken, `${cfg.apiUrl}/invites`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(flags.for ? { targetName: flags.for } : {})
+        body: JSON.stringify({ contactId: contact.id })
     });
     if (!result.ok) {
         process.exitCode = result.exit;
         return;
     }
-    emit(result.data, result.rawText, (i) => `Invitation minted${i.targetName ? ` for ${i.targetName}` : ''}.\n\n` +
+    emit(result.data, result.rawText, (i) => `${createdContact ? `Recorded person contact ${formatContact(contact)}.\n\n` : ''}` +
+        `Invitation minted${i.targetName ? ` for ${i.targetName}` : ''}.\n\n` +
         `  ${inviteLink(cfg, i.token)}\n\n` +
         `Hand it to ONE person — it is spent when someone signs up with it.\n` +
         `It is not permission to join; whether they may register is decided separately.\n` +
@@ -4289,7 +4581,7 @@ const getInvites = async (cfg) => {
         return;
     }
     emit(result.data, result.rawText, (list) => list.length === 0
-        ? 'No invitations yet. `lattris invite` mints one.'
+        ? 'No invitations yet. `lattris invite <contact>` mints one.'
         : list.map((i) => formatInvite(cfg, i)).join('\n\n'));
 };
 // ─── share (memory <id> --with <audience>) ─────────────────────────────────────
@@ -4305,17 +4597,36 @@ const describeAudience = (audience) => audience === 'public' ? 'public — anyon
 const SHARE_FLAG_NAMES = {
     '--with': 'with'
 };
+const resolveExistingPersonContact = async (cfg, accessToken, selector) => {
+    const result = await apiFetch(accessToken, `${cfg.apiUrl}/contacts`);
+    if (!result.ok) {
+        process.exitCode = result.exit;
+        return undefined;
+    }
+    const resolution = resolveInviteContact(result.data, selector.trim());
+    if (resolution.kind === 'ambiguous') {
+        process.stderr.write(`${sanitizeForTerminal(selector)} matches more than one of your contacts:\n${resolution.matches.map((c) => `  ${formatContact(c)}`).join('\n')}\nUse a contact id instead.\n`);
+        process.exitCode = EXIT.USAGE;
+        return undefined;
+    }
+    if (resolution.kind !== 'found') {
+        process.stderr.write(`No contact ${sanitizeForTerminal(selector)} among yours. ${renderRunHint(['contact', 'list'])} shows them.\n`);
+        process.exitCode = EXIT.GENERIC;
+        return undefined;
+    }
+    if (resolution.contact.type !== 'person' || resolution.contact.claimedPersonId == null) {
+        process.stderr.write('This person has no account yet — invite them first.\n');
+        process.exitCode = EXIT.USAGE;
+        return undefined;
+    }
+    return { ...resolution.contact, claimedPersonId: resolution.contact.claimedPersonId };
+};
 const shareMemory = async (cfg, idOrPrefix, audience, yes) => {
     // ALL local preconditions settle before any network/token touch — same law
     // as delete: a question that was always going to be refused must never
     // spend a token refresh first.
     if (audience === undefined) {
-        process.stderr.write(`--with is required. Accepted: ${SHARE_AUDIENCES.join(', ')}\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
-    if (!SHARE_AUDIENCES.includes(audience)) {
-        process.stderr.write(`Unknown audience: ${audience}. Accepted: ${SHARE_AUDIENCES.join(', ')}\n`);
+        process.stderr.write('--with is required. Use public or one of your contact names or ids.\n');
         process.exitCode = EXIT.USAGE;
         return;
     }
@@ -4337,6 +4648,11 @@ const shareMemory = async (cfg, idOrPrefix, audience, yes) => {
     // the confirm fetch and share by the FULL id from then on — not the raw
     // (possibly a prefix) argument again.
     let shareId = idOrPrefix;
+    const contact = audience === 'public'
+        ? undefined
+        : await resolveExistingPersonContact(cfg, accessToken, audience);
+    if (audience !== 'public' && !contact)
+        return;
     if (process.stdin.isTTY) {
         const fetched = await apiFetch(accessToken, `${cfg.apiUrl}/memories/${encodeURIComponent(idOrPrefix)}`);
         if (!fetched.ok) {
@@ -4345,7 +4661,7 @@ const shareMemory = async (cfg, idOrPrefix, audience, yes) => {
             return;
         }
         const title = sanitizeForTerminal(fetched.data.title ?? '(untitled)');
-        const confirmed = await confirmAction(`Share "${title}" (${fetched.data.id}) with ${describeAudience(audience)}? [y/N] `);
+        const confirmed = await confirmAction(`Share "${title}" (${fetched.data.id}) with ${describeAudience(contact?.displayName ?? audience)}? [y/N] `);
         if (confirmed === 'interrupted') {
             process.stderr.write('Cancelled.\n');
             process.exitCode = EXIT.GENERIC;
@@ -4360,7 +4676,7 @@ const shareMemory = async (cfg, idOrPrefix, audience, yes) => {
     const result = await apiFetch(accessToken, `${cfg.apiUrl}/memories/${encodeURIComponent(shareId)}/grants`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ audience })
+        body: JSON.stringify(contact ? { kind: 'person', contactId: contact.id } : { audience: 'public' })
     });
     if (!result.ok) {
         renderAmbiguousIfPresent(result.body);
@@ -4373,15 +4689,15 @@ const shareMemory = async (cfg, idOrPrefix, audience, yes) => {
     // wire, byte-verbatim (emit's non-TTY branch); a TTY gets the human line
     // instead. shareId (not the response body, which never echoes an id) is
     // what makes the human line locatable — closed over, not a second field.
-    emit(result.data, result.rawText, (grant) => `Shared memory ${shareId} with ${grant.kind}`);
+    emit(result.data, result.rawText, (grant) => `Shared memory ${shareId} with ${contact?.displayName ?? grant.kind}`);
 };
 export const SHARE_HELP = [
-    'share — grant an audience access to a memory.',
+    'share — grant public or a person contact access to a memory.',
     '',
     'Usage:',
-    '  lattris share memory <id-or-prefix> --with <audience> [--yes]',
+    '  lattris share memory <id-or-prefix> --with <public-or-contact> [--yes]',
     '',
-    '  --with   <audience>  required. v1 accepts: public',
+    '  --with   public, or an exact contact name or id from `lattris contact list`.',
     '  --yes                required when not at a terminal; at a terminal you',
     '                       are always asked, --yes or not.',
     '',
@@ -4415,29 +4731,10 @@ const share = async (cfg, noun, rest) => {
     }
     await shareMemory(cfg, positionals[0], flags.with, yes);
 };
-// ─── unshare (memory <id> --with <audience>) ───────────────────────────────────
-// Withdraws an audience — v1 accepts only "public". No confirmation: spec
-// rules withdrawal the safe direction (recoverable by re-sharing). The
-// record is ALWAYS resolved first — needed either way: to withdraw by the
-// FULL id (never re-resolve a prefix, same law as share/delete), or to echo
-// its current audiences + title in the bare-unshare refusal (owner-only
-// operation, so the echo leaks nothing this caller couldn't already see via
-// a plain get).
-export const UNSHARE_AUDIENCES = ['public'];
 const UNSHARE_FLAG_NAMES = {
     '--with': 'with'
 };
 const unshareMemory = async (cfg, idOrPrefix, audience) => {
-    // A PRESENT but unknown audience is a pure value check — it needs nothing
-    // fetched, so it settles before any network/token touch like every other
-    // local precondition in this file. A MISSING audience is different: its
-    // refusal echoes the record's current state, which only the fetch below
-    // can supply, so that one stays gated behind it.
-    if (audience !== undefined && !UNSHARE_AUDIENCES.includes(audience)) {
-        process.stderr.write(`Unknown audience: ${audience}. Accepted: ${UNSHARE_AUDIENCES.join(', ')}\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
     let accessToken;
     try {
         accessToken = await validAccessToken(cfg);
@@ -4447,6 +4744,11 @@ const unshareMemory = async (cfg, idOrPrefix, audience) => {
         process.exitCode = EXIT.NOAUTH;
         return;
     }
+    const contact = audience === undefined || audience === 'public'
+        ? undefined
+        : await resolveExistingPersonContact(cfg, accessToken, audience);
+    if (audience !== undefined && audience !== 'public' && !contact)
+        return;
     const fetched = await apiFetch(accessToken, `${cfg.apiUrl}/memories/${encodeURIComponent(idOrPrefix)}`);
     if (!fetched.ok) {
         renderAmbiguousIfPresent(fetched.body);
@@ -4455,26 +4757,28 @@ const unshareMemory = async (cfg, idOrPrefix, audience) => {
     }
     if (audience === undefined) {
         const title = sanitizeForTerminal(fetched.data.title ?? '(untitled)');
-        process.stderr.write(`--with is required. Accepted: ${UNSHARE_AUDIENCES.join(', ')}\n`);
+        process.stderr.write('--with is required. Use public or one of your contact names or ids.\n');
         process.stderr.write(`"${title}" (${fetched.data.id}) is currently shared with: ${formatAudiences(fetched.data.audiences)}\n`);
         process.exitCode = EXIT.USAGE;
         return;
     }
-    const result = await apiFetch(accessToken, `${cfg.apiUrl}/memories/${encodeURIComponent(fetched.data.id)}/grants/${audience}`, { method: 'DELETE' });
+    const result = await apiFetch(accessToken, contact
+        ? `${cfg.apiUrl}/memories/${encodeURIComponent(fetched.data.id)}/grants/person/${contact.claimedPersonId}`
+        : `${cfg.apiUrl}/memories/${encodeURIComponent(fetched.data.id)}/grants/public`, { method: 'DELETE' });
     if (!result.ok) {
         process.exitCode = result.exit;
         return;
     }
-    process.stderr.write(`Unshared memory ${fetched.data.id} from ${audience}\n`);
+    process.stderr.write(`Unshared memory ${fetched.data.id} from ${contact?.displayName ?? 'public'}\n`);
 };
 export const UNSHARE_HELP = [
     'unshare — withdraw an audience from a memory. No confirmation — withdrawal',
     'is the safe direction.',
     '',
     'Usage:',
-    '  lattris unshare memory <id-or-prefix> --with <audience>',
+    '  lattris unshare memory <id-or-prefix> --with <public-or-contact>',
     '',
-    '  --with   <audience>  required. v1 accepts: public',
+    '  --with   public, or an exact contact name or id from `lattris contact list`.',
     '',
     'Bare (no --with): refuses and shows what the memory is currently shared',
     'with, so you can see the state and the fix in one line.',
@@ -4505,6 +4809,58 @@ const unshare = async (cfg, noun, rest) => {
     }
     await unshareMemory(cfg, positionals[0], flags.with);
 };
+// ─── consent (<shared-memory-id> [--withdraw]) ─────────────────────────────
+export const CONSENT_HELP = [
+    'consent — choose whether a memory shared with you appears on your graph.',
+    '',
+    'Usage:',
+    '  lattris consent <id-or-prefix>',
+    '  lattris consent <id-or-prefix> --withdraw',
+    '',
+    'The choice is yours alone. Withdrawing a share hides the block regardless;',
+    'if its owner shares it again later, your previous choice still stands.'
+].join('\n');
+const consent = async (cfg, rest) => {
+    if (rest.some((arg) => HELP_TOKENS.has(arg))) {
+        process.stdout.write(`${CONSENT_HELP}\n`);
+        return;
+    }
+    const withdrawCount = rest.filter((arg) => arg === '--withdraw').length;
+    const args = rest.filter((arg) => arg !== '--withdraw');
+    const unknown = args.find((arg) => arg.startsWith('--'));
+    if (unknown !== undefined) {
+        process.stderr.write(`Unknown flag: ${unknown}\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    if (withdrawCount > 1 || args.length !== 1) {
+        process.stderr.write(`Usage: lattris consent <id-or-prefix> [--withdraw]\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    let accessToken;
+    try {
+        accessToken = await validAccessToken(cfg);
+    }
+    catch {
+        renderNotLoggedIn();
+        process.exitCode = EXIT.NOAUTH;
+        return;
+    }
+    const result = await apiFetch(accessToken, `${cfg.apiUrl}/memories/${encodeURIComponent(args[0])}/consent`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ consented: withdrawCount === 0 })
+    });
+    if (!result.ok) {
+        renderAmbiguousIfPresent(result.body);
+        process.exitCode = result.exit;
+        return;
+    }
+    emit(result.data, result.rawText, (state) => state.consented
+        ? `Memory ${args[0]} may appear on your graph.`
+        : `Memory ${args[0]} will stay off your graph.`);
+};
 // ─── capture recording (train 8) ────────────────────────────────────────────
 // The API meets ONE recording shape; vendor transcript formats translate HERE,
 // CLI-side, so the door never grows a per-vendor arm. A recording is one door,
@@ -5889,7 +6245,7 @@ const usage = () => {
         '  lattris capture session <transcript>  Save an AI conversation — the whole chain from its file',
         '  lattris get memories         List your memories, newest first, with filters',
         '  lattris contact create "<name>"  Record a person or an AI you work with (--ai); list, get, update',
-        '  lattris invite               Mint an invitation to hand to one person',
+        '  lattris invite <contact>     Mint an invitation for one of your person contacts',
         '  lattris get invites          List the invitations you have minted',
         '  lattris get memory <id>      Read one memory back \u2014 words and edges (--links/--depth/--content)',
         '  lattris ask <handle>         Leave a question on someone\u2019s tree \u2014 `echo "\u2026" | lattris ask <handle>`',
@@ -5897,6 +6253,7 @@ const usage = () => {
         '  lattris close question <id>  Close a question (--close-as updated|declined|already-answered)',
         '  lattris share memory <id>    Grant an audience access (--with public)',
         '  lattris unshare memory <id>  Withdraw an audience (--with public)',
+        '  lattris consent <id>         Put a memory shared with you on your graph (--withdraw reverses)',
         '  lattris link <from> <to>     State that one memory leads to another (--verb, --reason)',
         '  lattris unlink <from> <to>   Remove that claim (--verb; the blocks stay)',
         '  lattris update memory <id>   Correct a memory — `echo "…" | lattris update memory <id> --base-fingerprint <fp>`',
@@ -6420,11 +6777,13 @@ export const main = async () => {
             process.env.LATTRIS_HOME = asResolvedDir;
         }
     }
-    // Resolve the environment name: --env > .lattris env= > LATTRIS_ENV > "local".
+    // Resolve the environment name: --env > .lattris env= > LATTRIS_ENV > the
+    // install-aware fallback (published package = prod; worktree/source = local).
     // Must run AFTER --as (which sets LATTRIS_HOME, affecting resolveSessionHome
     // which findBinding reads for the env= field).
     const home = resolveSessionHome();
-    resolvedEnvName = envName ?? home.bindingEnv ?? process.env.LATTRIS_ENV ?? 'local';
+    resolvedEnvName =
+        envName ?? home.bindingEnv ?? process.env.LATTRIS_ENV ?? defaultEnvironmentForEntry();
     envWasExplicit =
         envName !== undefined || home.bindingEnv !== undefined || process.env.LATTRIS_ENV !== undefined;
     const forceFlag = argv.includes('--force');
@@ -6445,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);
@@ -6525,6 +6888,9 @@ export const main = async () => {
         case 'unshare':
             await unshare(cfg, argv[3], argv.slice(4));
             break;
+        case 'consent':
+            await consent(cfg, argv.slice(3));
+            break;
         case 'contact':
             await contact(cfg, argv[3], argv.slice(4));
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lattris",
-  "version": "0.1.0",
+  "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": [
@@ -11,6 +11,11 @@
   ],
   "license": "UNLICENSED",
   "homepage": "https://lattris.com",
+  "scripts": {
+    "test": "node ../../../node_modules/vitest/vitest.mjs run --config vite.config.ts",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && node ../../../node_modules/typescript/bin/tsc -p tsconfig.json",
+    "release": "node scripts/release.mjs"
+  },
   "bin": {
     "lattris": "./dist/main.js"
   },