nostr-bray 1.7.2 → 1.9.0

package/dist/cli.js

@@ -19,6 +19,7 @@ import { handleTrustSpokenChallenge, handleTrustSpokenVerify } from './trust/spo
 import { handleDuressConfigure, handleDuressActivate } from './safety/handlers.js';
 import { handleZapSend, handleZapBalance, handleZapMakeInvoice, handleZapLookupInvoice, handleZapListTransactions, handleZapReceipts, handleZapDecode } from './zap/handlers.js';
 import { handleDecode, handleEncodeNpub, handleEncodeNote, handleEncodeNprofile, handleEncodeNevent, handleVerify, handleEncrypt, handleDecrypt, handleCount, handleFetch, handleKeyPublic, handleEncodeNsec, handleFilter, handleNipList, handleNipShow } from './util/handlers.js';
+import { getCommandHelp } from './help.js';
 const args = process.argv.slice(2);
 const command = args[0];
 // No command = start MCP server
@@ -26,6 +27,14 @@ if (!command || command === 'serve') {
     await import('./index.js');
     process.exit(0);
 }
+// Per-command help: `nostr-bray post --help`
+if (args.includes('--help') && command && command !== 'help' && command !== '--help' && command !== '-h') {
+    const help = getCommandHelp(command);
+    if (help) {
+        console.log(help);
+        process.exit(0);
+    }
+}
 const HELP = `nostr-bray — Sovereign Nostr identities for AI agents
 
 Usage: nostr-bray [command] [args]
@@ -127,7 +136,23 @@ Environment:
   NOSTR_SECRET_KEY_FILE         Path to secret key file
   NOSTR_RELAYS                  Comma-separated relay URLs
   NWC_URI / NWC_URI_FILE        Nostr Wallet Connect URI
-  TOR_PROXY                     SOCKS5h proxy URL`;
+  TOR_PROXY                     SOCKS5h proxy URL
+
+Quick examples:
+  nostr-bray whoami                           # show your npub
+  nostr-bray post "gm nostr"                  # publish a note
+  nostr-bray persona work                     # derive work identity
+  nostr-bray dm abc123... "secret message"    # send encrypted DM
+  nostr-bray decode npub1...                  # decode any nip19 entity
+  nostr-bray nips                             # browse official NIPs
+  nostr-bray shell                            # interactive mode
+
+Use 'nostr-bray <command> --help' for detailed help on any command.
+
+Learn more:
+  Guide:     https://github.com/forgesworn/bray/blob/main/docs/guide.md
+  Examples:  https://github.com/forgesworn/bray/tree/main/examples
+  npm:       https://www.npmjs.com/package/nostr-bray`;
 if (command === 'help' || command === '--help' || command === '-h') {
     console.log(HELP);
     process.exit(0);

package/dist/help.d.ts

@@ -0,0 +1,9 @@
+/** Per-command help with examples and detail */
+export declare const COMMAND_HELP: Record<string, {
+    usage: string;
+    description: string;
+    examples: string[];
+    notes?: string;
+}>;
+/** Get formatted help for a single command */
+export declare function getCommandHelp(cmd: string): string | null;

package/dist/help.js

@@ -0,0 +1,102 @@
+/** Per-command help with examples and detail */
+export const COMMAND_HELP = {
+    // Identity
+    whoami: { usage: 'whoami', description: 'Show the active identity\'s npub.', examples: ['nostr-bray whoami'] },
+    create: { usage: 'create', description: 'Generate a fresh Nostr identity with a BIP-39 mnemonic seed. Returns the master npub and mnemonic for backup.', examples: ['nostr-bray create'], notes: 'Store the mnemonic securely — it will not be shown again.' },
+    list: { usage: 'list', description: 'List all known identities. Returns npub, purpose, and persona name. Never includes private keys.', examples: ['nostr-bray list'] },
+    derive: { usage: 'derive <purpose> [index]', description: 'Derive a child identity by purpose string and optional index. Deterministic — same inputs always produce the same npub.', examples: ['nostr-bray derive messaging', 'nostr-bray derive signing 0', 'nostr-bray derive signing 1  # different index = different key'] },
+    persona: { usage: 'persona <name> [index]', description: 'Derive a named persona (e.g. work, personal, anonymous). Shorthand for deriving with a semantic name.', examples: ['nostr-bray persona work', 'nostr-bray persona anonymous'] },
+    switch: { usage: 'switch <target> [index]', description: 'Switch the active identity. All subsequent operations sign as the new identity. Use "master" to return to root.', examples: ['nostr-bray switch work', 'nostr-bray switch master', 'nostr-bray switch messaging 0'] },
+    prove: { usage: 'prove [blind|full]', description: 'Create a cryptographic linkage proof between the master key and the active identity.\n  blind — proves the link without revealing the derivation path (default)\n  full  — reveals the purpose and index (use with care)', examples: ['nostr-bray prove', 'nostr-bray prove blind', 'nostr-bray prove full'] },
+    'proof-publish': { usage: 'proof-publish [blind|full] [--confirm]', description: 'Publish a linkage proof to relays as a kind 30078 event. This is IRREVERSIBLE — once published, the link between identities is public.', examples: ['nostr-bray proof-publish blind', 'nostr-bray proof-publish full --confirm'], notes: 'Without --confirm, shows a preview of what will be revealed.' },
+    backup: { usage: 'backup <dir> [threshold] [shares]', description: 'Split the active identity\'s private key into Shamir shards written to files. Default is 3-of-5 (any 3 shards reconstruct the key). Shard files use 0600 permissions.', examples: ['nostr-bray backup ./shards', 'nostr-bray backup ./shards 2 3  # 2-of-3 scheme'] },
+    restore: { usage: 'restore <file1> <file2> ... -t <threshold>', description: 'Reconstruct a secret key from Shamir shard files.', examples: ['nostr-bray restore ./shards/shard-1.bray ./shards/shard-2.bray -t 2'] },
+    'identity-backup': { usage: 'identity-backup <pubkey-hex>', description: 'Fetch profile (kind 0), contacts (kind 3), relay list (kind 10002), and attestations for a pubkey. Returns a portable JSON bundle — no private keys.', examples: ['nostr-bray identity-backup abc123...'] },
+    'identity-restore': { usage: 'identity-restore <pubkey-hex>', description: 'Re-sign migratable events (profile, contacts, relay list) under the active identity. Skips attestations to protect the trust chain.', examples: ['nostr-bray identity-restore abc123...'] },
+    migrate: { usage: 'migrate <old-hex> <old-npub> [--confirm]', description: 'Full identity migration. Preview first (shows profile fields, contact count), then execute with --confirm. Publishes a linkage proof and re-signs migratable events.', examples: ['nostr-bray migrate abc123... npub1old...', 'nostr-bray migrate abc123... npub1old... --confirm'] },
+    // Social
+    post: { usage: 'post "message"', description: 'Publish a text note (kind 1) as the active identity.', examples: ['nostr-bray post "gm nostr"', 'nostr-bray post "Hello from my work persona!"'] },
+    reply: { usage: 'reply <event-id> <pubkey> "text"', description: 'Reply to a Nostr event with correct e-tag and p-tag threading.', examples: ['nostr-bray reply abc123... def456... "Great post!"'] },
+    react: { usage: 'react <event-id> <pubkey> [emoji]', description: 'React to a Nostr event (kind 7). Defaults to "+" if no emoji specified.', examples: ['nostr-bray react abc123... def456...', 'nostr-bray react abc123... def456... 🤙'] },
+    delete: { usage: 'delete <event-id> [reason]', description: 'Request deletion of an event you published (kind 5). Relays may or may not honour the request.', examples: ['nostr-bray delete abc123...', 'nostr-bray delete abc123... "posted by mistake"'] },
+    repost: { usage: 'repost <event-id> <pubkey>', description: 'Repost/boost a Nostr event (kind 6).', examples: ['nostr-bray repost abc123... def456...'] },
+    profile: { usage: 'profile <pubkey-hex>', description: 'Fetch and display a Nostr profile (kind 0) for any pubkey.', examples: ['nostr-bray profile abc123...'] },
+    'profile-set': { usage: 'profile-set \'{"name":"...","about":"..."}\'', description: 'Set the kind 0 profile for the active identity. If a profile already exists, shows a diff and requires --confirm to overwrite.', examples: ['nostr-bray profile-set \'{"name":"Bray User","about":"Powered by nostr-bray"}\'', 'nostr-bray profile-set \'{"name":"Updated"}\' --confirm'] },
+    contacts: { usage: 'contacts <pubkey-hex>', description: 'List who a pubkey follows (kind 3 contact list). Shows pubkeys, relay hints, and petnames.', examples: ['nostr-bray contacts abc123...'] },
+    follow: { usage: 'follow <pubkey-hex> [relay] [petname]', description: 'Follow a pubkey. Fetches current contact list, adds the pubkey, publishes updated kind 3.', examples: ['nostr-bray follow abc123...', 'nostr-bray follow abc123... wss://relay.example.com alice'] },
+    unfollow: { usage: 'unfollow <pubkey-hex>', description: 'Unfollow a pubkey. Removes from contact list and publishes updated kind 3.', examples: ['nostr-bray unfollow abc123...'] },
+    dm: { usage: 'dm <pubkey-hex> "message" [--nip04]', description: 'Send an encrypted direct message. Uses NIP-17 gift wrap by default (most private — sender identity hidden behind ephemeral key). Add --nip04 for legacy NIP-04 (requires NIP04_ENABLED=1).', examples: ['nostr-bray dm abc123... "Secret message"', 'nostr-bray dm abc123... "Legacy DM" --nip04'] },
+    'dm-read': { usage: 'dm-read', description: 'Read direct messages addressed to the active identity. Decrypts both NIP-17 and NIP-04 messages. Returns error metadata (not crash) on decryption failure.', examples: ['nostr-bray dm-read'] },
+    feed: { usage: 'feed [--limit N]', description: 'Fetch the kind 1 text note feed from your relays.', examples: ['nostr-bray feed', 'nostr-bray feed --limit 10'] },
+    notifications: { usage: 'notifications [--limit N]', description: 'Fetch mentions, replies, reactions, and zap receipts for the active identity.', examples: ['nostr-bray notifications', 'nostr-bray notifications --limit 5'] },
+    'nip-publish': { usage: 'nip-publish <identifier> <title> <content-or-file> [--kinds N,N]', description: 'Publish a community NIP (kind 30817) — a custom protocol specification on Nostr. Content can be inline markdown or a file path.', examples: ['nostr-bray nip-publish my-protocol "My Protocol" ./spec.md', 'nostr-bray nip-publish gaming "Gaming Events" ./gaming.md --kinds 30100,30101'] },
+    'nip-read': { usage: 'nip-read [--author X] [--kind N] [--identifier X]', description: 'Fetch community NIPs (kind 30817) from relays.', examples: ['nostr-bray nip-read', 'nostr-bray nip-read --author abc123...', 'nostr-bray nip-read --kind 30100'] },
+    // Blossom
+    'blossom-upload': { usage: 'blossom-upload <server> <file>', description: 'Upload a file to a blossom media server. Signs a kind 24242 auth event. Returns the blob URL and SHA-256 hash.', examples: ['nostr-bray blossom-upload https://blossom.example.com ./photo.jpg'] },
+    'blossom-list': { usage: 'blossom-list <server> <pubkey-hex>', description: 'List blobs uploaded by a pubkey on a blossom server.', examples: ['nostr-bray blossom-list https://blossom.example.com abc123...'] },
+    'blossom-delete': { usage: 'blossom-delete <server> <sha256>', description: 'Delete a blob from a blossom media server by its SHA-256 hash.', examples: ['nostr-bray blossom-delete https://blossom.example.com deadbeef...'] },
+    // Groups
+    'group-info': { usage: 'group-info <group-id>', description: 'Fetch NIP-29 group metadata (name, about, picture, open status).', examples: ['nostr-bray group-info my-group'] },
+    'group-chat': { usage: 'group-chat <group-id> [--limit N]', description: 'Fetch recent chat messages (kind 9) from a NIP-29 group.', examples: ['nostr-bray group-chat my-group', 'nostr-bray group-chat my-group --limit 50'] },
+    'group-send': { usage: 'group-send <group-id> "message"', description: 'Send a message to a NIP-29 group (kind 9 with h-tag).', examples: ['nostr-bray group-send my-group "Hello group!"'] },
+    'group-members': { usage: 'group-members <group-id>', description: 'List members of a NIP-29 group.', examples: ['nostr-bray group-members my-group'] },
+    // Trust
+    attest: { usage: 'attest <type> <identifier> [subject]', description: 'Create and publish a kind 31000 verifiable attestation (NIP-VA).', examples: ['nostr-bray attest identity-verification abc123... def456...', 'nostr-bray attest endorsement org-member'] },
+    'trust-read': { usage: 'trust-read [--subject X] [--type X] [--attestor X]', description: 'Read kind 31000 attestations from relays. All filters are optional.', examples: ['nostr-bray trust-read --subject abc123...', 'nostr-bray trust-read --type identity-verification'] },
+    'trust-verify': { usage: 'trust-verify <event-json>', description: 'Validate the structural correctness of a kind 31000 attestation event.', examples: ['nostr-bray trust-verify \'{"kind":31000,...}\''] },
+    'trust-revoke': { usage: 'trust-revoke <type> <identifier>', description: 'Revoke a previously issued attestation. Active identity must match the original attestor.', examples: ['nostr-bray trust-revoke identity-verification abc123...'] },
+    'trust-request': { usage: 'trust-request <pubkey> <subject> <type>', description: 'Send an attestation request via NIP-17 encrypted DM.', examples: ['nostr-bray trust-request abc123... def456... identity-verification'] },
+    'trust-request-list': { usage: 'trust-request-list', description: 'Scan received NIP-17 DMs for attestation request payloads.', examples: ['nostr-bray trust-request-list'] },
+    'ring-prove': { usage: 'ring-prove <type> <pk1,pk2,...>', description: 'Create a ring signature proving anonymous group membership. Your active identity must be one of the pubkeys in the comma-separated ring.', examples: ['nostr-bray ring-prove kyc-verified abc123,def456,ghi789'] },
+    'ring-verify': { usage: 'ring-verify <event-json>', description: 'Verify a ring signature proof.', examples: ['nostr-bray ring-verify \'{"kind":30078,...}\''] },
+    'spoken-challenge': { usage: 'spoken-challenge <secret> <context> <counter>', description: 'Generate a spoken verification token for in-person identity confirmation. Both parties share a secret and verify via spoken words.', examples: ['nostr-bray spoken-challenge aabbccdd... meeting-2026-03-25 1'] },
+    'spoken-verify': { usage: 'spoken-verify <secret> <context> <counter> <input>', description: 'Verify a spoken token response.', examples: ['nostr-bray spoken-verify aabbccdd... meeting-2026-03-25 1 castle'] },
+    // Relay
+    'relay-list': { usage: 'relay-list [--compare npub]', description: 'List the relay set (read/write) for the active identity. Optionally warn about shared relays with another identity.', examples: ['nostr-bray relay-list', 'nostr-bray relay-list --compare npub1other...'] },
+    'relay-set': { usage: 'relay-set <url1> <url2> ... [--confirm]', description: 'Publish a kind 10002 relay list. Warns if one already exists — use --confirm to overwrite.', examples: ['nostr-bray relay-set wss://relay.damus.io wss://nos.lol', 'nostr-bray relay-set wss://relay.damus.io --confirm'] },
+    'relay-add': { usage: 'relay-add <url> [read|write]', description: 'Add a relay to the active identity\'s relay set (in-memory only — does not publish kind 10002).', examples: ['nostr-bray relay-add wss://new-relay.com', 'nostr-bray relay-add wss://read-only.com read'] },
+    'relay-info': { usage: 'relay-info <wss://url>', description: 'Fetch the NIP-11 relay information document (name, description, supported NIPs, limits).', examples: ['nostr-bray relay-info wss://relay.damus.io'] },
+    // Zap
+    'zap-send': { usage: 'zap-send <bolt11>', description: 'Pay a Lightning invoice via Nostr Wallet Connect (NIP-47). Requires NWC_URI configured.', examples: ['nostr-bray zap-send lnbc10u1...'] },
+    'zap-balance': { usage: 'zap-balance', description: 'Request wallet balance via NWC.', examples: ['nostr-bray zap-balance'] },
+    'zap-invoice': { usage: 'zap-invoice <msats> [description]', description: 'Generate a Lightning invoice via NWC to receive payments.', examples: ['nostr-bray zap-invoice 100000 "Coffee payment"'] },
+    'zap-lookup': { usage: 'zap-lookup <payment-hash>', description: 'Look up a Lightning invoice payment status via NWC.', examples: ['nostr-bray zap-lookup abc123...'] },
+    'zap-transactions': { usage: 'zap-transactions [--limit N]', description: 'List recent Lightning transactions via NWC.', examples: ['nostr-bray zap-transactions', 'nostr-bray zap-transactions --limit 5'] },
+    'zap-receipts': { usage: 'zap-receipts [--limit N]', description: 'Fetch zap receipts (kind 9735) for the active identity. Returns sender, amount in msats, and message.', examples: ['nostr-bray zap-receipts', 'nostr-bray zap-receipts --limit 10'] },
+    'zap-decode': { usage: 'zap-decode <bolt11>', description: 'Decode basic fields from a bolt11 Lightning invoice string.', examples: ['nostr-bray zap-decode lnbc10u1...'] },
+    // Safety
+    'safety-configure': { usage: 'safety-configure [persona-name]', description: 'Configure an alternative identity persona for emergency use. Defaults to "anonymous".', examples: ['nostr-bray safety-configure', 'nostr-bray safety-configure emergency'] },
+    'safety-activate': { usage: 'safety-activate [persona-name]', description: 'Switch to an alternative identity. Response is structurally identical to identity switch — an observer cannot distinguish this from a normal switch.', examples: ['nostr-bray safety-activate', 'nostr-bray safety-activate emergency'] },
+    // Utility
+    decode: { usage: 'decode <nip19>', description: 'Decode any nip19 entity (npub, nsec, note, nevent, nprofile, naddr) or nostr: URI to its components. For nsec, returns the derived pubkey — never the private key.', examples: ['nostr-bray decode npub1abc...', 'nostr-bray decode nevent1...', 'nostr-bray decode nostr:npub1abc...'] },
+    'encode-npub': { usage: 'encode-npub <hex>', description: 'Encode a 64-character hex public key as a bech32 npub.', examples: ['nostr-bray encode-npub abc123...'] },
+    'encode-note': { usage: 'encode-note <hex>', description: 'Encode a 64-character hex event ID as a bech32 note.', examples: ['nostr-bray encode-note abc123...'] },
+    'encode-nprofile': { usage: 'encode-nprofile <hex> [relay1,relay2,...]', description: 'Encode a hex pubkey with optional relay hints as a bech32 nprofile.', examples: ['nostr-bray encode-nprofile abc123...', 'nostr-bray encode-nprofile abc123... wss://relay.example.com'] },
+    'encode-nevent': { usage: 'encode-nevent <hex> [relay1,relay2,...]', description: 'Encode a hex event ID with optional relay hints as a bech32 nevent.', examples: ['nostr-bray encode-nevent abc123... wss://relay.example.com'] },
+    'encode-nsec': { usage: 'encode-nsec <hex>', description: 'Encode a 64-character hex private key as a bech32 nsec.', examples: ['nostr-bray encode-nsec abc123...'], notes: 'WARNING: private key is passed as a CLI argument. Use only on trusted systems.' },
+    'key-public': { usage: 'key-public <nsec-or-hex>', description: 'Derive a public key (hex + npub) from a secret key.', examples: ['nostr-bray key-public nsec1...', 'nostr-bray key-public abc123...'], notes: 'WARNING: secret key is passed as a CLI argument. Use only on trusted systems.' },
+    filter: { usage: 'filter <event-json> <filter-json>', description: 'Test if a Nostr event matches a given filter. Returns true or false.', examples: ['nostr-bray filter \'{"kind":1,...}\' \'{"kinds":[1]}\''] },
+    nips: { usage: 'nips', description: 'List all official Nostr NIPs from the protocol repository.', examples: ['nostr-bray nips'] },
+    nip: { usage: 'nip <number>', description: 'Fetch and display the full content of an official NIP by number.', examples: ['nostr-bray nip 1', 'nostr-bray nip 17', 'nostr-bray nip 65'] },
+    verify: { usage: 'verify <event-json>', description: 'Verify a Nostr event\'s id hash and cryptographic signature.', examples: ['nostr-bray verify \'{"id":"...","pubkey":"...","sig":"...",...}\''] },
+    encrypt: { usage: 'encrypt <pubkey-hex> "plaintext"', description: 'Encrypt a string using NIP-44 for a recipient pubkey. Uses the active identity\'s private key.', examples: ['nostr-bray encrypt abc123... "secret message"'] },
+    decrypt: { usage: 'decrypt <pubkey-hex> <ciphertext>', description: 'Decrypt a NIP-44 ciphertext using the active identity\'s private key.', examples: ['nostr-bray decrypt abc123... AQBh7...'] },
+    count: { usage: 'count [--kinds N,N] [--authors X,X] [--since N]', description: 'Count events matching a filter on relays.', examples: ['nostr-bray count --kinds 1', 'nostr-bray count --kinds 1,7 --authors abc123...'] },
+    fetch: { usage: 'fetch <nip19>', description: 'Fetch events by nip19 code (note, nevent, nprofile, npub, naddr). Resolves the entity and queries relays.', examples: ['nostr-bray fetch note1...', 'nostr-bray fetch nevent1...', 'nostr-bray fetch npub1...'] },
+    shell: { usage: 'shell', description: 'Start an interactive REPL with a persistent relay connection. Supports tab autocomplete. Type "help" for commands, "exit" to quit.', examples: ['nostr-bray shell'] },
+};
+/** Get formatted help for a single command */
+export function getCommandHelp(cmd) {
+    const h = COMMAND_HELP[cmd];
+    if (!h)
+        return null;
+    let out = `\nUsage: nostr-bray ${h.usage}\n\n${h.description}\n`;
+    if (h.notes)
+        out += `\n  ${h.notes}\n`;
+    out += '\nExamples:\n';
+    for (const ex of h.examples) {
+        out += `  ${ex}\n`;
+    }
+    out += '\nLearn more: https://github.com/forgesworn/bray/blob/main/docs/guide.md';
+    return out;
+}

package/dist/identity/tools.js

@@ -5,7 +5,7 @@ import { hexId } from '../validation.js';
 import { handleIdentityBackup, handleIdentityRestore, handleIdentityMigrate } from './migration.js';
 export function registerIdentityTools(server, deps) {
     server.registerTool('identity_create', {
-        description: 'Generate a fresh Nostr identity with a BIP-39 mnemonic seed. Returns the master npub and mnemonic for backup.',
+        description: 'Generate a fresh Nostr identity with a BIP-39 mnemonic seed. Returns { npub, mnemonic }. Store the mnemonic securely — it will not be shown again. Use this when the user needs a brand new identity unrelated to the current one.',
         annotations: { readOnlyHint: false },
     }, async () => {
         const result = handleIdentityCreate();
@@ -14,7 +14,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_derive', {
-        description: 'Derive a child Nostr identity from the active tree root. Returns the new npub.',
+        description: 'Derive a child Nostr identity from the master key by purpose and index. Deterministic — same inputs always produce the same npub. Returns { npub, purpose, index }. Use identity_switch after deriving to operate as the new identity.',
         inputSchema: {
             purpose: z.string().describe('Purpose string for derivation (e.g. "messaging", "signing")'),
             index: z.number().int().min(0).default(0).describe('Derivation index (default 0)'),
@@ -27,7 +27,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_derive_persona', {
-        description: 'Derive a named persona identity (e.g. "work", "personal", "anonymous"). Returns the new npub.',
+        description: 'Derive a named persona (e.g. "work", "personal", "anonymous"). Like identity_derive but uses a human-readable name. Returns { npub, personaName, index }. Follow with identity_switch to activate.',
         inputSchema: {
             name: z.string().describe('Persona name (e.g. "work", "personal", "anonymous")'),
             index: z.number().int().min(0).default(0).describe('Derivation index (default 0)'),
@@ -40,7 +40,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_switch', {
-        description: 'Switch the active Nostr identity. All subsequent tools operate as the new identity. Use "master" to return to root.',
+        description: 'Switch the active Nostr identity. ALL subsequent tool calls will sign events and query relays as the new identity. Pass "master" to return to root. Returns { npub } of the now-active identity. This is the key tool for multi-persona workflows.',
         inputSchema: {
             target: z.string().describe('Purpose, persona name, or "master" to switch to'),
             index: z.number().int().min(0).optional().describe('Derivation index (if switching by purpose)'),
@@ -53,7 +53,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_list', {
-        description: 'List all known Nostr identities. Returns npub, purpose, and persona name for each. Never includes private keys.',
+        description: 'List all known identities (master + all derived). Returns array of { npub, purpose, index, personaName }. Never includes private keys. Use this to see what identities are available before switching.',
         annotations: { readOnlyHint: true },
     }, async () => {
         const result = handleIdentityList(deps.ctx);
@@ -62,7 +62,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_prove', {
-        description: 'Create a cryptographic linkage proof between the master key and the active identity. Defaults to blind proof (no purpose/index revealed).',
+        description: 'Create a cryptographic linkage proof between the master key and the active identity. "blind" (default) proves they share a master without revealing how the child was derived. "full" also reveals the purpose and index. Returns a LinkageProof object that can be verified by anyone with nsec-tree. Use trust_proof_publish to make it permanent on relays.',
         inputSchema: {
             mode: z.enum(['blind', 'full']).default('blind').describe('Proof mode: "blind" hides derivation path, "full" reveals purpose and index'),
         },
@@ -74,7 +74,7 @@ export function registerIdentityTools(server, deps) {
         };
     });
     server.registerTool('identity_backup_shamir', {
-        description: 'Split the master secret into Shamir shard files. Shard content is written to disk — never returned in the response.',
+        description: 'Split the active identity\'s private key into Shamir shard files using threshold secret sharing. Any "threshold" shards can reconstruct the key. Files written with 0600 permissions via atomic rename. Returns file paths only — shard content never appears in the response.',
         inputSchema: {
             threshold: z.number().int().min(2).describe('Minimum shards needed to reconstruct'),
             shares: z.number().int().min(2).describe('Total number of shards to create'),

package/dist/social/tools.js

@@ -8,7 +8,7 @@ import { handleBlossomUpload, handleBlossomList, handleBlossomDelete } from './b
 import { handleGroupInfo, handleGroupChat, handleGroupSend, handleGroupMembers } from './groups.js';
 export function registerSocialTools(server, deps) {
     server.registerTool('social_post', {
-        description: 'Post a text note (kind 1) as the active identity. Returns the signed event.',
+        description: 'Post a text note (kind 1) signed by the active identity and publish to relays. Returns { id, pubkey, publish: { success, accepted, rejected } }. The most common social action.',
         inputSchema: {
             content: z.string().describe('Text content of the note'),
         },
@@ -24,7 +24,7 @@ export function registerSocialTools(server, deps) {
         };
     });
     server.registerTool('social_reply', {
-        description: 'Reply to a Nostr event (kind 1 with e-tag and p-tag) as the active identity.',
+        description: 'Reply to a Nostr event (kind 1) with correct threading tags. You need the event ID and the author\'s pubkey — get these from social_feed or social_notifications.',
         inputSchema: {
             content: z.string().describe('Reply text'),
             replyTo: hexId.describe('Event ID being replied to (hex)'),
@@ -42,7 +42,7 @@ export function registerSocialTools(server, deps) {
         };
     });
     server.registerTool('social_react', {
-        description: 'React to a Nostr event (kind 7) as the active identity. Default reaction is "+".',
+        description: 'React to a Nostr event (kind 7). Pass "+" for like, or any emoji (🤙, ❤️, 🔥). You need the event ID and author pubkey.',
         inputSchema: {
             eventId: hexId.describe('Event ID to react to (hex)'),
             eventPubkey: hexId.describe('Pubkey of the event author (hex)'),
@@ -135,7 +135,7 @@ export function registerSocialTools(server, deps) {
         };
     });
     server.registerTool('dm_send', {
-        description: 'Send a direct message to a Nostr pubkey. Uses NIP-17 gift wrap by default. Set nip04: true for legacy NIP-04 (requires NIP04_ENABLED).',
+        description: 'Send an encrypted direct message. Default: NIP-17 gift wrap (most private — sender identity hidden behind ephemeral key). Set nip04: true for legacy NIP-04 (only if NIP04_ENABLED=1). Returns { protocol, id, publish }.',
         inputSchema: {
             recipientPubkeyHex: hexId.describe('Recipient hex pubkey'),
             message: z.string().describe('Message text'),
@@ -160,7 +160,7 @@ export function registerSocialTools(server, deps) {
         };
     });
     server.registerTool('dm_read', {
-        description: 'Read direct messages addressed to the active identity. Decrypts NIP-17 and NIP-04 messages.',
+        description: 'Read direct messages addressed to the active identity. Decrypts both NIP-17 (gift wrap) and NIP-04 (legacy). Each message includes { from, content, protocol, decrypted }. Gracefully handles decryption failures without crashing.',
         annotations: { readOnlyHint: true },
     }, async () => {
         const messages = await handleDmRead(deps.ctx, deps.pool);

package/dist/trust/tools.js

@@ -5,7 +5,7 @@ import { handleTrustRingProve, handleTrustRingVerify } from './ring.js';
 import { handleTrustSpokenChallenge, handleTrustSpokenVerify } from './spoken.js';
 export function registerTrustTools(server, deps) {
     server.registerTool('trust_attest', {
-        description: 'Create and publish a kind 31000 verifiable attestation as the active identity.',
+        description: 'Create and publish a kind 31000 verifiable attestation (NIP-VA) as the active identity. An attestation is a signed statement about a subject (e.g. "I verify this pubkey belongs to Alice"). Warns if attesting from a derived persona instead of master. Use trust_read to find existing attestations, trust_revoke to revoke them.',
         inputSchema: {
             type: z.string().describe('Attestation type (e.g. "identity-verification", "endorsement")'),
             identifier: z.string().optional().describe('D-tag identifier (hex pubkey or context string)'),
@@ -124,7 +124,7 @@ export function registerTrustTools(server, deps) {
         };
     });
     server.registerTool('trust_ring_prove', {
-        description: 'Create a ring signature proving anonymous membership in a group of public keys.',
+        description: 'Create a ring signature proving anonymous group membership. A verifier can confirm "someone in this ring signed this" but cannot determine who. The active identity must be one of the pubkeys in the ring. Returns kind 30078 event with the signature.',
         inputSchema: {
             ring: z.array(hexId).describe('Hex x-only public keys of ring members (must include active identity)'),
             attestationType: z.string().describe('Attestation type context for the canonical message'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "1.7.2",
+  "version": "1.9.0",
   "description": "MCP server giving AI agents sovereign Nostr identities — key derivation, personas, attestations, duress detection, zaps",
   "type": "module",
   "main": "dist/index.js",