@glyphteck/veyl 0.56.0 → 0.58.0

package/docs/api.md

@@ -7,7 +7,6 @@
 ```js
 import {
   API_VERSION,
-  TERMS_VERSION,
   VERSION,
   open,
 } from '@glyphteck/veyl';
@@ -24,7 +23,7 @@ const veyl = await open({
 
 The auth and account compositions consume explicit runtime ports and have no direct Node, Firebase-construction, Spark-construction, filesystem, machine-key, namespace-file, browser-process, or React dependency. The package's current high-level `open()` implementation comes from `src/runtime/node.js`, which supplies the Node ports. Web and iOS use `openAuth()` and `openAccount()` with their existing cloud, passkey-ceremony, vault crypto, Spark, cache, network, and diagnostics ports; React remains only a snapshot/lifecycle adapter.
 
-Most product methods ensure login and vault unlock when a saved credential and vault secret are available. Long-running callers should explicitly login/unlock once and call `close()` when finished.
+Most product methods ensure login and vault unlock when saved account and vault keys are available. Long-running callers should explicitly login/unlock once and call `close()` when finished.
 
 ## Graphical auth owner
 
@@ -48,7 +47,7 @@ const auth = openAuth({
   },
 });
 
-await auth.register({ label, termsVersion });
+await auth.register({ label });
 await auth.login({ uid });
 const unsubscribeAuth = auth.subscribe((user) => console.log(user));
 
@@ -189,46 +188,46 @@ An unknown Spark send, payment-request payment, invoice payment, or withdrawal o
 
 ## Account
 
+Creating an account accepts Veyl's [Terms](https://veyl.glyphteck.com/legal#terms) and [Community Rules](https://veyl.glyphteck.com/community-rules).
+
 ```js
-await veyl.account.create({
+const accountKey = await veyl.account.create({
   username: 'runner',
   network: 'REGTEST',
-  termsVersion: TERMS_VERSION,
-  saveCredential: true,
 });
 
 await veyl.account.login();
 const local = await veyl.account.me();
 const terms = await veyl.account.terms();
-await veyl.account.acceptTerms({ termsVersion: TERMS_VERSION });
+await veyl.account.acceptTerms();
 await veyl.account.logout();
 await veyl.account.logoutAll();
 await veyl.account.delete({ confirm: true });
 ```
 
-- `create` makes an ordinary account authenticated by a local machine credential. Authentication does not assign a public bot label.
-- `createPasskey({ username, termsVersion, webUrl, onUrl })` creates a normal passkey account through a browser-assisted WebAuthn flow, then installs a local machine credential for future CLI sessions.
-- `login({ username?, credentialId?, privateKeyPem? })` authenticates a machine credential.
+- `create` makes an ordinary account authenticated by a local machine credential and returns its account key directly. Authentication does not assign a public bot label.
+- `createPasskey({ username, webUrl, onUrl })` creates a normal passkey account through a browser-assisted WebAuthn flow, installs a local machine credential for future CLI sessions, and returns that account key directly.
+- `login({ username?, key?, saveKey? })` authenticates with an account key. The key can instead come from `open({ accountKey })` or `VEYL_ACCOUNT_KEY`.
 - `loginPasskey({ username?, webUrl?, onUrl? })` authenticates through the browser-assisted passkey flow.
 - `me` returns the local account summary without forcing login.
-- `terms` reports the current Terms/Community Rules versions, the account's accepted versions, and whether they match.
-- `acceptTerms({ termsVersion })` records the current agreement through the shared user owner without forcing a vault unlock; the caller must first present both public documents and obtain explicit consent.
+- `terms` reports the canonical Terms/Community Rules links, whether the account's acceptance is current, and when it last accepted an agreement.
+- `acceptTerms()` records the current agreement through the shared user owner without forcing a vault unlock.
 - `logout` signs out and tears down only this runtime.
 - `logoutAll` revokes every product session generation, tears down this runtime locally, and stops a persistent CLI owner after its in-flight work drains.
 - `delete({ confirm: true })` drains decryptable inbox state, marks all discoverable chats deleted, destroys the complete account/network encrypted cache scope, proves vault possession, deletes identifiable account data, removes the local profile, and stops a persistent CLI owner after its in-flight work drains.
 
-Account summaries report identity, network, local credential/vault availability, public wallet/chat keys, auth kind, an explicit managed-bot marker when assigned by Glyphteck's owner namespace, and current signed-in/unlocked state. Private keys and vault secrets are never included in summaries.
+Account summaries report identity, network, local credential/vault availability, public wallet/chat keys, auth kind, an explicit managed-bot marker when assigned by Glyphteck's owner namespace, and current signed-in/unlocked state. Account and vault keys are never included in summaries.
 
 ## Vault
 
 ```js
-await veyl.vault.create({ secret, saveSecret: true });
-await veyl.vault.unlock({ secret });
+const vaultKey = await veyl.vault.create({ saveKey: false });
+await veyl.vault.unlock({ key: vaultKey });
 await veyl.vault.lock();
-const { mnemonic } = await veyl.vault.export({ secret });
+const { mnemonic } = await veyl.vault.export({ key: vaultKey });
 ```
 
-Vault creation and unlock use the shared local encryption, seed derivation, Spark wallet, chat, cache, peer, and transfer owners. `export` returns the Spark mnemonic and must be treated as secret output.
+Vault creation returns the vault key directly. That key unlocks the vault and every feature derived from it. Creation and unlock use the shared local encryption, seed derivation, Spark wallet, chat, cache, peer, and transfer owners. `export` returns the Spark mnemonic and must be treated as secret output.
 
 ## Profile, settings, and cache
 
@@ -395,7 +394,6 @@ These methods use the same account-scoped validation, encrypted-message lookup,
 const controller = new AbortController();
 
 await veyl.listen({
-  agent: true,
   replay: false,
   signal: controller.signal,
   onEvent(event) {
@@ -406,18 +404,17 @@ await veyl.listen({
 });
 ```
 
-`listen` subscribes to the shared live chat-list and transfer-store owners. It emits `ready`, `message`, `message-delete`, `transaction`, and `error` events. `agent: true` selects compact, incoming-only events and uses the chat list as a wakeup index: a changed conversation is opened briefly, processed, and released instead of retaining one message listener per chat. This keeps an account with hundreds of peers from multiplying long-lived Firestore listeners.
+`listen` subscribes to the shared live chat-list and transfer-store owners. It emits `ready`, `message`, `message-delete`, `transaction`, and `error` events. Compact, incoming-only events and transient chat subscriptions are the defaults: a changed conversation is opened briefly, processed, and released instead of retaining one message listener per chat. This keeps an account with hundreds of peers from multiplying long-lived Firestore listeners. Set `compact: false`, `incomingOnly: false`, or `persistentChats: true` only when the caller needs those broader behaviors.
 
 Use `listen` for account-wide agent wakeups. Use `chat.enter` when an agent is actively inside one conversation and needs that mounted transcript's exact lifecycle, history, retention, and read semantics.
 
 ## Local fleet owner
 
-`openFleetOwner` is the canonical long-running host for one local agent managing many Veyl accounts. The host keeps one fleet root seed and derives a separate machine credential, vault-unlock secret, and Veyl master seed for every monotonically allocated account index.
+`openFleetOwner` is the canonical long-running host for one local agent managing many Veyl accounts. The host keeps one fleet root seed and derives a separate account key, vault key, and Veyl master seed for every monotonically allocated account index.
 
 ```js
 import {
   FLEET_MANIFEST_VERSION,
-  TERMS_VERSION,
   createFleetSeed,
   openFleetOwner,
   saveFleetManifest,
@@ -446,7 +443,6 @@ await fleet.provision({
   username: 'worker-one',
   roles: ['read'],
   network: 'REGTEST',
-  termsVersion: TERMS_VERSION,
 });
 
 fleet.use(agentPolicy);
@@ -483,11 +479,11 @@ await fleet.stop();
 }
 ```
 
-The root format and derivation domains are versioned. `nextAccountIndex` only moves forward, so removing a profile never reuses its secret slot. The manifest accepts only public ownership and routing data; credentials and vault secrets are rejected. Derived secrets exist in memory while an account is used, and local fleet profile files contain only public identifiers.
+The root format and derivation domains are versioned. `nextAccountIndex` only moves forward, so removing a profile never reuses its key slot. The manifest accepts only public ownership and routing data; account and vault keys are rejected. Derived keys exist in memory while an account is used, and local fleet profile files contain only public identifiers.
 
 Losing the root loses every derived account. Back it up as carefully as a wallet seed.
 
-An existing account cannot retroactively acquire a derived master seed. Adopting one requires a one-time authenticated handoff that installs its root-derived machine credential and encrypts the existing master seed under its root-derived vault secret without changing wallet/chat material.
+An existing account cannot retroactively acquire a derived master seed. Adopting one requires a one-time authenticated handoff that installs its root-derived account key and encrypts the existing master seed under its root-derived vault key without changing wallet/chat material.
 
 The Glyphteck namespace seed is separate from a fleet root. `veyl namespace init` creates that owner-only local key once. When its default file exists under the fleet `homeDir`, provisioning automatically signs a short-lived claim bound to the exact derived machine credential so a reserved canonical username can use the normal public account-creation transaction. The seed is never stored in the manifest or an account profile. Other fleet operators do not have this key and cannot claim the reserved namespace.
 
@@ -525,7 +521,7 @@ Completed results survive restarts. An interrupted replay-safe chat action may r
 
 The default profile store is `~/.veyl`; override it with `homeDir` or `VEYL_HOME`. Profile directories use mode `0700`, and credential/secret/session files use mode `0600`.
 
-Standalone profiles may include Firebase uid, username, network, machine credential id and keypair, vault metadata, public wallet/chat keys, and optionally the vault secret. Root-derived fleet profiles intentionally store no private key or vault secret. Use `saveCredential: false` / `--no-save-credential` and `saveSecret: false` / `--no-save-secret` when another secret owner supplies them.
+Standalone profiles may include Firebase uid, username, network, account authentication material, vault metadata, public wallet/chat keys, and optionally the vault key. Root-derived fleet profiles intentionally store no account or vault key. Use `saveKey: false` / `--no-save-key` when another secret owner supplies a key.
 
 ## Close
 

package/docs/cli.md

@@ -17,22 +17,22 @@ The namespace seed is not accepted through a command argument, environment varia
 ## Account and vault
 
 ```bash
-veyl account create @name [--passkey] [--reserved] [--accept-terms VERSION]
+veyl account create @name [--passkey] [--reserved]
 veyl account login [@name] [--passkey]
 veyl account show
 veyl account terms
-veyl account accept-terms [--accept-terms VERSION]
+veyl account accept-terms
 veyl account logout
 veyl account logout-all
 veyl account delete --confirm
 
-veyl vault create [--secret VALUE] [--no-save-secret]
-veyl vault unlock [--secret VALUE]
+veyl vault create [--key VALUE] [--no-save-key]
+veyl vault unlock [--key VALUE] [--no-save-key]
 veyl vault lock
-veyl vault export [--secret VALUE]
+veyl vault export [--key VALUE]
 ```
 
-Interactive creation and `account accept-terms` print the public Terms and Community Rules URLs and ask for explicit acceptance. A non-interactive shell must pass the exact current version with `--accept-terms`. `account terms` reports both the current versions and the account's recorded acceptance without unlocking the vault.
+Creating an account accepts Veyl's [Terms](https://veyl.glyphteck.com/legal#terms) and [Community Rules](https://veyl.glyphteck.com/community-rules). `account accept-terms` accepts their current revisions for an existing account. `account terms` reports the canonical links and whether the account's acceptance is current without unlocking the vault.
 
 `vault export` returns the Spark mnemonic. Treat its JSON output as a secret.
 
@@ -172,7 +172,7 @@ veyl --profile runner --session default chat enter @alice
 # another shell, when the conversation is actually finished
 veyl --profile runner --session default chat leave @alice
 veyl --profile runner --session default session status
-veyl --profile runner --session default session events --agent
+veyl --profile runner --session default session events
 veyl --profile runner --session default session stop
 ```
 
@@ -184,9 +184,8 @@ Event flags:
 
 ```text
 --replay             include current rows at startup
---incoming           emit peer-authored messages only
---compact            emit smaller payloads
---agent              shorthand for --incoming --compact
+--all                include self-authored messages; defaults to incoming only
+--raw                include complete event payloads
 --no-chats           omit message events
 --no-transactions    omit transaction events
 ```
@@ -202,7 +201,8 @@ Event flags:
 --offset N
 --raw
 --web-url ORIGIN
---no-save-credential
+--key VALUE
+--no-save-key
 --operation-id ID
 --cid ID
 ```
@@ -213,6 +213,7 @@ Event flags:
 VEYL_HOME            local profile directory
 VEYL_PROFILE         default profile
 VEYL_NETWORK         REGTEST or MAINNET
-VEYL_VAULT_SECRET    vault secret used by create/unlock
+VEYL_ACCOUNT_KEY     account key used by login
+VEYL_VAULT_KEY       vault key used by create/unlock
 VEYL_WEB_URL         passkey browser origin
 ```

package/docs/validation.md

@@ -11,7 +11,7 @@ The Node SDK composes the same framework-free owners as web and iOS:
 | Product area | Shared owner used by the SDK | Node adaptation |
 | --- | --- | --- |
 | Auth/session | `core/account/session.js`, `core/account/user.js` | local machine credential or browser-assisted passkey |
-| Vault | `core/vault.js`, shared crypto/seed owners | local profile secret or caller secret manager |
+| Vault | `core/vault.js`, shared crypto/seed owners | local vault key or caller secret manager |
 | Peers/search/block | `core/peerlist.js`, `core/peers.js`, shared search sessions | JSON peer projections |
 | Chat | `core/chat/session.js`, `core/chat/actions/*`, shared message batches/cache | strings, byte buffers, filesystem paths, JSON events |
 | Wallet/transactions | `core/wallet/session.js`, `core/wallet/invoice.js`, transfer store, tx data | direct invoice/address strings, integer sats, and JSON results |

package/examples/bot-fleet/readme.md

@@ -2,7 +2,7 @@
 
 This is a reference implementation of a long-lived multi-account agent fleet built entirely on `@glyphteck/veyl`. It uses no Firebase Admin connection, privileged chat path, server action queue, or cloud secret store. The Glyphteck-owned runtime under `bots` consumes this policy with its own local lineup and operator controls.
 
-The secret-free version-2 manifest stores account indices, usernames, networks, roles, and enabled state. One owner-only root at `$VEYL_HOME/fleets/<name>.seed` derives isolated machine credentials, vault secrets, and Veyl master seeds for monotonic account indices. Per-account private material is never stored in the manifest.
+The secret-free version-2 manifest stores account indices, usernames, networks, roles, and enabled state. One owner-only root at `$VEYL_HOME/fleets/<name>.seed` derives isolated account keys, vault keys, and Veyl master seeds for monotonic account indices. Per-account private material is never stored in the manifest.
 
 ## Roles
 

package/examples/bot-fleet/runtime.js

@@ -21,7 +21,6 @@ export async function createExampleBotFleetRuntime(options = {}) {
         bootConcurrency: options.bootConcurrency ?? 2,
         policies: [],
         eventOptions: async (profile) => ({
-            agent: true,
             replay: true,
             chats: profile.roles.includes('read'),
             persistentChats: true,

package/package.json

@@ -41,5 +41,5 @@
         "start": "node src/cli.js",
         "lint": "eslint src --quiet"
     },
-    "version": "0.56.0"
+    "version": "0.58.0"
 }

package/readme.md

@@ -16,18 +16,22 @@ npm install @glyphteck/veyl
 
 ## JavaScript quick start
 
+Creating an account accepts Veyl's [Terms](https://veyl.glyphteck.com/legal#terms) and [Community Rules](https://veyl.glyphteck.com/community-rules).
+
 ```js
-import { open, TERMS_VERSION } from '@glyphteck/veyl';
+import { open } from '@glyphteck/veyl';
 
-const veyl = await open({ profile: 'runner', network: 'REGTEST' });
-await veyl.account.create({ username: 'runner', termsVersion: TERMS_VERSION });
-await veyl.vault.create();
+const veyl = await open({ network: 'REGTEST' });
+const accountKey = await veyl.account.create({ username: 'runner' });
+const vaultKey = await veyl.vault.create();
 await veyl.chat.send('@alice', 'hello');
 console.log(await veyl.wallet.balance());
 await veyl.close();
 ```
 
-The human or controlling application must show the public Terms and Community Rules and obtain explicit agreement before creating an account. Machine credentials and passkeys describe authentication capability, not whether a person or agent operates the account. Third-party agents use ordinary public profiles; only namespace-authorized Glyphteck services carry the managed bot marker. Use `REGTEST` for disposable automation and `MAINNET` only for real funds.
+`account.create()` returns the account key used to authenticate the machine. `vault.create()` returns the vault key that unlocks every vaulted feature. Both keys are saved in the local profile by default and must never be logged or committed.
+
+Machine credentials and passkeys describe authentication capability, not whether a person or agent operates the account. Third-party agents use ordinary public profiles; only namespace-authorized Glyphteck services carry the managed bot marker. Use `REGTEST` for disposable automation and `MAINNET` only for real funds.
 
 ## Optional CLI
 
@@ -40,12 +44,6 @@ npx veyl account show
 npx veyl wallet address
 ```
 
-Interactive account creation displays the public Terms and Community Rules URLs and asks for acceptance. Non-interactive callers must pass the exact current version:
-
-```bash
-npx veyl --network REGTEST account create @runner --accept-terms 2026-07-15
-```
-
 To create or log into a normal passkey account from a browser-capable terminal, add `--passkey` to `account create` or `account login`.
 
 Glyphteck's owner-only reserved namespace uses one local key:
@@ -59,7 +57,7 @@ Initialization writes the private seed only to `~/.veyl/namespace.seed` with mod
 
 Long-running agents should keep one unlocked client or foreground session alive. This reuses the same wallet, peer, chat, cache, and live-listener owners instead of paying cold login and wallet boot cost for every command.
 
-Agents can also mount one conversation through `veyl.chat.enter('@alice')`, or run one local `openFleetOwner(...)` for many accounts. A versioned fleet root derives isolated machine credentials, vault-unlock secrets, and Veyl master seeds by monotonically allocated account index, so the operator backs up one secret for an unbounded fleet. Fleet policies remain normal API consumers; they receive no Firebase Admin or wallet shortcuts.
+Agents can also mount one conversation through `veyl.chat.enter('@alice')`, or run one local `openFleetOwner(...)` for many accounts. A versioned fleet root derives isolated account keys, vault keys, and Veyl master seeds by monotonically allocated account index, so the operator backs up one root for an unbounded fleet. Fleet policies remain normal API consumers; they receive no Firebase Admin or wallet shortcuts.
 
 The public SDK keeps ordinary errors simple. Only an ambiguous money mutation has a stable `operation_outcome_unknown` contract, including its caller correlation id and whether an identical retry is safe. This prevents an agent from self-correcting a network error into a duplicate spend without building a large error taxonomy.
 
@@ -70,7 +68,7 @@ veyl --profile runner session start
 # another shell
 veyl --profile runner --session default wallet balance
 veyl --profile runner --session default chat enter @alice
-veyl --profile runner --session default session events --agent
+veyl --profile runner --session default session events
 veyl --profile runner --session default session stop
 ```
 
@@ -90,7 +88,8 @@ Profiles live under `~/.veyl` by default. The directory and sensitive files use
 VEYL_HOME=/secure/veyl-home
 VEYL_PROFILE=runner
 VEYL_NETWORK=REGTEST
-VEYL_VAULT_SECRET=...
+VEYL_ACCOUNT_KEY=...
+VEYL_VAULT_KEY=...
 VEYL_WEB_URL=https://veyl.glyphteck.com
 ```