@veilio-inc/cli 0.5.4 → 0.6.1

package/dist/cloud-commands.js

@@ -6,15 +6,22 @@
 // with no account touches nothing (FR-002). Putting these here is what keeps
 // that walk meaningful instead of something to be deleted the moment it becomes
 // inconvenient.
-import { CloudError, startDeviceLogin, exchangeDeviceCode, createMap, deleteMap, getMap, reservePlaceholders, getVault, getUserKeys, getTeamKeyWraps, listMaps, listRules, request, } from './cloud.js';
-import { checkVaultVerifier, decryptMapFromVault, deriveVaultKey, unwrapPrivateKey, unwrapTeamKey, exportTeamKey, encryptMapForVault, fromBase64, parseVaultEnvelope, importTeamKey, encryptTeamMap, decryptTeamMapWithAny, } from '@veilio-inc/engine';
-import { loadMap, loadRemote, saveMap } from './store.js';
+import { CloudError, startDeviceLogin, exchangeDeviceCode, reservePlaceholders, getUserKeys, getTeamKeyWraps, getMyTeam, listMaps, listRules, request, } from './cloud.js';
+import { unwrapTeamKey, exportTeamKey } from '@veilio-inc/engine';
 import { resolveTeamNamespace, teamLayerNote } from './team-namespace.js';
-import { readTeamUnlock, removeTeamUnlock, writeTeamUnlock, teamUnlockPath, expiryFrom, } from './team-unlock.js';
+import { removeTeamUnlock, writeTeamUnlock, teamUnlockPath, expiryFrom, } from './team-unlock.js';
 import { readCredential, removeCredential, writeCredential } from './credential.js';
 import { mergeRules, removeRules, rulesPath, writeRules } from './rules.js';
 import { EXIT_ERROR, EXIT_OK } from './commands.js';
 import { DEFAULT_INSTANCE } from './cloud.js';
+import { createCloudMap, listCloudMaps, pullCloudMap, removeCloudMap, updateCloudMap, } from './client/maps.js';
+import { refusal, renderRefusal } from './client/wording.js';
+import { bootstrapTeamKey, openOwnKeypair } from './client/team-key-bootstrap.js';
+import { vaultLock, vaultUnlock } from './client/keys.js';
+import { vaultKeyFor } from './client/vault-key.js';
+import { formatProjectsList, listTeamProjects, useProject, usedSentence, } from './client/projects.js';
+import { PROJECT_ENV, overriddenSentence, projectOverride, } from './client/project-scope.js';
+import { personalMapsKeyPath, removePersonalMapsKey } from './client/personal-maps-key.js';
 import { VERSION } from './version.js';
 /** The endpoint a sign-in is checked against. See `runLogin`. */
 const ENTITLED_PROBE = '/api/maps';
@@ -81,7 +88,7 @@ export async function runDeviceLogin(base, io) {
             const account = await accountFor(base, token, io);
             if (account === null)
                 return EXIT_ERROR;
-            writeCredential({ token, account, instance: base }, io.home);
+            writeCredential(keptProject({ token, account, instance: base }, io), io.home);
             io.stdout(`Signed in to ${base} as ${account}\n`);
             return EXIT_OK;
         }
@@ -112,6 +119,25 @@ export async function runDeviceLogin(base, io) {
         }
     }
 }
+/**
+ * A new sign-in keeps the project chosen under the previous one only when it
+ * is the same account on the same instance (spec 052, founder 2026-10-25).
+ * A project id from another account or instance means nothing here, and
+ * keeping it would point every team map call at somebody else's choice. It is
+ * dropped, and that is said, so nobody wonders why they are back to every
+ * project's maps.
+ */
+function keptProject(next, io) {
+    const prior = readCredential(io.home);
+    if (!prior?.project)
+        return next;
+    if (prior.instance === next.instance && prior.account === next.account) {
+        return { ...next, project: prior.project };
+    }
+    io.stderr(`veilio: project ${prior.project} was chosen for ${prior.account} on ${prior.instance}, so it does not ` +
+        'carry over to this sign-in. Run `veilio projects use <name>` to choose one.\n');
+    return next;
+}
 /** Who the new session belongs to, asked of the server rather than assumed. */
 async function accountFor(base, token, io) {
     try {
@@ -215,7 +241,7 @@ export async function runLogin(instance, io, opts = {}) {
     catch (err) {
         return reportLoginFailure(err, io);
     }
-    writeCredential(credential, io.home);
+    writeCredential(keptProject(credential, io), io.home);
     io.stdout(`Signed in to ${base} as ${credential.account}\n`);
     return EXIT_OK;
 }
@@ -248,6 +274,7 @@ export async function runLogout(io) {
             // branch where signing out quietly kept the more dangerous half.
             try {
                 removeTeamUnlock(io.home);
+                removePersonalMapsKey(io.home);
                 removeRules(io.home);
                 removeCredential(io.home);
             }
@@ -277,6 +304,15 @@ export async function runLogout(io) {
             `(${err instanceof Error ? err.message : String(err)}). Delete ${teamUnlockPath(io.home)} by hand.\n`);
         return EXIT_ERROR;
     }
+    // The personal-maps key, for the same reason as the team keys.
+    try {
+        removePersonalMapsKey(io.home);
+    }
+    catch (err) {
+        io.stderr(`veilio: the session was revoked, but the unlocked personal-maps key could not be removed ` +
+            `(${err instanceof Error ? err.message : String(err)}). Delete ${personalMapsKeyPath(io.home)} by hand.\n`);
+        return EXIT_ERROR;
+    }
     // The rules are the account's too, and a whitelist among them keeps names
     // readable: they go with the session rather than outliving it.
     try {
@@ -314,7 +350,16 @@ export function runWhoami(io) {
         io.stdout('Not signed in. Run `veilio login` to connect a Veilio Cloud account.\n');
         return EXIT_OK;
     }
-    io.stdout(`${credential.account} on ${credential.instance}\n`);
+    // Still no request: the variable is reported as set, not resolved - which
+    // project it names is `veilio projects`'s question, and needs the network.
+    const override = projectOverride(io.env);
+    io.stdout(`${credential.account} on ${credential.instance}` +
+        (override
+            ? `, project ${override} (from ${PROJECT_ENV})`
+            : credential.project
+                ? `, project ${credential.project}`
+                : '') +
+        '\n');
     return EXIT_OK;
 }
 /**
@@ -365,277 +410,121 @@ async function requirePassword(io, label) {
         throw new Error('this build cannot read a password interactively');
     return io.password(label);
 }
-// ─── maps: list, pull, push ──────────────────────────────────────────────────
+// ─── maps: list, pull, push, update, rm ──────────────────────────────────────
+//
+// The work is done in `client/maps.ts`, which the MCP server's map tools call
+// too (spec 052 §3). What is left here is the terminal's half: asking for the
+// passphrase, and saying what happened - results on stdout, refusals on
+// stderr, in the words of the shared table.
+/** The client's context for a terminal run: the person can be asked. */
+function clientContext(io) {
+    return {
+        home: io.home,
+        passphrase: io.password ? () => io.password('Vault passphrase: ') : undefined,
+        env: io.env,
+    };
+}
+/** A refusal on stderr, and the exit code that goes with it. */
+function refused(refusal, io) {
+    io.stderr(renderRefusal(refusal));
+    return EXIT_ERROR;
+}
+function notes(lines, io) {
+    for (const line of lines)
+        io.stderr(`veilio: ${line}\n`);
+}
 /**
  * List what the account holds.
  *
  * Prints the id, because `pull` takes one. A name would be friendlier and is
  * wrong: names are not unique, and picking "the first one that matches" is how
- * somebody pulls a different map over the one they were using.
+ * somebody pulls a different map over the one they were using. A teammate's
+ * team map is marked, because it is theirs to update or remove.
  */
 export async function runMapsList(io) {
-    const credential = readCredential(io.home);
-    if (!credential)
-        return notSignedIn(io);
-    let list;
-    try {
-        list = await listMaps(credential);
-    }
-    catch (err) {
-        return reportCloudFailure(err, io);
-    }
-    const all = [...list.personalMaps, ...list.teamMaps];
-    if (all.length === 0) {
+    const listed = await listCloudMaps(clientContext(io));
+    if (!listed.ok)
+        return refused(listed.refusal, io);
+    const { maps, project, projectFromEnv } = listed.value;
+    if (maps.length === 0) {
         io.stdout('No maps in Cloud yet. `veilio maps push <name>` uploads the local one.\n');
         return EXIT_OK;
     }
-    for (const map of all) {
-        const count = map.identifier_count === null ? '?' : String(map.identifier_count);
-        io.stdout(`${map.id}  ${map.scope.padEnd(8)} ${count.padStart(5)} symbols  ${map.name}\n`);
-    }
+    for (const map of maps) {
+        const count = map.count === null ? '?' : String(map.count);
+        const whose = map.scope === 'team' && !map.mine ? '  (a teammate’s)' : '';
+        io.stdout(`${map.id}  ${map.scope.padEnd(8)} ${count.padStart(5)} symbols  ${map.name}${whose}\n`);
+    }
+    // Said on stderr so the listing itself stays parseable: which project's team
+    // maps these are, or that no project was chosen.
+    if (project)
+        io.stderr(projectFromEnv
+            ? `veilio: team maps of project ${project} - ${PROJECT_ENV} chose it, so \`veilio projects use\` does not change it here\n`
+            : `veilio: team maps of project ${project} (\`veilio projects\` to change)\n`);
     return EXIT_OK;
 }
 /**
- * Open a team map with the team keys `veilio team unlock` stored.
- *
- * The same keys the MCP server reads, for the same reason: this machine may
- * have nobody present to type a vault passphrase, and the team key - not the
- * vault key - is what a team map is sealed under. Reports and returns null
- * when it cannot, so the caller writes nothing.
- */
-async function openTeamEnvelope(credential, mapData, io) {
-    const unlock = readTeamUnlock({ instance: credential.instance, account: credential.account }, io.home);
-    if (!unlock || unlock.keys.length === 0) {
-        io.stderr('veilio: that is a team map, and no team key is unlocked on this machine. ' +
-            'Run `veilio team unlock` first. Nothing was written.\n');
-        return null;
-    }
-    const keys = [];
-    for (const stored of unlock.keys) {
-        try {
-            keys.push({ version: stored.version, key: await importTeamKey(stored.key) });
-        }
-        catch {
-            // A damaged entry; the others may still open the map.
-            continue;
-        }
-    }
-    try {
-        return await decryptTeamMapWithAny(keys, JSON.parse(mapData));
-    }
-    catch (err) {
-        io.stderr(`veilio: that team map could not be opened with the unlocked team keys — ` +
-            `${err instanceof Error ? err.message : String(err)}. ` +
-            'If the team key was rotated since, run `veilio team unlock` again. Nothing was written.\n');
-        return null;
-    }
-}
-/**
- * Pull a map into the local store: decrypt FIRST, write second.
- *
- * The ordering is the control (Constitution IV). Writing before decrypting means
- * a wrong passphrase leaves a half-built store behind — and the store is the one
- * thing that can restore text already anonymized, so a partial write there is
- * not an inconvenience, it is unrecoverable text.
- *
- * A personal map is opened HERE. The server holds the salt and a verifier and
- * nothing else; the passphrase never leaves this machine, and there is no code
- * path in this package that could send it.
+ * Pull a map into the local store: decrypt FIRST, write second (see
+ * `pullCloudMap`). A personal map is opened HERE - the passphrase never leaves
+ * this machine, and there is no code path in this package that could send it.
  */
 export async function runMapsPull(id, mapPath, io, options = {}) {
-    const credential = readCredential(io.home);
-    if (!credential)
-        return notSignedIn(io);
-    if (!id) {
-        io.stderr('veilio: which map? Run `veilio maps list` for the ids.\n');
-        return EXIT_ERROR;
-    }
-    let remote;
-    try {
-        remote = await getMap(credential, id);
-    }
-    catch (err) {
-        return reportCloudFailure(err, io);
-    }
-    // Every map is an envelope the server cannot open: a personal map under the
-    // vault key, a team map under the team key. Which one is written on the
-    // envelope itself.
-    if (typeof remote.map_data !== 'string') {
-        io.stderr('veilio: that map is not an encrypted envelope, so it was not written.\n');
-        return EXIT_ERROR;
-    }
-    let envelope;
-    try {
-        envelope = JSON.parse(remote.map_data);
-    }
-    catch {
-        io.stderr('veilio: that map is not an encrypted envelope, so it was not written.\n');
-        return EXIT_ERROR;
-    }
-    let map;
-    if (envelope.alg === 'AES-256-GCM-TEAM') {
-        const opened = await openTeamEnvelope(credential, remote.map_data, io);
-        if (!opened)
-            return EXIT_ERROR;
-        map = opened;
-    }
-    else {
-        let vault;
-        try {
-            vault = await getVault(credential);
-        }
-        catch (err) {
-            return reportCloudFailure(err, io);
-        }
-        if (!vault.initialized) {
-            // Stated plainly rather than surfaced as a decryption failure. There is
-            // nothing to try a passphrase against, and inviting one would be asking
-            // somebody to guess at a lock that does not exist.
-            io.stderr('veilio: this account has no vault, so there is no key for that map. ' +
-                'Create one in the web app first — it is the passphrase your maps are encrypted under.\n');
-            return EXIT_ERROR;
-        }
-        const passphrase = io.password ? await io.password('Vault passphrase: ') : '';
-        if (passphrase === '') {
-            io.stderr('veilio: no passphrase given\n');
-            return EXIT_ERROR;
-        }
-        const key = await deriveVaultKey(passphrase, fromBase64(vault.salt), vault.kdf ? { name: 'PBKDF2-SHA256', iterations: vault.kdf.iterations } : undefined);
-        // The verifier answers "is this the right passphrase" before anything is
-        // decrypted, so a wrong one is named as a wrong passphrase rather than
-        // surfacing as an authentication-tag failure that reads like corruption.
-        if (!(await checkVaultVerifier(key, vault.verifier))) {
-            io.stderr('veilio: that vault passphrase is not right. Nothing was written.\n');
-            return EXIT_ERROR;
-        }
-        try {
-            map = await decryptMapFromVault(key, parseVaultEnvelope(remote.map_data));
-        }
-        catch (err) {
-            io.stderr(`veilio: that map could not be opened — ${err instanceof Error ? err.message : String(err)}. ` +
-                'Nothing was written.\n');
-            return EXIT_ERROR;
-        }
-    }
-    // Only now is anything touched on disk.
-    const existing = loadRemote(mapPath);
-    const local = loadMap(mapPath);
-    const hasLocal = Object.keys(local).length > 0;
-    const diverged = hasLocal &&
-        existing !== undefined &&
-        existing.id === remote.id &&
-        existing.updatedAt !== remote.updated_at &&
-        JSON.stringify(local) !== JSON.stringify(map);
-    if (diverged && options.force !== true) {
-        // Reported, not resolved. Overwriting either side silently loses entries
-        // that some text out there still depends on.
-        io.stderr(`veilio: this map changed in Cloud (${existing.updatedAt} → ${remote.updated_at}) and ` +
-            'locally since it was pulled. Neither copy has been touched.\n' +
-            `Pass --force to overwrite the local copy, or export it first with \`veilio map --json\`.\n`);
-        return EXIT_ERROR;
-    }
-    // Whether or not the Cloud copy changed: a local entry the pulled map lacks,
-    // or gives another name, is a placeholder some masked text still depends on
-    // (staging walk, 2026-10-01 - a scrub after a pull was lost on the next pull).
-    const dropped = Object.keys(local).filter((p) => map[p] !== local[p]);
-    if (dropped.length > 0 && options.force !== true) {
-        const shown = dropped.slice(0, 5).join(', ') + (dropped.length > 5 ? ` and ${dropped.length - 5} more` : '');
-        io.stderr(`veilio: pulling "${remote.name}" would drop ${dropped.length} placeholder(s) this project's map has: ${shown}. ` +
-            'Nothing was written.\n' +
-            `Push this map first (\`veilio maps push\`), pass --force to replace it, or export it with \`veilio map --json\`.\n`);
-        return EXIT_ERROR;
+    const pulled = await pullCloudMap(clientContext(io), id, { mapPath, force: options.force });
+    if (!pulled.ok)
+        return refused(pulled.refusal, io);
+    const { name, count, path } = pulled.value;
+    io.stdout(`Pulled "${name}" (${count} symbols) into ${path}\n`);
+    return EXIT_OK;
+}
+/** Upload the local map, personal or the team's. Same endpoint, same quotas,
+ *  same validation as the web app. */
+export async function runMapsPush(name, mapPath, io, toTeam = false) {
+    const created = await createCloudMap(clientContext(io), {
+        name,
+        scope: toTeam ? 'team' : 'personal',
+        mapPath,
+    });
+    if (!created.ok)
+        return refused(created.refusal, io);
+    const c = created.value;
+    notes(c.notes, io);
+    if (c.scope === 'personal') {
+        io.stdout(`Pushed ${c.count} symbols to Cloud as ${c.id}\n`);
+        return EXIT_OK;
     }
-    const now = new Date().toISOString();
-    saveMap(mapPath, map, {
-        force: true,
-        remote: { id: remote.id, updatedAt: remote.updated_at, pulledAt: now },
+    const disputed = c.disputed ?? 0;
+    io.stdout(`Published "${c.name}" (${c.count} symbols) to the team as ${c.id}\n` +
+        `The team's shared set now holds ${c.teamTotal} identifiers` +
+        (disputed > 0
+            ? `, ${disputed} of which ${disputed === 1 ? 'is' : 'are'} disputed and will not restore\n`
+            : ', none disputed\n'));
+    return EXIT_OK;
+}
+/** Replace a Cloud map's entries with the local map's, in place (spec 052). */
+export async function runMapsUpdate(id, mapPath, io, options = {}) {
+    const updated = await updateCloudMap(clientContext(io), id, {
+        mapPath,
+        allowDrop: options.allowDrop,
     });
-    io.stdout(`Pulled "${remote.name}" (${Object.keys(map).length} symbols) into ${mapPath}\n`);
+    if (!updated.ok)
+        return refused(updated.refusal, io);
+    const u = updated.value;
+    notes(u.notes, io);
+    io.stdout(`Updated "${u.name}" (${u.id}) in place: ${u.count} symbols` +
+        (u.dropped > 0 ? `, ${u.dropped} dropped as asked` : '') +
+        `${u.scope === 'team' ? ', sealed with the team key' : ''}\n`);
     return EXIT_OK;
 }
 /**
- * Placeholders the local map and the team's namespace use for DIFFERENT names.
- *
- * Publishing one of these creates a DISPUTED placeholder, and
- * `restoreLayers.disputedIn` then refuses to restore it for every member of
- * the team until somebody deletes a map. One person's push, a cost paid by
- * everyone, and nothing errors at the time - so it is checked before anything
- * is sealed rather than reported afterwards.
- *
- * An identifier the team holds under a DIFFERENT placeholder is an alias, not
- * a conflict: both still restore (spec 017), so those pass.
- *
- * A map anonymized with `reservedAnonymizeOverTeam` cannot reach this, because
- * its numbers came out of the team's own allocation. This is for maps that
- * predate it - numbered locally, possibly before this account joined a team.
+ * Remove a map from Cloud. Renaming and removing are allowed while a key
+ * rotation is owed, because neither stores anything under the key.
  */
-export function conflictsWithTeam(local, teamNamespace) {
-    const out = [];
-    for (const [placeholder, mine] of Object.entries(local)) {
-        const theirs = teamNamespace[placeholder];
-        if (theirs !== undefined && theirs !== mine)
-            out.push({ placeholder, mine, theirs });
-    }
-    return out;
-}
-/** Upload the local map. Same endpoint, same quotas, same validation. */
-export async function runMapsPush(name, mapPath, io, toTeam = false) {
-    const credential = readCredential(io.home);
-    if (!credential)
-        return notSignedIn(io);
-    const map = loadMap(mapPath);
-    if (Object.keys(map).length === 0) {
-        io.stderr(`veilio: there is no local map at ${mapPath} to push.\n`);
-        return EXIT_ERROR;
-    }
-    if (toTeam)
-        return pushToTeam(name, mapPath, map, credential, io);
-    let vault;
-    try {
-        vault = await getVault(credential);
-    }
-    catch (err) {
-        return reportCloudFailure(err, io);
-    }
-    if (!vault.initialized) {
-        io.stderr('veilio: this account has no vault, so there is no key to encrypt with. ' +
-            'Create one in the web app first.\n');
-        return EXIT_ERROR;
-    }
-    const passphrase = io.password ? await io.password('Vault passphrase: ') : '';
-    if (passphrase === '') {
-        io.stderr('veilio: no passphrase given\n');
-        return EXIT_ERROR;
-    }
-    const key = await deriveVaultKey(passphrase, fromBase64(vault.salt), vault.kdf ? { name: 'PBKDF2-SHA256', iterations: vault.kdf.iterations } : undefined);
-    if (!(await checkVaultVerifier(key, vault.verifier))) {
-        // Caught before anything is uploaded. Pushing under the wrong key would
-        // store a map the account can never open again.
-        io.stderr('veilio: that vault passphrase is not right. Nothing was uploaded.\n');
-        return EXIT_ERROR;
-    }
-    const envelope = await encryptMapForVault(key, map);
-    let created;
-    try {
-        created = await createMap(credential, {
-            name: name ?? 'from the terminal',
-            map_data: JSON.stringify(envelope),
-            identifier_count: Object.keys(map).length,
-            scope: 'personal',
-        });
-    }
-    catch (err) {
-        return reportCloudFailure(err, io);
-    }
-    saveMap(mapPath, map, {
-        force: true,
-        remote: {
-            id: created.id,
-            updatedAt: new Date().toISOString(),
-            pushedAt: new Date().toISOString(),
-        },
-    });
-    io.stdout(`Pushed ${Object.keys(map).length} symbols to Cloud as ${created.id}\n`);
+export async function runMapsRm(id, io) {
+    const removed = await removeCloudMap(clientContext(io), id);
+    if (!removed.ok)
+        return refused(removed.refusal, io);
+    const { name } = removed.value;
+    io.stdout(name ? `Removed "${name}" (${removed.value.id})\n` : `Removed ${removed.value.id}\n`);
     return EXIT_OK;
 }
 function notSignedIn(io) {
@@ -710,43 +599,57 @@ export async function runTeamUnlock(io, days) {
             return EXIT_ERROR;
         }
         const mine = await getUserKeys(credential);
-        if (!mine.initialized) {
-            io.stderr('veilio: this account has no keypair yet. Open the web app once — that is where a ' +
-                'keypair is created and where a teammate grants you the team key.\n');
-            return EXIT_ERROR;
-        }
-        const { wraps } = await getTeamKeyWraps(credential, teamId);
+        // No keypair: there is nothing to unwrap a team key with, nor to wrap a
+        // first one to. The web app makes it on the first vault unlock.
+        if (!mine.initialized)
+            return refused(refusal('keys_not_set_up'), io);
+        let { wraps } = await getTeamKeyWraps(credential, teamId);
+        const derived = await vaultKeyFor(credential, clientContext(io).passphrase);
+        if (!derived.ok)
+            return refused(derived.refusal, io);
+        const vaultKey = derived.value;
+        // The keypair, and its public half computed from the private one: a
+        // public key the server hands back is never trusted on its own word, not
+        // for a wrap's context and above all not for wrapping a key to (security
+        // review). A server answer that differs stops everything.
+        const own = await openOwnKeypair(vaultKey, mine.privateKeyEncrypted, mine.publicKey);
+        if (!own.ok)
+            return refused(refusal('own_public_key_mismatch'), io);
+        const privateKey = own.privateKey;
+        const myPublicKey = own.publicKey;
+        // None held here: the team may have no key at all - a team of one always
+        // starts that way - so try to mint its first one, as the web app does.
+        // The server says whether that is a bootstrap; a refusal means a key
+        // exists (or this member may not start one), never a reason to mint again.
+        let minted = null;
         if (wraps.length === 0) {
-            io.stderr('veilio: no teammate has granted you the team key yet. Ask someone already in the ' +
-                'team to open the web app, which is what performs the grant.\n');
-            return EXIT_ERROR;
-        }
-        const vault = await getVault(credential);
-        if (!vault.initialized) {
-            io.stderr('veilio: this account has no vault, so there is no key to unwrap anything with. ' +
-                'Create one in the web app first.\n');
-            return EXIT_ERROR;
-        }
-        const passphrase = io.password ? await io.password('Vault passphrase: ') : '';
-        if (passphrase === '') {
-            io.stderr('veilio: no passphrase given\n');
-            return EXIT_ERROR;
-        }
-        const vaultKey = await deriveVaultKey(passphrase, fromBase64(vault.salt), vault.kdf ? { name: 'PBKDF2-SHA256', iterations: vault.kdf.iterations } : undefined);
-        // Named as a wrong passphrase here rather than surfacing later as an
-        // authentication-tag failure that reads like corruption.
-        if (!(await checkVaultVerifier(vaultKey, vault.verifier))) {
-            io.stderr('veilio: that vault passphrase is not right. Nothing was written.\n');
-            return EXIT_ERROR;
+            const tried = await bootstrapTeamKey(credential, teamId, {
+                privateKey,
+                publicKey: myPublicKey,
+            });
+            if (tried.status === 'readback_mismatch')
+                return refused(refusal('team_key_readback_mismatch'), io);
+            if (tried.status === 'refused') {
+                if (tried.reason && /owner or an admin/i.test(tried.reason))
+                    return refused(refusal('team_key_not_startable', { detail: tried.reason }), io);
+                // A team of one has nobody to ask, and must not be told to.
+                if (await isTeamOfOne(credential)) {
+                    return refused(refusal('team_key_solo_unavailable', {
+                        detail: tried.reason ?? 'the server did not accept a first key',
+                    }), io);
+                }
+                return refused(refusal('team_key_waiting'), io);
+            }
+            minted = { version: tried.version };
+            ({ wraps } = await getTeamKeyWraps(credential, teamId));
         }
-        const privateKey = await unwrapPrivateKey(vaultKey, mine.privateKeyEncrypted);
         const keys = [];
         for (const wrap of wraps) {
             try {
                 const teamKey = await unwrapTeamKey(wrap.wrapped_key, privateKey, {
                     teamId,
                     version: wrap.version,
-                    myPublicKey: mine.publicKey,
+                    myPublicKey,
                 });
                 keys.push({ version: wrap.version, key: await exportTeamKey(teamKey) });
             }
@@ -759,7 +662,7 @@ export async function runTeamUnlock(io, days) {
         }
         if (keys.length === 0) {
             io.stderr('veilio: none of the team key wraps held for this account could be opened. ' +
-                'Ask a teammate to grant access again from the web app.\n');
+                'Grant it again from the team page in the web app, then run `veilio team unlock` again.\n');
             return EXIT_ERROR;
         }
         const now = new Date();
@@ -773,6 +676,10 @@ export async function runTeamUnlock(io, days) {
             keys,
         }, io.home);
         const versions = keys.map((k) => `v${k.version}`).join(', ');
+        if (minted) {
+            io.stdout(`Set up the team key (v${minted.version}): the team had none, so this account made its first one ` +
+                'and holds it. It was never sent anywhere unwrapped.\n');
+        }
         io.stdout(`Unlocked ${keys.length === 1 ? 'the team key' : 'team keys'} (${versions}) until ` +
             `${expiresAt}.\n` +
             `Stored in ${teamUnlockPath(io.home)}, readable only by you. ` +
@@ -783,6 +690,17 @@ export async function runTeamUnlock(io, days) {
         return reportCloudFailure(err, io);
     }
 }
+/** Whether this account is its team's only member. Unknown counts as not:
+ *  the general wording is still true for a team of one, just less helpful. */
+async function isTeamOfOne(credential) {
+    try {
+        const members = (await getMyTeam(credential)).team?.members;
+        return Array.isArray(members) && members.length === 1;
+    }
+    catch {
+        return false;
+    }
+}
 /** Remove the unlocked team keys. */
 export function runTeamLock(io) {
     try {
@@ -800,16 +718,84 @@ export function runTeamLock(io) {
     io.stdout('Team keys locked.\n');
     return EXIT_OK;
 }
+// ─── projects ────────────────────────────────────────────────────────────────
+/** The team's projects, the one in use marked with `*`. */
+export async function runProjectsList(io) {
+    const listed = await listTeamProjects(clientContext(io));
+    if (!listed.ok)
+        return refused(listed.refusal, io);
+    const { lines, note } = formatProjectsList(listed.value, { surface: 'cli' });
+    for (const line of lines)
+        io.stdout(`${line}\n`);
+    if (note)
+        io.stderr(`veilio: ${note}\n`);
+    return EXIT_OK;
+}
+/** Choose the project this sign-in works in. */
+export async function runProjectsUse(ref, io) {
+    const used = await useProject(clientContext(io), ref);
+    if (!used.ok)
+        return refused(used.refusal, io);
+    io.stdout(`${usedSentence(used.value, { surface: 'cli' })}\n`);
+    if (used.value.overriddenBy !== null)
+        io.stderr(`veilio: ${overriddenSentence(used.value, 'shell')}\n`);
+    return EXIT_OK;
+}
+// ─── vault: unlock, lock ─────────────────────────────────────────────────────
+/**
+ * Unlock the personal-maps key for processes that cannot ask for a passphrase
+ * (spec 052 FR-011). See `client/keys.ts` for what is kept: that key, and
+ * nothing else the vault protects.
+ */
+export async function runVaultUnlock(io, days) {
+    const unlocked = await vaultUnlock(clientContext(io), { days });
+    if (!unlocked.ok)
+        return refused(unlocked.refusal, io);
+    const u = unlocked.value;
+    io.stdout(`${u.created ? 'Created and unlocked' : 'Unlocked'} the personal-maps key until ${u.expiresAt}.\n` +
+        `Stored in ${u.path}, readable only by you. It opens your personal maps and nothing else; ` +
+        'the vault passphrase and key were not kept. Run `veilio vault lock` to remove it.\n' +
+        (u.resealed > 0
+            ? `Re-sealed ${u.resealed} personal map${u.resealed === 1 ? '' : 's'} under it, so the MCP server can open ${u.resealed === 1 ? 'it' : 'them'}.\n`
+            : ''));
+    if (u.failed.length > 0) {
+        io.stderr(`veilio: ${u.failed.length} personal map${u.failed.length === 1 ? '' : 's'} could not be re-sealed and ` +
+            `${u.failed.length === 1 ? 'is' : 'are'} still under the vault key, which the MCP server cannot open:\n` +
+            u.failed.map((f) => `  "${f.name}" (${f.id}): ${f.reason}\n`).join('') +
+            'Run `veilio vault unlock` again to retry them; the key itself is unlocked.\n');
+        return EXIT_ERROR;
+    }
+    return EXIT_OK;
+}
+/** Remove the personal-maps key from this machine. */
+export function runVaultLock(io) {
+    try {
+        if (!vaultLock(clientContext(io))) {
+            io.stdout('No personal-maps key was unlocked.\n');
+            return EXIT_OK;
+        }
+    }
+    catch (err) {
+        io.stderr(`veilio: the personal-maps key could not be removed ` +
+            `(${err instanceof Error ? err.message : String(err)}). ` +
+            `Delete ${personalMapsKeyPath(io.home)} by hand.\n`);
+        return EXIT_ERROR;
+    }
+    io.stdout('Personal-maps key locked.\n');
+    return EXIT_OK;
+}
 // ─── restore: the team layer ────────────────────────────────────────────────
 /**
  * The team's maps for `veilio restore` (spec 028), handed to the local command
  * as a callback so that command stays unlinked from the network. Signed out:
  * no request, no layer - a local restore, as before.
  */
-export async function teamLayerFor(home, missing) {
+export async function teamLayerFor(home, missing, env) {
     // Signed out, the resolver answers 'local' without a request. At most 5 s: a
     // hung instance must not stall a `... | veilio restore > file` pipeline.
-    const found = await resolveTeamNamespace(home, { deadlineMs: RESTORE_CLOUD_WAIT_MS });
+    const found = await resolveTeamNamespace(home, { deadlineMs: RESTORE_CLOUD_WAIT_MS, env });
+    if (found.status === 'refused')
+        return { team: null, note: null, refused: renderRefusal(found.refusal) };
     if (found.status === 'team' && found.conflictDetection)
         return { team: found.analysis, note: null };
     return { team: null, note: teamLayerNote(found, missing) };
@@ -817,8 +803,10 @@ export async function teamLayerFor(home, missing) {
 const RESTORE_CLOUD_WAIT_MS = 5000;
 /** What `veilio scrub` numbers from (spec 030): the team's namespace, or this
  *  project's map with the reason. Signed out or in no team: no request, no note. */
-export async function teamNamespaceForScrub(home) {
-    const found = await resolveTeamNamespace(home, { deadlineMs: RESTORE_CLOUD_WAIT_MS });
+export async function teamNamespaceForScrub(home, env) {
+    const found = await resolveTeamNamespace(home, { deadlineMs: RESTORE_CLOUD_WAIT_MS, env });
+    if (found.status === 'refused')
+        return { team: null, note: null, refused: renderRefusal(found.refusal) };
     if (found.status === 'team') {
         const credential = readCredential(home);
         const teamId = found.teamId;
@@ -853,179 +841,7 @@ export async function teamNamespaceForScrub(home) {
         };
     return { team: null, note: null };
 }
-/**
- * Publish the local map as the TEAM's, from the terminal (spec 011 US1).
- *
- * Seals what is on disk AS IT IS NUMBERED. It does not renumber: by the time
- * anybody runs this, the local map's placeholders are already present in the
- * files they masked, and renumbering here would publish a map that disagrees
- * with every one of them - while `saveMap(force)` rewrote the local map too,
- * breaking local restore as well. Numbers come out of the team's allocation at
- * ANONYMIZE time (`reservedAnonymizeOverTeam`), which is where the text and
- * the numbers can still change together.
- *
- * So the ordering here is: establish that publishing is safe, THEN seal, THEN
- * upload. Every refusal happens before the first byte leaves (FR-007).
- */
-async function pushToTeam(name, mapPath, map, credential, io) {
-    // 1. The key. Read from the unlock file, never derived here: publishing
-    //    needs the TEAM key, and nobody's passphrase can produce it.
-    const unlock = readTeamUnlock({ instance: credential.instance, account: credential.account }, io.home);
-    if (!unlock || unlock.keys.length === 0) {
-        io.stderr('veilio: no team key is unlocked on this machine, so this map cannot be sealed for ' +
-            'the team. Run `veilio team unlock` first. Nothing was uploaded.\n');
-        return EXIT_ERROR;
-    }
-    // Newest first: a team mid-rotation holds two, and new content belongs under
-    // the newer one. The version is declared on upload so the server can refuse
-    // a write under a key a departed member knew (spec 014).
-    const newest = [...unlock.keys].sort((a, b) => b.version - a.version)[0];
-    let teamKey;
-    try {
-        teamKey = await importTeamKey(newest.key);
-    }
-    catch (err) {
-        io.stderr(`veilio: the unlocked team key could not be read (${err instanceof Error ? err.message : String(err)}). ` +
-            'Run `veilio team unlock` again. Nothing was uploaded.\n');
-        return EXIT_ERROR;
-    }
-    // 2. The team's namespace, for the conflict check and for the report. A
-    //    failure here is NOT fallback-to-local: publishing blind is what the
-    //    check exists to prevent.
-    const found = await resolveTeamNamespace(io.home);
-    if (found.status === 'local') {
-        io.stderr('veilio: this account is not in a team, so there is no shared map to publish to. ' +
-            'Nothing was uploaded.\n');
-        return EXIT_ERROR;
-    }
-    if (found.status === 'locked') {
-        io.stderr('veilio: the team key on this machine does not match this team. ' +
-            'Run `veilio team unlock` again. Nothing was uploaded.\n');
-        return EXIT_ERROR;
-    }
-    if (found.status === 'unavailable') {
-        io.stderr(`veilio: could not read the team's maps (${found.reason}), so whether this map ` +
-            'conflicts with the team cannot be known. Nothing was uploaded.\n');
-        return EXIT_ERROR;
-    }
-    // 3. The conflict check. Before sealing, so a refusal costs nothing.
-    const clashes = conflictsWithTeam(map, found.analysis.namespace);
-    if (clashes.length > 0) {
-        io.stderr(`veilio: ${clashes.length} placeholder${clashes.length === 1 ? '' : 's'} in this map already ` +
-            `mean something else to the team. Publishing would leave ${clashes.length === 1 ? 'it' : 'them'} ` +
-            `unrestorable for every member, so nothing was uploaded:\n`);
-        for (const { placeholder, mine, theirs } of clashes.slice(0, 10)) {
-            io.stderr(`  ${placeholder}: this map says ${mine}, the team says ${theirs}\n`);
-        }
-        if (clashes.length > 10)
-            io.stderr(`  … and ${clashes.length - 10} more\n`);
-        io.stderr('Re-run `veilio scrub --team` to number this project out of the team\u2019s own ' +
-            'allocation, then push the result.\n');
-        return EXIT_ERROR;
-    }
-    // 4. Seal and upload. Nothing above this line has sent anything.
-    const envelope = await encryptTeamMap(teamKey, map);
-    let created;
-    try {
-        created = await createMap(credential, {
-            name: name ?? 'from the terminal',
-            map_data: JSON.stringify(envelope),
-            identifier_count: Object.keys(map).length,
-            scope: 'team',
-            key_version: newest.version,
-        });
-    }
-    catch (err) {
-        return reportTeamWriteFailure(err, io);
-    }
-    // The local map is NOT rewritten with a remote id: a team map is not this
-    // project's copy of anything, and recording it as `remote` would make the
-    // next `maps pull` treat the team's map as this project's own.
-    // A union, not a sum: a name already in the team that this map also holds is
-    // ONE identifier in the shared set, and the pre-flight above has just checked
-    // that every such overlap agrees. Adding the two counts said "about" three
-    // for two (spec 011 T030).
-    const total = new Set([...Object.keys(found.analysis.namespace), ...Object.keys(map)]).size;
-    const disputed = Object.keys(found.analysis.conflicts).length;
-    // The name the person chose, beside the id they would type to remove it (T014).
-    const label = name ?? 'from the terminal';
-    io.stdout(`Published "${label}" (${Object.keys(map).length} symbols) to the team as ${created.id}\n` +
-        `The team's shared set now holds ${total} identifiers` +
-        (disputed > 0
-            ? `, ${disputed} of which ${disputed === 1 ? 'is' : 'are'} disputed and will not restore\n`
-            : ', none disputed\n'));
-    return EXIT_OK;
-}
-/**
- * Remove a map from Cloud.
- *
- * Who may remove a team map is the server's decision and is not second-guessed
- * here - this says what each refusal means and changes nothing locally either
- * way. Renaming and removing are allowed while a key rotation is owed, because
- * neither stores anything under the key.
- */
-export async function runMapsRm(id, io) {
-    const credential = readCredential(io.home);
-    if (!credential)
-        return notSignedIn(io);
-    if (!id) {
-        io.stderr('veilio: which map? Run `veilio maps list` for the ids.\n');
-        return EXIT_ERROR;
-    }
-    // The name, read first, so the confirmation says WHICH map went: an id is
-    // what a person types, the name is what they recognise (spec 011 T032). A
-    // failed read never stops the removal - it only means the id is all there is
-    // to report.
-    let label;
-    try {
-        label = (await getMap(credential, id)).name || null;
-    }
-    catch {
-        label = null;
-    }
-    try {
-        await deleteMap(credential, id);
-    }
-    catch (err) {
-        if (err instanceof CloudError && err.status === 404) {
-            io.stderr(`veilio: there is no map ${id} on this account.\n`);
-            return EXIT_ERROR;
-        }
-        if (err instanceof CloudError && err.status === 403) {
-            io.stderr(`veilio: ${id} belongs to someone else on your team, so it is theirs to remove.\n`);
-            return EXIT_ERROR;
-        }
-        return reportCloudFailure(err, io);
-    }
-    io.stdout(label ? `Removed "${label}" (${id})\n` : `Removed ${id}\n`);
-    return EXIT_OK;
-}
-/**
- * A failed team-map write, said in terms of what happened and who can fix it.
- *
- * The person reading this is often not the person who can clear it: a rotation
- * is owed by whoever holds the current key, not by whoever happened to push.
- * An unexplained refusal in a terminal reads as a broken tool (spec 011 US3).
- */
-function reportTeamWriteFailure(err, io) {
-    if (err instanceof CloudError && err.status === 409) {
-        io.stderr('veilio: a teammate left while holding the team key, so no new team content may be ' +
-            'written until the key is changed. A member who holds the current key has to do ' +
-            'that — it cannot be done from here. Nothing was uploaded.\n');
-        return EXIT_ERROR;
-    }
-    if (err instanceof CloudError && err.status === 413) {
-        io.stderr('veilio: this map is too large for Cloud to accept, so nothing was stored. ' +
-            'Split it, or remove entries you no longer need.\n');
-        return EXIT_ERROR;
-    }
-    if (err instanceof CloudError && err.kind === 'forbidden' && /limit/i.test(err.message)) {
-        // The ceiling is an abuse limit, not a plan feature. Saying "upgrade" here
-        // would take money for a change that does nothing.
-        io.stderr(`veilio: ${err.message}\nThis ceiling is the same on every paid plan, so upgrading ` +
-            'will not raise it. Nothing was uploaded.\n');
-        return EXIT_ERROR;
-    }
-    return reportCloudFailure(err, io);
-}
+/** Kept importable from here: tests and callers written before spec 052 moved
+ *  it into the shared client. */
+export { conflictsWithTeam } from './client/maps.js';
 //# sourceMappingURL=cloud-commands.js.map