@userreason/cli 0.1.0 → 0.1.1

package/dist/capture.js

@@ -0,0 +1,256 @@
+import { spawn } from 'node:child_process';
+import { access, lstat, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+/** External, pinned capture tool; no SingleFile source is bundled into the UserReason package. */
+export const CAPTURE_ENGINE = 'single-file-cli@2.0.77';
+export class CaptureError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function captureUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('Capture requires an absolute HTTP(S) URL');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw new Error('Capture requires an HTTP(S) URL without embedded credentials');
+    return url;
+}
+export function captureArguments(url, output, options = {}) {
+    captureUrl(url);
+    const width = options.width ?? 1440, height = options.height ?? 900;
+    if (!Number.isInteger(width) || width < 240 || width > 2560 || !Number.isInteger(height) || height < 320 || height > 2560)
+        throw new Error('Capture dimensions must be 240–2560 wide and 320–2560 high');
+    return [url, output, `--browser-width=${width}`, `--browser-height=${height}`,
+        '--browser-wait-until=DOMContentLoaded', '--browser-wait-until-delay=1000',
+        '--browser-wait-until-fallback=false', `--browser-load-max-time=${options.interactive ? 300000 : 30000}`, '--browser-capture-max-time=60000',
+        '--remove-hidden-elements=false', '--remove-unused-styles=false', '--remove-unused-fonts=false',
+        '--remove-alternative-fonts=false', '--remove-alternative-medias=false', '--remove-alternative-images=false',
+        '--block-alternative-images=false', '--compress-content=false', '--self-extracting-archive=false',
+        '--filename-conflict-action=overwrite', ...(options.browser ? [`--browser-executable-path=${options.browser}`] : [])];
+}
+async function launcher(engine) {
+    if (engine)
+        return { command: resolve(engine), prefix: [] };
+    const candidates = [
+        ...(process.env.npm_execpath ? [join(dirname(process.env.npm_execpath), 'npx-cli.js')] : []),
+        join(dirname(process.execPath), '../lib/node_modules/npm/bin/npx-cli.js'),
+        join(dirname(process.execPath), 'node_modules/npm/bin/npx-cli.js'),
+        '/usr/share/nodejs/npm/bin/npx-cli.js',
+    ];
+    for (const file of candidates) {
+        try {
+            await access(file);
+            return { command: process.execPath, prefix: [file, '--yes', `--package=${CAPTURE_ENGINE}`, 'single-file'] };
+        }
+        catch { /* Try the next standard npm location. */ }
+    }
+    if (process.platform !== 'win32')
+        return { command: 'npx', prefix: ['--yes', `--package=${CAPTURE_ENGINE}`, 'single-file'] };
+    throw new Error('Install SingleFile CLI and pass its executable with --capture-bin');
+}
+async function run(command, args, timeoutMs, signal) {
+    signal.throwIfAborted();
+    await new Promise((done, reject) => {
+        const child = spawn(command, args, { stdio: 'ignore', shell: false, detached: process.platform !== 'win32' });
+        let timedOut = false;
+        const stop = () => {
+            try {
+                if (child.pid && process.platform !== 'win32')
+                    process.kill(-child.pid, 'SIGKILL');
+                else
+                    child.kill('SIGKILL');
+            }
+            catch { /* The capture process already exited. */ }
+        };
+        const timer = setTimeout(() => { timedOut = true; stop(); }, timeoutMs);
+        signal.addEventListener('abort', stop, { once: true });
+        if (signal.aborted)
+            stop();
+        const cleanup = () => { clearTimeout(timer); signal.removeEventListener('abort', stop); };
+        child.once('error', () => { cleanup(); reject(new Error('Could not start the capture engine. Install npm or pass --capture-bin with a SingleFile executable')); });
+        child.once('close', (code) => {
+            cleanup();
+            if (signal.aborted)
+                reject(signal.reason);
+            else if (timedOut)
+                reject(new CaptureError('capture_timeout', 'Capture timed out. The page may still be loading or waiting for input; try --interactive to inspect it.'));
+            else if (code !== 0)
+                reject(new Error('Page capture failed; check the URL, Chrome installation and access to the page'));
+            else
+                done();
+        });
+    });
+}
+/** Own the browser lifecycle: sandbox on, loopback CDP, isolated profile, no user cookies. */
+async function startBrowser(directory, options) {
+    const candidates = options.browser ? [resolve(options.browser)] : process.platform === 'darwin'
+        ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge']
+        : process.platform === 'win32'
+            ? [join(process.env.PROGRAMFILES ?? 'C:\\Program Files', 'Google/Chrome/Application/chrome.exe'), join(process.env.LOCALAPPDATA ?? '', 'Google/Chrome/Application/chrome.exe')]
+            : ['/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/opt/google/chrome/chrome'];
+    let executable;
+    for (const candidate of candidates) {
+        try {
+            await access(candidate);
+            executable = candidate;
+            break;
+        }
+        catch { /* Try next installed browser. */ }
+    }
+    if (!executable)
+        throw new Error('Chrome was not found. Install Chrome or use --browser-executable PATH');
+    const profile = join(directory, 'browser');
+    const child = spawn(executable, [...(options.interactive ? [] : ['--headless=new']), '--remote-debugging-port=0', '--remote-debugging-address=127.0.0.1', `--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check', '--disable-background-networking', '--disable-component-update', '--disable-sync', '--disable-extensions', 'about:blank'], { stdio: 'ignore', detached: process.platform !== 'win32', shell: false });
+    let exited = false;
+    child.once('error', () => { exited = true; });
+    child.once('exit', () => { exited = true; });
+    const close = () => {
+        process.off('SIGINT', close);
+        process.off('SIGTERM', close);
+        try {
+            if (child.pid && process.platform !== 'win32')
+                process.kill(-child.pid, 'SIGKILL');
+            else
+                child.kill('SIGKILL');
+        }
+        catch { /* Already closed. */ }
+    };
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+    const deadline = Date.now() + 15000;
+    while (!exited && Date.now() < deadline) {
+        try {
+            const [port = '', path] = (await readFile(join(profile, 'DevToolsActivePort'), 'utf8')).split('\n');
+            if (/^[0-9]{1,5}$/.test(port) && Number(port) > 0 && Number(port) < 65536)
+                return { server: `http://127.0.0.1:${port}`, debuggerUrl: path?.startsWith('/devtools/browser/') ? `ws://127.0.0.1:${port}${path}` : undefined, close };
+        }
+        catch { /* Chrome writes the port file once CDP is listening. */ }
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    close();
+    throw new Error('Chrome could not start its sandboxed capture session');
+}
+/** Watch new page targets before navigation so even an early prompt is observable. */
+async function watchDialogs(url, options, controller) {
+    const socket = new WebSocket(url);
+    let nextId = 0, closed = false;
+    const pending = new Map();
+    const fail = () => { if (!closed)
+        controller.abort(new CaptureError('capture_browser_closed', 'The capture browser closed before capture finished.')); };
+    const call = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
+        const id = ++nextId;
+        pending.set(id, { resolve, reject });
+        socket.send(JSON.stringify({ id, method, params, sessionId }));
+    });
+    socket.addEventListener('message', event => {
+        const message = JSON.parse(String(event.data));
+        if (message.id) {
+            const item = pending.get(message.id);
+            pending.delete(message.id);
+            if (message.error)
+                item?.reject(new Error('Could not observe the capture browser'));
+            else
+                item?.resolve();
+        }
+        else if (message.method === 'Target.attachedToTarget') {
+            const sessionId = message.params.sessionId;
+            void (async () => { await call('Page.enable', {}, sessionId); await call('Runtime.runIfWaitingForDebugger', {}, sessionId); })().catch(fail);
+        }
+        else if (message.method === 'Page.javascriptDialogOpening') {
+            if (options.interactive)
+                options.onProgress?.('The page is waiting for input. Answer the dialog in the capture browser.');
+            else
+                controller.abort(new CaptureError('capture_input_required', 'The page opened a browser dialog and needs input. Retry with --interactive to answer it in the capture browser.'));
+        }
+    });
+    socket.addEventListener('close', fail);
+    socket.addEventListener('error', fail);
+    const close = () => {
+        closed = true;
+        socket.close();
+        for (const item of pending.values())
+            item.reject(new Error('Capture browser observation ended'));
+        pending.clear();
+    };
+    let setupTimer;
+    try {
+        await Promise.race([
+            (async () => {
+                await new Promise((resolve, reject) => {
+                    socket.addEventListener('open', () => resolve(), { once: true });
+                    socket.addEventListener('error', () => reject(new Error('Could not connect to the capture browser')), { once: true });
+                });
+                await call('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true, filter: [{ type: 'page', exclude: false }, { exclude: true }] });
+            })(),
+            new Promise((_, reject) => { setupTimer = setTimeout(() => reject(new Error('Could not connect to the capture browser')), 5000); }),
+        ]);
+        return close;
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    finally {
+        clearTimeout(setupTimer);
+    }
+}
+export async function capturePage(value, options = {}) {
+    const url = captureUrl(value);
+    const timeout = options.timeoutMs ?? (options.interactive ? 300000 : 120000);
+    if (!Number.isInteger(timeout) || timeout < 1000 || timeout > 300000)
+        throw new Error('Capture timeout must be 1000–300000 milliseconds');
+    // Validate before starting an external process or touching a temporary directory.
+    captureArguments(url.href, 'capture.html', options);
+    const directory = await mkdtemp(join(tmpdir(), 'userreason-capture-'));
+    let browser;
+    let stopWatching;
+    const controller = new AbortController();
+    const interrupted = () => controller.abort(new CaptureError('capture_cancelled', 'Capture cancelled. Nothing was uploaded.'));
+    process.once('SIGINT', interrupted);
+    process.once('SIGTERM', interrupted);
+    try {
+        const output = join(directory, 'capture.html');
+        const hidePrompt = join(directory, 'hide-prompt.css');
+        // Removing a live SDK host can trigger its mount observer repeatedly.
+        await writeFile(hidePrompt, '[data-userreason] { display: none !important; }', { mode: 0o600 });
+        // Ownership remains private even if the external tool replaces the file contents.
+        await writeFile(output, '', { mode: 0o600 });
+        const { command, prefix } = await launcher(options.engine);
+        options.onProgress?.(options.interactive ? 'Opening capture browser. Complete any sign-in or dialog there.' : 'Starting isolated Chrome capture.');
+        browser = await startBrowser(directory, options);
+        if (controller.signal.aborted)
+            throw controller.signal.reason;
+        if (browser.debuggerUrl)
+            stopWatching = await watchDialogs(browser.debuggerUrl, options, controller);
+        options.onProgress?.('Loading page and embedding assets; first use may download SingleFile.');
+        const progressTimer = setInterval(() => options.onProgress?.('Still capturing the page and its assets…'), 10000);
+        try {
+            await run(command, [...prefix, ...captureArguments(url.href, output, options), `--browser-server=${browser.server}`, `--browser-stylesheet=${hidePrompt}`], timeout, controller.signal);
+        }
+        finally {
+            clearInterval(progressTimer);
+        }
+        const info = await lstat(output);
+        if (!info.isFile() || info.isSymbolicLink() || info.size < 1 || info.size > 4 * 1024 * 1024)
+            throw new Error('Captured HTML is empty or exceeds the 4 MiB demo limit');
+        return new Uint8Array(await readFile(output));
+    }
+    catch (error) {
+        throw controller.signal.aborted ? controller.signal.reason : error;
+    }
+    finally {
+        stopWatching?.();
+        browser?.close();
+        process.off('SIGINT', interrupted);
+        process.off('SIGTERM', interrupted);
+        await rm(directory, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+    }
+}

package/dist/catalog.d.ts

@@ -0,0 +1,16 @@
+import { type Scope } from './contracts.js';
+/** The description written for exactly this command or noun, if there is one. */
+export declare const commandSummary: (command: string) => string | undefined;
+export interface CommandReference {
+    command: string;
+    usage: string;
+    summary: string;
+    scopes: readonly Scope[];
+    notes: string[];
+}
+export declare const commandCatalog: CommandReference[];
+export declare const globalHelp = "Workspace and site default to the SDK initialization in the current project.\nExplicit --workspace / --site override it. No project configuration file is created.\nSurveys use the existing prompt command and API names.\nGlobal options: --dev, --api-url ORIGIN, --client-id CLIENT_ID, --json\nCredential storage: --credential-store file|keychain, or UR_CREDENTIAL_STORE (default file)\nLogin saves the selected store for this API environment. Existing Keychain sessions require --credential-store keychain.\nDocs: --docs-url ORIGIN, --offline (bundled CLI reference), --live (require hosted docs)\nCreation options: --request-id UUID, --workspace-id UUID / --site-id UUID\nSite environment: --environment development|production (default production)\nOrigins are unrestricted by default; --origin adds an exact restriction.\nFile credentials are plaintext under the user config directory with owner-only permissions (0600).\nKeychain is optional and never silently falls back to a file. WorkOS API keys are never required.";
+export declare const cliHelp: () => string;
+export declare function getCommandReference(command: string): CommandReference;
+export declare function searchCommands(query: string, limit?: number): CommandReference[];
+export declare function bundledCliMarkdown(): string;

package/dist/catalog.js

@@ -0,0 +1,180 @@
+import { SCOPES } from './contracts.js';
+// Shared by terminal help, offline command discovery, and the bundled CLI reference.
+const usages = `userreason login [--open]
+userreason access [--open] [--no-wait]
+userreason logout
+userreason whoami
+userreason deletion status --id UUID --workspace UUID
+userreason workspace delete UUID [--preview] [--confirm NAME --revision N --confirmation-token TOKEN]
+userreason site delete UUID --workspace UUID [--preview] [--confirm NAME --revision N --confirmation-token TOKEN]
+userreason prompt delete UUID --workspace UUID --site UUID [--preview] [--confirm NAME --revision N --confirmation-token TOKEN]
+userreason workspace list
+userreason workspace create --name NAME
+userreason site list --workspace UUID
+userreason site create --workspace UUID --name NAME [--origin URL]
+userreason grant request --scope site:read [--scope site:create] [--workspace UUID] [--wait]
+userreason grant status --id UUID [--wait]
+userreason prompt list --workspace UUID --site UUID
+userreason prompt get UUID --workspace UUID --site UUID
+userreason prompt validate --file PROMPT.json [--context-file EXAMPLE.json] --workspace UUID --site UUID
+userreason preview capture URL --dev --workspace UUID --site UUID [--name NAME] [--width 1440] [--height 900] [--interactive] [--open] [--capture-bin PATH] [--browser-executable PATH]
+userreason prompt create --file PROMPT.json --workspace UUID --site UUID [--id UUID]
+userreason prompt update UUID --file PROMPT.json --revision N --workspace UUID --site UUID
+userreason prompt publish|pause|resume|archive UUID --revision N --workspace UUID --site UUID
+userreason prompt responses UUID --workspace UUID --site UUID [--limit 50] [--after UUID]
+userreason audience list --workspace UUID --site UUID
+userreason audience get UUID --workspace UUID --site UUID
+userreason audience create --file AUDIENCE.json --workspace UUID --site UUID [--id UUID]
+userreason audience update UUID --file AUDIENCE.json --revision N --workspace UUID --site UUID
+userreason audience publish|discard|archive UUID --revision N --workspace UUID --site UUID
+userreason results overview --workspace UUID --site UUID [--days 1|7|30|90] [--time-zone ZONE]
+userreason results prompt UUID --workspace UUID --site UUID [--days N] [--country NL] [--segment browser=Chrome]
+userreason results experiments UUID --workspace UUID --site UUID [--run UUID] [--all-attempts] [--reported-only]
+userreason results breakdown --by country|language|device_type|os|browser --workspace UUID --site UUID [--prompt-id UUID]
+userreason responses list --workspace UUID --site UUID [--prompt-id UUID] [--run UUID] [--variant ID] [--user UUID] [--search TEXT] [--days N] [--cursor CURSOR]
+userreason user list --workspace UUID --site UUID [--kind all|identified|anonymous|responded] [--search TEXT] [--cursor CURSOR]
+userreason user get UUID --workspace UUID --site UUID
+userreason user eligibility UUID --workspace UUID --site UUID [--file AUDIENCE.json]
+userreason event list|overview --workspace UUID --site UUID [--days N]
+userreason event create --file EVENT.json [--purpose business|activity] --workspace UUID --site UUID [--id UUID]
+userreason event update UUID --file EVENT.json --revision N --workspace UUID --site UUID
+userreason site events preview --mode explicit|registered|all [--file LIMITS.json] --workspace UUID --site UUID
+userreason site events set --mode explicit|registered|all --revision N [--confirmation-token TOKEN] [--file LIMITS.json] --workspace UUID --site UUID
+userreason site activity --workspace UUID --site UUID
+userreason site frequency get --workspace UUID --site UUID
+userreason site frequency set --file POLICY.json --revision N --workspace UUID --site UUID
+userreason site frequency reset --revision N --workspace UUID --site UUID
+userreason prompt history --workspace UUID --site UUID
+userreason member list --workspace UUID
+userreason command --file COMMAND.json
+userreason query --workspace UUID --resource surveys [--site UUID] [--limit 50] [--after UUID]
+userreason docs search "QUESTION" [--limit 5]
+userreason docs get URL_OR_PATH
+userreason cli search "QUESTION" [--limit 5]
+userreason cli get "COMMAND"
+userreason cli list`;
+const descriptions = {
+    preview: 'Capture a webpage locally and upload a responsive HTML background to the development preview lab.',
+    deletion: 'Read the status of a permanent deletion job.',
+    'workspace delete': 'Preview or explicitly confirm permanent removal of a workspace and all its data.',
+    'site delete': 'Preview or explicitly confirm permanent removal of a site and all its data.',
+    'prompt delete': 'Preview or explicitly confirm permanent removal of a survey, versions and responses.',
+    login: 'Sign in and approve workspace access and permissions in the browser.',
+    access: 'Renew or change approved workspace access and permissions.',
+    logout: 'Remove the session from the selected local credential store.',
+    whoami: 'Inspect the signed-in account, API, workspace grants and project site.',
+    workspace: 'List or create workspaces.',
+    site: 'List or create sites, inspect SDK connection activity, or manage survey frequency limits.',
+    grant: 'Request deliberately restricted access or inspect approval status.',
+    prompt: 'Manage feedback surveys and their questions.',
+    'prompt validate': 'Rehearse survey targeting, event collection and SDK requirements without saving or publishing.',
+    'prompt create': 'Create a draft survey to collect feedback from visitors.',
+    'prompt update': 'Edit an existing survey draft with a complete question definition.',
+    'prompt publish': 'Publish an approved feedback survey to deliver it to matching visitors.',
+    'prompt pause': 'Pause a published survey to stop collecting new feedback.',
+    'prompt resume': 'Resume delivery of a paused feedback survey.',
+    'prompt archive': 'Retire a feedback survey while preserving published versions and responses.',
+    'prompt responses': 'Read answers submitted to one feedback survey.',
+    'prompt history': 'Read when the site began recording survey history.',
+    audience: 'Manage saved audiences, reusable targeting rules and segments.',
+    results: 'Analyze feedback results, response rates, funnels and breakdowns.',
+    'results experiments': 'Read experiment runs, allocation, comparisons and answer positions. See /prompts/experiments/ in the selected documentation site.',
+    responses: 'Read submitted feedback answers and filter responses.',
+    user: 'Inspect visitors and eligibility; explain why a person does or does not see a survey.',
+    'user eligibility': 'Explain why a visitor does or does not see a survey, including targeting and frequency checks.',
+    event: 'Inspect or register tracked events and their collection settings.',
+    'site activity': 'Check whether the SDK is connected and receiving sessions, events and displays.',
+    member: 'Read workspace members and roles.',
+    command: 'Submit a complete versioned management command JSON file.',
+    query: 'Query workspace and site records with pagination.',
+    docs: 'Search public SDK documentation or read a Markdown page. Use --offline for bundled CLI documentation.',
+    cli: 'Discover installed CLI commands and exact usage locally without login or network access.',
+};
+/** The description written for exactly this command or noun, if there is one. */
+export const commandSummary = (command) => descriptions[command];
+function scopeFor(command) {
+    const [group, action] = command.split(' ');
+    if (group === 'preview')
+        return ['site:read', 'survey:write'];
+    if (action === 'delete')
+        return ['resource:delete'];
+    if (group === 'workspace')
+        return [action === 'create' ? 'workspace:create' : 'workspace:read'];
+    if (group === 'member')
+        return ['workspace:read'];
+    if (group === 'site')
+        return [action === 'create' ? 'site:create' : command.startsWith('site events set') || command.startsWith('site frequency s') || command.endsWith('reset') ? 'site:update' : 'site:read'];
+    if (['prompt', 'audience', 'event'].includes(group)) {
+        if (['publish', 'pause', 'resume', 'archive'].includes(action))
+            return ['campaign:publish'];
+        if (['create', 'update', 'discard'].includes(action))
+            return ['survey:write'];
+        return ['site:read'];
+    }
+    if (['results', 'responses', 'user'].includes(group))
+        return ['site:read'];
+    return [];
+}
+export const commandCatalog = usages.split('\n').flatMap(line => {
+    const withoutBinary = line.replace(/^userreason /, '');
+    const path = withoutBinary.match(/^[a-z]+(?:[| ][a-z]+)*/)?.[0].trim() ?? '';
+    const parts = path.split(' '), last = parts.pop();
+    return last.split('|').map(action => {
+        const command = [...parts, action].join(' ');
+        const targeted = ['preview', 'site', 'prompt', 'audience', 'results', 'responses', 'user', 'event', 'query'].includes(parts[0] ?? action);
+        const notes = targeted ? ['Workspace and site default to the project SDK initialization. Explicit flags override detection. Missing access never selects another site.'] : [];
+        if (command === 'preview capture')
+            notes.push('Development API only. Requires Chrome; first use downloads a pinned external SingleFile CLI via npm. Captures use a fresh browser profile, preserve responsive assets and expire after seven days. Use --interactive to answer browser dialogs in a visible capture window. Returns links.preview.');
+        if (['create', 'update'].includes(action) && ['prompt', 'audience'].includes(parts[0]))
+            notes.push('The JSON file is a complete definition, not a patch. Saving a draft does not publish it.');
+        if (parts[0] === 'prompt' && ['create', 'update', 'publish', 'pause', 'resume', 'archive'].includes(action))
+            notes.push(`Share the returned links.${['create', 'update'].includes(action) ? 'edit' : 'results'} so the user can review the survey; state whether changes are draft or published.`);
+        if (withoutBinary.includes('--revision'))
+            notes.push('Read the current revision before changing a resource. On conflict, reread; do not retry blindly.');
+        if (action === 'delete')
+            notes.push('Without --confirm, only previews impact. Permanent deletion requires the exact name, reviewed token and revision, plus explicit user authorization. Use deletion status to track cleanup.');
+        if (action === 'publish')
+            notes.push('Publishing changes live delivery. Publish only the survey or audience the user approved.');
+        if (command === 'command' || command === 'query')
+            notes.push('The server derives the required permission from the requested operation and resource.');
+        return { command, usage: line.replace(path, command), summary: descriptions[command] ?? descriptions[parts[0] ?? action], scopes: scopeFor(command), notes };
+    });
+});
+export const globalHelp = `Workspace and site default to the SDK initialization in the current project.
+Explicit --workspace / --site override it. No project configuration file is created.
+Surveys use the existing prompt command and API names.
+Global options: --dev, --api-url ORIGIN, --client-id CLIENT_ID, --json
+Credential storage: --credential-store file|keychain, or UR_CREDENTIAL_STORE (default file)
+Login saves the selected store for this API environment. Existing Keychain sessions require --credential-store keychain.
+Docs: --docs-url ORIGIN, --offline (bundled CLI reference), --live (require hosted docs)
+Creation options: --request-id UUID, --workspace-id UUID / --site-id UUID
+Site environment: --environment development|production (default production)
+Origins are unrestricted by default; --origin adds an exact restriction.
+File credentials are plaintext under the user config directory with owner-only permissions (0600).
+Keychain is optional and never silently falls back to a file. WorkOS API keys are never required.`;
+export const cliHelp = () => 'UserReason CLI\n\n' + commandCatalog.map(item => item.usage).join('\n') + '\n\n' + globalHelp + '\n';
+export function getCommandReference(command) {
+    const key = command.trim().replace(/^userreason\s+/, '').replace(/\s+/g, ' ');
+    const found = commandCatalog.find(item => item.command === key);
+    if (!found)
+        throw new Error('Unknown CLI command. Use userreason cli search "QUESTION" or userreason cli list.');
+    return found;
+}
+export function searchCommands(query, limit = 5) {
+    if (!query.trim() || query.length > 500)
+        throw new Error('Command search needs a question of 1–500 characters');
+    if (!Number.isInteger(limit) || limit < 1 || limit > 20)
+        throw new Error('Command search limit must be an integer from 1 to 20');
+    const words = query.toLowerCase().match(/[a-z0-9]+/g)?.filter(word => !['a', 'an', 'the', 'to', 'for', 'i', 'want', 'how', 'do', 'my'].includes(word)) ?? [];
+    return commandCatalog.map(item => {
+        const path = item.command.toLowerCase(), text = (item.summary + ' ' + item.usage).toLowerCase();
+        const score = words.reduce((sum, word) => sum + (path.includes(word) ? 6 : text.includes(word) ? 1 : 0), 0);
+        return { item, score };
+    }).filter(item => item.score > 0).sort((a, b) => b.score - a.score || a.item.command.localeCompare(b.item.command)).slice(0, limit).map(({ item }) => item);
+}
+export function bundledCliMarkdown() {
+    return '# UserReason CLI command reference\n\nThis reference ships with the installed CLI and works offline. For live SDK documentation, use docs search or docs get with --live.\n\n' +
+        globalHelp + '\n\n## Access and retries\n\nLogin opens browser consent for all current and future workspaces and available permissions; the human can narrow them. Current membership and role still limit each operation. Use access --open for missing or expired grants. Local credential/network errors are not grant denials. Valid tokens are read without a lock; refreshing needs local write and network access. Never change grants to fix a local sandbox denial.\n\n' +
+        'Permissions: ' + SCOPES.join(', ') + '.\n\nUse the same request ID and unchanged input when retrying an uncertain mutation. Definitions are complete JSON files. Read each resource before changing its revision.\n\n' +
+        commandCatalog.map(item => '## ' + item.command + '\n\n' + item.summary + '\n\n```sh\n' + item.usage + '\n```\n\n' + (item.scopes.length ? 'Required scope: ' + item.scopes.join(', ') + '.\n\n' : '') + item.notes.join(' ') + '\n').join('\n');
+}

package/dist/client.d.ts

@@ -1,6 +1,11 @@
 import { type Account, type Credentials, type GrantRequest, type Scope, type Site, type Workspace } from "./contracts.js";
 import type { ClientConfig } from "./config.js";
 import { type Fetch } from "./workos.js";
+export type PromptAction = 'create' | 'update' | 'publish' | 'pause' | 'resume' | 'archive';
+export type AudienceAction = 'create' | 'update' | 'publish' | 'discard' | 'archive';
+/** What the dashboard reads beside records: results, the response feed, users, events and members. */
+export declare const READ_OPERATIONS: readonly ["insights.overview", "insights.prompt", "insights.experiments", "insights.breakdown", "responses.list", "users.list", "users.get", "users.eligibility", "prompts.validate", "prompts.history", "events.overview", "site.activity", "members.list"];
+export type ReadOperation = typeof READ_OPERATIONS[number];
 export declare class ApiError extends Error {
     status: number;
     code: string;
@@ -18,23 +23,30 @@ export declare class UserReasonClient {
     });
     private token;
     request(path: string, body?: unknown): Promise<unknown>;
+    private authenticatedRequest;
+    previewCaptures(workspaceId: string, siteId: string, forUpload?: boolean): Promise<unknown>;
+    uploadPreview(workspaceId: string, siteId: string, name: string, html: Uint8Array): Promise<unknown>;
+    deletion(operation: 'preview' | 'request' | 'status', input: Record<string, unknown>): Promise<unknown>;
     account(): Promise<Account>;
     createWorkspace(name: string, options?: {
         requestId?: string;
         workspaceId?: string;
     }): Promise<Workspace>;
     sites(workspaceId: string): Promise<Site[]>;
+    siteById(siteId: string): Promise<Site>;
     createSite(input: {
         workspaceId: string;
         name: string;
         environment: Site["environment"];
-        origins: string[];
+        origins?: string[];
         requestId?: string;
         siteId?: string;
     }): Promise<Site>;
     requestGrant(input: {
         workspaceId?: string;
         siteIds?: string[];
+        allWorkspaces?: boolean;
+        workspaceIds?: string[];
         scopes: Scope[];
         requestId?: string;
     }): Promise<GrantRequest>;
@@ -45,8 +57,67 @@ export declare class UserReasonClient {
         workspaceId: string;
         siteId?: string;
         resource: string;
+        eventCaptureMode?: string;
+        eventCollectionLimits?: unknown;
         limit?: number;
         after?: string;
+        id?: string;
+        promptId?: string;
+    }): Promise<unknown>;
+    /** A read-only view of one workspace (members) or one of its sites (everything else). Empty values are left out. */
+    read(operation: ReadOperation, input: {
+        workspaceId: string;
+        siteId?: string;
+    } & Record<string, unknown>): Promise<unknown>;
+    /** One site as stored, with its revision and frequency policy (null while it follows the starting values). */
+    siteRecord(input: {
+        workspaceId: string;
+        siteId: string;
+    }): Promise<Record<string, unknown>>;
+    prompts(input: {
+        workspaceId: string;
+        siteId: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    prompt(input: {
+        workspaceId: string;
+        siteId: string;
+        promptId: string;
+    }): Promise<Record<string, unknown>>;
+    promptCommand(input: {
+        workspaceId: string;
+        siteId: string;
+        action: PromptAction;
+        promptId: string;
+        requestId: string;
+        revision?: string;
+        definition?: Record<string, unknown>;
+    }): Promise<unknown>;
+    /** Saved audiences: named conditions that several prompts of a site share. */
+    audiences(input: {
+        workspaceId: string;
+        siteId: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    audience(input: {
+        workspaceId: string;
+        siteId: string;
+        audienceId: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Create and update save a draft from `{ name, description, rule }`. Publish makes every prompt
+     * that names the audience follow the new version at once; read `used_by` first.
+     */
+    audienceCommand(input: {
+        workspaceId: string;
+        siteId: string;
+        action: AudienceAction;
+        audienceId: string;
+        requestId: string;
+        revision?: string;
+        audience?: Record<string, unknown>;
     }): Promise<unknown>;
     waitForGrant(id: string, options?: {
         timeoutMs?: number;