coolhand-cli 0.11.1 → 0.13.0

package/dist/cli.js

@@ -9,13 +9,22 @@ import { run as runClients } from './commands/clients.js';
 import { run as runSearchOptimizations } from './commands/search-optimizations.js';
 import { run as runGetOptimization } from './commands/get-optimization.js';
 import { run as runCloseOptimization } from './commands/close-optimization.js';
+import { run as runUpdate } from './commands/update.js';
+import { run as runAutoUpdate, maybeAutoUpdate } from './auto-update/index.js';
 import { run as runUpdateOptimization } from './commands/update-optimization.js';
 import { run as runWildcard } from './commands/wildcard.js';
+import { run as runCaptureTurn } from './commands/capture-turn.js';
+import { isCaptureDisabled } from './hooks/disabled.js';
+import { logHookEvent } from './hooks/hook-log.js';
+import { HOOK_AGENTS } from './hooks/types.js';
 import { run as runClaude } from './commands/claude.js';
 import { run as runMonitor } from './commands/monitor.js';
 import { run as runAnalyzeClaudeSessions } from './commands/analyze-claude-sessions.js';
 import { run as runMapClaudeProjects } from './commands/map-claude-projects.js';
 import { run as runUploadClientFile } from './commands/upload-client-file.js';
+import { run as runListClientFiles } from './commands/list-client-files.js';
+import { run as runDownloadClientFile } from './commands/download-client-file.js';
+import { run as runUpdateClientFile } from './commands/update-client-file.js';
 import { run as runSyncSkills } from './commands/sync-skills.js';
 import { run as runListWorkloads } from './commands/list-workloads.js';
 import { run as runGetWorkload } from './commands/get-workload.js';
@@ -23,15 +32,20 @@ import { run as runUpdateWorkload } from './commands/update-workload.js';
 import { run as runFetchLog } from './commands/fetch-log.js';
 import { run as runSearchLogs } from './commands/search-logs.js';
 import { run as runSearchTemplates } from './commands/search-templates.js';
+import { run as runSearchWorkloads } from './commands/search-workloads.js';
 import { run as runGetTemplate } from './commands/get-template.js';
 import { run as runFlushPending, spawnBackgroundFlush } from './commands/flush-pending.js';
 import { run as runSearchFeedback } from './commands/search-feedback.js';
 import { run as runGetFeedback } from './commands/get-feedback.js';
+import { run as runSearchHelpArticles } from './commands/search-help-articles.js';
+import { run as runGetHelpArticle } from './commands/get-help-article.js';
+import { run as runListHelpCategories } from './commands/list-help-categories.js';
+import { run as runLinkFeedback } from './commands/link-feedback.js';
 import { run as runSearchReferencedFiles } from './commands/search-referenced-files.js';
 import { run as runListReferencedFileSessions } from './commands/list-referenced-file-sessions.js';
 import { countPending, flushFailed } from './pending-store.js';
 import { confirm } from './prompt.js';
-const BOOLEAN_FLAGS = new Set(['all', 'help', 'h', 'json', 'version', 'v', 'dry-run', 'include-archived', 'include-system', 'include-templates', 'full', 'matched', 'unmatched', 'include-thinking', 'unmatched-only', 'include-prompts', 'include-deprecated', 'force']);
+const BOOLEAN_FLAGS = new Set(['all', 'help', 'h', 'json', 'version', 'v', 'dry-run', 'include-archived', 'include-system', 'include-templates', 'full', 'matched', 'unmatched', 'include-thinking', 'unmatched-only', 'include-prompts', 'include-total', 'include-metrics', 'no-metrics', 'include-deprecated', 'force', 'check', 'anonymous', 'no-declare']);
 /** Flags whose repeated occurrences accumulate into an array instead of overwriting. */
 const REPEATABLE_FLAGS = new Set(['project', 'exclude-project', 'skill', 'exclude-skill', 'source']);
 const COMMANDS = [
@@ -67,6 +81,15 @@ const COMMANDS = [
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
     },
+    {
+        name: 'update',
+        oneLiner: 'Upgrade to the newest stable release that is at least 48 hours old',
+        usage: 'coolhand update [options]',
+        options: [
+            { flag: '--check', description: 'Report the available version without installing it' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
     {
         name: 'whoami',
         oneLiner: 'Show the currently configured client',
@@ -152,6 +175,20 @@ const COMMANDS = [
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
     },
+    {
+        name: 'capture-turn',
+        oneLiner: 'Agent hook: send the turn that just finished, with the conversation so far, to Coolhand',
+        usage: 'coolhand capture-turn --agent claude|copilot [--skill NAME] [options]   (reads the hook JSON on stdin)',
+        options: [
+            { flag: '--agent claude|copilot', description: 'Which agent is calling the hook (required)' },
+            { flag: '--skill NAME', description: 'Skill that enabled the hook; sent as metadata (required for --agent copilot, which sends only chats that invoked it)' },
+            { flag: '--api-key KEY', description: 'Public API key only, never a private key (or set COOLHAND_API_KEY). No login needed' },
+            { flag: '--base-url URL', description: 'Coolhand base URL (default: https://coolhandlabs.com)' },
+            { flag: '--skill-version V', description: "The skill's version; sent as metadata.skill_version" },
+            { flag: '--no-declare', description: "Don't declare a workload for the skill (by default `--skill NAME` declares one workload per skill)" },
+            { flag: '--anonymous', description: 'Anonymous machine id instead of the git email or COOLHAND_CAPTURE_USER; also omits the working directory' },
+        ],
+    },
     {
         name: 'search-feedback',
         oneLiner: 'Search and filter feedback records (requires a private key)',
@@ -172,6 +209,17 @@ const COMMANDS = [
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
     },
+    {
+        name: 'link-feedback',
+        oneLiner: 'Link feedback records to an optimization in bulk (requires a private key)',
+        usage: 'coolhand link-feedback <optimization-id> [feedback-id...] [--file PATH|--file=-] [--note TEXT] [options]',
+        options: [
+            { flag: '--file PATH', description: 'Read feedback ids from a file (whitespace/comma separated); use --file=- for stdin' },
+            { flag: '--note TEXT', description: 'Note attached to every link created' },
+            { flag: '--client-id ID', description: 'Use a specific stored client' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
     {
         name: 'get-feedback',
         oneLiner: 'Get a single feedback record by ID (requires a private key)',
@@ -222,6 +270,40 @@ const COMMANDS = [
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
     },
+    {
+        name: 'list-client-files',
+        oneLiner: "List the client's uploaded files, newest first (requires a client admin's private key)",
+        usage: 'coolhand list-client-files [options]',
+        options: [
+            { flag: '--status VALUE', description: 'Filter by status: draft, published, or archived' },
+            { flag: '--file-type TYPE', description: 'Filter by type: slide_deck, report, or document' },
+            { flag: '--page N', description: 'Page number (default: 1)' },
+            { flag: '--per-page N', description: 'Results per page (default: 25, max: 100)' },
+            { flag: '--client-id ID', description: 'Use a specific stored client' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
+    {
+        name: 'download-client-file',
+        oneLiner: "Download a client file's contents to disk (requires a client admin's private key)",
+        usage: 'coolhand download-client-file <file-id> [options]',
+        options: [
+            { flag: '--output PATH', description: 'Where to write the file; a directory keeps the server-provided filename (default: that filename in the current directory)' },
+            { flag: '--force', description: 'Overwrite the destination if it already exists' },
+            { flag: '--client-id ID', description: 'Use a specific stored client' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
+    {
+        name: 'update-client-file',
+        oneLiner: "Change a client file's status (requires a client admin's private key)",
+        usage: 'coolhand update-client-file <file-id> --status <draft|published|archived> [options]',
+        options: [
+            { flag: '--status VALUE', description: 'New status: draft, published, or archived (required)' },
+            { flag: '--client-id ID', description: 'Use a specific stored client' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
     {
         name: 'sync-skills',
         oneLiner: 'Upload locally-built Claude skills (SKILL.md files) to Coolhand as client files',
@@ -318,8 +400,15 @@ const COMMANDS = [
             { flag: '--source-api VALUE', description: "Filter by source API (e.g. 'openai', 'anthropic', 'vertex')" },
             { flag: '--source-api-result VALUE', description: 'Filter by result status: success, failed, operational, unmatched' },
             { flag: '--unmatched-only', description: 'Only return logs with no assigned template' },
-            { flag: '--days-back N', description: 'Limit to logs created in the last N days (unrestricted if omitted)' },
+            { flag: '--source-application VALUE', description: 'Filter by exact source_application' },
+            { flag: '--project-path PATH', description: 'Filter by exact metadata.project_path' },
+            { flag: '--days-back N', description: 'Limit to logs created in the last N days (unrestricted if omitted; ignored with --since/--until)' },
+            { flag: '--since TS', description: 'Only logs created at or after this ISO8601 timestamp (replaces --days-back)' },
+            { flag: '--until TS', description: 'Only logs created before this ISO8601 timestamp (exclusive; must be after --since)' },
+            { flag: '--min-cost USD', description: 'Only logs whose cost is at least this many USD (unpriced logs are excluded; 0 is valid)' },
+            { flag: '--order VALUE', description: "Order by cost instead of --sort: 'cost_desc' (highest cost first)" },
             { flag: '--include-prompts', description: 'Include system_prompt and user_prompt in results (may be large)' },
+            { flag: '--include-total', description: 'Ask the backend to compute the exact total_count/total_pages instead of the cheaper lower-bound estimate (costs a COUNT(*) server-side; off by default)' },
             { flag: '--sort VALUE', description: "Sort expression, e.g. 'created_at desc' (default: newest first)" },
             { flag: '--page N', description: 'Page number (default: 1)' },
             { flag: '--per-page N', description: 'Results per page (default: 25, max: 100)' },
@@ -337,16 +426,44 @@ const COMMANDS = [
             { flag: '--status VALUE', description: 'Filter by status: draft, published, or failure' },
             { flag: '--include-deprecated', description: 'Include deprecated templates (hidden by default)' },
             { flag: '--include-system', description: "Include the 'Unmatched' and 'Ignored API Calls' system buckets (hidden by default) — inspect 'Unmatched' when logs are misrouting" },
+            { flag: '--include-metrics', description: 'Add a cost and performance metrics object to each template' },
+            { flag: '--days-back N', description: 'Metrics window: rolling N days ending now (server default 28, max 365; ignored with --since)' },
+            { flag: '--since TS', description: 'Metrics window start, ISO8601 (inclusive; overrides --days-back)' },
+            { flag: '--until TS', description: 'Metrics window end, ISO8601 (exclusive; defaults to now)' },
             { flag: '--page N', description: 'Page number (default: 1)' },
             { flag: '--per-page N', description: 'Results per page (default: 25, max: 100)' },
             { flag: '--client-id ID', description: 'Use a specific stored client' },
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
-    }, {
+    },
+    {
+        name: 'search-workloads',
+        oneLiner: 'List and search workloads, optionally with cost and performance metrics (requires a private key)',
+        usage: 'coolhand search-workloads [options]',
+        options: [
+            { flag: '--search TEXT', description: 'Case-insensitive substring to match in the workload name' },
+            { flag: '--include-archived', description: 'Include archived workloads (hidden by default)' },
+            { flag: '--include-system', description: "Include system workloads such as 'Unmatched' (hidden by default)" },
+            { flag: '--include-templates', description: "Add each workload's active templates and their routing patterns" },
+            { flag: '--include-metrics', description: 'Add a cost and performance metrics object to each workload' },
+            { flag: '--days-back N', description: 'Metrics window: rolling N days ending now (server default 28, max 365; ignored with --since)' },
+            { flag: '--since TS', description: 'Metrics window start, ISO8601 (inclusive; overrides --days-back)' },
+            { flag: '--until TS', description: 'Metrics window end, ISO8601 (exclusive; defaults to now)' },
+            { flag: '--page N', description: 'Page number (default: 1)' },
+            { flag: '--per-page N', description: 'Results per page (default: 25, max: 100)' },
+            { flag: '--client-id ID', description: 'Use a specific stored client' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
+    {
         name: 'get-template',
-        oneLiner: 'Get a single LLM request template by ID, including its prompt patterns (requires a private key)',
+        oneLiner: 'Get a single LLM request template by ID, including its prompt patterns and metrics (requires a private key)',
         usage: 'coolhand get-template <template-id> [options]',
         options: [
+            { flag: '--no-metrics', description: 'Omit the metrics object (included by default)' },
+            { flag: '--days-back N', description: 'Metrics window: rolling N days ending now (server default 28, max 365; ignored with --since)' },
+            { flag: '--since TS', description: 'Metrics window start, ISO8601 (inclusive; overrides --days-back)' },
+            { flag: '--until TS', description: 'Metrics window end, ISO8601 (exclusive; defaults to now)' },
             { flag: '--client-id ID', description: 'Use a specific stored client' },
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
@@ -375,6 +492,40 @@ const COMMANDS = [
             { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
         ],
     },
+    {
+        name: 'search-help-articles',
+        oneLiner: 'Search or list Coolhand help center articles (no login needed)',
+        usage: 'coolhand search-help-articles [query] [options]',
+        options: [
+            { flag: '--query TEXT', description: 'Relevance search: quoted phrases, -exclusions and "or" work (or pass it as positional text). Omit to list every article' },
+            { flag: '--category SLUG', description: 'Only articles in one section (see list-help-categories)' },
+            { flag: '--page N', description: 'Page number (default: 1)' },
+            { flag: '--per-page N', description: 'Results per page (default: 25, max: 100)' },
+            { flag: '--base-url URL', description: 'Read from another Coolhand server; the stored key is only sent to the server you logged in to' },
+            { flag: '--client-id ID', description: 'Use a specific stored client (optional — reads work anonymously)' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
+    {
+        name: 'get-help-article',
+        oneLiner: 'Read one help center article by slug, with its full markdown body (no login needed)',
+        usage: 'coolhand get-help-article <slug> [options]',
+        options: [
+            { flag: '--base-url URL', description: 'Read from another Coolhand server; the stored key is only sent to the server you logged in to' },
+            { flag: '--client-id ID', description: 'Use a specific stored client (optional — reads work anonymously)' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
+    {
+        name: 'list-help-categories',
+        oneLiner: 'List help center sections and their allowed tags (no login needed)',
+        usage: 'coolhand list-help-categories [options]',
+        options: [
+            { flag: '--base-url URL', description: 'Read from another Coolhand server; the stored key is only sent to the server you logged in to' },
+            { flag: '--client-id ID', description: 'Use a specific stored client (optional — reads work anonymously)' },
+            { flag: '--json', description: 'Emit JSON output instead of human-readable text' },
+        ],
+    },
     {
         name: 'help',
         oneLiner: 'Show this message or per-command help',
@@ -587,6 +738,16 @@ function logoutOptions(parsed) {
     }
     return opts;
 }
+function updateOptions(parsed) {
+    const opts = {};
+    if (parsed.flags.check === true) {
+        opts.check = true;
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
 function statusOptions(parsed) {
     const opts = {};
     if (typeof parsed.flags['client-id'] === 'string') {
@@ -934,6 +1095,145 @@ function fetchLogOptions(parsed) {
     }
     return opts;
 }
+const CLIENT_FILE_STATUSES = new Set(['draft', 'published', 'archived']);
+function parseClientFileStatus(raw) {
+    if (!CLIENT_FILE_STATUSES.has(raw)) {
+        throw new CliError('INVALID_ARGS', '--status must be one of: draft, published, archived');
+    }
+    return raw;
+}
+function listClientFilesOptions(parsed) {
+    const opts = {};
+    if (typeof parsed.flags['status'] === 'string') {
+        opts.status = parseClientFileStatus(parsed.flags['status']);
+    }
+    if (typeof parsed.flags['file-type'] === 'string') {
+        if (!CLIENT_FILE_TYPES.has(parsed.flags['file-type'])) {
+            throw new CliError('INVALID_ARGS', '--file-type must be one of: slide_deck, report, document');
+        }
+        opts.fileType = parsed.flags['file-type'];
+    }
+    if (typeof parsed.flags['page'] === 'string') {
+        const raw = parsed.flags['page'];
+        const n = parseInt(raw, 10);
+        if (!/^\d+$/.test(raw) || isNaN(n) || n < 1) {
+            throw new CliError('INVALID_ARGS', '--page must be a positive integer');
+        }
+        opts.page = n;
+    }
+    if (typeof parsed.flags['per-page'] === 'string') {
+        const raw = parsed.flags['per-page'];
+        const n = parseInt(raw, 10);
+        if (!/^\d+$/.test(raw) || isNaN(n) || n < 1 || n > 100) {
+            throw new CliError('INVALID_ARGS', '--per-page must be an integer between 1 and 100');
+        }
+        opts.perPage = n;
+    }
+    if (typeof parsed.flags['client-id'] === 'string') {
+        opts.clientId = parsed.flags['client-id'];
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
+function downloadClientFileOptions(parsed) {
+    const id = parsed.positional[0];
+    if (!id) {
+        throw new CliError('INVALID_ARGS', 'download-client-file requires a <file-id> argument');
+    }
+    const opts = { id };
+    if ('output' in parsed.flags) {
+        const v = parsed.flags['output'];
+        if (typeof v !== 'string' || v.length === 0) {
+            throw new CliError('INVALID_ARGS', '--output requires a path argument');
+        }
+        opts.output = v;
+    }
+    if (parsed.flags['force'] === true) {
+        opts.force = true;
+    }
+    if (typeof parsed.flags['client-id'] === 'string') {
+        opts.clientId = parsed.flags['client-id'];
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
+function updateClientFileOptions(parsed) {
+    const id = parsed.positional[0];
+    if (!id) {
+        throw new CliError('INVALID_ARGS', 'update-client-file requires a <file-id> argument');
+    }
+    const rawStatus = parsed.flags['status'];
+    if (typeof rawStatus !== 'string') {
+        throw new CliError('INVALID_ARGS', 'update-client-file requires --status (draft, published, or archived)');
+    }
+    const opts = { id, status: parseClientFileStatus(rawStatus) };
+    if (typeof parsed.flags['client-id'] === 'string') {
+        opts.clientId = parsed.flags['client-id'];
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
+/** Strict positive integer (`/^\d+$/`, `>= 1`), as `--days-back` has always been parsed. */
+function positiveIntFlag(parsed, name) {
+    const raw = parsed.flags[name];
+    if (raw === undefined) {
+        return undefined;
+    }
+    const n = typeof raw === 'string' ? parseInt(raw, 10) : NaN;
+    if (typeof raw !== 'string' || !/^\d+$/.test(raw) || isNaN(n) || n < 1) {
+        throw new CliError('INVALID_ARGS', `--${name} must be a positive integer`);
+    }
+    return n;
+}
+/** `--per-page`: strict integer between 1 and 100. */
+function perPageFlag(parsed) {
+    const raw = parsed.flags['per-page'];
+    if (raw === undefined) {
+        return undefined;
+    }
+    const n = typeof raw === 'string' ? parseInt(raw, 10) : NaN;
+    if (typeof raw !== 'string' || !/^\d+$/.test(raw) || isNaN(n) || n < 1 || n > 100) {
+        throw new CliError('INVALID_ARGS', '--per-page must be an integer between 1 and 100');
+    }
+    return n;
+}
+/**
+ * ISO8601 `--since`/`--until`: passed straight through, never parsed into a `Date` locally — the
+ * server validates it and a 422 surfaces as a `CliError` with its message.
+ */
+function timestampFlag(parsed, name) {
+    const raw = parsed.flags[name];
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw new CliError('INVALID_ARGS', `--${name} requires an ISO8601 timestamp`);
+    }
+    return raw;
+}
+/** The metrics window flags shared by search-templates, get-template and search-workloads. */
+function metricsWindow(parsed) {
+    const window = {};
+    const daysBack = positiveIntFlag(parsed, 'days-back');
+    if (daysBack !== undefined) {
+        window.daysBack = daysBack;
+    }
+    const since = timestampFlag(parsed, 'since');
+    if (since !== undefined) {
+        window.since = since;
+    }
+    const until = timestampFlag(parsed, 'until');
+    if (until !== undefined) {
+        window.until = until;
+    }
+    return window;
+}
 const TEMPLATE_STATUSES = new Set(['draft', 'published', 'failure']);
 function searchTemplatesOptions(parsed) {
     const opts = {};
@@ -956,6 +1256,10 @@ function searchTemplatesOptions(parsed) {
     if (parsed.flags['include-system'] === true) {
         opts.includeSystem = true;
     }
+    if (parsed.flags['include-metrics'] === true) {
+        opts.includeMetrics = true;
+    }
+    Object.assign(opts, metricsWindow(parsed));
     if (typeof parsed.flags['page'] === 'string') {
         const raw = parsed.flags['page'];
         const n = parseInt(raw, 10);
@@ -980,12 +1284,63 @@ function searchTemplatesOptions(parsed) {
     }
     return opts;
 }
+function searchWorkloadsOptions(parsed) {
+    const opts = {};
+    if (typeof parsed.flags['search'] === 'string') {
+        opts.search = parsed.flags['search'];
+    }
+    if (parsed.flags['include-archived'] === true) {
+        opts.includeArchived = true;
+    }
+    if (parsed.flags['include-system'] === true) {
+        opts.includeSystem = true;
+    }
+    if (parsed.flags['include-templates'] === true) {
+        opts.includeTemplates = true;
+    }
+    if (parsed.flags['include-metrics'] === true) {
+        opts.includeMetrics = true;
+    }
+    Object.assign(opts, metricsWindow(parsed));
+    const page = positiveIntFlag(parsed, 'page');
+    if (page !== undefined) {
+        opts.page = page;
+    }
+    const perPage = perPageFlag(parsed);
+    if (perPage !== undefined) {
+        opts.perPage = perPage;
+    }
+    if (typeof parsed.flags['client-id'] === 'string') {
+        opts.clientId = parsed.flags['client-id'];
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
 function getTemplateOptions(parsed) {
     const id = parsed.positional[0];
     if (!id) {
         throw new CliError('INVALID_ARGS', 'get-template requires a <template-id> argument');
     }
     const opts = { id };
+    if (parsed.flags['no-metrics'] === true) {
+        opts.noMetrics = true;
+    }
+    Object.assign(opts, metricsWindow(parsed));
+    if (typeof parsed.flags['client-id'] === 'string') {
+        opts.clientId = parsed.flags['client-id'];
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
+function helpCenterReadOptions(parsed) {
+    const opts = {};
+    if (typeof parsed.flags['base-url'] === 'string') {
+        opts.baseUrl = parsed.flags['base-url'];
+    }
     if (typeof parsed.flags['client-id'] === 'string') {
         opts.clientId = parsed.flags['client-id'];
     }
@@ -994,6 +1349,47 @@ function getTemplateOptions(parsed) {
     }
     return opts;
 }
+function searchHelpArticlesOptions(parsed) {
+    const opts = helpCenterReadOptions(parsed);
+    if (parsed.flags['query'] === true) {
+        throw new CliError('INVALID_ARGS', '--query requires a value (attach a leading-dash query as --query=-text)');
+    }
+    const positionalQuery = parsed.positional.join(' ');
+    if (typeof parsed.flags['query'] === 'string' && positionalQuery.trim()) {
+        throw new CliError('INVALID_ARGS', 'Pass the search text either as --query or as positional text, not both');
+    }
+    const query = typeof parsed.flags['query'] === 'string' ? parsed.flags['query'] : positionalQuery;
+    if (query.trim()) {
+        opts.query = query;
+    }
+    if (typeof parsed.flags['category'] === 'string') {
+        opts.category = parsed.flags['category'];
+    }
+    if (typeof parsed.flags['page'] === 'string') {
+        const raw = parsed.flags['page'];
+        const n = parseInt(raw, 10);
+        if (!/^\d+$/.test(raw) || isNaN(n) || n < 1) {
+            throw new CliError('INVALID_ARGS', '--page must be a positive integer');
+        }
+        opts.page = n;
+    }
+    if (typeof parsed.flags['per-page'] === 'string') {
+        const raw = parsed.flags['per-page'];
+        const n = parseInt(raw, 10);
+        if (!/^\d+$/.test(raw) || isNaN(n) || n < 1 || n > 100) {
+            throw new CliError('INVALID_ARGS', '--per-page must be an integer between 1 and 100');
+        }
+        opts.perPage = n;
+    }
+    return opts;
+}
+function getHelpArticleOptions(parsed) {
+    const slug = parsed.positional[0];
+    if (!slug) {
+        throw new CliError('INVALID_ARGS', 'get-help-article requires a <slug> argument');
+    }
+    return { ...helpCenterReadOptions(parsed), slug };
+}
 function searchLogsOptions(parsed) {
     const opts = {};
     if (typeof parsed.flags['template-id'] === 'string') {
@@ -1028,9 +1424,38 @@ function searchLogsOptions(parsed) {
         }
         opts.daysBack = n;
     }
+    if (typeof parsed.flags['source-application'] === 'string') {
+        opts.sourceApplication = parsed.flags['source-application'];
+    }
+    if (typeof parsed.flags['project-path'] === 'string') {
+        opts.projectPath = parsed.flags['project-path'];
+    }
+    const since = timestampFlag(parsed, 'since');
+    if (since !== undefined) {
+        opts.since = since;
+    }
+    const until = timestampFlag(parsed, 'until');
+    if (until !== undefined) {
+        opts.until = until;
+    }
+    if (parsed.flags['min-cost'] !== undefined) {
+        const raw = parsed.flags['min-cost'];
+        // `0` is a valid floor and must reach the server, so compare against undefined, not falsiness.
+        if (typeof raw !== 'string' || !/^\d+(\.\d+)?$/.test(raw)) {
+            throw new CliError('INVALID_ARGS', '--min-cost must be a non-negative decimal number (USD)');
+        }
+        opts.minCost = parseFloat(raw);
+    }
+    if (typeof parsed.flags['order'] === 'string') {
+        // Not allowlisted here: the server validates it and a 422 surfaces as a CliError.
+        opts.order = parsed.flags['order'];
+    }
     if (parsed.flags['include-prompts'] === true) {
         opts.includePrompts = true;
     }
+    if (parsed.flags['include-total'] === true) {
+        opts.includeTotal = true;
+    }
     if (typeof parsed.flags['sort'] === 'string') {
         opts.sort = parsed.flags['sort'];
     }
@@ -1229,6 +1654,29 @@ function searchFeedbackOptions(parsed) {
     }
     return opts;
 }
+function linkFeedbackOptions(parsed) {
+    const optimizationId = parsed.positional[0];
+    if (!optimizationId) {
+        throw new CliError('INVALID_ARGS', 'link-feedback requires an <optimization-id> argument');
+    }
+    const opts = { optimizationId, feedbackIds: parsed.positional.slice(1) };
+    if (typeof parsed.flags.file === 'string') {
+        opts.file = parsed.flags.file;
+    }
+    else if (parsed.flags.file === true) {
+        throw new CliError('INVALID_ARGS', 'link-feedback --file requires a path; use --file=- to read ids from stdin');
+    }
+    if (typeof parsed.flags.note === 'string') {
+        opts.note = parsed.flags.note;
+    }
+    if (typeof parsed.flags['client-id'] === 'string') {
+        opts.clientId = parsed.flags['client-id'];
+    }
+    if (parsed.flags.json === true) {
+        opts.json = true;
+    }
+    return opts;
+}
 function getFeedbackOptions(parsed) {
     const id = parsed.positional[0];
     if (!id) {
@@ -1270,9 +1718,40 @@ function wildcardOptions(parsed) {
     }
     return opts;
 }
+function captureTurnOptions(parsed) {
+    const agent = parsed.flags.agent;
+    if (typeof agent !== 'string' || !HOOK_AGENTS.includes(agent)) {
+        throw new CliError('INVALID_ARGS', `capture-turn requires --agent ${HOOK_AGENTS.join('|')}`);
+    }
+    const opts = { agent: agent };
+    // `skill` is a repeatable flag, so a doubled `--skill` arrives as an array; the last one wins.
+    const skill = Array.isArray(parsed.flags.skill) ? parsed.flags.skill[parsed.flags.skill.length - 1] : parsed.flags.skill;
+    if (typeof skill === 'string') {
+        opts.skill = skill;
+    }
+    if (typeof parsed.flags['skill-version'] === 'string' && parsed.flags['skill-version'].trim()) {
+        opts.skillVersion = parsed.flags['skill-version'].trim().slice(0, 100);
+    }
+    if (typeof parsed.flags['api-key'] === 'string') {
+        opts.apiKey = parsed.flags['api-key'];
+    }
+    if (typeof parsed.flags['base-url'] === 'string' && parsed.flags['base-url']) {
+        opts.baseUrl = parsed.flags['base-url'];
+    }
+    // `--anonymous=true|1|yes` arrive as strings. Anonymity must fail closed: only an explicit
+    // false/0/no turns it off, and any other value still means anonymous.
+    const anonymous = parsed.flags.anonymous;
+    if (anonymous === true || (typeof anonymous === 'string' && !/^(false|0|no)$/i.test(anonymous))) {
+        opts.anonymous = true;
+    }
+    if (parsed.flags['no-declare'] === true) {
+        opts.declare = false;
+    }
+    return opts;
+}
 // Commands that must never trigger the failed-flush reminder: the flush itself, and
 // login (which runs its own pending-flush prompt).
-const NO_FLUSH_REMINDER = new Set(['__flush-pending', 'login', 'help', 'version']);
+const NO_FLUSH_REMINDER = new Set(['__flush-pending', '__auto-update', 'login', 'help', 'version', 'capture-turn']);
 /**
  * Option B retry: if a previous background flush failed, remind the user on their next
  * command and offer to retry. Interactive-only (`confirm` returns false with no TTY), so
@@ -1312,6 +1791,8 @@ export async function run(argv) {
         // Peel a leading --client-id before command dispatch. The `claude` passthrough
         // skips parseArgs entirely, so we extract any global --client-id here first.
         const { clientId: globalClientId, rest: argv2 } = peelClientId(argv);
+        const wantsHelp = argv2.includes('--help') || argv2.includes('-h');
+        await maybeAutoUpdate({ command: wantsHelp ? 'help' : argv2[0], json: argv2.includes('--json') });
         // `claude` is a passthrough wrapper: everything after it goes to the Claude CLI
         // verbatim (e.g. `coolhand claude --resume`), so it must skip the flag parser.
         if (argv2[0] === 'claude') {
@@ -1378,6 +1859,10 @@ export async function run(argv) {
         switch (resolvedCommand) {
             case '__flush-pending':
                 return await runFlushPending();
+            case '__auto-update':
+                return await runAutoUpdate();
+            case 'update':
+                return await runUpdate(updateOptions(parsed));
             case 'login':
                 return await runLogin(loginOptions(parsed));
             case 'logout':
@@ -1398,8 +1883,29 @@ export async function run(argv) {
                 return await runUpdateOptimization(updateOptimizationOptions(parsed));
             case 'wildcard':
                 return await runWildcard(wildcardOptions(parsed));
+            case 'capture-turn': {
+                // Runs unattended inside an agent hook: a bad flag must not print into the agent's hook
+                // channel or fail the hook. Only a human at a terminal gets the error.
+                let captureOpts;
+                try {
+                    captureOpts = captureTurnOptions(parsed);
+                }
+                catch (err) {
+                    if (process.stdin.isTTY) {
+                        throw err;
+                    }
+                    if (isCaptureDisabled()) {
+                        return ExitCode.OK;
+                    }
+                    await logHookEvent(`capture-turn: ${err.message}`);
+                    return ExitCode.OK;
+                }
+                return await runCaptureTurn(captureOpts);
+            }
             case 'search-feedback':
                 return await runSearchFeedback(searchFeedbackOptions(parsed));
+            case 'link-feedback':
+                return await runLinkFeedback(linkFeedbackOptions(parsed));
             case 'get-feedback':
                 return await runGetFeedback(getFeedbackOptions(parsed));
             case 'analyze-claude-sessions':
@@ -1408,6 +1914,12 @@ export async function run(argv) {
                 return await runMapClaudeProjects(mapClaudeProjectsOptions(parsed));
             case 'upload-client-file':
                 return await runUploadClientFile(uploadClientFileOptions(parsed));
+            case 'list-client-files':
+                return await runListClientFiles(listClientFilesOptions(parsed));
+            case 'download-client-file':
+                return await runDownloadClientFile(downloadClientFileOptions(parsed));
+            case 'update-client-file':
+                return await runUpdateClientFile(updateClientFileOptions(parsed));
             case 'sync-skills':
                 return await runSyncSkills(syncSkillsOptions(parsed));
             case 'list-workloads':
@@ -1422,8 +1934,16 @@ export async function run(argv) {
                 return await runSearchLogs(searchLogsOptions(parsed));
             case 'search-templates':
                 return await runSearchTemplates(searchTemplatesOptions(parsed));
+            case 'search-workloads':
+                return await runSearchWorkloads(searchWorkloadsOptions(parsed));
             case 'get-template':
                 return await runGetTemplate(getTemplateOptions(parsed));
+            case 'search-help-articles':
+                return await runSearchHelpArticles(searchHelpArticlesOptions(parsed));
+            case 'get-help-article':
+                return await runGetHelpArticle(getHelpArticleOptions(parsed));
+            case 'list-help-categories':
+                return await runListHelpCategories(helpCenterReadOptions(parsed));
             case 'search-referenced-files':
                 return await runSearchReferencedFiles(searchReferencedFilesOptions(parsed));
             case 'list-referenced-file-sessions':