@ariestools/cli 0.1.6

package/README.md

@@ -0,0 +1,1251 @@
+# @ariestools/cli
+
+Aries Tools CLI — a suite by Arie Trouw for AI-client tooling, Claude/Codex audit trails, sandboxed command execution, XL1 datalake provisioning, content hashing (strict + fuzzy + perceptual), XL1 wallet management, payload witnessing, and XYO protocol utilities.
+
+## Installation
+
+```sh
+npm install -g @ariestools/cli
+# or
+pnpm add -g @ariestools/cli
+```
+
+## Quick start
+
+```sh
+aries --help
+aries info
+aries hash --algorithm pdq ./photo.jpg
+ariesi plex libraries
+aries wallet create
+aries witness url --url https://example.com
+aries datalake list
+```
+
+## Top-level commands
+
+```text
+aries ai           AI client tools
+aries audit        Manage the Claude Code audit trail
+aries bank         Manage bank witness settings
+aries chain        Run a local published-chain S3/REST server
+aries clamp        Run commands inside a permission-controlled sandbox
+aries datalake     Provision and manage on-demand XL1 datalakes
+aries hash [file]  Generate a hash (sha256, xyo, fuzzy, perceptual)
+aries info         Display version and environment info
+aries npmjs        Inspect and lint npmjs org packages
+aries pentair      Manage Pentair ScreenLogic systems
+ariesi plex        Inspect and manage Plex Media Server (internal build)
+aries wallet       XL1 wallet — seed phrases, accounts, transactions, contacts
+aries witness      Observe data and produce XYO-compliant payloads
+aries xyo          XYO protocol utilities
+```
+
+## Global options
+
+Available on every command:
+
+| Option | Description |
+|---|---|
+| `-v, --verbose` | Enable verbose output |
+| `--version` | Show version number |
+| `--help` | Show help |
+
+---
+
+## `aries chain` — Local published-chain server
+
+```sh
+# Plain HTTP on loopback (default)
+aries chain up
+
+# Locally trusted HTTPS at https://chain.aries.test:8791 (macOS)
+brew install mkcert
+aries chain up --ssl auto
+```
+
+The server exposes the published-chain buckets at `/blocks`, `/state`, and
+`/indexes`. `--ssl auto` keeps the listener on `127.0.0.1`, installs or reuses
+mkcert's local development CA, generates a certificate under
+`~/.aries/chain/tls`, and adds an idempotent `chain.aries.test` entry to
+`/etc/hosts`. The first run may request administrator authorization. The CA and
+hosts entry remain installed after `chain down`; `chain reset` removes the
+generated Aries certificate files.
+
+| Option | Default | Description |
+|---|---|---|
+| `--port <number>` | `8791` | Listener port |
+| `--host <address>` | `127.0.0.1` | Bind address; auto TLS requires the default |
+| `--ssl off\|auto` | `off` | Enable macOS automatic local HTTPS setup |
+| `--backing memory` | `memory` | Ephemeral storage, wiped on shutdown |
+| `--timeout <seconds>` | `10` | Startup health-check timeout |
+
+The ready banner prints the `S3_ENDPOINT` used by `ariesi xyo s3 ...`. Aries
+automatically selects path-style S3 addressing and trusts the generated CA for
+the `chain.aries.test` endpoint. `S3_CA_BUNDLE` can provide a different private
+CA file for another HTTPS S3-compatible endpoint.
+
+---
+
+## `aries bank` — Manage bank witness settings
+
+```sh
+aries bank capitalone config get
+aries bank capitalone config set base-url https://api-sandbox.capitalone.com
+aries bank capitalone config set token-url https://api-sandbox.capitalone.com/oauth2/token
+aries bank capitalone config set client-id "$CAPITALONE_CLIENT_ID"
+aries bank capitalone config set client-secret "$CAPITALONE_CLIENT_SECRET"
+aries bank capitalone config set accounts-path /accounts
+aries bank capitalone config set balances-path '/accounts/{accountId}/balances'
+aries bank capitalone config set transactions-path '/accounts/{accountId}/transactions'
+```
+
+Capital One config is stored in `~/.aries/bank/capitalone.json` with restricted
+file permissions. `ARIES_HOME` overrides the `~/.aries` root.
+
+Capital One U.S. Customer Transactions is a private DevExchange product. Aries
+therefore requires the endpoint paths supplied by your Capital One partner docs
+for `aries witness bank --resource accounts`.
+
+The public sandbox `Retrieve Consumer Bank Products` product is a deposit product
+catalog, not personal account data. Use `aries witness bank --resource products`
+for that API; Aries uses Capital One's documented sandbox defaults unless you
+override `base-url` or `token-url`.
+
+### Capital One config keys
+
+| Key | Env var | Default | Description |
+|---|---|---|---|
+| `env` | `ARIES_CAPITALONE_ENV` | `sandbox` | Environment label: `sandbox` or `production` |
+| `base-url` | `ARIES_CAPITALONE_BASE_URL` | | Capital One API base URL |
+| `token-url` | `ARIES_CAPITALONE_TOKEN_URL` | | OAuth client-credentials token URL |
+| `client-id` | `ARIES_CAPITALONE_CLIENT_ID` | | OAuth client id |
+| `client-secret` | `ARIES_CAPITALONE_CLIENT_SECRET` | | OAuth client secret |
+| `scope` | `ARIES_CAPITALONE_SCOPE` | | Optional OAuth scope |
+| `accounts-path` | `ARIES_CAPITALONE_ACCOUNTS_PATH` | | Accounts endpoint path |
+| `balances-path` | `ARIES_CAPITALONE_BALANCES_PATH` | | Balances endpoint path; may include `{accountId}` |
+| `transactions-path` | `ARIES_CAPITALONE_TRANSACTIONS_PATH` | | Transactions endpoint path; may include `{accountId}` |
+
+`config get` redacts `client-secret`; pass `--show-secrets` to print it. Access
+tokens are not persisted; pass `--access-token` or set `ARIES_CAPITALONE_ACCESS_TOKEN`
+for one run.
+
+---
+
+## `aries pentair` — Manage Pentair ScreenLogic systems
+
+```sh
+aries pentair config get
+aries pentair config get address
+aries pentair config set address 192.0.2.10
+aries pentair config set port 80
+aries pentair config set system-name "Pentair ScreenLogic"
+aries pentair circuit runtime set --circuit-id 6 --hours 24 --on
+```
+
+Pentair config is stored in `~/.aries/pentair/config.json` and is used by the
+Pentair witness and circuit commands. `ARIES_HOME` overrides the `~/.aries` root.
+
+### Config keys
+
+| Key | Default | Description |
+|---|---|---|
+| `address` | | ScreenLogic adapter IP for direct connection; omit to use UDP discovery |
+| `port` | `80` | ScreenLogic adapter TCP port for direct connection |
+| `password` | `SCREENLOGIC_PASSWORD` | ScreenLogic password for direct connection |
+| `system-name` | `Pentair ScreenLogic` | ScreenLogic system name for direct connection |
+| `response-timeout` | `15000` | Milliseconds to wait for each ScreenLogic command response |
+| `search-timeout` | `5000` | Milliseconds to wait for each UDP discovery attempt |
+| `search-attempts` | `3` | Number of UDP discovery attempts before failing |
+| `series-file` | `~/.aries/pentair/intellichem.jsonl` | JSONL file used for saved IntelliChem samples and graphing |
+
+`config get` redacts `password`; pass `--show-secrets` to print it.
+
+### `aries pentair circuit runtime set`
+
+Set the ScreenLogic circuit egg timer. Runtime values are sent to ScreenLogic as
+minutes; `--hours 24` becomes `1440`.
+
+| Option | Description |
+|---|---|
+| `--circuit-id <id>` | Pentair circuit id to update |
+| `--hours <n>` | Runtime in hours; mutually exclusive with `--minutes` |
+| `--minutes <n>` | Runtime in minutes; mutually exclusive with `--hours` |
+| `--on` | Turn the circuit on after setting the runtime |
+| `--json` | Output as JSON |
+
+Connection override flags are also accepted: `--address`, `--port`,
+`--password`, `--system-name`, `--response-timeout`, `--search-timeout`, and
+`--search-attempts`.
+
+---
+
+## `ariesi plex` — Plex Media Server tools
+
+The Plex command is available from the internal `ariesi` build with
+`license.tier=internal`.
+
+### `ariesi plex libraries`
+
+List libraries configured in a Plex Media Server. By default, Aries tries the local server at `http://127.0.0.1:32400` and discovers the Plex token from `PLEX_TOKEN`, `X_PLEX_TOKEN`, `PLEX_AUTH_TOKEN`, local Plex `.LocalAdminToken`, or a local Plex `Preferences.xml`. If local API auth still blocks access, Aries falls back to the local Plex library database and then `Plex Media Scanner --list`.
+
+| Option | Default | Description |
+|---|---|---|
+| `--url <url>` | `PLEX_URL` or `http://127.0.0.1:32400` | Plex server URL |
+| `--token <token>` | env/local Preferences.xml | Plex auth token |
+| `--preferences <path>` | auto-detect | Plex `Preferences.xml` path for token discovery |
+| `--database <path>` | auto-detect | Plex library database path for local fallback |
+| `--no-fallback` | | Disable fallback to `Plex Media Scanner --list` when the API is unavailable |
+| `--json` | `false` | Output as JSON |
+
+### `ariesi plex lint [--library <name-or-id>]`
+
+Run read-only lint checks against the Plex setup. The first rule, `multiple-sources`, reports items that have more than one original source media copy. Plex optimized versions and files matching Plex's local extras naming conventions do not count as sources.
+
+| Option | Default | Description |
+|---|---|---|
+| `-l, --library <name-or-id>` | all libraries | Plex library name or ID, e.g. `Movies` or `9` |
+| `--database <path>` | auto-detect | Plex library database path |
+| `--json` | `false` | Output as JSON |
+
+### `ariesi plex items --library <name-or-id>`
+
+List top-level items in a Plex library from the local Plex database, including media resolution and optimization details.
+
+| Option | Default | Description |
+|---|---|---|
+| `-l, --library <name-or-id>` | required | Plex library name or ID, e.g. `Movies` or `9` |
+| `--database <path>` | auto-detect | Plex library database path |
+| `--fields <list>` | `media,optimizations` | Comma-separated details: `media`, `optimizations`, `files`, `all` |
+| `--limit <n>` | | Maximum number of items to inspect |
+| `--json` | `false` | Output as JSON |
+
+### `ariesi plex items optimize --tv --library <name-or-id>`
+
+Queue Plex "Optimized for TV" versions for items that do not already have one. Aries inspects the local Plex database first, skips items already marked `Optimized for TV`, and then queues missing items through the local Plex optimizer API.
+
+| Option | Default | Description |
+|---|---|---|
+| `-l, --library <name-or-id>` | required | Plex library name or ID, e.g. `Movies` or `9` |
+| `--tv` | required | Optimize missing items for Plex's TV profile |
+| `--dry-run` | `false` | Show what would be queued without changing Plex |
+| `--url <url>` | `PLEX_URL` or `http://127.0.0.1:32400` | Plex server URL |
+| `--token <token>` | env/local token discovery | Plex auth token |
+| `--preferences <path>` | auto-detect | Plex `Preferences.xml` path for token discovery |
+| `--database <path>` | auto-detect | Plex library database path |
+| `--limit <n>` | | Maximum number of missing optimizations to queue |
+| `--inspect-limit <n>` | | Maximum number of library items to inspect |
+| `--json` | `false` | Output as JSON |
+
+### `ariesi plex items optimize queue [--library <name-or-id>]`
+
+List items currently in Plex's optimizer queue. When `--library` is omitted, Aries lists queued optimizer items across all libraries.
+
+| Option | Default | Description |
+|---|---|---|
+| `-l, --library <name-or-id>` | all libraries | Plex library name or ID, e.g. `Movies` or `9` |
+| `--url <url>` | `PLEX_URL` or `http://127.0.0.1:32400` | Plex server URL |
+| `--token <token>` | env/local token discovery | Plex auth token |
+| `--preferences <path>` | auto-detect | Plex `Preferences.xml` path for token discovery |
+| `--database <path>` | auto-detect | Plex library database path for library names |
+| `--json` | `false` | Output as JSON |
+
+---
+
+## `aries ai` — AI client tools
+
+### `aries ai detect`
+
+Scan for installed AI clients.
+
+| Option | Default | Description |
+|---|---|---|
+| `--json` | `false` | Output as JSON |
+
+### `aries ai sync`
+
+Sync AI config between Claude Code and Codex.
+
+| Option | Default | Description |
+|---|---|---|
+| `--from <claude\|agents>` | `claude` | Source to sync from (the authority) |
+
+### `aries ai lint [path]`
+
+Check Claude Code and Codex AI configuration drift. The folder defaults to the current directory.
+
+| Option | Default | Description |
+|---|---|---|
+| `--scope <all\|project\|home>` | `all` | Check project config, shared/custom home config, or both |
+| `--json` | `false` | Output as JSON |
+
+---
+
+## `aries audit` — Manage the Claude Code audit trail
+
+```sh
+aries audit ai                    # Show current AI metadata recorded in audit entries
+aries audit list                  # List audit sessions
+aries audit show <session-id>     # Show audit trail for a session
+aries audit search <query>        # Search audit logs
+aries audit install [provider]    # Install the audit plugin (claude | codex | both)
+aries audit uninstall [provider]  # Uninstall the audit plugin
+aries audit open                  # Open the audit log directory in Finder/Explorer
+aries audit status                # Show audit plugin status and log statistics
+```
+
+### Per-command flags
+
+#### `aries audit ai`
+| Option | Default | Description |
+|---|---|---|
+| `--json` | `false` | Output as JSON |
+
+#### `aries audit list`
+| Option | Default | Description |
+|---|---|---|
+| `-d, --date <YYYY-MM-DD>` | | Filter by date |
+
+#### `aries audit show <session-id>`
+| Positional | | Description |
+|---|---|---|
+| `session-id` | required | Session ID (or prefix) |
+
+| Option | Default | Description |
+|---|---|---|
+| `-f, --format <text\|json>` | `text` | Output format |
+
+#### `aries audit search <query>`
+| Positional | | Description |
+|---|---|---|
+| `query` | required | Search text |
+
+| Option | Default | Description |
+|---|---|---|
+| `-d, --date <YYYY-MM-DD>` | | Filter by date |
+| `-n, --limit <n>` | `50` | Max results |
+
+#### `aries audit install [provider]` / `aries audit uninstall [provider]`
+| Positional | | Description |
+|---|---|---|
+| `provider` | both | `claude` or `codex` |
+
+`open`, `status` take no command-specific options.
+
+---
+
+## `aries clamp` — Run commands inside a permission-controlled sandbox
+
+```sh
+aries clamp run <command> [args..]   # Run a command inside the clamp sandbox
+aries clamp policy list              # List available clamp policies
+aries clamp policy show <name>       # Show a clamp policy
+aries clamp policy init              # Create a starter .aries-clamp.json
+```
+
+### Per-command flags
+
+#### `aries clamp run <command> [args..]`
+| Positional | | Description |
+|---|---|---|
+| `command` | required | Command to run inside the sandbox |
+| `args` | `[]` | Arguments for the command |
+
+| Option | Default | Description |
+|---|---|---|
+| `-p, --policy <path-or-name>` | | Policy file path or name |
+| `--audit` | `true` | Enable audit logging |
+| `--dry-run` | `false` | Show what would be sandboxed without running |
+
+#### `aries clamp policy show <name>`
+| Positional | | Description |
+|---|---|---|
+| `name` | required | Policy name or file path |
+
+`policy list` and `policy init` take no command-specific options.
+
+---
+
+## `aries datalake` — Provision and manage on-demand XL1 datalakes
+
+### Authentication
+
+#### `aries datalake login`
+| Option | Default | Description |
+|---|---|---|
+| `--base-url <url>` | | Control-plane base URL (P0: required) |
+| `--token <jwt>` | | Pre-issued auth token (P0: required; OAuth lands in P1) |
+
+`aries datalake logout` — clears stored credentials, no flags.
+
+### Lifecycle
+
+#### `aries datalake create <name>`
+| Positional | | Description |
+|---|---|---|
+| `name` | required | Human-friendly name (unique per owner) |
+
+| Option | Default | Description |
+|---|---|---|
+| `-t, --tier <small\|medium\|large\|archive>` | `small` | Service tier |
+| `-s, --size <e.g. 10GB>` | | Capacity |
+| `--iops <n>` | | Provisioned IOPS target |
+| `-r, --region <us-west-2\|us-east-1\|eu-west-1>` | | Deployment region |
+| `--retention-days <n>` | tier default | Retention in days |
+| `--verify-hashes` | `false` | Reject inserts whose `$hash` does not match the content digest |
+| `--rate-auth-per-minute <n>` | | Override: authenticated requests per minute |
+| `--rate-anon-per-minute <n>` | | Override: anonymous requests per minute |
+| `--rate-burst-factor <n>` | | Override: rate-limit burst factor (1 = no burst) |
+
+`aries datalake list` — no flags.
+
+#### `aries datalake describe [name]` / `aries datalake destroy [name]`
+| Positional | | Description |
+|---|---|---|
+| `name` | active default | Datalake name or id |
+
+`destroy` adds:
+| Option | Default | Description |
+|---|---|---|
+| `-f, --force` | `false` | Required confirmation flag |
+
+#### `aries datalake use [name]`
+
+Sets the default datalake for subsequent commands. Omit the name to clear.
+
+### Access control
+
+#### `aries datalake grant <name> <principal>`
+| Positional | | Description |
+|---|---|---|
+| `name` | required | Datalake name or id |
+| `principal` | required | User id, or the literal `public` |
+
+| Option | Default | Description |
+|---|---|---|
+| `-r, --role <viewer\|runner>` | `viewer` | Role to grant |
+| `--confirm-public` | `false` | Required to grant `public runner` (anonymous writes) |
+
+#### `aries datalake revoke <name> <principal>`
+
+Same positionals; no command-specific options.
+
+#### `aries datalake token [name]`
+| Positional | | Description |
+|---|---|---|
+| `name` | active default | Datalake name or id |
+
+| Option | Default | Description |
+|---|---|---|
+| `-r, --role <viewer\|runner>` | `viewer` | Role encoded in the token |
+| `--ttl <seconds>` | server-capped | Lifetime in seconds |
+
+### Data plane
+
+#### `aries datalake push <file> [name]`
+| Positional | | Description |
+|---|---|---|
+| `file` | required | Path to a `.json` (array) or `.jsonl` (one payload/line) file |
+| `name` | active default | Target datalake |
+
+| Option | Default | Description |
+|---|---|---|
+| `--batch-size <n>` | `500` | Max payloads per HTTP request |
+| `--verify` | `false` | Verify each payload's `$hash` against content locally before pushing |
+| `--xl1-sdk` | `false` | Use the real `@xyo-network/xl1-protocol-sdk RestDataLakeRunner` |
+
+#### `aries datalake fetch <hash> [name]`
+| Positional | | Description |
+|---|---|---|
+| `hash` | required | Content hash of the payload |
+| `name` | active default | Target datalake |
+
+| Option | Default | Description |
+|---|---|---|
+| `--raw` | `false` | Print only the raw JSON payload (no header) |
+| `--xl1-sdk` | `false` | Use the real `@xyo-network/xl1-protocol-sdk RestDataLakeViewer` |
+
+#### `aries datalake tail [name]`
+| Positional | | Description |
+|---|---|---|
+| `name` | active default | Datalake name or id |
+
+| Option | Default | Description |
+|---|---|---|
+| `-f, --follow` | `false` | Keep polling for new payloads after draining the backlog |
+| `-n, --limit <n>` | `50` | Max payloads per page |
+| `--cursor <hash>` | | Resume after this hash (exclusive) |
+| `--schemas <csv>` | | Comma-separated list of schemas to include |
+| `--poll-interval <ms>` | `1000` | Poll interval in ms when following |
+
+### Audit (data-plane log inspection)
+
+```sh
+aries datalake audit          # default: view
+aries datalake audit view     # Print audit log rows
+aries datalake audit purge    # Delete rotated audit files older than --max-age-days
+```
+
+#### `aries datalake audit view`
+| Option | Default | Description |
+|---|---|---|
+| `-f, --follow` | `false` | Stream new rows as they arrive (tails the most recent file) |
+| `-n, --lines <n>` | `50` | Tail this many rows (0 = start fresh in `--follow` mode) |
+| `-d, --datalake <id>` | | Filter by datalake name or id |
+| `--status <prefix>` | | Status code prefix filter (e.g. `4` matches 4xx) |
+| `--method <verb>` | | HTTP method filter (`GET`, `POST`, …) |
+| `--authenticated <true\|false>` | | Show only authenticated or only anonymous requests |
+| `--grep <regex>` | | Regex pattern applied to the raw JSON line |
+| `--file <path>` | | File or directory (auto-detects rotation layout) |
+
+#### `aries datalake audit purge`
+| Option | Default | Description |
+|---|---|---|
+| `--max-age-days <n>` | required | Retention window; files older than this are deleted |
+| `--directory <path>` | `<ARIES_HOME>/dev/audit` | Rotation directory |
+| `--dry-run` | `false` | Report what would be deleted without removing anything |
+
+### Local development
+
+```sh
+aries datalake dev up        # Start the local control + data plane dev server
+aries datalake dev down      # Stop it (clears credentials)
+aries datalake dev status    # Report whether the local dev server is running and healthy
+aries datalake dev logs      # Print recent dev server log output
+aries datalake dev reset     # Stop the dev server and wipe all local state
+```
+
+#### `aries datalake dev up`
+| Option | Default | Description |
+|---|---|---|
+| `--control-port <n>` | `8787` | Control-plane port |
+| `--plane-port <n>` | `8788` | Data-plane port |
+| `--timeout <s>` | `10` | Seconds to wait for health |
+| `--persist` | `false` | Persist store state to disk so it survives restarts |
+| `--audit` | `false` | Write a JSONL audit log of every data-plane request |
+| `--audit-rotate` | `false` | Rotate the audit log daily (writes to `<home>/dev/audit/`) |
+| `--audit-keep-days <n>` | | Prune rotated audit files older than this many days |
+
+#### `aries datalake dev logs`
+| Option | Default | Description |
+|---|---|---|
+| `-f, --follow` | `false` | Stream new lines as they arrive |
+| `-n, --lines <n>` | `50` | Number of tail lines to show |
+
+`down`, `status`, `reset` take no command-specific options.
+
+---
+
+## `ariesi signing-pool` — XL1 gas-sponsored transaction signing
+
+Signing pools are wallet-backed servers that co-sign XL1 transactions so the
+pool address pays gas instead of the caller. The transaction must use signature
+slot 0 for the pool and signature slot 1 for the caller:
+
+- `addresses[0]` is the signing-pool address.
+- `addresses[1]` is the authenticated caller address.
+- `$signatures[0]` must be `null` when submitted.
+- `$signatures[1]` must already verify against `addresses[1]`.
+
+`signing-pool sign` submits a hydrated transaction tuple
+`[TransactionBoundWitness, payloads[]]`. For compatibility with the original
+CLI helper, the input file may also be an unsigned template; in that case the
+CLI fills the pool/caller slots, signs slot 1 with the active XL1 wallet, and
+sends the hydrated tuple to the pool.
+
+```sh
+ariesi signing-pool create <name> --daily-limit <atto> --max-tx-gas <atto> --min-exp-blocks 10 --max-exp-blocks 500
+ariesi signing-pool grant <id> <caller-address>
+ariesi signing-pool sign <id> ./tx.json --output ./signed-tx.json
+ariesi signing-pool dev up --xl1-node-rpc-url http://127.0.0.1:8545
+```
+
+The control plane rejects transactions it cannot inspect. In this phase, every
+payload elevated on-chain via `script: ["elevate|<payload-hash>"]` must be
+present in the hydrated payload array, and `network.xyo.transfer` is prohibited
+as an elevated/on-chain payload.
+
+### Local development
+
+```sh
+ariesi signing-pool dev up      # Start the local signing-pool control plane
+ariesi signing-pool dev down    # Stop it
+ariesi signing-pool dev status  # Report whether it is running and healthy
+ariesi signing-pool dev logs    # Print recent server log output
+ariesi signing-pool dev reset   # Stop the server and wipe local state
+```
+
+#### `ariesi signing-pool dev up`
+| Option | Default | Description |
+|---|---|---|
+| `--port <n>` | `8790` | Control-plane port |
+| `--timeout <s>` | `10` | Seconds to wait for health |
+| `--persist` | `false` | Persist pool state under `<ARIES_HOME>/signing-pool-dev/store` |
+| `--audience <aud>` | `aries-signing-pool` | JWT audience accepted by the dev control plane |
+| `--master-mnemonic <phrase>` | generated | Override the dev mnemonic used to derive pool signing accounts |
+| `--xl1-node-rpc-url <url>` | `$XL1_NODE_RPC_URL` | XL1 node RPC URL used to read current block height |
+
+The dev client auto-discovers a live local signing-pool state when
+`--base-url`, `$SIGNING_POOL_CONTROL_URL`, and `$TOKEN_POOL_CONTROL_URL` are not
+set.
+
+### Upstream builder follow-up
+
+The signing pool currently uses a narrow local helper to fill a single
+`$signatures[]` slot without mutating the rest of the bound witness. The proper
+upstream fix belongs in `sdk-protocol-js`: add explicit partial-signing support
+to `BoundWitnessBuilder`, then expose that through `TransactionBuilder` so a
+caller can build/sign slot 1 and a signing pool can later sign slot 0 while
+preserving the hydrated transaction tuple and all existing signatures.
+
+---
+
+## `aries hash [file]` — content hashing
+
+```text
+aries hash [file] [options]
+aries hash compare <hashA> <hashB> --algorithm <name> [--json]
+```
+
+Reads input from `[file]` (positional), `--string`, or piped stdin (priority order). Dispatches to one of 11 algorithms.
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `-a, --algorithm <name>` | `sha256` | Algorithm — see the matrix below |
+| `-s, --string <text>` | | Hash this string instead of a file/stdin |
+| `-x, --xyo` | `false` | Shortcut for `--algorithm xyo` (input must be JSON) |
+| `--base64` | `false` | Re-encode hex output as base64 (only for hex-output algorithms) |
+| `--fps <n>` | `1` | Frames-per-second sample rate (`video-frames` only) |
+| `--frame-algorithm <phash\|pdq>` | `phash` | Per-frame hash for `video-frames` |
+
+### Algorithm reference
+
+| Algorithm | Family | Input | Output | External binary | Compare metric |
+|---|---|---|---|---|---|
+| `sha256` | strict | bytes | 64-char hex | — | `exact-match` |
+| `xyo` | strict | JSON | 64-char hex | — | `exact-match` |
+| `tlsh` | fuzzy-byte | ≥50 bytes | 70-char hex | — | `tlsh-bit-hamming` ⚠ |
+| `nilsimsa` | fuzzy-byte | bytes | 64-char hex | — | `nilsimsa-score` |
+| `ssdeep` | fuzzy-byte | bytes | `bs:h1:h2` | `ssdeep` | `ssdeep-levenshtein` ⚠ |
+| `phash` | perceptual-image | image | 16-char hex (64-bit) | — | `hamming-64` |
+| `dhash` | perceptual-image | image | 16-char hex (64-bit) | — | `hamming-64` |
+| `blockhash` | perceptual-image | image | 16-char hex (64-bit) | — | `hamming-64` |
+| `pdq` | perceptual-image | image | 64-char hex (256-bit) — Meta PDQ via WASM | — | `hamming-256` |
+| `chromaprint` | audio | audio file | JSON `{duration, fingerprint[]}` | `fpcalc` | `chromaprint-windowed-hamming` |
+| `video-frames` | video | video file | JSON `{fps, frames:[{t,hash}]}` | `ffmpeg` | `frame-sequence-<algo>@<fps>fps` |
+
+⚠ — Approximations, not the canonical reference scores:
+- `tlsh-bit-hamming` — the upstream `tlsh` npm package only exposes hashing, not the canonical TLSH-diff algorithm. We use bit-level Hamming over the hash body as a proxy.
+- `ssdeep-levenshtein` — block-size-aware Levenshtein, without the canonical block-size attenuation curve.
+
+### External binary install
+
+```sh
+# macOS
+brew install ssdeep chromaprint ffmpeg
+
+# Debian/Ubuntu
+apt install ssdeep libchromaprint-tools ffmpeg
+
+# Windows
+choco install ssdeep chromaprint ffmpeg
+```
+
+Each algorithm probes its binary at hash time and prints clear install instructions if the binary is missing.
+
+### Examples
+
+```sh
+# Strict
+aries hash --string "hello"
+aries hash ./payload.json --algorithm xyo
+
+# Byte-fuzzy
+aries hash --algorithm tlsh ./binary.exe
+aries hash compare <hashA> <hashB> --algorithm tlsh
+
+# Perceptual image
+aries hash --algorithm phash ./photo.jpg
+aries hash --algorithm pdq   ./photo.jpg
+aries hash compare <hashA> <hashB> --algorithm pdq
+
+# Audio
+aries hash --algorithm chromaprint ./song.mp3 > song.fp.json
+aries hash compare "$(cat a.fp.json)" "$(cat b.fp.json)" --algorithm chromaprint --json
+
+# Video
+aries hash --algorithm video-frames --fps 1 ./movie.mkv > movie.fp.json
+aries hash --algorithm video-frames --fps 1 --frame-algorithm pdq ./movie.mkv > movie-pdq.fp.json
+aries hash compare "$(cat a.fp.json)" "$(cat b.fp.json)" --algorithm video-frames
+```
+
+### `aries hash compare <hashA> <hashB>`
+
+| Positional | | Description |
+|---|---|---|
+| `hashA` | required | First hash |
+| `hashB` | required | Second hash |
+
+| Option | Default | Description |
+|---|---|---|
+| `-a, --algorithm <name>` | required | Algorithm that produced the hashes |
+| `--json` | `false` | Print full result as JSON |
+
+Plain output: `<similarity>\t<metric>[\tdistance=<n>]` (similarity is a 0..1 float, 1 = identical). JSON output: `{"similarity":0.93,"distance":18,"metric":"hamming-256"}`.
+
+The compare command needs only the two hash strings — works against hashes generated on different machines.
+
+---
+
+## `aries npmjs` — npmjs org package checks
+
+```sh
+aries npmjs list --org=xylabs
+aries npmjs lint --org=xylabs
+aries npmjs lint --org=xylabs --fix
+aries npmjs lint              # all auth-visible org packages
+```
+
+By default, package discovery uses your current npm CLI authentication via `npm access list packages @<org> --json`, so private or restricted org packages are included when your npm account can see them. Omit `--org` to list or lint all scoped packages returned by `npm access list packages --json`, grouped by org with a per-org summary at the end. If npm auth is unavailable for a specific `--org`, `aries npmjs` falls back to public package discovery and reports `npm auth: unauthenticated` at the end of text output. Use `--public-only` with `--org` to force public discovery.
+
+### `aries npmjs list`
+
+| Option | Default | Description |
+|---|---|---|
+| `--org <scope>` | | npm org scope, with or without `@`; omit for all auth-visible org packages |
+| `--public-only` | `false` | List only public packages without using `npm access` |
+| `--json` | `false` | Output as JSON |
+
+### `aries npmjs lint`
+
+Find packages that are not marked deprecated but probably should be. V1 reports warning-only findings and exits `0` unless an operational error occurs.
+
+| Option | Default | Description |
+|---|---|---|
+| `--org <scope>` | | npm org scope, with or without `@`; omit for all auth-visible org packages |
+| `--public-only` | `false` | Lint only public packages without using `npm access` |
+| `--abandoned-days <n>` | `365` | Warn when latest publish is at least this many days old |
+| `--unused-downloads <n>` | `100` | Warn when weekly downloads are below this threshold |
+| `--new-days <n>` | `30` | Do not warn for low downloads until a package is at least this many days old |
+| `--fix` | `false` | Interactively choose lint findings to deprecate with `npm deprecate` |
+| `--deprecation-message <text>` | | Message to pass to `npm deprecate` for selected packages |
+| `--json` | `false` | Output as JSON |
+
+Rules:
+- `abandoned` — latest publish date is older than the configured threshold.
+- `unused` — weekly downloads are below the configured threshold and the package is not new.
+
+`--fix` is text-only and prompts with a default `Do Nothing` / optional `Deprecate` toggle for each package reported by lint. After selection, each selected package prompts for an optional replacement package name. Blank keeps the default message; a replacement appends `Use <replacement> instead.` Selected packages are deprecated with `npm deprecate <package>@* <message>` after Enter is pressed.
+
+---
+
+## `aries info`
+
+Display ariestools version and environment info. No command-specific options.
+
+---
+
+## `aries wallet` — XL1 wallet
+
+Wallet commands are provided by the standalone `@xyo-network/wallet-xl1-cli` package (`xl1-wallet`). The Aries CLI forwards `aries wallet ...` to that bin and uses the wallet CLI storage layout: `~/.xl1/wallet/cli` by default, overrideable with `XL1_WALLET_HOME` (`ARIES_WALLET_HOME` remains a legacy fallback).
+
+### Wallet management
+
+```sh
+aries wallet create               # Generate a new XL1 wallet (random recovery phrase)
+aries wallet import               # Import an existing XL1 recovery phrase
+aries wallet export               # Print the recovery phrase for the active (or specified) wallet
+aries wallet list                 # List stored wallets
+aries wallet use <id>             # Set the active wallet
+aries wallet rename <id> <label>  # Rename a stored wallet
+aries wallet remove <id>          # Delete a stored wallet (and its address book)
+```
+
+#### `aries wallet create`
+| Option | Default | Description |
+|---|---|---|
+| `-l, --label <text>` | first available `wallet#` | Friendly label for the wallet |
+| `--algorithm <secp256k1\|ml-dsa-65>` | `secp256k1` | Wallet signing algorithm |
+
+#### `aries wallet import`
+| Option | Default | Description |
+|---|---|---|
+| `-l, --label <text>` | `imported` | Friendly label |
+| `-p, --phrase <words>` | | Recovery phrase (skips interactive prompt) |
+| `--algorithm <secp256k1\|ml-dsa-65>` | `secp256k1` | Wallet signing algorithm |
+
+`ml-dsa-65` wallets use `QuantHDWallet` and derive `qm65...` bech32m addresses. Wallet-JWT commands and datalake `--wallet` mode require secp256k1 until ML-DSA-65 has a standardized JOSE algorithm.
+Wallet labels must be unique. If `create` is run without `--label`, the CLI uses the first available `wallet#` label, starting with `wallet0`.
+
+#### `aries wallet export`
+| Option | Default | Description |
+|---|---|---|
+| `--id <wallet-id>` | active | Wallet id or label |
+
+#### `aries wallet use <id>` / `aries wallet remove <id>`
+| Positional | | Description |
+|---|---|---|
+| `id` | required | Wallet id or label |
+
+#### `aries wallet rename <id> <label>`
+| Positional | | Description |
+|---|---|---|
+| `id` | required | Wallet id or current label |
+| `label` | required | New label |
+
+### Session
+
+```sh
+aries wallet unlock                   # Cache the wallet password (encrypted at rest) for a TTL
+aries wallet lock                     # Clear the cached unlocked session
+aries wallet password change          # Change the wallet password (re-encrypts every stored phrase)
+```
+
+#### `aries wallet unlock`
+| Option | Default | Description |
+|---|---|---|
+| `--ttl <seconds>` | `900` | Session lifetime in seconds (default 15 min) |
+
+`lock` and `password change` take no command-specific options.
+
+### Reset (lost password recovery)
+
+```sh
+aries wallet reset                    # Destroy all wallet data — only path forward when password is lost
+```
+
+Use this only when you have forgotten your wallet password. There is no other way to recover from a lost password — encrypted seed phrases cannot be decrypted without it.
+
+`reset` deletes the entire wallet directory (`~/.xl1/wallet/cli` by default): every stored seed phrase, every derived account, every address-book entry, every saved contact, every saved network configuration, and the active session. **This is irreversible unless you have a backup** (see [`aries wallet backup`](#backup)).
+
+To prevent accidental loss, the command requires two interactive confirmations:
+1. Type the literal word `RESET` (uppercase, exactly).
+2. Answer `y` to the final `[y/N]` prompt.
+
+Anything else cancels with no changes. There is no `--force` flag.
+
+If no wallet has been initialized (e.g. on first run), `reset` is a no-op and prints `No wallet found — no reset needed.`
+
+### Accounts
+
+```sh
+aries wallet account list                    # List derived accounts in the active wallet
+aries wallet account show <offset>           # Show details for a derived account
+aries wallet account derive <offset>         # Derive a new account at the given HD offset
+aries wallet account label <offset> <label>  # Label a derived account
+aries wallet account remove <offset>         # Remove an account from the address book
+```
+
+All `account` commands take an HD path offset positional (e.g. `0`).
+
+#### `aries wallet account derive <offset>`
+| Option | Default | Description |
+|---|---|---|
+| `-l, --label <text>` | | Friendly label for the account |
+
+### Balance & signing
+
+#### `aries wallet balance [offset]`
+| Positional | | Description |
+|---|---|---|
+| `offset` | `0` | HD path offset |
+
+#### `aries wallet sign <file>`
+| Positional | | Description |
+|---|---|---|
+| `file` | required | Path to a JSON payload file |
+
+| Option | Default | Description |
+|---|---|---|
+| `-o, --offset <n>` | `0` | HD path offset of the signer |
+| `-O, --output <path>` | | Write output to file instead of stdout |
+
+Produces a BoundWitness.
+
+### Self-signed JWT
+
+A wallet account can mint a JWT-shaped, time-bounded permission token that a site verifies locally, without running its own login flow. Think of it as reverse OAuth: the holder signs an attestation declaring an audience (the domain they intend to use the token at) and an expiration; the site checks the signature and claims and grants the session.
+
+The token is the standard `header.payload.signature` JWT format, base64url-encoded. The signing input is `keccak256(utf8("${headerB64}.${payloadB64}"))` and the alg is `ES256K` (secp256k1 ECDSA). The header carries both `kid` (signer address) and `pub` (full public key) so verification is self-contained — no out-of-band pubkey lookup is needed.
+
+**Header** fields: `alg` (`ES256K`), `typ` (`JWT`), `kid` (40-char lowercase hex address), `pub` (hex public key bytes).
+
+**Payload** is an XYO Payload (must include `schema`). The default schema is `network.xyo.auth.signin` and the standard claims are `iss` (mirrors `kid`), `aud`, `iat`, `exp`, plus optional `nbf`, `nonce`, and any extra fields supplied via `--payload-file` or `--claim`.
+
+> Note: this is the **single-signed** path. A future co-signed BoundWitness flow (where the site offers a permissions BW signed by its own address and the client co-signs) is planned and will reuse the same schema and account-derivation infrastructure.
+
+#### `aries wallet jwt create`
+| Option | Default | Description |
+|---|---|---|
+| `-a, --audience <domain>` | required | Audience — becomes the `aud` claim (e.g. `xyo.network`) |
+| `--ttl <seconds>` | `3600` | Lifetime in seconds (mutually exclusive with `--exp`) |
+| `--exp <unix-seconds>` | | Absolute expiration; alternative to `--ttl` |
+| `--schema <schema>` | `network.xyo.auth.signin` | XYO schema for the payload |
+| `--payload-file <path>` | | JSON file with extra payload fields (CLI flags win) |
+| `--claim <key=value>` | | Extra claim, repeatable; numeric/boolean strings are coerced |
+| `-o, --offset <n>` | `0` | HD path offset of the signer |
+| `-O, --output <path>` | | Write the token to a file instead of stdout |
+
+#### `aries wallet jwt verify [token]`
+| Positional | | Description |
+|---|---|---|
+| `token` | | JWT to verify (omit to read from `--input` or stdin) |
+
+| Option | Default | Description |
+|---|---|---|
+| `-a, --audience <domain>` | | If provided, fail unless `aud` matches |
+| `-i, --input <path>` | | Read JWT from file |
+| `--now <unix-seconds>` | | Override current time — useful for tests |
+
+Prints `{ ok, header, payload, reasons? }` JSON. Exits non-zero on any verification failure (signature, expiry, audience mismatch, kid/iss mismatch, public-key/address mismatch).
+
+#### `aries wallet jwt decode [token]`
+Decode header and payload without verifying the signature. Useful for debugging.
+
+### Transactions
+
+```sh
+aries wallet send <recipient> <amount>      # Send XL1 to a recipient address
+aries wallet tx sign <file>                 # Sign an unsigned transaction JSON file
+aries wallet tx broadcast <file>            # Broadcast a signed transaction JSON file
+```
+
+#### `aries wallet send <recipient> <amount>`
+| Positional | | Description |
+|---|---|---|
+| `recipient` | required | Recipient address (`0x…`) |
+| `amount` | required | Amount in the selected unit (XL1 by default) |
+
+| Option | Default | Description |
+|---|---|---|
+| `-o, --offset <n>` | `0` | HD path offset of the sender |
+| `--xl1` | | Interpret amount as XL1 (default) |
+| `--milli` | | Interpret amount as milli XL1 |
+| `--micro` | | Interpret amount as micro XL1 |
+| `--nano` | | Interpret amount as nano XL1 |
+| `--pico` | | Interpret amount as pico XL1 |
+| `--femto` | | Interpret amount as femto XL1 |
+| `--atto` | | Interpret amount as atto XL1; must be a whole number |
+| `--dry-run` | `false` | Build and sign the transfer without submitting it |
+| `--json` | `false` | Emit machine-readable JSON output |
+| `--attempts <n>` | `30` | Confirmation polling attempts |
+| `--delay <ms>` | `2000` | Delay between confirmation attempts |
+
+#### `aries wallet tx sign <file>`
+| Positional | | Description |
+|---|---|---|
+| `file` | required | Path to unsigned transaction JSON |
+
+| Option | Default | Description |
+|---|---|---|
+| `-o, --offset <n>` | `0` | HD path offset of the signer |
+| `-O, --output <path>` | | Write signed tx to file instead of stdout |
+
+#### `aries wallet tx broadcast <file>`
+| Positional | | Description |
+|---|---|---|
+| `file` | required | Path to signed transaction JSON |
+
+| Option | Default | Description |
+|---|---|---|
+| `-o, --offset <n>` | `0` | HD path offset for client connection |
+
+### Networks
+
+```sh
+aries wallet network list                # List configured networks
+aries wallet network add <id> <rpcUrl>   # Add a custom network
+aries wallet network use <id>            # Set the active network
+aries wallet network remove <id>         # Remove a custom network
+```
+
+#### `aries wallet network add <id> <rpcUrl>`
+| Positional | | Description |
+|---|---|---|
+| `id` | required | Network id (unique) |
+| `rpcUrl` | required | Gateway RPC URL |
+
+| Option | Default | Description |
+|---|---|---|
+| `-l, --label <text>` | | Friendly label |
+| `--chain-id <hex>` | | Chain id (hex) |
+
+`use` and `remove` take a network `id` positional only.
+
+### Contacts
+
+```sh
+aries wallet contact list                       # List address-book contacts
+aries wallet contact add <address> <label>      # Add or update a contact
+aries wallet contact rename <address> <label>   # Rename an existing contact
+aries wallet contact remove <address>           # Remove a contact
+```
+
+All take an `address` positional (`0x…`); `add`/`rename` also take a `label` positional. No additional flags.
+
+### Backup
+
+```sh
+aries wallet backup export <file>   # Export address books and contacts to a JSON file
+aries wallet backup import <file>   # Import a wallet backup JSON file (merges into current state)
+```
+
+`file` is the only positional; no additional flags.
+
+---
+
+## `aries witness` — Observe data and produce XYO-compliant payloads
+
+```sh
+aries witness timestamp     # Capture the current timestamp
+aries witness system-info   # Capture system information (OS, CPU, memory, etc.)
+aries witness url           # Capture metadata and content from a URL
+aries witness bank          # Capture bank account snapshots or Capital One product catalog data
+aries witness pentair       # Capture Pentair ScreenLogic pool equipment state
+aries witness pentair-intellichem # Capture and graph Pentair IntelliChem chemistry data
+aries witness pentair-schedules   # Capture Pentair ScreenLogic schedules with circuit and pump context
+aries witness app           # Inspect installed applications
+aries witness app list      # List installed macOS applications
+```
+
+### Common witness flags
+
+These flags are available on every `witness` leaf:
+
+| Option | Default | Description |
+|---|---|---|
+| `--json` | `false` | Output raw JSON |
+| `-o, --output <path>` | | Write output to file |
+| `--pretty` | `true` | Pretty-print JSON output |
+| `--bound-witness` | `false` | Wrap payloads in a BoundWitness |
+| `--binary-dir <path>` | `~/.aries/binaries/` | Directory for binary artifacts |
+
+### Per-command additions
+
+#### `aries witness url`
+| Option | Default | Description |
+|---|---|---|
+| `--url <url>` | required | The URL to fetch |
+
+#### `aries witness bank`
+
+```sh
+aries witness bank --provider capitalone --account-id acct-123 --from 2026-06-01 --to 2026-06-25 --json
+aries witness bank --provider capitalone --access-token "$CAPITALONE_TOKEN" --include-raw --json
+aries witness bank --provider capitalone --resource products --client-id "$CAPITALONE_CLIENT_ID" --client-secret "$CAPITALONE_CLIENT_SECRET" --json
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `--provider <capitalone>` | `capitalone` | Bank provider |
+| `--resource <accounts\|products>` | `accounts` | `accounts` for private account APIs; `products` for Capital One's sandbox deposit product catalog |
+| `--from <value>` | | Transaction window start passed as query param `from` |
+| `--to <value>` | | Transaction window end passed as query param `to` |
+| `--account-id <id>` | | Provider account id for balances and transactions |
+| `--include-raw` | `false` | Store raw provider JSON as witness binary artifacts |
+| `--redaction <default\|none>` | `default` | Hash provider account/transaction ids unless explicitly set to `none` |
+| `--env <sandbox\|production>` | `bank config` | Environment label |
+| `--base-url <url>` | `bank config` | Capital One API base URL |
+| `--token-url <url>` | `bank config` | OAuth client-credentials token URL |
+| `--access-token <token>` | `ARIES_CAPITALONE_ACCESS_TOKEN` | Pre-issued bearer token; not persisted |
+| `--client-id <id>` | `bank config` | OAuth client id |
+| `--client-secret <secret>` | `bank config` | OAuth client secret |
+| `--scope <scope>` | `bank config` | Optional OAuth client-credentials scope |
+| `--api-version <version>` | `5` | Capital One products media-type version |
+| `--operation <retrieve-products\|retail-products\|search>` | `search` | Capital One products operation |
+| `--product-id <id>` | `~` for product-id operations | Capital One path product id |
+| `--body <json>` | `{"isCollapseRate":true}` for `search`; `{}` otherwise | JSON body for Capital One products POST operations |
+| `--body-file <path>` | | JSON body file for Capital One products POST operations |
+| `--accounts-path <path>` | `bank config` | Accounts endpoint path |
+| `--balances-path <path>` | `bank config` | Balances endpoint path; may include `{accountId}` |
+| `--transactions-path <path>` | `bank config` | Transactions endpoint path; may include `{accountId}` |
+
+With `--resource accounts`, the bank witness returns one
+`network.xyo.bank.account-snapshot` payload containing normalized accounts,
+balances, and transactions. By default, provider account and transaction
+identifiers are hashed.
+
+With `--resource products`, the bank witness calls Capital One's documented
+`Retrieve Consumer Bank Products` sandbox API and returns one
+`network.xyo.bank.product-catalog` payload. This is product catalog data, not a
+consumer account snapshot. The default product request follows Capital One's
+published "Scenario 1a: All Products" example: `POST /deposits/products/~/search`
+with `{"isCollapseRate": true}`.
+
+If Capital One returns `{"id":"200008","text":"no endpoint matched for request"}`
+from the product request after OAuth succeeds, the client credentials are valid
+but Capital One's sandbox gateway did not match the product endpoint. Verify the
+app is connected to DevExchange product `1359-5` in the sandbox and confirm the
+active sandbox base path with Capital One.
+
+#### `aries witness pentair-intellichem`
+| Option | Default | Description |
+|---|---|---|
+| `--history` | `false` | Fetch IntelliChem controller history |
+| `--from <date\|age>` | `24h` | History start as ISO date or relative age like `30m`, `6h`, `7d` |
+| `--to <date\|age>` | now | History end as ISO date or relative age |
+| `--save` | `false` | Save normalized samples to the JSONL series file |
+| `--series-file <path>` | `pentair config` or `~/.aries/pentair/intellichem.jsonl` | JSONL file used for saved samples and graphing |
+| `--graph <path>` | | Write a standalone HTML graph |
+| `--graph-only` | `false` | Render a graph from the series file without connecting to ScreenLogic |
+| `--address <ip>` | `pentair config` | Connect directly to a ScreenLogic adapter IP instead of UDP discovery |
+| `--port <number>` | `pentair config` or `80` | ScreenLogic adapter TCP port for direct connection |
+| `--password <password>` | `pentair config` or `SCREENLOGIC_PASSWORD` | ScreenLogic password for direct connection, if configured |
+| `--system-name <name>` | `pentair config` or `Pentair ScreenLogic` | ScreenLogic system name for direct connection |
+| `--response-timeout <ms>` | `pentair config` or `15000` | Milliseconds to wait for each ScreenLogic command response |
+| `--search-timeout <ms>` | `pentair config` or `5000` | Milliseconds to wait for each UDP discovery attempt |
+| `--search-attempts <count>` | `pentair config` or `3` | Number of UDP discovery attempts before failing |
+
+Examples:
+
+```sh
+aries witness pentair-intellichem --save
+aries witness pentair-intellichem --history --from 7d --save --graph intellichem.html
+aries witness pentair-intellichem --graph-only --graph intellichem.html
+```
+
+#### `aries witness pentair-schedules`
+| Option | Default | Description |
+|---|---|---|
+| `--address <ip>` | `pentair config` | Connect directly to a ScreenLogic adapter IP instead of UDP discovery |
+| `--port <number>` | `pentair config` or `80` | ScreenLogic adapter TCP port for direct connection |
+| `--password <password>` | `pentair config` or `SCREENLOGIC_PASSWORD` | ScreenLogic password for direct connection, if configured |
+| `--system-name <name>` | `pentair config` or `Pentair ScreenLogic` | ScreenLogic system name for direct connection |
+| `--response-timeout <ms>` | `pentair config` or `15000` | Milliseconds to wait for each ScreenLogic command response |
+| `--search-timeout <ms>` | `pentair config` or `5000` | Milliseconds to wait for each UDP discovery attempt |
+| `--search-attempts <count>` | `pentair config` or `3` | Number of UDP discovery attempts before failing |
+
+Example:
+
+```sh
+aries witness pentair-schedules --json
+```
+
+#### `aries witness app list`
+| Option | Default | Description |
+|---|---|---|
+| `--scope <all\|global\|system\|user>` | `all` | Filter by install scope |
+
+`witness timestamp`, `witness system-info`, and `witness pentair` take only the common flags.
+
+---
+
+## `aries xyo` — XYO protocol utilities
+
+### `aries xyo rewards <sequence|mainnet> <view>`
+
+Query finalized XL1 reward activity through the SDK REST gateway and its block
+rollup indexes.
+
+```sh
+aries xyo rewards sequence summary
+aries xyo rewards mainnet steps --from-block 500000
+aries xyo rewards sequence recipients --stage redeemed --limit 25
+aries xyo rewards mainnet recipients --stage supplemental-funding --limit 25
+aries xyo rewards sequence address <address> --json
+aries xyo rewards sequence summary --from-block 510000 --explain
+```
+
+| View | Description |
+|---|---|
+| `summary` | Direct and supplemental funding, allocation, payout, actual step-holder balance, unique-recipient, and reward-step totals |
+| `steps` | Per-step direct funding, supplemental funding, and allocation; optionally filter with `--step-level` |
+| `recipients` | Rank recipients at the `funded`, `supplemental-funding`, `allocated`, or `redeemed` stage |
+| `address <address>` | Reward lifecycle events involving an escrow, staker, or destination |
+
+| Common option | Default | Description |
+|---|---|---|
+| `--from-block <n>` | `0` | First finalized block to include |
+| `--to-block <n>` | finalized head | Last finalized block to include |
+| `--concurrency <n>` | `2` | Indexed ranges read concurrently, from 1 to 16 |
+| `--json` | `false` | Stable machine-readable output; XL1 amounts include atto and decimal forms |
+| `--explain` | `false` | Show indexed frame use, direct reads, gateway setup/scan/balance requests, bytes, timing, and SDK budget warnings |
+| `--no-progress` | | Suppress the default gateway and scan progress written to stderr |
+
+The reward lifecycle distinguishes direct funding (reward pool to step holder)
+from supplemental funding (any other inbound transfer to a deterministic step
+holder), followed by allocation (step holder to reward escrow) and redemption
+(reward escrow to a final wallet). “Total Rewards Funded” is direct plus
+supplemental funding. “Total Rewards Paid Out” means redeemed rewards. Exact
+staker identity is visible when an escrow redeems, so
+`uniqueObservedStakers` counts stakers seen in redemption context; it is not an
+allocation-time staker count.
+
+“Outstanding in Step Holders” is the actual sum of deterministic holder account
+balances at `--to-block`, read in one SDK batch against the finalized range.
+The separately reported step-holder lifecycle net is direct plus supplemental
+funding, minus allocation and rounding returns. With a later `--from-block`,
+that lifecycle value and the reward-escrow value are labeled range deltas,
+while the step-holder balance remains the actual balance at `--to-block`.
+
+`--explain` is intentionally part of the product rather than only a debugging
+flag. It separates gateway startup work from the reward scan and makes direct
+block fallbacks, payload volume, and repeated request patterns visible. Those
+measurements identify reward-specific indexes worth publishing through the XL1
+indexing pipeline as full-history use grows.
+
+Human-readable commands print gateway initialization and bounded scan progress
+to stderr by default. JSON commands remain quiet so stdout stays
+machine-readable; SDK diagnostics and the completion footer also stay on
+stderr. Add `--verbose` to a JSON command to opt into progress.
+
+Every `aries` and `ariesi` invocation writes a status-aware timing footer to
+stderr after the command finishes: `✅ Succeeded in <milliseconds>ms.` or
+`❌ Failed in <milliseconds>ms.` This includes JSON commands without changing
+their machine-readable stdout.
+
+### `aries xyo tx validate [data]`
+
+Validate one or more XL1 transactions. Reads from a file path, inline JSON, or stdin.
+
+| Positional | | Description |
+|---|---|---|
+| `data` | | Path to a `.json`/`.jsonl` file, or an inline transaction JSON tuple `[bw, payloads[]]`. Omit to read from stdin. |
+
+| Option | Default | Description |
+|---|---|---|
+| `-d, --detail` | `false` | Print per-transaction error details (always shown for invalid transactions) |
+
+**Input modes** (resolved in priority order):
+
+| Mode | Example |
+|---|---|
+| File path | `aries xyo tx validate ./tx.json` |
+| File path (JSONL batch) | `aries xyo tx validate ./txs.jsonl` |
+| Inline JSON | `aries xyo tx validate '[[...], [...]]'` |
+| Piped stdin | `cat txs.jsonl \| aries xyo tx validate` |
+
+**Supported file formats:**
+- `.json` — a single transaction tuple `[boundWitness, payloads[]]`, or a JSON array of tuples
+- `.jsonl` / `.ndjson` — one transaction tuple per line
+
+**Output:**
+
+```text
+Total:   3
+Valid:   2
+Invalid: 1
+
+[2] ./txs.jsonl:3
+  - TransactionGasValidator: insufficient gas
+```
+
+**Exit codes:** `0` = all valid, `1` = any invalid or parse error.
+
+---
+
+## Configuration
+
+Aries configuration lives under `~/.aries/` (or `$ARIES_HOME` if set). Wallet data lives under `~/.xl1/wallet/cli` (or `$XL1_WALLET_HOME` if set) and is encrypted at rest using your wallet password.
+
+---
+
+## License
+
+LGPL-3.0-only © XY Labs
+
+## Credits
+
+[Made with 🔥 and ❄️ by AriesTools](https://arietrouw.com)