@glyphteck/veyl 0.1.2 → 0.3.0

package/README.md

@@ -1,106 +1,113 @@
 # Veyl Headless
 
-`apps/headless` is the programmable Bun client for terminal users, scripts, automations, and MCP servers.
+`@glyphteck/veyl` is the Bun client for using Veyl from a terminal, script, automation, bot, agent, or MCP client.
 
-It is a client, not a privileged backend. Headless accounts own their local machine credential, vault secret, wallet seed, and chat key material. The server should only create public account records, verify login challenges, and store encrypted vault material it cannot decrypt.
+Headless is a normal Veyl client, not a privileged backend. Account keys, vault secrets, wallet entropy, chat seeds, Spark wallet boot, message encryption, and payment signing run locally. The backend only creates public account records, verifies machine-key login challenges, issues Firebase custom tokens, and stores encrypted vault data it cannot decrypt.
 
-The package also supports real passkey accounts from a terminal. Passkey create/login opens the configured Veyl web origin for the WebAuthn ceremony, receives a Firebase token on a localhost callback, then pairs a local machine credential to that signed-in account for future CLI sessions. True machine-created headless accounts remain separate from passkey-created accounts.
+Machine-created accounts are marked as `bot` on their public profile. Passkey-created CLI accounts are real human accounts and are not marked as bots.
 
-Run the public package with Bun:
+## Install
 
 ```bash
 bunx @glyphteck/veyl help
 ```
 
-## Interface Boundary
+For scripts:
 
-`headless` is the client boundary. CLI, MCP, scripts, and future channel adapters are interfaces on top of the same client, not separate clients with their own account, vault, chat, or money logic.
+```bash
+bun add @glyphteck/veyl
+```
+
+## Quick Start
 
-- `src/client.js`: shared programmable API.
-- `src/cli.js`: terminal command wrapper.
-- `src/mcp.js`: MCP wrapper.
-- `src/passkey.js`: browser-assisted passkey bridge for terminal flows.
+```bash
+veyl create @runner
+veyl vault create
+veyl balance
+veyl listen --agent
+```
 
-The npm package publishes bundled `dist` entrypoints so callers do not need Veyl's monorepo workspace packages installed locally.
+Passkey account from the terminal:
 
-## API Shape
+```bash
+veyl create --passkey @runner
+veyl vault create
+veyl listen --agent
+```
 
-The public surface should stay simple enough to infer from the command names:
+## JavaScript
 
 ```js
 import { open } from '@glyphteck/veyl';
 
-const veyl = await open();
+const veyl = await open({ profile: 'runner', network: 'REGTEST' });
 
-const account = await veyl.account.create({ username: 'runner' });
-const vault = await veyl.vault.create();
+await veyl.account.login();
 await veyl.vault.unlock();
 await veyl.chat.send('@alice', 'hello');
-const messages = await veyl.chat.read('@alice');
-
-await veyl.money.send('@alice', 1000);
 await veyl.money.request('@alice', 1000);
-const transactions = await veyl.money.transactions();
+```
+
+## Agent Loop
+
+```js
+import { open } from '@glyphteck/veyl';
+
+const veyl = await open({ profile: 'runner', network: 'REGTEST' });
+
+await veyl.account.login();
+await veyl.vault.unlock();
 
-console.log(account.uid, vault.vaultSecret, messages, transactions);
+await veyl.listen({
+  agent: true,
+  onEvent: async (event) => {
+    if (event.type !== 'message' || event.message.type !== 'txt') return;
+    await veyl.chat.reply(event, `received: ${event.message.text}`);
+  },
+});
 ```
 
-CLI names should mirror the JS API:
+## Common CLI Commands
 
 ```bash
+veyl create @runner
 veyl create --passkey @runner
-veyl send @alice 1000
-veyl request @alice 1000
-veyl balance
-veyl read @alice
-veyl say @alice "hello"
-veyl listen
-
-veyl account create @runner
-veyl account create --passkey @runner
-veyl account login @runner
-veyl account login --passkey @runner
+veyl login [@runner]
 veyl vault create
 veyl vault unlock
-veyl vault lock
-veyl chat read @alice
-veyl chat send @alice "hello"
-veyl money balance
-veyl money send @alice 1000
-veyl money request @alice 1000
+veyl balance
+veyl receive
+veyl claim
+veyl say @alice "hello"
+veyl reply @alice <message-id> "got it"
+veyl react @alice <message-id> +1
+veyl send @alice 1000
+veyl request @alice 1000
+veyl pay <request-id>
 veyl transactions
+veyl listen --agent
 veyl mcp serve
 ```
 
-The same commands are exposed as MCP tools through `veyl mcp serve`.
-
-`veyl listen` keeps one auth and vault session alive in the current process, then emits newline-delimited JSON events for new messages and wallet transfers. It is the terminal event-stream path for agents that do not want to speak MCP.
+## Docs
 
-Passkey browser auth defaults to `https://veyl.glyphteck.com`. Use `--web-url` or `VEYL_WEB_URL` to point the CLI at another allowed passkey origin, such as a local dev host or a future dedicated auth host.
-
-From this monorepo, use the root dev helper instead of the package filter form:
-
-```bash
-bun dev headless regtest create --passkey @runner
-```
+- Agent quick reference: [docs/agents.md](docs/agents.md)
+- JavaScript API: [docs/api.md](docs/api.md)
+- CLI: [docs/cli.md](docs/cli.md)
+- MCP: [docs/mcp.md](docs/mcp.md)
 
 ## Local Secrets
 
-The package creates a local profile under `~/.veyl` by default. It stores the machine credential and, unless `saveSecret: false` or `--no-save-secret` is used, the generated vault secret. Passkey flows pair and store a local machine credential by default so later CLI commands do not need a browser prompt; use `--no-save-credential` or `saveCredential: false` to return the credential material without saving the private key locally. Callers that already have a secret manager can pass `VEYL_HOME`, `VEYL_PROFILE`, `VEYL_VAULT_SECRET`, or explicit SDK options and store those secrets elsewhere.
-
-Glyphteck-owned Google Secret Manager bot seeds are not used by this public path.
+Profiles live under `~/.veyl` by default, or `VEYL_HOME` if set. Use `--no-save-secret`, `--no-save-credential`, `saveSecret: false`, or `saveCredential: false` if you want to store vault or machine credentials yourself.
 
-## Backend Contract
+## Environment
 
-The backend only verifies machine-key challenges and issues Firebase custom tokens:
-
-- `POST /headless/account/create/start`
-- `POST /headless/account/create/finish`
-- `POST /headless/account/login/start`
-- `POST /headless/account/login/finish`
-- `POST /headless/account/credential/add/start`
-- `POST /headless/account/credential/add/finish`
-
-Vault secrets, wallet entropy, chat seeds, Spark wallet boot, and message/payment signing all run locally in this package through shared Veyl primitives.
+```bash
+VEYL_HOME=/secure/veyl-home
+VEYL_PROFILE=runner
+VEYL_NETWORK=REGTEST
+VEYL_VAULT_SECRET=...
+VEYL_WEB_URL=https://veyl.glyphteck.com
+```
 
-Generic unlocked-account actions live in `@veyl/shared/account/actions`; this package only wraps them with headless account auth, local profile storage, CLI commands, and MCP serving.
+`VEYL_WEB_URL` is used for passkey flows and must be `https://...` or `localhost`.