@glyphteck/veyl 0.2.0 → 0.3.1

package/README.md

@@ -1,148 +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
+```
 
-- `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.
+## Quick Start
 
-The npm package publishes bundled `dist` entrypoints so callers do not need Veyl's monorepo workspace packages installed locally.
+```bash
+veyl create @runner
+veyl vault create
+veyl balance
+veyl listen --agent
+```
 
-## API Shape
+Passkey account from the terminal:
+
+```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.chat.reply({ peer: '@alice', messageId: messages.messages[0].id }, 'got it');
-await veyl.chat.react('@alice', messages.messages[0].id, '+1');
-await veyl.chat.save('@alice', messages.messages[0].id);
-await veyl.chat.retention('@alice', '24h');
+await veyl.money.request('@alice', 1000);
+```
+
+## Agent Loop
+
+```js
+import { open } from '@glyphteck/veyl';
+
+const veyl = await open({ profile: 'runner', network: 'REGTEST' });
+
+await veyl.account.login();
+await veyl.vault.unlock();
 
 await veyl.listen({
-  compact: true,
-  incomingOnly: true,
+  agent: true,
   onEvent: async (event) => {
-    if (event.type !== 'message') return;
-    await veyl.chat.reactTo(event, '+1');
-    await veyl.chat.reply(event, 'thanks');
+    if (event.type !== 'message' || event.message.type !== 'txt') return;
+    await veyl.chat.reply(event, `received: ${event.message.text}`);
   },
 });
-
-const receive = await veyl.money.receive();
-const invoice = await veyl.money.invoice(1000, { memo: 'coffee' });
-await veyl.money.send('@alice', 1000);
-await veyl.money.request('@alice', 1000);
-const transactions = await veyl.money.transactions();
-
-console.log(account.uid, vault.vaultSecret, receive.address, invoice.encodedInvoice, messages, transactions);
 ```
 
-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 login [@runner]
+veyl vault create
+veyl vault unlock
+veyl balance
 veyl receive
 veyl claim
-veyl invoice 100 "coffee"
-veyl pay-invoice <invoice>
-veyl withdraw <address> 1000
-veyl balance
-veyl read @alice
 veyl say @alice "hello"
 veyl reply @alice <message-id> "got it"
 veyl react @alice <message-id> +1
-veyl save @alice <message-id>
-veyl retention @alice 24h
-veyl listen --agent
-
-veyl account create @runner
-veyl account create --passkey @runner
-veyl account login @runner
-veyl account login --passkey @runner
-veyl vault create
-veyl vault unlock
-veyl vault lock
-veyl chat read @alice
-veyl chat send @alice "hello"
-veyl chat reply @alice <message-id> "got it"
-veyl chat react @alice <message-id> +1
-veyl chat react-to @alice <message-id> +1
-veyl chat unreact @alice <message-id>
-veyl chat save @alice <message-id>
-veyl chat unsave @alice <message-id>
-veyl chat delete @alice <message-id>
-veyl chat delete-chat @alice
-veyl chat retention @alice seen
-veyl money receive
-veyl money balance
-veyl money claim
-veyl money invoice 100 "coffee"
-veyl money pay-invoice <invoice>
-veyl money send @alice 1000
-veyl money request @alice 1000
-veyl money withdraw-quote <address> 1000
-veyl money withdraw <address> 1000
+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. Use `veyl listen --agent` for compact peer-authored message events with `replyTo` and `reactTo` handles shaped as `{ peer, messageId }`.
-
-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.
+## Docs
 
-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.
+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.
 
-Glyphteck-owned Google Secret Manager bot seeds are not used by this public path.
+## Environment
 
-## Backend Contract
-
-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`
-
-Machine-created accounts are marked as bots on their public profile so app users can tell that the account is bot-operated. Passkey-created CLI accounts are not marked as bots.
-
-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`.