faces-cli 1.7.7 → 1.7.9

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

@@ -1,10 +1,11 @@
 import { BaseCommand } from '../../../base.js';
 export default class CompileDoc extends BaseCommand {
     static description: string;
+    static examples: string[];
     static flags: {
         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>;
+        file: 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>;
@@ -16,4 +17,10 @@ export default class CompileDoc extends BaseCommand {
         face_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<unknown>;
+    /**
+     * `documents` is always present and always in input order. For a single
+     * source the compiled/started body is also spread at the top level, so
+     * callers that already read `.document_id` keep working.
+     */
+    private shape;
 }

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

@@ -1,21 +1,28 @@
 import { Args, Flags } from '@oclif/core';
 import fs from 'node:fs';
+import path from 'node:path';
 import { BaseCommand } from '../../../base.js';
 import { FacesAPIError } from '../../../client.js';
 import { pollCompileProgress } from '../../../poll.js';
 export default class CompileDoc extends BaseCommand {
-    static description = 'Compile a document into a face (create → make in one step)';
+    static description = 'Compile one or more documents into a face (create → make in one step). ' +
+        'Repeat --file to submit several documents in a single command; each file becomes its own ' +
+        'document rather than being concatenated.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> alice --file notes.txt',
+        '<%= config.bin %> <%= command.id %> alice --file a.txt --file b.txt --file c.txt --no-wait --json',
+    ];
     static flags = {
         ...BaseCommand.baseFlags,
-        label: Flags.string({ description: 'Document label/title' }),
-        content: Flags.string({ description: 'Inline text content' }),
-        file: Flags.string({ description: 'Read content from file' }),
+        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 }),
         perspective: Flags.string({
             description: 'Perspective',
             options: ['first-person', 'third-person'],
             default: 'first-person',
         }),
-        timeout: Flags.integer({ description: 'Compile timeout in seconds (default: 600)', default: 600 }),
+        timeout: Flags.integer({ description: 'Compile timeout in seconds, per document (default: 600)', default: 600 }),
         'no-wait': Flags.boolean({
             description: 'Create and trigger compilation, then return immediately without polling.',
             default: false,
@@ -28,79 +35,181 @@ export default class CompileDoc extends BaseCommand {
         const { args, flags } = await this.parse(CompileDoc);
         const client = this.makeClient(flags);
         const json = this.jsonEnabled();
-        // Resolve content
-        let content = flags.content;
-        if (flags.file) {
-            if (!fs.existsSync(flags.file))
-                this.error(`File not found: ${flags.file}`);
-            content = fs.readFileSync(flags.file, 'utf8');
-        }
-        if (!content)
+        const files = flags.file ?? [];
+        if (files.length === 0 && !flags.content)
             this.error('Provide --content or --file.');
-        // Step 1: Create document
-        if (!json)
-            process.stderr.write('Creating document... ');
-        let doc;
-        try {
-            const payload = { alias: args.face_id, content };
-            if (flags.label)
-                payload.label = flags.label;
-            if (flags.perspective)
-                payload.perspective = flags.perspective;
-            doc = await client.post('/v1/compile/documents', { body: payload });
-        }
-        catch (err) {
-            if (err instanceof FacesAPIError)
-                this.error(`Error (${err.statusCode}): ${err.message}`);
-            throw err;
+        if (flags.label && files.length > 1) {
+            this.error('--label applies to a single document. With several --file flags each document is labelled by its filename.');
         }
-        const docId = (doc.document_id ?? doc.id);
-        if (!json)
-            process.stderr.write(`done (${docId})\n`);
-        // Step 2: Make (prepare + sync in one call, returns 202)
-        let makeResponse;
-        try {
-            makeResponse = await client.post(`/v1/compile/documents/${docId}/make`);
+        // Read every source up front, keeping failures in place rather than
+        // collecting them separately — results must come back in input order so a
+        // caller can line them up against what it passed. A file that cannot be
+        // used is a per-file failure, not a reason to abandon the files that are
+        // fine: a whole-call failure leaves the caller unable to tell which file
+        // was at fault.
+        const sources = files.map((file) => {
+            try {
+                return { name: file, content: readTextFile(file) };
+            }
+            catch (err) {
+                return { name: file, readError: err instanceof Error ? err.message : String(err) };
+            }
+        });
+        if (flags.content)
+            sources.push({ name: '(--content)', content: flags.content });
+        const results = [];
+        const multi = files.length > 1;
+        const started = [];
+        for (const source of sources) {
+            if (source.readError !== undefined) {
+                results.push({ file: source.name, error: source.readError });
+                continue;
+            }
+            try {
+                const payload = { alias: args.face_id, content: source.content };
+                if (flags.label)
+                    payload.label = flags.label;
+                else if (multi)
+                    payload.label = path.basename(source.name);
+                if (flags.perspective)
+                    payload.perspective = flags.perspective;
+                if (!json)
+                    process.stderr.write(`Creating document${multi ? ` (${source.name})` : ''}... `);
+                const doc = (await client.post('/v1/compile/documents', { body: payload }));
+                const docId = String(doc.document_id ?? doc.id ?? '');
+                if (!docId)
+                    throw new Error('Server did not return a document_id');
+                if (!json)
+                    process.stderr.write(`done (${docId})\n`);
+                const makeResponse = (await client.post(`/v1/compile/documents/${docId}/make`));
+                const chunksTotal = makeResponse.chunks_total;
+                started.push({ source, docId, chunksTotal });
+                results.push({ file: source.name, document_id: docId, chunks_total: chunksTotal });
+            }
+            catch (err) {
+                if (!json)
+                    process.stderr.write('failed\n');
+                const message = err instanceof FacesAPIError ? `Error (${err.statusCode}): ${err.message}` : err instanceof Error ? err.message : String(err);
+                results.push({ file: source.name, error: message });
+            }
         }
-        catch (err) {
-            if (err instanceof FacesAPIError)
-                this.error(`Error (${err.statusCode}): ${err.message}`);
-            throw err;
+        if (started.length === 0) {
+            // Nothing was accepted — report every reason, then fail.
+            for (const r of results)
+                if (r.error)
+                    process.stderr.write(`${r.file}: ${r.error}\n`);
+            this.error(results.length === 1 ? 'Document was not accepted.' : 'No documents were accepted.');
         }
-        const chunksTotal = makeResponse.chunks_total;
+        if (!json)
+            for (const r of results)
+                if (r.error)
+                    process.stderr.write(`${r.file}: ${r.error}\n`);
         if (flags['no-wait']) {
             if (!json) {
-                process.stderr.write(`Compilation started in background${chunksTotal ? ` (${chunksTotal} chunks)` : ''}.\n`);
-                process.stderr.write(`Poll with: faces compile:doc:get ${docId} --json\n`);
+                for (const s of started) {
+                    process.stderr.write(`Compilation started in background${s.chunksTotal ? ` (${s.chunksTotal} chunks)` : ''}: ${s.docId}\n`);
+                }
+                process.stderr.write(`Poll with: faces compile:doc:get <id> --json\n`);
             }
-            return makeResponse;
+            return this.shape(results);
         }
-        if (!json)
-            process.stderr.write(`Compiling${chunksTotal ? ` (${chunksTotal} chunks)` : ''}:\n`);
-        // Step 3: Poll until synced
-        let result;
-        try {
-            result = await pollCompileProgress(client, docId, {
-                timeoutMs: flags.timeout * 1000,
-                onProgress: (p) => {
-                    if (!json) {
+        for (const s of started) {
+            if (!json)
+                process.stderr.write(`Compiling ${multi ? `${s.source.name} ` : ''}${s.chunksTotal ? `(${s.chunksTotal} chunks)` : ''}:\n`);
+            try {
+                const result = (await pollCompileProgress(client, s.docId, {
+                    timeoutMs: flags.timeout * 1000,
+                    onProgress: (p) => {
+                        if (json)
+                            return;
                         const c = p.current_counts;
                         const counts = c ? `ε=${c.epsilon} β=${c.beta} δ=${c.delta} α=${c.alpha}` : '';
                         const phase = p.prepare_status === 'syncing' ? ' (syncing)' : '';
                         process.stderr.write(`  [${p.chunks_completed ?? '?'}/${p.chunks_total ?? '?'}] ${counts}${phase}\n`);
-                    }
-                },
-            });
-        }
-        catch (err) {
-            if (err instanceof Error)
-                this.error(err.message);
-            throw err;
+                    },
+                }));
+                const hit = results.find((r) => r.document_id === s.docId);
+                if (hit)
+                    hit.compiled = result;
+            }
+            catch (err) {
+                const hit = results.find((r) => r.document_id === s.docId);
+                if (hit)
+                    hit.error = err instanceof Error ? err.message : String(err);
+                if (!json)
+                    process.stderr.write(`${s.source.name}: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
         }
         if (!json)
             process.stderr.write('Done.\n');
-        if (json)
-            this.log(JSON.stringify(result, null, 2));
-        return result;
+        return this.shape(results);
+    }
+    /**
+     * `documents` is always present and always in input order. For a single
+     * source the compiled/started body is also spread at the top level, so
+     * callers that already read `.document_id` keep working.
+     */
+    shape(results) {
+        const documents = results.map((r) => {
+            const out = { file: r.file };
+            if (r.document_id)
+                out.document_id = r.document_id;
+            if (r.chunks_total !== undefined)
+                out.chunks_total = r.chunks_total;
+            if (r.error)
+                out.error = r.error;
+            return out;
+        });
+        const body = { documents };
+        if (results.length === 1) {
+            const only = results[0];
+            Object.assign(body, only.compiled ?? {}, only.document_id ? { document_id: only.document_id } : {});
+            if (only.chunks_total !== undefined && body.chunks_total === undefined)
+                body.chunks_total = only.chunks_total;
+            body.documents = documents;
+        }
+        return body;
     }
 }
+/** Extensions the compile-documents endpoint takes as inline text. */
+const BINARY_HINTS = {
+    '.pdf': 'PDF is supported, but not by this command — use: faces compile:upload <alias> --file <path> --kind document',
+    '.docx': 'Word documents are not supported. Convert it to text first (e.g. `textutil -convert txt file.docx` on macOS).',
+    '.doc': 'Word documents are not supported. Convert it to text first.',
+    '.pages': 'Pages documents are not supported. Export it as text or PDF first.',
+    '.rtf': 'RTF is not supported. Convert it to plain text first (e.g. `textutil -convert txt file.rtf`).',
+    '.key': 'Keynote files are not supported. Export the text first.',
+    '.pptx': 'PowerPoint files are not supported. Export the text first.',
+    '.xlsx': 'Excel files are not supported. Export as .csv first.',
+    '.zip': 'Archives are not supported. Extract it and pass the text files.',
+    '.epub': 'EPUB is not supported. Convert it to text first.',
+};
+/**
+ * Read a file as text, refusing binary before it reaches the API.
+ *
+ * `compile:doc` posts its content as a text field, so a binary file used to
+ * travel all the way to the server and come back as a 500 ("A string literal
+ * cannot contain NUL (0x00) characters") that named neither the file nor the
+ * cause. The NUL scan is the general check — the extension table only makes the
+ * message more useful for formats people actually try.
+ */
+function readTextFile(file) {
+    if (!fs.existsSync(file))
+        throw new Error(`File not found: ${file}`);
+    const stat = fs.statSync(file);
+    if (stat.isDirectory())
+        throw new Error(`Not a file: ${file}`);
+    // Extension first, and independent of the byte scan: a small PDF can contain
+    // no NUL at all and would otherwise be posted as mojibake. A known format
+    // always gets the answer for that format.
+    const hint = BINARY_HINTS[path.extname(file).toLowerCase()];
+    if (hint)
+        throw new Error(hint);
+    const buf = fs.readFileSync(file);
+    if (buf.includes(0))
+        throw new Error('Looks like a binary file, not text. Convert it to text first.');
+    const content = buf.toString('utf8');
+    if (content.trim() === '')
+        throw new Error('File is empty.');
+    return content;
+}

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

@@ -2,6 +2,8 @@ import { BaseCommand } from '../../../base.js';
 export default class CompileDocPause extends BaseCommand {
     static description: string;
     static flags: {
+        'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, 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>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -10,4 +12,5 @@ export default class CompileDocPause extends BaseCommand {
         doc_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<unknown>;
+    private report;
 }

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

@@ -1,10 +1,17 @@
-import { Args } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../../base.js';
 import { FacesAPIError } from '../../../client.js';
+import { pollUntilPaused } from '../../../poll.js';
 export default class CompileDocPause extends BaseCommand {
-    static description = 'Pause a running document compilation (preserves progress, resume with make)';
+    static description = 'Ask a running document compilation to stop (preserves progress, resume with make). ' +
+        'The compile stops at the next chunk boundary; this waits for it unless --no-wait.';
     static flags = {
         ...BaseCommand.baseFlags,
+        'no-wait': Flags.boolean({
+            description: 'Return as soon as the pause is accepted, without waiting for the compile to stop.',
+            default: false,
+        }),
+        timeout: Flags.integer({ description: 'Seconds to wait for the compile to stop (default: 60)', default: 60 }),
     };
     static args = {
         doc_id: Args.string({ description: 'Document ID', required: true }),
@@ -12,6 +19,7 @@ export default class CompileDocPause extends BaseCommand {
     async run() {
         const { args, flags } = await this.parse(CompileDocPause);
         const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
         let data;
         try {
             data = await client.post(`/v1/compile/documents/${args.doc_id}/pause`);
@@ -21,9 +29,48 @@ export default class CompileDocPause extends BaseCommand {
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        if (!this.jsonEnabled()) {
-            this.log(`Paused. Resume with: faces compile:doc:make ${args.doc_id}`);
+        // POST /pause only acknowledges the request — it answers "pausing", not
+        // "paused". Reporting it as stopped here would be a guess, and before the
+        // backend fix it was usually a wrong one. prepare_status is the authority.
+        if (flags['no-wait']) {
+            if (!json) {
+                process.stderr.write(`Pausing. Poll with: faces compile:doc:get ${args.doc_id} --json\n`);
+            }
+            return data;
+        }
+        if (!json)
+            process.stderr.write('Pausing');
+        const status = await pollUntilPaused(client, args.doc_id, {
+            timeoutMs: flags.timeout * 1000,
+            onTick: () => {
+                if (!json && process.stderr.isTTY)
+                    process.stderr.write('.');
+            },
+        });
+        if (!json)
+            process.stderr.write('\n');
+        if (!json)
+            this.log(this.report(status, args.doc_id, flags.timeout));
+        return { ...data, prepare_status: status ?? null };
+    }
+    report(status, id, timeout) {
+        switch (status) {
+            case 'paused': {
+                return `Paused. Resume with: faces compile:doc:make ${id}`;
+            }
+            case 'synced':
+            case 'ready': {
+                return 'Compile finished before the pause took effect — nothing to resume.';
+            }
+            case 'failed': {
+                return 'Compile failed before the pause took effect.';
+            }
+            case null: {
+                return 'Stopped — the compile is no longer running.';
+            }
+            default: {
+                return `Still stopping after ${timeout}s. Poll with: faces compile:doc:get ${id} --json`;
+            }
         }
-        return data;
     }
 }

package/dist/commands/compile/thread/pause.d.ts

@@ -2,6 +2,8 @@ import { BaseCommand } from '../../../base.js';
 export default class CompileThreadPause extends BaseCommand {
     static description: string;
     static flags: {
+        'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, 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>;
         'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -10,4 +12,5 @@ export default class CompileThreadPause extends BaseCommand {
         thread_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     run(): Promise<unknown>;
+    private report;
 }

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

@@ -1,10 +1,17 @@
-import { Args } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../../../base.js';
 import { FacesAPIError } from '../../../client.js';
+import { pollUntilPaused } from '../../../poll.js';
 export default class CompileThreadPause extends BaseCommand {
-    static description = 'Pause a running thread compilation (preserves progress, resume with make)';
+    static description = 'Ask a running thread compilation to stop (preserves progress, resume with make). ' +
+        'The compile stops at the next chunk boundary; this waits for it unless --no-wait.';
     static flags = {
         ...BaseCommand.baseFlags,
+        'no-wait': Flags.boolean({
+            description: 'Return as soon as the pause is accepted, without waiting for the compile to stop.',
+            default: false,
+        }),
+        timeout: Flags.integer({ description: 'Seconds to wait for the compile to stop (default: 60)', default: 60 }),
     };
     static args = {
         thread_id: Args.string({ description: 'Thread ID', required: true }),
@@ -12,6 +19,7 @@ export default class CompileThreadPause extends BaseCommand {
     async run() {
         const { args, flags } = await this.parse(CompileThreadPause);
         const client = this.makeClient(flags);
+        const json = this.jsonEnabled();
         let data;
         try {
             data = await client.post(`/v1/compile/threads/${args.thread_id}/pause`);
@@ -21,9 +29,49 @@ export default class CompileThreadPause extends BaseCommand {
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        if (!this.jsonEnabled()) {
-            this.log(`Paused. Resume with: faces compile:thread:make ${args.thread_id}`);
+        // POST /pause only acknowledges the request — it answers "pausing", not
+        // "paused". Reporting it as stopped here would be a guess, and before the
+        // backend fix it was usually a wrong one. prepare_status is the authority.
+        if (flags['no-wait']) {
+            if (!json) {
+                process.stderr.write(`Pausing. Poll with: faces compile:thread:get ${args.thread_id} --json\n`);
+            }
+            return data;
+        }
+        if (!json)
+            process.stderr.write('Pausing');
+        const status = await pollUntilPaused(client, args.thread_id, {
+            endpoint: `/v1/compile/threads/${args.thread_id}`,
+            timeoutMs: flags.timeout * 1000,
+            onTick: () => {
+                if (!json && process.stderr.isTTY)
+                    process.stderr.write('.');
+            },
+        });
+        if (!json)
+            process.stderr.write('\n');
+        if (!json)
+            this.log(this.report(status, args.thread_id, flags.timeout));
+        return { ...data, prepare_status: status ?? null };
+    }
+    report(status, id, timeout) {
+        switch (status) {
+            case 'paused': {
+                return `Paused. Resume with: faces compile:thread:make ${id}`;
+            }
+            case 'synced':
+            case 'ready': {
+                return 'Compile finished before the pause took effect — nothing to resume.';
+            }
+            case 'failed': {
+                return 'Compile failed before the pause took effect.';
+            }
+            case null: {
+                return 'Stopped — the compile is no longer running.';
+            }
+            default: {
+                return `Still stopping after ${timeout}s. Poll with: faces compile:thread:get ${id} --json`;
+            }
         }
-        return data;
     }
 }

package/dist/poll.d.ts

@@ -30,3 +30,24 @@ export interface PollOptions {
  * Throws on timeout or failure.
  */
 export declare function pollCompileProgress(client: FacesClient, id: string, opts?: PollOptions): Promise<unknown>;
+export interface PausePollOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    onTick?: () => void;
+    /** Override the GET endpoint path. Defaults to /v1/compile/documents/{id}. */
+    endpoint?: string;
+}
+/**
+ * Wait for a pause request to actually land.
+ *
+ * POST /pause only acknowledges the request — it returns `status: "pausing"` and
+ * the compile stops at the next chunk boundary, usually within a few seconds.
+ * `prepare_status` on the document is the authority on whether it has stopped.
+ *
+ * Returns that final status: `paused` when the pause landed, `synced`/`ready`
+ * when the compile finished before it could (a normal race, not an error),
+ * `failed` if it died, or null when nothing was running. Returns undefined if
+ * the timeout expires while it is still stopping — the pause was accepted
+ * either way, so callers should report rather than fail.
+ */
+export declare function pollUntilPaused(client: FacesClient, id: string, opts?: PausePollOptions): Promise<string | null | undefined>;

package/dist/poll.js

@@ -39,3 +39,37 @@ export async function pollCompileProgress(client, id, opts = {}) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Statuses that mean the compile is no longer running. `paused` is the outcome a
+ * pause is waiting for; the rest mean it stopped for some other reason first.
+ */
+const PAUSE_TERMINAL = new Set(['paused', 'synced', 'ready', 'failed']);
+/**
+ * Wait for a pause request to actually land.
+ *
+ * POST /pause only acknowledges the request — it returns `status: "pausing"` and
+ * the compile stops at the next chunk boundary, usually within a few seconds.
+ * `prepare_status` on the document is the authority on whether it has stopped.
+ *
+ * Returns that final status: `paused` when the pause landed, `synced`/`ready`
+ * when the compile finished before it could (a normal race, not an error),
+ * `failed` if it died, or null when nothing was running. Returns undefined if
+ * the timeout expires while it is still stopping — the pause was accepted
+ * either way, so callers should report rather than fail.
+ */
+export async function pollUntilPaused(client, id, opts = {}) {
+    const interval = opts.intervalMs ?? 1000;
+    const timeout = opts.timeoutMs ?? 60_000;
+    const endpoint = opts.endpoint ?? `/v1/compile/documents/${id}`;
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+        await sleep(interval);
+        opts.onTick?.();
+        // status_only trims the body to the progress fields — this is a poll loop.
+        const data = await client.get(`${endpoint}?status_only=true`);
+        const status = data.prepare_status ?? null;
+        if (status === null || PAUSE_TERMINAL.has(status))
+            return status;
+    }
+    return undefined;
+}

package/oclif.manifest.json

@@ -632,10 +632,10 @@
         "whoami.js"
       ]
     },
-    "catalog:backup": {
+    "billing:balance": {
       "aliases": [],
       "args": {},
-      "description": "Snapshot all faces, teams, and source material for migration",
+      "description": "Show credit balance and payment method status",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -671,7 +671,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "catalog:backup",
+      "id": "billing:balance",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -681,14 +681,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "catalog",
-        "backup.js"
+        "billing",
+        "balance.js"
       ]
     },
-    "catalog:doctor": {
+    "billing:card-setup": {
       "aliases": [],
       "args": {},
-      "description": "Diagnose and repair the local face and team catalog",
+      "description": "Get a Stripe card setup URL to save a payment method",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -720,23 +720,11 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "fix": {
-          "description": "Rebuild missing or stale catalog entries from API",
-          "name": "fix",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "generate": {
-          "description": "Fix + generate missing descriptions via LLM",
-          "name": "generate",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "catalog:doctor",
+      "id": "billing:card-setup",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -746,14 +734,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "catalog",
-        "doctor.js"
+        "billing",
+        "card-setup.js"
       ]
     },
-    "catalog:list": {
+    "billing:llm-costs": {
       "aliases": [],
       "args": {},
-      "description": "List all faces in the local catalog",
+      "description": "List available LLMs and their per-token costs",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -785,11 +773,18 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "provider": {
+          "description": "Filter by provider (e.g. openai, anthropic)",
+          "name": "provider",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "catalog:list",
+      "id": "billing:llm-costs",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -799,14 +794,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "catalog",
-        "list.js"
+        "billing",
+        "llm-costs.js"
       ]
     },
-    "catalog:manyfaced": {
+    "billing:topup": {
       "aliases": [],
       "args": {},
-      "description": "Browse and install community manyfaced skills from github.com/facessh/manyfaced",
+      "description": "Top up credit balance using saved payment method",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -839,37 +834,25 @@
           "multiple": false,
           "type": "option"
         },
-        "skill": {
-          "description": "Show details for a specific skill",
-          "name": "skill",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "install": {
-          "description": "Install a skill by name",
-          "name": "install",
+        "amount": {
+          "description": "Top-up amount in USD (min $1)",
+          "name": "amount",
+          "required": true,
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "skills-dir": {
-          "description": "Directory to install skills into (required for --install)",
-          "name": "skills-dir",
+        "payment-ref": {
+          "description": "Payment reference (admin/test path)",
+          "name": "payment-ref",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "refresh": {
-          "description": "Force refresh the skill index (ignore cache)",
-          "name": "refresh",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "catalog:manyfaced",
+      "id": "billing:topup",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -879,19 +862,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "catalog",
-        "manyfaced.js"
+        "billing",
+        "topup.js"
       ]
     },
-    "catalog:restore": {
+    "billing:usage": {
       "aliases": [],
-      "args": {
-        "file": {
-          "description": "Backup file path (default: most recent in ~/.faces/backups/)",
-          "name": "file"
-        }
-      },
-      "description": "Restore faces, teams, and source material from a backup snapshot",
+      "args": {},
+      "description": "Aggregated usage analytics",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -924,16 +902,37 @@
           "multiple": false,
           "type": "option"
         },
-        "compile": {
-          "description": "Run compile:all after restoring",
-          "name": "compile",
-          "allowNo": false,
-          "type": "boolean"
+        "group-by": {
+          "description": "Group results",
+          "name": "group-by",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "api_key",
+            "model",
+            "llm",
+            "date"
+          ],
+          "type": "option"
+        },
+        "from": {
+          "description": "Start date (YYYY-MM-DD)",
+          "name": "from",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "to": {
+          "description": "End date (YYYY-MM-DD)",
+          "name": "to",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "catalog:restore",
+      "id": "billing:usage",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -943,14 +942,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "catalog",
-        "restore.js"
+        "billing",
+        "usage.js"
       ]
     },
-    "billing:balance": {
+    "catalog:backup": {
       "aliases": [],
       "args": {},
-      "description": "Show credit balance and payment method status",
+      "description": "Snapshot all faces, teams, and source material for migration",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -986,7 +985,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "billing:balance",
+      "id": "catalog:backup",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -996,14 +995,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "billing",
-        "balance.js"
+        "catalog",
+        "backup.js"
       ]
     },
-    "billing:card-setup": {
+    "catalog:doctor": {
       "aliases": [],
       "args": {},
-      "description": "Get a Stripe card setup URL to save a payment method",
+      "description": "Diagnose and repair the local face and team catalog",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -1035,11 +1034,23 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "fix": {
+          "description": "Rebuild missing or stale catalog entries from API",
+          "name": "fix",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "generate": {
+          "description": "Fix + generate missing descriptions via LLM",
+          "name": "generate",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "billing:card-setup",
+      "id": "catalog:doctor",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -1049,14 +1060,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "billing",
-        "card-setup.js"
+        "catalog",
+        "doctor.js"
       ]
     },
-    "billing:llm-costs": {
+    "catalog:list": {
       "aliases": [],
       "args": {},
-      "description": "List available LLMs and their per-token costs",
+      "description": "List all faces in the local catalog",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -1088,18 +1099,11 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "provider": {
-          "description": "Filter by provider (e.g. openai, anthropic)",
-          "name": "provider",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "billing:llm-costs",
+      "id": "catalog:list",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -1109,14 +1113,14 @@
       "relativePath": [
         "dist",
         "commands",
-        "billing",
-        "llm-costs.js"
+        "catalog",
+        "list.js"
       ]
     },
-    "billing:topup": {
+    "catalog:manyfaced": {
       "aliases": [],
       "args": {},
-      "description": "Top up credit balance using saved payment method",
+      "description": "Browse and install community manyfaced skills from github.com/facessh/manyfaced",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -1149,25 +1153,37 @@
           "multiple": false,
           "type": "option"
         },
-        "amount": {
-          "description": "Top-up amount in USD (min $1)",
-          "name": "amount",
-          "required": true,
+        "skill": {
+          "description": "Show details for a specific skill",
+          "name": "skill",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "payment-ref": {
-          "description": "Payment reference (admin/test path)",
-          "name": "payment-ref",
+        "install": {
+          "description": "Install a skill by name",
+          "name": "install",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "skills-dir": {
+          "description": "Directory to install skills into (required for --install)",
+          "name": "skills-dir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "refresh": {
+          "description": "Force refresh the skill index (ignore cache)",
+          "name": "refresh",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "billing:topup",
+      "id": "catalog:manyfaced",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -1177,14 +1193,19 @@
       "relativePath": [
         "dist",
         "commands",
-        "billing",
-        "topup.js"
+        "catalog",
+        "manyfaced.js"
       ]
     },
-    "billing:usage": {
+    "catalog:restore": {
       "aliases": [],
-      "args": {},
-      "description": "Aggregated usage analytics",
+      "args": {
+        "file": {
+          "description": "Backup file path (default: most recent in ~/.faces/backups/)",
+          "name": "file"
+        }
+      },
+      "description": "Restore faces, teams, and source material from a backup snapshot",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -1217,37 +1238,16 @@
           "multiple": false,
           "type": "option"
         },
-        "group-by": {
-          "description": "Group results",
-          "name": "group-by",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "api_key",
-            "model",
-            "llm",
-            "date"
-          ],
-          "type": "option"
-        },
-        "from": {
-          "description": "Start date (YYYY-MM-DD)",
-          "name": "from",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "to": {
-          "description": "End date (YYYY-MM-DD)",
-          "name": "to",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "compile": {
+          "description": "Run compile:all after restoring",
+          "name": "compile",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "billing:usage",
+      "id": "catalog:restore",
       "pluginAlias": "faces-cli",
       "pluginName": "faces-cli",
       "pluginType": "core",
@@ -1257,8 +1257,8 @@
       "relativePath": [
         "dist",
         "commands",
-        "billing",
-        "usage.js"
+        "catalog",
+        "restore.js"
       ]
     },
     "chat:chat": {
@@ -4499,7 +4499,11 @@
           "required": true
         }
       },
-      "description": "Compile a document into a face (create → make in one step)",
+      "description": "Compile one or more documents into a face (create → make in one step). Repeat --file to submit several documents in a single command; each file becomes its own document rather than being concatenated.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> alice --file notes.txt",
+        "<%= config.bin %> <%= command.id %> alice --file a.txt --file b.txt --file c.txt --no-wait --json"
+      ],
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -4533,7 +4537,7 @@
           "type": "option"
         },
         "label": {
-          "description": "Document label/title",
+          "description": "Document label/title (single document only; with several files each is labelled by its filename)",
           "name": "label",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -4541,16 +4545,19 @@
         },
         "content": {
           "description": "Inline text content",
+          "exclusive": [
+            "file"
+          ],
           "name": "content",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "file": {
-          "description": "Read content from file",
+          "description": "Read content from file (repeatable — each file becomes its own document)",
           "name": "file",
           "hasDynamicHelp": false,
-          "multiple": false,
+          "multiple": true,
           "type": "option"
         },
         "perspective": {
@@ -4566,7 +4573,7 @@
           "type": "option"
         },
         "timeout": {
-          "description": "Compile timeout in seconds (default: 600)",
+          "description": "Compile timeout in seconds, per document (default: 600)",
           "name": "timeout",
           "default": 600,
           "hasDynamicHelp": false,
@@ -4740,7 +4747,7 @@
           "required": true
         }
       },
-      "description": "Pause a running document compilation (preserves progress, resume with make)",
+      "description": "Ask a running document compilation to stop (preserves progress, resume with make). The compile stops at the next chunk boundary; this waits for it unless --no-wait.",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -4772,6 +4779,20 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "no-wait": {
+          "description": "Return as soon as the pause is accepted, without waiting for the compile to stop.",
+          "name": "no-wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Seconds to wait for the compile to stop (default: 60)",
+          "name": "timeout",
+          "default": 60,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -5348,7 +5369,7 @@
           "required": true
         }
       },
-      "description": "Pause a running thread compilation (preserves progress, resume with make)",
+      "description": "Ask a running thread compilation to stop (preserves progress, resume with make). The compile stops at the next chunk boundary; this waits for it unless --no-wait.",
       "flags": {
         "json": {
           "description": "Format output as json.",
@@ -5380,6 +5401,20 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "no-wait": {
+          "description": "Return as soon as the pause is accepted, without waiting for the compile to stop.",
+          "name": "no-wait",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Seconds to wait for the compile to stop (default: 60)",
+          "name": "timeout",
+          "default": 60,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -6102,5 +6137,5 @@
       ]
     }
   },
-  "version": "1.7.7"
+  "version": "1.7.9"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faces-cli",
-  "version": "1.7.7",
+  "version": "1.7.9",
   "description": "CLI for the Faces AI platform",
   "type": "module",
   "author": "sybileak <sybileak@proton.me>",