@glyphteck/veyl 0.58.0 → 0.59.0

package/docs/agents.md

@@ -54,12 +54,13 @@ await veyl.listen({
 
 This is a live subscription to shared chat-list and transfer state, not a polling loop. By default it emits compact peer-authored events and opens a changed chat only long enough to process it, so hundreds of peers do not become hundreds of retained message listeners. Set `compact: false` or `incomingOnly: false` when complete payloads or self-authored messages are required. A long-lived fleet can opt into `persistentChats: true` with `persistentChatIdleMs` to keep active conversations mounted, mark peer messages read before policy effects, and release only idle conversations; the account-level chat-list subscription reopens them when new activity arrives. Each listener has independent replay/filter state. Slow callbacks should hand work to an application queue if they must preserve event throughput.
 
-Compact message events include reusable `replyTo` and `reactTo` targets. Transaction events carry the same simplified transfer shape returned by wallet history.
+Compact message events include stable `chatId`, verified sender identity, member summaries, and reusable `replyTo` and `reactTo` targets. Transaction events carry the same simplified transfer shape returned by wallet history.
 
 When an agent is actively working inside one conversation, mount its shared route instead of repeatedly taking one-shot reads:
 
 ```js
-const chat = await veyl.chat.enter('@alice', { readPolicy: 'auto' });
+const group = await veyl.chat.create(['@alice', '@bob'], { title: 'operators' });
+const chat = await veyl.chat.enterById(group.id, { readPolicy: 'auto' });
 const unsubscribe = chat.subscribe((snapshot) => {
   memory.replace(snapshot.messages);
 });
@@ -69,7 +70,7 @@ chat.leave();
 unsubscribe();
 ```
 
-The mounted route preserves its coherent transcript and retention lifecycle until leave. Account-wide `listen` remains the wakeup surface; entered chat is the focused conversation surface.
+The mounted route preserves its coherent epoch-spanning transcript and retention lifecycle until leave. Account-wide `listen` remains the wakeup surface; `enterById` is the primary focused notes/direct/group surface. `enter('@alice')` remains a canonical-direct convenience.
 
 For multiple agent identities, run one local `openFleetOwner`. It derives every account's machine credential, vault key, and Veyl master seed from one versioned root and account index. It opens one normal public client per secret-free manifest profile, tags each event with its account, and runs host policies above those clients. It grants no admin access and bypasses no product owner.
 
@@ -109,6 +110,8 @@ Then issue commands from other processes through the owner-only local socket:
 ```bash
 veyl --profile runner --session default wallet balance
 veyl --profile runner --session default chat send @alice "hello"
+veyl --profile runner --session default chat create-group @alice,@bob --title operators
+veyl --profile runner --session default chat enter-by-id CHAT_ID
 veyl --profile runner --session default chat enter @alice
 veyl --profile runner --session default session events
 veyl --profile runner --session default session stop
@@ -116,7 +119,7 @@ veyl --profile runner --session default session stop
 
 Commands share the unlocked client and can run concurrently where the shared owners permit it. Same-chat sends remain ordered, disjoint chats can progress independently, and wallet mutations stay serialized.
 
-An entered chat remains mounted in the foreground session if its output shell disconnects. Use `chat entered` to inspect it and `chat leave @peer` when the agent is finished.
+An entered chat remains mounted in the foreground session if its output shell disconnects. Use `chat entered` to inspect it and `chat exit-by-id CHAT_ID` when the agent is finished.
 
 ## Safety rules
 

package/docs/api.md

@@ -149,13 +149,13 @@ unsubscribe();
 account.close();
 ```
 
-`openAccount()` owns authenticated user observation, username and avatar publication, vault observation and creation, vault unlock/lock, encrypted settings/network selection, presence, late wallet readiness, public Bitcoin data, support/report commands, chat and peer/profile composition, account switching, and secret-bearing session teardown. Its snapshot exposes `user`, `vault`, `vaultReady`, `vaultError`, `session`, `wallet`, `walletError`, `network`, and `lockState`; stable domain owners such as `bitcoin` and `support` live directly on the returned account owner.
+`openAccount()` owns authenticated user observation, username and avatar publication, vault observation and creation, vault unlock/lock, encrypted settings/network selection, presence, late wallet readiness, public Bitcoin data, support/report commands, chat and peer/profile composition, account switching, and secret-bearing session teardown. Focused-chat presence is separately owned by the chat session's encrypted ephemeral live transport. The account snapshot exposes `user`, `vault`, `vaultReady`, `vaultError`, `session`, `wallet`, `walletError`, `network`, and `lockState`; stable domain owners such as `bitcoin` and `support` live directly on the returned account owner.
 
 `account.profile` owns the server mutation after a platform has prepared avatar bytes or collected a username. Browser canvas work and native image manipulation remain platform-local; both then call the same `setAvatar`, `clearAvatar`, or `setUsername` command. Successful avatar commands update the shared user owner before returning.
 
 `account.peers` is the shared peer-directory owner used by Node, web, and iOS. `openAccount()` supplies its chat, wallet, blocked-user, and encrypted-cache sources directly, including missing-profile chat cleanup. Graphical adapters only subscribe to the same snapshot and profile selectors already defined by core. `openSearch('profiles')` creates profile-only search; web may also use `openSearch('mainmenu')` for its combined local-action and remote-profile menu. Active searches track peer and blocked-user changes and release those subscriptions when cleared or closed.
 
-`account.chat` is the one account-scoped encrypted chat owner used by Node, web, and iOS. It starts with the account, receives authenticated-user and unlocked-secret sources directly from `openAccount()`, and clears list, route-batch, local-message, delivery, and key-bearing state on lock or account switch. Its snapshot owns chat-list paging, encrypted inbox/private delivery, mounted-message batch inputs, sends, attachments, reactions, receipts, retention, saves, message deletion, and whole-chat deletion. Graphical chat providers only expose this owner through React; `@veyl/react` retains mounted-route lifecycle, while browser/native media preparation and foreground/native-crypto behavior enter through the `chat` platform ports.
+`account.chat` is the one account-scoped protocol-v3 chat owner used by Node, web, and iOS. It owns notes/direct/group creation, stable logical chat IDs, membership epochs, encrypted list/inbox convergence, epoch-spanning history, delivery, messages, receipts, signed encrypted chat settings, member changes, leaving, and deletion. It clears every route, cache, timer, and key-bearing state on lock/account switch. Graphical providers only expose this owner through React; platform media preparation and native behavior enter through explicit ports.
 
 `account.wallet` is the stable account-scoped wallet composition used by Node, web, and iOS. It owns the one live `core/wallet/session.js` engine, its transfer store, cached pre-Spark display state, transaction aggregation, wallet-derived peer recency, late Spark attachment, and lock teardown. `getSnapshot()` preserves the shared `{ value, txValue }` contract; `transactions` exposes aggregate/search/chart data and `transfers` exposes focused list and keyed subscriptions. Graphical wallet providers only adapt those SDK subscriptions and add browser/native behavior through the `wallet` platform ports.
 
@@ -262,6 +262,33 @@ Peer resolution accepts `@username`, username, chat public key, or wallet public
 
 ```js
 const chats = await veyl.chat.list({ count: 30 });
+const notes = await veyl.chat.notes();
+const direct = await veyl.chat.openDirect('@alice');
+const group = await veyl.chat.create(['@alice', '@bob'], { title: 'builders' });
+const activeGroup = await veyl.chat.create(['@alice', '@bob'], {
+    title: 'builders',
+    initialMessage: 'first light',
+});
+
+await veyl.chat.addMembers(group.id, ['@carol']);
+const expanded = await veyl.chat.get(group.id);
+await veyl.chat.updateSettings(group.id, {
+  title: 'night builders',
+  avatarRef: expanded.members[0].chatPK,
+});
+await veyl.chat.kickMember(group.id, memberChatPK);
+
+const groupPage = await veyl.chat.readById(group.id, { count: 30 });
+await veyl.chat.markReadIn(group.id);
+const enteredGroup = await veyl.chat.enterById(group.id, { readPolicy: 'auto' });
+const groupMessage = await veyl.chat.sendTo(group.id, 'hello everyone');
+await veyl.chat.replyIn(group.id, groupMessage.message.id, 'follow up');
+await veyl.chat.reactIn(group.id, groupMessage.message.id, '+1');
+enteredGroup.leave();
+
+await veyl.chat.leaveMembership(group.id);
+
+// Direct-peer conveniences resolve the canonical direct chat first.
 const page = await veyl.chat.read('@alice', { count: 30 });
 await veyl.chat.markRead('@alice');
 
@@ -289,9 +316,13 @@ await veyl.chat.retention('@alice', '24h');
 await veyl.chat.deleteChat('@alice', { cleanup: true });
 ```
 
-`read` advances the shared older-history loader until `count` visible messages are covered or history ends, then marks the newest applicable peer message read. `markRead` stays on the latest window and writes only the newest applicable receipt. `retry` accepts the CID of a failed local text or attachment send and uses the shared retry queue. `reply` and `reactTo` also accept a compact event object produced by `listen`. Chat reads, reduction, signatures, local pending state, send ordering, whole-chat mutation exclusion, stale-generation retry, retention, expiry holds, deletes, and encrypted cache behavior are shared with web/iOS.
+All materialized chats are stable logical objects. `notes`, `openDirect`, and `create` without `initialMessage` first return local provisional routes; they consume no KeyPackage and create no remote state or chat-list row until first content is sent. Direct open and first send both resolve the complete encrypted owner history before creating a fresh random direct. Only a membership change rotates a fresh epoch beneath an existing `chatId`; title, picture, retention, reads, reactions, and ordinary messages remain inside the current epoch. Added members do not receive old keys. A chat that becomes a group keeps permanent group lineage and never replaces a later ordinary direct chat.
+
+`avatarRef` selects one current member chat key whose live profile picture represents the chat; `null` restores automatic direct/notes/composite presentation. Arbitrary uploaded group artwork is not part of the launch storage contract. `forever` is reserved protocol state and is not exposed by official clients.
+
+`readById` pages current and owner-authorized historical epochs until `count` visible messages are covered or history ends. `markReadIn` writes the latest applicable receipt by stable chat id. Direct `read`/`markRead` are canonical-peer conveniences. Every projected message includes stable chat target and verified actor identity; group actions never need a fake direct peer.
 
-`enter` mounts that chat's framework-free shared route and returns a stable handle with `getSnapshot`, `subscribe`, `loadOlder`, `markRead`, and `leave`. Re-entering the same peer in one client returns the existing handle. The route keeps its transcript reconciled and retains already-visible retention-expired rows until explicit leave; explicit deletion still removes a row immediately. `readPolicy` is `auto` by default, `manual` disables automatic receipts but permits `entered.markRead()`, and `none` disables both. `chat.entered()` returns serializable snapshots for every mounted route, and `chat.leave(peer)` releases one without requiring the original handle.
+`enterById` mounts a logical chat route and returns a stable handle with `getSnapshot`, `subscribe`, `loadOlder`, `markRead`, and `leave`. `enter(peer)` does the same after resolving the canonical direct. Re-entering the same `chatId` reuses the handle. `readPolicy` is `auto`, `manual`, or `none`. Route-local retention holds and explicit-delete behavior match web/iOS.
 
 Attachments:
 
@@ -404,9 +435,9 @@ 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. 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.
+`listen` subscribes to the shared live chat-list and transfer-store owners. It emits `ready`, `message`, `message-delete`, `transaction`, and `error` events. Message events carry a stable `chatId`, verified actor/member summaries, and a qualified message target. Compact, incoming-only events and transient chat subscriptions are the defaults: the encrypted chat list acts as a wake index, so a changed chat opens briefly, processes its current and history pages, and releases instead of retaining one listener per chat. 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.
+Use `listen` for account-wide agent wakeups. Use `chat.enterById` when an agent is actively inside any notes/direct/group chat; use `chat.enter(peer)` only as a canonical-direct convenience.
 
 ## Local fleet owner
 

package/docs/cli.md

@@ -63,12 +63,36 @@ veyl peers block @alice
 veyl peers unblock @alice
 ```
 
-Blocking yourself is rejected. Blocking a peer immediately hides the local chat and rejects later sealed-inbox delivery from that account. Encrypted stream validation remains client-owned.
+Blocking yourself is rejected. Blocking deletes the canonical direct chat and leaves every decrypted group containing that UID. A future successor containing the block is dropped locally; no readable server membership graph exists.
 
 ## Chat
 
 ```bash
 veyl chat list [--count 30]
+veyl chat get CHAT_ID
+veyl chat notes
+veyl chat open-direct @alice
+veyl chat create-group @alice,@bob --title "builders"
+veyl chat add-members CHAT_ID @carol
+veyl chat kick-member CHAT_ID MEMBER_CHAT_PK
+veyl chat update-settings CHAT_ID '{"title":"night builders"}'
+veyl chat messages-by-id CHAT_ID [--count 30]
+veyl chat enter-by-id CHAT_ID [--read-policy auto|manual|none]
+veyl chat mark-read-by-id CHAT_ID [MESSAGE_ID]
+veyl chat send-to CHAT_ID "hello everyone"
+veyl chat reply-in CHAT_ID MESSAGE_ID "got it"
+veyl chat react-in CHAT_ID MESSAGE_ID "+1"
+veyl chat unreact-in CHAT_ID MESSAGE_ID
+veyl chat save-in CHAT_ID MESSAGE_ID
+veyl chat unsave-in CHAT_ID MESSAGE_ID
+veyl chat edit-in CHAT_ID MESSAGE_ID "corrected text"
+veyl chat delete-message-in CHAT_ID MESSAGE_ID
+veyl chat send-file-to CHAT_ID ./photo.webp
+veyl chat download-by-id CHAT_ID MESSAGE_ID ./downloaded-file
+veyl chat leave-membership CHAT_ID
+veyl chat delete-by-id CHAT_ID
+
+# Canonical-direct convenience commands:
 veyl chat enter @alice [--count 30] [--read-policy auto|manual|none]
 veyl chat entered
 veyl chat leave @alice
@@ -97,9 +121,11 @@ veyl chat share @alice MESSAGE_ID @bob,@carol
 veyl chat download @alice MESSAGE_ID ./downloaded-file
 ```
 
-`chat messages` pages the same shared older-history loader used by the app until `--count` visible messages are covered or history ends, then marks the newest applicable peer message read. The live listener likewise marks incoming plaintext it decrypts as read. `chat mark-read` remains available for an explicit latest-only write without paging older history. Explicit message delete is immediate; retention expiry remains held in an already-mounted route until that route is released.
+The `*-by-id`, `*-to`, and `*-in` commands are the primary notes/direct/group surface. Direct peer commands first resolve the canonical private direct alias. A chat that once became a group remains a separate group-lineage object even if reduced to two members.
 
-`chat enter` emits the initial mounted transcript and every later route snapshot as newline-delimited JSON. A one-off process owns the route only until that process exits. With `--session`, the foreground runtime owns the route: disconnecting or pressing Ctrl-C only detaches that output stream, `chat entered` can inspect the retained transcript later, and `chat leave` explicitly releases it. `--read-policy manual` requires `chat mark-read` or the JavaScript handle's `markRead`; `none` suppresses read writes for that entered route.
+`chat messages-by-id` and `chat messages` page the same epoch-spanning older-history loader used by the app, then mark the newest applicable message read. `chat mark-read-by-id` is the stable-chat latest-only write. Explicit message delete is immediate; retention expiry remains held in an already-mounted route until release.
+
+`chat enter-by-id` and `chat enter` emit mounted snapshots as newline-delimited JSON. A one-off process owns the route until exit. With `--session`, the foreground runtime retains it after output disconnect; `chat entered` inspects retained routes and `chat exit-by-id` releases any chat by stable id. `manual` requires an explicit mark-read; `none` suppresses read writes.
 
 ## Wallet
 

package/docs/validation.md

@@ -45,7 +45,7 @@ API version 3 establishes `open()` as the public SDK composition root and remove
 | Settings | 2 / 2 | shared user settings owner and normalization |
 | Cache | 2 / 2 | shared vault-encrypted local-data cache |
 | Peers | 6 / 6 | `core/peerlist.js`, `core/peers.js`, and shared search sessions |
-| Chat | 21 / 21 | `core/chat/session.js`, the framework-free mounted message route, shared actions, message batches, history, retention, and attachment owners |
+| Chat | 44 / 44 | `core/chat/session.js`, stable-id notes/direct/group creation, membership epochs, mounted routes, shared actions, history, retention, and attachment owners |
 | Wallet | 10 / 10 | `core/wallet/session.js`, claim, transfer-store, and tx-data owners |
 | Lightning | 5 / 5 | the same shared wallet session and Spark request owners |
 | Withdrawal | 3 / 3 | shared wallet session, fee normalization, and generic payment-intent/L1 review owner |
@@ -171,11 +171,11 @@ Cold one-off commands are inherently inefficient for agent loops because Spark b
 
 The executable source is `costs/model.mjs`.
 
-An established visible encrypted send with one active notification route is modeled as 10 Firestore read-equivalent operations, 4 writes, and 1 Function invocation; delivery with no active route is one read cheaper. Read receipts and reaction removals are encrypted stream-only actions with 3 rules reads and 1 write, while adding or changing a reaction intentionally uses the visible notification path.
+Protocol v3 separates constant content cost from recipient availability cost. One visible action commits one ciphertext, one logical-chat budget update, and at most one coalesced sender owner row: 6 planning reads and 3 writes independent of group size. Each accepted recipient wake adds two route/slot reads, one minimum push-route query when APNs is due, one overwritten slot write, and one Function invocation. The default one-edge/direct upper bound is therefore 9 reads, 4 writes, and 1 invocation. Read receipts add one shared 6-read/2-write action with no wake.
 
-The current planning bundle is about 495 Firestore read-equivalent operations, 138 writes, 28 Function invocations, and one Storage Class A operation per active user/day. Headline projections are about `$2,300/month` at 100k DAU and `$23,021/month` at 1M DAU. At a sustained one visible send per second, the model is `$35.25` gross per month, or `$44.58` with one receipt per send.
+The current one-edge planning bundle is about 542 Firestore read-equivalent operations, 163 writes, 28 Function invocations, and one Storage Class A operation per active user/day. Headline projections are about `$2,519/month` at 100k DAU and `$25,217/month` at 1M DAU. At a sustained one visible send per second, the model is `$33.70` gross per month, or `$52.36` with one receipt per send. Set `MESSAGE_RECIPIENT_EDGES` to model larger groups; sender, wake-slot, and APNs coalescing reduce the isolated-send upper bound.
 
-Live Cloud Run logs matched the intended invocation boundary: each visible message, added reaction, and explicit delete produced one `push` request; read receipts and reaction removal produced none. Current source also treats push docs as revocable authorization leases. Registration revalidates session generation and credential ownership inside its transaction, while account-wide and credential-scoped revocation delete leases transactionally; delivery therefore avoids two recipient-auth reads per active destination on every visible send. These are dated observations; current deployment state must be verified independently before a release decision.
+Earlier live Cloud Run measurements covered the retired direct-chat delivery contract and must not be treated as v3 evidence. Current source uses anonymous opaque capability delivery, a recipient-owned overwritten slot, prompt-plus-trailing sender burst coalescing, a 250 ms slot debounce, and a 2 s APNs debounce. Dev traces must establish the real accepted-wake ratio before production projections are tightened.
 
 These totals intentionally exclude Function CPU/memory duration, outbound network, APNS delivery, Spark/vendor/network fees, media download bytes, and moderation labor until real rates are measured.
 

package/examples/bot-fleet/policy.js

@@ -16,6 +16,12 @@ function canRespond(account) {
     return roles.has('echo') || roles.has('faucet');
 }
 
+function willRespond(account) {
+    return canRespond(account)
+        && account?.enabled !== false
+        && (account?.state == null || account.state === 'ready');
+}
+
 function eventId(event) {
     const chatId = String(
         event?.message?.chatId || event?.chat?.id || ''
@@ -66,11 +72,50 @@ function usernameTarget(value) {
     return username ? `@${username}` : '';
 }
 
+function chatKey(value) {
+    return String(value || '').trim().toLowerCase();
+}
+
+function isGroupMessage(event) {
+    return event?.chat?.lineage === 'group';
+}
+
+function isFleetGeneratedMessage(event) {
+    const id = String(event?.message?.cid || event?.message?.id || '').trim();
+    return id.startsWith('_bot_') || id.startsWith('_traffic_');
+}
+
 function requestAmount(event) {
     const amount = Number(event?.message?.amountSats);
     return Number.isSafeInteger(amount) && amount > 0 ? amount : null;
 }
 
+function eventChatId(event) {
+    return String(event?.message?.chatId || event?.chat?.id || '').trim();
+}
+
+function sendToEventChat(client, event, message, options) {
+    const chatId = eventChatId(event);
+    return chatId
+        ? client.chat.sendTo(chatId, message, options)
+        : client.chat.send(event.peer, message, options);
+}
+
+function sendAttachmentToEventChat(client, event, attachment, options) {
+    const chatId = eventChatId(event);
+    return chatId
+        ? client.chat.sendAttachmentTo(chatId, attachment, options)
+        : client.chat.sendAttachment(event.peer, attachment, options);
+}
+
+function markEventChatRead(client, event) {
+    const options = { messageId: event.message.id };
+    const chatId = eventChatId(event);
+    return chatId
+        ? client.chat.markReadIn(chatId, options)
+        : client.chat.markRead(event.peer, options);
+}
+
 async function runAction(
     journal,
     account,
@@ -106,7 +151,7 @@ async function sendUnderfunded(
         event,
         'faucet-insufficient',
         { replaySafe: true },
-        () => client.chat.send(event.peer, BOT_UNDERFUNDED_TEXT, {
+        () => sendToEventChat(client, event, BOT_UNDERFUNDED_TEXT, {
             cid: botActionCid(event, 'funds', account),
         })
     );
@@ -116,8 +161,9 @@ async function sendUnderfunded(
         event,
         'faucet-balance',
         { replaySafe: true },
-        () => client.chat.send(
-            event.peer,
+        () => sendToEventChat(
+            client,
+            event,
             `i only have ${availableSats} sats`,
             { cid: botActionCid(event, 'funds-balance', account) }
         )
@@ -125,17 +171,22 @@ async function sendUnderfunded(
 }
 
 async function mirrorAttachment(account, client, event) {
-    const downloaded = await client.chat.readAttachment(
-        event.peer,
-        event.message.id
-    );
+    const chatId = eventChatId(event);
+    const downloaded = chatId
+        ? await client.chat.readAttachmentIn(chatId, event.message.id)
+        : await client.chat.readAttachment(event.peer, event.message.id);
     const payload = downloaded.message?.payload || {};
-    return client.chat.sendAttachment(event.peer, {
+    return sendAttachmentToEventChat(client, event, {
         type: event.message.type,
         data: downloaded.bytes,
         mimeType: event.message.mime || payload.m,
         name: event.message.name || payload.n,
         caption: event.message.caption || payload.c,
+        size: event.message.size || payload.z,
+        width: event.message.width || payload.w,
+        height: event.message.height || payload.h,
+        duration: event.message.duration || payload.d,
+        audio: typeof event.message.audio === 'boolean' ? event.message.audio : payload.audio,
     }, {
         cid: botActionCid(event, 'echo', account),
     });
@@ -149,12 +200,13 @@ async function mirrorEcho(journal, account, client, event) {
             event,
             'echo-text',
             { replaySafe: true },
-            () => client.chat.send(event.peer, event.message.text || '', {
+            () => sendToEventChat(client, event, event.message.text || '', {
                 cid: botActionCid(event, 'echo', account),
             })
         );
     }
     if (event.message.type === 'req') {
+        if (event.chat?.lineage && event.chat.lineage !== 'direct') return null;
         const amountSats = requestAmount(event);
         if (!amountSats) return null;
         return runAction(
@@ -182,6 +234,7 @@ async function mirrorEcho(journal, account, client, event) {
 }
 
 async function serveFaucet(journal, account, client, event) {
+    if (event.chat?.lineage && event.chat.lineage !== 'direct') return null;
     const amountSats = requestAmount(event);
     if (!amountSats || !event.message.requestId) return null;
     const paymentActionId = actionId(account, event, 'faucet-payment');
@@ -310,14 +363,40 @@ export function createBotFleetPolicy(options = {}) {
         throw new Error('bot fleet baseline checkpoint required');
     }
     const managedUsernames = new Set();
+    const managedChatKeys = new Set();
     const usernameByProfile = new Map();
+    const responderProfiles = new Set();
+    const chatKeyByProfile = new Map();
     const claimStates = new Map();
 
+    function shouldMirror(event) {
+        if (isFleetGeneratedMessage(event)) return false;
+        if (!isGroupMessage(event)) {
+            return !managedUsernames.has(usernameTarget(event.peer));
+        }
+        if (
+            responderProfiles.size === 0
+            || chatKeyByProfile.size !== responderProfiles.size
+        ) {
+            return false;
+        }
+        const senderChatPK = chatKey(event.message?.senderChatPK);
+        if (!senderChatPK) return false;
+        return !managedChatKeys.has(senderChatPK);
+    }
+
     return Object.freeze({
         startFleet({ profiles }) {
+            managedUsernames.clear();
+            managedChatKeys.clear();
+            responderProfiles.clear();
+            chatKeyByProfile.clear();
             for (const profile of profiles) {
                 assertRoles(profile);
                 if (!canRespond(profile)) continue;
+                if (willRespond(profile)) {
+                    responderProfiles.add(profile.profile);
+                }
                 const username = usernameTarget(profile.username);
                 if (username) managedUsernames.add(username);
             }
@@ -338,7 +417,18 @@ export function createBotFleetPolicy(options = {}) {
                 );
             }
             usernameByProfile.set(account.profile, username);
-            if (canRespond(account)) managedUsernames.add(username);
+            if (canRespond(account)) {
+                const accountChatPK = chatKey(current?.chatPK);
+                if (!accountChatPK) {
+                    throw new Error(
+                        `bot fleet profile has no chat identity: ${account.profile}`
+                    );
+                }
+                responderProfiles.add(account.profile);
+                chatKeyByProfile.set(account.profile, accountChatPK);
+                managedChatKeys.add(accountChatPK);
+                managedUsernames.add(username);
+            }
             if (!baseline) {
                 startClaimLoop(account, client, claimStates);
             }
@@ -346,11 +436,17 @@ export function createBotFleetPolicy(options = {}) {
         async stop({ account }) {
             await stopClaimLoop(account.profile, claimStates);
             const username = usernameByProfile.get(account.profile);
+            const accountChatPK = chatKeyByProfile.get(account.profile);
             usernameByProfile.delete(account.profile);
+            chatKeyByProfile.delete(account.profile);
+            if (accountChatPK) managedChatKeys.delete(accountChatPK);
             if (username) managedUsernames.delete(username);
         },
         async stopFleet() {
             managedUsernames.clear();
+            managedChatKeys.clear();
+            responderProfiles.clear();
+            chatKeyByProfile.clear();
             await checkpoint?.flush();
         },
         async onEvent({ account, client, event }) {
@@ -386,7 +482,7 @@ export function createBotFleetPolicy(options = {}) {
                     );
                 } else if (
                     roles.has('echo') &&
-                    !managedUsernames.has(usernameTarget(event.peer))
+                    shouldMirror(event)
                 ) {
                     result = await mirrorEcho(
                         journal,
@@ -397,9 +493,7 @@ export function createBotFleetPolicy(options = {}) {
                 }
             }
             if (markRead) {
-                await client.chat.markRead(event.peer, {
-                    messageId: event.message.id,
-                });
+                await markEventChatRead(client, event);
             }
             await checkpoint?.mark(account.profile, event);
             return result;

package/package.json

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

package/readme.md

@@ -1,108 +1,61 @@
 # @glyphteck/veyl
 
-Programmable Veyl SDK with a high-level Node.js 22+ runtime and provider-neutral auth/passkey and account/vault entries for graphical clients. It exposes account, vault, profile, peer, encrypted chat, wallet, Lightning, withdrawal, invite-link, passkey, support, cache, settings, and fleet operations through one JavaScript client and a JSON CLI. A separate read-only MCP resource server exposes the packaged documentation.
+Use a Veyl account from Node.js or the shell. The package provides:
 
-The SDK is a real client, not an admin API. It uses the same shared account, vault, peer, chat, encrypted-cache, and Spark wallet owners as web and iOS. Authentication, vault decryption, message encryption/signing, attachment encryption, and wallet signing remain local.
+- account, profile, and peer management
+- end-to-end encrypted notes, direct chats, groups, files, reactions, and payment requests
+- a self-custodial Spark wallet for peer payments, Lightning, and Bitcoin withdrawals
+- a JavaScript API, JSON CLI, and live events for agents and automations
 
-The public `open()` factory selects the Node runtime ports for filesystem profiles, Firebase transport, Spark, machine credentials, browser-assisted passkeys, and local encrypted cache. Official web and iOS clients use the `@glyphteck/veyl/auth` and `@glyphteck/veyl/account` entries with platform ports for the same passkey orchestration, authenticated user, encrypted settings, public-profile mutation, vault, network, presence, wallet, transfer, transaction, public Bitcoin data, chat-session, peer-directory, profile-search, support/reporting, authenticated push leases, account deletion, and teardown owners. They do not carry separate auth, passkey, account, profile, peer, search, chat, wallet, Bitcoin, transfer, transaction, settings, support, or deletion state machines. The browser/native credential ceremony, native notification presentation, and device-local credential cleanup remain platform behavior.
+Requires Node.js 22 or newer.
 
-## Install the SDK
+## install
 
 ```bash
-npm install @glyphteck/veyl
-# or: pnpm add @glyphteck/veyl
-# or: bun add @glyphteck/veyl
+bun add @glyphteck/veyl
+# or: 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).
+## quick start
 
 ```js
 import { open } from '@glyphteck/veyl';
 
-const veyl = await open({ network: 'REGTEST' });
+const veyl = await open({ profile: 'runner', 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();
 ```
 
-`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.
+`accountKey` authenticates the account. `vaultKey` unlocks its chat and wallet. By default, both are saved in `~/.veyl/profiles/runner.json` with owner-only permissions so later runs can call `account.login()` and `vault.unlock()` without passing them again.
 
-## Optional CLI
+To store the keys in your own secret manager, pass `saveKey: false` to both creation calls and provide them later through `open({ accountKey, vaultKey })`, `VEYL_ACCOUNT_KEY`, and `VEYL_VAULT_KEY`. Never log or commit either key.
 
-The package also ships a CLI for one-off shell work:
-
-```bash
-npx veyl --network REGTEST account create @runner
-npx veyl vault create
-npx veyl account show
-npx veyl wallet address
-```
+Use `REGTEST` for development and disposable accounts. `MAINNET` uses real funds. Creating an account accepts Veyl's [Terms](https://veyl.glyphteck.com/legal#terms) and [Community Rules](https://veyl.glyphteck.com/community-rules).
 
-To create or log into a normal passkey account from a browser-capable terminal, add `--passkey` to `account create` or `account login`.
+## CLI
 
-Glyphteck's owner-only reserved namespace uses one local key:
+The CLI prints JSON, which makes it suitable for shell scripts and agents.
 
 ```bash
-npx veyl namespace init
-npx veyl --network REGTEST account create @faucet --reserved
-```
-
-Initialization writes the private seed only to `~/.veyl/namespace.seed` with mode `0600` and prints its public identity. The explicit `--reserved` account flow and Glyphteck fleet provisioning sign an exact, short-lived reserved-name claim when that file exists. General users do not possess the key and remain unable to claim reserved names.
-
-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 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.
-
-The [SDK bot fleet example](examples/bot-fleet/readme.md) is a complete public-client policy with replay checkpoints and a durable effect journal. The Glyphteck runtime consumes that same reference policy without receiving privileged backend or wallet access.
-
-```bash
-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
-veyl --profile runner --session default session stop
-```
-
-## Documentation discovery
-
-```bash
-veyl docs mcp
-```
-
-The local stdio server advertises packaged Markdown as read-only MCP resources. It cannot access accounts, credentials, chats, or wallets. Agents that control their runtime should import the SDK directly.
-
-## Local state
-
-Profiles live under `~/.veyl` by default. The directory and sensitive files use owner-only permissions.
-
-```text
-VEYL_HOME=/secure/veyl-home
-VEYL_PROFILE=runner
-VEYL_NETWORK=REGTEST
-VEYL_ACCOUNT_KEY=...
-VEYL_VAULT_KEY=...
-VEYL_WEB_URL=https://veyl.glyphteck.com
+bunx veyl --network REGTEST account create @runner
+bunx veyl vault create
+bunx veyl chat send @alice "hello"
+bunx veyl wallet balance
 ```
 
-Use `REGTEST` for development and disposable accounts. Use `MAINNET` only for real funds.
+Run `bunx veyl help` for the full command list. Long-running agents should keep one JavaScript client or persistent CLI session open instead of starting a new wallet and chat session for every action.
 
-## Documentation
+## documentation
 
-- [CLI](docs/cli.md)
 - [JavaScript API](docs/api.md)
-- [Agent operation](docs/agents.md)
-- [Documentation discovery](docs/discovery.md)
-- [Parity and validation](docs/validation.md)
+- [CLI reference](docs/cli.md)
+- [agent operation](docs/agents.md)
+- [MCP documentation discovery](docs/discovery.md)
 
-## License
+## license
 
-The official Veyl JavaScript SDK is distributed under its [proprietary SDK license](LICENSE); it is not currently open source. The license permits use of the unmodified SDK with Veyl, including normal compiled or bundled use, but not modified or standalone redistribution.
+This package is proprietary. The unmodified SDK may be used with Veyl; see the [license](LICENSE) for terms.