@jacebenson/jsn 4.3.8 → 4.3.9-dev.62

package/README.md

@@ -1,445 +1,39 @@
-# JSN — ServiceNow CLI
+# JSN: ServiceNow CLI
 
-A command-line interface for ServiceNow. Type `jsn` and start working — no web UI needed.
-
-Works standalone or with AI agents (Claude Code, OpenCode, Hermes, Cursor, Copilot).
+A command-line interface for ServiceNow. Read and update records, manage flows, inspect platform data, and automate routine work from your terminal or AI agent.
 
 ## Install
 
-```bash
-npm install -g @jacebenson/jsn
-```
-
-Node.js 22.5.0 or newer. macOS, Linux, Windows.
-
-The install also copies an AI agent skill file to `~/.agents/skills/servicenow/SKILL.md`.
-
-### Install from GitHub (test unreleased builds)
-
-To test a branch or the freshly merged `main` before it's published to npm:
-
-```bash
-npm install -g github:jacebenson/jsn#main        # merged but not yet tagged
-npm install -g github:jacebenson/jsn#<branch>    # any PR/feature branch
-```
-
-Go back to the released version with:
+Requires Node.js 22.5.0 or newer. Supports macOS, Linux, and Windows.
 
 ```bash
 npm install -g @jacebenson/jsn
+jsn setup
 ```
 
-**Note:** git installs build `better-sqlite3` (docs search) from source, so the machine needs build tools (Python, make, a C++ compiler).
-
-## Direct MID installation
-
-```sh
-jsn midservers add --install-method direct --name worker1
-```
-
-Official x86-64 ZIPs for Linux and Windows, selected from the instance's
-`mid.version`. Credentials are prompted and validated before installation.
-Linux supports a user-owned background runtime. Windows currently prepares
-private files and offers a foreground console, not native service registration.
-See [direct MID installation](docs/mid-direct-install.md) for security boundaries,
-lifecycle commands and the untested Windows host phases. Docker remains available.
-
-## Quick Start
-
-```bash
-jsn setup                                    # Interactive: add, switch, remove, modify instances
-jsn incidents list --query "priority=1"      # Critical incidents
-```
-
-## What It Does
+See the [setup guide](docs/docs-setup.md) to connect an instance safely.
 
-jsn talks to the ServiceNow REST API. Read, create, update, delete — tickets, users, groups, records on any table. Inspect flows and business rules. Export update sets. Run background scripts.
-
-Everything outputs JSON when piped, styled tables in a terminal.
+## Try it
 
 ```bash
-# Core ticket work
 jsn incidents list --query "active=true^priority=1"
-jsn incidents INC0010001
-jsn incidents create --description "Server down" --priority 1
-
-# Admin tasks
-jsn flows list                                # Interactive picker with pagination
-jsn flows show "Assign Task"                  # Full flow detail
-jsn flows executions                          # All states, newest first
-jsn flows executions --active                  # Only waiting/running/queued
-jsn flows executions --since "2026-08-25 00:00:00" --until "2026-08-26 00:00:00"
-jsn flows executions --summary                 # Server totals + sampled duration metrics by flow
-jsn flows executions --limit 100               # Inspect more rows from the matching population
-jsn flows executions --record <sys_id>        # Executions for one source record
-jsn flows create --data-file flow.manifest.json # Create a draft record-triggered flow
-jsn rules list --query "collection=incident"
-jsn updatesets set "My Feature"
-
-# Generic table access
-jsn records list --table incident --limit 50 --json | jq '.data.records[].number'
-jsn records create --table incident --data '{"short_description":"test"}'
-jsn records list --table incident --limit 50 --get "data.records.0.number"   # no jq needed
-jsn records list --table incident --query "active=true"                       # totals included by default
-jsn records list --table incident --limit 10 --no-count                       # opt out of the total query
-jsn records bulk --table incident --query "priority=1" --set '{"state":"3"}'  # dry-run by default
-jsn records get --table incident --sys-id 8a1234abcd5678 --attachments        # record + its files
-jsn records list --table incident --limit 10 --csv                            # output CSV
-
-# Read-only cross-profile record diff
-jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod
-jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --ignore state
-jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --no-ignore
-
-# Script execution
-jsn eval "gs.info('Hello World')"
-cat script.js | jsn eval --stdin          # pipe a script in (no shell escaping)
-
-# Now GraphQL (documents may contain mutations; read-only profiles are blocked)
-jsn graphql --query '{ GlideRecord_Query { incident(pagination: {limit: 2}) { _results { number { value } } } } }'
-cat incident.graphql | jsn graphql --stdin --variables '{"limit":2}'
-
-# Saved query snippets (stored locally, run against the active profile)
-jsn snippets save open-inc --table incident --query "active=true"
-jsn snippets run open-inc
-
-# Live log tailing (Ctrl+C to stop)
-jsn logs follow --level error --tail 10
-```
-
-### Flow Designer actions
-
-`actions` and `action` are the same command. `list`, `show`, and explicit
-`delete` remain available. In a human terminal, omit the target to open a
-searchable picker. Create and edit guide you through provider schemas and save
-full Process Flow definitions, not ordinary table-field updates.
-
-```bash
-jsn actions create                 # Guided scope, name, schemas, inputs and script
-jsn actions edit                   # Pick an action, edit its saved definition
-jsn actions definition             # Pick and inspect a complete definition
-jsn actions test --wait            # Pick an action, supply saved-schema inputs, confirm
-jsn actions step-types             # Pick the exact transaction scope
-```
-
-Script inputs offer a file path or your `$VISUAL`/`$EDITOR`. New script steps can
-declare outputs and map them to action outputs. Variable declarations reuse
-provider schema templates and receive fresh UI identities. Unknown nested
-schema fields are retained. Unsupported input types stop with instructions to
-use `--data-file`; JSN does not silently omit them or invent schema defaults.
-Creation waits for an explicit final confirmation before allocating a parent.
-It saves a draft only and never publishes or runs it automatically.
-
-For automation, keep using explicit identifiers and full JSON:
-
-```bash
-jsn actions step-types --scope <scope_sys_id> --get data > step-types.json
-jsn actions create --scope <scope_sys_id> --data-file new-action.json --json
-jsn actions definition <action_sys_id> --get data > action.json
-# Edit action.json, retaining its ID, scope, lifecycle fields and all arrays.
-jsn actions update <action_sys_id> --data-file action.json --json
-jsn action edit <action_sys_id> --data-file action.json --json  # same operation
-jsn actions test <action_sys_id> --force --output-map '{"response":"hello"}' --wait --timeout 60 --json
-jsn actions test <action_sys_id> --force --data-file action.json --output-map '{"response":"hello"}' --wait --get data.outputs.response.value
-jsn actions delete <action_sys_id> --force  # explicit cleanup, never automatic
+jsn records list --table incident --limit 10 --json
+jsn flows list
 ```
 
-Existing targets infer their exact transaction scope from the action record.
-An explicit `--scope` must match that record byte-for-byte and exist in
-`sys_scope`. For Global, use the literal sys_id `global`.
-
-This **illustrative create document** shows an input/script/output mapping.
-Replace `<SCRIPT_STEP_TYPE_SYS_ID>` with the target's `step-types` result.
-Start from that step type's full input/output schemas, preserving runtime
-settings, status outputs and any other required fields. The shortened example
-is not a captured or instance-verified template. New steps/variables need their
-own identifiers; do not clone another action's record IDs. Leave new steps'
-`step_id` and `action` blank or omitted. Create binds their `action` to the newly
-allocated parent; persisted step IDs or parent bindings are rejected before creation.
-
-```json
-{
-  "name": "Echo response",
-  "description": "Return the supplied response",
-  "internal_name": "echo_response",
-  "inputs": [{"name": "response", "label": "Response", "type": "string", "mandatory": true}],
-  "outputs": [{"name": "response", "label": "Response", "type": "string", "value": "{{step[11111111-2222-4333-8444-555555555555].response}}"}],
-  "steps": [{
-    "cid": "11111111-2222-4333-8444-555555555555",
-    "step_type": "SCRIPT",
-    "step_type_id": "<SCRIPT_STEP_TYPE_SYS_ID>",
-    "label": "Echo script",
-    "order": 1,
-    "inputs": [
-      {"name": "required_run_time", "type": "choice", "value": "instance"},
-      {"name": "script", "type": "script", "value": "(function execute(inputs, outputs) { outputs.response = inputs.response; })(inputs, outputs);"}
-    ],
-    "outputs": [],
-    "extended_inputs": [{"name": "response", "type": "string", "value": "{{inputs.response}}", "extended": true}],
-    "extended_outputs": [{"name": "response", "type": "string", "extended": true}]
-  }]
-}
-```
+Run `jsn --help` for the command list. See the [CLI guide](docs/cli-guide.md) for authentication, output formats, development, and examples. The [docs site](https://jacebenson.github.io/jsn/) has feature guides.
 
-Create first inserts the parent in `sys_hub_action_type_definition`, reads that
-parent's own Process Flow defaults, then saves the inputs, outputs and nonempty
-steps with the internal `/api/now/processflow/action/action_types/{id}` PUT.
-It retains fresh lifecycle/status metadata instead of copying source snapshot
-or status IDs. A subsequent definition GET plus `/step_instances` GET verifies
-scripts, mappings and schemas. Update requires a complete document from
-`definition`, including target-owned lifecycle fields. Omitted fields are
-rejected before mutation. A PUT timeout triggers readback, not another PUT;
-`persisted_after_timeout` means persistence was verified, not that HTTP success
-was received. Failed creation reports the parent ID and leaves cleanup to you.
-
-Test sends `action`, `outputMap`, `runOnThread` and `tracingEnabled` to `/test`.
-Despite its wire name, `--output-map` supplies **action inputs**. Without
-`--wait`, success means dispatch only, with `status: dispatched` and no outputs.
-With `--wait`, JSN requires a `COMPLETE` context, blank `error_message`, and each
-declared user output's actual value from `sys_flow_runtime_value`. Output entries
-have `value`, `displayValue` and `hasValue`; false, zero and empty strings count.
-Failures, denied/missing outputs and timeouts exit nonzero. The wait budget
-starts after dispatch, defaults to 60 seconds, and is capped at 3600 seconds.
-Timeout does not cancel the server execution. Draft actions can be tested without
-publication. Testing runs their scripts and can have side effects. It requires
-interactive confirmation or `--force`, unless the profile explicitly skips
-confirmations. Read-only profiles block create/update/delete/test. No publish
-or snapshot command is added.
-These internal endpoints and runtime-table permissions can vary by instance.
-
-### Flow execution fields
-
-### Flow Designer terminal workflows
-
-```bash
-jsn flows create         # Guided record trigger and published action inputs
-jsn flows edit           # Pick an inactive Draft, edit condition or existing inputs
-jsn flows show           # Pick a flow to inspect
-jsn flows status         # Pick a flow to diagnose
-jsn flows test           # Pick flow and a record from its actual trigger table, confirm
-jsn flows publish        # Pick a flow, explicitly confirm activation
-# Automation must explicitly confirm publication too:
-jsn flows publish <flow_sys_id> --force --json
-```
-
-Wizards and omitted-target pickers require both a prompt-capable terminal and
-`auto` output. `--json`, explicit formats, `--get`, `--data`, `--data-file`,
-`--output-map`, pipes, `CI`, `NONINTERACTIVE` and `JSN_NO_PROMPTS=1` never open a
-wizard. In those modes provide identifiers and required scope/record/data
-explicitly. Tests, publish and deletion require `--force` or the profile's
-existing explicit skip-confirmations setting when prompting is unavailable.
-Read-only profiles still block mutations before authentication or prompting.
-Press Escape in record pickers or Ctrl+C in any wizard to cancel. Refusing a
-final confirmation leaves the instance untouched.
-
-Existing action/flow scopes come from saved raw identifiers. New scopes offer
-the active application preference if available, then a searchable scope picker.
-No scope name is guessed. Input pills are passed through unchanged.
-
-Flow edits are limited to the existing manifest contract. They do not rename
-flows, add/remove steps, implement Flow Logic, subflows, variables or error
-handling. Flow deletion remains unsupported. Action deletion retains its
-existing explicit parent-record cleanup and absence readback, not a new native
-builder deletion lifecycle. See [command coverage and local proof](docs/flow-designer-interactive.md).
-
-### Flow creation manifest
-
-`jsn flows create` accepts `--data-file` or inline `--data`, or guides human
-terminal users without those options. The supported slice
-supports one `record_create_or_update` trigger and published Action types whose
-input schemas are available from the instance. JSN resolves action metadata,
-defaults, and typed inputs from ServiceNow; callers do not provide GraphQL or
-editor-generated identifiers.
-
-```json
-{
-  "name": "JSN-STUDY-ticket-log",
-  "description": "Log JSN study tickets",
-  "scope": "<SCOPE_SYS_ID>",
-  "trigger": {
-    "type": "record_create_or_update",
-    "table": "ticket",
-    "condition": "short_descriptionSTARTSWITHJSN-STUDY-"
-  },
-  "actions": [
-    { "type": "Log", "inputs": { "log_level": "info", "log_message": "Ticket received" } }
-  ]
-}
-```
+## AI agents
 
-`scope` is required; JSN never defaults it to a tenant-specific or captured
-scope. The record-trigger condition currently accepts one simple encoded-query
-predicate (`fieldSTARTSWITHvalue`, `field=value`, `fieldLIKEvalue`, and the
-equivalent single-predicate operators). Compound `^`/`^OR` expressions are
-rejected until their predicate AST mapping is proven against the instance.
-
-Creation leaves the flow in Draft and inactive, then creates and reads back an
-Autosave version. `flows publish` remains a separate lifecycle operation: it
-reads the saved ProcessFlow definition, POSTs `/snapshot`, creates an
-`Activate/Publish` version, reads version history, and verifies `active=true`.
-Do not use it in a dry-run: publishing activates the flow.
-
-`jsn flows test <identifier> --record <sys_id>` is also a mutating operation.
-It requires confirmation (or `--force`), reads the saved definition, verifies
-that the supplied record exists in the record-trigger table, and POSTs the full
-definition to the ProcessFlow test endpoint. A response with only a context ID
-is reported as accepted, not completed. Test runs execute actions and can have
-side effects; this slice does not execute test flows during development.
-
-Flow Logic, subflows, flow-variable lifecycle, and error handling are deferred
-and rejected by this slice rather than silently ignored.
-
-`jsn flows update <identifier> --data-file update.json` updates supported fields
-of existing inactive Draft flows. The manifest may contain only `trigger` (with
-`table` and/or `condition`) and `actions`. Each action selects one saved instance
-by its one-based `order` and reusable action `type` (name or sys_id). Its `inputs`
-object may change only inputs already present in that saved Action. The CLI reads
-the saved component identities itself; manifests never carry UI UUIDs. Omitted
-trigger fields, Action inputs, metadata, and other flow components are preserved.
-Names must resolve to exactly one flow, and the protected `jace-test-flow` is
-rejected. Update sends the captured GraphQL `triggerInstances.update` and/or
-`actions.update` shapes, reads the full ProcessFlow definition back, creates an
-Autosave version, and reports update-set captures. It never publishes or
-activates the flow. Unsupported Flow Logic, subflows, variables, error handling,
-new Action inputs, ambiguous selectors, active flows, and non-Draft flows are
-rejected before mutation.
-
-`jsn flows executions` reads `sys_flow_context` and returns both the raw row and a normalized `execution` object. JSN discovers the runtime columns from `sys_dictionary` first, then uses these mappings:
-
-- `started`: `started`, `start_time`, `started_at`, then `sys_created_on`
-- `ended`: `ended`, `end_time`, `ended_at`, then `completed_on`
-- `duration_seconds`: stored `duration`, `run_time`, or `execution_duration`, otherwise `ended - started`
-- `waiting_age_seconds`: current time minus `started` while the status is waiting, queued, paused, or pending
-- `execution_age_seconds`: current time minus `started` while the status is running, executing, or processing
-- `status`: `state`, then `status`, then `execution_state`
-- `error`: `error`, `error_message`, `exception`, then `message`
-
-The timestamp fields are instance-dependent. `sys_created_on` is a fallback for when the context row was created, not a claim that it is the true runtime start time.
-
-## Commands
-
-Run `jsn` for the full grouped list. Commands are organized by ServiceNow domain:
-
-**Core** — `incidents`, `changes`, `requests`, `tasks`, `tickets`
-
-**Automation** — `flows`, `actions`, `rules`, `scrapi`, `updatesets`, `eval`, `rest`
-
-**Access** — `acls`, `roles`, `scopes`, `properties`, `privileges`
-
-**User Experience** — `forms`, `lists`, `clientscripts`, `uipolicies`, `uiactions`
-
-**Data** — `records` (list/get/create/update/delete/count/bulk/attachments), `diff record` (cross-profile read-only comparison), `tables`, `columns`, `includes`, `import`, `logs` (list/show/follow), `snippets` (save/run), `users`, `groups`
-
-**Platform** — `platform health` (cluster records) and `platform stats` (bounded, read-only `/xmlstats.do` summary; allowlisted metrics only)
-
-Every command supports `--json`, `--query`, and `--help`.
-
-For multiline script fields, `--data-file` parses the file as UTF-8 JSON and
-passes the resulting values through unchanged. On Windows PowerShell, generate
-the payload as JSON text and inspect it before invoking JSN, for example:
-
-```powershell
-$script = [string](Get-Content -Path .\Example.script.js -Raw)
-$payload = @{ script = $script; description = 'Example' } |
-  ConvertTo-Json -Depth 5 -Compress
-Set-Content -Path .\Example.update.json -Value $payload -Encoding UTF8
-Get-Content .\Example.update.json -Raw | ConvertFrom-Json | Select-Object -ExpandProperty script
-jsn includes update Example --data-file .\Example.update.json --json
-```
-
-`JSON.parse` preserves a JSON string as a JavaScript string, and the SDK
-serializes update payloads with `JSON.stringify`. If the file already contains
-a `{value=...}` or FileSystem-provider representation, that text is external
-to JSN and must be corrected before the update. Use a read-back command or
-`records update --strict` where applicable to verify persisted fields.
-
-## Instances
-
-Switch between instances without re-authenticating.
-
-```bash
-jsn setup                    # Interactive: add, switch, remove, or modify instances
-jsn auth status              # Dashboard — auth state, read-only 🔒, skip-confirmations ⚡
-```
-
-`jsn setup` is the human front door — one command, interactive menu. For scripts and CI, use the atomic commands:
-
-```bash
-jsn auth login https://dev12345.service-now.com   # Add + authenticate (scripted)
-jsn auth refresh                                  # Manually refresh the OAuth token
-jsn auth switch dev12345                          # Flip the active profile (scripted)
-jsn auth modify dev12345                          # Toggle read-only / skip confirmations
-```
-
-## Output Formats
-
-| Flag | When to use |
-|------|-------------|
-| (default) | Terminal — styled tables |
-| `--json` | Pipelines, scripts |
-| `--markdown` | Documentation |
-| `--quiet` / `-q` | Data only, no envelope |
-| `--csv` | Spreadsheets (opens straight into Excel) |
-| `--get <path>` | Pull one value out of the JSON envelope — no jq (e.g. `--get "data.records.0.number"`) |
-
-## Authentication
-
-JSN supports OAuth 2.0 with PKCE, Basic Auth, and browser-session auth. Credentials are stored in the operating system's credential store, with a file fallback under `~/.config/servicenow/credentials/` when the keyring is unavailable.
-
-```bash
-jsn auth login https://dev12345.service-now.com
-```
-
-For Basic Auth, set `SN_USERNAME` and `SN_PASSWORD`, then run `jsn auth login --basic <instance>`.
-For browser-session auth, run `jsn auth login --gck <instance>` and paste the request headers when prompted.
-
-For CI/CD, set environment variables:
-
-```bash
-export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
-export SERVICENOW_OAUTH_TOKEN="***"
-jsn incidents list
-```
-
-For the credential identity, auth-method, diagnostics, migration, and concurrency contract, see [`docs/AUTH_LIFECYCLE.md`](docs/AUTH_LIFECYCLE.md).
-
-GraphQL uses ServiceNow's `/api/now/graphql` endpoint and sends `{query, variables}` through the authenticated SDK transport. The command preserves GraphQL `data` and `errors`; introspection and available namespaces depend on the target instance.
-
-`jsn platform stats` uses a fixed `GET /xmlstats.do` request. It never accepts a processor path, query parameters, or request body, and it does not emit raw XML, cookies, credentials, or full node identifiers. Oversized, HTML/login, permission, unsupported, timeout, and malformed responses are reported with bounded collector statuses; missing metrics remain unavailable rather than being reported as zero.
-
-## Local data
-
-JSN stores durable local data under `~/.jsn/`. Documentation lives in
-`~/.jsn/docs/`, including `docs.db`, the ServiceNowDocs source checkout, and
-community markdown. Configuration stays under `~/.config/servicenow/` and
-credentials use the operating system's credential store, with a file fallback under `~/.config/servicenow/credentials/`.
-
-Existing installations migrate documentation from
-`~/.cache/servicenow-cli/docs/` automatically the first time the docs data is
-accessed. The old directory is removed only after the destination is verified.
-
-
-## AI Agents
-
-jsn ships with a skill file that tells AI agents how to use it. Installed automatically to `~/.agents/skills/servicenow/SKILL.md`.
-
-```bash
-jsn skill show                  # View the skill
-jsn skill install               # Install to Hermes
-jsn skill install --target all  # All supported agents
-```
+JSN includes a skill for Claude Code, OpenCode, Hermes, Cursor, Copilot, and other agents. Use `jsn skill install --target all` to install it or `jsn skill show` to inspect it.
 
 ## Development
 
 ```bash
-git clone https://github.com/jacebenson/jsn.git
-cd jsn
 npm install
 npm test
 ```
 
-Releases run from the GitHub Actions workflow. Dispatch `Release production` with `patch`, `minor`, or `major`. The workflow tests and lints the repo, bumps the version, pushes the commit and tag, dispatches the npm publish workflow, and creates the GitHub release.
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.8",
+  "version": "4.3.9-dev.62",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "main": "src/cli.js",
   "scripts": {
-    "test": "node --experimental-test-module-mocks --test --test-concurrency=1 $(find test -name '*.test.js')",
+    "test": "node --experimental-test-module-mocks --test --test-concurrency=4 $(find test -name '*.test.js')",
+    "test:mutation": "stryker run",
     "lint": "npx eslint src/ bin/ test/",
     "start": "node bin/jsn.js",
     "docs": "npm --prefix docs run build",
@@ -35,6 +36,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@stryker-mutator/core": "^10.0.0",
     "globals": "^17.6.0"
   },
   "files": [

package/skills/servicenow/SKILL.md

@@ -73,6 +73,60 @@ Pick the most specific tool for the job. **Never default to eval** — it's the
 | **Docs** | `docs sync`, `docs status`, `docs search`, `docs serve` |
 | **Developer** | `eval`, `rest`, `skill`, `version` |
 
+### Customization evidence
+
+```sh
+jsn customizations capture --label review --customer-scope x_acme_app --json
+jsn customizations list --json
+jsn customizations show <run_id> --get data.categories
+jsn customizations show <run_id> --get data.triage
+jsn customizations html <run_id> [--out review.html]
+jsn customizations compare <baseline_id> <new_id> --json
+```
+
+Capture performs bounded GET-only table reads and saves local reports. It never
+evals or creates, updates or deletes instance records. Standard authentication
+may refresh OAuth tokens, store refreshed credentials locally and bootstrap a
+session/GCK using authentication POSTs. List/show/compare are offline.
+Declare customer ownership with repeatable `--customer-scope` values or sys_ids;
+never infer customer ownership from a non-global scope. The declaration is
+caller evidence, not independent publisher verification. OOTB findings reflect
+historical upgrade skips, not a current verified baseline deviation. The upgrade
+history is read server-side for the skip dispositions and every observed skipped
+`file_name` is resolved against `sys_metadata` by chunked
+`sys_update_nameIN<chunk>` lookups, so the OOTB inventory covers the observed
+skipped artifacts; the broad `sys_metadata` read is an arbitrary `sys_id`-ordered
+slice and is reported as a bounded sample, not an inventory, describing only the
+unclassified and declared-customer categories. Unresolved skipped names and
+failed lookup chunks stay explicit rather than becoming absent artifacts, and a
+resolved artifact can lack a scope name when its scope record was outside the
+bounded `sys_scope` read. Missing
+ACL access, pagination limits and unmatched evidence remain explicit. All
+reports are incomplete; no findings is not proof of no customizations.
+Comparisons cover captured metadata/evidence, not source payloads. Removals mean
+no longer observed, not proven deletion. Reversion impact and dependencies
+remain unknown until separately investigated. Never recommend automatic reversion.
+
+Upgrade history joins `file_name` to metadata `sys_update_name`. Raw disposition
+`4` or `104` is skipped-customization evidence; resolution `reviewed_reverted`
+excludes that history row. Use raw values, not display labels or other skip reasons.
+
+### Complete an update set
+
+```bash
+jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json
+```
+
+`complete [name]` defaults to the current set when the name is omitted. Explicit
+names must be unique. Supply nonempty `--notes` in automation; real newlines
+separate bullets. A human terminal opens a notes editor when `--notes` is absent.
+Existing Description text is preserved and appended after confirmation. Use
+`--force` only after approval, or the profile's `skip_confirmations` policy.
+Notes apply only to the selected set. ServiceNow's normal batch rules can complete
+child sets when the parent completes; their descriptions are not replaced.
+Both selected-set Description and state are read back before success. On
+verification failure, inspect the set before retrying.
+
 ### Table and raw REST examples
 
 ```bash

package/src/cli.js

@@ -9,6 +9,7 @@ import { App } from './app.js';
 import { resolveSession, applySession } from './session.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
+import { skippedUpdatesCmd } from './commands/skipped-updates.js';
 import { noInstanceCommands, dailyCheckSkipCommands } from './capabilities.js';
 import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
 import { formatCommandList } from './helpers.js';
@@ -70,6 +71,7 @@ import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { perfCmd } from './commands/perf.js';
+import { customizationsCmd } from './commands/customizations.js';
 import { midserversCmd } from './commands/midservers.js';
 import { diffCmd } from './commands/diff.js';
 import { graphqlCmd } from './commands/graphql.js';
@@ -405,7 +407,9 @@ export function buildCLI() {
     // DEVELOPER
     .command(atfCmd(wrap))
     .command(approvalsCmd(wrap))
+    .command(skippedUpdatesCmd(wrap))
     .command(perfCmd(wrap))
+    .command(customizationsCmd(wrap))
     .command(midserversCmd(wrap))
     .command(diffCmd(wrap))
     .command(graphqlCmd(wrap))