faces-cli 1.7.10 → 1.7.14

package/dist/catalog.d.ts

@@ -8,12 +8,7 @@ export interface FaceFrontmatter {
     tags?: string[];
     default_model?: string;
     formula?: string | null;
-    component_counts?: {
-        alpha: number;
-        beta: number;
-        delta: number;
-        epsilon: number;
-    };
+    component_counts?: number[];
     compiled_tokens?: number;
     profile_token_count?: number;
     [key: string]: unknown;
@@ -29,12 +24,7 @@ export interface FaceDataInput {
     tags?: string[] | null;
     default_model?: string | null;
     formula?: string | null;
-    component_counts?: {
-        alpha: number;
-        beta: number;
-        delta: number;
-        epsilon: number;
-    } | null;
+    component_counts?: number[] | null;
     profile_token_count?: number | null;
     total_tokens_saved?: number | null;
 }

package/dist/catalog.js

@@ -29,9 +29,8 @@ function serializeFrontmatter(fm) {
     if (fm.tags && fm.tags.length > 0) {
         lines.push(`tags: [${fm.tags.join(', ')}]`);
     }
-    if (fm.component_counts) {
-        const cc = fm.component_counts;
-        lines.push(`component_counts: ${cc.alpha + cc.beta + cc.delta + cc.epsilon}`);
+    if (fm.component_counts?.length) {
+        lines.push(`component_counts: ${fm.component_counts.reduce((a, b) => a + b, 0)}`);
     }
     if (fm.compiled_tokens) {
         lines.push(`compiled_tokens: ${fm.compiled_tokens}`);

package/dist/commands/chat/chat.d.ts

@@ -12,6 +12,7 @@ export default class ChatChat extends BaseCommand {
         temperature: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         responses: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'oauth-only': 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/chat/chat.js

@@ -2,7 +2,7 @@ import { Args, Flags } from '@oclif/core';
 import fs from 'node:fs';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
-import { extractStreamDelta } from '../../utils.js';
+import { extractStreamDelta, isMaxTokensRenameError, MIN_MAX_OUTPUT_TOKENS, MEDIUM_FLAG_DESCRIPTION, warnDroppedParams, CHAT_PARAM_FLAGS } from '../../utils.js';
 import { resolveEndpoint, MESSAGES_ENDPOINT, RESPONSES_ENDPOINT, isCompositeFormula, faceSpecOf, llmFromArg } from '../../routing.js';
 export default class ChatChat extends BaseCommand {
     static description = 'Chat via a face. Auto-routes to the correct API endpoint based on the model catalog.';
@@ -22,6 +22,7 @@ export default class ChatChat extends BaseCommand {
         temperature: Flags.string({ description: 'Temperature (0.0-2.0)' }),
         file: Flags.string({ description: 'Read message from file' }),
         responses: Flags.boolean({ description: 'Force the OpenAI Responses API endpoint (escape hatch; routing is automatic otherwise)', default: false }),
+        medium: Flags.string({ description: MEDIUM_FLAG_DESCRIPTION }),
         'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
@@ -140,13 +141,32 @@ export default class ChatChat extends BaseCommand {
             payload.max_tokens = flags['max-tokens'];
         if (flags.temperature !== undefined)
             payload.temperature = Number.parseFloat(flags.temperature);
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
             await this.streamDeltas(client, '/v1/chat/completions', payload);
             return {};
         }
-        const { data, headers } = await client.postWithHeaders('/v1/chat/completions', { body: payload });
+        let data;
+        let headers;
+        try {
+            ;
+            ({ data, headers } = await client.postWithHeaders('/v1/chat/completions', { body: payload }));
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError && isMaxTokensRenameError(err.message) && payload.max_tokens !== undefined) {
+                payload.max_completion_tokens = payload.max_tokens;
+                delete payload.max_tokens;
+                ({ data, headers } = await client.postWithHeaders('/v1/chat/completions', { body: payload }));
+            }
+            else {
+                throw err;
+            }
+        }
+        if (!this.jsonEnabled())
+            warnDroppedParams(headers, CHAT_PARAM_FLAGS);
         const body = data;
         const choices = body.choices;
         const text = String(choices?.[0]?.message?.content ?? '');
@@ -167,6 +187,8 @@ export default class ChatChat extends BaseCommand {
         };
         if (flags.system)
             payload.system = flags.system;
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
@@ -174,6 +196,8 @@ export default class ChatChat extends BaseCommand {
             return {};
         }
         const { data, headers } = await client.postWithHeaders('/v1/messages', { body: payload });
+        if (!this.jsonEnabled())
+            warnDroppedParams(headers, CHAT_PARAM_FLAGS);
         const body = data;
         if (this.jsonEnabled()) {
             body._meta = this.metaFor(headers, '/v1/messages');
@@ -199,10 +223,17 @@ export default class ChatChat extends BaseCommand {
         // `temperature` is accepted per-model (gpt-5.1/5.2/5.4 yes; gpt-5.5/5.6-*/o3
         // no) with no capability flag to query, so we always send what the user asked
         // for — the backend strips the param and retries when a model 400s on it.
-        if (flags['max-tokens'])
+        if (flags['max-tokens']) {
+            if (flags['max-tokens'] < MIN_MAX_OUTPUT_TOKENS) {
+                this.error(`--max-tokens must be at least ${MIN_MAX_OUTPUT_TOKENS} for this model (got ${flags['max-tokens']}). ` +
+                    'The Responses API rejects a smaller output cap.');
+            }
             payload.max_output_tokens = flags['max-tokens'];
+        }
         if (flags.temperature !== undefined)
             payload.temperature = Number.parseFloat(flags.temperature);
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
@@ -210,6 +241,8 @@ export default class ChatChat extends BaseCommand {
             return {};
         }
         const { data, headers } = await client.postWithHeaders('/v1/responses', { body: payload });
+        if (!this.jsonEnabled())
+            warnDroppedParams(headers, CHAT_PARAM_FLAGS);
         const body = data;
         if (this.jsonEnabled()) {
             body._meta = this.metaFor(headers, '/v1/responses');

package/dist/commands/chat/messages.d.ts

@@ -6,6 +6,7 @@ export default class ChatMessages extends BaseCommand {
         system: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         stream: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'max-tokens': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'oauth-only': 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/chat/messages.js

@@ -1,5 +1,6 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../base.js';
+import { MEDIUM_FLAG_DESCRIPTION } from '../../utils.js';
 import { FacesAPIError } from '../../client.js';
 export default class ChatMessages extends BaseCommand {
     static description = 'Anthropic Messages API proxy via a face (alias: chat:chat auto-routes Anthropic models here)';
@@ -9,10 +10,11 @@ export default class ChatMessages extends BaseCommand {
         system: Flags.string({ description: 'System prompt' }),
         stream: Flags.boolean({ description: 'Stream the response', default: false }),
         'max-tokens': Flags.integer({ description: 'Max tokens', default: 1024 }),
+        medium: Flags.string({ description: MEDIUM_FLAG_DESCRIPTION }),
         'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
-        face_model: Args.string({ description: 'Face model (e.g. myface, myface@claude-sonnet-4-6, or head:judge@claude-sonnet-4-6)', required: true }),
+        face_model: Args.string({ description: 'Face model (e.g. myface, myface@claude-sonnet-4-6, or head:socrates@claude-sonnet-4-6)', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(ChatMessages);
@@ -26,6 +28,8 @@ export default class ChatMessages extends BaseCommand {
         };
         if (flags.system)
             payload.system = flags.system;
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         try {

package/dist/commands/chat/responses.d.ts

@@ -5,6 +5,7 @@ export default class ChatResponses extends BaseCommand {
         message: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         instructions: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         stream: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'oauth-only': 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/chat/responses.js

@@ -1,5 +1,6 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../base.js';
+import { MEDIUM_FLAG_DESCRIPTION } from '../../utils.js';
 import { FacesAPIError } from '../../client.js';
 export default class ChatResponses extends BaseCommand {
     static description = 'OpenAI Responses API proxy via a face (alias: chat:chat --responses)';
@@ -8,10 +9,11 @@ export default class ChatResponses extends BaseCommand {
         message: Flags.string({ char: 'm', description: 'User input message', required: true }),
         instructions: Flags.string({ description: 'System instructions' }),
         stream: Flags.boolean({ description: 'Stream the response', default: false }),
+        medium: Flags.string({ description: MEDIUM_FLAG_DESCRIPTION }),
         'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key (use OAuth only)', default: false }),
     };
     static args = {
-        face_model: Args.string({ description: 'Face model (e.g. myface, myface@gpt-4o, or head:logician@gpt-5.4)', required: true }),
+        face_model: Args.string({ description: 'Face model (e.g. myface, myface@gpt-4o, or head:socrates@gpt-5.4)', required: true }),
     };
     async run() {
         const { args, flags } = await this.parse(ChatResponses);
@@ -23,6 +25,8 @@ export default class ChatResponses extends BaseCommand {
         };
         if (flags.instructions)
             payload.instructions = flags.instructions;
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         try {

package/dist/commands/chat/thread.d.ts

@@ -11,6 +11,7 @@ export default class ChatThread extends BaseCommand {
         'max-tokens': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
         temperature: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         stream: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'oauth-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         list: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         show: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/chat/thread.js

@@ -5,7 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { BaseCommand } from '../../base.js';
 import { FacesAPIError } from '../../client.js';
-import { extractStreamDelta } from '../../utils.js';
+import { extractStreamDelta, isMaxTokensRenameError, MIN_MAX_OUTPUT_TOKENS, MEDIUM_FLAG_DESCRIPTION } from '../../utils.js';
 import { resolveEndpoint, MESSAGES_ENDPOINT, RESPONSES_ENDPOINT, CHAT_COMPLETIONS_ENDPOINT } from '../../routing.js';
 const THREADS_DIR = path.join(os.homedir(), '.faces', 'threads');
 /**
@@ -91,6 +91,7 @@ export default class ChatThread extends BaseCommand {
         'max-tokens': Flags.integer({ description: 'Max tokens' }),
         temperature: Flags.string({ description: 'Temperature (0.0-2.0, OpenAI/Chat Completions only)' }),
         stream: Flags.boolean({ description: 'Stream the response', default: false }),
+        medium: Flags.string({ description: MEDIUM_FLAG_DESCRIPTION }),
         'oauth-only': Flags.boolean({ description: 'Prevent fallback to paid system key', default: false }),
         list: Flags.boolean({ description: 'List saved threads', default: false }),
         show: Flags.boolean({ description: 'Show the thread transcript (requires --id)', default: false }),
@@ -279,12 +280,30 @@ export default class ChatThread extends BaseCommand {
             payload.max_tokens = flags['max-tokens'];
         if (flags.temperature !== undefined)
             payload.temperature = Number.parseFloat(flags.temperature);
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
             return this.streamAndAccumulate(client, CHAT_COMPLETIONS_ENDPOINT, payload);
         }
-        const { data } = await client.postWithHeaders(CHAT_COMPLETIONS_ENDPOINT, { body: payload });
+        let data;
+        try {
+            ;
+            ({ data } = await client.postWithHeaders(CHAT_COMPLETIONS_ENDPOINT, { body: payload }));
+        }
+        catch (err) {
+            // Newer OpenAI models require max_completion_tokens; retry on the provider's
+            // own rejection rather than keeping a model list that goes stale.
+            if (err instanceof FacesAPIError && isMaxTokensRenameError(err.message) && payload.max_tokens !== undefined) {
+                payload.max_completion_tokens = payload.max_tokens;
+                delete payload.max_tokens;
+                ({ data } = await client.postWithHeaders(CHAT_COMPLETIONS_ENDPOINT, { body: payload }));
+            }
+            else {
+                throw err;
+            }
+        }
         return extractAssistantText(data, CHAT_COMPLETIONS_ENDPOINT);
     }
     async sendResponses(client, thread, flags) {
@@ -294,8 +313,15 @@ export default class ChatThread extends BaseCommand {
         const payload = { model: thread.model, input, stream: flags.stream };
         if (thread.system)
             payload.instructions = thread.system;
-        if (flags['max-tokens'])
+        if (flags['max-tokens']) {
+            if (flags['max-tokens'] < MIN_MAX_OUTPUT_TOKENS) {
+                throw new Error(`--max-tokens must be at least ${MIN_MAX_OUTPUT_TOKENS} for this model (got ${flags['max-tokens']}). ` +
+                    'The Responses API rejects a smaller output cap.');
+            }
             payload.max_output_tokens = flags['max-tokens'];
+        }
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {
@@ -314,6 +340,8 @@ export default class ChatThread extends BaseCommand {
         };
         if (thread.system)
             payload.system = thread.system;
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags['oauth-only'])
             payload.oauth_only = true;
         if (flags.stream) {

package/dist/commands/compile/doc/create.d.ts

@@ -5,6 +5,7 @@ export default class CompileDocCreate extends BaseCommand {
         label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         content: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         perspective: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         '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/compile/doc/create.js

@@ -1,6 +1,7 @@
 import { Args, Flags } from '@oclif/core';
 import fs from 'node:fs';
 import { BaseCommand } from '../../../base.js';
+import { MEDIUM_FLAG_DESCRIPTION } from '../../../utils.js';
 import { FacesAPIError } from '../../../client.js';
 export default class CompileDocCreate extends BaseCommand {
     static description = 'Submit a document to a face';
@@ -9,6 +10,7 @@ export default class CompileDocCreate extends BaseCommand {
         label: Flags.string({ description: 'Document label/title' }),
         content: Flags.string({ description: 'Inline text content' }),
         file: Flags.string({ description: 'Read content from file' }),
+        medium: Flags.string({ description: MEDIUM_FLAG_DESCRIPTION }),
         perspective: Flags.string({ description: 'Perspective (first-person or third-person)', options: ['first-person', 'third-person'], default: 'first-person' }),
     };
     static args = {
@@ -28,6 +30,8 @@ export default class CompileDocCreate extends BaseCommand {
         const payload = { alias: args.face_id, content };
         if (flags.label)
             payload.label = flags.label;
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags.perspective)
             payload.perspective = flags.perspective;
         let data;

package/dist/commands/compile/doc/edit.d.ts

@@ -5,6 +5,7 @@ export default class CompileDocEdit extends BaseCommand {
         label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         content: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         perspective: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         '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/compile/doc/edit.js

@@ -1,6 +1,7 @@
 import { Args, Flags } from '@oclif/core';
 import fs from 'node:fs';
 import { BaseCommand } from '../../../base.js';
+import { MEDIUM_FLAG_DESCRIPTION } from '../../../utils.js';
 import { FacesAPIError } from '../../../client.js';
 export default class CompileDocEdit extends BaseCommand {
     static description = 'Edit a document (label, content, or perspective)';
@@ -9,6 +10,7 @@ export default class CompileDocEdit extends BaseCommand {
         label: Flags.string({ description: 'New label/title' }),
         content: Flags.string({ description: 'New inline text content' }),
         file: Flags.string({ description: 'Read new content from file' }),
+        medium: Flags.string({ description: MEDIUM_FLAG_DESCRIPTION }),
         perspective: Flags.string({ description: 'Perspective (first-person or third-person)', options: ['first-person', 'third-person'] }),
     };
     static args = {
@@ -20,6 +22,8 @@ export default class CompileDocEdit extends BaseCommand {
         const payload = {};
         if (flags.label)
             payload.label = flags.label;
+        if (flags.medium)
+            payload.medium = flags.medium;
         if (flags.perspective)
             payload.perspective = flags.perspective;
         if (flags.file) {

package/dist/commands/compile/doc/index.d.ts

@@ -6,6 +6,7 @@ export default class CompileDoc extends BaseCommand {
         label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         content: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         file: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         perspective: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/compile/doc/index.js

@@ -2,6 +2,7 @@ import { Args, Flags } from '@oclif/core';
 import fs from 'node:fs';
 import path from 'node:path';
 import { BaseCommand } from '../../../base.js';
+import { MEDIUM_FLAG_DESCRIPTION } from '../../../utils.js';
 import { FacesAPIError } from '../../../client.js';
 import { pollCompileProgress } from '../../../poll.js';
 export default class CompileDoc extends BaseCommand {
@@ -17,6 +18,7 @@ export default class CompileDoc extends BaseCommand {
         label: Flags.string({ description: 'Document label/title (single document only; with several files each is labelled by its filename)' }),
         content: Flags.string({ description: 'Inline text content', exclusive: ['file'] }),
         file: Flags.string({ description: 'Read content from file (repeatable — each file becomes its own document)', multiple: true }),
+        medium: Flags.string({ description: MEDIUM_FLAG_DESCRIPTION }),
         perspective: Flags.string({
             description: 'Perspective',
             options: ['first-person', 'third-person'],
@@ -71,6 +73,8 @@ export default class CompileDoc extends BaseCommand {
                     payload.label = flags.label;
                 else if (multi)
                     payload.label = path.basename(source.name);
+                if (flags.medium)
+                    payload.medium = flags.medium;
                 if (flags.perspective)
                     payload.perspective = flags.perspective;
                 if (!json)
@@ -123,7 +127,7 @@ export default class CompileDoc extends BaseCommand {
                         if (json)
                             return;
                         const c = p.current_counts;
-                        const counts = c ? `ε=${c.epsilon} β=${c.beta} δ=${c.delta} α=${c.alpha}` : '';
+                        const counts = c?.length ? `${c.reduce((a, b) => a + b, 0)} components` : '';
                         const phase = p.prepare_status === 'syncing' ? ' (syncing)' : '';
                         process.stderr.write(`  [${p.chunks_completed ?? '?'}/${p.chunks_total ?? '?'}] ${counts}${phase}\n`);
                     },

package/dist/commands/compile/doc/make.js

@@ -45,7 +45,7 @@ export default class CompileDocMake extends BaseCommand {
                 onProgress: (p) => {
                     if (!json) {
                         const c = p.current_counts;
-                        const counts = c ? `ε=${c.epsilon} β=${c.beta} δ=${c.delta} α=${c.alpha}` : '';
+                        const counts = c?.length ? `${c.reduce((a, b) => a + b, 0)} components` : '';
                         const phase = p.prepare_status === 'syncing' ? ' (syncing)' : '';
                         process.stderr.write(`  [${p.chunks_completed ?? '?'}/${p.chunks_total ?? '?'}] ${counts}${phase}\n`);
                     }

package/dist/commands/compile/thread/make.js

@@ -46,7 +46,7 @@ export default class CompileThreadMake extends BaseCommand {
                 onProgress: (p) => {
                     if (!json) {
                         const c = p.current_counts;
-                        const counts = c ? `ε=${c.epsilon} β=${c.beta} δ=${c.delta} α=${c.alpha}` : '';
+                        const counts = c?.length ? `${c.reduce((a, b) => a + b, 0)} components` : '';
                         const phase = p.prepare_status === 'syncing' ? ' (syncing)' : '';
                         process.stderr.write(`  [${p.chunks_completed ?? '?'}/${p.chunks_total ?? '?'}] ${counts}${phase}\n`);
                     }

package/dist/commands/compile/upload.d.ts

@@ -5,6 +5,7 @@ export default class CompileUpload extends BaseCommand {
         file: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         kind: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         perspective: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        medium: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'face-speaker': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/compile/upload.js

@@ -2,6 +2,7 @@ import { Args, Flags } from '@oclif/core';
 import fs from 'node:fs';
 import path from 'node:path';
 import { BaseCommand } from '../../base.js';
+import { MEDIUM_FLAG_DESCRIPTION } from '../../utils.js';
 import { FacesAPIError } from '../../client.js';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -21,6 +22,7 @@ export default class CompileUpload extends BaseCommand {
             options: ['first-person', 'third-person'],
             default: 'third-person',
         }),
+        medium: Flags.string({ description: MEDIUM_FLAG_DESCRIPTION + ' Only valid with --kind document.' }),
         'face-speaker': Flags.string({
             description: 'Speaker name to map to the face (thread only). If omitted, auto-detected from face name.',
         }),
@@ -42,8 +44,15 @@ export default class CompileUpload extends BaseCommand {
         const fileBlob = new Blob([fs.readFileSync(flags.file)], { type: 'application/octet-stream' });
         const form = new FormData();
         form.append('file', fileBlob, filename);
+        // The API accepts medium for document uploads only — a thread carries a kind
+        // per message, derived from the file. Refuse here rather than on a 422.
+        if (flags.medium && flags.kind !== 'document') {
+            this.error(`--medium applies to --kind document only (got --kind ${flags.kind}); a thread carries a kind per message.`);
+        }
         const params = new URLSearchParams();
         params.set('type', flags.kind);
+        if (flags.medium)
+            params.set('medium', flags.medium);
         params.set('perspective', flags.perspective);
         if (flags['face-speaker'])
             params.set('face_speaker', flags['face-speaker']);

package/dist/commands/face/diff.js

@@ -30,16 +30,18 @@ export default class FaceDiff extends BaseCommand {
         if (!this.jsonEnabled()) {
             const res = data;
             const faces = res.faces;
-            const components = ['face', 'beta', 'delta', 'epsilon'];
+            const fmt = (v) => (v === null || v === undefined ? '—' : v.toFixed(2));
             for (let i = 0; i < faces.length; i++) {
                 for (let j = i + 1; j < faces.length; j++) {
                     const a = faces[i];
                     const b = faces[j];
-                    const scores = res.similarity[a][b];
-                    const parts = components.map(c => {
-                        const v = scores[c];
-                        return `${c}: ${v === null ? '—' : v.toFixed(2)}`;
-                    });
+                    const { face: overall, components } = res.similarity[a][b];
+                    const parts = [
+                        `overall: ${fmt(overall)}`,
+                        // Label by true index, never by ordinal-among-non-null: the position
+                        // is the identity, and it is the same vocabulary the API uses.
+                        ...(components ?? []).map((v, n) => `component ${n}: ${fmt(v)}`),
+                    ];
                     this.log(`${a}  ↔  ${b}   ${parts.join('   ')}`);
                 }
             }

package/dist/commands/face/list.d.ts

@@ -6,6 +6,7 @@ export default class FaceList extends BaseCommand {
         team: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         include: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         public: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        shared: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         system: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'from-users': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'not-from-users': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/face/list.js

@@ -11,7 +11,8 @@ export default class FaceList extends BaseCommand {
         tag: Flags.string({ description: 'Filter by tag (repeatable, AND logic)', multiple: true }),
         team: Flags.string({ description: 'Filter by team ID (repeatable, OR logic)', multiple: true }),
         include: Flags.string({ description: 'Include extra fields: tags, teams (comma-separated)' }),
-        public: Flags.boolean({ description: 'Include published faces from other accounts' }),
+        public: Flags.boolean({ description: 'Include published faces from other accounts (open to everybody)' }),
+        shared: Flags.boolean({ description: 'Include faces other accounts have shared with YOU in particular' }),
         system: Flags.boolean({ description: `Show only the curated system faces (published faces owned by '${SYSTEM_OWNER}')` }),
         'from-users': Flags.string({ description: 'Only published faces from these owners (repeatable/comma-separated)', multiple: true }),
         'not-from-users': Flags.string({ description: 'Exclude published faces from these owners (repeatable/comma-separated)', multiple: true }),
@@ -44,6 +45,8 @@ export default class FaceList extends BaseCommand {
             parts.push(`include=${encodeURIComponent(flags.include)}`);
         if (includePublished)
             parts.push('include_published=true');
+        if (flags.shared)
+            parts.push('include_shared=true');
         for (const u of fromUsers)
             parts.push(`from_users=${encodeURIComponent(u)}`);
         for (const u of notFromUsers)
@@ -82,7 +85,11 @@ export default class FaceList extends BaseCommand {
             data = faces;
         if (!this.jsonEnabled()) {
             // Published faces are chatted as `owner:alias`; own faces stay bare.
-            const handle = (f) => f.published && f.owned_by ? `${f.owned_by}:${f.alias}` : f.alias;
+            // A face you do not own needs the owner prefix to resolve at all. Both
+            // published and shared faces are someone else's, and only those two carry
+            // `published` / `via`, so either marks the alias as needing qualifying.
+            const isForeign = (f) => Boolean(f.published || f.via?.length);
+            const handle = (f) => isForeign(f) && f.owned_by ? `${f.owned_by}:${f.alias}` : f.alias;
             if (faces.length === 0) {
                 this.log('(no faces)');
             }
@@ -96,10 +103,16 @@ export default class FaceList extends BaseCommand {
                     }
                     else if (f.component_counts || f.profile_token_count) {
                         const cc = f.component_counts;
-                        const total = cc ? cc.alpha + cc.beta + cc.delta + cc.epsilon : 0;
+                        const total = cc?.reduce((a, b) => a + b, 0) ?? 0;
                         const profile = f.profile_token_count ?? 0;
                         suffix = `  [profile: ${profile} tok, components: ${total}]`;
                     }
+                    if (f.via?.length) {
+                        const how = f.via.includes('shared') && f.via.includes('workspace')
+                            ? 'shared with you, and via a workspace'
+                            : f.via.includes('workspace') ? 'via a workspace' : 'shared with you';
+                        suffix += `  [${how} · requires @model]`;
+                    }
                     if (f.published)
                         suffix += '  [public · requires @model]';
                     if (f.read_only)

package/dist/commands/face/neighbors.js

@@ -12,8 +12,8 @@ export default class FaceNeighbors extends BaseCommand {
             max: 20,
         }),
         component: Flags.string({
-            description: 'Centroid component to rank on (beta, delta, epsilon are the principal components of a face; face is their composite)',
-            options: ['face', 'beta', 'delta', 'epsilon'],
+            description: 'What to rank on: `face` for overall similarity, or a component position such as 1. ' +
+                'Which positions are comparable varies; the API names them if you pick a wrong one.',
             default: 'face',
         }),
         direction: Flags.string({
@@ -33,19 +33,35 @@ export default class FaceNeighbors extends BaseCommand {
             component: flags.component,
             direction: flags.direction,
         };
+        // Positions are open-ended (they follow the component-counts order, which can
+        // grow), so validate the shape only and let the API say which are comparable
+        // — it knows, and the answer differs per face.
+        if (flags.component !== 'face' && !/^\d+$/.test(flags.component)) {
+            this.error(`--component must be 'face' or a component position such as 1 (got '${flags.component}').`);
+        }
         let data;
         try {
             data = await client.get(`/v1/faces/${args.face_id}/neighbors`, { params });
         }
         catch (err) {
-            if (err instanceof FacesAPIError)
+            if (err instanceof FacesAPIError) {
+                // A face with nothing at that position is an empty answer, not a failure:
+                // it mirrors the null at the same index in face:diff. Say so plainly and
+                // exit clean, so a caller can tell "nothing here" from "something broke".
+                if (err.statusCode === 422 && /has no (data for component position|centroid)/.test(err.message)) {
+                    if (!this.jsonEnabled())
+                        this.log(err.message);
+                    return { face: args.face_id, component: flags.component, direction: flags.direction, neighbors: [], reason: err.message };
+                }
                 this.error(`Error (${err.statusCode}): ${err.message}`);
+            }
             throw err;
         }
         if (!this.jsonEnabled()) {
             const res = data;
             const label = res.direction === 'nearest' ? 'Nearest' : 'Most dissimilar';
-            this.log(`${label} neighbors to ${res.face} (by ${res.component}):`);
+            const by = res.component === 'face' ? 'overall similarity' : `component ${res.component}`;
+            this.log(`${label} neighbors to ${res.face} (by ${by}):`);
             this.log('');
             if (res.neighbors.length === 0) {
                 this.log('  (none)');