faces-cli 1.8.0 → 1.8.2

package/dist/commands/catalog/doctor.js

@@ -5,7 +5,7 @@ import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { loadConfig } from '../../config.js';
 import { CatalogService, CATALOG_DIR } from '../../catalog.js';
-import { TeamCatalogService } from '../../team-catalog.js';
+import { TeamCatalogService, TEAMS_DIR, slugifyTeamName } from '../../team-catalog.js';
 import { resolveEndpoint, MESSAGES_ENDPOINT, RESPONSES_ENDPOINT } from '../../routing.js';
 export default class CatalogDoctor extends BaseCommand {
     static description = 'Diagnose and repair the local face and team catalog';
@@ -106,17 +106,33 @@ export default class CatalogDoctor extends BaseCommand {
         }
         // Check teams
         let remoteTeams = [];
+        // Every team the account has, personal included. The sync pass skips the
+        // personal Guild, but orphan detection must not: a local copy of a team
+        // that was filtered out of the comparison looks deleted when it is not.
+        let allRemoteSlugs = new Set();
+        // Whether the server actually answered. Without this an unreachable API
+        // looks exactly like an account with no teams, and --fix would delete the
+        // entire local team catalog on a timeout.
+        let teamsFetched = false;
         const localTeamNames = new Set(teamCatalog.listTeams());
         try {
             const resp = await client.get('/v1/me/teams');
-            remoteTeams = (resp.data ?? resp)
-                .filter(t => t.kind !== 'personal');
+            const all = resp.data ?? resp;
+            allRemoteSlugs = new Set(all.map(t => slugifyTeamName(String(t.name))));
+            remoteTeams = all.filter(t => t.kind !== 'personal');
+            teamsFetched = true;
         }
-        catch { /* proceed */ }
-        const missingTeams = remoteTeams.filter(t => {
-            const slug = String(t.name).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-            return !localTeamNames.has(slug);
-        });
+        catch { /* proceed; teamsFetched stays false */ }
+        const missingTeams = remoteTeams.filter(t => !localTeamNames.has(slugifyTeamName(String(t.name))));
+        // The mirror of the orphaned-face pass: present locally, gone from the server.
+        const orphanedTeams = teamsFetched
+            ? [...localTeamNames].filter(name => !allRemoteSlugs.has(name))
+            : [];
+        // A deleted team's protocol survives only in TEAM.md, so anything with a
+        // body is reported rather than removed. Frontmatter alone is reproducible
+        // and safe to drop.
+        const removableTeams = orphanedTeams.filter(name => !teamCatalog.hasLocalContent(name));
+        const keptTeams = orphanedTeams.filter(name => teamCatalog.hasLocalContent(name));
         const doFix = flags.fix || flags.generate;
         if (!doFix) {
             const issues = [];
@@ -130,6 +146,11 @@ export default class CatalogDoctor extends BaseCommand {
                 issues.push(`${noDescription.length} face(s) without a description`);
             if (missingTeams.length > 0)
                 issues.push(`${missingTeams.length} team(s) missing from local catalog`);
+            if (removableTeams.length > 0)
+                issues.push(`${removableTeams.length} local team(s) no longer on the server`);
+            if (keptTeams.length > 0) {
+                issues.push(`${keptTeams.length} local team(s) no longer on the server with local content: ${keptTeams.join(', ')}`);
+            }
             if (issues.length === 0) {
                 this.log('Catalog is healthy.');
             }
@@ -142,7 +163,15 @@ export default class CatalogDoctor extends BaseCommand {
                     this.log('Run faces catalog:doctor --generate to also create missing descriptions');
                 }
             }
-            return { missing: missing.length, stale: stale.length, orphaned: orphaned.length, noDescription: noDescription.length, missingTeams: missingTeams.length };
+            return {
+                missing: missing.length,
+                stale: stale.length,
+                orphaned: orphaned.length,
+                noDescription: noDescription.length,
+                missingTeams: missingTeams.length,
+                orphanedTeams: removableTeams.length,
+                orphanedTeamsKept: keptTeams,
+            };
         }
         // Fix mode: rebuild face entries
         let fixed = 0;
@@ -172,7 +201,7 @@ export default class CatalogDoctor extends BaseCommand {
         }
         for (const team of remoteTeams) {
             const teamId = team.id;
-            const slug = String(team.name).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+            const slug = slugifyTeamName(String(team.name));
             // Fetch members and tags
             let memberAliases = [];
             try {
@@ -198,7 +227,22 @@ export default class CatalogDoctor extends BaseCommand {
             }, team.protocol ?? undefined);
             teamsSynced++;
         }
-        this.log(`Fixed ${fixed} face(s), removed ${removed} orphan(s), synced ${teamsSynced} team(s).`);
+        // Remove orphaned teams, the mirror of the orphaned-face removal above.
+        let teamsRemoved = 0;
+        for (const name of removableTeams) {
+            teamCatalog.deleteTeam(name);
+            teamsRemoved++;
+        }
+        this.log(`Fixed ${fixed} face(s), removed ${removed} orphaned face(s) and ${teamsRemoved} orphaned team(s), ` +
+            `synced ${teamsSynced} team(s).`);
+        // Never let a partial clean-up read as a complete one.
+        for (const name of keptTeams) {
+            this.log(`Kept '${name}': the team is gone from the server but TEAM.md has content that exists nowhere else. ` +
+                `Remove it yourself with: rm -rf ${path.join(TEAMS_DIR, name)}`);
+        }
+        if (!teamsFetched) {
+            this.log('Could not reach the teams API, so local teams were not checked against the server.');
+        }
         // Generate mode: create missing descriptions
         if (flags.generate && noDescription.length > 0) {
             const cfg = loadConfig();
@@ -262,6 +306,13 @@ export default class CatalogDoctor extends BaseCommand {
             this.log(`Generated ${generated} description(s).`);
         }
         catalog.rebuildIndex();
-        return { fixed, removed, teamsSynced, generated: flags.generate ? noDescription.length : 0 };
+        return {
+            fixed,
+            removed,
+            teamsRemoved,
+            teamsKept: keptTeams,
+            teamsSynced,
+            generated: flags.generate ? noDescription.length : 0,
+        };
     }
 }

package/dist/commands/face/get.js

@@ -1,9 +1,10 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
-import { renameFaceFields } from '../../utils.js';
+import { renameFaceFields, resolveFace } from '../../utils.js';
 export default class FaceGet extends BaseCommand {
-    static description = 'Get details for a face by alias';
+    static description = 'Get details for a face, by alias or owner:alias. A published or shared face is reachable under the ' +
+        'same owner:alias address chat uses; it is shown with a note that you do not own it.';
     static flags = {
         ...BaseCommand.baseFlags,
         include: Flags.string({ description: 'Include extra fields: tags, teams (comma-separated)' }),
@@ -20,16 +21,21 @@ export default class FaceGet extends BaseCommand {
         if (flags.include)
             for (const v of flags.include.split(','))
                 includes.add(v.trim());
-        const path = `/v1/faces/${args.face_id}?include=${[...includes].join(',')}`;
-        let data;
+        let resolved;
         try {
-            data = await client.get(path);
+            resolved = await resolveFace(client, args.face_id, [...includes].join(','));
         }
         catch (err) {
-            if (err instanceof FacesAPIError)
+            if (err instanceof FacesAPIError) {
+                if (err.statusCode === 404) {
+                    this.error(`No face '${args.face_id}'. If it belongs to another account, name it as owner:alias, ` +
+                        'the same address chat uses. Find it with: faces face:list --public');
+                }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
             throw err;
         }
+        const data = resolved.face;
         const face = data;
         renameFaceFields(face);
         const f = face;
@@ -38,6 +44,11 @@ export default class FaceGet extends BaseCommand {
             this.log(`uid:       ${f.uid}`);
             this.log(`name:      ${f.name}`);
             this.log(`owned_by:  ${f.owned_by}`);
+            // Say plainly that this is someone else's, and how it can be used.
+            if (!resolved.owned) {
+                this.log(`access:    not yours; reachable because it is published or shared with you`);
+                this.log(`address:   ${resolved.handle}@<model>  (chat only; it cannot join a team or be edited)`);
+            }
             this.log(`created:   ${new Date(f.created * 1000).toISOString().slice(0, 10)}`);
             if (f.read_only)
                 this.log('read only');

package/dist/commands/style/delete.d.ts

@@ -3,7 +3,6 @@ export default class StyleDelete extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        scope: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/style/delete.js

@@ -3,26 +3,28 @@ import { createInterface } from 'node:readline';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { STYLE_FACES_PATH } from '../../style.js';
-/** What each scope destroys, in the words the user needs before choosing. */
-const SCOPES = {
-    map: 'the captured style and everything derived from it. Your uploaded material is kept, so it can be captured again without re-uploading.',
-    all: 'the captured style AND the material it was built from. The uploaded corpus is deleted. This cannot be undone and nothing can rebuild it.',
-};
+/**
+ * The API takes a scope: `map` clears the captured style, `all` clears it and
+ * destroys the uploaded material with it. This CLI only ever sends `map`.
+ *
+ * Nothing that removes a style should be able to take source text with it. A
+ * user reaching for "delete the style" is not asking to lose the writing it was
+ * learned from, and the two are one keystroke apart on the same command. Source
+ * text is deleted through the commands that own it — compile:doc:delete and
+ * compile:thread:delete — where that is the whole point of the call rather than
+ * a side effect of a flag value.
+ */
+const SCOPE = 'map';
 export default class StyleDelete extends BaseCommand {
-    static description = 'Delete a face\'s captured style. --scope map forgets the style and keeps the material it came from. ' +
-        '--scope all deletes the uploaded material too, permanently. There is no default because the two ' +
-        'differ by whether your material survives.';
+    static description = "Delete a face's captured style. The material it was learned from is kept, so the style can be " +
+        'captured again without re-uploading. This never deletes documents or threads: remove those with ' +
+        'compile:doc:delete or compile:thread:delete.';
     static examples = [
-        '<%= config.bin %> <%= command.id %> alice --scope map',
-        '<%= config.bin %> <%= command.id %> alice --scope all --yes',
+        '<%= config.bin %> <%= command.id %> alice',
+        '<%= config.bin %> <%= command.id %> alice --yes',
     ];
     static flags = {
         ...BaseCommand.baseFlags,
-        scope: Flags.string({
-            description: 'map: forget the style, keep the material. all: delete the material with it, permanently.',
-            options: ['map', 'all'],
-            required: true,
-        }),
         yes: Flags.boolean({ description: 'Skip confirmation', default: false }),
     };
     static args = {
@@ -31,32 +33,32 @@ export default class StyleDelete extends BaseCommand {
     async run() {
         const { args, flags } = await this.parse(StyleDelete);
         const client = this.makeClient(flags);
-        const scope = flags.scope;
         if (!flags.yes) {
-            const what = `This deletes ${SCOPES[scope]}`;
+            const what = `'${args.alias}' will forget its captured style. Its documents, threads and uploaded material are kept.`;
             if (this.jsonEnabled())
                 this.error(`${what}\nRe-run with --yes to confirm.`);
-            const ok = await this.confirm(`${what}\nDelete for '${args.alias}'?`);
+            const ok = await this.confirm(`${what}\nDelete the style?`);
             if (!ok)
                 this.error('Aborted. Nothing was deleted.');
         }
         let data;
         try {
-            data = await client.delete(`${STYLE_FACES_PATH}/${encodeURIComponent(args.alias)}?scope=${scope}`);
+            data = await client.delete(`${STYLE_FACES_PATH}/${encodeURIComponent(args.alias)}?scope=${SCOPE}`);
         }
         catch (err) {
             if (err instanceof FacesAPIError) {
                 if (err.statusCode === 404)
                     this.error(`No face named '${args.alias}'. It does not exist, or is not yours.`);
+                if (err.statusCode === 409)
+                    this.error(`Error (409): ${err.message}\nThe face may be locked. Unlock it first.`);
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             }
             throw err;
         }
         if (this.jsonEnabled())
             return data;
-        this.log(scope === 'all'
-            ? `Deleted the style and the uploaded material for '${args.alias}'.`
-            : `Deleted the style for '${args.alias}'. The material it came from is still there, so you can capture it again: faces style:make ${args.alias} --all`);
+        this.log(`'${args.alias}' has forgotten its style. Its source material is untouched.`);
+        this.log(`Capture it again with: faces style:make ${args.alias} --all`);
         return data;
     }
     confirm(message) {

package/dist/commands/style/make.js

@@ -25,8 +25,8 @@ export default class StyleMake extends BaseCommand {
             default: false,
         }),
         medium: Flags.string({
-            description: 'Medium for any selected source that does not declare one. Each medium is analysed on its own, ' +
-                'so an essay never teaches a rule about email.',
+            description: 'Medium for selected sources that do not already declare one. It does not override a source ' +
+                'that does. Each medium is analysed on its own, so an essay never teaches a rule about email.',
         }),
         model: Flags.string({ description: `Analyst model (default: ${DEFAULT_STYLE_MODEL})` }),
         'allow-paid': Flags.boolean({
@@ -145,6 +145,13 @@ export default class StyleMake extends BaseCommand {
                 // A live thread is the exception. It compiles as its messages arrive
                 // and is billed per message, so sweeping an unfinished one would charge
                 // for turns the user did not send. Those wait to be named.
+                // The server reports how many messages a capture would actually read.
+                // Zero is a guaranteed intake failure, and one bad source fails the
+                // whole request, so a sweep must not pull them in.
+                if (s.authored === 0) {
+                    skipped.push(`${s.label} (${s.id}) has nothing written by this person for a capture to read.`);
+                    continue;
+                }
                 if (s.isCorpus || s.synced) {
                     if (!flags.compile && !s.synced) {
                         skipped.push(`${s.label} (${s.id}) is not compiled, and --no-compile means it would teach nothing.`);
@@ -182,7 +189,12 @@ export default class StyleMake extends BaseCommand {
         const undeclared = [];
         const sources = [];
         for (const { s, declared } of chosen) {
-            const medium = declared ?? flags.medium ?? s.medium;
+            // Precedence: an explicit --source id:medium, then whatever the source
+            // itself declares, then --medium as a fallback for sources that say
+            // nothing. --medium must not override a source's own declaration: doing
+            // that silently resubmits a document that says "essay" as something else,
+            // and the stamp it leaves behind then misreports how it was read.
+            const medium = declared ?? s.medium ?? flags.medium;
             if (!medium) {
                 undeclared.push(s);
                 continue;

package/dist/commands/style/revert.d.ts

@@ -3,6 +3,7 @@ export default class StyleRevert extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/style/revert.js

@@ -3,12 +3,18 @@ import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { VERSIONS_PATH } from '../../style.js';
 export default class StyleRevert extends BaseCommand {
-    static description = 'Go back to the style a face had before the last style:make. It steps backwards through the kept ' +
-        'versions and there is no step forward, so the way to undo a revert is to capture the style again. ' +
-        'It changes how the face writes immediately, so it asks first.';
-    static examples = ['<%= config.bin %> <%= command.id %> alice --yes'];
+    static description = 'Go back to the style a face had before the last style:make. A face holds one style per medium, so ' +
+        'name which one with --medium when it has more than one. Two versions are kept per medium, so this ' +
+        'goes back exactly one step. It changes how the face writes immediately, so it asks first.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --yes',
+        '<%= config.bin %> <%= command.id %> alice --medium email --yes',
+    ];
     static flags = {
         ...BaseCommand.baseFlags,
+        medium: Flags.string({
+            description: 'Which style to step back, when the face has more than one. See faces style:versions <alias>.',
+        }),
         yes: Flags.boolean({ description: 'Skip confirmation', default: false }),
     };
     static args = {
@@ -21,26 +27,35 @@ export default class StyleRevert extends BaseCommand {
         // not ceremony: the endpoint takes a single field and gives no dry run, so
         // an exploratory call is indistinguishable from a real one.
         if (!flags.yes) {
-            this.error(`This changes how '${args.alias}' writes, straight away. Re-run with --yes to confirm.\n` +
+            this.error(`This changes how '${args.alias}' writes${flags.medium ? ` for ${flags.medium}` : ''}, straight away. ` +
+                'Re-run with --yes to confirm.\n' +
                 `See what it would go back to: faces style:versions ${args.alias}`);
         }
+        const body = { self_face: args.alias };
+        // A medium is required once a face holds more than one style. Sending the
+        // flag only when given keeps the legacy single-lineage call unchanged.
+        if (flags.medium !== undefined)
+            body.medium = flags.medium;
         let data;
         try {
-            data = (await client.post(`${VERSIONS_PATH}/revert`, { body: { self_face: args.alias } }));
+            data = (await client.post(`${VERSIONS_PATH}/revert`, { body }));
         }
         catch (err) {
             if (err instanceof FacesAPIError) {
                 if (err.statusCode === 404)
                     this.error(`No face named '${args.alias}'. It does not exist, or is not yours.`);
-                if (err.statusCode === 409)
-                    this.error(`Error (409): ${err.message}\nThe face may be locked. Unlock it first.`);
-                // Reverting past the oldest kept version fails this way rather than
-                // with a clean refusal (faces-backend-shared#590).
+                // The server's 409s say exactly what is wrong — more than one style to
+                // choose between, or nothing left to step back to. Pass them through
+                // and add only the command that answers them.
+                if (err.statusCode === 409) {
+                    this.error(`Error (409): ${err.message}\nSee what is there: faces style:versions ${args.alias}`);
+                }
+                // Reverting a named medium currently fails this way even when the
+                // server itself reports can_revert: true (faces-backend-shared#590).
                 if (err.statusCode === 500) {
-                    this.error(`Error (500): ${err.message}\n` +
-                        `'${args.alias}' may already be on the oldest style that is still kept, in which case there ` +
-                        'is nothing further back to go to. Check with: faces style:versions ' +
-                        args.alias);
+                    this.error(`Error (500): the server failed to revert '${args.alias}'.\n` +
+                        'Reverting a per-medium style is currently broken upstream and nothing was changed. ' +
+                        'Tracked as faces-backend-shared#590.');
                 }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             }
@@ -56,9 +71,7 @@ export default class StyleRevert extends BaseCommand {
         else {
             this.log(`'${args.alias}' reverted.`);
         }
-        // Not "run it again to undo": another revert steps back again, it does not
-        // return. Verified against production.
-        this.log(`There is no step forward. To undo this, capture the style again: faces style:make ${args.alias} --all`);
+        this.log(`To undo this, capture the style again: faces style:make ${args.alias} --all`);
         this.log(`List versions: faces style:versions ${args.alias}`);
         return data;
     }

package/dist/commands/style/versions.js

@@ -3,8 +3,10 @@ import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { EXIT_NO_SUCH_FACE, VERSIONS_PATH, faceExists } from '../../style.js';
 export default class StyleVersions extends BaseCommand {
-    static description = 'List the styles captured for a face, and which one it is writing in now. Each style:make keeps ' +
-        'the previous one, so this is what style:revert has to go back to.';
+    static description = 'List the styles captured for a face, and which one it writes in now. A face holds one style per ' +
+        'medium, so more than one can be in use at once: an email style and an essay style are separate ' +
+        'and do not replace each other. Two versions are kept per medium, which is what style:revert has ' +
+        'to go back to.';
     static examples = ['<%= config.bin %> <%= command.id %> alice', '<%= config.bin %> <%= command.id %> alice --json'];
     static flags = { ...BaseCommand.baseFlags };
     static args = {
@@ -12,6 +14,7 @@ export default class StyleVersions extends BaseCommand {
     };
     async run() {
         const { args, flags } = await this.parse(StyleVersions);
+        const alias = args.alias;
         const client = this.makeClient(flags);
         let data;
         try {
@@ -41,14 +44,19 @@ export default class StyleVersions extends BaseCommand {
             return data;
         }
         const rows = versions.map((v) => ({
+            // A null medium is a map built before media existed, not a missing value.
+            medium: v.medium?.trim() || '(before media)',
             version: String(v.version ?? '-'),
             active: v.active ? 'yes' : '-',
+            revert: v.can_revert ? 'yes' : '-',
             model: v.model?.trim() || '-',
             created: String(v.created_at ?? '').slice(0, 19).replace('T', ' ') || '-',
         }));
         const cols = [
+            ['MEDIUM', (r) => r.medium],
             ['VERSION', (r) => r.version],
-            ['ACTIVE', (r) => r.active],
+            ['IN USE', (r) => r.active],
+            ['REVERTABLE', (r) => r.revert],
             ['MODEL', (r) => r.model],
             ['CAPTURED', (r) => r.created],
         ];
@@ -57,20 +65,24 @@ export default class StyleVersions extends BaseCommand {
         this.log(line(cols.map(([h]) => h)));
         for (const r of rows)
             this.log(line(cols.map(([, g]) => g(r))));
-        // More than one row can come back marked active (faces-backend-shared#589).
-        // Saying "you are writing in version N" would be a guess, so when the data
-        // is ambiguous the command says so instead of picking one.
+        // Several rows are active at once by design: one per medium. Version
+        // numbers restart per medium, so a version number alone does not identify
+        // a row and the summary names the medium with it.
         const active = versions.filter((v) => v.active);
+        const label = (v) => `${v.medium?.trim() || '(before media)'} v${v.version}`;
         this.log('');
-        if (active.length === 1) {
-            this.log(`Writing in version ${active[0].version} now. ${versions.length} version(s) kept.`);
-        }
-        else if (active.length === 0) {
-            this.log(`${versions.length} version(s) kept. None is marked active.`);
+        if (active.length === 0) {
+            this.log(`${versions.length} version(s) kept, none in use.`);
         }
         else {
-            this.log(`${versions.length} version(s) kept, and ${active.length} are marked active, so which one is in ` +
-                'use cannot be read from this list. Reported upstream.');
+            this.log(`In use: ${active.map((v) => label(v)).join(', ')}.`);
+            this.log(`${versions.length} version(s) kept in total, two per medium.`);
+        }
+        const revertable = versions.filter((v) => v.can_revert);
+        if (revertable.length > 0) {
+            const media = revertable.map((v) => v.medium?.trim()).filter(Boolean);
+            this.log(`Can step back: ${revertable.map((v) => label(v)).join(', ')}. ` +
+                (media.length > 0 ? `Use: faces style:revert ${alias} --medium ${media[0]} --yes` : ''));
         }
         return data;
     }

package/dist/commands/team/add.js

@@ -2,8 +2,10 @@ import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
 import { TeamCatalogService } from '../../team-catalog.js';
+import { resolveFace } from '../../utils.js';
 export default class TeamAdd extends BaseCommand {
-    static description = 'Add face(s) to a team';
+    static description = 'Add face(s) to a team. A team may only contain faces this account owns: a published or shared face ' +
+        'can be chatted with but cannot be a member.';
     static flags = {
         ...BaseCommand.baseFlags,
         face: Flags.string({ description: 'Face alias to add (repeatable)', multiple: true, required: true }),
@@ -14,21 +16,40 @@ export default class TeamAdd extends BaseCommand {
     async run() {
         const { args, flags } = await this.parse(TeamAdd);
         const client = this.makeClient(flags);
-        // Resolve aliases to iam_ids
+        // Resolve aliases to iam_ids. resolveFace also finds published and shared
+        // faces, which the plain face route cannot: without that a reachable face
+        // fails here as 404 or 403 depending on how it was named, and both read as
+        // a typo rather than as the rule that teams are owner-scoped.
         const iamIds = [];
         for (const alias of flags.face) {
+            let resolved;
             try {
-                const face = await client.get(`/v1/faces/${alias}`);
-                const id = (face.uid ?? face.id ?? face.iam_id);
-                if (!id)
-                    this.error(`Could not resolve iam_id for face '${alias}'`);
-                iamIds.push(id);
+                resolved = await resolveFace(client, alias);
             }
             catch (err) {
-                if (err instanceof FacesAPIError)
+                if (err instanceof FacesAPIError) {
+                    if (err.statusCode === 404) {
+                        this.error(`No face '${alias}'. If it belongs to another account, name it as owner:alias. ` +
+                            'Find it with: faces face:list --public');
+                    }
                     this.error(`Error resolving '${alias}' (${err.statusCode}): ${err.message}`);
+                }
                 throw err;
             }
+            // The server enforces this too, but only once it has an id, which this
+            // command cannot reach for a face it does not own. Say the real reason.
+            if (!resolved.owned) {
+                this.error(`A team may only contain faces you own, and '${resolved.handle}' is owned by ` +
+                    `'${resolved.owner ?? 'another account'}'. It is published or shared with you, so you can chat ` +
+                    `it as ${resolved.handle}@<model>, but it cannot be a team member.\n` +
+                    'Do not create a copy to work around this: the copy would be a different face with different ' +
+                    'compiled material.');
+            }
+            const face = resolved.face;
+            const id = (face.uid ?? face.id ?? face.iam_id);
+            if (!id)
+                this.error(`Could not resolve iam_id for face '${alias}'`);
+            iamIds.push(id);
         }
         let data;
         try {

package/dist/style.d.ts

@@ -57,6 +57,12 @@ export interface Selectable {
      * which is the one source type a build may not compile for free.
      */
     isCorpus: boolean;
+    /**
+     * Messages a capture would actually read, by the same rule intake applies.
+     * Zero means the capture fails on this source. Undefined on documents and on
+     * servers that predate the field.
+     */
+    authored?: number;
     /** Present once this source has been printed. */
     printedAt?: string;
     printedMedium?: string;

package/dist/style.js

@@ -92,6 +92,7 @@ function rowToSelectable(r, sourceType) {
         label: r.label?.trim() || '(untitled)',
         synced: Boolean(r.synced),
         isCorpus: sourceType === 'document' || Boolean(r.corpus_kind?.trim()),
+        authored: r.authored_message_count ?? undefined,
         // The stamp was renamed alongside the request field, but stored stamps kept
         // the old key (faces-backend-shared#589), so both are read.
         printedMedium: stamp?.medium ?? stamp?.kind,

package/dist/team-catalog.d.ts

@@ -1,4 +1,13 @@
 export declare const TEAMS_DIR: string;
+/**
+ * Directory name for a team.
+ *
+ * Local teams are stored under a slug of their display name, so any comparison
+ * between the server's teams and the local ones has to normalise the same way
+ * in both directions. Exported because doing it in one direction only is how a
+ * team whose name contains punctuation ends up looking orphaned every time.
+ */
+export declare function slugifyTeamName(name: string): string;
 export interface TeamFrontmatter {
     id?: string;
     name: string;
@@ -13,5 +22,13 @@ export declare class TeamCatalogService {
         body: string;
     } | null;
     listTeams(): string[];
+    /**
+     * Whether TEAM.md carries anything beyond the frontmatter the CLI writes.
+     *
+     * For a team that still exists this body is the server's protocol and gets
+     * overwritten on every sync. For one that does not, it is the only copy left,
+     * which is the difference between tidying up and losing something.
+     */
+    hasLocalContent(name: string): boolean;
     deleteTeam(name: string): void;
 }

package/dist/team-catalog.js

@@ -2,6 +2,20 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 export const TEAMS_DIR = path.join(os.homedir(), '.faces', 'teams');
+/**
+ * Directory name for a team.
+ *
+ * Local teams are stored under a slug of their display name, so any comparison
+ * between the server's teams and the local ones has to normalise the same way
+ * in both directions. Exported because doing it in one direction only is how a
+ * team whose name contains punctuation ends up looking orphaned every time.
+ */
+export function slugifyTeamName(name) {
+    return String(name)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
 function quoteYaml(value) {
     if (/[:#\[\]{}&*!|>'"%@`\n]/.test(value) || value !== value.trim() || value === '') {
         return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
@@ -91,6 +105,17 @@ export class TeamCatalogService {
             .filter(d => d.isDirectory() && fs.existsSync(path.join(TEAMS_DIR, d.name, 'TEAM.md')))
             .map(d => d.name);
     }
+    /**
+     * Whether TEAM.md carries anything beyond the frontmatter the CLI writes.
+     *
+     * For a team that still exists this body is the server's protocol and gets
+     * overwritten on every sync. For one that does not, it is the only copy left,
+     * which is the difference between tidying up and losing something.
+     */
+    hasLocalContent(name) {
+        const team = this.readTeam(name);
+        return Boolean(team && team.body.trim());
+    }
     deleteTeam(name) {
         try {
             const dir = path.join(TEAMS_DIR, name);