@knowttl/artium-axi 0.0.25 → 0.0.27

package/README.md

@@ -133,7 +133,7 @@ Tool output limits vary; `--full` restores supported text within byte/time budge
 | Artium exit | Meaning |
 | --- | --- |
 | 0 | Success |
-| 1 | Authentication, server or transport failure |
+| 1 | Authentication, server, transport or local CLI failure |
 | 2 | Usage or configuration error |
 
 See [output behavior](docs/client-reference.md#toon-output-behavior) and the generated [error catalogue](docs/errors.md).
@@ -142,6 +142,7 @@ See [output behavior](docs/client-reference.md#toon-output-behavior) and the gen
 
 | Symptom | Next step |
 | --- | --- |
+| A tool call failed | Follow the tool's help and keep the stderr `request_id` for an administrator; see [troubleshooting a failed tool call](docs/runbook.md#troubleshoot-a-failed-tool-call). |
 | `CLIENT_CONFIG_INVALID` | Set the HTTPS URL and a readable CA file if needed, then sign in. |
 | `PASSWORD_CHANGE_REQUIRED` | Run `artium-axi passwd`, then sign in again. |
 | `CLI_OUTDATED` | Follow [installation-specific update guidance](docs/client-reference.md#verified-client). |

package/bin/artium-axi.mjs

@@ -6,7 +6,6 @@ var __export = (target, all) => {
 };
 
 // src/cli/main.ts
-import { randomUUID as randomUUID5 } from "node:crypto";
 import { homedir as homedir3 } from "node:os";
 import { resolve as resolve4, relative, sep, isAbsolute as isAbsolute2 } from "node:path";
 
@@ -19740,6 +19739,7 @@ var definitions = {
   UPSTREAM_AUTH_FAILED: { status: 503, message: "The upstream service rejected the credential.", next: "Ask an administrator to check the provider code, identity, secret expiry and permissions, then test again." },
   UPSTREAM_NETWORK_FAILED: { status: 503, message: "The upstream service could not be reached.", next: "Ask an administrator to check DNS, routing, firewall rules and the diagnostic host and stage." },
   UPSTREAM_TLS_FAILED: { status: 503, message: "The upstream certificate could not be verified.", next: "Ask an administrator to check the host, certificate chain and trusted CA configuration." },
+  UPSTREAM_RESPONSE_INVALID: { status: 503, message: "The upstream service returned a response the tool could not accept.", next: "Ask an administrator to inspect the diagnostic message and hint, check the service endpoint and API compatibility, then test again." },
   TOOL_REJECTED_INPUT: { status: 503, message: "The tool rejected its configuration or arguments.", next: "Ask an administrator to correct the field or combination named by the tool and test again." },
   TOOL_FAILED: { status: 503, message: "The tool exited unsuccessfully.", next: "Ask an administrator to inspect the diagnostic message and hint from Test credential." },
   INVALID_INPUT: { status: 400, message: "The request input is invalid.", next: "Check the request fields and content type." },
@@ -21365,6 +21365,8 @@ var auditCursorSchema = external_exports.string().max(50).regex(/^\d{1,16}:\d{1,
   return [ceiling, time3, id].every(Number.isSafeInteger) && ceiling > 0 && id > 0 && id <= ceiling && time3 <= 864e13;
 });
 var auditFiltersSchema = external_exports.strictObject({
+  requestId: external_exports.string().min(1).max(100).optional(),
+  failed: external_exports.enum(["0", "1"]).optional(),
   user: external_exports.string().min(1).max(256).optional(),
   tool: toolSchema.optional(),
   event: external_exports.string().min(1).max(100).optional(),
@@ -21507,7 +21509,7 @@ var nativeSettingsSchemas = {
   })
 };
 var diagnosticSchema = external_exports.strictObject({
-  stage: external_exports.enum(["configuration", "token acquisition", "DNS", "TCP", "TLS", "authentication", "tool run"]),
+  stage: external_exports.enum(["configuration", "token acquisition", "DNS", "TCP", "TLS", "authentication", "response", "tool run"]),
   message: external_exports.string().max(4096),
   toolCode: external_exports.string().max(80).optional(),
   providerCode: external_exports.string().max(80).optional(),
@@ -22012,7 +22014,8 @@ var toolsResponseSchema = external_exports.strictObject({
     name: toolSchema,
     version: external_exports.string(),
     readOnly: external_exports.boolean().default(true),
-    status: external_exports.enum(["unconfigured", "unknown", "checking", "ok", "error", "disabled"])
+    status: external_exports.enum(["unconfigured", "unknown", "checking", "ok", "error", "disabled"]),
+    errorCode: healthSchema.shape.errorCode.optional()
   }))
 });
 var inputFileSchema = external_exports.strictObject({
@@ -22068,7 +22071,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "artium-axi",
-  version: "0.0.25",
+  version: "0.0.27",
   private: true,
   license: "MIT",
   type: "module",
@@ -22321,7 +22324,9 @@ var Client = class {
     return this.storedSessions;
   }
   certificateVerified = false;
+  requestId;
   async request(path, method, input2, token, bytes = false, headers = {}) {
+    this.requestId = void 0;
     this.certificateVerified = false;
     let ca;
     try {
@@ -22341,6 +22346,8 @@ var Client = class {
         signal: AbortSignal.any([controller.signal, this.cancellation.signal]),
         headers: { ...headers, "x-artium-cli-version": cliVersion, ...token ? { authorization: `Bearer ${token}` } : {}, ...body ? { "content-type": "application/json" } : {} }
       }, (response) => {
+        const requestId = response.headers["x-artium-request-id"];
+        if (typeof requestId === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(requestId)) this.requestId = requestId;
         if (response.statusCode >= 300 && response.statusCode < 400) {
           response.destroy();
           reject(new ArtiumError("INVALID_RESPONSE", "Authenticated redirects are refused."));
@@ -22556,13 +22563,13 @@ var falcon_axi_default = {
   generatedBy: "scripts/falcon-inventory.mjs",
   tool: "falcon-axi",
   repository: "https://github.com/knowttl/falcon-axi.git",
-  tag: "v0.8.2",
-  commit: "2b1fe5d7550a341277e2f3c7a17b4629914b084c",
-  version: "0.8.2",
+  tag: "v0.8.3",
+  commit: "6d5b5a70137b84407fa4b844f4d90009a90c6629",
+  version: "0.8.3",
   distribution: {
-    filename: "falcon_axi-0.8.2-py3-none-any.whl",
-    sha256: "8546b601ec69da9ca0bfe2ac323765d12b11d1842abb1b7421a7ccccbe200c16",
-    provenance: "https://pypi.org/integrity/falcon-axi/0.8.2/falcon_axi-0.8.2-py3-none-any.whl/provenance"
+    filename: "falcon_axi-0.8.3-py3-none-any.whl",
+    sha256: "37d04718728493cff0ec6547d8d6345bb32a576a33348526feddb602c9bdb5b1",
+    provenance: "https://pypi.org/integrity/falcon-axi/0.8.3/falcon_axi-0.8.3-py3-none-any.whl/provenance"
   },
   skillSha256: "893c2ad3a474d76734117e4e46a91b19278f1fdeafaf1b69189be4a09da333b1",
   parser: {
@@ -44060,8 +44067,8 @@ var hybrid_axi_default = {
 var beyondtrust_axi_default = {
   generatedBy: "scripts/beyondtrust-inventory.mjs",
   tool: "beyondtrust-axi",
-  version: "0.1.1",
-  integrity: "sha512-B5Nc4eOIaAlceGRE8FfPbUMuwnedlKfzBYjGeozjqmAD1LVHYJBspQXiJuj7fCtOlUd9ea/axisM3RH82A6Wjg==",
+  version: "0.1.4",
+  integrity: "sha512-A6vBEpopJdcgsBozBIrnCMD891Saa9gwKTD8mH7XdGoi8zasKspY3uhmaw4fNUoL3898oT0EcE3X6Eq8tOrJHw==",
   parserEvidence: "Published catalogue and reviewed native parsers, write coordinator, delete gates and download contracts",
   sources: [
     {
@@ -44070,7 +44077,7 @@ var beyondtrust_axi_default = {
     },
     {
       path: "dist/src/cli.js",
-      sha256: "3fc44bbbba5bb266e40b13e77d0bb61f356b169f9a67e69cec4ca65fe4919d03"
+      sha256: "78171b922ce7be6da474c9b82a998dc93505ce6e3841f4a1450d8e3677b4c910"
     },
     {
       path: "dist/src/computer-writes.js",
@@ -44094,7 +44101,7 @@ var beyondtrust_axi_default = {
     },
     {
       path: "dist/src/jit-writes.js",
-      sha256: "8f8d46b549ebb9474108a5b9e15088d61822ae421452a9f1d482840c85aec7f3"
+      sha256: "b9c6df9b9062ff9d8b3e6ae00dcc6a5147a75c30d6d5775b9e7b9e3092511a7a"
     },
     {
       path: "dist/src/policy-writes.js",
@@ -44114,11 +44121,15 @@ var beyondtrust_axi_default = {
     },
     {
       path: "dist/src/resource-reads.js",
-      sha256: "28774772d3f2720324ffa8bf77580bcca0c922f2496d4d426de3922543680713"
+      sha256: "52e0d50b351fa8464182aed4bc96a0c1501e19c14634ee80a4e2e15ac1608c1a"
+    },
+    {
+      path: "dist/src/response-diagnostics.js",
+      sha256: "7acea5c3133ebf8ca5b54aa5122ef7996ff183482c384c086eb4efdf709d140d"
     },
     {
       path: "dist/src/transport.js",
-      sha256: "9f2d93ffc01016d32782ad183580ecbaa9c5c799c1c5b559de2c829d83bdeb7a"
+      sha256: "89b35e4fcb2b9c25fb496fc7037d9e3123d3006737c64691eb17e597b8216806"
     },
     {
       path: "dist/src/windows-download.js",
@@ -44141,11 +44152,15 @@ var beyondtrust_axi_default = {
     ],
     properties: {
       clientId: {
+        title: "Client ID",
+        description: "The PM Cloud API account client ID.",
         type: "string",
         minLength: 1,
         pattern: "\\S"
       },
       clientSecret: {
+        title: "Client secret",
+        description: "An environment variable or absolute file SecretRef for the API account client secret; never an inline secret. Defaults to BEYONDTRUST_AXI_CLIENT_SECRET.",
         $ref: "#/$defs/secretRef",
         "x-secret": true,
         default: {
@@ -44153,6 +44168,8 @@ var beyondtrust_axi_default = {
         }
       },
       downloads: {
+        title: "Download permissions",
+        description: "Set allow to true to permit raw-byte downloads from a named file profile to a new private destination file. Downloads are disabled by default.",
         type: "object",
         additionalProperties: false,
         required: [
@@ -44168,6 +44185,8 @@ var beyondtrust_axi_default = {
         }
       },
       writes: {
+        title: "Write permissions",
+        description: "Set allowWrites and list exact operations to permit writes from a named file profile. Deletes also require allowDeletes. Writes and deletes are disabled by default.",
         type: "object",
         additionalProperties: false,
         required: [
@@ -44197,6 +44216,8 @@ var beyondtrust_axi_default = {
         }
       },
       host: {
+        title: "PM Cloud API host",
+        description: "The PM Cloud API host as a lowercase DNS name in the documented <organization>-services.pm.beyondtrustcloud.com form, ending in .beyondtrustcloud.com, with no scheme, port or path.",
         type: "string",
         maxLength: 253,
         pattern: "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+beyondtrustcloud\\.com(?![\\s\\S])"
@@ -44235,7 +44256,7 @@ var beyondtrust_axi_default = {
       }
     }
   },
-  skillSha256: "7fed424c9547defcf4f9d2920358bd5f26a60b12aa46b817e7126053de36c881",
+  skillSha256: "242e35d3479e70d8e2f624d53480db82c110fdc441577239e8d23a8756f3eb6b",
   nativeWriteSettings: {
     supportedOperations: [
       "admin-request.create",
@@ -44410,7 +44431,7 @@ var beyondtrust_axi_default = {
         limit: "Maximum rows, 1-1000 (default: 50)",
         all: "Read up to 1000 rows within 10 requests, 60 seconds and 8 MiB",
         cursor: "Resume an opaque cursor with the same profile, command and filters",
-        sort: "Sort property and order, e.g. name:asc (default: created:asc)",
+        sort: "Sort property and order, e.g. name:asc (default: API order)",
         decision: "Filter Decision (string)",
         "created-on": "Filter CreatedOn (string)",
         "active-only": "Filter ActiveOnly (boolean)",
@@ -44546,7 +44567,7 @@ var beyondtrust_axi_default = {
         limit: "Maximum rows, 1-1000 (default: 50)",
         all: "Read up to 1000 rows within 10 requests, 60 seconds and 8 MiB",
         cursor: "Resume an opaque cursor with the same profile, command and filters",
-        sort: "Sort property and order, e.g. name:asc (default: created:asc)",
+        sort: "Sort property and order, e.g. name:asc (default: API order)",
         "ticket-id": "Filter TicketId (string)",
         user: "Filter User (string)",
         "computer-name": "Filter ComputerName (string)",
@@ -44612,7 +44633,7 @@ var beyondtrust_axi_default = {
         limit: "Maximum rows, 1-1000 (default: 50)",
         all: "Read up to 1000 rows within 10 requests, 60 seconds and 8 MiB",
         cursor: "Resume an opaque cursor with the same profile, command and filters",
-        sort: "Sort property and order, e.g. name:asc (default: created:asc)",
+        sort: "Sort property and order, e.g. name:asc (default: API order)",
         decision: "Filter Decision (string)",
         "created-on": "Filter CreatedOn (string)",
         "active-only": "Filter ActiveOnly (boolean)",
@@ -45062,7 +45083,7 @@ var beyondtrust_axi_default = {
         limit: "Maximum rows, 1-1000 (default: 50)",
         all: "Read up to 1000 rows within 10 requests, 60 seconds and 8 MiB",
         cursor: "Resume an opaque cursor with the same profile, command and filters",
-        sort: "Sort property and order, e.g. name:asc (default: created:asc)",
+        sort: "Sort property and order, e.g. name:asc (default: API order)",
         id: "Filter Id (string)",
         name: "Filter Name (string)",
         description: "Filter Description (string)",
@@ -45788,7 +45809,7 @@ var beyondtrust_axi_default = {
         limit: "Maximum rows, 1-1000 (default: 50)",
         all: "Read up to 1000 rows within 10 requests, 60 seconds and 8 MiB",
         cursor: "Resume an opaque cursor with the same profile, command and filters",
-        sort: "Sort property and order, e.g. name:asc (default: created:asc)",
+        sort: "Sort property and order, e.g. name:asc (default: API order)",
         "email-address": "Filter EmailAddress (string)",
         "role-id": "Filter RoleId (string)",
         "permission-id": "Filter PermissionId (string)",
@@ -45858,13 +45879,13 @@ var beyondtrust_axi_default = {
 var checkpoint_axi_default = {
   generatedBy: "scripts/checkpoint-inventory.mjs",
   tool: "checkpoint-axi",
-  version: "0.1.1",
-  integrity: "sha512-xkVncU3PYUeGFD5vIMp/lT9JAsTsSaCTVF+dEFYye1iSDkjPjuHJDHnZ8BquT3ClHw9bcBWdLAnEtJRPSVimtg==",
+  version: "0.1.4",
+  integrity: "sha512-f+ipm5OeIgeOXY1MnTaU3sWE/v0Ay44XNOKHY2gifdEz08nkDe8I5vUbYewcUlxMawYWFoGfmF23tV22anxVng==",
   parserEvidence: "Published catalogue, fixed regional map and reviewed native parsers, write coordinator and download contracts",
   sources: [
     {
       path: "dist/src/catalogue.js",
-      sha256: "59b9568b614a101e2746a8275768c238ba8eb7166185119875a40f7eac191f7a"
+      sha256: "fbac0730e6c3744a63c072b8e5243c1d668fbc7952398be80387b073f307dad6"
     },
     {
       path: "dist/src/cli.js",
@@ -45884,7 +45905,7 @@ var checkpoint_axi_default = {
     },
     {
       path: "dist/src/local-commands.js",
-      sha256: "ed9c39e204d42f45ae3c5b8008bf1c719d88f8e7214168f68de4d15921e35299"
+      sha256: "0d2e310373850e04f96135f910e179e5014dd8050269ff5df0eb97c07d8478ce"
     },
     {
       path: "dist/src/private-file.js",
@@ -45892,11 +45913,11 @@ var checkpoint_axi_default = {
     },
     {
       path: "dist/src/profiles.js",
-      sha256: "db013b041bb6302993d7045fe3bd411bbd1a3593b5b2a84a3d8411645f55d3e6"
+      sha256: "8032b342fa9bc8492f436015dff09c41cddbb394d62305662c46007d6f541c8f"
     },
     {
       path: "dist/src/reads.js",
-      sha256: "02a5478edb3d44ab51ea300095794abc69d9e4a353060af4faed0d6e4ce592a7"
+      sha256: "639ad32c60f06830905b7be34ed853abef64bb79a56dd0211846a1cc21855c1f"
     },
     {
       path: "dist/src/redact.js",
@@ -45906,9 +45927,13 @@ var checkpoint_axi_default = {
       path: "dist/src/regions.js",
       sha256: "44288abe19a68fa672bc04ad167141717aed5c3a333b2420b14ee68e13abee78"
     },
+    {
+      path: "dist/src/response-invalid.js",
+      sha256: "323428f95087fec84e36dab86c7a64ecad69f43e9188f6c6425b64498dac6b5c"
+    },
     {
       path: "dist/src/transport.js",
-      sha256: "7beb28cc283e876db4f6aeaf5c308280e1fce482c20c19dd9924e29985e54e56"
+      sha256: "241eff8feb3addcd5ea1d099e31b101f956ab5f34fe49117f0922ddcdcd63f78"
     },
     {
       path: "dist/src/write-exceptions.js",
@@ -45935,6 +45960,8 @@ var checkpoint_axi_default = {
     ],
     properties: {
       region: {
+        title: "Region",
+        description: "Required region code for your tenant's regional gateway: us, eu, ca, au, uk, uae or in. Obtain it from your tenant administrator. There is no default; URLs are not accepted.",
         type: "string",
         enum: [
           "us",
@@ -45947,11 +45974,15 @@ var checkpoint_axi_default = {
         ]
       },
       clientId: {
+        title: "Client ID",
+        description: "Required non-blank API client ID from your tenant's API credentials. There is no default.",
         type: "string",
         minLength: 1,
         pattern: "\\S"
       },
       clientSecret: {
+        title: "Client secret reference",
+        description: "Reference the environment variable or absolute private file containing your API client secret, never the secret itself. If omitted, reads CHECKPOINT_AXI_CLIENT_SECRET; a missing or blank secret prevents authentication.",
         $ref: "#/$defs/secretRef",
         "x-secret": true,
         default: {
@@ -45959,17 +45990,26 @@ var checkpoint_axi_default = {
         }
       },
       saas: {
+        title: "SaaS application name",
+        description: "One non-blank SaaS application name for the tenant, not a gateway, host or authentication URL; slash (/) is not allowed. Obtain the exact API application name from your tenant administrator or Check Point support. If omitted, defaults to office365_emails, selecting Microsoft 365 email; supply the appropriate name for another application. A profile takes one value, while --saas on event list accepts a comma-separated list.",
         type: "string",
         minLength: 1,
         pattern: "\\S",
+        not: {
+          pattern: "/"
+        },
         default: "office365_emails"
       },
       scope: {
+        title: "Download scope",
+        description: "Download scope value supplied by your tenant administrator or Check Point support for the intended download. Use printable ASCII with no spaces (characters ! through ~); comma-separated values are sent verbatim. There is no default: omitted means unset, so email download fails because it requires the profile scope as its scopes header. Attachment download uses this only as the default scope query; --scope overrides it, and neither supplied means no scope query. Tenant scope authorization and the relationship between these selectors remain unverified; do not guess a value.",
         type: "string",
         minLength: 1,
-        pattern: "\\S"
+        pattern: "^[!-~]+$"
       },
       downloads: {
+        title: "Download permission",
+        description: "Separate file-profile download opt-in. If omitted, downloads are disabled. Environment profiles cannot enable downloads.",
         type: "object",
         additionalProperties: false,
         required: [
@@ -45980,11 +46020,15 @@ var checkpoint_axi_default = {
         },
         properties: {
           allow: {
+            title: "Allow downloads",
+            description: "Set true to permit download commands; each command still requires a new private output file.",
             type: "boolean"
           }
         }
       },
       writes: {
+        title: "Write permissions",
+        description: "File-profile write opt-in and exact operation allow-list. If omitted, writes are disabled with no allowed operations. Forced read-only always wins.",
         type: "object",
         additionalProperties: false,
         required: [
@@ -45997,9 +46041,13 @@ var checkpoint_axi_default = {
         },
         properties: {
           allowWrites: {
+            title: "Allow writes",
+            description: "Set true to permit listed operations, subject to preview, exact confirmation and durable redacted intent.",
             type: "boolean"
           },
           operations: {
+            title: "Allowed write operations",
+            description: "Exact operation names to allow, such as email.quarantine. An empty list permits no writes.",
             type: "array",
             items: {
               type: "string",
@@ -46020,6 +46068,8 @@ var checkpoint_axi_default = {
             ],
             properties: {
               env: {
+                title: "Secret environment variable",
+                description: "Name of the environment variable holding the secret, such as CHECKPOINT_AXI_CLIENT_SECRET. Use letters, digits and underscores, starting with a letter or underscore.",
                 type: "string",
                 pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
               }
@@ -46033,6 +46083,8 @@ var checkpoint_axi_default = {
             ],
             properties: {
               file: {
+                title: "Secret file path",
+                description: "Absolute path to a private UTF-8 file holding the secret. Symlinks and insecure permissions are rejected; a leading BOM and trailing whitespace are removed from its content.",
                 type: "string",
                 pattern: "^(?:/|[A-Za-z]:[\\\\/])"
               }
@@ -46051,7 +46103,7 @@ var checkpoint_axi_default = {
     uae: "https://cloudinfra-gw.me.portal.checkpoint.com",
     in: "https://cloudinfra-gw.in.portal.checkpoint.com"
   },
-  skillSha256: "b64e7d373d92331cf653ef4478b2438e57c801032ed8cad7e161ed5fa6cc73a0",
+  skillSha256: "33011d4e7abc8fd76b0b3b38450cfdff545117a1950e22ee5176ab3c2cf589c9",
   nativeWriteSettings: {
     supportedOperations: [
       "attachment.download",
@@ -46239,7 +46291,7 @@ var checkpoint_axi_default = {
       flags: {
         config: "Config path; default CHECKPOINT_AXI_CONFIG or platform path",
         profile: "Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile",
-        fields: "Comma-separated output fields; default all",
+        fields: "Comma-separated row fields: id,subject,state,verdict; or top-level emails,count,total,complete,reason,cursor,expansion,help; default all",
         full: "Show full strings instead of 500-character previews; default false",
         help: "Show concise command help; default false",
         saas: "SaaS override; default selected profile saas or office365_emails",
@@ -46249,7 +46301,10 @@ var checkpoint_axi_default = {
         limit: "Maximum rows; default 50, range 1-1000; cannot combine with --all",
         all: "Read up to 1000 rows / 10 HTTP requests / 60 seconds / 8 MiB; default false",
         cursor: "Opaque continuation bound to profile, region, operation and selectors; repeat original selectors",
-        filter: "JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters (guide pages 19-20)"
+        expand: "Opt in to read-only show details on returned rows; default false; partial expansion is reported separately",
+        "expand-limit": "Maximum detail attempts; default 5, range 1-8; requires --expand",
+        "expand-requests": "Total HTTP request cap including auth, list pages, detail and retries; default 10, range 2-10; requires --expand",
+        filter: "JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters. saasAttrName is a field path, not a closed enum (guide pages 19-20). Documented examples: entityPayload.subject, entityPayload.fromEmail, entityPayload.attachmentCount. Other documented email payload paths (pages 15-16, 24-25): entityPayload.internetMessageId, entityPayload.received, entityPayload.size, entityPayload.emailLinks, entityPayload.attachments, entityPayload.mode, entityPayload.recipients, entityPayload.fromDomain, entityPayload.fromUser, entityPayload.fromName, entityPayload.to, entityPayload.toUser, entityPayload.cc, entityPayload.ccUser, entityPayload.bcc, entityPayload.bccUser, entityPayload.replyToEmail, entityPayload.replyToNickname, entityPayload.isRead, entityPayload.isDeleted, entityPayload.isIncoming, entityPayload.isInternal, entityPayload.isOutgoing, entityPayload.isQuarantined, entityPayload.isQuarantineNotification, entityPayload.isRestored, entityPayload.isRestoreRequested, entityPayload.isRestoreDeclined, entityPayload.saasSpamVerdict, entityPayload.SpfResult. saasAttrOp: is, contains, startsWith, isEmpty, isNot, notContains, isNotEmpty, greaterThan, lessThan. The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan. saasAttrValue is a string."
       }
     },
     {
@@ -46285,7 +46340,7 @@ var checkpoint_axi_default = {
       flags: {
         config: "Config path; default CHECKPOINT_AXI_CONFIG or platform path",
         profile: "Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile",
-        fields: "Comma-separated output fields; default all",
+        fields: "Comma-separated row fields: id,type,state,severity; or top-level events,count,total,complete,reason,cursor,expansion,help; default all",
         full: "Show full strings instead of 500-character previews; default false",
         help: "Show concise command help; default false",
         "start-date": "ISO timestamp with timezone; default 24 hours before end-date; maximum window 31 days",
@@ -46293,10 +46348,14 @@ var checkpoint_axi_default = {
         limit: "Maximum rows; default 50, range 1-1000; cannot combine with --all",
         all: "Read up to 1000 rows / 10 HTTP requests / 60 seconds / 8 MiB; default false",
         cursor: "Opaque continuation bound to profile, region, operation and selectors; repeat original selectors",
+        expand: "Opt in to read-only show details on returned rows; default false; partial expansion is reported separately",
+        "expand-limit": "Maximum detail attempts; default 5, range 1-8; requires --expand",
+        "expand-requests": "Total HTTP request cap including auth, list pages, detail and retries; default 10, range 2-10; requires --expand",
         saas: "Comma-separated SaaS overrides; default selected profile saas or office365_emails",
         "event-types": "Comma-separated event types; default unfiltered",
-        "event-states": "Comma-separated event states; default unfiltered",
-        severities: "Comma-separated severities; default unfiltered",
+        "event-states": "Comma-separated event states: new, detected, pending, remediated, dismissed, exception; default unfiltered",
+        states: "Alias for --event-states; cannot combine with --event-states",
+        severities: "Nonempty comma-separated severity strings; vendor documents no fixed severity list; unrecognised severities can return an empty result; default unfiltered",
         "event-ids": "Comma-separated event IDs; default unfiltered",
         "confidence-indicator": "Confidence indicator selector; default unfiltered",
         description: "Description selector; default unfiltered"
@@ -46445,7 +46504,11 @@ var checkpoint_axi_default = {
         profile: "Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile",
         fields: "Comma-separated output fields; default all",
         full: "Show full strings instead of 500-character previews; default false",
-        help: "Show concise command help; default false"
+        help: "Show concise command help; default false",
+        wait: "Poll existing task status only; default false; requires --timeout; terminal: completed, failed, stopped",
+        timeout: "Total wait timeout in integer seconds, range 1-60; required with --wait; includes auth and retries",
+        "poll-interval": "Seconds between status reads; default 2, range 1-10; requires --wait",
+        "wait-requests": "Total HTTP request cap including auth and retries; default 10, range 2-10; requires --wait"
       }
     }
   ]
@@ -47874,6 +47937,13 @@ function rewriteDiscoveryHelp(help, tool) {
     examples: help.examples.map((example) => hostedHelp(example, tool, flags, true))
   });
 }
+function encodeSuggestion(value, inline) {
+  try {
+    if (value && !(inline && value.includes(",")) && decode3(`value: ${value}`).value === value) return value;
+  } catch {
+  }
+  return JSON.stringify(value);
+}
 function rewriteSuggestions(output3, tool, truncated = false, invocation) {
   if (truncated) return output3;
   if (tool === "gh-axi") return rewriteGhSuggestions(output3, invocation, truncated);
@@ -47964,6 +48034,7 @@ function rewriteSuggestions(output3, tool, truncated = false, invocation) {
   const executable = new RegExp(`^(?:artium-axi |npx -y @knowttl/)?${tool}(?=\\s|$)`);
   if (executable.test(output3.replace(/^[ \t]*(?:(?:Command|Native operation|Examples|Usage): )?/, "")) || tool === "ldap-axi" && ldapHelp.test(output3)) return hostedHelp(output3, tool, flags, true);
   let spans;
+  let field;
   let unknownOutcome = false;
   try {
     const json2 = output3.trimStart().startsWith("{");
@@ -47993,16 +48064,41 @@ function rewriteSuggestions(output3, tool, truncated = false, invocation) {
     }
     const { spans: suggestions, document } = parsed;
     spans = suggestions;
+    field = parsed.field;
     if (tool === "az-axi") {
       unknownOutcome = document?.code === "UNKNOWN_OUTCOME" || document?.error?.code === "UNKNOWN_OUTCOME";
     }
   } catch {
     return output3;
   }
-  for (const span of [...spans].reverse()) {
-    const value = hostedHelp(span.value, tool, flags, /^[ \t]*(?:Command|Native operation|Examples|Usage):/m.test(span.value));
-    if (value === span.value) continue;
-    output3 = output3.slice(0, span.start) + (span.quoted || ["ldap-axi", "ado-axi", "awx-axi", "gh-axi"].includes(tool) && /[,\r\n]/.test(value) ? JSON.stringify(value) : value) + output3.slice(span.start + span.raw.length);
+  const replacements = spans.map((span) => hostedHelp(span.value, tool, flags, /^[ \t]*(?:Command|Native operation|Examples|Usage):/m.test(span.value)));
+  if (field && replacements.some((value) => !value.trim())) {
+    const values = replacements.filter((value) => value.trim());
+    const help = field.array ? values : values[0] ?? "";
+    const replacement = output3.trimStart().startsWith("{") ? JSON.stringify(help) : field.array && !values.length ? "help[0]:" : encode3({ help });
+    output3 = output3.slice(0, field.start) + replacement + output3.slice(field.end);
+  } else {
+    const edits = [];
+    const lists = /* @__PURE__ */ new Map();
+    for (let index = 0; index < spans.length; index++) {
+      const span = spans[index];
+      const value = replacements[index];
+      const changed = value !== span.value;
+      const text2 = span.quoted ? JSON.stringify(value) : encodeSuggestion(value, Boolean(span.list));
+      if (!span.list) {
+        if (changed) edits.push({ start: span.start, end: span.start + span.raw.length, text: text2 });
+        continue;
+      }
+      const list = lists.get(span.list) ?? { items: [], changed: false };
+      if (!changed) list.items.push(span.raw);
+      else if (value) list.items.push(text2);
+      list.changed ||= changed;
+      lists.set(span.list, list);
+    }
+    for (const [{ countStart, end }, { items, changed }] of lists) {
+      if (changed) edits.push({ start: countStart, end, text: `${items.length}]:${items.length ? ` ${items.join(",")}` : ""}` });
+    }
+    for (const edit of edits.sort((a, b) => b.start - a.start)) output3 = output3.slice(0, edit.start) + edit.text + output3.slice(edit.end);
   }
   spans = (output3.trimStart().startsWith("{") ? jsonHelp(output3) : toonHelp(output3)).spans;
   if (spans.some((span) => /\\[`'"]/.test(span.value))) return output3;
@@ -48156,8 +48252,10 @@ function jsonHelp(output3) {
   const spans = [];
   let index = 0;
   let helpFields = 0;
+  let field;
   function value(help = false, root = false) {
     const token = tokens[index++];
+    const start = token.index;
     if (token[0] === "{") {
       while (tokens[index][0] !== "}") {
         const key = JSON.parse(tokens[index++][0]);
@@ -48176,21 +48274,23 @@ function jsonHelp(output3) {
     } else if (help && token[0].startsWith('"')) {
       spans.push({ start: token.index, raw: token[0], value: JSON.parse(token[0]), quoted: true });
     }
+    if (help) field = { start, end: tokens[index - 1].index + tokens[index - 1][0].length, array: token[0] === "[" };
   }
   value(false, true);
-  return { spans: helpFields === 1 ? spans : [], document: parsed };
+  return { spans: helpFields === 1 ? spans : [], field: helpFields === 1 ? field : void 0, document: parsed };
 }
 function toonHelp(output3) {
   const lines = [...output3.matchAll(/[^\r\n]*(?:\r\n|\n|$)/g)].filter((line) => line[0]);
   const spans = [];
   const validation = lines.map((line) => line[0].replace(/\r?\n$/, ""));
   let helpFields = 0;
-  function scalar(raw, start) {
+  let range;
+  function scalar(raw, start, list) {
     const parsed2 = decode3(`value: ${raw}`);
     if (typeof parsed2.value !== "string") throw new Error("Unknown suggestion format");
     const quoted = raw.startsWith('"');
     if (quoted && JSON.parse(raw) !== parsed2.value) throw new Error("Unknown escaping");
-    spans.push({ start, raw, value: parsed2.value, quoted });
+    spans.push({ start, raw, value: parsed2.value, quoted, ...list ? { list } : {} });
   }
   for (let index = 0; index < lines.length; index++) {
     const text2 = lines[index][0].replace(/\r?\n$/, "");
@@ -48206,6 +48306,7 @@ ${line[0]}`);
       }
     }
     helpFields++;
+    range = { start: lines[index].index, end: lines[index].index + text2.length, array: !!field[1] };
     validation[index] = 'help: ""';
     if (!field[1]) {
       scalar(field[2], lines[index].index + text2.length - field[2].length);
@@ -48213,6 +48314,7 @@ ${line[0]}`);
     }
     if (field[2]) {
       const raw = field[2];
+      const list = { countStart: lines[index].index + /^(?:help|"help")\[/.exec(text2)[0].length, end: lines[index].index + text2.length };
       let cursor = 0;
       let items = 0;
       while (cursor < raw.length) {
@@ -48226,7 +48328,7 @@ ${line[0]}`);
           const comma = raw.indexOf(",", cursor);
           cursor = comma === -1 ? raw.length : comma;
         }
-        scalar(raw.slice(start, cursor).trimEnd(), lines[index].index + text2.length - raw.length + start);
+        scalar(raw.slice(start, cursor).trimEnd(), lines[index].index + text2.length - raw.length + start, list);
         items++;
         while (/[ \t]/.test(raw[cursor] ?? "")) cursor++;
         if (cursor < raw.length && raw[cursor++] !== ",") throw new Error("Unknown inline suggestion");
@@ -48242,6 +48344,7 @@ ${line[0]}`);
       const row = /^  (?:- )?(\S[^\r\n]*)(?:\r?\n)?$/.exec(line[0]);
       if (!row) throw new Error("Unknown suggestion item");
       scalar(row[1], line.index + line[0].indexOf(row[1]));
+      range.end = line.index + line[0].replace(/\r?\n$/, "").length;
       validation[index] = "";
     }
     if (lines[index + 1]?.[0].startsWith(" ")) throw new Error("Extra suggestion rows");
@@ -48249,7 +48352,7 @@ ${line[0]}`);
   const document = validation.filter((line) => line !== "").join("\n");
   const parsed = decode3(document);
   if (encode3(parsed) !== document) throw new Error("Unknown document structure");
-  return { spans: helpFields === 1 ? spans : [], document: parsed };
+  return { spans: helpFields === 1 ? spans : [], field: helpFields === 1 ? range : void 0, document: parsed };
 }
 
 // src/cli/views.ts
@@ -48354,8 +48457,8 @@ async function doctor(createClient = (deadline) => new Client(process.env, void
         line(
           tool.name,
           tool.status === "ok",
-          tool.status,
-          new ArtiumError(tool.status === "unconfigured" ? "CREDENTIAL_NOT_CONFIGURED" : tool.status === "error" ? "TOOL_FAILED" : tool.status === "disabled" ? "TOOL_DISABLED" : "SERVER_UNAVAILABLE")
+          tool.status === "error" && tool.errorCode ? `${tool.status}: ${tool.errorCode}` : tool.status,
+          new ArtiumError(tool.status === "unconfigured" ? "CREDENTIAL_NOT_CONFIGURED" : tool.status === "error" ? tool.errorCode ?? "TOOL_FAILED" : tool.status === "disabled" ? "TOOL_DISABLED" : "SERVER_UNAVAILABLE")
         );
       }
     } catch (error62) {
@@ -48608,7 +48711,7 @@ import { homedir as homedir2 } from "node:os";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
 
 // skill/artium-axi/SKILL.md
-var SKILL_default = "---\nname: artium-axi\ndescription: Discover and run managed commands through Artium, using the signed-in account and its granted tools.\n---\n\nFor requests involving data from Artium-managed tools, discover the tools available to this account before choosing one.\nRun `artium-axi` for identity and tools together, or `artium-axi tools` when only tool discovery is needed.\nRun `artium-axi tools show <tool>` for its commands and a vetted example, then run `artium-axi <tool> <args>`.\nFollow the returned next commands; they already include the Artium prefix.\nKeep upstream arguments intact and use the managed credentials rather than configuring an upstream CLI directly.\nSee [client input handling](https://github.com/knowttl/artium-axi/blob/main/docs/client-reference.md#command-surface-and-subcommands) for Azure stdin selection and Tenable local uploads or explicit stdin.\n\nIf artium-axi is absent from PATH, use the installed command below in place of `artium-axi` in every example:\nOn Windows, choose the labelled PowerShell or Git Bash command for your shell.\n\n<!-- artium-axi executable -->\nThe setup command records the standalone bundle's Node invocation here.\n<!-- /artium-axi executable -->\n\nIf sign-in is required, ask the user to sign in with their SSO or local account.\nNever request or print tokens or put passwords in arguments.\nAn empty tool list means no enabled runtime tool is available through the account's roles; ask an administrator to check grants and enabled tools.\nUse `artium-axi doctor` for connection or cached health diagnostics.\nDo not retry an uncertain command outcome, especially a write.\n\n## Investigation quick guide\n\nStart with these reads using an already signed-in account, without running help first.\nArtium is a managed transport; vendor investigation syntax and one-call pivots belong to the tool skills installed by setup.\nUse the matching installed skill once you know the granted tool.\n\n| Read command and example | What it answers |\n| --- | --- |\n| `artium-axi` | Identity, roles and available tools together in one call. |\n| `artium-axi tools` | Granted enabled tools, status, pinned version and `readOnly`; no flags required. |\n| `artium-axi tools show falcon-axi` | One tool's reviewed command inventory, vetted upstream help and first read example; substitute a granted tool name. |\n| `artium-axi whoami` | Identity, roles, session expiry and server; no flags required. |\n| `artium-axi doctor` | Connection, certificate, token, version and cached tool health; does not run a fresh upstream credential test. |\n| `artium-axi falcon-axi detection list` | First endpoint detection read when Falcon is granted; keep all upstream arguments after the tool name. |\n\nThe home view combines identity and tool discovery, so skip separate whoami and tools calls when it already answers the question.\nTools show combines command inventory, vetted help and a first call, avoiding help probes for every listed command.\nArtium has no generic batch, start-and-wait, list-with-details or lookup-and-pivot flag.\nUse only single-call forms documented by the granted tool's installed skill and supported by its pinned command inventory; upstream support does not imply managed availability.\n\n### Keep output small\n\nClient discovery has no `--fields`, `--limit` or `--full` flags.\nTools already returns only `name`, `status`, `version` and `readOnly`; use tools show for one tool's details only when needed.\nForward tool-specific filters, `--fields` and `--limit` only where its skill documents them.\nPrefer identifiers, status, timestamps and summary fields; fetch long descriptions only for relevant records.\nUpstream `--full`, where supported, restores text but never bypasses redaction, execution budgets or output caps.\nHeed stderr truncation notices and narrow the query rather than treating partial output as complete; see [output limits](https://github.com/knowttl/artium-axi/blob/main/docs/client-reference.md#toon-output-behavior).\n\n### Help is recovery\n\nUse help for a command that fails or whose arguments are unclear, not to start an investigation.\n`artium-axi --help` returns the local client command list, usage, flags and an example without signing in.\nClient command help, such as `artium-axi tools --help`, `artium-axi tools show --help`, `artium-axi whoami --help` and `artium-axi doctor --help`, describes only that client command.\n`artium-axi --help falcon-axi` is local entry help describing forwarding and managed boundaries.\n`artium-axi falcon-axi --help` and `artium-axi falcon-axi detection list --help` authenticate and forward help to the pinned tool at the requested level.\nThe same before/after-tool distinction applies to other granted tools.\n\n### Read allowlist and state changes\n\nThe six reads above are candidates for a reviewed allowlist, scoped to their exact argument forms.\nAuthenticated reads can refresh local session tokens and create server audit records.\nNever allow an unrestricted tool prefix merely because its discovery row says `readOnly`.\nLogin, passwd and logout change session/account state; setup writes skills/hooks; update replaces the executable; download prepares transfers or saves artifacts.\nForwarded writes and job creation need separate review and administrator enablement where supported.\nHybrid Analysis quick scans can transmit samples or URLs even with managed writes disabled.\nNative preview, execute and exact confirmation gates still apply; there is no universal Artium confirmation flag.\n\n### Failures and next action\n\nArtium errors are TOON on stdout with `error.code`, `source`, `message` and `next`; follow `next` rather than retrying blindly.\nExit 0 means success, 2 means usage/configuration error and 1 means authentication/server/transport failure; upstream exit status passes through.\n\nUse the [generated error reference](https://github.com/knowttl/artium-axi/blob/main/docs/errors.md) for code-specific recovery and exit codes.\n\n## Commands\n\nThis table is kept identical to the [command reference](https://github.com/knowttl/artium-axi/blob/main/docs/commands.md).\nTool reference links describe upstream commands; Artium controls availability, credentials and permissions.\n\n| Command | Purpose |\n| --- | --- |\n| `artium-axi` | Show identity, roles and available tools. |\n| `artium-axi --help [<command>]` | Show local client or tool-entry help without authentication. |\n| `artium-axi --version` | Print the client package version. |\n| `artium-axi login --username <username> [--password-stdin]` | Sign in with a local account using protected password input. |\n| `artium-axi login --sso` | Sign in through browser approval of the terminal code. |\n| `artium-axi passwd [--password-stdin]` | Change the account password, then sign in again. |\n| `artium-axi logout` | Remove local tokens and attempt server-session revocation. |\n| `artium-axi whoami` | Show identity, roles, session expiry and server. |\n| `artium-axi tools` | List granted enabled tools with status and pinned versions. |\n| `artium-axi tools show <tool>` | Show one available tool, vetted upstream help and a first call. |\n| `artium-axi doctor` | Check the server, certificate, token, client version and cached tool health. |\n| `artium-axi update` | Download and verify the server client, replace this file and retain a .bak backup; npm installs use npm instead. |\n| `artium-axi download --operation <operation> --selector <selector> --type <type> --destination <absolute-new-path> [--transfer <id> --execute --confirm <exact-confirm>] [--password-stdin\\|--sso]` | Preview or explicitly verify and save administrator-enabled Hybrid Analysis archives, Check Point emails/attachments, Graph mail exports or BeyondTrust endpoint content; see `artium-axi download --help` for guards. |\n| `artium-axi setup --host <claude\\|codex\\|opencode\\|pi> [--hook] [--force]` | Install skills for the signed-in account's granted tools and an optional Claude Code hook. |\n| `artium-axi --managed-session <command> [<args>]` | Supply and persist caller-owned sessions through private pipes; see `artium-axi --managed-session --help`. |\n| `artium-axi falcon-axi [<args>]` | Run Falcon commands with managed credentials; [tool reference](https://github.com/knowttl/falcon-axi#readme). |\n| `artium-axi vectra-axi [<args>]` | Run Vectra commands with managed credentials; [tool reference](https://www.npmjs.com/package/@knowttl/vectra-axi). |\n| `artium-axi az-axi [<args>]` | Run Azure commands with the managed identity; [tool reference](https://www.npmjs.com/package/@knowttl/az-axi). |\n| `artium-axi mg-axi [<args>]` | Run Microsoft Graph commands with the managed identity; [tool reference](https://www.npmjs.com/package/@knowttl/mg-axi). |\n| `artium-axi ldap-axi [<args>]` | Read directory data with the managed LDAP bind identity; [tool reference](https://www.npmjs.com/package/@knowttl/ldap-axi). |\n| `artium-axi ado-axi [<args>]` | Run Azure DevOps commands with managed credentials; [tool reference](https://www.npmjs.com/package/@jeffreyhaen/ado-axi). |\n| `artium-axi awx-axi [<args>]` | Inspect AWX automation with managed credentials; [tool reference](https://www.npmjs.com/package/awx-axi). |\n| `artium-axi tenable-axi [<args>]` | Investigate Tenable One with managed API keys; [tool reference](https://www.npmjs.com/package/@knowttl/tenable-axi). |\n| `artium-axi hybrid-axi [<args>]` | Investigate Hybrid Analysis with a managed API key; [tool reference](https://www.npmjs.com/package/@knowttl/hybrid-axi). |\n| `artium-axi beyondtrust-axi [<args>]` | Inspect BeyondTrust PM Cloud Endpoint Privilege Management with managed credentials; [tool reference](https://www.npmjs.com/package/@knowttl/beyondtrust-axi). |\n| `artium-axi checkpoint-axi [<args>]` | Investigate Check Point Email Security with managed regional credentials; [tool reference](https://www.npmjs.com/package/@knowttl/checkpoint-axi). |\n| `artium-axi gh-axi [<args>]` | Read and update GitHub data with managed credentials; [tool reference](https://www.npmjs.com/package/gh-axi). |\n";
+var SKILL_default = "---\nname: artium-axi\ndescription: Discover and run managed commands through Artium, using the signed-in account and its granted tools.\n---\n\nFor requests involving data from Artium-managed tools, discover the tools available to this account before choosing one.\nRun `artium-axi` for identity and tools together, or `artium-axi tools` when only tool discovery is needed.\nRun `artium-axi tools show <tool>` for its commands and a vetted example, then run `artium-axi <tool> <args>`.\nFollow the returned next commands; they already include the Artium prefix.\nKeep upstream arguments intact and use the managed credentials rather than configuring an upstream CLI directly.\nSee [client input handling](https://github.com/knowttl/artium-axi/blob/main/docs/client-reference.md#command-surface-and-subcommands) for Azure stdin selection and Tenable local uploads or explicit stdin.\n\nIf artium-axi is absent from PATH, use the installed command below in place of `artium-axi` in every example:\nOn Windows, choose the labelled PowerShell or Git Bash command for your shell.\n\n<!-- artium-axi executable -->\nThe setup command records the standalone bundle's Node invocation here.\n<!-- /artium-axi executable -->\n\nIf sign-in is required, ask the user to sign in with their SSO or local account.\nNever request or print tokens or put passwords in arguments.\nAn empty tool list means no enabled runtime tool is available through the account's roles; ask an administrator to check grants and enabled tools.\nUse `artium-axi doctor` for connection or cached health diagnostics.\nDo not retry an uncertain command outcome, especially a write.\n\n## Investigation quick guide\n\nStart with these reads using an already signed-in account, without running help first.\nArtium is a managed transport; vendor investigation syntax and one-call pivots belong to the tool skills installed by setup.\nUse the matching installed skill once you know the granted tool.\n\n| Read command and example | What it answers |\n| --- | --- |\n| `artium-axi` | Identity, roles and available tools together in one call. |\n| `artium-axi tools` | Granted enabled tools, status, pinned version and `readOnly`; no flags required. |\n| `artium-axi tools show falcon-axi` | One tool's reviewed command inventory, vetted upstream help and first read example; substitute a granted tool name. |\n| `artium-axi whoami` | Identity, roles, session expiry and server; no flags required. |\n| `artium-axi doctor` | Connection, certificate, token, version and cached tool health; does not run a fresh upstream credential test. |\n| `artium-axi falcon-axi detection list` | First endpoint detection read when Falcon is granted; keep all upstream arguments after the tool name. |\n\nThe home view combines identity and tool discovery, so skip separate whoami and tools calls when it already answers the question.\nTools show combines command inventory, vetted help and a first call, avoiding help probes for every listed command.\nArtium has no generic batch, start-and-wait, list-with-details or lookup-and-pivot flag.\nUse only single-call forms documented by the granted tool's installed skill and supported by its pinned command inventory; upstream support does not imply managed availability.\n\n### Keep output small\n\nClient discovery has no `--fields`, `--limit` or `--full` flags.\nTools already returns only `name`, `status`, `version` and `readOnly`; use tools show for one tool's details only when needed.\nForward tool-specific filters, `--fields` and `--limit` only where its skill documents them.\nPrefer identifiers, status, timestamps and summary fields; fetch long descriptions only for relevant records.\nUpstream `--full`, where supported, restores text but never bypasses redaction, execution budgets or output caps.\nHeed stderr truncation notices and narrow the query rather than treating partial output as complete; see [output limits](https://github.com/knowttl/artium-axi/blob/main/docs/client-reference.md#toon-output-behavior).\n\n### Help is recovery\n\nUse help for a command that fails or whose arguments are unclear, not to start an investigation.\n`artium-axi --help` returns the local client command list, usage, flags and an example without signing in.\nClient command help, such as `artium-axi tools --help`, `artium-axi tools show --help`, `artium-axi whoami --help` and `artium-axi doctor --help`, describes only that client command.\n`artium-axi --help falcon-axi` is local entry help describing forwarding and managed boundaries.\n`artium-axi falcon-axi --help` and `artium-axi falcon-axi detection list --help` authenticate and forward help to the pinned tool at the requested level.\nThe same before/after-tool distinction applies to other granted tools.\n\n### Read allowlist and state changes\n\nThe six reads above are candidates for a reviewed allowlist, scoped to their exact argument forms.\nAuthenticated reads can refresh local session tokens and create server audit records.\nNever allow an unrestricted tool prefix merely because its discovery row says `readOnly`.\nLogin, passwd and logout change session/account state; setup writes skills/hooks; update replaces the executable; download prepares transfers or saves artifacts.\nForwarded writes and job creation need separate review and administrator enablement where supported.\nHybrid Analysis quick scans can transmit samples or URLs even with managed writes disabled.\nNative preview, execute and exact confirmation gates still apply; there is no universal Artium confirmation flag.\n\n### Failures and next action\n\nArtium errors are TOON on stdout with `error.code`, `source`, `message` and `next`; follow `next` rather than retrying blindly.\nFor a non-zero tool exit, keep the stderr `artium-axi: request_id <id>` line and quote that ID, the tool and time when asking an administrator for help; never include credentials or sensitive output.\nFollow the [failed-call troubleshooting path](https://github.com/knowttl/artium-axi/blob/main/docs/runbook.md#troubleshoot-a-failed-tool-call) for administrator investigation, and check current state before retrying an unknown write outcome.\nSee the [output contract](https://github.com/knowttl/artium-axi/blob/main/README.md#toon-output-and-errors) for exit codes and upstream output handling.\n\nUse the [generated error reference](https://github.com/knowttl/artium-axi/blob/main/docs/errors.md) for code-specific recovery and exit codes.\nSee the [credential diagnostic guidance](https://github.com/knowttl/artium-axi/blob/main/docs/runbook.md#scripted-administrator-sessions) for tool-code mappings and administrator troubleshooting.\n\n## Commands\n\nThis table is kept identical to the [command reference](https://github.com/knowttl/artium-axi/blob/main/docs/commands.md).\nTool reference links describe upstream commands; Artium controls availability, credentials and permissions.\n\n| Command | Purpose |\n| --- | --- |\n| `artium-axi` | Show identity, roles and available tools. |\n| `artium-axi --help [<command>]` | Show local client or tool-entry help without authentication. |\n| `artium-axi --version` | Print the client package version. |\n| `artium-axi login --username <username> [--password-stdin]` | Sign in with a local account using protected password input. |\n| `artium-axi login --sso` | Sign in through browser approval of the terminal code. |\n| `artium-axi passwd [--password-stdin]` | Change the account password, then sign in again. |\n| `artium-axi logout` | Remove local tokens and attempt server-session revocation. |\n| `artium-axi whoami` | Show identity, roles, session expiry and server. |\n| `artium-axi tools` | List granted enabled tools with status and pinned versions. |\n| `artium-axi tools show <tool>` | Show one available tool, vetted upstream help and a first call. |\n| `artium-axi doctor` | Check the server, certificate, token, client version and cached tool health. |\n| `artium-axi update` | Download and verify the server client, replace this file and retain a .bak backup; npm installs use npm instead. |\n| `artium-axi download --operation <operation> --selector <selector> --type <type> --destination <absolute-new-path> [--transfer <id> --execute --confirm <exact-confirm>] [--password-stdin\\|--sso]` | Preview or explicitly verify and save administrator-enabled Hybrid Analysis archives, Check Point emails/attachments, Graph mail exports or BeyondTrust endpoint content; see `artium-axi download --help` for guards. |\n| `artium-axi setup --host <claude\\|codex\\|opencode\\|pi> [--hook] [--force]` | Install skills for the signed-in account's granted tools and an optional Claude Code hook. |\n| `artium-axi --managed-session <command> [<args>]` | Supply and persist caller-owned sessions through private pipes; see `artium-axi --managed-session --help`. |\n| `artium-axi falcon-axi [<args>]` | Run Falcon commands with managed credentials; [tool reference](https://github.com/knowttl/falcon-axi#readme). |\n| `artium-axi vectra-axi [<args>]` | Run Vectra commands with managed credentials; [tool reference](https://www.npmjs.com/package/@knowttl/vectra-axi). |\n| `artium-axi az-axi [<args>]` | Run Azure commands with the managed identity; [tool reference](https://www.npmjs.com/package/@knowttl/az-axi). |\n| `artium-axi mg-axi [<args>]` | Run Microsoft Graph commands with the managed identity; [tool reference](https://www.npmjs.com/package/@knowttl/mg-axi). |\n| `artium-axi ldap-axi [<args>]` | Read directory data with the managed LDAP bind identity; [tool reference](https://www.npmjs.com/package/@knowttl/ldap-axi). |\n| `artium-axi ado-axi [<args>]` | Run Azure DevOps commands with managed credentials; [tool reference](https://www.npmjs.com/package/@jeffreyhaen/ado-axi). |\n| `artium-axi awx-axi [<args>]` | Inspect AWX automation with managed credentials; [tool reference](https://www.npmjs.com/package/awx-axi). |\n| `artium-axi tenable-axi [<args>]` | Investigate Tenable One with managed API keys; [tool reference](https://www.npmjs.com/package/@knowttl/tenable-axi). |\n| `artium-axi hybrid-axi [<args>]` | Investigate Hybrid Analysis with a managed API key; [tool reference](https://www.npmjs.com/package/@knowttl/hybrid-axi). |\n| `artium-axi beyondtrust-axi [<args>]` | Inspect BeyondTrust PM Cloud Endpoint Privilege Management with managed credentials; [tool reference](https://www.npmjs.com/package/@knowttl/beyondtrust-axi). |\n| `artium-axi checkpoint-axi [<args>]` | Investigate Check Point Email Security with managed regional credentials; [tool reference](https://www.npmjs.com/package/@knowttl/checkpoint-axi). |\n| `artium-axi gh-axi [<args>]` | Read and update GitHub data with managed credentials; [tool reference](https://www.npmjs.com/package/gh-axi). |\n";
 
 // src/cli/setup.ts
 var hosts = {
@@ -49373,6 +49476,7 @@ async function download(args, output3, managed2) {
 
 // src/cli/main.ts
 var managed;
+var failureContext = "main";
 for (const stream of [process.stdout, process.stderr]) {
   stream.on("error", (error62) => {
     if (error62.code !== "EPIPE") throw error62;
@@ -49572,26 +49676,35 @@ ${view}${toolsView(tools.data.tools)}`;
     const { stdout, stderr, exitCode, truncated } = parsed.data;
     if (truncated.stdout || truncated.stderr) output2("stderr", `artium-axi: output truncated (${["stdout", "stderr"].filter((stream) => truncated[stream]).join(", ")}).
 `);
+    failureContext = "rewriteSuggestions";
     output2("stdout", rewriteSuggestions(stdout, command, truncated.stdout));
     output2("stderr", rewriteSuggestions(stderr, command, truncated.stderr));
+    if (exitCode !== 0 && client.requestId) output2("stderr", `${stderr && !stderr.endsWith("\n") ? "\n" : ""}artium-axi: request_id ${client.requestId}
+`);
     process.exitCode = exitCode;
   }
 }
-function printError(response) {
+function printError(error62) {
+  const errorClass = error62 instanceof TypeError ? "TypeError" : error62 instanceof SyntaxError ? "SyntaxError" : error62 instanceof RangeError ? "RangeError" : error62 instanceof ReferenceError ? "ReferenceError" : error62 instanceof URIError ? "URIError" : error62 instanceof EvalError ? "EvalError" : error62 instanceof Error ? "Error" : "NonError";
+  const response = errorResponse(error62 instanceof ArtiumError ? error62 : new ArtiumError(
+    "INTERNAL_ERROR",
+    `The CLI failed locally (${errorClass} in ${failureContext}).`,
+    "Report the error class and function to the CLI maintainer. Check the previous call outcome before retrying."
+  ), "");
   if (process.argv[2] === "download" || process.argv[2] === "--managed-session" && process.argv[3] === "download") {
     output2("stdout", `warning: ${JSON.stringify(transferWarningFor(process.argv[process.argv.indexOf("--operation") + 1] ?? ""))}
 `);
   }
   output2("stdout", `error:
-${Object.entries(response.error).map(([key, value]) => `  ${key}: ${JSON.stringify(value)}`).join("\n")}
+${Object.entries(response.error).filter(([key, value]) => key !== "requestId" || value).map(([key, value]) => `  ${key}: ${JSON.stringify(value)}`).join("\n")}
 `);
   process.exitCode = errors[response.error.code].exitCode;
 }
-main(process.argv.slice(2)).catch((error62) => printError(errorResponse(error62 instanceof ArtiumError ? error62 : new ArtiumError("INTERNAL_ERROR"), randomUUID5()))).then(() => {
+main(process.argv.slice(2)).catch(printError).then(() => {
   try {
     managed?.flush();
   } catch {
     managed = void 0;
-    printError(errorResponse(new ArtiumError("SECRET_IN_OUTPUT"), randomUUID5()));
+    printError(new ArtiumError("SECRET_IN_OUTPUT"));
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/artium-axi",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Client CLI and embedded skill for the Artium managed tools server.",
   "license": "MIT",
   "type": "module",

package/skill/artium-axi/SKILL.md

@@ -74,9 +74,12 @@ Native preview, execute and exact confirmation gates still apply; there is no un
 ### Failures and next action
 
 Artium errors are TOON on stdout with `error.code`, `source`, `message` and `next`; follow `next` rather than retrying blindly.
-Exit 0 means success, 2 means usage/configuration error and 1 means authentication/server/transport failure; upstream exit status passes through.
+For a non-zero tool exit, keep the stderr `artium-axi: request_id <id>` line and quote that ID, the tool and time when asking an administrator for help; never include credentials or sensitive output.
+Follow the [failed-call troubleshooting path](https://github.com/knowttl/artium-axi/blob/main/docs/runbook.md#troubleshoot-a-failed-tool-call) for administrator investigation, and check current state before retrying an unknown write outcome.
+See the [output contract](https://github.com/knowttl/artium-axi/blob/main/README.md#toon-output-and-errors) for exit codes and upstream output handling.
 
 Use the [generated error reference](https://github.com/knowttl/artium-axi/blob/main/docs/errors.md) for code-specific recovery and exit codes.
+See the [credential diagnostic guidance](https://github.com/knowttl/artium-axi/blob/main/docs/runbook.md#scripted-administrator-sessions) for tool-code mappings and administrator troubleshooting.
 
 ## Commands