@uru-intelligence/cli 0.3.53 → 0.3.55

package/dist/uru.mjs

@@ -6,7 +6,7 @@ import { spawn as spawn3 } from "node:child_process";
 
 // src/types.ts
 var DEFAULT_API_URL = "https://api.uruintelligence.com";
-var CLI_VERSION = "0.3.53";
+var CLI_VERSION = "0.3.55";
 var ExitCode = {
   Ok: 0,
   Failure: 1,
@@ -202,6 +202,7 @@ function buildOperationGroups(op) {
     op("gem.fs_read", "gems", "Read a file from a Gem project directory.", "gem_query", "fs_read", "read"),
     op("gem.fs_write", "gems", "Write a file inside a Gem project directory.", "gem_control_plane", "fs_write", "write"),
     op("gem.fs_batch_write", "gems", "Write multiple Gem files atomically through the server source layer.", "gem_control_plane", "fs_batch_write", "write"),
+    op("gem.fs_sync", "gems", "Synchronize Gem files and deletions atomically through the server source layer.", "gem_control_plane", "fs_sync", "write"),
     op("gem.fs_patch", "gems", "Apply a patch to Gem source files.", "gem_control_plane", "fs_patch", "write"),
     op("gem.fs_mkdir", "gems", "Create a directory inside a Gem project.", "gem_control_plane", "fs_mkdir", "write"),
     op("gem.fs_rm", "gems", "Remove a file or directory from a Gem project.", "gem_control_plane", "fs_rm", "destructive"),
@@ -240,8 +241,12 @@ function buildOperationGroups(op) {
   const libraryOperations = [
     op("library.ls", "library", "List visible Library folders and resources.", "library_query", "ls", "read"),
     op("library.stat", "library", "Read metadata for a visible Library path.", "library_query", "stat", "read"),
+    op("library.read", "library", "Read a visible text-backed Library resource by path.", "library_query", "read", "read"),
     op("library.search", "library", "Search visible Library resources server-side.", "library_query", "search", "read"),
     op("library.mkdir", "library", "Create a Library folder.", "library_fs", "mkdir", "write"),
+    op("library.write", "library", "Create or replace a text-backed Library resource by path.", "library_fs", "write", "write"),
+    op("library.patch", "library", "Replace text content for a text-backed Library resource by path.", "library_fs", "patch", "write"),
+    op("library.cp", "library", "Copy a supported Library item when the backing resource supports copy semantics.", "library_fs", "cp", "write"),
     op("library.mv", "library", "Move or rename a Library item.", "library_fs", "mv", "write"),
     op("library.move_workspace", "library", "Move a Library item to another workspace.", "library_fs", "move_workspace", "destructive"),
     op("library.rm", "library", "Trash a Library item.", "library_fs", "rm", "destructive"),
@@ -249,19 +254,17 @@ function buildOperationGroups(op) {
     op("library.empty_trash", "library", "Permanently empty Library trash.", "library_fs", "empty_trash", "destructive"),
     op("library.upload_preflight", "library", "Preflight a Library upload.", "library_upload", "preflight", "read"),
     op("library.upload_create_session", "library", "Create a direct Library upload session.", "library_upload", "create_session", "write"),
-    op("library.upload_complete_session", "library", "Complete a direct Library upload session.", "library_upload", "complete_session", "write"),
-    op("context.manage", "library", "Manage typed Context Library metadata such as workspace-default, teams, category, and favorite state.", "context_manage", undefined, "write"),
-    op("prompt.render", "library", "Render a typed Prompt Library resource with supplied variables.", "prompt_render", undefined, "read"),
-    op("persona.query", "library", "Query typed Persona Library resources and linked prompt/context resources.", "persona_query", undefined, "read")
+    op("library.upload_complete_session", "library", "Complete a direct Library upload session.", "library_upload", "complete_session", "write")
   ];
   const sharingOperations = [
     op("sharing.share", "sharing", "Share a Library resource with a user, team, or workspace.", "library_collab", "share", "write"),
     op("sharing.unshare", "sharing", "Remove a Library resource grant.", "library_collab", "unshare", "destructive"),
-    op("sharing.permissions_list", "sharing", "List permissions for a Library resource.", "library_collab", "list_permissions", "read"),
+    op("sharing.permissions_list", "sharing", "List permissions for a Library resource.", "sharing_query", "list_permissions", "read"),
+    op("sharing.shares_list", "sharing", "List active share grants for a Library resource.", "sharing_query", "list_shares", "read"),
     op("sharing.permissions_set", "sharing", "Set permissions for a Library resource.", "library_collab", "set_permissions", "write"),
     op("sharing.settings_set", "sharing", "Set share settings for a Library resource.", "library_collab", "set_share_settings", "write"),
     op("sharing.transfer_ownership", "sharing", "Transfer ownership for a Library resource.", "library_collab", "transfer_ownership", "destructive"),
-    op("sharing.versions_list", "sharing", "List Library resource versions.", "library_collab", "list_versions", "read"),
+    op("sharing.versions_list", "sharing", "List Library resource versions.", "sharing_query", "list_versions", "read"),
     op("sharing.version_restore", "sharing", "Restore a Library resource version.", "library_collab", "restore_version", "destructive"),
     op("sharing.comment", "sharing", "Comment on a Library resource.", "library_collab", "comment", "write"),
     op("sharing.comment_resolve", "sharing", "Resolve a Library resource comment.", "library_collab", "resolve_comment", "write"),
@@ -414,7 +417,7 @@ function buildOperationGroups(op) {
     op("file.download_for_user", "files", "Prepare a file download for the user.", "DOWNLOAD_FILE_FOR_USER", undefined, "read")
   ];
   const businessSqlOperations = [
-    op("business_sql.transcript", "business_sql", "Query transcript SQL.", "TRANSCRIPT_SQL", undefined, "read"),
+    op("business_sql.transcript", "business_sql", "Query transcript SQL.", "transcript_sql", undefined, "read"),
     op("business_sql.maguire", "business_sql", "Query Maguire SQL.", "MAGUIRE_SQL", undefined, "read"),
     op("business_sql.tyler", "business_sql", "Query Tyler SQL.", "TYLER_SQL", undefined, "read"),
     op("business_sql.cfo", "business_sql", "Query CFO SQL.", "CFO_SQL", undefined, "read"),
@@ -471,10 +474,13 @@ var internalOnlyPlatformToolIds = new Set([
   "MAGUIRE_WRITE_SQL",
   "PEREGRINE_SQL",
   "RESTORE_DATASET_ROWS",
-  "TRANSCRIPT_SQL",
   "TYLER_SQL",
   "UPSERT_DATASET_ROWS"
 ]);
+// ../../packages/platform-operations/src/external_company_mcp_policy.ts
+var externalCompanyMcpDeniedToolIds = new Set([
+  "MAGUIRE_WRITE_SQL"
+]);
 // ../../packages/platform-operations/src/index.ts
 var ALL_SURFACES = [
   "cli",
@@ -621,6 +627,12 @@ class UruApiClient {
       body: { parameters }
     });
   }
+  async streamTool(name, parameters, onEvent) {
+    return this.requestStream(`/api/platform/tools/${encodeURIComponent(name)}/execute`, {
+      method: "POST",
+      body: { parameters }
+    }, onEvent);
+  }
   async api(path, options) {
     return this.request(path, options);
   }
@@ -644,6 +656,30 @@ class UruApiClient {
     }
     return payload;
   }
+  async requestStream(path, options, onEvent) {
+    const init = {
+      method: options.method,
+      ...this.signal === undefined ? {} : { signal: this.signal },
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        Accept: "application/x-ndjson, application/json",
+        ...this.workspaceId === undefined ? {} : { "X-Uru-Workspace-Id": this.workspaceId },
+        ...options.body === undefined ? {} : { "Content-Type": "application/json" }
+      },
+      ...options.body === undefined ? {} : { body: JSON.stringify(options.body) }
+    };
+    const response = await this.fetchImpl(`${this.apiUrl}${path}`, init);
+    if (response.ok && response.body !== null && isNdjsonResponse(response.headers.get("content-type"))) {
+      await readNdjsonStream(response.body, onEvent);
+      return { streamed: true };
+    }
+    const text = await response.text();
+    const payload = parseResponseBody(text);
+    if (!response.ok) {
+      throw apiError(response.status, payload, options.body);
+    }
+    return { streamed: false, payload };
+  }
 }
 function normalizeApiUrl(value) {
   const trimmed = value.trim();
@@ -659,6 +695,52 @@ function parseResponseBody(text) {
   }
   return parsed;
 }
+function isNdjsonResponse(contentType) {
+  const normalized = String(contentType ?? "").toLowerCase();
+  return normalized.includes("application/x-ndjson") || normalized.includes("application/ndjson") || normalized.includes("text/x-ndjson");
+}
+async function readNdjsonStream(body, onEvent) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder;
+  let buffered = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffered += decoder.decode(value, { stream: true });
+      buffered = emitCompleteNdjsonLines(buffered, onEvent);
+    }
+    buffered += decoder.decode();
+    emitNdjsonLine(buffered, onEvent);
+  } finally {
+    reader.releaseLock();
+  }
+}
+function emitCompleteNdjsonLines(buffered, onEvent) {
+  let start = 0;
+  while (true) {
+    const newline = buffered.indexOf(`
+`, start);
+    if (newline === -1) {
+      return buffered.slice(start);
+    }
+    emitNdjsonLine(buffered.slice(start, newline), onEvent);
+    start = newline + 1;
+  }
+}
+function emitNdjsonLine(line, onEvent) {
+  const trimmed = line.trim();
+  if (trimmed === "") {
+    return;
+  }
+  const parsed = JSON.parse(trimmed);
+  if (!isJsonObject(parsed)) {
+    throw new CliError("API returned a non-object stream event");
+  }
+  onEvent(parsed);
+}
 function apiError(status, payload, requestBody) {
   const redactions = collectSensitiveValues(requestBody);
   const summary = errorMessage(payload) ?? `Uru API request failed with HTTP ${status}`;
@@ -1005,6 +1087,15 @@ function writeStreamJson(io, event, value) {
   io.stdout.write(`${JSON.stringify({ event, ...payload })}
 `);
 }
+function writeStreamJsonEvent(io, value) {
+  const payload = objectPayload(value);
+  if (typeof payload["event"] !== "string" || payload["event"].trim() === "") {
+    writeStreamJson(io, "event", payload);
+    return;
+  }
+  io.stdout.write(`${JSON.stringify(payload)}
+`);
+}
 function writeText(io, value) {
   io.stdout.write(value.endsWith(`
 `) ? value : `${value}
@@ -1075,13 +1166,13 @@ GEMS
   uru build [library/name.gem] --dry-run --outdir   Build/validate and export build manifest
   uru deploy [library/name.gem] [--prod] [--dry-run] Server-side build/deploy/publish
   uru deploy [library/name.gem] --skip-promote      Deploy without promoting the published link
-  uru promote <version-id> [library/name.gem]      Promote a Gem version to a published link
+  uru promote <version-id> [library/name.gem]      Promote a staged Gem version/deployment
   uru status [library/name.gem]                     Local source status versus source lock
   uru logs [library/name.gem] [--limit 100] [--follow]
                                                     Runtime logs
   uru open [library/name.gem]                       Print first published URL
-  uru rollback <version-id> [library/name.gem] --yes
-                                                    Roll back a link to a Gem version
+  uru rollback [<version-id>] [library/name.gem] --yes
+                                                    Roll back a live Gem link
   uru gems inspect|validate|build|status [library/name.gem]
   uru gems versions upload [library/name.gem]       Create an immutable Gem version
   uru gems versions deploy <version-id> [library/name.gem]
@@ -1093,20 +1184,29 @@ LIBRARY / DATASETS / TOOLS
   uru library ls [path]                             List Library items
   uru library search <query>                        Search Library items
   uru library mkdir <path>                          Create a Library folder
+  uru library read <path>                           Print a text-backed Library resource
+  uru library write <path> --file ./note.md --create Create/replace text-backed Library content
+  uru library patch <path> --content "..."          Replace text-backed Library content
+  uru library cp|mv <path> <target-path>            Copy or move visible Library items
+  uru library rm <path> [--permanent --yes]         Trash or permanently delete Library items
+  uru library restore <path>                        Restore a trashed Library item
   # Prompts, personas, contexts: use typed Library paths such as library/Prompts/Foo.prompt.md
-  uru datasets query <dataset-slug> [--limit 50]    Query dataset rows
+  uru datasets query <dataset-slug> [--limit 50]    Query dataset rows; add --response-format concise for compact output
+  uru automations ls|get|create|enable|disable      Manage automations without raw JSON parameters
+  uru automations trigger <id>                      Start a manual automation run
+  uru automations runs ls|tail <run-id>             Inspect automation runs and logs
   uru secrets put <name> [library/name.gem] --value-stdin Store Gem secret without shell history
   uru secrets ls [library/name.gem]                  List Gem secret metadata only
   uru secrets rm <name> [library/name.gem] --yes     Remove a Gem secret value
   uru env pull [library/name.gem]                    Write a local metadata-only .env template
   uru env run -- <cmd>                               Run with local env values and redact output
-  uru tokens create [library/name.gem] --expiry 30d Create a Gem-scoped deploy token
+  uru tokens create [library/name.gem] --name CI --expiry 30d Create a Gem-scoped deploy token
   uru tokens ls [library/name.gem]                   List Gem token metadata only
   uru tokens revoke <token-id> --yes                 Revoke a Gem token immediately
   uru tools ls|schema <name>|run <name>             Full platform-tool parity
   uru operations ls [--family gems]                 Print generated operation registry
   uru operations run <operation-id> --params-json    Run any registry-backed operation
-  uru workspace|sharing|automations|web <op>         Registry families for full-platform parity
+  uru workspace|sharing|web <op>                    Registry families for full-platform parity
   uru mcp config|install                              Print/write MCP client config
   uru complete bash|zsh|fish                          Print shell completions
   uru update                                          Print the self-update command
@@ -1180,8 +1280,6 @@ qualified operation form.
 var REGISTRY_FAMILY_COMMANDS = {
   workspace: "workspace",
   sharing: "sharing",
-  automations: "automations",
-  automation: "automations",
   web: "web",
   files: "files",
   file: "files",
@@ -1242,13 +1340,16 @@ deployment that can be promoted after checks; --prod cannot be combined with
 --no-publish.
 `,
   promote: `Usage: uru promote <version-id> [library/name.gem] [--link-id <published-link-id>] [--no-wait]
+       uru promote --deployment-id <deployment-id> [library/name.gem] [--link-id <published-link-id>] [--no-wait]
 
-Deploy an immutable Gem version and promote a published link to it. If --link-id
-is omitted, Uru publishes through the default clean Gem link.
+Promote an already-staged immutable Gem version or ready deployment. With
+--link-id, this is a published-link pointer flip after checks pass. If --link-id
+is omitted, Uru promotes through the default clean Gem link.
 `,
-  pull: `Usage: uru pull [library/name.gem]
+  pull: `Usage: uru pull [library/name.gem] [--force]
 
 Download Gem source into the current directory and write .uru/source-lock.json.
+Refuses to overwrite dirty local files unless --force is supplied.
 `,
   status: `Usage: uru status [library/name.gem] [--json]
 
@@ -1275,11 +1376,12 @@ before the command to emit NDJSON events.
 
 Print the first available hosted/published Gem URL.
 `,
-  rollback: `Usage: uru rollback <version-id> [library/name.gem] [--link-id <published-link-id>] --yes
+  rollback: `Usage: uru rollback [<version-id>] [library/name.gem] [--deployment-id <deployment-id>] [--link-id <published-link-id>] --yes
 
-Deploy an immutable Gem version and retarget the published link as a rollback.
-Requires --yes because it mutates live traffic. If --link-id is omitted, Uru
-publishes through the default clean Gem link.
+Rollback retargets a live link to an already-materialized older Gem version or
+deployment after server-side rollback preflight passes. Requires --yes because it
+mutates live traffic. If --link-id is omitted, Uru rolls back through the active
+Primary Gem link.
 `,
   gems: `Usage: uru gems <inspect|validate|build|status|read|write|versions|checks> [...]
 
@@ -1290,8 +1392,9 @@ same platform operations used by MCP and the web UI.
        uru gems versions deploy <version-id> [library/name.gem] [--pct 100]
 
 Create immutable Gem versions and deploy them through the Gem control plane.
-Upload accepts --message, --tag/--tags, and --preview-alias. Gradual percentages
-below 100 fail closed until split traffic routing is enabled.
+Upload accepts --message, --tag/--tags, and --preview-alias. Non-100
+percentages are accepted only with --skip-promote to stage rollout intent; live
+promote/rollback requires 100 until weighted link routing is enabled.
 `,
   "gems checks": `Usage: uru gems checks <version-id> [library/name.gem] [--deployment-id <id>]
        uru gems checks run browser|security [library/name.gem] [--deployment-id <id>] [--blocking]
@@ -1303,12 +1406,39 @@ the check a release gate; security also accepts --deep.
   library: `Usage: uru library ls [path]
        uru library search <query>
        uru library mkdir <path>
+       uru library read <path>
+       uru library write <path> (--file <local-path>|--content <text>|--stdin) [--create]
+       uru library patch <path> (--file <local-path>|--content <text>|--stdin)
+       uru library cp <path> <target-path>
+       uru library mv <path> <target-path>
+       uru library rm <path> [--permanent] [--yes]
+       uru library restore <path>
+       uru library empty-trash --yes
 
-Operate on Library items through platform tools.
+Operate on Library items through platform tools. Use write --create to create
+text-backed Context, Prompt, Persona, note, and plain .md/.txt resources at
+visible Library paths. For binary files, use library_upload through
+\`uru operations run\` or \`uru tools run\`; for Gem child source files, use
+\`uru gems read|write\`.
 `,
-  datasets: `Usage: uru datasets query <dataset-slug> [--limit 50] [--offset 0]
+  datasets: `Usage: uru datasets query <dataset-slug> [--limit 50] [--offset 0] [--response-format detailed|concise]
 
-Query dataset rows through the platform dataset operation.
+Query dataset rows through the platform dataset operation. Use concise for id plus selected/display fields while keeping server totals and aggregates.
+`,
+  automations: `Usage: uru automations ls [--status draft|active|paused|archived] [--limit 100] [--view summary|detailed]
+       uru automations get <automation-id>
+       uru automations create <name> [--description <text>] [--status draft|active|paused]
+       uru automations enable <automation-id>
+       uru automations disable <automation-id>
+       uru automations trigger <automation-id> [--input-message <text>] [--idempotency-key <key>]
+       uru automations runs ls [automation-id] [--scope personal|workspace] [--limit 100]
+       uru automations runs tail <run-id> [--limit 1000] [--level debug|info|warn|error]
+       uru automations runs debug|timeline <run-id>
+       uru automations runs cancel <run-id> --yes
+
+Manage automations through first-class CLI commands backed by the shared
+operation registry. Reads default to compact summary views; use --view detailed
+only when you need full graph/config payloads.
 `,
   tokens: `Usage: uru tokens create [library/name.gem] --expiry <duration> --name <name>
        uru tokens ls [library/name.gem]
@@ -1412,6 +1542,19 @@ async function emitTool(ctx, operationId, params, options = {}) {
       operation: options.streamStart["operation"] ?? operationId,
       phase: "requesting"
     });
+    const streamed = await executeOperationStream(ctx, operationId, params, (event) => {
+      writeStreamJsonEvent(ctx.io, event);
+    });
+    if (streamed.streamed) {
+      return;
+    }
+    const unwrapped2 = unwrapToolResult(streamed.payload ?? null);
+    const output2 = options.transform?.(unwrapped2) ?? unwrapped2;
+    writeStreamJson(ctx.io, "result", output2);
+    writeStreamJson(ctx.io, "done", {
+      operation: options.streamStart["operation"] ?? operationId
+    });
+    return;
   }
   const result = await executeOperation(ctx, operationId, params);
   const unwrapped = unwrapToolResult(result);
@@ -1429,6 +1572,17 @@ async function emitTool(ctx, operationId, params, options = {}) {
     writeText(ctx.io, options.textExtractor?.(output) ?? JSON.stringify(output, null, 2));
   }
 }
+async function executeOperationStream(ctx, operationId, params, onEvent) {
+  const operation = getPlatformOperation(operationId);
+  if (operation === undefined) {
+    throw new CliError(`Unknown operation registry id: ${operationId}`);
+  }
+  const toolParams = { ...params };
+  if (operation.backendOp !== undefined) {
+    toolParams["op"] = operation.backendOp;
+  }
+  return client(ctx).streamTool(operation.backendToolName, toolParams, onEvent);
+}
 async function executeOperation(ctx, operationId, params) {
   const operation = getPlatformOperation(operationId);
   if (operation === undefined) {
@@ -1474,7 +1628,7 @@ function tokenGemRefParams(flags, linkedProject, options = {}) {
   }
   const explicitGem = flags.values["--gem"];
   if (explicitGem !== undefined) {
-    return { gem_id: explicitGem };
+    return explicitGem.startsWith("library/") ? { path: explicitGem } : { gem_id: explicitGem };
   }
   const positional = flags.positionals[0];
   if (positional !== undefined) {
@@ -1624,6 +1778,18 @@ function sanitizeConfig(value) {
   if (value["insecureStorage"] === true) {
     config.insecureStorage = true;
   }
+  if (isRecord(value["update"])) {
+    const update = {};
+    for (const key of ["lastCheckedAt", "latestVersion"]) {
+      const item = value["update"][key];
+      if (typeof item === "string" && item.trim() !== "") {
+        update[key] = item;
+      }
+    }
+    if (Object.keys(update).length > 0) {
+      config.update = update;
+    }
+  }
   return config;
 }
 function isNodeError(error) {
@@ -2008,10 +2174,15 @@ function credentialStoreUnavailableError(backend, message, error) {
 var CLI_DOCS_URL = "https://docs.uruintelligence.com/cli/errors";
 var ERROR_TIPS = {
   auth_required: "Run `uru login`, pass `--token`, or set `URU_TOKEN` before retrying.",
+  interactive_login_required: "Run `uru login` before this command, use `uru login --device` on remote shells, or pass `--token`/`URU_TOKEN` in CI.",
   conflict: "Run `uru status` or `uru pull` to inspect remote changes; use `--force` only when you intentionally want to overwrite.",
   api_request_failed: "Check the request parameters, workspace context, and server response before retrying.",
   keychain_access_failed: "Unlock the OS credential store, or retry with `--insecure-storage` only if plaintext local storage is acceptable.",
   keychain_unavailable: "Install or unlock the OS credential helper, or retry with `--insecure-storage` only if plaintext local storage is acceptable.",
+  oauth_state_mismatch: "Restart `uru login`; this usually means the browser callback came from an old or mismatched login tab.",
+  oauth_authorization_failed: "Restart `uru login` and approve access in the browser, or use `uru login --device` if the browser cannot reach the callback.",
+  oauth_missing_code: "Restart `uru login`; if the browser callback keeps failing, retry with `uru login --device`.",
+  oauth_request_failed: "Check the API URL and network access, then retry `uru login`; use `uru login --device` from SSH/headless environments.",
   oauth_device_failed: "Restart `uru login --device` and complete authorization in the browser before the code expires.",
   oauth_device_timeout: "Run `uru login --device` again and complete browser authorization before the timeout.",
   cancelled: "The command was cancelled; rerun it only if you still want the operation to continue."
@@ -2257,6 +2428,120 @@ function terminalWidth(stream, env) {
   return 80;
 }
 
+// src/update-notifier.ts
+var PACKAGE_NAME = "@uru-intelligence/cli";
+var REGISTRY_LATEST_URL = "https://registry.npmjs.org/@uru-intelligence%2Fcli/latest";
+var UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+var UPDATE_CHECK_TIMEOUT_MS = 750;
+async function maybeNotifyCliUpdate(ctx, options = {}) {
+  if (!shouldCheckForUpdate(ctx, options.env ?? process.env)) {
+    return;
+  }
+  const now = options.now?.() ?? Date.now();
+  if (!isUpdateCheckDue(ctx.config, now)) {
+    return;
+  }
+  const checkedConfig = withUpdateCheckTimestamp(ctx.config, now);
+  await writeConfigBestEffort(ctx, checkedConfig);
+  const latestVersion = await fetchLatestVersion({
+    fetchImpl: ctx.fetch ?? fetch,
+    parentSignal: ctx.abortSignal
+  });
+  if (latestVersion === undefined) {
+    return;
+  }
+  await writeConfigBestEffort(ctx, {
+    ...checkedConfig,
+    update: {
+      ...checkedConfig.update,
+      latestVersion
+    }
+  });
+  if (compareVersions(latestVersion, CLI_VERSION) <= 0) {
+    return;
+  }
+  ctx.io.stderr.write(`A newer Uru CLI is available: ${CLI_VERSION} → ${latestVersion}. ` + `Run npm install -g ${PACKAGE_NAME}@latest
+`);
+}
+function shouldCheckForUpdate(ctx, env) {
+  return ctx.outputFormat === "text" && ctx.terminal.stderrIsTty && !ctx.terminal.ci && env["NO_UPDATE_NOTIFIER"] === undefined && env["URU_NO_UPDATE_NOTIFIER"] === undefined;
+}
+function isUpdateCheckDue(config, now) {
+  const raw = config.update?.lastCheckedAt;
+  if (raw === undefined) {
+    return true;
+  }
+  const lastCheckedAt = Date.parse(raw);
+  return !Number.isFinite(lastCheckedAt) || now - lastCheckedAt >= UPDATE_CHECK_INTERVAL_MS;
+}
+function withUpdateCheckTimestamp(config, now) {
+  return {
+    ...config,
+    update: {
+      ...config.update,
+      lastCheckedAt: new Date(now).toISOString()
+    }
+  };
+}
+async function fetchLatestVersion(args) {
+  const controller = new AbortController;
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, UPDATE_CHECK_TIMEOUT_MS);
+  timeout.unref?.();
+  const abortFromParent = () => {
+    controller.abort(args.parentSignal.reason);
+  };
+  if (args.parentSignal.aborted) {
+    abortFromParent();
+  } else {
+    args.parentSignal.addEventListener("abort", abortFromParent, { once: true });
+  }
+  try {
+    const response = await args.fetchImpl(REGISTRY_LATEST_URL, {
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return;
+    }
+    const payload = await response.json();
+    if (!isRecord2(payload)) {
+      return;
+    }
+    const version = payload["version"];
+    return typeof version === "string" && version.trim() !== "" ? version.trim() : undefined;
+  } catch {
+    return;
+  } finally {
+    clearTimeout(timeout);
+    args.parentSignal.removeEventListener("abort", abortFromParent);
+  }
+}
+async function writeConfigBestEffort(ctx, config) {
+  try {
+    await ctx.store.write(config);
+  } catch {}
+}
+function compareVersions(left, right) {
+  const leftParts = versionParts(left);
+  const rightParts = versionParts(right);
+  const width = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0;index < width; index += 1) {
+    const delta = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+    if (delta !== 0) {
+      return delta;
+    }
+  }
+  return 0;
+}
+function versionParts(version) {
+  return version.replace(/^v/, "").split(/[.-]/).map((part) => Number.parseInt(part, 10)).filter((part) => Number.isFinite(part));
+}
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 // src/auth-commands.ts
 import { readFile as readFile3 } from "node:fs/promises";
 import { createServer } from "node:http";
@@ -2633,14 +2918,19 @@ async function resolveFlagToken(flags, stdin) {
   return;
 }
 async function login(ctx, options = {}) {
-  const token = ctx.token === undefined || ctx.token.trim() === "" ? await obtainLoginSessionToken(ctx) : ctx.token;
-  const loginClient = new UruApiClient({
-    apiUrl: ctx.apiUrl,
-    token,
-    ...ctx.workspace !== undefined ? { workspaceId: ctx.workspace } : {},
-    ...ctx.fetch !== undefined ? { fetch: ctx.fetch } : {}
-  });
-  const result = await loginClient.validateToken();
+  const existingToken = ctx.token === undefined || ctx.token.trim() === "" ? undefined : ctx.token;
+  let token = existingToken ?? await obtainLoginSessionToken(ctx);
+  let result;
+  try {
+    result = await validateSessionToken(ctx, token);
+  } catch (error) {
+    const storedTokenIsStale = existingToken !== undefined && !ctx.tokenIsExplicit && isAuthRequiredError(error);
+    if (!storedTokenIsStale) {
+      throw error;
+    }
+    token = await obtainLoginSessionToken(ctx);
+    result = await validateSessionToken(ctx, token);
+  }
   const selectedWorkspace = selectWorkspace(result, ctx.workspace);
   await persistLoginToken(ctx, token, selectedWorkspace);
   if (options.silentSuccess === true) {
@@ -2661,6 +2951,18 @@ async function login(ctx, options = {}) {
     writeText(ctx.io, ctx.insecureStorage ? "Logged in (token stored in local config)" : "Logged in");
   }
 }
+async function validateSessionToken(ctx, token) {
+  const loginClient = new UruApiClient({
+    apiUrl: ctx.apiUrl,
+    token,
+    ...ctx.workspace !== undefined ? { workspaceId: ctx.workspace } : {},
+    ...ctx.fetch !== undefined ? { fetch: ctx.fetch } : {}
+  });
+  return loginClient.validateToken();
+}
+function isAuthRequiredError(error) {
+  return error instanceof CliError && error.exitCode === ExitCode.AuthRequired;
+}
 async function readAllStdin(input) {
   const chunks = [];
   for await (const chunk of input) {
@@ -2900,13 +3202,11 @@ async function switchWorkspace(ctx, workspaceId) {
 }
 
 // src/local-commands.ts
-import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname as dirname3 } from "node:path";
+import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+import { dirname as dirname3, resolve as resolve2 } from "node:path";
 var GENERIC_FAMILY_COMMANDS = {
   workspace: "workspace",
   sharing: "sharing",
-  automations: "automations",
-  automation: "automations",
   web: "web",
   files: "files",
   file: "files",
@@ -2942,6 +3242,7 @@ var TOP_LEVEL_COMMANDS = [
   "open",
   "rollback",
   "gems",
+  "automations",
   "library",
   "datasets",
   "tokens",
@@ -3131,7 +3432,109 @@ async function dispatchLibrary(ctx, sub, args) {
     });
     return;
   }
-  throw new CliError("Usage: uru library ls|search|mkdir");
+  if (sub === "read" || sub === "cat") {
+    await emitTool(ctx, "library.read", {
+      path: requireCommandValue(args[0], "Usage: uru library read <path>")
+    }, { textExtractor: extractLibraryTextContent });
+    return;
+  }
+  if (sub === "write") {
+    const flags = parseLocalFlags(args);
+    const path = requireCommandValue(flags.positionals[0], "Usage: uru library write <path> (--file <local-path>|--content <text>|--stdin) [--create]");
+    await emitTool(ctx, "library.write", {
+      path,
+      content: await libraryTextFromFlags(ctx, flags, "write"),
+      create: flags.booleans.has("--create")
+    });
+    return;
+  }
+  if (sub === "patch") {
+    const flags = parseLocalFlags(args);
+    const path = requireCommandValue(flags.positionals[0], "Usage: uru library patch <path> (--file <local-path>|--content <text>|--stdin)");
+    await emitTool(ctx, "library.patch", {
+      path,
+      content: await libraryTextFromFlags(ctx, flags, "patch")
+    });
+    return;
+  }
+  if (sub === "cp" || sub === "copy") {
+    const [path, targetPath] = args;
+    await emitTool(ctx, "library.cp", {
+      path: requireCommandValue(path, "Usage: uru library cp <path> <target-path>"),
+      target_path: requireCommandValue(targetPath, "Usage: uru library cp <path> <target-path>")
+    });
+    return;
+  }
+  if (sub === "mv" || sub === "move" || sub === "rename") {
+    const [path, targetPath] = args;
+    await emitTool(ctx, "library.mv", {
+      path: requireCommandValue(path, "Usage: uru library mv <path> <target-path>"),
+      target_path: requireCommandValue(targetPath, "Usage: uru library mv <path> <target-path>")
+    });
+    return;
+  }
+  if (sub === "rm" || sub === "remove" || sub === "delete") {
+    const flags = parseLocalFlags(args);
+    if ((flags.booleans.has("--permanent") || flags.booleans.has("--hard-delete")) && !ctx.yes && !flags.booleans.has("--yes")) {
+      throw new CliError("Permanent Library deletion cannot be undone. Re-run with --yes to confirm.");
+    }
+    const path = requireCommandValue(flags.positionals[0], "Usage: uru library rm <path> [--permanent] [--yes]");
+    await emitTool(ctx, "library.rm", {
+      path,
+      permanent: flags.booleans.has("--permanent") || flags.booleans.has("--hard-delete")
+    });
+    return;
+  }
+  if (sub === "restore") {
+    await emitTool(ctx, "library.restore", {
+      path: requireCommandValue(args[0], "Usage: uru library restore <path>"),
+      include_trashed: true
+    });
+    return;
+  }
+  if (sub === "empty-trash") {
+    const flags = parseLocalFlags(args);
+    if (!ctx.yes && !flags.booleans.has("--yes")) {
+      throw new CliError("Emptying Library trash permanently deletes all trashed items. Re-run with --yes to confirm.");
+    }
+    await emitTool(ctx, "library.empty_trash", {});
+    return;
+  }
+  throw new CliError("Usage: uru library ls|search|mkdir|read|write|patch|cp|mv|rm|restore|empty-trash");
+}
+async function libraryTextFromFlags(ctx, flags, verb) {
+  const content = flags.values["--content"];
+  const file = flags.values["--file"];
+  const fromStdin = flags.booleans.has("--stdin");
+  const sources = [content !== undefined, file !== undefined, fromStdin].filter(Boolean).length;
+  if (sources !== 1) {
+    throw new CliError(`Library ${verb} requires exactly one of --file <path>, --content <text>, or --stdin.`);
+  }
+  if (content !== undefined) {
+    return content;
+  }
+  if (file !== undefined) {
+    return await readFile4(resolve2(ctx.cwd, file), "utf8");
+  }
+  return await readStdinText(ctx.stdin ?? process.stdin);
+}
+async function readStdinText(stdin) {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function extractLibraryTextContent(value) {
+  if (!isJsonObject2(value)) {
+    return;
+  }
+  const content = value["content"];
+  if (typeof content === "string") {
+    return content;
+  }
+  const text = value["text"];
+  return typeof text === "string" ? text : undefined;
 }
 async function dispatchDatasets(ctx, sub, args) {
   if (sub !== "query") {
@@ -3139,13 +3542,154 @@ async function dispatchDatasets(ctx, sub, args) {
     return;
   }
   const flags = parseLocalFlags(args);
-  const datasetId = requireCommandValue(flags.positionals[0], "Usage: uru datasets query <dataset-slug> [--limit 50]");
-  await emitTool(ctx, "dataset.query", {
+  const datasetId = requireCommandValue(flags.positionals[0], "Usage: uru datasets query <dataset-slug> [--limit 50] [--response-format detailed|concise]");
+  const params = {
     dataset_id: datasetId,
     datasetId,
     limit: integerFlag(flags, "--limit", 50),
     offset: integerFlag(flags, "--offset", 0)
-  });
+  };
+  const responseFormat = flags.values["--response-format"];
+  if (responseFormat !== undefined) {
+    if (responseFormat !== "detailed" && responseFormat !== "concise") {
+      throw new CliError('--response-format must be "detailed" or "concise"');
+    }
+    params["response_format"] = responseFormat;
+  }
+  await emitTool(ctx, "dataset.query", params);
+}
+async function dispatchAutomations(ctx, sub, args) {
+  if (sub === "ls" || sub === "list") {
+    const flags = parseLocalFlags(args);
+    const params = {
+      limit: integerFlag(flags, "--limit", 100)
+    };
+    copyOptionalFlag(flags, params, "--status", "status_filter");
+    copyOptionalFlag(flags, params, "--parent-folder-id", "parent_folder_id");
+    copyOptionalFlag(flags, params, "--folder-id", "parent_folder_id");
+    copyAutomationView(flags, params);
+    await emitTool(ctx, "automation.list", params);
+    return;
+  }
+  if (sub === "get" || sub === "inspect") {
+    const flags = parseLocalFlags(args);
+    await emitTool(ctx, "automation.get", {
+      automation_id: requireCommandValue(flags.positionals[0], "Usage: uru automations get <automation-id>")
+    });
+    return;
+  }
+  if (sub === "create") {
+    const flags = parseLocalFlags(args);
+    const params = {
+      name: requireCommandValue(flags.positionals[0], "Usage: uru automations create <name> [--description <text>] [--status draft|active|paused] [--graph-json {...}]")
+    };
+    copyOptionalFlag(flags, params, "--description", "description");
+    copyOptionalFlag(flags, params, "--status", "status");
+    copyOptionalFlag(flags, params, "--parent-folder-id", "parent_folder_id");
+    copyOptionalFlag(flags, params, "--folder-id", "parent_folder_id");
+    const graphJson = flags.values["--graph-json"];
+    if (graphJson !== undefined) {
+      params["graph_json"] = parseParamsJson(graphJson, "--graph-json");
+    }
+    await emitTool(ctx, "automation.create", params);
+    return;
+  }
+  if (sub === "enable" || sub === "disable") {
+    const flags = parseLocalFlags(args);
+    await emitTool(ctx, "automation.update", {
+      automation_id: requireCommandValue(flags.positionals[0], `Usage: uru automations ${sub} <automation-id>`),
+      status: sub === "enable" ? "active" : "paused"
+    });
+    return;
+  }
+  if (sub === "trigger" || sub === "run" || sub === "start") {
+    const flags = parseLocalFlags(args);
+    const params = {
+      automation_id: requireCommandValue(flags.values["--automation-id"] ?? flags.positionals[0], "Usage: uru automations trigger <automation-id> [--input-message <text>] [--idempotency-key <key>]")
+    };
+    copyOptionalFlag(flags, params, "--input-message", "input_message");
+    copyOptionalFlag(flags, params, "--idempotency-key", "idempotency_key");
+    await emitTool(ctx, "automation.run_start", params);
+    return;
+  }
+  if (sub === "runs") {
+    await dispatchAutomationRuns(ctx, args[0], args.slice(1));
+    return;
+  }
+  throw new CliError("Usage: uru automations ls|get|create|enable|disable|trigger|runs");
+}
+async function dispatchAutomationRuns(ctx, sub, args) {
+  if (sub === "ls" || sub === "list") {
+    const flags = parseLocalFlags(args);
+    const params = {
+      limit: integerFlag(flags, "--limit", 100)
+    };
+    copyOptionalFlag(flags, params, "--automation-id", "automation_id");
+    copyOptionalFlag(flags, params, "--scope", "scope");
+    copyOptionalFlag(flags, params, "--cursor", "cursor");
+    copyOptionalFlag(flags, params, "--include", "include");
+    if (params["automation_id"] === undefined && flags.positionals[0] !== undefined) {
+      params["automation_id"] = flags.positionals[0];
+    }
+    await emitTool(ctx, "automation.runs_list", params);
+    return;
+  }
+  if (sub === "tail" || sub === "logs") {
+    const flags = parseLocalFlags(args);
+    const params = {
+      run_id: requireCommandValue(flags.values["--run-id"] ?? flags.positionals[0], "Usage: uru automations runs tail <run-id> [--limit 1000] [--level debug|info|warn|error]"),
+      limit: integerFlag(flags, "--limit", 1000)
+    };
+    copyOptionalFlag(flags, params, "--level", "level");
+    await emitTool(ctx, "automation.run_logs", params);
+    return;
+  }
+  if (sub === "debug") {
+    const flags = parseLocalFlags(args);
+    const params = {
+      run_id: requireCommandValue(flags.values["--run-id"] ?? flags.positionals[0], "Usage: uru automations runs debug <run-id> [--log-limit 100] [--transcript-limit 50]"),
+      log_limit: integerFlag(flags, "--log-limit", 100),
+      transcript_limit: integerFlag(flags, "--transcript-limit", 50)
+    };
+    copyOptionalFlag(flags, params, "--log-level", "log_level");
+    await emitTool(ctx, "automation.run_debug", params);
+    return;
+  }
+  if (sub === "timeline") {
+    const flags = parseLocalFlags(args);
+    await emitTool(ctx, "automation.run_timeline", {
+      run_id: requireCommandValue(flags.values["--run-id"] ?? flags.positionals[0], "Usage: uru automations runs timeline <run-id> [--limit 5000]"),
+      limit: integerFlag(flags, "--limit", 5000)
+    });
+    return;
+  }
+  if (sub === "cancel") {
+    if (!ctx.yes) {
+      throw new CliError("Cancelling an automation run requires --yes because it mutates execution state.");
+    }
+    const flags = parseLocalFlags(args);
+    await emitTool(ctx, "automation.run_cancel", {
+      run_id: requireCommandValue(flags.values["--run-id"] ?? flags.positionals[0], "Usage: uru automations runs cancel <run-id> --yes")
+    });
+    return;
+  }
+  throw new CliError("Usage: uru automations runs ls|tail|debug|timeline|cancel");
+}
+function copyOptionalFlag(flags, target, flagName, paramName) {
+  const value = flags.values[flagName];
+  if (value !== undefined) {
+    target[paramName] = value;
+  }
+}
+function copyAutomationView(flags, target) {
+  const value = flags.values["--view"];
+  if (value === undefined) {
+    return;
+  }
+  if (value !== "summary" && value !== "detailed") {
+    throw new CliError('--view must be "summary" or "detailed"');
+  }
+  target["view"] = value;
 }
 function mcpServerConfig(args) {
   const apiKey = requireCommandValue(args.apiKey, "MCP config requires --api-key, --token, URU_TOKEN, or a logged-in CLI token.");
@@ -3199,9 +3743,9 @@ function levenshtein(left, right) {
 }
 
 // src/gem-lifecycle-commands.ts
-import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
+import { mkdir as mkdir4, readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
 import { setTimeout as sleep } from "node:timers/promises";
-import { join as join3, resolve as resolve2 } from "node:path";
+import { join as join3, resolve as resolve3 } from "node:path";
 async function dispatchGems(ctx, sub, args, linkedProject) {
   const gemPath = () => gemPathFromArgs(args, linkedProject);
   if (sub === "inspect") {
@@ -3254,7 +3798,7 @@ async function gemInit(ctx, args) {
     params["content"] = flags.values["--content"];
   }
   if (flags.values["--file"] !== undefined) {
-    params["content"] = await readFile4(flags.values["--file"], "utf8");
+    params["content"] = await readFile5(flags.values["--file"], "utf8");
   }
   await emitGemTool(ctx, "gem.init", params);
 }
@@ -3353,10 +3897,10 @@ async function gemBuild(ctx, args, linkedProject) {
 }
 async function gemPromote(ctx, args, linkedProject) {
   const flags = parseLocalFlags(args);
-  assertAllowedLocalFlags(flags, ["--gem", "--link-id", "--no-wait", "--path", "--pct"], "uru promote");
+  assertAllowedLocalFlags(flags, ["--deployment-id", "--gem", "--link-id", "--no-wait", "--path", "--pct"], "uru promote");
   await deployVersionToPublishedLink(ctx, flags, linkedProject, {
     operation: "promote",
-    usage: "Usage: uru promote <version-id> [library/name.gem] [--link-id <published-link-id>]"
+    usage: "Usage: uru promote <version-id> [library/name.gem] [--link-id <published-link-id>] | uru promote --deployment-id <deployment-id> [library/name.gem]"
   });
 }
 async function gemChecks(ctx, args, linkedProject) {
@@ -3366,10 +3910,11 @@ async function gemChecks(ctx, args, linkedProject) {
     return;
   }
   assertAllowedLocalFlags(flags, ["--deployment-id", "--gem", "--path"], "uru gems checks");
+  const explicitDeploymentId = flags.values["--deployment-id"];
+  const gemPathArgs = explicitDeploymentId === undefined ? flags.positionals.slice(1) : flags.positionals;
   const params = {
-    path: gemPathFromArgs(flags.positionals.slice(1), linkedProject)
+    path: gemPathFromArgs(gemPathArgs, linkedProject)
   };
-  const explicitDeploymentId = flags.values["--deployment-id"];
   if (explicitDeploymentId !== undefined) {
     params["deployment_id"] = explicitDeploymentId;
   } else if (flags.positionals[0] !== undefined) {
@@ -3576,20 +4121,28 @@ async function gemOpen(ctx, args, linkedProject) {
 }
 async function gemRollback(ctx, args, linkedProject) {
   const flags = parseLocalFlags(args);
-  assertAllowedLocalFlags(flags, ["--gem", "--link-id", "--no-wait", "--path", "--pct", "--yes"], "uru rollback");
+  assertAllowedLocalFlags(flags, [
+    "--deployment-id",
+    "--gem",
+    "--link-id",
+    "--no-wait",
+    "--path",
+    "--pct",
+    "--yes"
+  ], "uru rollback");
   if (!ctx.yes && !flags.booleans.has("--yes")) {
     throw new CliError("Rollback requires --yes to confirm the link pointer change.");
   }
   await deployVersionToPublishedLink(ctx, flags, linkedProject, {
     operation: "rollback",
-    usage: "Usage: uru rollback <version-id> [library/name.gem] [--link-id <published-link-id>] --yes"
+    usage: "Usage: uru rollback [<version-id>] [library/name.gem] [--deployment-id <deployment-id>] [--link-id <published-link-id>] --yes"
   });
 }
 async function gemWrite(ctx, args) {
   const flags = parseLocalFlags(args);
   const gemPath = requireCommandValue(flags.positionals[0], "Usage: uru gems write <gem-path> <file> --content <text>|--file <local-file>");
   const filePath = requireCommandValue(flags.positionals[1], "Usage: uru gems write <gem-path> <file> --content <text>|--file <local-file>");
-  const content = flags.values["--content"] ?? (flags.values["--file"] === undefined ? undefined : await readFile4(flags.values["--file"], "utf8"));
+  const content = flags.values["--content"] ?? (flags.values["--file"] === undefined ? undefined : await readFile5(flags.values["--file"], "utf8"));
   if (content === undefined) {
     throw new CliError("Gem write requires --content or --file.");
   }
@@ -3619,12 +4172,15 @@ async function dispatchGemVersions(ctx, args, linkedProject) {
     const gemPath = gemPathFromArgs(flags.positionals.slice(1), linkedProject);
     const pct = flags.values["--pct"] ?? trafficPercent;
     const trafficPercentValue = pct === undefined || pct === "" ? 100 : parseTrafficPercent(pct);
-    assertCurrentBackendTrafficSupport(trafficPercentValue);
+    const publish = !flags.booleans.has("--skip-promote");
+    if (publish && trafficPercentValue !== 100) {
+      throw new CliError("Gradual Gem traffic shifts are not enabled yet. Use --skip-promote to create the deployment without changing live traffic, or deploy with --pct 100.");
+    }
     const params = {
       path: gemPath,
       version_id: requireCommandValue(versionId, "Usage: uru gems versions deploy <version-id> [library/name.gem] [--pct 100] [--skip-promote]"),
       traffic_percent: trafficPercentValue,
-      publish: !flags.booleans.has("--skip-promote")
+      publish
     };
     copyStringFlag(flags, params, "--link-id", "link_id");
     if (flags.booleans.has("--no-wait")) {
@@ -3659,13 +4215,17 @@ async function gemVersionUpload(ctx, args, linkedProject) {
   }
   copyStringFlag(flags, params, "--source-version-id", "source_version_id");
   copyStringFlag(flags, params, "--message", "message");
-  copyStringFlag(flags, params, "--preview-alias", "preview_alias");
+  const previewAlias = flags.values["--preview-alias"];
+  if (previewAlias !== undefined) {
+    params["preview_alias"] = validatePreviewAlias(previewAlias);
+  }
   const tags = tagsFromFlags(flags);
   if (tags.length > 0) {
     params["tags"] = tags;
   }
   await emitGemTool(ctx, "gem.version_upload", params, {
-    streamStart: { operation: "gem.version_upload", path: gemPath }
+    streamStart: { operation: "gem.version_upload", path: gemPath },
+    textExtractor: extractVersionUploadSummary
   });
 }
 function parseTrafficPercent(raw) {
@@ -3675,29 +4235,33 @@ function parseTrafficPercent(raw) {
   }
   return value;
 }
-function assertCurrentBackendTrafficSupport(value) {
-  if (value !== 100) {
-    throw new CliError("Gradual percentage Gem deploys require backend traffic-splitting support; omit @pct/--pct or use 100 until split traffic is enabled.");
-  }
-}
 async function deployVersionToPublishedLink(ctx, flags, linkedProject, options) {
-  const versionId = requireCommandValue(flags.positionals[0], options.usage);
-  const gemPath = gemPathFromArgs(flags.positionals.slice(1), linkedProject);
+  const deploymentId = flags.values["--deployment-id"];
+  const firstPositional = flags.positionals[0];
+  const versionId = deploymentId === undefined && firstPositional !== undefined ? firstPositional.startsWith("library/") ? undefined : firstPositional : undefined;
+  if (deploymentId === undefined && versionId === undefined) {
+    throw new CliError(options.usage);
+  }
+  const gemPath = gemPathFromArgs(versionId === undefined ? flags.positionals : flags.positionals.slice(1), linkedProject);
   const trafficPercent = parseTrafficPercent(flags.values["--pct"] ?? "100");
-  assertCurrentBackendTrafficSupport(trafficPercent);
+  if (trafficPercent !== 100) {
+    throw new CliError(`${options.operation} does not support partial traffic shifts yet. Deploy the version with --skip-promote for validation, or ${options.operation} with --pct 100.`);
+  }
   const params = {
-    path: gemPath,
-    version_id: versionId,
-    traffic_percent: trafficPercent,
-    publish: true,
-    operation: options.operation
+    path: gemPath
   };
+  if (deploymentId === undefined) {
+    params["version_id"] = requireCommandValue(versionId, options.usage);
+  } else {
+    params["app_deployment_id"] = deploymentId;
+  }
   copyStringFlag(flags, params, "--link-id", "link_id");
   if (flags.booleans.has("--no-wait")) {
     params["wait"] = false;
   }
-  await emitGemTool(ctx, "gem.version_deploy", params, {
-    streamStart: { operation: "gem.version_deploy", path: gemPath },
+  const operation = `gem.${options.operation}`;
+  await emitGemTool(ctx, operation, params, {
+    streamStart: { operation, path: gemPath },
     textExtractor: extractDeploymentUrl
   });
 }
@@ -3708,6 +4272,13 @@ function tagsFromFlags(flags) {
   }
   return raw.split(",").map((tag) => tag.trim()).filter((tag) => tag.length > 0);
 }
+function validatePreviewAlias(rawAlias) {
+  const alias = rawAlias.trim();
+  if (alias.length === 0 || alias.length > 63 || !/^[a-z][a-z0-9-]*[a-z0-9]$/u.test(alias)) {
+    throw new CliError("--preview-alias must be a DNS-safe label: 1-63 characters, start with a lowercase letter, contain only lowercase letters, numbers, and dashes, and not end with a dash.");
+  }
+  return alias;
+}
 function assertAllowedLocalFlags(flags, allowedFlags, commandName) {
   const allowed = new Set(allowedFlags);
   const unexpected = localFlagNames(flags).filter((flag) => !allowed.has(flag));
@@ -3727,9 +4298,12 @@ function localFlagNames(flags) {
 }
 async function writeBuildManifest(ctx, outdir, buildResult) {
   const manifest = gemBuildManifestFromBuildResult(buildResult);
-  const absoluteOutdir = resolve2(ctx.cwd, outdir);
+  const providerDecision = gemProviderDecisionFromBuildResult(buildResult, manifest);
+  const absoluteOutdir = resolve3(ctx.cwd, outdir);
   await mkdir4(absoluteOutdir, { recursive: true });
   await writeFile4(join3(absoluteOutdir, "gem-build-manifest.json"), `${JSON.stringify(manifest, null, 2)}
+`, { mode: 384 });
+  await writeFile4(join3(absoluteOutdir, "gem-provider-decision.json"), `${JSON.stringify(providerDecision, null, 2)}
 `, { mode: 384 });
 }
 function gemBuildManifestFromBuildResult(buildResult) {
@@ -3782,6 +4356,80 @@ function normalizeGemBuildManifest(value) {
     manifest_kind: "gem_build_manifest"
   };
 }
+function gemProviderDecisionFromBuildResult(buildResult, manifest) {
+  const root = jsonObjectOrNull(buildResult);
+  const build = jsonObjectOrNull(root?.["build"]);
+  const buildResultDetails = jsonObjectOrNull(build?.["build_result"]);
+  const buildMetadata = jsonObjectOrNull(buildResultDetails?.["metadata"]);
+  const runtimeProfile = firstJsonObject([
+    root?.["runtime_profile"],
+    root?.["runtimeProfile"],
+    build?.["runtime_profile"],
+    build?.["runtimeProfile"],
+    buildResultDetails?.["runtime_profile"],
+    buildResultDetails?.["runtimeProfile"],
+    buildMetadata?.["runtime_profile"],
+    buildMetadata?.["runtimeProfile"]
+  ]) ?? {};
+  const providerDecision = firstJsonObject([
+    root?.["provider_decision"],
+    root?.["providerDecision"],
+    build?.["provider_decision"],
+    build?.["providerDecision"],
+    buildResultDetails?.["provider_decision"],
+    buildResultDetails?.["providerDecision"],
+    buildMetadata?.["provider_decision"],
+    buildMetadata?.["providerDecision"]
+  ]) ?? {};
+  const runtimeContract = firstJsonObject([
+    root?.["runtime_contract"],
+    root?.["runtimeContract"],
+    build?.["runtime_contract"],
+    build?.["runtimeContract"],
+    buildResultDetails?.["runtime_contract"],
+    buildResultDetails?.["runtimeContract"],
+    buildMetadata?.["runtime_contract"],
+    buildMetadata?.["runtimeContract"],
+    manifest["runtime_contract"],
+    manifest["runtimeContract"]
+  ]) ?? {};
+  return {
+    schema: "uru.gem.provider_decision.v1",
+    schema_version: 1,
+    manifest_kind: "gem_provider_decision",
+    provider: stringFieldFromJsonObjects([providerDecision, runtimeProfile, manifest], ["provider", "runtime_provider", "runtimeProvider", "selected_provider"]),
+    runtime_class: stringFieldFromJsonObjects([providerDecision, runtimeProfile, manifest], ["runtime_class", "runtimeClass", "class", "serving_mode"]),
+    runtime_profile: runtimeProfile,
+    provider_decision: providerDecision,
+    runtime_contract: runtimeContract,
+    manifest_summary: {
+      serving_mode: manifest["serving_mode"] ?? null,
+      worker_compatibility: manifest["worker_compatibility"] ?? null,
+      serverful_compatibility: manifest["serverful_compatibility"] ?? null,
+      runtime_requirements: manifest["runtime_requirements"] ?? null
+    }
+  };
+}
+function firstJsonObject(values) {
+  for (const value of values) {
+    const object = jsonObjectOrNull(value);
+    if (object !== null) {
+      return object;
+    }
+  }
+  return null;
+}
+function stringFieldFromJsonObjects(objects, keys) {
+  for (const object of objects) {
+    for (const key of keys) {
+      const value = object[key];
+      if (typeof value === "string" && value.trim() !== "") {
+        return value.trim();
+      }
+    }
+  }
+  return null;
+}
 function jsonObjectOrNull(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return null;
@@ -3791,6 +4439,48 @@ function jsonObjectOrNull(value) {
 function extractDeploymentUrl(value) {
   return firstUrl(value);
 }
+function extractVersionUploadSummary(value) {
+  const objects = collectJsonObjects(value);
+  const versionId = stringFieldFromJsonObjects(objects, [
+    "version_id",
+    "versionId",
+    "id"
+  ]);
+  const previewUrl = stringFieldFromJsonObjects(objects, [
+    "preview_url",
+    "previewUrl",
+    "preview_alias_url",
+    "previewAliasUrl",
+    "url"
+  ]) ?? firstUrl(value);
+  const lines = [
+    versionId === null ? null : `Version: ${versionId}`,
+    previewUrl === undefined || previewUrl === null ? null : `Preview: ${previewUrl}`
+  ].filter((line) => line !== null);
+  return lines.length === 0 ? undefined : lines.join(`
+`);
+}
+function collectJsonObjects(value) {
+  const objects = [];
+  collectJsonObjectsInto(value, objects);
+  return objects;
+}
+function collectJsonObjectsInto(value, objects) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectJsonObjectsInto(item, objects);
+    }
+    return;
+  }
+  const object = jsonObjectOrNull(value);
+  if (object === null) {
+    return;
+  }
+  objects.push(object);
+  for (const child of Object.values(object)) {
+    collectJsonObjectsInto(child, objects);
+  }
+}
 function trimTrailingSlashes(value) {
   let end = value.length;
   while (end > 0 && value.charCodeAt(end - 1) === 47) {
@@ -3807,10 +4497,20 @@ function trimLeadingSlashes(value) {
 }
 
 // src/gem-source-commands.ts
-import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
-import { dirname as dirname4, join as join4, resolve as resolve3 } from "node:path";
+import { mkdir as mkdir5, rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
+import { dirname as dirname4, join as join4, resolve as resolve4 } from "node:path";
 async function gemSourcePull(ctx, args, linkedProject) {
-  const gemPath = gemPathFromArgs(args, linkedProject);
+  const flags = parseLocalFlags(args);
+  const gemPath = gemPathFromArgs(flags.positionals, linkedProject);
+  const force = flags.booleans.has("--force");
+  const previousLock = await readSourceLock(ctx.cwd);
+  const localFilesBeforePull = await collectLocalSourceFiles(ctx.cwd);
+  const localStatusBeforePull = compareSourceLock(previousLock, localFilesBeforePull);
+  if (!force && !localStatusBeforePull.clean) {
+    throw new CliError(dirtyPullErrorMessage(localStatusBeforePull), {
+      code: ExitCode.Conflict
+    });
+  }
   const tree = unwrapToolResult(await executeOperation(ctx, "gem.fs_tree", {
     path: gemPath,
     recursive: true
@@ -3830,6 +4530,7 @@ async function gemSourcePull(ctx, args, linkedProject) {
     await writePulledSourceFile(ctx.cwd, filePath, content);
     files[filePath] = sha256Hex(content);
   }
+  const pruned = await pruneRemoteDeletedSourceFiles(ctx.cwd, previousLock, localFilesBeforePull, new Set(filePaths));
   const lock = {
     ...sourceVersionId === undefined ? {} : { sourceVersionId },
     files,
@@ -3840,8 +4541,10 @@ async function gemSourcePull(ctx, args, linkedProject) {
     ok: true,
     path: gemPath,
     files: filePaths,
+    prunedFiles: pruned.deleted,
+    preservedFiles: pruned.preserved,
     ...sourceVersionId === undefined ? {} : { sourceVersionId }
-  }, `Pulled ${filePaths.length} file${filePaths.length === 1 ? "" : "s"} from ${gemPath}`);
+  }, formatPullSummary(gemPath, filePaths.length, pruned));
 }
 async function gemSourceStatus(ctx, args, linkedProject) {
   const flags = parseLocalFlags(args);
@@ -3901,24 +4604,16 @@ async function gemSourcePush(ctx, args, linkedProject) {
     ...lock.sourceVersionId === undefined ? {} : { sourceVersionId: lock.sourceVersionId }
   };
   try {
-    for (const deletedPath of localStatus.deleted) {
-      const deleteResult = unwrapToolResult(await executeOperation(ctx, "gem.fs_rm", {
-        path: gemFilePath(gemPath, deletedPath),
-        recursive: false,
-        ...sourceMutationCasParams(sourceCas, force),
-        change_summary: force ? "Force-push local Gem source deletion via Uru CLI." : "Push local Gem source deletion via Uru CLI."
-      }));
-      sourceCas = nextSourceMutationCas(sourceCas, deleteResult);
-    }
-    if (sortedFiles.length > 0) {
-      const writeResult = unwrapToolResult(await executeOperation(ctx, "gem.fs_batch_write", {
-        path: gemPath,
-        files: sortedFiles.map(localFileBatchWritePayload),
-        ...sourceMutationCasParams(sourceCas, force),
-        change_summary: force ? "Force-push local Gem source via Uru CLI." : "Push local Gem source via Uru CLI."
-      }));
-      sourceCas = nextSourceMutationCas(sourceCas, writeResult);
-    }
+    const syncResult = unwrapToolResult(await executeOperation(ctx, "gem.fs_sync", {
+      path: gemPath,
+      files: sortedFiles.map(localFileBatchWritePayload),
+      delete_paths: localStatus.deleted.map((deletedPath) => ({
+        path: deletedPath
+      })),
+      ...sourceMutationCasParams(sourceCas, force),
+      change_summary: force ? "Force-push local Gem source via Uru CLI." : "Push local Gem source via Uru CLI."
+    }));
+    sourceCas = nextSourceMutationCas(sourceCas, syncResult);
   } catch (error) {
     if (isConflictLikeError(error)) {
       throw new CliError(error instanceof Error ? error.message : "Gem source conflict", { code: ExitCode.Conflict, cause: error });
@@ -3945,6 +4640,44 @@ function localFileBatchWritePayload(file) {
     content_base64: file.contentBase64
   };
 }
+async function pruneRemoteDeletedSourceFiles(cwd, previousLock, localFilesBeforePull, remotePaths) {
+  const deleted = [];
+  const preserved = [];
+  const lockedFiles = Object.entries(previousLock.files ?? {}).sort(([left], [right]) => left.localeCompare(right));
+  for (const [projectPath2, lockedHash] of lockedFiles) {
+    if (remotePaths.has(projectPath2)) {
+      continue;
+    }
+    const localFile = localFilesBeforePull[projectPath2];
+    if (localFile === undefined) {
+      continue;
+    }
+    if (localFile.sha256 !== lockedHash) {
+      preserved.push(projectPath2);
+      continue;
+    }
+    const safePath = safeProjectPath(projectPath2);
+    if (safePath === null) {
+      preserved.push(projectPath2);
+      continue;
+    }
+    await rm3(join4(resolve4(cwd), ...safePath.split("/")), { force: true });
+    deleted.push(projectPath2);
+  }
+  return { deleted, preserved };
+}
+function formatPullSummary(gemPath, writtenCount, pruned) {
+  const parts = [
+    `Pulled ${writtenCount} file${writtenCount === 1 ? "" : "s"} from ${gemPath}`
+  ];
+  if (pruned.deleted.length > 0) {
+    parts.push(`pruned ${pruned.deleted.length} remote-deleted file${pruned.deleted.length === 1 ? "" : "s"}`);
+  }
+  if (pruned.preserved.length > 0) {
+    parts.push(`preserved ${pruned.preserved.length} locally changed remote-deleted file${pruned.preserved.length === 1 ? "" : "s"}`);
+  }
+  return parts.join("; ");
+}
 function sourceMutationCasParams(cas, force) {
   if (force || cas.sourceVersionId === undefined) {
     return { force: true };
@@ -4036,6 +4769,17 @@ function formatLocalStatusEntries(status) {
     ...status.deleted.map((path) => `D ${path}`)
   ];
 }
+function dirtyPullErrorMessage(status) {
+  const entries = formatLocalStatusEntries(status);
+  const preview = entries.slice(0, 10).map((entry) => `  ${entry}`).join(`
+`);
+  const moreCount = Math.max(0, entries.length - 10);
+  const moreLine = moreCount > 0 ? `
+  ...and ${moreCount} more local change(s)` : "";
+  return `Refusing to pull because local Gem source has uncommitted changes that could be overwritten.
+Run \`uru status\` to inspect them, save or push your changes, or re-run \`uru pull --force\` to replace local files with server source.
+${preview}${moreLine}`;
+}
 async function tryRemoteSourceOperation(ctx, operationId, params) {
   try {
     return {
@@ -4138,7 +4882,7 @@ async function writePulledSourceFile(cwd, projectPath2, content) {
   if (safePath === null) {
     throw new CliError(`Refusing to write unsafe Gem source path: ${projectPath2}`);
   }
-  const localPath = join4(resolve3(cwd), ...safePath.split("/"));
+  const localPath = join4(resolve4(cwd), ...safePath.split("/"));
   await mkdir5(dirname4(localPath), { recursive: true });
   await writeFile5(localPath, content);
 }
@@ -4193,20 +4937,34 @@ function isConflictLikeError(error) {
 
 // src/token-env-secret-commands.ts
 import { spawn as spawn2 } from "node:child_process";
-import { chmod, mkdir as mkdir6, readFile as readFile5, writeFile as writeFile6 } from "node:fs/promises";
-import { dirname as dirname5, resolve as resolve4 } from "node:path";
+import { chmod, mkdir as mkdir6, readFile as readFile6, writeFile as writeFile6 } from "node:fs/promises";
+import { dirname as dirname5, resolve as resolve5 } from "node:path";
 async function dispatchTokens(ctx, sub, args, linkedProject) {
   if (sub === "create") {
     const flags = parseLocalFlags(args);
+    const usage = "Usage: uru tokens create [library/name.gem] [--gem <id>] --name <name> (--expiry 30d|--expires-at <iso>)";
+    const name = requireCommandValue(flags.values["--name"], usage);
+    const expiry = flags.values["--expiry"];
+    const expiresAt = flags.values["--expires-at"];
+    if (expiry === undefined && expiresAt === undefined) {
+      throw new CliError("Gem deploy token creation requires --expiry <duration> or --expires-at <iso timestamp>.");
+    }
+    if (expiry !== undefined && expiresAt !== undefined) {
+      throw new CliError("Pass only one token lifetime flag: --expiry or --expires-at.");
+    }
     const params = {
       ...tokenGemRefParams(flags, linkedProject, {
         required: true,
-        usage: "Usage: uru tokens create [library/name.gem] [--gem <id>] [--name <name>] [--expiry 30d]"
-      })
+        usage
+      }),
+      name
     };
-    copyStringFlag(flags, params, "--name", "name");
-    copyStringFlag(flags, params, "--expiry", "expiry");
-    copyStringFlag(flags, params, "--expires-at", "expires_at");
+    if (expiry !== undefined) {
+      params["expiry"] = expiry;
+    }
+    if (expiresAt !== undefined) {
+      params["expires_at"] = expiresAt;
+    }
     const scopes = tokenScopes(flags);
     if (scopes.length > 0) {
       params["scopes"] = scopes;
@@ -4294,7 +5052,7 @@ async function dispatchEnv(ctx, sub, args, linkedProject) {
     })));
     const secrets = extractSecretRows(result);
     const content = formatEnvTemplate(secrets);
-    const absolutePath = resolve4(ctx.cwd, outputPath);
+    const absolutePath = resolve5(ctx.cwd, outputPath);
     await mkdir6(dirname5(absolutePath), { recursive: true });
     await writeFile6(absolutePath, content, { mode: 384 });
     await chmod(absolutePath, 384);
@@ -4311,8 +5069,8 @@ async function dispatchEnv(ctx, sub, args, linkedProject) {
   }
   if (sub === "run") {
     const parsed = parseEnvRunArgs(args);
-    const envFilePath = resolve4(ctx.cwd, parsed.envFile);
-    const envVars = parseEnvFile(await readFile5(envFilePath, "utf8"));
+    const envFilePath = resolve5(ctx.cwd, parsed.envFile);
+    const envVars = parseEnvFile(await readFile6(envFilePath, "utf8"));
     await runEnvCommand(ctx, parsed.command, envVars);
     return;
   }
@@ -4332,10 +5090,10 @@ async function secretValueFromFlags(ctx, flags) {
   }
   const valueFile = flags.values["--value-file"];
   if (valueFile !== undefined) {
-    return (await readFile5(resolve4(ctx.cwd, valueFile), "utf8")).trimEnd();
+    return (await readFile6(resolve5(ctx.cwd, valueFile), "utf8")).trimEnd();
   }
   if (flags.booleans.has("--value-stdin")) {
-    return await readStdinText(ctx.stdin ?? process.stdin);
+    return await readStdinText2(ctx.stdin ?? process.stdin);
   }
   throw new CliError("Secret put requires --value-file <path> or --value-stdin. Values are never printed by the CLI.");
 }
@@ -4480,7 +5238,7 @@ function redactValues2(content, values) {
   }
   return redacted;
 }
-async function readStdinText(stdin) {
+async function readStdinText2(stdin) {
   const chunks = [];
   for await (const chunk of stdin) {
     chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
@@ -4640,6 +5398,7 @@ async function runCli(options) {
       credentialStore,
       apiUrl,
       ...token !== undefined ? { token } : {},
+      tokenIsExplicit: flagToken !== undefined || envToken !== undefined,
       ...workspace !== undefined ? { workspace } : {},
       cwd,
       json: outputFormat === "json",
@@ -4661,6 +5420,9 @@ async function runCli(options) {
     };
     throwIfCancelled(cancellation.signal);
     await dispatchWithImplicitLogin(ctx, parsed.command, linkedProject);
+    await maybeNotifyCliUpdate(ctx, {
+      ...options.env === undefined ? {} : { env: options.env }
+    });
     return ExitCode.Ok;
   } catch (error) {
     const cliError = normalizeError(error);
@@ -4894,6 +5656,11 @@ async function dispatch(ctx, command, linkedProject) {
     await dispatchDatasets(ctx, sub, command.slice(2));
     return;
   }
+  if (head === "automations") {
+    await withWorkspace(ctx);
+    await dispatchAutomations(ctx, sub, command.slice(2));
+    return;
+  }
   if (head === "tokens" || head === "token") {
     await withWorkspace(ctx);
     await dispatchTokens(ctx, sub, command.slice(2), linkedProject);
@@ -4947,14 +5714,14 @@ function writeSystemClipboard(text) {
   const platform = process.platform;
   const command = platform === "darwin" ? "pbcopy" : platform === "win32" ? "clip" : "xclip";
   const args = platform === "linux" ? ["-selection", "clipboard"] : [];
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve6, reject) => {
     const child = spawn3(command, args, { stdio: ["pipe", "ignore", "ignore"] });
     child.on("error", (error) => {
       reject(new CliError("Could not copy login URL to clipboard. Re-run without --clipboard to print the URL.", { cause: error }));
     });
     child.on("close", (code) => {
       if (code === 0) {
-        resolve5();
+        resolve6();
         return;
       }
       reject(new CliError(`Could not copy login URL to clipboard (${command} exited ${code ?? "unknown"}). Re-run without --clipboard to print the URL.`));