@alva-ai/toolkit 0.2.0 → 0.3.1

package/dist/cli.js

@@ -28,9 +28,20 @@ var FsResource = class {
   client;
   /** Returns `ArrayBuffer` for binary files, or parsed JSON for time-series virtual paths. */
   async read(params) {
-    return this.client._request("GET", "/api/v1/fs/read", {
+    const result = await this.client._request("GET", "/api/v1/fs/read", {
       query: { path: params.path, offset: params.offset, size: params.size }
     });
+    if (!(result instanceof ArrayBuffer)) return result;
+    try {
+      const text = new TextDecoder("utf-8", { fatal: true }).decode(result);
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    } catch {
+      return result;
+    }
   }
   /** Write file using JSON body (Mode 2). For text content. */
   async write(params) {
@@ -338,6 +349,55 @@ var SdkDocsResource = class {
   }
 };
 
+// src/resources/skills.ts
+var SkillsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async list() {
+    const res = await this.client._request("GET", "/api/v1/skills", {
+      baseUrl: this.client.arraysBaseUrl,
+      noAuth: true
+    });
+    return { skills: res.data ?? [] };
+  }
+  async summary(params) {
+    const encoded = encodeURIComponent(params.name);
+    const res = await this.client._request(
+      "GET",
+      `/api/v1/skills/${encoded}`,
+      {
+        baseUrl: this.client.arraysBaseUrl,
+        noAuth: true
+      }
+    );
+    const doc = res.data?.[0];
+    if (!doc)
+      throw new Error(`empty skills summary response for "${params.name}"`);
+    return doc;
+  }
+  async endpoint(params) {
+    const encoded = encodeURIComponent(params.name);
+    const res = await this.client._request(
+      "GET",
+      `/api/v1/skills/${encoded}`,
+      {
+        baseUrl: this.client.arraysBaseUrl,
+        noAuth: true,
+        query: { endpoint: params.file }
+      }
+    );
+    const doc = res.data?.[0];
+    if (!doc) {
+      throw new Error(
+        `empty skills endpoint response for "${params.name}" file "${params.file}"`
+      );
+    }
+    return doc;
+  }
+};
+
 // src/resources/comments.ts
 var CommentsResource = class {
   constructor(client) {
@@ -493,11 +553,37 @@ var TradingResource = class {
   }
 };
 
+// src/resources/arraysJwt.ts
+var ArraysJwtResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Idempotently sign-or-renew the Arrays JWT server-side. */
+  async ensure() {
+    this.client._requireAuth();
+    return this.client._request(
+      "POST",
+      "/api/v1/arrays-jwt/ensure"
+    );
+  }
+  /** Report the current Arrays JWT state for the authenticated user. */
+  async status() {
+    this.client._requireAuth();
+    return this.client._request(
+      "GET",
+      "/api/v1/arrays-jwt/status"
+    );
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api-llm.prd.alva.ai";
+var DEFAULT_ARRAYS_BASE_URL = "https://data-tools.prd.space.id";
 var AlvaClient = class {
   baseUrl;
-  token;
+  arraysBaseUrl;
+  viewer_token;
   apiKey;
   _fs;
   _run;
@@ -505,14 +591,17 @@ var AlvaClient = class {
   _release;
   _secrets;
   _sdk;
+  _skills;
   _comments;
   _remix;
   _screenshot;
   _user;
   _trading;
+  _arraysJwt;
   constructor(config) {
     this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
-    this.token = config.token;
+    this.arraysBaseUrl = config.arraysBaseUrl ?? DEFAULT_ARRAYS_BASE_URL;
+    this.viewer_token = config.viewer_token;
     this.apiKey = config.apiKey;
   }
   get fs() {
@@ -533,6 +622,9 @@ var AlvaClient = class {
   get sdk() {
     return this._sdk ??= new SdkDocsResource(this);
   }
+  get skills() {
+    return this._skills ??= new SkillsResource(this);
+  }
   get comments() {
     return this._comments ??= new CommentsResource(this);
   }
@@ -548,17 +640,21 @@ var AlvaClient = class {
   get trading() {
     return this._trading ??= new TradingResource(this);
   }
+  get arraysJwt() {
+    return this._arraysJwt ??= new ArraysJwtResource(this);
+  }
   _requireAuth() {
-    if (!this.token && !this.apiKey) {
+    if (!this.viewer_token && !this.apiKey) {
       throw new AlvaError(
         "UNAUTHENTICATED",
-        "Authentication is required. Pass token or apiKey in the constructor.",
+        "Authentication is required. Pass viewer_token or apiKey in the constructor.",
         401
       );
     }
   }
   async _request(method, path, options) {
-    let url = `${this.baseUrl}${path}`;
+    const baseUrl = options?.baseUrl ?? this.baseUrl;
+    let url = `${baseUrl}${path}`;
     if (options?.query) {
       const params = new URLSearchParams();
       for (const [key, value] of Object.entries(options.query)) {
@@ -572,10 +668,12 @@ var AlvaClient = class {
       }
     }
     const headers = {};
-    if (this.token) {
-      headers.Authorization = `${this.token}`;
-    } else if (this.apiKey) {
-      headers["X-Alva-Api-Key"] = this.apiKey;
+    if (!options?.noAuth) {
+      if (this.viewer_token) {
+        headers["x-Playbook-Viewer"] = this.viewer_token;
+      } else if (this.apiKey) {
+        headers["X-Alva-Api-Key"] = this.apiKey;
+      }
     }
     let fetchBody;
     if (options?.rawBody !== void 0) {
@@ -691,6 +789,7 @@ async function writeConfig(config, deps, profileName = "default") {
   return {
     apiKey: profileData.apiKey,
     baseUrl: profileData.baseUrl,
+    arraysBaseUrl: DEFAULT_ARRAYS_BASE_URL,
     profile: profileName
   };
 }
@@ -710,6 +809,8 @@ function loadConfig(deps) {
   const profileName = parseFlag(argv, "--profile") || env.ALVA_PROFILE || "default";
   const baseUrlFlag = parseFlag(argv, "--base-url");
   const baseUrlEnv = env.ALVA_ENDPOINT;
+  const arraysBaseUrlFlag = parseFlag(argv, "--arrays-endpoint");
+  const arraysBaseUrlEnv = env.ARRAYS_ENDPOINT;
   const apiKeyFlag = parseFlag(argv, "--api-key");
   const apiKeyEnv = env.ALVA_API_KEY;
   let fileProfile = {};
@@ -731,6 +832,7 @@ function loadConfig(deps) {
   return {
     apiKey: apiKeyFlag ?? apiKeyEnv ?? fileProfile.apiKey,
     baseUrl: baseUrlFlag ?? baseUrlEnv ?? fileProfile.baseUrl,
+    arraysBaseUrl: arraysBaseUrlFlag ?? arraysBaseUrlEnv ?? DEFAULT_ARRAYS_BASE_URL,
     profile: profileName
   };
 }
@@ -859,11 +961,48 @@ Waiting for login callback...
   });
 }
 
+// src/cli/postConfigureHooks.ts
+function defaultStderr(s) {
+  process.stderr.write(s);
+}
+function formatTier(t) {
+  const stripped = typeof t === "string" && t.startsWith("SUBSCRIPTION_TIER_") ? t.slice("SUBSCRIPTION_TIER_".length) : String(t);
+  return stripped.toLowerCase();
+}
+function formatExpiry(expiresAt) {
+  return new Date(expiresAt * 1e3).toISOString().slice(0, 10);
+}
+var ensureArraysJwtHook = {
+  name: "ensureArraysJwt",
+  async run(client) {
+    const res = await client.arraysJwt.ensure();
+    const date = formatExpiry(res.expires_at);
+    const tier = formatTier(res.tier);
+    const verb = res.renewed ? "Arrays JWT provisioned" : "Arrays JWT already current";
+    process.stderr.write(`${verb} (expires ${date}, tier: ${tier})
+`);
+  }
+};
+var POST_CONFIGURE_HOOKS = [ensureArraysJwtHook];
+async function runPostConfigureHooks(client, deps) {
+  const hooks = deps?.hooks ?? POST_CONFIGURE_HOOKS;
+  const stderr = deps?.stderr ?? defaultStderr;
+  for (const hook of hooks) {
+    try {
+      await hook.run(client);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      stderr(`warning: post-configure hook "${hook.name}" failed: ${msg}
+`);
+    }
+  }
+}
+
 // src/cli/index.ts
 import * as fs from "fs";
 import * as os2 from "os";
 import * as fsPromises2 from "fs/promises";
-var CLI_VERSION = true ? "0.2.0" : "dev";
+var CLI_VERSION = true ? "0.3.1" : "dev";
 function isVersionOlderThan(a, b) {
   const parse = (v) => {
     if (!v) return null;
@@ -885,24 +1024,27 @@ var HELP_TEXT = `Usage: alva <command> [options]
 
 Commands:
   configure   Save API key and endpoint to a named profile
-  whoami      Verify credentials and show current user info
-  user        User profile operations
+  whoami      Verify credentials and show current identity
+  user        User profile operations (me)
   fs          Filesystem operations (read, write, stat, readdir, mkdir, remove, rename, copy, symlink, readlink, chmod, grant, revoke)
   run         Execute code in the Alva runtime
-  deploy      Cronjob management (create, list, get, update, delete, pause, resume)
+  deploy      Cronjob management (create, list, get, update, delete, pause, resume, runs, run-logs)
   release     Feed and playbook releases (feed, playbook-draft, playbook)
   secrets     Secret management (create, list, get, update, delete)
   sdk         SDK documentation (doc, partitions, partition-summary)
+  skills      Data-skill documentation from the Arrays backend (list, summary, endpoint)
   comments    Playbook comments (create, pin, unpin)
   remix       Save playbook remix lineage
   trading     Trading operations (accounts, portfolio, orders, subscriptions, equity-history, risk-rules, subscribe, unsubscribe, execute, update-risk-rules)
-  auth        Authentication (login via browser)
+  auth        Authentication (login)
   screenshot  Capture a web screenshot as PNG
+  arrays      Arrays backend operations (token ensure, token status)
 
 Global options:
-  --api-key <key>      API key (overrides env and config file)
-  --base-url <url>     API base URL (overrides env and config file)
-  --profile <name>     Named profile to use (default: "default")
+  --api-key <key>        API key (overrides env and config file)
+  --base-url <url>       API base URL (overrides env and config file)
+  --profile <name>       Named profile to use (default: "default")
+  --arrays-endpoint <url>  Arrays backend URL (or ARRAYS_ENDPOINT env; default: https://data-tools.prd.space.id)
   -v, --version        Show CLI version
   --help               Show help (use 'alva <command> --help' for command details)
 
@@ -919,6 +1061,8 @@ var COMMAND_HELP = {
 Save API credentials to ~/.config/alva/config.json (mode 0600).
 After configuring, subsequent commands use the saved key automatically.
 Multiple profiles allow switching between environments (production, staging, etc.).
+Also auto-runs 'alva arrays token ensure' to provision the server-side Arrays JWT
+(soft-fail: a network/auth failure prints a stderr warning but exit stays 0).
 
 Required:
   --api-key <key>      Your Alva API key (starts with "alva_")
@@ -954,6 +1098,9 @@ Verify that your credentials are valid by calling the Alva API. Shows your
 username, subscription tier, and which profile/endpoint is being used.
 Use this after 'alva configure' to confirm everything works.
 
+Output also includes _meta.arrays_jwt (exists, expires_at, renewal_needed,
+tier) when the backend is reachable; the field is omitted on RPC failure.
+
 Examples:
   alva whoami
   alva --profile staging whoami`,
@@ -987,16 +1134,26 @@ Subcommands:
   grant      Grant access permission to a user or group
   revoke     Revoke access permission
 
-Common flags:
-  --path <path>          File or directory path (required for most subcommands)
-  --recursive            Enable recursive operation (readdir, remove)
-  --no-recursive         Disable recursive operation
-  --mkdir-parents        Create parent directories on write (default for write)
-  --no-mkdir-parents     Disable automatic parent directory creation on write
+Subcommand flags:
+  read       --path (required), [--offset <n>], [--size <n>]
+  write      --path (required), --data <text> OR --file <local-path> (one required),
+             [--mkdir-parents | --no-mkdir-parents]
+  stat       --path (required)
+  readdir    --path (required), [--recursive | --no-recursive]
+  mkdir      --path (required)
+  remove     --path (required), [--recursive | --no-recursive]
+  rename     --old-path (required), --new-path (required)
+  copy       --src-path (required), --dst-path (required)
+  symlink    --target-path (required), --link-path (required)
+  readlink   --path (required)
+  chmod      --path (required), --mode <octal> (required)
+  grant      --path (required), --subject <s> (required), --permission <p> (required)
+  revoke     --path (required), --subject <s> (required), --permission <p> (required)
 
 Path conventions:
   ~/...                  Home-relative path (expands to /alva/home/<username>/...)
   /alva/home/alice/...   Absolute path (required for public/unauthenticated reads)
+  Quote tilde paths to prevent shell expansion: --path "~/data" (not --path ~/data).
 
 Time series reads:
   Paths under feed data directories support virtual suffixes:
@@ -1012,21 +1169,23 @@ Grant/revoke subjects:
   user:<id>              Specific user by ID
 
 Examples:
-  alva fs readdir --path ~/
-  alva fs readdir --path ~/data --recursive
-  alva fs read --path ~/data/prices.json
-  alva fs read --path ~/feeds/btc-ema/v1/data/metrics/prices/@last/100
+  alva fs readdir --path "~/"
+  alva fs readdir --path "~/data" --recursive
+  alva fs read --path "~/data/prices.json"
+  alva fs read --path "~/feeds/btc-ema/v1/data/metrics/prices/@last/100"
   alva fs read --path /alva/home/alice/feeds/btc-ema/v1/data/metrics/prices/@last/10
-  alva fs write --path ~/hello.txt --data "Hello, world!"
-  alva fs write --path ~/feeds/my-feed/v1/src/index.js --file ./local-script.js --mkdir-parents
-  alva fs stat --path ~/hello.txt
-  alva fs mkdir --path ~/feeds/my-feed/v1/src
-  alva fs remove --path ~/old-folder --recursive
-  alva fs rename --old-path ~/a.txt --new-path ~/b.txt
-  alva fs copy --src-path ~/a.txt --dst-path ~/b.txt
-  alva fs chmod --path ~/script.js --mode 755
-  alva fs grant --path ~/feeds/btc-ema --subject "special:user:*" --permission read
-  alva fs revoke --path ~/feeds/btc-ema --subject "special:user:*" --permission read`,
+  alva fs write --path "~/hello.txt" --data "Hello, world!"
+  alva fs write --path "~/feeds/my-feed/v1/src/index.js" --file ./local-script.js --mkdir-parents
+  alva fs stat --path "~/hello.txt"
+  alva fs mkdir --path "~/feeds/my-feed/v1/src"
+  alva fs remove --path "~/old-folder" --recursive
+  alva fs rename --old-path "~/a.txt" --new-path "~/b.txt"
+  alva fs copy --src-path "~/a.txt" --dst-path "~/b.txt"
+  alva fs chmod --path "~/script.js" --mode 755
+  alva fs grant --path "~/feeds/btc-ema" --subject "special:user:*" --permission read
+  alva fs revoke --path "~/feeds/btc-ema" --subject "special:user:*" --permission read
+  alva fs symlink --target-path "~/real-file.txt" --link-path "~/my-link.txt"
+  alva fs readlink --path "~/my-link.txt"`,
   run: `Usage: alva run [options]
 
 Execute JavaScript code in the Alva V8 runtime. Provide either inline code
@@ -1067,8 +1226,8 @@ Constraints:
 Examples:
   alva run --code "1 + 2 + 3;"
   alva run --code "JSON.stringify(require('env').args);" --args '{"symbol":"BTC"}'
-  alva run --entry-path ~/feeds/my-feed/v1/src/index.js
-  alva run --entry-path ~/tasks/analyze/src/index.js --args '{"symbol":"NVDA","limit":50}'
+  alva run --entry-path "~/feeds/my-feed/v1/src/index.js"
+  alva run --entry-path "~/tasks/analyze/src/index.js" --args '{"symbol":"NVDA","limit":50}'
   alva run --local-file ./my-script.js --args '{"symbol":"BTC"}'`,
   deploy: `Usage: alva deploy <subcommand> [options]
 
@@ -1083,6 +1242,8 @@ Subcommands:
   delete     Delete a cronjob
   pause      Pause a running cronjob
   resume     Resume a paused cronjob
+  runs       List runs for a cronjob (cursor-paginated)
+  run-logs   Get stdout/stderr logs for a single cronjob run
 
 Create flags:
   --name <name>          Cronjob name (required, 1-63 lowercase alphanumeric/hyphens)
@@ -1099,6 +1260,15 @@ List flags:
 Get/Update/Delete/Pause/Resume flags:
   --id <id>              Cronjob ID (required)
 
+Runs flags:
+  --id <id>              Cronjob ID (required)
+  --first <n>            Max results per page
+  --cursor <cursor>      Pagination cursor from previous response
+
+Run-logs flags:
+  --id <id>              Cronjob ID (required)
+  --run-id <id>          Run ID (required)
+
 Name format: 1-63 lowercase alphanumeric or hyphens, no leading/trailing hyphens.
   Valid:   btc-ema-update, my-strategy-1
   Invalid: BTC EMA, -my-job-, my_job
@@ -1110,8 +1280,8 @@ Recommended cron schedules:
   "0 0 * * *"      Daily at midnight (end-of-day summaries)
 
 Examples:
-  alva deploy create --name btc-ema --path ~/feeds/btc-ema/v1/src/index.js --cron "0 */4 * * *"
-  alva deploy create --name alert --path ~/feeds/alert/v1/src/index.js --cron "*/5 * * * *" --push-notify --args '{"threshold":100}'
+  alva deploy create --name btc-ema --path "~/feeds/btc-ema/v1/src/index.js" --cron "0 */4 * * *"
+  alva deploy create --name alert --path "~/feeds/alert/v1/src/index.js" --cron "*/5 * * * *" --push-notify --args '{"threshold":100}'
   alva deploy list
   alva deploy list --limit 10
   alva deploy get --id 42
@@ -1147,7 +1317,7 @@ Playbook-draft flags:
   --name <name>              URL-safe playbook name, unique per user (required)
   --display-name <name>      Human-readable title, max 40 chars (required)
   --feeds <json>             JSON array of {feed_id, feed_major?} (required)
-  --changelog <text>         Release changelog (required)
+  --changelog <text>         Release changelog
   --description <text>       Playbook description
   --trading-symbols <json>   JSON array of tickers, e.g. '["BTC","ETH"]' (max 50)
 
@@ -1215,20 +1385,37 @@ Flags:
   --partition <name>     Partition name for 'partition-summary' (required)
 
 Key partitions:
-  spot_market_price_and_volume         Spot OHLCV for crypto and equities
-  crypto_futures_data                  Perpetual futures, funding rates, OI
-  crypto_technical_metrics             MA, RSI, MACD, MVRV, SOPR, NUPL (20 modules)
-  equity_fundamentals                  Income, balance sheet, PE, ROE (31 modules)
-  equity_estimates_and_targets         Analyst targets, consensus estimates
-  equity_ownership_and_flow            Insider trades, senator trading, institutions
-  macro_and_economics_data             CPI, GDP, Treasury rates, VIX (20 modules)
+  feed_widgets                             Per-handle/channel rolling subscriptions
+  unified_search                           Web search and URL scraping tools (X/Grok, Google, Brave, serper, decodo)
   technical_indicator_calculation_helpers  50+ pure calculators (RSI, MACD, Bollinger)
 
 Examples:
   alva sdk partitions
-  alva sdk partition-summary --partition spot_market_price_and_volume
-  alva sdk doc --name "@arrays/crypto/ohlcv:v1.0.0"
-  alva sdk doc --name "@arrays/data/stock/ohlcv:v1.0.0"`,
+  alva sdk partition-summary --partition feed_widgets
+  alva sdk doc --name "@arrays/data/widget-scrap/twitter:v1.0.0"
+  alva sdk doc --name "@arrays/data/search/search-grok-x:v1.0.0"`,
+  skills: `Usage: alva skills <subcommand> [options]
+
+Browse the Arrays backend's data-skill documentation. These endpoints are
+public \u2014 no Alva credentials required.
+
+Subcommands:
+  list       List all available data skills
+  summary    Get the endpoints table for a skill (requires --name)
+  endpoint   Get full documentation for a specific endpoint (requires --name and --file)
+
+Flags:
+  --name <name>      Skill name (required for summary and endpoint)
+  --file <file>      Endpoint file name from the "File" column of 'skills summary' (required for endpoint)
+
+Global override:
+  --arrays-endpoint <url>   Arrays backend URL (or ARRAYS_ENDPOINT env)
+                            Default: https://data-tools.prd.space.id
+
+Examples:
+  alva skills list
+  alva skills summary --name <skill>
+  alva skills endpoint --name <skill> --file <endpoint-file>`,
   comments: `Usage: alva comments <subcommand> [options]
 
 Manage comments on Alva playbooks. Supports top-level comments and threaded
@@ -1348,7 +1535,20 @@ Examples:
   alva trading subscribe --account-id acc_123 --source-username alice --source-feed btc-signals --playbook-id pb_1 --playbook-version v1.0.0
   alva trading unsubscribe --subscription-id sub_456
   alva trading execute --account-id acc_123 --signal '{"symbol":"BTC","side":"buy","qty":0.1}' --dry-run
-  alva trading update-risk-rules --max-single-order-value 10000 --max-single-order-enabled true --max-daily-turnover-value 50000 --max-daily-turnover-enabled true --max-daily-orders-value 100 --max-daily-orders-enabled true`
+  alva trading update-risk-rules --max-single-order-value 10000 --max-single-order-enabled true --max-daily-turnover-value 50000 --max-daily-turnover-enabled true --max-daily-orders-value 100 --max-daily-orders-enabled true`,
+  arrays: `Usage: alva arrays token <subcommand>
+
+Manage the Arrays JWT used by sandbox scripts (secret.loadPlaintext('ARRAYS_JWT')).
+The JWT is stored server-side as a jagent secret; the CLI never receives the
+token itself. 'alva configure' auto-runs 'token ensure' after saving credentials.
+
+Subcommands:
+  token ensure    Provision or refresh the Arrays JWT (idempotent)
+  token status    Show Arrays JWT presence, expiry, tier, and renewal hint
+
+Examples:
+  alva arrays token ensure
+  alva arrays token status`
 };
 async function handleConfigure(args, deps) {
   const flags = parseFlags2(args.slice(1));
@@ -1373,6 +1573,15 @@ async function handleConfigure(args, deps) {
     readFile: (path) => fsPromises2.readFile(path, "utf-8")
   };
   const result = await writeConfig(configInput, writeDeps, profileName);
+  const client = new AlvaClient(baseUrl ? { apiKey, baseUrl } : { apiKey });
+  const runHooks = writeDeps.runHooks ?? ((c) => runPostConfigureHooks(c));
+  try {
+    await runHooks(client);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr?.write?.(`warning: post-configure hooks crashed: ${msg}
+`);
+  }
   return {
     status: "configured",
     apiKey: result.apiKey,
@@ -1458,12 +1667,21 @@ async function dispatch(client, args, meta) {
     const user = await client.user.me();
     const record = user;
     const version = meta?.cliVersion ?? CLI_VERSION;
+    let arraysJwtStatus;
+    try {
+      arraysJwtStatus = await client.arraysJwt.status();
+    } catch {
+    }
+    const metaBlock = {
+      profile: meta?.profile ?? "default",
+      endpoint: meta?.baseUrl ?? client.baseUrl
+    };
+    if (arraysJwtStatus !== void 0) {
+      metaBlock.arrays_jwt = arraysJwtStatus;
+    }
     const result = {
       ...record,
-      _meta: {
-        profile: meta?.profile ?? "default",
-        endpoint: meta?.baseUrl ?? client.baseUrl
-      }
+      _meta: metaBlock
     };
     const minVersion = record.toolkit_min_version;
     if (typeof minVersion === "string" && version && version !== "dev" && isVersionOlderThan(version, minVersion)) {
@@ -1674,11 +1892,7 @@ async function dispatch(client, args, meta) {
               requireFlag(flags, "feeds", "release playbook-draft")
             ),
             trading_symbols: flags["trading-symbols"] ? jsonParse(flags["trading-symbols"]) : void 0,
-            changelog: requireFlag(
-              flags,
-              "changelog",
-              "release playbook-draft"
-            )
+            changelog: flags["changelog"]
           });
         case "playbook":
           return client.release.playbook({
@@ -1748,6 +1962,28 @@ async function dispatch(client, args, meta) {
           );
       }
     }
+    case "skills": {
+      if (!subcommand)
+        throw new CliUsageError("Missing subcommand for skills", "skills");
+      switch (subcommand) {
+        case "list":
+          return client.skills.list();
+        case "summary":
+          return client.skills.summary({
+            name: requireFlag(flags, "name", "skills summary")
+          });
+        case "endpoint":
+          return client.skills.endpoint({
+            name: requireFlag(flags, "name", "skills endpoint"),
+            file: requireFlag(flags, "file", "skills endpoint")
+          });
+        default:
+          throw new CliUsageError(
+            `Unknown subcommand: skills ${subcommand}`,
+            "skills"
+          );
+      }
+    }
     case "comments": {
       if (!subcommand)
         throw new CliUsageError("Missing subcommand for comments", "comments");
@@ -1786,6 +2022,30 @@ async function dispatch(client, args, meta) {
         },
         parents: jsonParse(requireFlag(flags, "parents", "remix"))
       });
+    case "arrays": {
+      if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        return { _help: true, text: COMMAND_HELP.arrays };
+      }
+      if (subcommand === "token") {
+        const leaf = args[2];
+        if (!leaf || leaf === "--help" || leaf === "-h") {
+          return { _help: true, text: COMMAND_HELP.arrays };
+        }
+        switch (leaf) {
+          case "ensure":
+            return client.arraysJwt.ensure();
+          case "status":
+            return client.arraysJwt.status();
+          default:
+            throw new Error(
+              `Unknown subcommand 'arrays token ${leaf}'. Use 'alva arrays --help' for usage.`
+            );
+        }
+      }
+      throw new Error(
+        `Unknown subcommand 'arrays ${subcommand}'. Use 'alva arrays --help' for usage.`
+      );
+    }
     case "screenshot": {
       const outFile = requireFlag(flags, "out", "screenshot");
       const result = await client.screenshot.capture({
@@ -1794,6 +2054,12 @@ async function dispatch(client, args, meta) {
         xpath: flags["xpath"]
       });
       const buf = Buffer.from(result);
+      if (buf.length === 0) {
+        throw new CliUsageError(
+          "Screenshot service returned empty response (0 bytes). The service may be overloaded \u2014 retry in a few seconds.",
+          "screenshot"
+        );
+      }
       fs.writeFileSync(outFile, buf);
       return { written: outFile, bytes: buf.length };
     }
@@ -1917,6 +2183,27 @@ async function dispatch(client, args, meta) {
       throw new CliUsageError(`Unknown command: '${group}'`);
   }
 }
+function stripGlobalFlags(argv) {
+  const GLOBAL_FLAGS = [
+    "--api-key",
+    "--base-url",
+    "--profile",
+    "--arrays-endpoint"
+  ];
+  const result = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (GLOBAL_FLAGS.includes(a)) {
+      i++;
+      continue;
+    }
+    if (GLOBAL_FLAGS.some((f) => a.startsWith(`${f}=`))) {
+      continue;
+    }
+    result.push(a);
+  }
+  return result;
+}
 async function main() {
   try {
     const rawArgs = process.argv.slice(2);
@@ -1959,20 +2246,10 @@ async function main() {
     });
     const client = new AlvaClient({
       apiKey: config.apiKey,
-      baseUrl: config.baseUrl
+      baseUrl: config.baseUrl,
+      arraysBaseUrl: config.arraysBaseUrl
     });
-    const cleanArgs = [];
-    for (let i = 0; i < rawArgs.length; i++) {
-      const a = rawArgs[i];
-      if (a === "--api-key" || a === "--base-url" || a === "--profile") {
-        i++;
-        continue;
-      }
-      if (a.startsWith("--api-key=") || a.startsWith("--base-url=") || a.startsWith("--profile=")) {
-        continue;
-      }
-      cleanArgs.push(a);
-    }
+    const cleanArgs = stripGlobalFlags(rawArgs);
     const result = await dispatch(client, cleanArgs, {
       profile: config.profile,
       baseUrl: config.baseUrl,
@@ -1993,6 +2270,10 @@ async function main() {
       process.stdout.write(Buffer.from(result));
       return;
     }
+    if (typeof result === "string") {
+      process.stdout.write(result);
+      return;
+    }
     if (result !== void 0) {
       process.stdout.write(JSON.stringify(result, null, 2) + "\n");
     }
@@ -2030,6 +2311,7 @@ export {
   CLI_VERSION,
   dispatch,
   handleConfigure,
-  isVersionOlderThan
+  isVersionOlderThan,
+  stripGlobalFlags
 };
 //# sourceMappingURL=cli.js.map