@glyphteck/veyl 0.2.0 → 0.3.1

package/docs/cli.md

@@ -0,0 +1,169 @@
+# CLI
+
+The `veyl` binary is the terminal adapter over the headless JavaScript API.
+
+`veyl help` is generated from the same command descriptors that drive CLI dispatch and MCP tools. The examples below highlight common commands rather than defining a separate command inventory.
+
+## Install
+
+```bash
+bunx @glyphteck/veyl help
+bun add -g @glyphteck/veyl
+```
+
+Project-local:
+
+```bash
+bun add @glyphteck/veyl
+bunx veyl help
+```
+
+## Account And Vault
+
+```bash
+veyl create @runner
+veyl create --passkey @runner
+veyl login [@runner]
+veyl login --passkey [@runner]
+veyl me
+veyl vault create
+veyl unlock
+veyl lock
+```
+
+`create` without `--passkey` creates a machine-operated account and marks the profile as `bot`. `create --passkey` creates a normal passkey account through a browser-assisted flow and stores a local CLI credential.
+
+## Chat
+
+```bash
+veyl chats
+veyl read @alice
+veyl say @alice "hello"
+veyl reply @alice <message-id> "got it"
+veyl react @alice <message-id> +1
+veyl unreact @alice <message-id>
+veyl save @alice <message-id>
+veyl unsave @alice <message-id>
+veyl delete-message @alice <message-id>
+veyl delete-chat @alice
+veyl retention @alice seen
+veyl retention @alice 24h
+```
+
+Structured form:
+
+```bash
+veyl chat list
+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 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
+```
+
+## Money
+
+```bash
+veyl balance
+veyl receive
+veyl claim
+veyl send @alice 1000
+veyl request @alice 1000
+veyl pay <request-id>
+veyl invoice 1000 "memo"
+veyl pay-invoice <invoice>
+veyl transactions
+veyl withdraw-quote <address> 1000
+veyl withdraw-prepare <address> 1000
+veyl withdraw <address> 1000
+```
+
+Structured form:
+
+```bash
+veyl money balance
+veyl money receive
+veyl money claim
+veyl money send @alice 1000
+veyl money request @alice 1000
+veyl money pay <request-id>
+veyl money invoice 1000 "memo"
+veyl money pay-invoice <invoice>
+veyl money lightning-quote <invoice>
+veyl money lightning-pay <invoice>
+veyl money lightning-receive <id>
+veyl money lightning-send <id>
+veyl money transactions
+veyl money withdraw-quote <address> 1000
+veyl money withdraw-prepare <address> 1000
+veyl money withdraw <address> 1000
+```
+
+## Listen
+
+```bash
+veyl listen --agent
+```
+
+Useful flags:
+
+```text
+--interval <ms>
+--chat-count <n>
+--message-count <n>
+--tx-count <n>
+--replay
+--incoming
+--incoming-only
+--all
+--compact
+--agent
+--no-chats
+--no-transactions
+```
+
+`--agent` is the preferred event stream for agents. It emits compact incoming-only newline-delimited JSON events.
+
+## Common Flags
+
+```text
+--profile <name>
+--network REGTEST|MAINNET
+--secret <vault-secret>
+--no-save-secret
+--passkey
+--web-url <origin>
+--no-save-credential
+--count <n>
+--limit <n>
+--offset <n>
+--raw
+--memo <text>
+--expiry <seconds>
+--max-fee <sats>
+--amount <sats>
+--amount-to-send <sats>
+--speed SLOW|MEDIUM|FAST
+--no-deduct-fee
+--type lightning|spark
+--prefer-spark
+--no-prefer-spark
+--include-spark-address
+--include-spark-invoice
+--no-cleanup
+```
+
+## Env
+
+```bash
+VEYL_HOME=/secure/veyl-home
+VEYL_PROFILE=runner
+VEYL_NETWORK=REGTEST
+VEYL_VAULT_SECRET=...
+VEYL_WEB_URL=https://veyl.glyphteck.com
+```

package/docs/mcp.md

@@ -0,0 +1,54 @@
+# MCP
+
+The MCP server is a local stdio adapter over the headless JavaScript API.
+
+Veyl does not host a remote MCP endpoint. There is no Vercel URL for MCP. A user, agent host, desktop app, or worker starts the package command itself:
+
+```bash
+veyl mcp serve
+```
+
+The host sends MCP JSON-RPC messages to stdin and reads responses from stdout. The server uses the same local profile, vault, wallet, and chat session as the CLI/API.
+
+## When To Use MCP
+
+Use MCP when the agent runtime already supports MCP tools and wants to call Veyl through tool invocations.
+
+Use the JavaScript API when you control the runtime and need an efficient long-running loop, streaming listener, custom memory, or custom wake/sleep logic.
+
+Use the CLI when a human or shell script needs one-off commands.
+
+## Local Config Example
+
+Exact MCP host config differs by host. The important command is:
+
+```json
+{
+  "command": "veyl",
+  "args": ["mcp", "serve"],
+  "env": {
+    "VEYL_PROFILE": "runner",
+    "VEYL_NETWORK": "REGTEST",
+    "VEYL_HOME": "/secure/veyl-home"
+  }
+}
+```
+
+If `veyl` is not globally installed, point the command at Bun:
+
+```json
+{
+  "command": "bunx",
+  "args": ["@glyphteck/veyl", "mcp", "serve"]
+}
+```
+
+## Tools
+
+The live tool list is returned by MCP `tools/list` and generated from the canonical descriptors in `src/commands.js`. It covers account and vault access, chat reads/actions, wallet payments and requests, Lightning operations, withdrawals, and transaction history.
+
+`chat_reply` and `chat_react_to` accept either explicit `peer` plus `messageId`, or a full `event` object from `veyl listen`.
+
+## Security
+
+The MCP server is not privileged. It can only do what the local profile, credential, vault secret, and wallet funds allow. Do not expose stdio over a public network bridge. If a custom MCP host stores secrets elsewhere, disable package-side secret persistence with `saveSecret: false`, `saveCredential: false`, `--no-save-secret`, or `--no-save-credential`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@glyphteck/veyl",
-    "version": "0.2.0",
+    "version": "0.3.1",
     "license": "Apache-2.0",
     "type": "module",
     "description": "Programmable Bun client for Veyl accounts, vaults, chat, and wallet payments.",
@@ -12,6 +12,7 @@
     },
     "files": [
         "dist",
+        "docs",
         "README.md",
         "package.json"
     ],