@gravity-rail/cli 0.5.0 → 0.5.1

package/dist/gr.js

@@ -1,56 +1,15 @@
 #!/usr/bin/env node
+import { CLIError, handleError, AuthRequiredError } from './chunk-XRBVAFCB.js';
+import fs, { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync, unlinkSync, createWriteStream } from 'fs';
+import path3, { join, resolve, dirname } from 'path';
 import { createServer } from 'http';
 import { randomBytes, createHash } from 'crypto';
-import { readFileSync, existsSync, mkdirSync, writeFileSync, chmodSync, unlinkSync, createWriteStream } from 'fs';
-import { join } from 'path';
 import { execSync, execFile, exec, spawn, spawnSync } from 'child_process';
 import * as readline from 'readline';
-import { homedir } from 'os';
+import readline__default from 'readline';
+import os, { homedir } from 'os';
 import { EventEmitter } from 'events';
 
-// src/lib/errors.ts
-var CLIError = class extends Error {
-  constructor(message, exitCode = 1) {
-    super(message);
-    this.exitCode = exitCode;
-    this.name = "CLIError";
-  }
-};
-var AuthRequiredError = class extends CLIError {
-  constructor(message = "Not authenticated. Run `gr login` or set GRAVITY_RAIL_API_KEY.") {
-    super(message, 2);
-    this.name = "AuthRequiredError";
-  }
-};
-function handleError(err) {
-  if (err instanceof CLIError) {
-    process.stderr.write(`Error: ${err.message}
-`);
-    process.exit(err.exitCode);
-  }
-  if (err instanceof Error) {
-    process.stderr.write(`Error: ${err.message}
-`);
-    if ("errors" in err && Array.isArray(err.errors)) {
-      for (const e of err.errors) {
-        process.stderr.write(`  - ${e}
-`);
-      }
-    }
-    if ("statusCode" in err && err.statusCode === 401) {
-      process.stderr.write(
-        `
-Hint: Run "gr login" to authenticate, or set GRAVITY_RAIL_API_KEY for non-interactive use.
-`
-      );
-    }
-    process.exit(1);
-  }
-  process.stderr.write(`Error: ${String(err)}
-`);
-  process.exit(1);
-}
-
 // src/lib/pagination.ts
 function isListResult(data) {
   if (!data || typeof data !== "object" || Array.isArray(data)) return false;
@@ -174,7 +133,7 @@ var COMMON_ARGS = [
   { name: "uuid", description: "Entity UUID" }
 ];
 function parseArgs(defs, argv) {
-  const allDefs = [...COMMON_ARGS, ...defs];
+  const allDefs = [...defs, ...COMMON_ARGS];
   const result2 = {};
   for (const def of allDefs) {
     if (def.default !== void 0) {
@@ -201,8 +160,7 @@ function parseArgs(defs, argv) {
     const def = findDef(allDefs, flagPart);
     if (!def) {
       if ((flagPart.startsWith("--") || flagPart.startsWith("-")) && !KNOWN_GLOBAL_FLAGS.has(flagPart)) {
-        process.stderr.write(`Warning: unknown flag "${flagPart}" (ignored)
-`);
+        throw new CLIError(`Unknown flag "${flagPart}"`);
       }
       continue;
     }
@@ -217,9 +175,11 @@ function parseArgs(defs, argv) {
     }
   }
   for (const def of allDefs) {
-    if (def.required && result2[def.name] === void 0) {
-      throw new CLIError(`Missing required argument: --${def.name}`);
-    }
+    if (!def.required) continue;
+    if (result2[def.name] !== void 0) continue;
+    const aliasNames = [def.alias, ...def.aliases ?? []].filter(Boolean);
+    if (aliasNames.some((a) => result2[a] !== void 0)) continue;
+    throw new CLIError(`Missing required argument: --${def.name}`);
   }
   return result2;
 }
@@ -2392,7 +2352,7 @@ function parsePhoneNumber4() {
   return withMetadataArgument(parsePhoneNumber3, arguments);
 }
 
-// ../sdk/dist/chunk-QZC4QPP2.js
+// ../sdk/dist/chunk-XRKRVY46.js
 function getCookieValue(name) {
   if (typeof document === "undefined") return void 0;
   const cookies = document.cookie.split(";");
@@ -2800,7 +2760,7 @@ ${formattedErrors}`, response.status);
    * Fetch from root path (not prefixed with /api/v2/)
    * Used for OAuth and other non-API endpoints
    */
-  async fetchRoot(path, options) {
+  async fetchRoot(path4, options) {
     try {
       const headers2 = new Headers({
         ...options?.body instanceof FormData ? {} : { "Content-Type": "application/json" },
@@ -2820,7 +2780,7 @@ ${formattedErrors}`, response.status);
       if (this.orgToken) {
         headers2.set("X-Org-Token", this.orgToken);
       }
-      const fullUrl = `${this.baseUrl}/${path}`;
+      const fullUrl = `${this.baseUrl}/${path4}`;
       const response = await this.fetchFunction(fullUrl, {
         ...options,
         ...this.apiKey ? {} : { credentials: "include" },
@@ -7034,22 +6994,22 @@ var OAuthConnectionsApi = class extends BaseApiClient {
    * Get the connection status for an OAuth provider
    */
   async getConnectionStatus(providerSlug) {
-    const path = getOAuthPath(providerSlug, "status");
-    return this.fetchRoot(path);
+    const path4 = getOAuthPath(providerSlug, "status");
+    return this.fetchRoot(path4);
   }
   /**
    * Get the authorization URL to start OAuth flow
    */
   async getAuthorizationUrl(providerSlug) {
-    const path = getOAuthPath(providerSlug, "authorize");
-    return this.fetchRoot(path);
+    const path4 = getOAuthPath(providerSlug, "authorize");
+    return this.fetchRoot(path4);
   }
   /**
    * Disconnect an OAuth provider
    */
   async disconnect(providerSlug) {
-    const path = getOAuthPath(providerSlug, "disconnect");
-    return this.fetchRoot(path, { method: "DELETE" });
+    const path4 = getOAuthPath(providerSlug, "disconnect");
+    return this.fetchRoot(path4, { method: "DELETE" });
   }
 };
 var OAuthApi = class extends BaseApiClient {
@@ -12990,11 +12950,87 @@ var ApiClient = class extends GravityRailClient {
   // ignore X-Org-Token entirely, so propagating an org token to adminApi is
   // dead code that would only obscure auth flow if admin route logic changes.
 };
-
-// src/cli-utils/config.ts
+var ENVIRONMENTS = {
+  dev: {
+    apiUrl: "https://api.gravityrail.test:5054",
+    frontendUrl: "https://app.gravityrail.test:3000"
+  },
+  prod: {
+    apiUrl: "https://api.gravityrail.com",
+    frontendUrl: "https://app.gravityrail.com"
+  },
+  staging: {
+    apiUrl: "https://api.gr-staging.com",
+    frontendUrl: "https://app.gr-staging.com"
+  }
+};
 var CALLBACK_PORT = 31337;
 var CALLBACK_PATH = "/oauth/callback";
 var REDIRECT_URI = `http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`;
+function detectWorktreePorts() {
+  let dir = resolve(process.cwd());
+  let overridePath;
+  while (true) {
+    const candidate = join(dir, "docker-compose.override.yml");
+    if (existsSync(candidate)) {
+      overridePath = candidate;
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (!overridePath) return {};
+  let content;
+  try {
+    content = readFileSync(overridePath, "utf-8");
+  } catch {
+    return {};
+  }
+  if (!content.includes("worktree-setup.sh")) return {};
+  let apiPort;
+  let frontendPort;
+  for (const match of content.matchAll(/-\s*'(\d+):(\d+)'/g)) {
+    const host = parseInt(match[1], 10);
+    const container = parseInt(match[2], 10);
+    if (container === 5050) apiPort = host;
+    if (container === 3e3) frontendPort = host;
+  }
+  return { apiPort, frontendPort };
+}
+function getEnvironmentConfig(env) {
+  if (env.startsWith("dev-cloud:")) {
+    const namespace = env.slice("dev-cloud:".length);
+    if (!namespace) {
+      throw new Error("dev-cloud environment requires a namespace: --env dev-cloud:NAMESPACE");
+    }
+    return {
+      apiUrl: `https://${namespace}-api.gravityrail-dev.com`,
+      frontendUrl: `https://${namespace}-app.gravityrail-dev.com`
+    };
+  }
+  const config = ENVIRONMENTS[env];
+  if (!config) {
+    throw new Error(
+      `Invalid environment: ${env}. Use 'dev', 'staging', 'prod', or 'dev-cloud:NAMESPACE'.`
+    );
+  }
+  const apiUrl = process.env.GRAVITY_RAIL_API_URL || config.apiUrl;
+  const frontendUrl = process.env.GRAVITY_RAIL_FRONTEND_URL || config.frontendUrl;
+  if (apiUrl !== config.apiUrl || frontendUrl !== config.frontendUrl) {
+    return { apiUrl, frontendUrl };
+  }
+  if (env === "dev") {
+    const ports = detectWorktreePorts();
+    if (ports.apiPort || ports.frontendPort) {
+      return {
+        apiUrl: ports.apiPort ? `https://api.gravityrail.test:${ports.apiPort}` : config.apiUrl,
+        frontendUrl: ports.frontendPort ? `https://app.gravityrail.test:${ports.frontendPort}` : config.frontendUrl
+      };
+    }
+  }
+  return config;
+}
 var CredentialsManager = class {
   cacheDir;
   apiUrl;
@@ -13124,7 +13160,7 @@ function openBrowser(url) {
   });
 }
 function startCallbackServer() {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let authCode = null;
     let error = null;
     let receivedState = null;
@@ -13166,7 +13202,7 @@ function startCallbackServer() {
           </html>
         `);
         server.close();
-        resolve({ code: authCode, state: receivedState });
+        resolve2({ code: authCode, state: receivedState });
       } else {
         res.writeHead(400);
         res.end("Missing code parameter");
@@ -13358,7 +13394,7 @@ async function selectFromList(items, options = {}) {
     return { item: null, isNew: false };
   }
   const displayItems = allowNew ? [NEW_ITEM_MARKER, ...items] : items;
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let selectedIndex = allowNew ? 1 : 0;
     let filterText = "";
     const getFilteredItems = () => {
@@ -13441,16 +13477,16 @@ async function selectFromList(items, options = {}) {
         if (filtered.length > 0 && selectedIndex < filtered.length) {
           const selected = filtered[selectedIndex];
           if (selected === NEW_ITEM_MARKER) {
-            resolve({ item: null, isNew: true });
+            resolve2({ item: null, isNew: true });
           } else {
-            resolve({ item: selected, isNew: false });
+            resolve2({ item: selected, isNew: false });
           }
         } else {
-          resolve({ item: null, isNew: false });
+          resolve2({ item: null, isNew: false });
         }
       } else if (key.name === "escape" || key.ctrl && key.name === "c") {
         cleanup();
-        resolve({ item: null, isNew: false });
+        resolve2({ item: null, isNew: false });
       } else if (key.name === "backspace") {
         filterText = filterText.slice(0, -1);
         selectedIndex = allowNew ? 0 : 0;
@@ -13560,29 +13596,82 @@ function clearScreen() {
 // src/cli-utils/agui.ts
 var AGUIClient = class {
   endpointUrl;
+  baseUrl;
+  workspaceUuid;
+  chatId;
   accessToken;
   debug;
   model;
+  appContext;
   constructor(options) {
+    this.baseUrl = options.baseUrl;
+    this.workspaceUuid = options.workspaceUuid ?? "";
+    this.chatId = options.chatId ?? 0;
+    if (!options.endpointUrl && (!options.workspaceUuid || options.chatId === void 0)) {
+      throw new Error("AGUIClient requires workspaceUuid and chatId, or endpointUrl");
+    }
     this.endpointUrl = options.endpointUrl ?? `${options.baseUrl}/api/v2/w/${options.workspaceUuid}/web-chat/${options.chatId}/chat/agui`;
     this.accessToken = options.accessToken;
     this.debug = options.debug ?? false;
     this.model = "model" in options ? options.model : "manager";
+    this.appContext = options.appContext;
+  }
+  inferenceStatusUrl() {
+    if (!this.workspaceUuid || this.chatId <= 0) return null;
+    return `${this.baseUrl}/api/v2/w/${this.workspaceUuid}/chats/${this.chatId}/inference/status`;
+  }
+  async waitForInferenceInactive(maxWaitMs = 6e4) {
+    const url = this.inferenceStatusUrl();
+    if (!url) return false;
+    const deadline = Date.now() + maxWaitMs;
+    while (Date.now() < deadline) {
+      try {
+        const res = await fetch(url, {
+          headers: { Authorization: `Bearer ${this.accessToken}` }
+        });
+        if (res.ok) {
+          const body = await res.json();
+          if (!body.active) return true;
+        }
+      } catch (err) {
+        if (this.debug) {
+          console.log(
+            `[DEBUG] waitForInferenceInactive fetch failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+      await new Promise((r) => setTimeout(r, 2e3));
+    }
+    return false;
   }
   /**
    * Send messages and stream the response
    */
   async sendMessage(messages, onEvent, options) {
+    return this.streamRequest({ messages }, onEvent, options);
+  }
+  /**
+   * Stream an AG-UI request (initial messages or HITL resume).
+   */
+  async streamRequest(request, onEvent, options) {
     const body = JSON.stringify({
       ...this.model ? { model: this.model } : {},
-      messages,
+      messages: request.messages ?? [],
+      ...this.appContext ? { appContext: this.appContext } : {},
+      ...request.resumeValue !== void 0 ? { resumeValue: request.resumeValue } : {},
+      ...request.resumeInterruptId ? { resumeInterruptId: request.resumeInterruptId } : {},
       ...options?.autoApprove ? { context: { autoApprove: true } } : {}
     });
     if (this.debug) {
       console.log(`
 [DEBUG] POST ${this.endpointUrl}`);
-      console.log(`[DEBUG] Body: ${messages.length} message(s)`);
+      console.log(
+        `[DEBUG] Body: ${request.resumeValue !== void 0 ? "resume" : `${(request.messages ?? []).length} message(s)`}`
+      );
     }
+    await this.postStream(body, onEvent, options);
+  }
+  async postStream(body, onEvent, options, conflictRetries = 0) {
     const response = await fetch(this.endpointUrl, {
       method: "POST",
       headers: {
@@ -13595,12 +13684,21 @@ var AGUIClient = class {
     if (this.debug) {
       console.log(`[DEBUG] Response status: ${response.status}`);
     }
+    if (response.status === 409 && conflictRetries < 3) {
+      const ready = await this.waitForInferenceInactive();
+      if (ready) {
+        await this.postStream(body, onEvent, options, conflictRetries + 1);
+        return;
+      }
+    }
     if (!response.ok) {
       const errorText = await response.text().catch(() => "");
       if (this.debug) {
         console.log(`[DEBUG] Error response: ${errorText}`);
       }
-      throw new Error(`Chat request failed: ${response.status}`);
+      throw new Error(
+        `Chat request failed: ${response.status}${errorText ? `: ${errorText.slice(0, 200)}` : ""}`
+      );
     }
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
@@ -13873,12 +13971,14 @@ function requireAuth(ctx) {
   return ctx;
 }
 function createPublicContext(opts) {
-  const apiUrl = opts.apiUrl || process.env.GRAVITY_RAIL_API_URL || "https://api.gravityrail.com";
-  const frontendUrl = opts.frontendUrl || process.env.GRAVITY_RAIL_FRONTEND_URL || "https://app.gravityrail.com";
-  const envConfig = { apiUrl, frontendUrl };
-  const credentialsManager = new CredentialsManager(homedir(), apiUrl);
+  const env = opts.env ?? "prod";
+  const envConfig = opts.apiUrl ? {
+    apiUrl: opts.apiUrl,
+    frontendUrl: opts.frontendUrl || process.env.GRAVITY_RAIL_FRONTEND_URL || "https://app.gravityrail.com"
+  } : getEnvironmentConfig(env);
+  const credentialsManager = new CredentialsManager(homedir(), envConfig.apiUrl);
   return {
-    env: "prod",
+    env,
     envConfig,
     outputFormat: detectOutputFormat(opts.outputFormat),
     verbose: opts.verbose ?? false,
@@ -13927,32 +14027,48 @@ async function readJsonInput(args) {
       throw new CLIError(`Cannot read file: ${filePath}`);
     }
   }
-  if (!process.stdin.isTTY) {
-    return readStdin();
+  if (process.stdin.isTTY === true) {
+    return void 0;
   }
-  return void 0;
+  return readStdinIfPiped();
 }
-function readStdin() {
-  return new Promise((resolve, reject) => {
+function readStdinIfPiped() {
+  return new Promise((resolve2, reject) => {
     let data = "";
-    process.stdin.setEncoding("utf-8");
-    process.stdin.on("data", (chunk) => {
-      data += chunk;
-    });
-    process.stdin.on("end", () => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve2(value);
+    };
+    const flush = () => {
       if (!data.trim()) {
-        resolve(void 0);
+        finish(void 0);
         return;
       }
       try {
-        resolve(JSON.parse(data));
+        finish(JSON.parse(data));
       } catch {
         reject(new CLIError("Invalid JSON from stdin"));
       }
+    };
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
     });
+    process.stdin.on("end", flush);
     process.stdin.on("error", (err) => {
       reject(new CLIError(`Error reading stdin: ${err.message}`));
     });
+    process.stdin.resume();
+    setImmediate(() => {
+      if (data) return;
+      if (process.stdin.readableEnded) {
+        flush();
+        return;
+      }
+      finish(void 0);
+    });
   });
 }
 
@@ -14358,6 +14474,17 @@ function requireNumber(args, key) {
   if (isNaN(num)) throw new Error(`Argument --${key} must be a number`);
   return num;
 }
+function requireNumberFrom(args, ...keys) {
+  for (const key of keys) {
+    const val = args[key];
+    if (typeof val === "string") {
+      const num = Number(val);
+      if (!isNaN(num)) return num;
+    }
+  }
+  const hint = keys.map((k) => `--${k}`).join(" or ");
+  throw new Error(`Missing required argument: ${hint}`);
+}
 
 // src/domains/agent-tasks.ts
 var LIST_COLUMNS = [
@@ -14518,6 +14645,7 @@ var agentsDomain = {
 var COLUMNS2 = [
   COL.id(),
   COL.uuid(),
+  { header: "TYPE", getValue: (item) => item.chatType ?? item.chat_type ?? "" },
   { header: "MEMBER", getValue: (item) => item.member_name ?? String(item.member_id ?? "") },
   COL.status(),
   { header: "CHANNEL", getValue: (item) => item.channel ?? "" },
@@ -14569,7 +14697,11 @@ var chatsDomain = {
           isFlag: true
         },
         { name: "is-test", description: "Show only test chats", isFlag: true },
-        { name: "member-id", description: "Filter by member ID" }
+        { name: "member-id", description: "Filter by member ID" },
+        {
+          name: "chat-type",
+          description: "Filter by chat type (assignment, manager, developer, member, contributor). Default: assignment"
+        }
       ]
     }),
     // Messages
@@ -14578,7 +14710,7 @@ var chatsDomain = {
       description: "List messages for a chat. Use --limit/--offset to page; the API caps a single request at 100. Tool-call shell rows that the API filter excludes (parent_message_id IS NOT NULL or parent_call_id IS NOT NULL) are still hidden \u2014 use `gr chats inspect --id <chat>` for the full debug view.",
       requiresWorkspace: true,
       args: [
-        { name: "chat-id", description: "Chat ID", required: true },
+        { name: "chat-id", aliases: ["id"], description: "Chat ID", required: true },
         {
           name: "limit",
           description: "Max messages to return (1-100, default 100)"
@@ -14601,7 +14733,7 @@ var chatsDomain = {
         }
         const result2 = await requireAuth(ctx).apiClient.getChatMessages(
           workspace,
-          requireNumber(args, "chat-id"),
+          requireNumberFrom(args, "chat-id", "id"),
           limit,
           offset
         );
@@ -14614,7 +14746,7 @@ var chatsDomain = {
       mutates: true,
       requiresWorkspace: true,
       args: [
-        { name: "chat-id", description: "Chat ID", required: true },
+        { name: "chat-id", aliases: ["id"], description: "Chat ID", required: true },
         { name: "stream", description: "Stream the AI response via AG-UI", isFlag: true }
       ],
       handler: async ({ ctx, workspace, args, data }) => {
@@ -14623,7 +14755,7 @@ var chatsDomain = {
           throw new Error(
             `Message content is required (pass --data '"your message"' or --data '{"content":"your message"}')`
           );
-        const chatId = requireNumber(args, "chat-id");
+        const chatId = requireNumberFrom(args, "chat-id", "id");
         if (args.stream) {
           const aguiClient = new AGUIClient({
             baseUrl: ctx.envConfig.apiUrl,
@@ -14656,11 +14788,11 @@ var chatsDomain = {
       description: "Send an assistant message to a chat (does not trigger AI inference)",
       mutates: true,
       requiresWorkspace: true,
-      args: [{ name: "chat-id", description: "Chat ID", required: true }],
+      args: [{ name: "chat-id", aliases: ["id"], description: "Chat ID", required: true }],
       handler: async ({ ctx, workspace, args, data }) => {
         const result2 = await requireAuth(ctx).apiClient.sendAssistantMessage(
           workspace,
-          requireNumber(args, "chat-id"),
+          requireNumberFrom(args, "chat-id", "id"),
           data
         );
         outputSingle(result2, ctx, MESSAGE_COLUMNS2);
@@ -16723,10 +16855,20 @@ var eventRulesCrudNoList = crudCommands({
     '  "eventType":"journey_step:execute","actionType":"member:label",',
     `  "actionParams":{"addLabelIds":["<label-uuid>"]},"journeyStepId":<step-id>}'`,
     "",
+    "Scheduled outbound (routine \u2192 chat \u2192 voice/SMS):",
+    `gr events rules create -w $WID --allow-write --data '{"name":"AM voice check-in",`,
+    '  "objectType":"routine","eventType":"routine:triggered","actionType":"chat:create",',
+    '  "routineId":<routine-id>,',
+    '  "actionParams":{"workflowId":<workflow-id>,"channel":"phone-voice",',
+    `  "phoneNumberId":<workspace-phone-id>}}'`,
+    "",
+    '  PM SMS variant: use "channel":"phone-sms" and a second rule on the same routineId.',
+    "  Prereq: org phone assigned + gr phone-numbers link; workflow published with start task.",
+    "",
     "Required: objectType, eventType, actionType",
-    "Optional: name, actionParams, conditions (CEL), journeyStepId, delay (sec), order",
+    "Optional: name, actionParams, conditions (CEL), journeyStepId, routineId, delay (sec), order",
     "",
-    "Common eventTypes: journey_step:execute, journey:enrolled, journey:completed,",
+    "Common eventTypes: journey_step:execute, journey:enrolled, routine:triggered,",
     "  task:created, chat:created, data_record:created, member:created",
     "",
     "Common actionTypes: member:label, member:notify, webhook:send, email:send,",
@@ -19009,7 +19151,7 @@ var conciergeDomain = {
       path: ["concierge", "messages"],
       description: "Show messages for a concierge chat",
       requiresWorkspace: false,
-      args: [{ name: "id", description: "Chat ID", required: true }],
+      args: [{ name: "id", aliases: ["chat-id"], description: "Chat ID", required: true }],
       handler: async ({ ctx, args }) => {
         const auth = requireAuth(ctx);
         const chatId = Number(args.id);
@@ -19642,15 +19784,15 @@ var DOMAIN_UUID_ARG = {
 function pluralize(count, singular, plural = `${singular}s`) {
   return count === 1 ? singular : plural;
 }
-function emailVerifyCommand(path, description) {
+function emailVerifyCommand(path4, description) {
   return {
-    path,
+    path: path4,
     description,
     mutates: true,
     requiresWorkspace: false,
     args: [ORG_UUID_ARG, DOMAIN_UUID_ARG],
     examples: [
-      `yarn gr ${path.join(" ")} --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write`
+      `yarn gr ${path4.join(" ")} --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write`
     ],
     handler: async (hctx) => {
       const result2 = await requireAuth(hctx.ctx).apiClient.verifyOrgDomainEmail(
@@ -19661,15 +19803,15 @@ function emailVerifyCommand(path, description) {
     }
   };
 }
-function siteVerifyCommand(path, description) {
+function siteVerifyCommand(path4, description) {
   return {
-    path,
+    path: path4,
     description,
     mutates: true,
     requiresWorkspace: false,
     args: [ORG_UUID_ARG, DOMAIN_UUID_ARG],
     examples: [
-      `yarn gr ${path.join(" ")} --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write`
+      `yarn gr ${path4.join(" ")} --org-uuid $ORG_UUID --domain-uuid $DOMAIN_UUID --allow-write`
     ],
     handler: async (hctx) => {
       const result2 = await requireAuth(hctx.ctx).apiClient.verifyOrgDomainSite(
@@ -19680,9 +19822,9 @@ function siteVerifyCommand(path, description) {
     }
   };
 }
-function registerDomainCommand(path) {
+function registerDomainCommand(path4) {
   return {
-    path,
+    path: path4,
     description: "Register an organization domain and return ownership TXT instructions",
     mutates: true,
     requiresWorkspace: false,
@@ -19691,7 +19833,7 @@ function registerDomainCommand(path) {
       { name: "domain", description: "Domain to register, e.g. example.com", required: true }
     ],
     examples: [
-      `yarn gr ${path.join(" ")} --org-uuid $ORG_UUID --domain example.com --allow-write`
+      `yarn gr ${path4.join(" ")} --org-uuid $ORG_UUID --domain example.com --allow-write`
     ],
     handler: async (hctx) => {
       const result2 = await requireAuth(hctx.ctx).apiClient.registerOrgDomain(
@@ -20045,6 +20187,12 @@ var commands2 = [
         workspaceUuid
       );
       outputSingle(result2, hctx.ctx, PROVIDER_PHONE_COLUMNS);
+      process.stdout.write(
+        `
+If workspace phone list is still empty, create a workspace phone record then:
+  gr phone-numbers link -w ${workspaceUuid} --id <workspace-phone-id> --provider-phone-uuid ${providerPhoneUuid} --allow-write
+`
+      );
     }
   },
   {
@@ -20148,6 +20296,31 @@ var phoneNumbersDomain = {
         outputData(result2, ctx, COLUMNS25);
       }
     },
+    {
+      path: ["phone-numbers", "link"],
+      description: "Link a workspace phone number to a provider (org) phone",
+      mutates: true,
+      requiresWorkspace: true,
+      args: [
+        {
+          name: "phone-number-id",
+          aliases: ["id"],
+          description: "Workspace phone number ID",
+          required: true
+        },
+        { name: "provider-phone-uuid", description: "Provider phone UUID", required: true }
+      ],
+      examples: [
+        "gr phone-numbers link -w $WID --id 1 --provider-phone-uuid <uuid> --allow-write"
+      ],
+      handler: async ({ ctx, workspace, args }) => {
+        const auth = requireAuth(ctx);
+        const id = requireNumberFrom(args, "phone-number-id", "id");
+        const providerPhoneUuid = requireString(args, "provider-phone-uuid");
+        const result2 = await auth.apiClient.linkPhoneNumber(workspace, id, providerPhoneUuid);
+        outputData([result2], auth, COLUMNS25);
+      }
+    },
     {
       path: ["phone-numbers", "request"],
       description: "Request a phone number",
@@ -20166,7 +20339,12 @@ var phoneNumbersDomain = {
       description: "List calls for a phone number",
       requiresWorkspace: true,
       args: [
-        { name: "phone-number-id", description: "Phone number ID", required: true },
+        {
+          name: "phone-number-id",
+          aliases: ["id"],
+          description: "Phone number ID",
+          required: true
+        },
         { name: "page", description: "Page number" },
         { name: "page-size", description: "Page size" },
         { name: "status", description: "Filter by status" }
@@ -20175,7 +20353,7 @@ var phoneNumbersDomain = {
         const status = args.status;
         const result2 = await requireAuth(ctx).apiClient.getPhoneNumberCalls(
           workspace,
-          requireNumber(args, "phone-number-id"),
+          requireNumberFrom(args, "phone-number-id", "id"),
           args.page ? Number(args.page) : void 0,
           args["page-size"] ? Number(args["page-size"]) : void 0,
           status ? { status } : void 0
@@ -20188,14 +20366,19 @@ var phoneNumbersDomain = {
       description: "List messages for a phone number",
       requiresWorkspace: true,
       args: [
-        { name: "phone-number-id", description: "Phone number ID", required: true },
+        {
+          name: "phone-number-id",
+          aliases: ["id"],
+          description: "Phone number ID",
+          required: true
+        },
         { name: "page", description: "Page number" },
         { name: "page-size", description: "Page size" }
       ],
       handler: async ({ ctx, workspace, args }) => {
         const result2 = await requireAuth(ctx).apiClient.getPhoneNumberMessages(
           workspace,
-          requireNumber(args, "phone-number-id"),
+          requireNumberFrom(args, "phone-number-id", "id"),
           args.page ? Number(args.page) : void 0,
           args["page-size"] ? Number(args["page-size"]) : void 0
         );
@@ -20205,36 +20388,85 @@ var phoneNumbersDomain = {
   ]
 };
 
+// src/lib/resolve-org.ts
+async function resolveOrgUuidFromWorkspace(apiClient, workspaceUuid) {
+  const workspace = await apiClient.getWorkspace(workspaceUuid);
+  const orgUuid = workspace.organizationUuid;
+  if (!orgUuid) {
+    throw new CLIError(
+      "Workspace has no organization; pass --org-uuid for organization-scoped commands"
+    );
+  }
+  return orgUuid;
+}
+function normalizePronunciationCreatePayload(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new CLIError("JSON body required with term and respelling (--data or --file)");
+  }
+  const raw = data;
+  const term = raw.term ?? raw.word;
+  const respelling = raw.respelling ?? raw.pronunciation;
+  if (typeof term !== "string" || !term) {
+    throw new CLIError("Payload requires term (alias: word)");
+  }
+  if (typeof respelling !== "string" || !respelling) {
+    throw new CLIError("Payload requires respelling (alias: pronunciation)");
+  }
+  const payload = { term, respelling };
+  if (raw.accountId !== void 0 && raw.accountId !== null) {
+    payload.accountId = Number(raw.accountId);
+  }
+  return payload;
+}
+function normalizePronunciationUpdatePayload(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    throw new CLIError("JSON body required (--data or --file)");
+  }
+  const raw = data;
+  const respelling = raw.respelling ?? raw.pronunciation;
+  if (typeof respelling !== "string" || !respelling) {
+    throw new CLIError("Payload requires respelling (alias: pronunciation)");
+  }
+  return { respelling };
+}
+
 // src/domains/pronunciations.ts
 var COLUMNS26 = [
   COL.id(),
-  { header: "WORD", getValue: (item) => item.word ?? "" },
-  { header: "PRONUNCIATION", getValue: (item) => item.pronunciation ?? "" },
-  { header: "TYPE", getValue: (item) => item.type ?? "" }
+  { header: "TERM", getValue: (item) => item.term ?? "" },
+  { header: "RESPELLING", getValue: (item) => item.respelling ?? "" },
+  { header: "SCOPE", getValue: (item) => item.scope ?? "" }
+];
+var CREATE_EXAMPLES = [
+  `gr pronunciations create -w $WID --data '{"term":"Jeeves","respelling":"JEEVZ"}' --allow-write`,
+  "  (aliases: word \u2192 term, pronunciation \u2192 respelling)"
 ];
 var pronunciationsDomain = {
   name: "pronunciations",
-  description: "Manage pronunciation entries",
+  description: "Manage pronunciation entries (org-scoped; -w resolves organization)",
   commands: [
     {
       path: ["pronunciations", "list"],
-      description: "List pronunciation entries",
+      description: "List pronunciation entries for the workspace organization",
       requiresWorkspace: true,
       handler: async ({ ctx, workspace }) => {
-        const result2 = await requireAuth(ctx).apiClient.getPronunciationEntries(workspace);
+        const auth = requireAuth(ctx);
+        const orgUuid = await resolveOrgUuidFromWorkspace(auth.apiClient, workspace);
+        const result2 = await auth.apiClient.getPronunciationEntries(orgUuid);
         outputData(result2, ctx, COLUMNS26);
       }
     },
     {
       path: ["pronunciations", "create"],
-      description: "Create a pronunciation entry",
+      description: "Create a pronunciation entry (term + respelling)",
       mutates: true,
       requiresWorkspace: true,
+      examples: CREATE_EXAMPLES,
       handler: async ({ ctx, workspace, data }) => {
-        const result2 = await requireAuth(ctx).apiClient.createPronunciationEntry(
-          workspace,
-          data
-        );
+        const auth = requireAuth(ctx);
+        const orgUuid = await resolveOrgUuidFromWorkspace(auth.apiClient, workspace);
+        const payload = normalizePronunciationCreatePayload(data);
+        const result2 = await auth.apiClient.createPronunciationEntry(orgUuid, payload);
         outputSingle(result2, ctx, COLUMNS26);
       }
     },
@@ -20245,10 +20477,13 @@ var pronunciationsDomain = {
       requiresWorkspace: true,
       args: [{ name: "id", description: "Pronunciation entry ID", required: true }],
       handler: async ({ ctx, workspace, args, data }) => {
-        const result2 = await requireAuth(ctx).apiClient.updatePronunciationEntry(
-          workspace,
+        const auth = requireAuth(ctx);
+        const orgUuid = await resolveOrgUuidFromWorkspace(auth.apiClient, workspace);
+        const payload = normalizePronunciationUpdatePayload(data);
+        const result2 = await auth.apiClient.updatePronunciationEntry(
+          orgUuid,
           requireNumber(args, "id"),
-          data
+          payload
         );
         outputSingle(result2, ctx, COLUMNS26);
       }
@@ -20260,8 +20495,10 @@ var pronunciationsDomain = {
       requiresWorkspace: true,
       args: [{ name: "id", description: "Pronunciation entry ID", required: true }],
       handler: async ({ ctx, workspace, args }) => {
+        const auth = requireAuth(ctx);
+        const orgUuid = await resolveOrgUuidFromWorkspace(auth.apiClient, workspace);
         const id = requireNumber(args, "id");
-        await requireAuth(ctx).apiClient.deletePronunciationEntry(workspace, id);
+        await auth.apiClient.deletePronunciationEntry(orgUuid, id);
         process.stdout.write(`Deleted pronunciation entry ${id}
 `);
       }
@@ -20281,7 +20518,8 @@ var pronunciationsDomain = {
       mutates: true,
       requiresWorkspace: true,
       handler: async ({ ctx, data }) => {
-        const result2 = await requireAuth(ctx).apiClient.createMyPronunciation(data);
+        const payload = normalizePronunciationCreatePayload(data);
+        const result2 = await requireAuth(ctx).apiClient.createMyPronunciation(payload);
         outputSingle(result2, ctx, COLUMNS26);
       }
     },
@@ -20289,11 +20527,17 @@ var pronunciationsDomain = {
       path: ["pronunciations", "suggest"],
       description: "Get pronunciation suggestions for a word",
       requiresWorkspace: true,
-      args: [{ name: "word", description: "Word to get suggestions for", required: true }],
+      args: [
+        {
+          name: "word",
+          aliases: ["term"],
+          description: "Word to get suggestions for",
+          required: true
+        }
+      ],
       handler: async ({ ctx, args }) => {
-        const result2 = await requireAuth(ctx).apiClient.suggestPronunciations(
-          requireString(args, "word")
-        );
+        const word = typeof args.word === "string" ? args.word : typeof args.term === "string" ? args.term : requireString(args, "word");
+        const result2 = await requireAuth(ctx).apiClient.suggestPronunciations(word);
         outputData(result2, ctx);
       }
     },
@@ -22250,6 +22494,327 @@ function openUrl(url) {
     }
   });
 }
+function buildCliConciergeAppContext() {
+  const shell = process.env.SHELL ? path3.basename(process.env.SHELL) : void 0;
+  return {
+    clientSurface: "cli",
+    channel: "text",
+    cliContext: {
+      shell,
+      os: process.platform,
+      cwdBasename: path3.basename(process.cwd())
+    }
+  };
+}
+var DEFAULT_MAX_READ_BYTES = 5e4;
+var ABSOLUTE_MAX_READ_BYTES = 1e6;
+function resolveSafePath(root, relativePath) {
+  const rootResolved = path3.resolve(root);
+  const target = path3.resolve(rootResolved, relativePath || ".");
+  if (target !== rootResolved && !target.startsWith(rootResolved + path3.sep)) {
+    return null;
+  }
+  let cursor = rootResolved;
+  const rest = path3.relative(rootResolved, target);
+  if (rest && rest !== ".") {
+    for (const segment of rest.split(path3.sep)) {
+      cursor = path3.join(cursor, segment);
+      try {
+        const lstat = fs.lstatSync(cursor);
+        if (lstat.isSymbolicLink()) {
+          return null;
+        }
+      } catch {
+        break;
+      }
+    }
+  }
+  return target;
+}
+function executeCliLocalFileAction(root, interrupt, opts) {
+  const safe = resolveSafePath(root, interrupt.path);
+  if (!safe) {
+    return { ok: false, error: "Path escapes trusted directory" };
+  }
+  try {
+    switch (interrupt.action) {
+      case "read_file": {
+        if (!fs.existsSync(safe)) {
+          return { ok: false, error: "File not found" };
+        }
+        const stat = fs.lstatSync(safe);
+        if (stat.isSymbolicLink()) {
+          return { ok: false, error: "Path escapes trusted directory" };
+        }
+        if (!stat.isFile()) {
+          return { ok: false, error: "Not a file" };
+        }
+        const requested = Number.isFinite(interrupt.max_bytes) ? Math.max(1, Math.min(Number(interrupt.max_bytes), ABSOLUTE_MAX_READ_BYTES)) : DEFAULT_MAX_READ_BYTES;
+        if (stat.size > requested) {
+          const buf = fs.readFileSync(safe, { encoding: "utf8" });
+          return {
+            ok: true,
+            content: buf.slice(0, requested) + `
+
+[truncated at ${requested} bytes]`
+          };
+        }
+        return { ok: true, content: fs.readFileSync(safe, "utf8") };
+      }
+      case "list_dir": {
+        if (!fs.existsSync(safe)) {
+          return { ok: false, error: "Directory not found" };
+        }
+        const entries = fs.readdirSync(safe, { withFileTypes: true });
+        const lines = entries.slice(0, 200).map((e) => e.isDirectory() ? `${e.name}/` : e.name);
+        if (entries.length > 200) {
+          lines.push(`... and ${entries.length - 200} more`);
+        }
+        return { ok: true, content: lines.join("\n") };
+      }
+      case "write_file": {
+        if (!opts.allowWrite) {
+          return { ok: false, error: "Write requires --allow-write" };
+        }
+        if (interrupt.content === void 0) {
+          return { ok: false, error: "Missing content for write_file" };
+        }
+        fs.mkdirSync(path3.dirname(safe), { recursive: true });
+        fs.writeFileSync(safe, interrupt.content, "utf8");
+        return { ok: true, content: "written" };
+      }
+      default:
+        return { ok: false, error: `Unknown action: ${interrupt.action}` };
+    }
+  } catch (e) {
+    return { ok: false, error: sanitizeLocalFileError(e) };
+  }
+}
+function sanitizeLocalFileError(e) {
+  if (e && typeof e === "object" && "code" in e) {
+    const code = e.code;
+    if (code === "ENOENT") return "File or directory not found";
+    if (code === "EACCES" || code === "EPERM") return "Permission denied";
+    if (code === "EISDIR") return "Not a file";
+    if (code === "ENOTDIR") return "Not a directory";
+  }
+  return "Local file operation failed";
+}
+function isCliLocalFileInterrupt(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.type === "cli_local_file" && typeof v.action === "string" && typeof v.path === "string";
+}
+var STORE_VERSION = 1;
+function storePath() {
+  const base = process.env.XDG_CONFIG_HOME ?? (process.platform === "win32" ? path3.join(process.env.APPDATA ?? os.homedir(), "gravityrail") : path3.join(os.homedir(), ".config", "gravityrail"));
+  return path3.join(base, "trusted-dirs.json");
+}
+function loadTrustedDirsStore() {
+  const file = storePath();
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (raw?.version === STORE_VERSION && Array.isArray(raw.always)) {
+      return { version: STORE_VERSION, always: raw.always.map((p) => path3.resolve(p)) };
+    }
+  } catch {
+  }
+  return { version: STORE_VERSION, always: [] };
+}
+function saveTrustedDirsStore(store) {
+  const file = storePath();
+  const dir = path3.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  fs.writeFileSync(file, JSON.stringify(store, null, 2) + "\n", { mode: 384 });
+}
+function isDirectoryTrusted(dirPath, opts) {
+  if (opts?.trustCwdFlag) return true;
+  const resolved = path3.resolve(dirPath);
+  const store = loadTrustedDirsStore();
+  return store.always.includes(resolved);
+}
+async function promptTrustInteractive(dirPath) {
+  const rl = readline__default.createInterface({ input: process.stdin, output: process.stderr });
+  const question = (q) => new Promise((resolve2) => rl.question(q, resolve2));
+  process.stderr.write(
+    `
+Gravity Rail may read files in:
+  ${dirPath}
+
+File contents can influence the assistant. Do you trust the files in this directory?
+  [1] Trust once (this session)
+  [2] Trust always (remember for this path)
+  [3] No \u2014 do not read local files
+
+Choice [1/2/3] (default 3): `
+  );
+  const answer = (await question("")).trim() || "3";
+  rl.close();
+  if (answer === "1") return "once";
+  if (answer === "2") return "always";
+  return "denied";
+}
+var sessionTrusted = /* @__PURE__ */ new Set();
+async function resolveDirectoryTrust(opts) {
+  const dir = path3.resolve(opts.trustDir ?? opts.cwd ?? process.cwd());
+  if (isDirectoryTrusted(dir, { trustCwdFlag: opts.trustCwd })) return "trusted";
+  if (sessionTrusted.has(dir)) return "trusted";
+  if (opts.trustDir && path3.resolve(opts.trustDir) === dir) {
+    sessionTrusted.add(dir);
+    return "trusted";
+  }
+  if (opts.trustCwd) {
+    sessionTrusted.add(dir);
+    return "trusted";
+  }
+  if (!process.stdin.isTTY || opts.nonInteractive) {
+    return "denied";
+  }
+  const decision = await promptTrustInteractive(dir);
+  if (decision === "denied") {
+    return "denied";
+  }
+  if (decision === "always") {
+    const store = loadTrustedDirsStore();
+    if (!store.always.includes(dir)) {
+      store.always.push(dir);
+      saveTrustedDirsStore(store);
+    }
+  }
+  sessionTrusted.add(dir);
+  return "trusted";
+}
+
+// src/lib/cli-hitl.ts
+function extractHumanInputRequest(event) {
+  const type = String(event.type ?? "").toUpperCase();
+  if (type === "CUSTOM" && event.name === "human_input_request") {
+    return event.value;
+  }
+  if (event.name === "human_input_request") {
+    return event.value;
+  }
+  return null;
+}
+async function handleCliHitlInterrupt(value, opts) {
+  if (!value || typeof value !== "object") return null;
+  const payload = value;
+  if (isCliLocalFileInterrupt(payload)) {
+    const interrupt = payload;
+    if (typeof payload.interrupt_id === "string") {
+      interrupt.interrupt_id = payload.interrupt_id;
+    }
+    return handleCliLocalFile(interrupt, opts);
+  }
+  if (payload.type === "present_choice") {
+    return handlePresentChoiceTerminal(payload);
+  }
+  return null;
+}
+async function handleCliLocalFile(interrupt, opts) {
+  const trust = await resolveDirectoryTrust({
+    cwd: process.cwd(),
+    trustCwd: opts.trustCwd,
+    trustDir: opts.trustDir,
+    // Interactive sessions: prompt on first local-file use (review feedback).
+    nonInteractive: opts.nonInteractive ?? process.stdin.isTTY !== true
+  });
+  if (trust !== "trusted") {
+    return {
+      resumeValue: JSON.stringify({
+        ok: false,
+        error: "Directory not trusted for local file access. Re-run with --trust-cwd or --trust-dir <path>, or approve trust interactively when prompted."
+      }),
+      resumeInterruptId: interrupt.interrupt_id
+    };
+  }
+  process.stderr.write(`
+[local ${interrupt.action}] ${interrupt.path}
+`);
+  const result2 = executeCliLocalFileAction(process.cwd(), interrupt, {
+    allowWrite: opts.allowWrite
+  });
+  return {
+    resumeValue: JSON.stringify(result2),
+    resumeInterruptId: interrupt.interrupt_id
+  };
+}
+async function handlePresentChoiceTerminal(payload) {
+  const prompt = typeof payload.user_prompt === "string" && payload.user_prompt || typeof payload.description === "string" && payload.description || "Choose an option";
+  const markup = typeof payload.openui_markup === "string" ? payload.openui_markup : "";
+  process.stderr.write(`
+${prompt}
+`);
+  if (markup) {
+    process.stderr.write(`${markup.slice(0, 2e3)}
+`);
+  }
+  if (!process.stdin.isTTY) {
+    return {
+      resumeValue: "",
+      resumeInterruptId: typeof payload.interrupt_id === "string" ? payload.interrupt_id : void 0
+    };
+  }
+  const rl = readline__default.createInterface({ input: process.stdin, output: process.stderr });
+  const answer = await new Promise((resolve2) => {
+    rl.question("Your choice (value): ", resolve2);
+  });
+  rl.close();
+  return {
+    resumeValue: answer.trim(),
+    resumeInterruptId: typeof payload.interrupt_id === "string" ? payload.interrupt_id : void 0
+  };
+}
+
+// src/lib/concierge-agui-loop.ts
+var MAX_HITL_ROUNDS = 25;
+async function runConciergeAguiLoop(client, initialMessages, onEvent, opts) {
+  let streamText = "";
+  let hasToolCalls = false;
+  let resume;
+  for (let round = 0; round < MAX_HITL_ROUNDS; round++) {
+    let hitlPayload = null;
+    await client.streamRequest(
+      resume ? {
+        messages: [],
+        resumeValue: resume.resumeValue,
+        resumeInterruptId: resume.resumeInterruptId
+      } : { messages: initialMessages },
+      (event) => {
+        onEvent(event);
+        const delta = getTextDelta(event);
+        if (delta) streamText += delta;
+        const type = event.type?.toLowerCase() ?? "";
+        if (type === "tool_call_start") hasToolCalls = true;
+        const errorMsg = getErrorMessage(event);
+        if (errorMsg) process.stderr.write(`\x1B[31mError: ${errorMsg}\x1B[0m
+`);
+        const hitl = extractHumanInputRequest(event);
+        if (hitl) hitlPayload = hitl;
+      },
+      { autoApprove: opts.autoApprove }
+    );
+    if (!hitlPayload) {
+      break;
+    }
+    const next = await handleCliHitlInterrupt(hitlPayload, {
+      allowWrite: opts.allowWrite,
+      autoApprove: opts.autoApprove,
+      trustCwd: opts.trustCwd,
+      trustDir: opts.trustDir,
+      nonInteractive: opts.nonInteractive
+    });
+    if (!next) {
+      process.stderr.write(
+        "  [HITL] Unsupported interrupt in CLI \u2014 open app.gravityrail.com/setup to continue.\n"
+      );
+      break;
+    }
+    resume = next;
+    streamText = "";
+  }
+  return { streamText, hasToolCalls };
+}
 var RealtimeClient = class extends EventEmitter {
   ws = null;
   connected = false;
@@ -22269,7 +22834,7 @@ var RealtimeClient = class extends EventEmitter {
         new Error("WebSocket not available. Node.js 22+ is required for realtime mode.")
       );
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const params = new URLSearchParams();
       if (this.options.vadMode) {
         params.append("vad", this.options.vadMode);
@@ -22324,7 +22889,7 @@ var RealtimeClient = class extends EventEmitter {
       }, 1e4);
       this.once("connected", () => {
         clearTimeout(timeout);
-        resolve();
+        resolve2();
       });
       this.once("error", () => {
         clearTimeout(timeout);
@@ -23289,7 +23854,7 @@ async function listOutputDevices() {
   return listDevices("play");
 }
 function listDevices(command) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     try {
       const proc = spawnSync(command, ["--list-devices"], {
         encoding: "utf-8",
@@ -23313,9 +23878,9 @@ function listDevices(command) {
       if (devices.length === 0) {
         devices.push({ id: "default", name: "System Default", isDefault: true });
       }
-      resolve(devices);
+      resolve2(devices);
     } catch {
-      resolve([{ id: "default", name: "System Default", isDefault: true }]);
+      resolve2([{ id: "default", name: "System Default", isDefault: true }]);
     }
   });
 }
@@ -23337,14 +23902,14 @@ async function selectDevice(devices, label) {
     process.stderr.write(`    ${i + 1}. ${dev.name}${marker}
 `);
   }
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const defaultIdx = devices.findIndex((d) => d.isDefault);
     const defaultNum = defaultIdx >= 0 ? defaultIdx + 1 : 1;
     rl.question(`  Select [${defaultNum}]: `, (answer) => {
       rl.close();
       const num = answer.trim() ? parseInt(answer.trim(), 10) : defaultNum;
       const idx = Math.max(0, Math.min(devices.length - 1, num - 1));
-      resolve(devices[idx]);
+      resolve2(devices[idx]);
     });
   });
 }
@@ -23602,56 +24167,51 @@ async function runChatSession(session, args) {
       "Interactive mode requires a TTY. Use --message for non-interactive mode."
     );
   }
+  const allowWrite = !!args["allow-write"] || !!session.allowWrite;
   if (message) {
-    await singleTurnChatSession(session, message, debug, autoApprove);
+    await singleTurnChatSession(session, message, debug, autoApprove, allowWrite);
   } else if (isVoice) {
     await voiceChatSession(session, vadMode(args), args, debug);
   } else if (isRealtime) {
     await realtimeChatSession(session, vadMode(args), debug);
   } else {
-    await interactiveChatSession(session, debug);
+    await interactiveChatSession(session, debug, autoApprove, allowWrite);
   }
 }
 function vadMode(args) {
   return typeof args.vad === "string" ? args.vad : "server";
 }
-async function singleTurnChatSession(session, message, debug, autoApprove = false) {
+async function singleTurnChatSession(session, message, debug, autoApprove = false, allowWrite = false) {
   const aguiClient = new AGUIClient({
     baseUrl: session.ctx.envConfig.apiUrl,
+    workspaceUuid: session.workspaceUuid,
+    chatId: session.chatId,
     endpointUrl: session.aguiEndpointUrl,
     accessToken: session.ctx.accessToken,
     debug,
-    model: session.model
+    model: session.model,
+    appContext: session.appContext
   });
-  let streamText = "";
-  let hasToolCalls = false;
-  let eventCount = 0;
-  const logFile = process.env.GR_SSE_LOG;
-  const fs = logFile ? await import('fs') : null;
-  const logStream = logFile && fs ? fs.createWriteStream(logFile, { flags: "a" }) : null;
-  await aguiClient.sendMessage(
-    [{ role: "user", content: message }],
-    (event) => {
-      eventCount++;
-      if (logStream) logStream.write(JSON.stringify(event) + "\n");
-      const delta = getTextDelta(event);
-      if (delta) streamText += delta;
-      const type = event.type?.toLowerCase() ?? "";
-      if (type === "tool_call_start") {
-        hasToolCalls = true;
-        const name = event.name ?? "";
-        process.stderr.write(`  [${name}]
-`);
-      }
-      const errorMsg = getErrorMessage(event);
-      if (errorMsg) process.stderr.write(`\x1B[31mError: ${errorMsg}\x1B[0m
+  const onEvent = (event) => {
+    const type = event.type?.toLowerCase() ?? "";
+    if (type === "tool_call_start") {
+      const name = event.toolCallName ?? event.name ?? "";
+      process.stderr.write(`  [${name}]
 `);
-    },
-    { autoApprove }
+    }
+  };
+  const { streamText, hasToolCalls } = await runConciergeAguiLoop(
+    aguiClient,
+    [{ role: "user", content: message }],
+    onEvent,
+    {
+      autoApprove,
+      allowWrite: allowWrite || !!session.allowWrite,
+      trustCwd: session.trustCwd,
+      trustDir: session.trustDir,
+      nonInteractive: true
+    }
   );
-  if (logStream) logStream.end();
-  if (debug) process.stderr.write(`  (${eventCount} SSE events)
-`);
   if (streamText) {
     process.stdout.write(`\x1B[32mAssistant:\x1B[0m ${streamText}
 `);
@@ -23685,13 +24245,16 @@ async function singleTurnChatSession(session, message, debug, autoApprove = fals
 `);
   }
 }
-async function interactiveChatSession(session, debug) {
+async function interactiveChatSession(session, debug, autoApprove, allowWrite) {
   const aguiClient = new AGUIClient({
     baseUrl: session.ctx.envConfig.apiUrl,
+    workspaceUuid: session.workspaceUuid,
+    chatId: session.chatId,
     endpointUrl: session.aguiEndpointUrl,
     accessToken: session.ctx.accessToken,
     debug,
-    model: session.model
+    model: session.model,
+    appContext: session.appContext
   });
   clearScreen();
   console.log("=".repeat(60));
@@ -23720,7 +24283,7 @@ async function interactiveChatSession(session, debug) {
     }
   }
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const prompt = () => {
       rl.question("\x1B[34mYou:\x1B[0m ", async (input) => {
         const trimmed = input.trim();
@@ -23737,18 +24300,34 @@ async function interactiveChatSession(session, debug) {
         process.stdout.write("\n\x1B[32mAssistant:\x1B[0m ");
         let assistantContent = "";
         try {
-          await aguiClient.sendMessage(conversationMessages, (event) => {
-            const delta = getTextDelta(event);
-            if (delta) {
-              process.stdout.write(delta);
-              assistantContent += delta;
-            }
-            const errorMsg = getErrorMessage(event);
-            if (errorMsg) console.log(`
+          const { streamText } = await runConciergeAguiLoop(
+            aguiClient,
+            conversationMessages,
+            (event) => {
+              const delta = getTextDelta(event);
+              if (delta) {
+                process.stdout.write(delta);
+                assistantContent += delta;
+              }
+              const errorMsg = getErrorMessage(event);
+              if (errorMsg) console.log(`
 \x1B[31mError: ${errorMsg}\x1B[0m`);
-          });
-          if (assistantContent)
+            },
+            {
+              autoApprove,
+              allowWrite: allowWrite || !!session.allowWrite,
+              debug,
+              trustCwd: session.trustCwd,
+              trustDir: session.trustDir
+            }
+          );
+          if (streamText && !assistantContent) {
+            assistantContent = streamText;
+            process.stdout.write(streamText);
+          }
+          if (assistantContent) {
             conversationMessages.push({ role: "assistant", content: assistantContent });
+          }
           console.log("\n");
         } catch (error) {
           console.log(
@@ -23762,7 +24341,7 @@ async function interactiveChatSession(session, debug) {
     };
     rl.on("close", () => {
       console.log("\nGoodbye!");
-      resolve();
+      resolve2();
     });
     prompt();
   });
@@ -23859,8 +24438,8 @@ async function realtimeChatSession(session, vad, debug) {
   });
   tui.loadHistory(history);
   tui.start();
-  await new Promise((resolve) => {
-    client.once("closed", resolve);
+  await new Promise((resolve2) => {
+    client.once("closed", resolve2);
   });
 }
 async function voiceChatSession(session, vad, args, debug) {
@@ -23977,8 +24556,8 @@ Connecting to ${session.label.toLowerCase()}...
   tui.loadHistory(history);
   tui.start();
   mic.start(inputDeviceId);
-  await new Promise((resolve) => {
-    client.once("closed", resolve);
+  await new Promise((resolve2) => {
+    client.once("closed", resolve2);
   });
 }
 async function listAudioDevices() {
@@ -24008,13 +24587,14 @@ async function conciergeCommand(hctx) {
   const chatIdArg = typeof args["chat-id"] === "string" ? args["chat-id"] : void 0;
   const message = typeof args.message === "string" ? args.message : void 0;
   const chat = await getOrCreateConciergeChat(ctx, chatIdArg, !!message);
-  const session = buildConciergeSession(ctx, chat);
+  const session = buildConciergeSession(ctx, chat, args);
   await runChatSession(session, args);
 }
-function buildConciergeSession(ctx, chat) {
+function buildConciergeSession(ctx, chat, args) {
   const wsBase = ctx.envConfig.apiUrl.replace(/^https:/, "wss:").replace(/^http:/, "ws:");
   return {
     ctx,
+    workspaceUuid: "",
     chatId: chat.id,
     chatUuid: chat.uuid,
     chatTitle: chat.title || chat.uuid,
@@ -24022,8 +24602,12 @@ function buildConciergeSession(ctx, chat) {
     wsUrl: `${wsBase}/api/v2/concierge/voice/stream-ws`,
     loadMessages: () => getConciergeChatMessages(ctx, chat.id).catch(() => []),
     label: "Concierge",
-    model: void 0
+    model: void 0,
     // concierge doesn't send model field
+    appContext: buildCliConciergeAppContext(),
+    allowWrite: true,
+    trustCwd: !!args["trust-cwd"],
+    trustDir: typeof args["trust-dir"] === "string" ? args["trust-dir"] : void 0
   };
 }
 async function getOrCreateConciergeChat(ctx, chatIdArg, skipSelection) {
@@ -24058,6 +24642,95 @@ async function getOrCreateConciergeChat(ctx, chatIdArg, skipSelection) {
   }
   return selectedChat;
 }
+
+// src/commands/get-started.ts
+var WEB_SETUP = "https://app.gravityrail.com/setup";
+var WEB_GET_STARTED = "https://app.gravityrail.com/get-started";
+var HUMAN_GUIDE = `Gravity Rail \u2014 getting started
+
+1. Authenticate:  gr login --env prod
+   Confirm:       gr whoami
+
+2. Recommended path \u2014 concierge (no workspace required):
+   gr concierge chat --allow-write
+   The concierge can create your org (auto-created on first login), list products,
+   start Stripe checkout, and create your first workspace.
+
+3. Verify workspaces:  gr workspaces list
+
+4. Web wizards (human-friendly):  ${WEB_SETUP}  and  ${WEB_GET_STARTED}
+
+Headless boundary: Stripe checkout needs a human in a browser \u2014 the concierge returns
+a checkout URL; an agent should hand that link to the user, not loop on payment.
+
+Agent-readable steps:  gr get-started --format llm
+`;
+var LLM_GUIDE = `# Gravity Rail CLI bootstrap (agent instructions)
+
+## Preconditions
+- Install: \`npm install -g @gravity-rail/cli\` or \`npx @gravity-rail/cli\`
+- Authenticate: \`gr login --env prod\` (interactive OAuth). Verify with \`gr whoami\`.
+- **Monorepo dev:** from gravity-team with Docker dev up, use \`yarn gr <cmd> --realm superadmin\` (reads \`dev-realms.json\`; no browser). Rebuild: \`yarn workspace @gravity-rail/gr-cli build\`.
+
+## Important facts
+- **Agents/CI:** do not leave stdin open on read-only commands; use \`GRAVITY_RAIL_API_KEY\` or redirect stdin from /dev/null. Commands only read stdin when \`--data\`/\`--file\` is passed.
+- Use \`--env dev|staging|prod\` (default prod) so credentials match the target; \`gr whoami\` shows the active env.
+- After login, an **organization is created automatically** \u2014 do not create a duplicate org unless \`gr organizations list\` is empty.
+- **Workspace is required** for workflow/agent/task commands (\`-w <workspace-uuid>\`).
+- **Concierge does not require \`-w\`** \u2014 use it for first-run setup.
+
+## Recommended path (concierge-driven)
+\`\`\`bash
+gr concierge chat --allow-write --message "Help me set up my first Gravity Rail workspace"
+\`\`\`
+Flags for unattended turns:
+- \`--message\` / \`-m\`: single-turn (non-interactive)
+- \`--auto-approve\`: skip HITL tool approval where policy allows
+- \`--allow-write\`: required for create/update tools
+
+The concierge can: list/create orgs, list org/workspace products, create Stripe checkout sessions, create workspace specs, and \`create_workspace\`.
+
+## Manual CLI path (if not using concierge)
+1. \`gr whoami\` \u2014 confirm account
+2. \`gr organizations list\` \u2014 note org slug/UUID
+3. \`gr concierge chat\` OR web: ${WEB_GET_STARTED}
+4. Product purchase: concierge returns Stripe checkout URL \u2192 **human must complete in browser**
+5. \`gr workspaces list\` \u2014 pick workspace UUID for \`-w\`
+
+## Support (account-level, no workspace)
+\`\`\`bash
+gr support create --type question --title "..." --description "..." --allow-write
+gr support list
+\`\`\`
+
+## Web fallbacks
+- Concierge / setup: ${WEB_SETUP}
+- Wizard: ${WEB_GET_STARTED}
+
+## Headless limits (do not retry forever)
+- Stripe payment / checkout: requires human browser
+- OAuth login: requires human browser
+- Directory trust for future local-file tools: use \`--trust-cwd\` only after user confirms files are safe
+
+## Local project files (CLI only)
+After directory trust + \`--allow-write\`, the concierge can use \`read_local_file\`, \`list_local_dir\`, \`write_local_file\` (client-executed via HITL).
+
+## Verify success
+\`gr workspaces list\` then \`gr workflows list -w <uuid>\` or \`gr agents list -w <uuid>\`
+`;
+async function getStartedCommand(hctx) {
+  const format = hctx.args.format ?? hctx.args.agent;
+  const isLlm = format === "llm" || format === "agent" || hctx.args["format"] === "llm" || !!hctx.args.agent;
+  if (!isLlm) {
+    try {
+      requireAuth(hctx.ctx);
+    } catch {
+    }
+    process.stdout.write(HUMAN_GUIDE);
+    return;
+  }
+  process.stdout.write(LLM_GUIDE);
+}
 async function devImportLocalCommand(ctx, workspace) {
   stderr2(`Exporting workspace ${workspace}...`);
   const exportData = await ctx.apiClient.exportWorkspace(workspace);
@@ -24136,8 +24809,17 @@ async function manageCommand(hctx) {
   const chatIdArg = typeof args["chat-id"] === "string" ? args["chat-id"] : void 0;
   const message = typeof args.message === "string" ? args.message : void 0;
   const chat = await getOrCreateChat(ctx, workspace, chatIdArg, asMember, "manager", !!message);
-  const session = buildWorkspaceSession(ctx, workspace, chat, "Workspace Manager");
+  const session = buildWorkspaceSession(ctx, workspace, chat, "Workspace Manager", {
+    appContext: buildCliConciergeAppContext(),
+    allowWrite: true,
+    trustCwd: !!args["trust-cwd"],
+    trustDir: typeof args["trust-dir"] === "string" ? args["trust-dir"] : void 0
+  });
+  process.stderr.write(`Chat #${session.chatId}
+`);
   await runChatSession(session, args);
+  process.stderr.write(`Chat #${session.chatId}
+`);
 }
 async function chatCommand(hctx) {
   const ctx = requireAuth(hctx.ctx);
@@ -24162,10 +24844,11 @@ async function chatCommand(hctx) {
   const session = buildWorkspaceSession(ctx, workspace, chat, "Chat");
   await runChatSession(session, args);
 }
-function buildWorkspaceSession(ctx, workspace, chat, label) {
+function buildWorkspaceSession(ctx, workspace, chat, label, extra) {
   const wsBase = ctx.envConfig.apiUrl.replace(/^https:/, "wss:").replace(/^http:/, "ws:");
   return {
     ctx,
+    workspaceUuid: workspace,
     chatId: chat.id,
     chatUuid: chat.uuid,
     chatTitle: chat.title || chat.uuid,
@@ -24173,7 +24856,8 @@ function buildWorkspaceSession(ctx, workspace, chat, label) {
     wsUrl: `${wsBase}/api/v2/w/${workspace}/realtime/stream-ws`,
     loadMessages: () => ctx.apiClient.getChatMessages(workspace, chat.id, 50).catch(() => []),
     label,
-    model: "manager"
+    model: "manager",
+    ...extra
   };
 }
 async function getOrCreateChat(ctx, workspace, chatIdArg, asMemberId, chatType, skipSelection = false) {
@@ -24271,16 +24955,20 @@ var COLUMNS35 = [
   { header: "NAME", getValue: (a) => a.name || "", maxWidth: 30 },
   { header: "EMAIL", getValue: (a) => a.email || "", maxWidth: 40 },
   { header: "UUID", getValue: (a) => a.uuid },
+  { header: "ENV", getValue: () => "" },
   { header: "SUPERUSER", getValue: (a) => a.isSuperuser ? "yes" : "no" }
 ];
 async function whoamiCommand(ctx) {
   const account = await ctx.apiClient.getUserAccount();
-  outputSingle(account, ctx, COLUMNS35);
+  const columns = COLUMNS35.map(
+    (col) => col.header === "ENV" ? { ...col, getValue: () => ctx.env } : col
+  );
+  outputSingle(account, ctx, columns);
 }
 
 // package.json
 var package_default = {
-  version: "0.5.0"};
+  version: "0.5.1"};
 
 // src/gr.ts
 var VERSION = package_default.version;
@@ -24333,6 +25021,15 @@ function createRegistry() {
         name: "auto-approve",
         description: "Auto-approve all tool calls (skip HITL)",
         isFlag: true
+      },
+      {
+        name: "trust-cwd",
+        description: "Trust files in the current working directory (non-interactive)",
+        isFlag: true
+      },
+      {
+        name: "trust-dir",
+        description: "Trust files in this directory (non-interactive; absolute path)"
       }
     ],
     handler: async (hctx) => {
@@ -24366,6 +25063,37 @@ function createRegistry() {
       await chatCommand(hctx);
     }
   });
+  registry.registerCommand({
+    path: ["get-started"],
+    description: "Bootstrap instructions for new users and LLM agents",
+    requiresAuth: false,
+    args: [
+      {
+        name: "format",
+        description: "Output format: llm (agent-readable) or default (human)"
+      },
+      {
+        name: "agent",
+        description: "Alias for --format llm",
+        isFlag: true
+      }
+    ],
+    handler: async (hctx) => {
+      await getStartedCommand(hctx);
+    }
+  });
+  registry.registerCommand({
+    path: ["setup"],
+    description: "Alias for get-started \u2014 bootstrap instructions",
+    requiresAuth: false,
+    args: [
+      { name: "format", description: "Output format: llm or default" },
+      { name: "agent", description: "Alias for --format llm", isFlag: true }
+    ],
+    handler: async (hctx) => {
+      await getStartedCommand(hctx);
+    }
+  });
   registry.registerCommand({
     path: ["concierge", "chat"],
     description: "Interactive concierge chat (text, realtime, or voice)",
@@ -24385,6 +25113,15 @@ function createRegistry() {
         name: "auto-approve",
         description: "Auto-approve all tool calls (skip HITL)",
         isFlag: true
+      },
+      {
+        name: "trust-cwd",
+        description: "Trust files in the current working directory (non-interactive)",
+        isFlag: true
+      },
+      {
+        name: "trust-dir",
+        description: "Trust files in this directory (non-interactive; absolute path)"
       }
     ],
     handler: async (hctx) => {
@@ -24423,6 +25160,7 @@ function createRegistry() {
   return registry;
 }
 function parseGlobalOptions(argv) {
+  let env = "prod";
   let apiUrl;
   let outputFormat;
   let verbose = false;
@@ -24432,6 +25170,13 @@ function parseGlobalOptions(argv) {
   let collectingCommand = true;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
+    const eqIdx = arg.indexOf("=");
+    const flagPart = eqIdx !== -1 ? arg.slice(0, eqIdx) : arg;
+    const inlineValue = eqIdx !== -1 ? arg.slice(eqIdx + 1) : void 0;
+    if (flagPart === "--env" && (inlineValue ?? argv[i + 1])) {
+      env = inlineValue ?? argv[++i];
+      continue;
+    }
     if (arg === "--api-url" && argv[i + 1]) {
       apiUrl = argv[++i];
       continue;
@@ -24459,7 +25204,7 @@ function parseGlobalOptions(argv) {
     rest.unshift(commandWords.pop());
   }
   return {
-    opts: { apiUrl, outputFormat, verbose, allowWrite },
+    opts: { env, apiUrl, outputFormat, verbose, allowWrite },
     commandWords,
     rest
   };
@@ -24508,7 +25253,8 @@ async function main() {
       process.stderr.write("Error: --workspace (-w) is required\n");
       process.exit(1);
     }
-    const data = await readJsonInput(parsedArgs);
+    const acceptsJsonInput = cmd.args?.some((a) => a.name === "data" || a.name === "file");
+    const data = acceptsJsonInput ? await readJsonInput(parsedArgs) : void 0;
     hctx = { ctx, args: parsedArgs, workspace, data };
   } else {
     const baseCtx = createPublicContext(opts);
@@ -24527,7 +25273,7 @@ async function main() {
   }
   await cmd.handler(hctx);
   if (process.stdout.writableNeedDrain) {
-    await new Promise((resolve) => process.stdout.once("drain", resolve));
+    await new Promise((resolve2) => process.stdout.once("drain", resolve2));
   }
   process.exit(0);
 }