@userreason/cli 0.1.1 → 0.2.1

package/README.md

@@ -121,3 +121,220 @@ site's environment is separate from the API environment.
 
 See [troubleshooting](https://docs.userreason.com/get-started/troubleshooting/)
 for installation, sign-in and configuration help.
+
+## Optional usage measurement
+
+The CLI reports canonical command types, success/failure counts, durations,
+execution mode and its version to the UserReason API. It never reports command
+arguments, documentation searches, file paths, source code, command output,
+raw errors, email addresses or credentials as analytics properties. Signed-in
+requests can be associated with the verified UserReason account and workspace;
+anonymous usage uses a random local installation ID. Switching accounts never
+attributes an earlier account's queued activity to the next account.
+
+Usage is batched in the per-user UserReason configuration directory, outside
+your project, with a seven-day expiry, bounded storage and an upload deadline of
+500 ms for anonymous batches or 1.5 seconds for authenticated batches. Failed
+uploads do not change command output or exit status.
+`--offline` sends no analytics requests. Local command discovery (`cli`) also
+stays offline. The queue is retried on later online commands; aggregated command
+counts, rather than the number of batches, describe usage.
+
+Disable for one invocation with `--no-telemetry`, for a process or CI job with
+`UR_TELEMETRY_DISABLED=1` (or `DO_NOT_TRACK=1`), or persistently with:
+
+```sh
+userreason telemetry disable
+userreason telemetry status
+userreason telemetry enable
+```
+
+The persistent setting is shared with the installation wizard. Disabling it
+also removes locally queued analytics and the random installation identity.
+
+### Schedule a survey and set collection targets
+
+The JSON definition accepted by `prompt create` and `prompt update` supports an
+optional `rules.collection` object. For example:
+
+```json
+{
+  "starts_at": "2026-10-20T07:00:00.000Z",
+  "ends_at": "2026-10-27T16:00:00.000Z",
+  "time_zone": "Europe/Amsterdam",
+  "response_target": 500,
+  "daily_response_target": 50
+}
+```
+
+Publish the saved draft through the normal prompt command. Use null for an unset
+timestamp or unlimited target, or omit the object for no schedule/targets. Targets
+are shared across the campaign's versions, experiments and enrollments. They stop
+new admissions while allowing already-admitted surveys to finish. `prompt list`
+and prompt reads include the current collection state and completed counts.
+
+## Conversational surveys (development)
+
+The development API accepts a terminal conversation as a text question with a
+versioned `conversation` setting. Use the existing `prompt create`, `update`,
+`validate` and `publish` commands with the complete definition. Read
+`https://docs-dev.userreason.com/prompts/conversations/` for the current schema.
+A conversation stands alone or starts an experiment version; it cannot follow a
+rating. Quick, Focused and In-depth presets limit follow-ups and time. Review and
+Send remain separate: only the visitor's accepted answer is a response.
+
+```sh
+userreason workspace ai get --dev --workspace WORKSPACE_UUID
+userreason workspace ai get --dev --workspace WORKSPACE_UUID --site SITE_UUID
+userreason workspace ai set --dev --workspace WORKSPACE_UUID --file AI-SETTINGS.json
+userreason results conversations PROMPT_UUID --dev --workspace WORKSPACE_UUID --site SITE_UUID
+userreason conversation get CONVERSATION_UUID --dev --workspace WORKSPACE_UUID --site SITE_UUID
+```
+
+`AI-SETTINGS.json` contains only the fields to change, for example
+`{"enabled":true,"voice_enabled":false}`. Owners and admins manage allowance
+controls. To change site context, pass one `--site` and a file such as
+`{"product_context":"Scheduled reports email PDF or CSV files."}`; editors can
+update that site context. Missing settings keep their current value.
+
+Typed, spoken and live-test sessions share workspace AI allowance. Scripted
+preview uses no allowance. Accepted text, transcript, and optional generated
+analysis have different provenance; generated analysis is not a visitor answer.
+These commands require the matching development backend and private development
+package set. Public npm `latest` remains unchanged by this rollout.
+
+## Browser setup client and local execution
+
+The exported setup-v1 client provides a proof-bound handshake, strict bounded
+protocol reads, heartbeat/claim/result adapters and `runSetupExecutor` with a per-project lock for the
+browser-driven wizard. It uses a separate owner-only `setup-v1` store
+outside the project; it neither reads nor replaces normal login credentials.
+Loading a selected expired setup removes its capability. New setup saves lazily
+inspect at most 128 directory entries and remove validated setup records at
+least seven days old; later saves handle remaining batches. There is no cleanup
+daemon. Unknown files, symlinks, project files, locks and normal login credentials
+are left alone.
+The server must explicitly advertise `browser_setup` v1 as enabled. Old or
+disabled servers return an unsupported result before local effects. A started
+setup never silently falls back to a different installation flow.
+
+Setup requests also propagate `--no-telemetry`, the shared saved opt-out,
+`UR_TELEMETRY_DISABLED` and `DO_NOT_TRACK` to optional server-side setup
+measurement. Unreadable preference state suppresses measurement without blocking
+the setup request. Browser measurement preferences remain separate.
+
+An active setup can request its simulated sample using:
+
+```sh
+userreason setup sample --setup SETUP_UUID --directory /path/to/original/project --json
+```
+
+Use `--api-url` or `--dev` for the same API as that setup. This operation requires
+its unexpired local setup capability and an open sample-test step. It reads a
+clearly labelled static sample and records only that setup's read receipt; it
+does not read real feedback, create responses, consume response quota, publish
+surveys or authorize ongoing CLI access. The ID in the command is not a bearer
+credential. Setup credentials are never printed. `--request-id UUID` permits an
+explicit idempotent retry of the read.
+
+The executor accepts only locally prepared, browser-approved typed operations.
+It writes a private intent before starting, verifies exact source/manifest hashes,
+and records the result before reporting. Package-manager lockfiles are declared
+managed outputs: their contents are generated during dependency resolution and
+their actual hashes are saved in the local receipt, rather than predicted.
+After an interruption it reconciles known output; it never blindly reruns an
+unknown command. `recoverSetupProjectLock` explicitly releases a crashed owner's
+lock only after that process is gone. Local receipts contain prepared file bytes,
+stay outside the project with owner-only permissions, and expire after seven
+days. Lazy cleanup is bounded; receipts never restore expired remote access.
+The browser executor requires durable file synchronization (`fsync`). Node 24
+permission mode disables that operation even for allowed paths, so setup stops
+before server calls or application changes under those flags. It does not remove
+permission flags or fall back to nondurable receipts.
+
+`detectSetupTerminal` emits fixed platform/app codes only. Installing the project
+agent skill does not grant continuing management access. Ordinary CLI login,
+terminal installation and first-survey commands are unchanged.
+
+`runBrowserSetup` connects this executor to the optional browser onboarding flow.
+The server's source-analysis flag is checked before collecting any source. The
+local collector prepares a bounded, memory-only application packet with no Git
+history. `onSourcePrepared` can display the exact excerpts locally; the initial
+`source-plan` request contains only relative paths, line ranges, hashes and package
+metadata. The browser separately approves that packet digest and configured
+providers. Immediately before `source-upload`, the runner rechecks all full-file
+hashes, recollects the same snapshot and validates installed package metadata.
+Source text is never saved in setup receipts. Resuming rebuilds the original
+snapshot ID and refuses changed content until the browser reviews a fresh packet.
+
+Heartbeat continues while the bounded analysis request runs. A dropped response
+is reconciled by polling, not a repeated provider call. A failed preparation or
+analysis needs a browser retry or skip. The browser owns candidate selection,
+inactive draft creation, sample skip, finish and cancellation. The local runner
+cannot create drafts, publish surveys or change ongoing CLI grants. Server rollout
+flags remain off by default; these are prepared clients for a compatible release.
+
+## Optional first-survey guidance
+
+The development wizard also uses the exported `starterSurvey` flow. It provides
+one-question starters for improvement, workflow friction and satisfaction, with
+optional background personalization. Local preparation after sign-in is
+memory-only; provider processing still needs approval of the exact source packet.
+The model returns wording and cited rationale, while the Worker compiles the
+inactive draft. Users keep control of their edits and choose delivery separately.
+An unconfigured starter matches nobody, even if it is later published unchanged.
+Draft save receipts survive a lost response so retries use the same identifiers.
+This does not change the legacy `first-survey start` command.
+
+`userreason first-survey start --workspace WORKSPACE_UUID --site SITE_UUID
+--directory /absolute/app` offers interactive, evidence-backed suggestions and
+individual unpublished draft creation. Repeating the command resumes the private
+session. `handoff` prints a coding-agent task; `cancel` prevents further work;
+`delete` removes the retained plan (not already-created drafts). No publication
+or source edits are automatic. Noninteractive/JSON runs cannot authorize analysis.
+
+Only a reviewed packet from the explicit application root is uploaded. Default
+bounds: 200 files, 500 KiB local text, 10 KiB source packet, 12,000 input and 4,000
+output tokens, one clarification round. Symlinks, ignored/generated files and
+files with detected secrets are omitted. Detection is best effort: review every
+excerpt. Git subjects need separate consent and are limited to 20 commits/90 days;
+no authors, diffs or network fetch. Narrow the selected paths when truncated.
+
+Before saving, the review shows every question, rating label, answer option and
+conditional route in the returned definition. The analysis deadline is 35 seconds;
+the transport allows the backend's maximum deadline without cutting it off early.
+Draft validation remains authoritative: unsupported survey behavior cannot be
+silently converted or published by this flow.
+
+The provider destination and configured policy are shown before approval. Local
+sessions contain hashes, private proposals and mutation receipts, never submitted source
+packets or credentials (generated plans can quote source); protect their owner-only config directory. They expire
+after seven days. Worker plans expire after seven days and are purged on subsequent
+planning activity; provider retention is separately configured/disclosed. Drafts
+have their normal account retention. Deletion retains a content-free budget
+receipt until expiry so it cannot reset allowance. No first-survey content is sent
+to product telemetry.
+
+Analysis requires an ongoing connection with `site:read` and `survey:write` on the
+exact site; installation grants do not suffice. Use `access --open` if necessary,
+reviewing replacement-grant semantics rather than broadening installation access.
+Provider errors do not undo installation. Use the agent/manual workflow when
+analysis is unavailable. Integration and browser eligibility remain unverified
+until tested: reachable configuration is not browser verification. Instrumentation
+requires a reviewed, hash-guarded diff and separate edit approval using the agent
+skill; unsupported host transforms are never executed automatically.
+
+The 0.2.1 production installation profile selects `@userreason/js@0.5.3` and
+`@userreason/cli@0.2.1` exactly. Browser setup remains an explicit wizard entry
+and requires an enabled compatible server; ordinary CLI authentication and
+management commands retain their existing authorization flow.
+
+Local setup execution failures retain bounded, redacted diagnostic text in the
+private execution receipt. `onOperationError` displays it on failure and resume.
+The detailed text never enters setup API requests or telemetry; the server still
+receives only the typed outcome code.
+
+A new run automatically recovers an existing project lock only after verifying
+that its recorded process no longer exists. It still acquires the lock exclusively,
+keeps all installation receipts for reconciliation, and refuses live, unreadable
+or malformed locks. A live-lock error identifies the process to finish or stop.

package/dist/bin.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import { firstSurvey } from './first-survey.js';
+import { firstSurveyTerminalUI } from './first-survey-terminal.js';
+import { createInterface } from 'node:readline/promises';
+import { realpath } from 'node:fs/promises';
 import { eventCollection } from './event-policy.js';
 import { CaptureError, capturePage, captureUrl } from './capture.js';
 import { randomUUID } from "node:crypto";
@@ -19,8 +23,14 @@ import { docsOrigin, packageProfile } from "./profile.js";
 import { createSpinner, createUiKit, detectAgentHarness, detectColorLevel } from './ui.js';
 import { nounHelp, overviewHelp, overviewNouns, suggestCommand } from './help.js';
 import { grantSummary, promptsView, resultsOverviewView, sitesView, whoamiView, workspacesView } from './views.js';
+import { ToolTelemetry, telemetryCommand, telemetryEnabled, setTelemetryEnabled } from './telemetry.js';
+import { resumeBrowserSetup } from './setup.js';
+import { SetupError } from './setup-store.js';
 /** Terminal styling applies only to a person at a terminal: never when piped, with --json, or in an agent harness. */
 let errorStyle;
+let analytics;
+let analyticsCommand = 'unknown';
+const analyticsStarted = performance.now();
 const cliVersion = () => { try {
     return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 }
@@ -97,22 +107,35 @@ async function readJsonFile(file) {
 }
 async function main() {
     const parsed = parseArgs({ allowPositionals: true, strict: true, options: {
-            all: { type: "boolean" }, human: { type: "boolean" }, "no-color": { type: "boolean" },
+            directory: { type: "string" }, all: { type: "boolean" }, human: { type: "boolean" }, "no-color": { type: "boolean" }, "no-telemetry": { type: 'boolean' },
             width: { type: 'string' }, height: { type: 'string' }, 'capture-bin': { type: 'string' }, 'browser-executable': { type: 'string' }, interactive: { type: 'boolean' },
             preview: { type: "boolean" }, confirm: { type: "string" }, help: { type: "boolean", short: "h" }, json: { type: "boolean" }, dev: { type: "boolean" }, open: { type: "boolean" }, wait: { type: "boolean" }, "no-wait": { type: "boolean" },
             offline: { type: "boolean" }, live: { type: "boolean" }, "credential-store": { type: "string" }, "api-url": { type: "string" }, "docs-url": { type: "string" }, "client-id": { type: "string" }, name: { type: "string" }, workspace: { type: "string" }, id: { type: "string" },
             origin: { type: "string", multiple: true }, scope: { type: "string", multiple: true }, site: { type: "string", multiple: true }, environment: { type: "string" },
-            "request-id": { type: "string" }, "workspace-id": { type: "string" }, "site-id": { type: "string" },
+            "request-id": { type: "string" }, setup: { type: "string" }, "workspace-id": { type: "string" }, "site-id": { type: "string" },
             file: { type: "string" }, "context-file": { type: "string" }, purpose: { type: "string" }, mode: { type: "string" }, "confirmation-token": { type: "string" }, resource: { type: "string" }, limit: { type: "string" }, after: { type: "string" }, revision: { type: "string" }, "prompt-id": { type: "string" },
             days: { type: "string" }, "time-zone": { type: "string" }, country: { type: "string" }, segment: { type: "string" }, by: { type: "string" }, user: { type: "string" }, kind: { type: "string" }, search: { type: "string" }, cursor: { type: "string" },
             run: { type: 'string' }, variant: { type: 'string' }, 'all-attempts': { type: 'boolean' }, 'reported-only': { type: 'boolean' },
         } });
     const values = parsed.values, [command, action, positionalId] = parsed.positionals;
+    if (command === 'telemetry') {
+        if (action === 'enable' || action === 'disable')
+            await setTelemetryEnabled(action === 'enable');
+        else if (action !== 'status')
+            throw new Error('Use userreason telemetry enable, disable or status');
+        process.stdout.write(JSON.stringify({ enabled: await telemetryEnabled() }) + '\n');
+        return;
+    }
     if (action === 'delete' && positionalId && command === 'workspace')
         values.workspace = uuid(positionalId);
     if (action === 'delete' && positionalId && command === 'site')
         values.site = [uuid(positionalId)];
     const harness = detectAgentHarness();
+    analyticsCommand = telemetryCommand(parsed.positionals, values.help);
+    try {
+        analytics = new ToolTelemetry({ surface: 'cli', releaseVersion: cliVersion() ?? 'unknown', executionMode: process.env.CI ? 'ci' : harness ? 'agent' : process.stdin.isTTY ? 'interactive' : 'noninteractive', apiUrl: values['api-url'] ?? process.env.UR_API_URL ?? ((values.dev ?? developmentApi()) ? 'https://api-dev.userreason.com' : 'https://api.userreason.com'), disabled: values['no-telemetry'] || values.help || !command, offline: values.offline || command === 'cli' });
+    }
+    catch { /* Optional telemetry never changes command validation. */ }
     const humanOut = Boolean(process.stdout.isTTY) && !values.json && (!harness || Boolean(values.human));
     const humanErr = Boolean(process.stderr.isTTY) && !values.json && (!harness || Boolean(values.human));
     const kit = createUiKit({ level: detectColorLevel({ stream: process.stdout, off: values["no-color"] }) });
@@ -123,7 +146,7 @@ async function main() {
         process.stdout.write(values.all ? cliHelp() : noun ?? overviewHelp(kit, { version: cliVersion(), development: values.dev ?? developmentApi(), trademark: humanOut }));
         return;
     }
-    if (!overviewNouns.includes(command)) {
+    if (command !== "first-survey" && !overviewNouns.includes(command)) {
         const guess = suggestCommand(command);
         throw new UnknownCommand(command, guess);
     }
@@ -145,6 +168,19 @@ async function main() {
     }
     if (values.offline && values.live)
         throw new Error('Choose --offline or --live');
+    if (command === 'setup') {
+        if (action !== 'sample' || parsed.positionals.length !== 2)
+            throw new Error('Use userreason setup sample --setup UUID [--directory PATH]');
+        if (values.offline)
+            throw new Error('Reading the setup sample requires the setup service; omit --offline.');
+        if (values.workspace || values.site || values['client-id'] || values['credential-store'])
+            throw new Error('The setup sample uses only the selected setup session, not workspace flags or a general CLI login.');
+        const origin = values['api-url'] ?? process.env.UR_API_URL ?? ((values.dev ?? developmentApi()) ? 'https://api-dev.userreason.com' : 'https://api.userreason.com');
+        const { client } = await resumeBrowserSetup(origin, uuid(required('setup')), values.directory ?? process.cwd(), { measurementDisabled: values['no-telemetry'] });
+        const sample = await client.sample(values['request-id'] ? uuid(values['request-id']) : undefined);
+        process.stdout.write(JSON.stringify(sample, null, values.json ? undefined : 2) + '\n');
+        return;
+    }
     if (command === "docs") {
         // Public documentation: no login, saved configuration or credential store is involved.
         let projectDevelopment;
@@ -178,7 +214,7 @@ async function main() {
         project = await detectProjectTarget();
     }
     catch (error) {
-        if (!values.workspace && !values.site)
+        if (!values.workspace && !values.site && !(command === 'whoami' && error.code === 'ERR_ACCESS_DENIED'))
             throw error;
     }
     const explicitApi = values["api-url"] ?? process.env.UR_API_URL ?? (values.dev ? 'https://api-dev.userreason.com' : undefined);
@@ -187,8 +223,10 @@ async function main() {
     const selectedApi = explicitApi ?? project?.apiUrl;
     const development = values.dev ?? (selectedApi === 'https://api-dev.userreason.com' ? true : selectedApi === 'https://api.userreason.com' ? false : packageProfile().apiEnvironment === 'development');
     const config = await resolveConfig({ development, apiUrl: selectedApi, clientId: values["client-id"], credentialStore: values["credential-store"] });
-    const credentials = resolveCredentials(config), client = new UserReasonClient(config, credentials);
-    const targeting = ['preview', 'prompt', 'audience', 'results', 'responses', 'user', 'event', 'member', 'query', 'site'].includes(command);
+    analytics?.configure({ apiUrl: config.apiUrl });
+    const rawCredentials = resolveCredentials(config);
+    const credentials = analytics?.observeCredentials(rawCredentials) ?? rawCredentials, client = new UserReasonClient(config, credentials);
+    const targeting = ['conversation', 'preview', 'prompt', 'audience', 'results', 'responses', 'user', 'event', 'member', 'query', 'site'].includes(command);
     let targetName;
     if (targeting && !values.workspace) {
         const siteId = values.site?.length === 1 ? values.site[0] : project?.siteId;
@@ -204,8 +242,29 @@ async function main() {
                     : `Using ${printable(site.name)} (${site.id}) on ${config.apiUrl}\n`);
         }
     }
+    analytics?.configure({ context: { ...(values.workspace ? { workspace_id: values.workspace } : {}), ...(values.site?.length === 1 ? { site_id: values.site[0] } : {}), ...(values.environment === 'development' || values.environment === 'production' ? { source_site_environment: values.environment } : {}) } });
     let result;
-    if (command === "login" || command === "access") {
+    if (command === 'first-survey') {
+        if (values.site?.length !== 1)
+            throw new Error('Select exactly one site');
+        if (!['start', 'handoff', 'cancel', 'delete'].includes(action ?? ''))
+            throw new Error('Use first-survey start, handoff, cancel or delete');
+        if (action === 'start' && (!process.stdin.isTTY || values.json))
+            throw new Error('Guided source consent requires an interactive terminal; use first-survey handoff for an agent task');
+        const abort = new AbortController();
+        const cancel = () => abort.abort();
+        process.once('SIGINT', cancel);
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        rl.on('SIGINT', cancel);
+        try {
+            result = await firstSurvey(client, await realpath(values.directory ?? process.cwd()), uuid(required('workspace')), uuid(values.site[0]), firstSurveyTerminalUI(rl, process.stderr, abort.signal), action);
+        }
+        finally {
+            rl.close();
+            process.off('SIGINT', cancel);
+        }
+    }
+    else if (command === "login" || command === "access") {
         const open = (url) => {
             if (!values.open)
                 return;
@@ -328,6 +387,25 @@ async function main() {
             result = await client.deletion('request', { ...target, request_id, expected_revision: required('revision'), confirmation_token: required('confirmation-token'), confirm_name: values.confirm });
         }
     }
+    else if (command === 'workspace' && action === 'ai') {
+        const context = { workspaceId: uuid(required('workspace')), ...(values.site?.length === 1 ? { siteId: uuid(values.site[0]) } : {}) };
+        if (values.site && values.site.length !== 1)
+            throw new Error('AI settings accept at most one --site');
+        const sub = parsed.positionals[2];
+        if (sub === 'get')
+            result = await client.read('workspace.ai', context);
+        else if (sub === 'set')
+            result = await client.updateWorkspaceAi({ ...context, settings: await readJsonFile(required('file')) });
+        else
+            throw new Error('Use workspace ai get or workspace ai set --file SETTINGS.json');
+    }
+    else if (command === 'conversation') {
+        if (action !== 'get')
+            throw new Error('Use conversation get UUID');
+        if (values.site?.length !== 1)
+            throw new Error('This command requires one --site');
+        result = await client.read('conversation.transcript', { workspaceId: uuid(required('workspace')), siteId: uuid(values.site[0]), conversation_id: uuid(positionalId ?? required('id')) });
+    }
     else if (command === "workspace" && action === "list")
         result = (await client.account()).workspaces;
     else if (command === "workspace" && action === "create")
@@ -364,6 +442,8 @@ async function main() {
                 result = await client.read('insights.overview', { ...context, ...range, ...filters });
             else if (command === "results" && action === "prompt")
                 result = await client.read('insights.prompt', { ...context, ...range, ...filters, prompt_id: uuid(positionalId ?? required("prompt-id")) });
+            else if (command === 'results' && action === 'conversations')
+                result = await client.read('insights.conversations', { ...context, ...range, ...filters, prompt_id: uuid(positionalId ?? required('prompt-id')) });
             else if (command === "results" && action === "experiments")
                 result = await client.read('insights.experiments', { ...context, prompt_id: uuid(positionalId ?? required('prompt-id')), run_id: values.run, all_attempts: values['all-attempts'] ?? false, reported_only: values['reported-only'] ?? false });
             else if (command === "results" && action === "breakdown")
@@ -498,6 +578,8 @@ async function main() {
     // A person at a terminal has just read the progress lines; the JSON result needs --json or a pipe.
     if ((command === 'login' || command === 'access') && humanOut && !values["no-wait"])
         return;
+    if (command === 'first-survey' && !values.json)
+        return;
     const view = humanOut ? humanView(kit, command, action, result) : undefined;
     process.stdout.write((view ? view.join('\n') : humanOut ? kit.json(result) : JSON.stringify(result, null, values.json ? undefined : 2)) + "\n");
     function humanView(ui, name, verb, data) {
@@ -519,7 +601,7 @@ async function main() {
 }
 main().catch(error => {
     const json = process.argv.includes("--json");
-    const detail = { error: error instanceof ApiError || error instanceof DocsError || error instanceof CredentialStoreError || error instanceof NetworkError || error instanceof AuthenticationError || error instanceof ConfigurationError || error instanceof CaptureError ? error.code : "command_failed", message: error instanceof Error ? error.message : "Command failed", ...(error instanceof ApiError && error.approvalUrl ? { approval_url: error.approvalUrl } : {}), ...(retry ? { retry } : {}) };
+    const detail = { error: error instanceof ApiError || error instanceof DocsError || error instanceof CredentialStoreError || error instanceof NetworkError || error instanceof AuthenticationError || error instanceof ConfigurationError || error instanceof CaptureError || error instanceof SetupError ? error.code : "command_failed", message: error instanceof Error ? error.message : "Command failed", ...(error instanceof ApiError && error.approvalUrl ? { approval_url: error.approvalUrl } : {}), ...(retry ? { retry } : {}) };
     const exitCode = error instanceof CaptureError && error.code === 'capture_cancelled' ? 130 : 1;
     if (error instanceof ApiError && error.code === 'authorization_required')
         detail.message += '. The current login lacks access to this target. Run userreason access --open to review workspace access and permissions.';
@@ -530,4 +612,7 @@ main().catch(error => {
     }
     process.stderr.write((json ? JSON.stringify(detail) : detail.message + (retry ? `\nRetry with the same input, --id ${retry.prompt_id} --request-id ${retry.request_id}; read the survey first if changing the request.` : "")) + "\n");
     process.exitCode = exitCode;
+}).finally(async () => {
+    analytics?.command(analyticsCommand, !process.exitCode, performance.now() - analyticsStarted);
+    await analytics?.flush();
 });

package/dist/catalog.js

@@ -1,6 +1,9 @@
 import { SCOPES } from './contracts.js';
 // Shared by terminal help, offline command discovery, and the bundled CLI reference.
-const usages = `userreason login [--open]
+const usages = `userreason telemetry enable|disable|status
+userreason setup sample --setup UUID [--directory PATH] [--request-id UUID]
+userreason first-survey start|handoff|cancel|delete --workspace UUID --site UUID [--directory PATH]
+userreason login [--open]
 userreason access [--open] [--no-wait]
 userreason logout
 userreason whoami
@@ -8,6 +11,9 @@ 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 ai get --workspace UUID [--site UUID]
+userreason workspace ai set --file SETTINGS.json --workspace UUID [--site UUID]
+userreason conversation get UUID --workspace UUID --site UUID
 userreason workspace list
 userreason workspace create --name NAME
 userreason site list --workspace UUID
@@ -29,6 +35,7 @@ userreason audience update UUID --file AUDIENCE.json --revision N --workspace UU
 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 conversations UUID --workspace UUID --site UUID [--days N]
 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]
@@ -54,16 +61,23 @@ userreason cli search "QUESTION" [--limit 5]
 userreason cli get "COMMAND"
 userreason cli list`;
 const descriptions = {
+    setup: 'Read the clearly simulated answers for one active browser setup using its separate local setup capability; no ordinary login or real response data.',
+    telemetry: 'Enable, disable or inspect optional anonymous usage measurement. UR_TELEMETRY_DISABLED=1 and --no-telemetry disable it too.',
     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.',
+    'first-survey': 'Review consented source-backed proposals and explicitly save real unpublished drafts; handoff requires no upload.',
     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.',
+    'workspace ai get': 'Read the shared conversation allowance and optional site product context.',
+    'workspace ai set': 'Update authorized conversation controls or site product context from a complete settings file.',
+    conversation: 'Read a conversation transcript and reviewed answer with source provenance.',
+    'results conversations': 'Read conversational survey results, completion, timing and answer evidence.',
     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.',
@@ -94,10 +108,16 @@ const descriptions = {
 export const commandSummary = (command) => descriptions[command];
 function scopeFor(command) {
     const [group, action] = command.split(' ');
+    if (group === 'first-survey')
+        return action === 'handoff' ? [] : ['site:read', 'survey:write'];
     if (group === 'preview')
         return ['site:read', 'survey:write'];
     if (action === 'delete')
         return ['resource:delete'];
+    if (command === 'workspace ai set')
+        return ['workspace:read'];
+    if (group === 'conversation')
+        return ['site:read'];
     if (group === 'workspace')
         return [action === 'create' ? 'workspace:create' : 'workspace:read'];
     if (group === 'member')
@@ -117,14 +137,20 @@ function scopeFor(command) {
 }
 export const commandCatalog = usages.split('\n').flatMap(line => {
     const withoutBinary = line.replace(/^userreason /, '');
-    const path = withoutBinary.match(/^[a-z]+(?:[| ][a-z]+)*/)?.[0].trim() ?? '';
+    const path = withoutBinary.match(/^[a-z]+(?:-[a-z]+)*(?:[| ][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 targeted = ['conversation', '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 === 'workspace ai set')
+            notes.push('Owner/admin is required for workspace allowance controls. Site product context accepts editors. Updating one setting does not reset omitted settings.');
+        if (command.startsWith('conversation') || command === 'results conversations')
+            notes.push('Development feature. Accepted answers are separate from generated analysis; retain speaker, typed/spoken and recorded/live provenance.');
         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 (command === 'setup sample')
+            notes.push('Requires an explicitly selected setup ID and its unexpired local capability for this API/project. Records only a setup-scoped sample-read receipt; never creates real responses, consumes response quota or grants ongoing access. Browser setup must be enabled by the server.');
         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))

package/dist/client.d.ts

@@ -4,7 +4,7 @@ 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 declare const READ_OPERATIONS: readonly ["workspace.ai", "conversation.transcript", "insights.conversations", "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;
@@ -22,7 +22,7 @@ export declare class UserReasonClient {
         lock?: <T>(operation: () => Promise<T>) => Promise<T>;
     });
     private token;
-    request(path: string, body?: unknown): Promise<unknown>;
+    request(path: string, body?: unknown, signal?: AbortSignal): Promise<unknown>;
     private authenticatedRequest;
     previewCaptures(workspaceId: string, siteId: string, forUpload?: boolean): Promise<unknown>;
     uploadPreview(workspaceId: string, siteId: string, name: string, html: Uint8Array): Promise<unknown>;
@@ -69,6 +69,12 @@ export declare class UserReasonClient {
         workspaceId: string;
         siteId?: string;
     } & Record<string, unknown>): Promise<unknown>;
+    /** Workspace allowance settings and optional site product context; server enforces the caller's role. */
+    updateWorkspaceAi(input: {
+        workspaceId: string;
+        siteId?: string;
+        settings: 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;

package/dist/client.js

@@ -4,7 +4,7 @@ import { refresh, AuthenticationError } from "./workos.js";
 import { withSessionLock } from "./lock.js";
 import { fetchWithErrors } from './errors.js';
 /** What the dashboard reads beside records: results, the response feed, users, events and members. */
-export const READ_OPERATIONS = ['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 const READ_OPERATIONS = ['workspace.ai', 'conversation.transcript', 'insights.conversations', '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 class ApiError extends Error {
     status;
     code;
@@ -27,8 +27,9 @@ export class UserReasonClient {
         this.options = options;
         this.fetcher = options.fetcher ?? fetch;
     }
-    async token(forceRefresh = false, previous) {
+    async token(forceRefresh = false, previous, signal) {
         const read = async () => {
+            signal?.throwIfAborted();
             const current = await this.credentials.load();
             if (!current)
                 throw new AuthenticationError('login_required', 'Run userreason login --open first. Existing Keychain logins can be used with --credential-store keychain.');
@@ -49,20 +50,25 @@ export class UserReasonClient {
                 return current;
             if (current.accessToken.startsWith('ur-install.'))
                 throw new AuthenticationError('installation_expired', 'Installation access expired or was revoked; rerun the wizard to reconnect');
-            return refresh(this.config, this.credentials, current, this.fetcher);
+            return refresh(this.config, this.credentials, current, this.fetcher, signal);
         });
     }
-    async request(path, body) {
-        return this.authenticatedRequest(path, body === undefined ? undefined : JSON.stringify(body), 'application/json');
+    async request(path, body, signal) {
+        return this.authenticatedRequest(path, body === undefined ? undefined : JSON.stringify(body), 'application/json', signal);
     }
-    async authenticatedRequest(path, body, contentType) {
+    async authenticatedRequest(path, body, contentType, signal) {
         if (!path.startsWith("/onboarding/v1/") || path.includes("//") || path.includes("\\"))
             throw new Error("Invalid UserReason API path");
-        let session = await this.token();
+        // Planning may use the API's full 40-second deadline. One transport budget
+        // also bounds authentication refresh; cancellation must survive a retry.
+        const requestSignal = AbortSignal.any([AbortSignal.timeout(path === '/onboarding/v1/planning/analyze' ? 45_000 : 20_000), ...(signal ? [signal] : [])]);
+        requestSignal.throwIfAborted();
+        let session = await this.token(false, undefined, requestSignal);
         for (let attempt = 0; attempt < 2; attempt++) {
-            const response = await fetchWithErrors(this.fetcher, this.config.apiUrl + path, { method: body === undefined ? "GET" : "POST", redirect: "error", headers: { Authorization: `Bearer ${session.accessToken}`, "x-ur-client": "cli", "Content-Type": contentType }, ...(body === undefined ? {} : { body: body }), signal: AbortSignal.timeout(20_000) }, 'UserReason API request');
+            requestSignal.throwIfAborted();
+            const response = await fetchWithErrors(this.fetcher, this.config.apiUrl + path, { method: body === undefined ? "GET" : "POST", redirect: "error", headers: { Authorization: `Bearer ${session.accessToken}`, "x-ur-client": "cli", "Content-Type": contentType }, ...(body === undefined ? {} : { body: body }), signal: requestSignal }, 'UserReason API request');
             if (response.status === 401 && attempt === 0) {
-                session = await this.token(true, session.accessToken);
+                session = await this.token(true, session.accessToken, requestSignal);
                 continue;
             }
             let result;
@@ -167,18 +173,27 @@ export class UserReasonClient {
         if (!READ_OPERATIONS.includes(operation))
             throw new Error("Unsupported read operation");
         const { workspaceId, siteId, ...rest } = input;
-        if (operation !== 'members.list' && !siteId)
+        if (!['members.list', 'workspace.ai'].includes(operation) && !siteId)
             throw new Error("This read requires a site");
         if (rest.run_id !== undefined)
             uuid(string(rest.run_id, 'Experiment run ID'));
         if (rest.variant_id && !rest.run_id)
             throw new Error('A variant filter requires an experiment run');
-        const body = { workspace_id: uuid(workspaceId), ...(operation === 'members.list' ? {} : { site_id: uuid(siteId) }) };
+        const body = { workspace_id: uuid(workspaceId), ...(operation === 'members.list' || !siteId ? {} : { site_id: uuid(siteId) }) };
         for (const [key, value] of Object.entries(rest))
             if (value !== undefined && value !== null && value !== '')
                 body[key] = value;
         return this.request(`/onboarding/v1/read/${operation}`, body);
     }
+    /** Workspace allowance settings and optional site product context; server enforces the caller's role. */
+    async updateWorkspaceAi(input) {
+        const allowed = new Set(['enabled', 'voice_enabled', 'monthly_limit_microusd', 'concurrent_limit', 'preview_daily_limit', 'product_context']);
+        if (!Object.keys(input.settings).length || Object.keys(input.settings).some(key => !allowed.has(key)))
+            throw new Error('AI settings require supported setting fields only');
+        if ('product_context' in input.settings && !input.siteId)
+            throw new Error('Product context requires a site');
+        return this.request('/onboarding/v1/workspace/ai/update', { ...input.settings, workspace_id: uuid(input.workspaceId), ...(input.siteId ? { site_id: uuid(input.siteId) } : {}) });
+    }
     /** One site as stored, with its revision and frequency policy (null while it follows the starting values). */
     async siteRecord(input) {
         const page = object(await this.query({ ...input, resource: 'sites', id: input.siteId, limit: 1 }), 'sites');