@ariestools/cli 0.1.20 → 0.1.22

package/README.md

@@ -1,6 +1,6 @@
 # @ariestools/cli
 
-Aries Tools CLI — a suite by Arie Trouw for AI-client tooling, sandboxed command execution, XL1 datalake provisioning, content hashing (strict + fuzzy + perceptual), XL1 wallet management, payload witnessing, and XYO protocol utilities.
+Aries Tools CLI — a suite by Arie Trouw for AI-client tooling, XL1 datalake provisioning, content hashing (strict + fuzzy + perceptual), XL1 wallet management, payload witnessing, and XYO protocol utilities.
 
 ## Installation
 
@@ -15,7 +15,8 @@ pnpm add -g @ariestools/cli
 ```sh
 aries --help
 aries info
-aries hash --algorithm pdq ./photo.jpg
+aries secrets status
+ariesi hash --algorithm pdq ./photo.jpg
 ariesi plex libraries
 ariesi gate pair ticker BTC_USDT
 aries wallet create
@@ -33,9 +34,9 @@ private monorepo packages (`aries-datalake-plane`, etc.) installed.
 export ARIES_HOME=/tmp/aries-test-$$
 
 # Free ports by default (or pass --control-port / --plane-port)
-aries datalake dev up
+aries datalake up
 aries datalake list
-aries datalake dev down
+aries datalake down
 ```
 
 ### Programmatic client (no shell-out per request)
@@ -46,7 +47,7 @@ import {
   RestPayloadsClient,
 } from '@ariestools/cli/datalake'
 
-// After `aries datalake dev up` (or with baseUrl + authToken options)
+// After `aries datalake up` (or with baseUrl + authToken options)
 const control = createDatalakeClient()
 const lakes = await control.list()
 // …
@@ -57,18 +58,22 @@ Private workspace packages stay private; runtime daemons ship under
 
 ## Top-level commands
 
+The reference includes public `aries` commands and internal `ariesi` commands.
+Internal commands require the private CLI build and an internal license tier;
+the public installation cannot run them.
+
 ```text
 aries ai           AI client tools
-aries bank         Manage bank witness settings
+ariesi 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
 ariesi gate        Query the Gate exchange API (internal build)
-aries hash [file]  Generate a hash (sha256, xyo, fuzzy, perceptual)
+ariesi 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 npmjs        Inspect and lint npmjs org packages
+ariesi pentair      Manage Pentair ScreenLogic systems
 ariesi plex        Inspect and manage Plex Media Server (internal build)
+aries secrets      Secrets foundation, static AI instructions, and the human-only vault path
 aries wallet       XL1 wallet — seed phrases, accounts, transactions, contacts
 aries witness      Observe data and produce XYO-compliant payloads
 aries xyo          XYO protocol utilities
@@ -81,11 +86,561 @@ Available on every command:
 | Option | Description |
 |---|---|
 | `-v, --verbose` | Enable verbose output |
+| `--help-ai` | Print static AI-oriented help for a registered command path |
 | `--version` | Show version number |
 | `--help` | Show help |
 
 ---
 
+## `aries secrets` — Secrets foundation and the human-only vault path
+
+The current implementation provides versioned, static discovery and status,
+the read-only inventory listing, local bastion profile and provider
+configuration, and eight human-only commands, `init`, `create`, `reveal`,
+`set`, `generate`, `delete`, `list`, and `describe`, each documented in the
+next sections:
+
+```sh
+aries secrets status
+aries secrets status --json
+aries secrets --help-ai
+aries secrets --help-ai --json
+aries secrets init                                  # human-only; no --json form
+aries secrets create --name "Deploy token" --input-fd 3 3<file   # human-only; value from fd 3, else the prompt
+aries secrets reveal --secret-id sec_…              # human-only; the value, once, to the terminal
+aries secrets set --secret-id sec_… --expected-version <v> --input-fd 3 3<file   # human-only; compare-and-swap replace
+aries secrets generate --name "Signing key" --kind random-bytes --length 64      # human-only; drawn in-process, never printed
+aries secrets delete --secret-id sec_… --expected-version <v>                    # human-only; compare-and-swap delete, not recoverable
+aries secrets list                                  # human-only; metadata only
+aries secrets describe --secret-id sec_…            # human-only; metadata only
+```
+
+`status` reports the implementation phase (`human-only-storage`) plus three
+live observations: `bastionConfigured` is true when the bastion profile store
+holds at least one profile and `data.bastionStore` names the store path and
+its state (`configured`, `empty`, or `unreadable` — a refused or corrupt store
+is reported, never thrown); `data.providers` carries the negotiated state of
+every provider entry on the selected profile; and `data.humanOnlyPath` states
+whether the human-only path is available on this platform. `data.state` is
+`not-initialized` until a vault exists on the selected profile and
+`human-only-storage` once one does. There is no `initialized` state and no
+authenticated operator: `init` performs no operator or recovery bootstrap, so
+the realm stays provisional and nothing accepts a grant.
+
+`aries --help-ai [--json]` discovers registered AI-help subtrees. AI help is
+embedded package content and runs before `.env`, settings, licensing, provider,
+or broker initialization. Its manifest marks future commands as `planned`, the
+human-only commands as `human-only` (risk `human-only`, no `--json` option),
+and carries a `humanOnlyPath` block: `brokered: false`, `humanAttested:
+true`, the eight conditions every human-only command enforces, the platforms
+on which they can be satisfied (`darwin`, `linux`), `unlock:
+'per-invocation'`, and `lease: 'not-available'`.
+
+Agent-operational secret access is not implemented. This foundation cannot
+connect to a bastion, create AI identities, authenticate with JWTs, manage
+grants or approvals, or broker a secret to any program. The inventory listing
+below observes presence metadata only: it initializes no provider and reads no
+secret value. The bastion profile and provider commands record non-secret
+configuration only: they contact no bastion and create no socket or vault.
+The one path that touches a vault is human-only and unbrokered, described
+under `aries secrets init`, `aries secrets create`, `aries secrets reveal`,
+and the `set`, `generate`, `delete`, `list`, and `describe` sections below.
+
+### The refusal contract
+
+All eight human-only commands — `init`, `create`, `reveal`, `set`,
+`generate`, `delete`, `list`, and `describe` — refuse unless standard input
+and standard output are both interactive terminals, the platform provides
+`/dev/tty`, `stty`, and a process-ancestry probe (an allow-list, so `win32`
+and any unknown platform are refused outright), no AI agent host is detected
+through a documented environment signal or an agent binary in the process
+ancestry (an ambiguous probe fails closed), and argv carries no
+structured-output option (`--json`, `--no-json`) and no delivery option
+(`--delivery`, `--destination`, `--output`, `--out`, `--out-file`, `--fd`,
+`--env`, `--clipboard`, `--temp-file`, `--to`) anywhere — including before
+the `secrets` word. A secret value still has two ways in, both of them input
+channels rather than delivery: the masked prompt on the attached terminal,
+and `--input-fd <fd>` on `create` and `set`, which reads the value from a
+descriptor the caller opened. Every refusal is `HUMAN_CHANNEL_REQUIRED`
+(exit 2) with a fixed message on standard error that never reflects an argv
+value and nothing at all on standard output, and the two kinds differ in
+what they record: a refusal by the channel gate — a pipe, a non-terminal, an
+unsupported platform, a detected or ambiguous agent host — is recorded as a
+human-attested `refused` audit event, while an argv refusal is caught by the
+preflight before any store is opened and writes no audit event at all. The
+gate conditions are evaluated in the order above, so a piped or captured
+caller is refused before any `ps` probe runs. Passing the gate refuses the
+non-interactive case; it is not proof of a human, because a pseudo-terminal
+remains agent-drivable.
+
+No MCP tool and no GUI reaches this path. The `aries mcp` servers register no
+tool that names a secret and import nothing from the secrets action tree; the
+Electron shell and the dashboard import nothing from that tree either — not
+the human-only modules, not the barrel that re-exports them, not the provider
+seam, and not the encrypted-file vault package — and neither declares
+`@ariestools/cli-lib` as a dependency (the dashboard reads only
+`secrets inventory list --json` by running the packed CLI, which reads no
+value). The vault package itself is not a GUI or IPC API: the only consumers
+of its unlock, create, re-key, and record primitives are the human-only
+command modules that handle plaintext and the provider seam they load it
+through. There is no socket, no daemon, and no lease — a command unlocks the
+vault for that invocation and locks it again before it returns.
+
+### Storage layout under `~/.aries/secrets`
+
+`ARIES_HOME` relocates `~/.aries` in full. Everything the CLI writes below it
+is created `0600` inside `0700` directories. The three stores it owns —
+`config/bastions.json`, `realms/<realmId>/secrets-index.json`, and
+`audit/human-attested.jsonl` — are also checked when they are read: a group
+or other permission bit, a foreign owner, a symlink, a non-regular file, or
+an oversized one fails the command and names the `chmod` or `chown` fix
+rather than repairing it. The vault files are written the same way and are
+refused on a symlink, a non-regular file, or an oversized one, and their
+directory is created `0700`. Two rows below are operator-authored and are
+never written, moved, or permission-checked by the CLI: `inventory.json`,
+read as declarations only, and `realms/<realmId>/denies.json`, which refuses
+every secret-touching operation in this milestone by existing at all.
+
+| Path | Contents |
+| --- | --- |
+| `config/bastions.json` | The bastion profile envelope: realms, bastions, endpoints, provider entries, and the active selection. Non-secret. `ARIES_SECRETS_BASTIONS` redirects it (absolute path). |
+| `vaults/<providerId>/vault.json` | The encrypted-file vault header, format v1: plaintext parameters only — the vault ID, PBKDF2-SHA256 at 100,000 iterations, AES-256-GCM with a 12-byte IV, and the creation time. |
+| `vaults/<providerId>/vault-password.json` | The password verifier: the PBKDF2 salt and a SHA-256 hash of the derived key. Never the password. |
+| `vaults/<providerId>/records.json` | Every secret, as ciphertext with its authenticated metadata. The display name lives inside the encrypted body. |
+| `realms/<realmId>/secrets-index.json` | The routing index: secret ID → `{ providerId, digest }`, and nothing else. |
+| `realms/<realmId>/denies.json` | Deny records, consulted before every secret-touching operation. Nothing in this milestone writes it. |
+| `audit/human-attested.jsonl` | The hash-chained, append-only human-attested audit log: one event per line, no secret value and no grant evidence. |
+| `inventory.json` | The machine-wide managed-secret declarations, written by the operator and only read here. Presence metadata only. `ARIES_SECRETS_INVENTORY` redirects it. |
+
+`broker.sock` is recorded on a local profile as the endpoint the future broker
+would use; no socket is created, bound, or connected to in this build.
+
+## `aries secrets inventory` — Managed secrets visibility
+
+```sh
+aries secrets inventory list
+aries secrets inventory list --repo owner/myapp
+aries secrets inventory list --source env --env-file ./deploy/.env --json
+```
+
+`secrets` is always registered at the free tier, so every example works
+unchanged in the internal `ariesi` build.
+
+Managed secrets are declared in one schema at two scopes, each a JSON file
+with a root-level `inventory` list:
+
+- `~/.aries/secrets/inventory.json` (override with `ARIES_SECRETS_INVENTORY`;
+  `ARIES_HOME` relocates `~/.aries`) — machine-wide entries, each optionally
+  naming its `repos`. The legacy `~/.config/aries/secrets.json` is still read
+  when the new file is absent, with a notice on stderr and
+  `data.legacyInventoryPath` under `--json`; move it to the new path.
+- `<repo>/.config/aries/secrets.json` — entries needed by that repository's
+  agents. These files are safe to commit: the closed entry shape
+  (`service`, `account`, optional `label`, `env`, and — global only — `repos`)
+  structurally rejects value-bearing fields, so a committed file can never
+  become a secret store.
+
+```json
+{
+  "version": 1,
+  "inventory": [
+    {
+      "account": "ci-token",
+      "env": "GITHUB_TOKEN",
+      "label": "GitHub token",
+      "service": "github"
+    }
+  ]
+}
+```
+
+Presence is metadata only and never returns a value: on macOS the default
+`auto` source probes the Keychain by `(service, account)` existence without
+requesting the password; elsewhere (or with `--source env`) presence means the
+mapped `env` variable is set and non-empty after `.env` loading. Repositories
+are discovered below `ARIES_CODE_ROOT` (default `~/GitHub`). The `--json`
+envelope follows the secrets result schema and contains identifiers and
+presence booleans only — suitable as the dashboard panel's data source.
+
+## `aries secrets bastion` — Bastion profiles
+
+```sh
+aries secrets bastion add --name "Laptop bastion"
+aries secrets bastion list
+aries secrets bastion show                      # active or sole profile
+aries secrets bastion show "Laptop bastion"     # by display name
+aries secrets bastion show --bastion bpf_…      # by profile ID
+aries secrets bastion use "Laptop bastion"
+aries secrets bastion remove "Laptop bastion"
+aries secrets bastion list --json
+```
+
+A bastion profile is a closed, versioned, non-secret record naming a realm,
+a bastion, its endpoint, and its providers; it holds no password, token, or
+key material. Profiles live in one envelope at
+`~/.aries/secrets/config/bastions.json` (`ARIES_HOME` relocates `~/.aries`;
+`ARIES_SECRETS_BASTIONS` redirects the file for tests and must be absolute),
+written `0600` inside a `0700` directory. A file or directory with group or
+other permission bits, a foreign owner, a file over 256 KiB, or an unparseable
+file fails every command with `BASTION_CONFIGURATION_INVALID` (exit 9), naming
+only the path and the fix. A redirected store is disclosed on stderr in human
+output and as `data.bastionStore` under `--json`.
+
+- `add --name <displayName> [--kind local-ipc]` mints the profile, realm, and
+  bastion identifiers, derives the audience, and records the inert socket path
+  `<secretsRoot>/broker.sock` without touching the filesystem. The first
+  profile written to an empty store becomes the active selection. Every new
+  profile starts with one `encrypted-file` provider entry (`encrypted-local`,
+  vault directory `<secretsRoot>/vaults/encrypted-local`); no vault is created.
+  `--kind remote` is refused with `CAPABILITY_UNSUPPORTED` until Phase 9. A
+  display name that collides with an existing profile ID or display name is an
+  error, never an overwrite.
+- `list` reads the store only: it never contacts a bastion or starts a broker,
+  succeeds on a missing store with an empty table, and marks a `remote`
+  profile `unusable in this build`.
+- `show [<profile>] [--bastion <profile>]` resolves by profile ID first, then
+  display name, else the active profile, else the sole profile; the result
+  names which namespace matched. With nothing selectable it fails with
+  `BASTION_NOT_SELECTED`. The endpoint is labeled `not used in this build`.
+- `use <profile>` writes `activeProfileId` and nothing else. Selection is not
+  authorization; a `remote` profile is refused.
+- `remove <profile>` deletes the local record and clears an active selection
+  that pointed at it. It revokes nothing: grants, delegations, and enrollments
+  at the removed realm remain in force and must be revoked at the bastion
+  separately, which the result states in both output forms.
+
+`add`, `use`, and `remove` are mutating: they print the store path on stderr
+for every write, and an agent must not run them without explicit operator
+instruction (the AI-help manifest carries that rule). Every command takes
+`--json`; the envelope follows the secrets result schema and typed failures
+map to the secrets exit codes.
+
+---
+
+## `aries secrets provider` — Provider entries
+
+```sh
+aries secrets provider list
+aries secrets provider show                       # active or sole provider
+aries secrets provider show backup                # by provider ID
+aries secrets provider add --id backup --kind encrypted-file
+aries secrets provider add --id backup --kind encrypted-file --vault-path /srv/vaults/backup
+aries secrets provider configure backup --vault-path /srv/vaults/backup
+aries secrets provider use backup
+aries secrets provider remove backup
+aries secrets provider test                       # active or sole provider
+aries secrets provider test backup --json
+aries secrets provider list --bastion "Laptop bastion" --json
+```
+
+A provider entry is the non-secret placement record on a bastion profile:
+`providerId`, `kind`, and `configurationRef` (for `encrypted-file`, the
+absolute vault directory, default `<secretsRoot>/vaults/<providerId>`). It
+holds no password and no key material; the vault's own files hold those.
+Every command takes the inherited `--bastion <profile>` (profile ID first,
+then display name; omitted means the active profile, else the sole profile,
+else `BASTION_NOT_SELECTED`) and `--json`, discloses the store as
+`data.bastionStore`, and refuses a `remote` profile with
+`CAPABILITY_UNSUPPORTED`.
+
+- `add --id <providerId> --kind encrypted-file [--vault-path <dir>]` appends
+  one entry. The kind union is closed at the option table and again at the
+  record parser, so `memory` and `macos-keychain` are refused by both. A
+  duplicate ID is an error, never an overwrite. No vault and no directory is
+  created: initialization needs a password and is human-only.
+- `list` prints every entry with `initialized` — whether `vault.json` exists
+  at `configurationRef`, a stat only, with no unlock and no header parse —
+  and marks the active provider.
+- `show [<providerId>]` resolves by ID, else the active provider (set by
+  `use`), else the sole provider, and carries two fixed notes: unlock is
+  per-invocation with no lease, and compare-and-swap is cooperative (it holds
+  only among writers honoring the vault store lock).
+- `configure <providerId> --vault-path <dir>` replaces `configurationRef`
+  only; the kind is immutable and nothing is created, moved, or unlocked.
+- `remove <providerId>` deletes the entry and clears an active provider
+  selection that pointed at it. The vault directory is not deleted, which the
+  result states in both output forms. The last provider of a profile cannot
+  be removed; remove the profile instead.
+- `use <providerId>` records `activeProviderId`, which satisfies `--provider`
+  on management commands only. Placement on `create` and `generate` still
+  requires `--provider` whenever the profile lists more than one provider;
+  there is no default provider.
+- `test [<providerId>]` resolves like `show` and reports the adapter's
+  declared capabilities, `maximumSecretBytes`, a bounded health check, the
+  per-invocation unlock mode, and the cooperative compare-and-swap caveat.
+  It never prompts, unlocks, lists, or reads: the adapter is built around a
+  locked placeholder session, and a locked vault — the designed steady state
+  — succeeds with health `locked` and exit 0. Only an unavailable provider
+  fails (`PROVIDER_UNAVAILABLE`, exit 7): not initialized (`next.command`
+  names the human-only `init`), a corrupt header (reported with a redacted
+  diagnostic, never a path), or a health check that misses its deadline
+  (retryable). `status` runs the same negotiation for every provider entry
+  on the selected profile and reports `providerCount` and per-provider rows
+  under the same ok-when-locked rule; it still succeeds when every provider
+  is unavailable.
+
+`--vault-path` must be absolute and is refused when equal to or inside the
+resolved XL1 wallet root, or inside the directory named by `XL1_WALLET_HOME`
+or `ARIES_WALLET_HOME` when either is set, so a vault never shares a
+directory with a wallet store; the refusal names the rule, never the path.
+`add`, `configure`, `remove`, and `use` are mutating: they print the store
+path on stderr for every write, and an agent must not run them without
+explicit operator instruction.
+
+## `aries secrets init` — Human-only vault creation
+
+```sh
+aries secrets init                                   # mints "Local bastion" when no profile exists
+aries secrets init --name "Laptop bastion"           # display name for the minted profile
+aries secrets init --bastion "Laptop bastion"        # an existing profile
+aries secrets init --provider-id backup              # another entry; added to the profile when absent
+```
+
+`init` is the first human-only, unbrokered command. From an interactive
+terminal it resolves the bastion profile (or mints a local one when none
+exists), ensures an `encrypted-file` provider entry for `--provider-id`
+(default `encrypted-local`, vault directory
+`<secretsRoot>/vaults/<providerId>`), refuses an existing vault at that
+entry's location (`VERSION_CONFLICT`, exit 8; the refusal names the rule,
+never the path), prompts for the vault password twice on `/dev/tty` with
+the vault's 12-character minimum, creates the vault, opens it once to confirm
+it answers under that password, locks it again, and prints the profile,
+provider, and vault summary. Unlock is per-invocation: no lease, session
+file, or key survives the command. The password is read from the terminal
+alone — never from an environment variable or a command-line argument.
+
+`init` initializes one vault and one local profile only. It performs no
+operator or recovery bootstrap: the realm stays provisional in the plan's
+sense, nothing accepts a grant, and neither `status` nor `--help-ai`
+describes the operator as authenticated.
+
+Every human-only command enforces these rules, each covered by a test:
+
+- standard input and standard output must both be interactive terminals; a
+  piped, redirected, or captured channel fails with `HUMAN_CHANNEL_REQUIRED`
+  (exit 2) on stderr and writes nothing to stdout;
+- a detected AI agent host (Claude Code, Codex, Cursor, Aider, and the other
+  documented signals, or an agent binary in the process ancestry) is refused,
+  and an ambiguous probe fails closed;
+- there is no `--json` and no delivery option; `--json`, `--no-json`,
+  `--delivery`, `--destination`, `--output`, `--fd`, `--env`, `--clipboard`,
+  `--temp-file`, or `--to` anywhere in argv — including before the `secrets`
+  word — is refused with a fixed message before yargs runs, and the refused
+  value is never reflected;
+- the command is not mirrored as an MCP tool and is reachable over no IPC,
+  socket, or remote transport;
+- every run, refusal, and failure appends a human-attested, unbrokered event
+  to `<secretsRoot>/audit/human-attested.jsonl`; an event that cannot be
+  written refuses the operation (`AUDIT_UNAVAILABLE`);
+- the realm's deny records are consulted before a secret-touching operation
+  (`init` alone is exempt, because no realm exists before it mints one);
+  `create`, `reveal`, `set`, `generate`, `delete`, `list`, and `describe`
+  refuse with `POLICY_INVALID` (exit 5) when the deny set cannot be read,
+  which in this milestone includes any existing
+  `<secretsRoot>/realms/<realmId>/denies.json`, since nothing writes one yet;
+- on `win32` every human-only command fails with `HUMAN_CHANNEL_REQUIRED` and
+  reason `platform-unsupported`, which `status` and the manifest state.
+
+Agents must not invoke a human-only command, wrap it, or treat it as agent
+access: it identifies no principal, evaluates no grant, and confers nothing
+on any agent principal.
+
+## `aries secrets create` — Human-only secret storage
+
+```sh
+aries secrets create --name "Deploy token" --input-fd 3 3<./token.txt   # value from descriptor 3
+aries secrets create --name "Deploy token"                               # masked prompt, typed twice
+aries secrets create --name "API key" --provider backup                  # placement on a named entry
+```
+
+`create` stores one secret in the operator's own vault. From an interactive
+terminal it resolves the bastion profile (`--bastion`, else the active
+profile, else the sole profile — it never mints one), places the secret on
+`--provider` (required when the profile lists more than one provider,
+implied when it lists exactly one; the active provider never satisfies
+placement), consults the realm's deny records, appends the `intent` audit
+event, prompts for the vault password on `/dev/tty`, collects the value,
+writes the record, indexes it, locks the vault, and prints the secret ID
+and version — never the value.
+
+The value comes from exactly one of two sources. `--input-fd <n>` reads a
+trusted producer's descriptor, which must be numbered 3 or higher, open,
+and not a terminal: standard input is never accepted, because it may be
+model-composed or captured in a transcript. The read is bounded at 65536
+bytes and exactly one trailing newline is removed. Without `--input-fd`
+the value is typed on the terminal, masked, and confirmed. In both cases
+the record is stored as `text/plain`, and the descriptor is read before
+the password prompt so a closed or reserved descriptor is refused early.
+The display name (`--name`, at most 256 bytes, no control characters) is
+stored inside the encrypted record body, where the vault's associated data
+authenticates it.
+
+The write spans two stores under two leases and is not atomic, so its order
+is fixed: the provider record is created first, then the index entry. If
+the index write fails, the record is deleted again under the same session
+and the command reports the index failure with provider effect none; if
+that deletion cannot be proven, the command reports
+`PROVIDER_OUTCOME_UNKNOWN` (exit 7) naming the record's opaque ID, which
+may then remain in the vault unindexed until it is reconciled.
+
+### The secret index
+
+Each realm has one routing index at
+`<secretsRoot>/realms/<realmId>/secrets-index.json`, written `0600` inside
+a `0700` realm directory through the same journaled, atomic store that
+holds the bastion profiles. It maps a secret ID to `{ providerId, digest }`
+and nothing else: no display name, content type, byte length, or timestamp
+ever lands in it, so the file discloses routing alone. The `digest` is
+SHA-256 over the canonical JSON of `{ secretId, providerId, opaqueId }`,
+computed at create and re-verified on every resolve; `opaqueId` equals the
+secret ID by construction, because the human path mints a canonical
+22-character `sec_` token that the encrypted-file vault stores verbatim.
+The digest is unkeyed: it detects an accidental edit or a truncated write,
+and nothing more — any party with write access to the file can recompute
+it. Phase 3 replaces it with a broker-held keyed MAC. Do not delete the
+index: every secret it routes becomes unreachable by ID.
+
+## `aries secrets reveal` — Human-only reveal to the terminal
+
+```sh
+aries secrets reveal --secret-id sec_…                     # the value, once, then a newline
+aries secrets reveal --secret-id sec_… --bastion "Laptop"  # an explicit profile
+```
+
+`reveal` resolves `--secret-id` through the realm's secret index alone. A
+missing entry is `INVALID_ARGUMENT` (exit 2); an entry naming a provider
+the profile no longer lists, or one whose digest no longer verifies, is
+`BASTION_CONFIGURATION_INVALID` (exit 9) — each fails closed, and no
+provider is ever opened or searched to find a matching record. `--provider`
+is refused with `INVALID_ARGUMENT` for the same reason: the index is the
+only routing input, so a reference can never be redirected from the
+command line. The command then consults the deny records, appends the
+`intent` event, prompts for the vault password, reads the record, locks the
+vault, appends the `completed` event, and writes the value exactly once to
+standard output followed by one newline — nothing else is written there.
+There is no other delivery: no destination, file, descriptor, environment,
+clipboard, or temporary file, and no structured output. The value never
+appears in an audit line or on standard error.
+
+## `aries secrets set` — Human-only compare-and-swap replace
+
+```sh
+aries secrets set --secret-id sec_… --expected-version <v> --input-fd 3 3<./new.txt   # value from descriptor 3
+aries secrets set --secret-id sec_… --expected-version <v>                             # masked prompt, typed twice
+```
+
+`set` replaces one secret's value in the operator's own vault. It resolves
+`--secret-id` through the realm's secret index alone, exactly as `reveal`
+does (`--provider` is refused with `INVALID_ARGUMENT`), consults the deny
+records, appends the `intent` event, prompts for the vault password, collects
+the new value from `--input-fd` (3 or higher; read before the password prompt)
+or the masked terminal prompt with confirmation, and performs one
+compare-and-swap replace: `--expected-version` must equal the record's
+current version token exactly as the last `create`, `generate`, `set`, or
+`describe` printed it, or the command fails with `VERSION_CONFLICT` (exit 8)
+and nothing changes. The display name and content type are preserved from
+the record. The reference does not change, so the index is untouched; the
+command prints the new version and the superseded one, never the value. A
+replace whose effect the provider cannot prove is `PROVIDER_OUTCOME_UNKNOWN`
+(exit 7), naming the record and stating that the index still routes it.
+
+## `aries secrets generate` — Human-only in-process generation
+
+```sh
+aries secrets generate --name "Signing key" --kind random-bytes --length 64
+aries secrets generate --name "Webhook token" --kind base64url-token
+aries secrets generate --name "Database password" --kind password --length 24 --provider backup
+```
+
+`generate` draws a value in the operator's own process from Web Crypto and
+stores it exactly as `create` would: placement on `--provider` (or the sole
+provider), the deny consultation, the `intent` event, the password prompt,
+the provider record first with the display name inside the encrypted body,
+then the routing entry in the realm's index, with the same rollback when the
+index write fails. It prints the secret ID, kind, size, and version — the
+value is never printed, logged, audited, or returned, and exists only in the
+record's ciphertext; read it back with `reveal`. `--kind` is a closed list
+and `--length` counts the kind's unit inside an inclusive range:
+
+| Kind | Stored as | `--length` | Default | Range |
+| --- | --- | --- | --- | --- |
+| `random-bytes` | `application/octet-stream`, raw bytes | bytes | 32 | 8–1024 |
+| `base64url-token` | `text/plain` | characters | 32 | 8–512 |
+| `password` | `text/plain` | characters | 32 | 8–256 |
+
+`password` uses a fixed 70-symbol printable alphabet with the ambiguous
+`0 O 1 l I` removed and no space, quote, backslash, `$`, backtick, or
+redirection character; `base64url-token` uses the 64 base64url symbols. Both
+are uniform: a byte that would bias the draw is rejected, never reduced. An
+unlisted kind or an out-of-range length is `INVALID_ARGUMENT` (exit 2) before
+anything runs.
+
+## `aries secrets delete` — Human-only compare-and-swap delete
+
+```sh
+aries secrets delete --secret-id sec_… --expected-version <v>
+```
+
+`delete` resolves `--secret-id` through the index alone, consults the deny
+records, appends the `intent` event, prompts for the vault password, and
+deletes the record under the `--expected-version` guard; a stale guard is
+`VERSION_CONFLICT` (exit 8) and nothing changes. It then removes the routing
+entry from the realm's index: the tombstone is the removal itself, so the ID
+no longer resolves through any command and a later `describe` or `reveal`
+stops at the index with `INVALID_ARGUMENT`. **The vault record is gone and is
+not recoverable through aries**: the encrypted-file provider discards the
+ciphertext and keeps no tombstone, which the receipt reports as
+`unrecoverable`. The audit line records the secret ID and the fresh tombstone
+version only. If the record is deleted but the index cannot be updated, the
+command reports `PROVIDER_OUTCOME_UNKNOWN` (exit 7) naming both facts — the
+record is gone, the index may still route the ID. Until you reconcile,
+`describe` on that ID fails either at the vault with `RESOURCE_UNAVAILABLE`,
+with `list` showing it as `missing`, or at the index with `INVALID_ARGUMENT`
+if the entry did go after all.
+
+## `aries secrets list` — Human-only metadata listing
+
+```sh
+aries secrets list                     # the active provider, or the sole provider
+aries secrets list --provider backup   # one provider entry
+```
+
+`list` resolves the provider entry (`--provider`, else the active provider,
+else the sole one), consults the deny records for the realm's catalog,
+prompts for the vault password, and prints metadata alone: for every index
+entry routed to that provider, the secret ID, version, incarnation, content
+type, byte length, display name, and created and updated timestamps, read
+from the vault's own description; an entry whose record the provider no
+longer holds is shown as `missing`, one whose index digest does not verify
+as `integrity-failed` (the vault is not consulted for it), and one whose
+record the vault holds but will not describe as `undescribable` with the
+failure code — a single unreadable record never hides the rest of the
+catalog. Entries routed to other providers on the profile are counted, not
+listed. The
+command also enumerates the provider's own records and reports every record
+the index does not route to that provider as `unindexed`, with its opaque
+ID, version, byte length, and timestamps — never its value or display name.
+An unindexed record is reachable by no aries command until it is reconciled,
+because the index is the only routing input. No value is ever printed.
+
+## `aries secrets describe` — Human-only metadata for one secret
+
+```sh
+aries secrets describe --secret-id sec_…
+```
+
+`describe` resolves `--secret-id` through the index alone (`--provider` is
+refused), consults the deny records, prompts for the vault password, and
+prints the record's current version, incarnation, created and updated
+timestamps, content type, byte length, and display name — never the value,
+which is decrypted only to measure it and wiped inside the library. A
+record the vault does not hold is `RESOURCE_UNAVAILABLE` (exit 7); an ID the
+index does not route is `INVALID_ARGUMENT` (exit 2) before any vault is
+opened. The printed version is the `--expected-version` for the next `set`
+or `delete`.
+
+---
+
 ## `aries chain` — Local published-chain server
 
 ```sh
@@ -120,17 +675,17 @@ CA file for another HTTPS S3-compatible endpoint.
 
 ---
 
-## `aries bank` — Manage bank witness settings
+## `ariesi 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'
+ariesi bank capitalone config get
+ariesi bank capitalone config set base-url https://api-sandbox.capitalone.com
+ariesi bank capitalone config set token-url https://api-sandbox.capitalone.com/oauth2/token
+ariesi bank capitalone config set client-id "$CAPITALONE_CLIENT_ID"
+ariesi bank capitalone config set client-secret "$CAPITALONE_CLIENT_SECRET"
+ariesi bank capitalone config set accounts-path /accounts
+ariesi bank capitalone config set balances-path '/accounts/{accountId}/balances'
+ariesi bank capitalone config set transactions-path '/accounts/{accountId}/transactions'
 ```
 
 Capital One config is stored in `~/.aries/bank/capitalone.json` with restricted
@@ -165,15 +720,15 @@ for one run.
 
 ---
 
-## `aries pentair` — Manage Pentair ScreenLogic systems
+## `ariesi 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
+ariesi pentair config get
+ariesi pentair config get address
+ariesi pentair config set address 192.0.2.10
+ariesi pentair config set port 80
+ariesi pentair config set system-name "Pentair ScreenLogic"
+ariesi pentair circuit runtime set --circuit-id 6 --hours 24 --on
 ```
 
 Pentair config is stored in `~/.aries/pentair/config.json` and is used by the
@@ -194,7 +749,7 @@ Pentair witness and circuit commands. `ARIES_HOME` overrides the `~/.aries` root
 
 `config get` redacts `password`; pass `--show-secrets` to print it.
 
-### `aries pentair circuit runtime set`
+### `ariesi pentair circuit runtime set`
 
 Set the ScreenLogic circuit egg timer. Runtime values are sent to ScreenLogic as
 minutes; `--hours 24` becomes `1440`.
@@ -351,14 +906,6 @@ Scan for installed AI clients.
 |---|---|---|
 | `--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.
@@ -368,37 +915,18 @@ Check Claude Code and Codex AI configuration drift. The folder defaults to the c
 | `--scope <all\|project\|home>` | `all` | Check project config, shared/custom home config, or both |
 | `--json` | `false` | Output as JSON |
 
----
-
-## `aries clamp` — Run commands inside a permission-controlled sandbox
+### `aries ai skills list [tool]`
 
-```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 |
+List installed skills discovered for Claude Code, Codex, and Cursor. The optional
+`tool` positional accepts `claude`, `codex`, or `cursor`; omit it to inspect all
+three. Cursor currently reports no skills. Detection and listing do not modify client configuration.
 
 | 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 |
+| `--json` | `false` | Output as JSON |
 
-`policy list` and `policy init` take no command-specific options.
+AI lint also inspects shared/custom home plugin manifests and skill files for
+drift without changing them.
 
 ---
 
@@ -544,14 +1072,17 @@ aries datalake audit purge    # Delete rotated audit files older than --max-age-
 ### 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 up        # Start the local control + data plane dev server
+aries datalake down      # Stop it (clears credentials)
+aries datalake status    # Report whether the local dev server is running and healthy
+aries datalake logs      # Print recent dev server log output
+aries datalake reset     # Stop the dev server and wipe all local state
 ```
 
-#### `aries datalake dev up`
+The original `aries datalake dev up|down|status|logs|reset` spellings remain
+available for compatibility.
+
+#### `aries datalake up`
 | Option | Default | Description |
 |---|---|---|
 | `--control-port <n>` | free loopback port | Control-plane port |
@@ -564,7 +1095,7 @@ aries datalake dev reset     # Stop the dev server and wipe all local state
 | `--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`
+#### `aries datalake logs`
 | Option | Default | Description |
 |---|---|---|
 | `-f, --follow` | `false` | Stream new lines as they arrive |
@@ -638,14 +1169,14 @@ preserving the hydrated transaction tuple and all existing signatures.
 
 ---
 
-## `aries hash [file]` — content hashing
+## `ariesi hash [file]` — content hashing
 
 ```text
-aries hash [file] [options]
-aries hash compare <hashA> <hashB> --algorithm <name> [--json]
+ariesi hash [file] [options]
+ariesi hash compare <hashA> <hashB> --algorithm <name> [--json]
 ```
 
-Reads input from `[file]` (positional), `--string`, or piped stdin (priority order). Dispatches to one of 11 algorithms.
+Reads input from `[file]` (positional), `--string`, or piped stdin (priority order). Dispatches to one of 10 algorithms.
 
 ### Options
 
@@ -664,7 +1195,6 @@ Reads input from `[file]` (positional), `--string`, or piped stdin (priority ord
 |---|---|---|---|---|---|
 | `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` |
@@ -675,7 +1205,6 @@ Reads input from `[file]` (positional), `--string`, or piped stdin (priority ord
 | `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
@@ -697,29 +1226,29 @@ Each algorithm probes its binary at hash time and prints clear install instructi
 
 ```sh
 # Strict
-aries hash --string "hello"
-aries hash ./payload.json --algorithm xyo
+ariesi hash --string "hello"
+ariesi hash ./payload.json --algorithm xyo
 
 # Byte-fuzzy
-aries hash --algorithm tlsh ./binary.exe
-aries hash compare <hashA> <hashB> --algorithm tlsh
+ariesi hash --algorithm nilsimsa ./binary.exe
+ariesi hash compare <hashA> <hashB> --algorithm nilsimsa
 
 # Perceptual image
-aries hash --algorithm phash ./photo.jpg
-aries hash --algorithm pdq   ./photo.jpg
-aries hash compare <hashA> <hashB> --algorithm pdq
+ariesi hash --algorithm phash ./photo.jpg
+ariesi hash --algorithm pdq   ./photo.jpg
+ariesi 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
+ariesi hash --algorithm chromaprint ./song.mp3 > song.fp.json
+ariesi 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
+ariesi hash --algorithm video-frames --fps 1 ./movie.mkv > movie.fp.json
+ariesi hash --algorithm video-frames --fps 1 --frame-algorithm pdq ./movie.mkv > movie-pdq.fp.json
+ariesi hash compare "$(cat a.fp.json)" "$(cat b.fp.json)" --algorithm video-frames
 ```
 
-### `aries hash compare <hashA> <hashB>`
+### `ariesi hash compare <hashA> <hashB>`
 
 | Positional | | Description |
 |---|---|---|
@@ -737,18 +1266,18 @@ The compare command needs only the two hash strings — works against hashes gen
 
 ---
 
-## `aries npmjs` — npmjs org package checks
+## `ariesi 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
+ariesi npmjs list --org=xylabs
+ariesi npmjs lint --org=xylabs
+ariesi npmjs lint --org=xylabs --fix
+ariesi 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.
+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`, `ariesi 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`
+### `ariesi npmjs list`
 
 | Option | Default | Description |
 |---|---|---|
@@ -756,7 +1285,7 @@ By default, package discovery uses your current npm CLI authentication via `npm
 | `--public-only` | `false` | List only public packages without using `npm access` |
 | `--json` | `false` | Output as JSON |
 
-### `aries npmjs lint`
+### `ariesi 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.