@jacebenson/jsn 3.0.5 → 3.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -142,9 +142,12 @@ export const cli = yargs(hideBin(process.argv))
     }
 
     // Auto-check skill on every command (fire-and-forget, non-blocking)
+    // Skipped under --json, --quiet, --no-skill-check, or env var
     const skipSkillCheck = ['help', 'version', 'completion', 'skill'].includes(cmd)
       || process.env.JSN_NO_SKILL_CHECK === '1'
-      || argv['no-skill-check'];
+      || argv['no-skill-check']
+      || argv.json
+      || argv.quiet;
     if (!skipSkillCheck) {
       // Fire check but don't await — it runs in background
       checkSkill().then(result => {

package/src/commands/dev/_simple.js

@@ -81,7 +81,6 @@ export const spPagesCmd = (wrap) => buildDevCmd('sppages', 'sp_page', ['sp-pages
 export const spWidgetsCmd = (wrap) => buildDevCmd('spwidgets', 'sp_widget', ['sp-widget', 'widgets'], ['id', 'name', 'sys_scope'], wrap, { singular: 'Service Portal widget', readOnly: true });
 export const uiPagesCmd = (wrap) => buildDevCmd('uipages', 'sys_ui_page', ['ui-page', 'pages'], ['name', 'sys_scope'], wrap, { singular: 'UI page', scopeValidation: true });
 export const appMenuCmd = (wrap) => buildDevCmd('appmenu', 'sys_app_application', ['app-menu', 'menu'], ['name', 'active', 'sys_scope'], wrap, { singular: 'application menu', scopeValidation: true });
-export const scRAPICmd = (wrap) => buildDevCmd('scrapi', 'sys_ws_operation', ['scripted-rest', 'rest-api'], ['name', 'sys_ws_definition', 'sys_scope'], wrap, { singular: 'scripted REST API', readOnly: true });
 
 // Commands with full CRUD
 export const aclsCmd = (wrap) => buildDevCmd('acls', 'sys_security_acl', ['acl'], ['name', 'operation', 'type', 'active', 'sys_scope'], wrap, { singular: 'ACL', scopeValidation: true });

package/src/commands/dev/scrapi.js

@@ -0,0 +1,344 @@
+// Custom scraPI command: list/show individual operations + one-shot API definition creation
+//
+// The 'create' subcommand lets you build a full Scripted REST API in one call:
+//   jsn dev scrapi create \
+//     --name "SL Managed Services" --service-id managed_services --namespace slapi \
+//     --resource create=POST:/create:./create.js \
+//     --resource comment=POST:/comment:./comment.js
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { formatRecordForDisplay, getStringField, isHexString } from '../../helpers.js';
+import { errUsageHint } from '../../errors.js';
+
+/**
+ * Parse a --resource flag value of the form:
+ *   name=METHOD:/path:./script.js
+ * Returns { name, method, relativePath, scriptFile } or null.
+ */
+function parseResourceArg(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+
+  // Split on first '=' to get name and the rest
+  const eqIdx = raw.indexOf('=');
+  if (eqIdx === -1) return null;
+  const name = raw.slice(0, eqIdx).trim();
+  const rest = raw.slice(eqIdx + 1).trim();
+
+  // Rest should be METHOD:/path:./script.js
+  // Split on first ':' to separate METHOD from the path:file part
+  const colonIdx = rest.indexOf(':');
+  if (colonIdx === -1) return null;
+  const method = rest.slice(0, colonIdx).trim().toUpperCase();
+  const pathFile = rest.slice(colonIdx + 1).trim();
+
+  // Split pathAndFile on last ':' to separate relative_path from script file
+  const lastColon = pathFile.lastIndexOf(':');
+  if (lastColon === -1) return null;
+  const relativePath = pathFile.slice(0, lastColon).trim();
+  const scriptFile = pathFile.slice(lastColon + 1).trim();
+
+  if (!relativePath.startsWith('/')) {
+    return null; // relative_path must start with /
+  }
+
+  return { name, method, relativePath, scriptFile };
+}
+
+/**
+ * Read script content from a file path (relative to cwd or absolute).
+ */
+function readScriptFile(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw errUsageHint(
+      `Script file not found: ${filePath}`,
+      `Checked: ${resolved}`
+    );
+  }
+  return fs.readFileSync(resolved, 'utf-8');
+}
+
+export function scrapiCmd(wrap) {
+  return {
+    command: 'scrapi [subcommand]',
+    aliases: ['scripted-rest', 'rest-api'],
+    describe: 'Manage Scripted REST APIs (list/show operations, create full APIs with resources)',
+    builder: (yargs) => {
+      return yargs
+        // ── list ──
+        .command({
+          command: 'list',
+          aliases: ['ls'],
+          describe: 'List API operations',
+          builder: (y) => y
+            .option('query', { type: 'string', describe: 'Encoded query (e.g. "nameLIKEincident")' })
+            .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns' })
+            .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' }),
+          handler: wrap(async (argv, app) => {
+            const columns = argv.columns ? argv.columns.split(',') : ['name', 'sys_ws_definition', 'http_method', 'relative_path', 'sys_scope'];
+            const query = argv.query || '';
+            const limit = argv.limit;
+
+            const params = new URLSearchParams();
+            params.set('sysparm_limit', String(limit));
+            params.set('sysparm_display_value', 'all');
+            params.set('sysparm_fields', ['sys_id', ...columns].join(','));
+            const q = query ? query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
+            params.set('sysparm_query', q);
+            const records = await app.sdk.list('sys_ws_operation', params);
+
+            app.ok({
+              table: 'sys_ws_operation',
+              count: records.length,
+              columns,
+              records: records.map(r => formatRecordForDisplay(r, columns)),
+              context: { instance_url: app.getEffectiveInstance() },
+            }, {
+              summary: `${records.length} operation(s)`,
+              breadcrumbs: [
+                { action: 'create', cmd: 'jsn dev scrapi create --name "My API" --service-id my-api --namespace myapp --resource get=GET:/items:./script.js', description: 'Create a new REST API' },
+                { action: 'show', cmd: 'jsn dev scrapi show <name>', description: 'Show operation details' },
+              ],
+            });
+          }),
+        })
+        // ── show ──
+        .command({
+          command: 'show <identifier>',
+          aliases: ['get'],
+          describe: 'Show an API definition or operation by service_id, name, or sys_id — includes child resources',
+          handler: wrap(async (argv, app) => {
+            const id = argv.identifier;
+            const isSysId = isHexString(id) && id.length === 32;
+
+            // 1. Try to find a sys_ws_operation by name or sys_id
+            const opParams = new URLSearchParams();
+            opParams.set('sysparm_query', `${isSysId ? 'sys_id' : 'name'}=${id}`);
+            opParams.set('sysparm_limit', '1');
+            opParams.set('sysparm_display_value', 'all');
+            let records = await app.sdk.list('sys_ws_operation', opParams);
+
+            if (records.length > 0) {
+              // Found an operation — show it directly
+              records[0]._context = {
+                instance_url: app.getEffectiveInstance(),
+                table: 'sys_ws_operation',
+              };
+              return app.ok(records[0], {
+                summary: `Operation: ${getStringField(records[0], 'name') || id}`,
+                breadcrumbs: [
+                  { action: 'list', cmd: 'jsn dev scrapi list', description: 'Back to all operations' },
+                ],
+              });
+            }
+
+            // 2. Try to find a sys_ws_definition by service_id, name, or sys_id
+            const defQuery = isSysId
+              ? `sys_id=${id}`
+              : `service_id=${id}^ORname=${id}`;
+            const defParams = new URLSearchParams();
+            defParams.set('sysparm_query', defQuery);
+            defParams.set('sysparm_limit', '1');
+            defParams.set('sysparm_display_value', 'all');
+            const defRecords = await app.sdk.list('sys_ws_definition', defParams);
+
+            if (defRecords.length === 0) {
+              throw new Error(`No API or operation found matching: ${id}`);
+            }
+
+            const definition = defRecords[0];
+            const defName = getStringField(definition, 'name');
+            const defSysId = definition.sys_id?.value || definition.sys_id;
+
+            // 3. Fetch child operations for this definition
+            const childParams = new URLSearchParams();
+            childParams.set('sysparm_query', `web_service_definition=${defSysId}`);
+            childParams.set('sysparm_limit', '50');
+            childParams.set('sysparm_display_value', 'all');
+            childParams.set('sysparm_fields', 'sys_id,name,http_method,relative_path,active');
+            const childOps = await app.sdk.list('sys_ws_operation', childParams);
+
+            // Build a formatted display
+            const instanceURL = app.getEffectiveInstance();
+            const defLink = `${instanceURL}/sys_ws_definition.do?sys_id=${defSysId}`;
+
+            let formatted = `\n${defName} (Scripted REST API)\n`;
+            formatted += `${'─'.repeat(defName.length + 22)}\n\n`;
+            formatted += `  service_id:     ${getStringField(definition, 'service_id')}\n`;
+            formatted += `  namespace:      ${getStringField(definition, 'namespace')}\n`;
+            formatted += `  scope:          ${getStringField(definition, 'sys_scope')}\n`;
+            formatted += `  base_uri:       ${getStringField(definition, 'base_uri')}\n`;
+            formatted += `  description:    ${(getStringField(definition, 'description') || '(none)').slice(0, 60)}\n`;
+            formatted += `\n  Link: ${defLink}\n`;
+
+            if (childOps.length > 0) {
+              formatted += `\n  ── Resources (${childOps.length}) ──\n\n`;
+              for (const op of childOps) {
+                const opName = getStringField(op, 'name');
+                const method = getStringField(op, 'http_method');
+                const relPath = getStringField(op, 'relative_path');
+                const active = getStringField(op, 'active');
+                formatted += `    ${(method + '  ').slice(0, 7)} ${relPath.padEnd(30)} ${opName}${active !== 'true' ? ' (inactive)' : ''}\n`;
+              }
+            } else {
+              formatted += `\n  (no resources — run jsn dev scrapi create --resource ... to add some)\n`;
+            }
+
+            app.ok({
+              _formatted: formatted,
+              definition: {
+                sys_id: defSysId,
+                name: defName,
+                service_id: getStringField(definition, 'service_id'),
+                namespace: getStringField(definition, 'namespace'),
+                base_uri: getStringField(definition, 'base_uri'),
+                scope: getStringField(definition, 'sys_scope'),
+                description: getStringField(definition, 'description'),
+                link: defLink,
+              },
+              resources: childOps.map(op => ({
+                name: getStringField(op, 'name'),
+                method: getStringField(op, 'http_method'),
+                relative_path: getStringField(op, 'relative_path'),
+                active: getStringField(op, 'active'),
+              })),
+              _context: { instance_url: instanceURL, table: 'sys_ws_definition' },
+            }, {
+              summary: `API: ${defName} — ${childOps.length} resource(s)`,
+              breadcrumbs: [
+                { action: 'create', cmd: 'jsn dev scrapi create --name "..." --service-id ... --namespace ... --resource ...', description: 'Create a new API' },
+                { action: 'list', cmd: 'jsn dev scrapi list', description: 'Back to all operations' },
+              ],
+            });
+          }),
+        })
+        // ── create (one-shot API + operations) ──
+        .command({
+          command: 'create',
+          describe: 'Create a new Scripted REST API with operations in one command',
+          builder: (y) => y
+            .option('name', { type: 'string', demandOption: true, describe: 'API name (e.g. "SL Managed Services")' })
+            .option('service-id', { type: 'string', demandOption: true, describe: 'Service ID (e.g. "managed_services")' })
+            .option('namespace', { type: 'string', demandOption: true, describe: 'API namespace (e.g. "slapi")' })
+            .option('resource', {
+              type: 'string',
+              array: true,
+              demandOption: true,
+              describe: 'Resource definition: name=METHOD:/path:./script.js (can be repeated)',
+            })
+            .option('description', { type: 'string', describe: 'API description' })
+            .option('scope', { type: 'string', describe: 'Scope name or sys_id (default: current scope)' }),
+          handler: wrap(async (argv, app) => {
+            if (!app.sdk) throw new Error('Not connected to a ServiceNow instance');
+
+            // 1. Parse and validate all resources first
+            const resources = [];
+            for (const raw of argv.resource) {
+              const parsed = parseResourceArg(raw);
+              if (!parsed) {
+                throw errUsageHint(
+                  `Invalid --resource format: ${raw}`,
+                  'Expected: name=METHOD:/path:./script.js  e.g. create=POST:/create:./create.js'
+                );
+              }
+              const script = readScriptFile(parsed.scriptFile);
+              resources.push({ ...parsed, script });
+            }
+
+            const apiName = argv.name;
+            const serviceId = argv['service-id'];
+            const namespace = argv.namespace;
+            const description = argv.description || '';
+
+            // 2. Resolve scope if provided
+            let scopeSysId = null;
+            if (argv.scope) {
+              scopeSysId = await app.sdk.resolveScope(argv.scope);
+              if (!scopeSysId) {
+                throw new Error(`Scope not found: ${argv.scope}`);
+              }
+            }
+
+            // 3. Create the API definition (sys_ws_definition)
+            const definitionData = {
+              name: apiName,
+              service_id: serviceId,
+              namespace,
+              description,
+            };
+            if (scopeSysId) {
+              definitionData.sys_scope = scopeSysId;
+            }
+
+            const definition = await app.sdk.create('sys_ws_definition', definitionData);
+            const defSysId = definition?.sys_id?.value || definition?.sys_id;
+            if (!defSysId) {
+              throw new Error('API definition creation returned no sys_id — check for validation errors');
+            }
+
+            // 4. Create each operation (sys_ws_operation)
+            const operations = [];
+            for (const res of resources) {
+              const opData = {
+                name: res.name,
+                http_method: res.method,
+                relative_path: res.relativePath,
+                operation_script: res.script,
+                web_service_definition: defSysId,
+              };
+              // Set the scope so the operation inherits the API's scope
+              if (scopeSysId) {
+                opData.sys_scope = scopeSysId;
+              }
+              const operation = await app.sdk.create('sys_ws_operation', opData);
+              operations.push(operation?.result || operation);
+            }
+
+            // 5. Report
+            const instanceURL = app.getEffectiveInstance();
+            const apiURL = `${instanceURL}/sys_ws_definition.do?sys_id=${defSysId}`;
+
+            app.ok({
+              api_definition: {
+                sys_id: defSysId,
+                name: apiName,
+                service_id: serviceId,
+                namespace,
+                link: apiURL,
+              },
+              operations: operations.map((op, i) => ({
+                name: resources[i].name,
+                method: resources[i].method,
+                relative_path: resources[i].relativePath,
+              })),
+            }, {
+              summary: `Created API "${apiName}" with ${operations.length} operation(s)`,
+              notice: `View API: ${apiURL}`,
+              breadcrumbs: [
+                { action: 'show', cmd: `jsn dev scrapi list --query "web_service_definition=${defSysId}"`, description: 'List operations for this API' },
+                { action: 'add', cmd: `jsn dev scrapi add-resource --api "${serviceId}" --name <name>=METHOD:/path:./script.js`, description: 'Add another resource' },
+              ],
+            });
+          }),
+        });
+    },
+    // Default handler when no subcommand matches
+    handler: () => {
+      console.log('Manage Scripted REST APIs.');
+      console.log('');
+      console.log('Available subcommands:');
+      console.log('  list        List API operations');
+      console.log('  show        Show an operation by name or sys_id');
+      console.log('  create      Create a new API with operations (one-shot)');
+      console.log('');
+      console.log('Examples:');
+      console.log('  jsn dev scrapi list');
+      console.log('  jsn dev scrapi show my_operation');
+      console.log('  jsn dev scrapi create \\');
+      console.log('    --name "My API" --service-id my-api --namespace myapp \\');
+      console.log('    --resource "create=POST:/create:./create.js" \\');
+      console.log('    --resource "list=GET:/list:./list.js"');
+    },
+  };
+}

package/src/commands/dev.js

@@ -4,7 +4,7 @@ import {
   actionsCmd, includesCmd, rulesCmd,
   clientScriptsCmd, uiActionsCmd, uiPoliciesCmd,
   tablesCmd, columnsCmd, importCmd,
-  spPagesCmd, spWidgetsCmd, uiPagesCmd, appMenuCmd, scRAPICmd,
+  spPagesCmd, spWidgetsCmd, uiPagesCmd, appMenuCmd,
   aclsCmd, rolesCmd, propertiesCmd,
   relationshipsCmd, appmodulesCmd, listcontrolsCmd, viewsCmd,
   privilegesCmd, securitytypesCmd, uxscriptsCmd, aliasesCmd,
@@ -18,6 +18,7 @@ import { scopesCmd } from './dev/scopes.js';
 import { evalCmd } from './dev/eval.js';
 import { restCmd } from './dev/rest.js';
 import { logsCmd } from './dev/logs.js';
+import { scrapiCmd } from './dev/scrapi.js';
 
 export function devCmd(wrap) {
   return {
@@ -41,7 +42,7 @@ export function devCmd(wrap) {
         .command(spWidgetsCmd(wrap))
         .command(uiPagesCmd(wrap))
         .command(appMenuCmd(wrap))
-        .command(scRAPICmd(wrap))
+        .command(scrapiCmd(wrap))
         .command(aclsCmd(wrap))
         .command(rolesCmd(wrap))
         .command(updateSetsCmd(wrap))

package/src/commands/records.js

@@ -1,4 +1,4 @@
-import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam } from '../helpers.js';
+import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields } from '../helpers.js';
 
 const tableDefaultColumns = {
   incident: ['number', 'short_description', 'priority', 'state', 'assigned_to'],
@@ -133,9 +133,14 @@ export function recordsCmd(wrap) {
           builder: (y) => y
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
-            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' }),
           handler: wrap(async (argv, app) => {
             const recordData = parseDataArg(argv);
+            const warnings = checkDerivedFields(argv.table, recordData);
+            for (const w of warnings) {
+              process.stderr.write(`⚠ ${w.hint}\n`);
+            }
             const record = await app.sdk.create(argv.table, recordData);
             app.ok(record, { summary: `Created record in ${argv.table}` });
           }),
@@ -147,9 +152,14 @@ export function recordsCmd(wrap) {
             .option('table', { type: 'string', demandOption: true, describe: 'Table name' })
             .option('sys-id', { type: 'string', demandOption: true, describe: 'Record sys_id' })
             .option('data', { type: 'string', describe: 'JSON fields (e.g. \'{"state":"2"}\')' })
-            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' }),
+            .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
+            .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin (pipe-friendly)' }),
           handler: wrap(async (argv, app) => {
             const recordData = parseDataArg(argv);
+            const warnings = checkDerivedFields(argv.table, recordData);
+            for (const w of warnings) {
+              process.stderr.write(`⚠ ${w.hint}\n`);
+            }
             const record = await app.sdk.update(argv.table, argv['sys-id'], recordData);
             app.ok(record, { summary: `Updated record in ${argv.table}` });
           }),

package/src/commands/skill.js

@@ -1,17 +1,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+const SKILL_NAME = 'servicenow';
 const SKILL_REPO_PATH = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
-  '..', '..', 'skills', 'servicenow', 'SKILL.md'
+  '..', '..', 'skills', SKILL_NAME, 'SKILL.md'
 );
 
-const HERMES_SKILL_PATH = path.join(os.homedir(), '.hermes', 'skills', 'servicenow', 'SKILL.md');
+const HERMES_SKILL_PATH = path.join(os.homedir(), '.hermes', 'skills', SKILL_NAME, 'SKILL.md');
 
 const SKILL_RAW_URL = 'https://raw.githubusercontent.com/jacebenson/jsn/nodejs/skills/servicenow/SKILL.md';
 
+// Known agent skill directories (personal/user-level)
+// Keyed by agent name for the --target flag
+const AGENT_SKILL_DIRS = {
+  hermes: path.join(os.homedir(), '.hermes', 'skills', SKILL_NAME),
+  copilot: path.join(os.homedir(), '.copilot', 'skills', SKILL_NAME),
+  claude: path.join(os.homedir(), '.claude', 'skills', SKILL_NAME),
+  cursor: path.join(os.homedir(), '.cursor', 'rules'),
+  agents: path.join(os.homedir(), '.agents', 'skills', SKILL_NAME),
+};
+
+const TARGET_NAMES = {
+  hermes: 'Hermes Agent',
+  copilot: 'GitHub Copilot',
+  claude: 'Claude Code',
+  cursor: 'Cursor',
+  agents: 'Agents (open standard)',
+};
+
 function readBundledSkill() {
   try {
     return fs.readFileSync(SKILL_REPO_PATH, 'utf-8');
@@ -115,18 +135,23 @@ export function skillCmd(wrap) {
           command: 'path',
           describe: 'Show skill file locations and install targets',
           handler: wrap(async (_argv, app) => {
-            const hermesDir = path.join(os.homedir(), '.hermes', 'skills', 'servicenow');
-            const hermesPath = path.join(hermesDir, 'SKILL.md');
+            const allPaths = {};
+            for (const [key, dir] of Object.entries(AGENT_SKILL_DIRS)) {
+              const file = key === 'cursor' ? path.join(dir, `${SKILL_NAME}.mdc`) : path.join(dir, 'SKILL.md');
+              allPaths[TARGET_NAMES[key]] = file;
+            }
+
             app.ok({
               bundled: SKILL_REPO_PATH,
-              hermes: hermesPath,
+              targets: allPaths,
               raw_url: SKILL_RAW_URL,
             }, {
-              summary: 'Skill file locations',
+              summary: 'Skill file locations and install targets',
               breadcrumbs: [
-                { action: 'view', cmd: 'jsn skill show', description: 'Show bundled skill content' },
-                { action: 'fetch', cmd: 'jsn skill fetch', description: 'Download latest from GitHub' },
-                { action: 'install', cmd: 'jsn skill install', description: 'Download + save to Hermes' },
+                { action: 'install', cmd: 'jsn skill install', description: 'Install to Hermes (default)' },
+                { action: 'install-all', cmd: 'jsn skill install --target all', description: 'Install to all supported agents' },
+                { action: 'install-copilot', cmd: 'jsn skill install --target copilot', description: 'Install for GitHub Copilot' },
+                { action: 'install-claude', cmd: 'jsn skill install --target claude', description: 'Install for Claude Code' },
               ],
             });
           }),
@@ -137,30 +162,71 @@ export function skillCmd(wrap) {
           builder: (y) => y
             .positional('dir', {
               type: 'string',
-              describe: 'Target directory (default: ~/.hermes/skills/servicenow/)',
+              describe: 'Target directory (overrides --target; installs only to this dir)',
+            })
+            .option('target', {
+              type: 'string',
+              describe: 'Target agent(s): hermes, copilot, claude, cursor, agents, or "all" (comma-separated)',
+              default: 'hermes',
             }),
           handler: wrap(async (argv, app) => {
-            const targetDir = argv.dir || path.join(os.homedir(), '.hermes', 'skills', 'servicenow');
-            const targetPath = path.join(targetDir, 'SKILL.md');
-
-            fs.mkdirSync(targetDir, { recursive: true });
-
             const res = await fetch(SKILL_RAW_URL);
             if (!res.ok) throw new Error(`Failed to fetch skill: ${res.status} ${res.statusText}`);
             const content = await res.text();
 
-            fs.writeFileSync(targetPath, content, 'utf-8');
+            // Resolve target directories
+            let targets = [];
 
-            app.ok({
-              installed: targetPath,
-              from: SKILL_RAW_URL,
-            }, {
-              summary: `Skill installed to ${targetPath}`,
+            if (argv.dir) {
+              // Explicit --dir overrides targets — single install
+              const p = path.resolve(argv.dir);
+              fs.mkdirSync(p, { recursive: true });
+              const targetPath = path.join(p, 'SKILL.md');
+              fs.writeFileSync(targetPath, content, 'utf-8');
+              targets.push({ name: path.basename(argv.dir), path: targetPath });
+            } else {
+              const rawTargets = argv.target.split(',').map(t => t.trim().toLowerCase());
+              const all = rawTargets.includes('all');
+
+              for (const [key, dir] of Object.entries(AGENT_SKILL_DIRS)) {
+                if (all || rawTargets.includes(key)) {
+                  // For cursor, the skill goes in a .mdc file, not a subfolder
+                  if (key === 'cursor') {
+                    fs.mkdirSync(dir, { recursive: true });
+                    const targetPath = path.join(dir, `${SKILL_NAME}.mdc`);
+                    fs.writeFileSync(targetPath, content, 'utf-8');
+                    targets.push({ name: TARGET_NAMES[key], path: targetPath });
+                  } else {
+                    fs.mkdirSync(dir, { recursive: true });
+                    const targetPath = path.join(dir, 'SKILL.md');
+                    fs.writeFileSync(targetPath, content, 'utf-8');
+                    targets.push({ name: TARGET_NAMES[key], path: targetPath });
+                  }
+                }
+              }
+            }
+
+            if (targets.length === 0) {
+              throw new Error(`No targets matched. Valid targets: ${Object.keys(AGENT_SKILL_DIRS).join(', ')}, or "all"`);
+            }
+
+            const installed = targets.reduce((acc, t) => { acc[t.name] = t.path; return acc; }, {});
+            const summary = targets.length === 1
+              ? `Skill installed to ${targets[0].path}`
+              : `Skill installed to ${targets.length} target(s)`;
+
+            const okOpts = {
+              summary,
               breadcrumbs: [
-                { action: 'verify', cmd: `head -30 ${targetPath}`, description: 'Verify the installed skill' },
-                { action: 'reinstall', cmd: 'jsn skill install', description: 'Re-download and reinstall' },
+                { action: 'reinstall', cmd: 'jsn skill install', description: 'Re-download and reinstall to default target' },
               ],
-            });
+            };
+
+            if (targets.length > 1) {
+              okOpts.notice = 'Installed to multiple agents. Restart or reload your agent to pick up the skill.';
+            }
+
+            app.ok({ installed, from: SKILL_RAW_URL }, okOpts);
           }),
         });
     },

package/src/errors.js

@@ -79,7 +79,34 @@ export function errAPI(status, msg) {
   if (status >= 500) {
     hint = 'The ServiceNow instance may be experiencing issues. Try again later.';
   }
-  return new AppError(CodeAPI, `API error (status ${status}): ${msg}`, hint, status);
+
+  // Try to extract structured error detail from JSON API error bodies
+  let displayMsg = msg;
+  if (typeof msg === 'string' && (msg.startsWith('{') || msg.startsWith('['))) {
+    try {
+      const parsed = JSON.parse(msg);
+      const errObj = parsed.error || parsed;
+      const detail = errObj.detail || errObj.message || '';
+      const message = errObj.message || '';
+
+      if (detail && message) {
+        displayMsg = `${message}: ${detail}`;
+      } else if (detail) {
+        displayMsg = detail;
+      } else if (message) {
+        displayMsg = message;
+      }
+
+      // Detect business rule abortion and add a hint
+      if (detail && detail.includes('Business Rule')) {
+        hint = 'A Business Rule rejected this operation. Check for overlapping routes, validation rules, or ACLs on this table.';
+      }
+    } catch {
+      // Not valid JSON, use original message
+    }
+  }
+
+  return new AppError(CodeAPI, `API error (status ${status}): ${displayMsg}`, hint, status);
 }
 
 export function errAmbiguous(resource, matches) {

package/src/helpers.js

@@ -135,25 +135,80 @@ function vowelArticle(word) {
 }
 
 /**
- * Parse --data or --data-file into a JSON object.
- * If --data-file is given, reads the file. Otherwise parses --data directly.
- * Throws if neither is provided or JSON is invalid.
+ * Known derived (read-only) ServiceNow fields that should not be set directly.
+ * Maps table name → array of field names that are computed by the platform.
+ * When a create/update payload contains these, a warning is emitted.
+ */
+export const DERIVED_FIELDS = {
+  sys_ws_operation: ['operation_uri'],
+  sys_ws_definition: ['base_uri'],
+  incident: ['sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'sys_mod_count'],
+  change_request: ['sys_created_on', 'sys_updated_on', 'sys_created_by', 'sys_updated_by', 'sys_mod_count'],
+  // Generic — all sys_ fields are system-managed
+};
+
+/**
+ * Check a data payload for fields that appear to be derived/read-only.
+ * Returns an array of warning objects ({field, hint}) for any matches.
+ * @param {string} table - Table name (e.g. 'sys_ws_operation')
+ * @param {object} data - The JSON payload being sent
+ * @returns {Array<{field: string, hint: string}>}
+ */
+export function checkDerivedFields(table, data) {
+  if (!data || typeof data !== 'object') return [];
+  const warnings = [];
+
+  // Check explicitly known derived fields for this table
+  const knownFields = DERIVED_FIELDS[table] || [];
+  for (const field of knownFields) {
+    if (field in data && data[field] != null) {
+      warnings.push({
+        field,
+        hint: `${field} is a derived/read-only field. Setting it directly will be ignored.`,
+      });
+    }
+  }
+
+  // Warn about any sys_* fields that look like system-managed metadata
+  // (but be careful — not all sys_ fields are read-only)
+  if (data.sys_created_on) {
+    warnings.push({
+      field: 'sys_created_on',
+      hint: 'sys_created_on is a system-managed field. Setting it directly will be ignored.',
+    });
+  }
+  if (data.sys_updated_on) {
+    warnings.push({
+      field: 'sys_updated_on',
+      hint: 'sys_updated_on is a system-managed field. Setting it directly will be ignored.',
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Parse --data, --data-file, or --data-stdin into a JSON object.
+ * Priority: --data-file > --data-stdin > --data
+ * Throws if none is provided or JSON is invalid.
  */
 export function parseDataArg(argv) {
   let raw;
   if (argv['data-file']) {
     raw = fs.readFileSync(argv['data-file'], 'utf-8');
-    // Strip UTF-8 BOM (\ufeff) which some editors (Windows/PowerShell) add
+    // Strip UTF-8 BOM (\\ufeff) which some editors (Windows/PowerShell) add
     if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+  } else if (argv['data-stdin']) {
+    raw = fs.readFileSync(process.stdin.fd, 'utf-8');
   } else if (argv.data) {
     raw = argv.data;
   } else {
-    throw new Error('--data or --data-file is required');
+    throw new Error('--data, --data-file, or --data-stdin is required');
   }
   try {
     return JSON.parse(raw);
   } catch (e) {
-    throw new Error(`Invalid JSON: ${e.message}\n\nHint: On Windows PowerShell, use --data-file instead of --data to avoid quote mangling.\nRaw value: ${raw.substring(0, 200)}`, { cause: e });
+    throw new Error(`Invalid JSON: ${e.message}\n\nHint: Use --data-file for multiline payloads to avoid shell escaping issues.\nRaw value: ${raw.substring(0, 200)}`, { cause: e });
   }
 }