lattris 0.1.0 → 0.1.2

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,4 @@
+{
+  "commit": "e813390b3f7e3c6eed78e607fed6125a10c9cf2c",
+  "builtAt": "2026-09-12T04:33:05.921Z"
+}

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',
@@ -1201,11 +1215,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 +1229,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
@@ -2343,7 +2356,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
@@ -2580,7 +2595,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 +2629,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
@@ -2641,6 +2655,8 @@ const getMemories = async (cfg, flags) => {
             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`);
     }
@@ -2660,7 +2676,7 @@ export const GET_HELP = [
     '  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 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 memory <id-or-prefix> --revision <n>      one revision, as history kept it',
     '  lattris get history <id-or-prefix> [--limit <n>] [--before <operation-id>]',
@@ -2678,6 +2694,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',
+    '  --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',
@@ -2792,6 +2810,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 +2891,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;
@@ -2936,6 +2964,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 +2977,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 +2997,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 +4199,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 +4214,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 +4248,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 +4276,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 +4304,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 +4383,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 +4399,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 +4450,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 +4463,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 +4478,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 +4491,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 +4533,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 +4546,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 +4559,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 +4611,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 +6047,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 +6055,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 +6579,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');
@@ -6525,6 +6686,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.2",
   "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"
   },