diff --git a/docs/pine-voice-commands.md b/docs/pine-voice-commands.md new file mode 100644 index 00000000..51e8b8c4 --- /dev/null +++ b/docs/pine-voice-commands.md @@ -0,0 +1,170 @@ +# Pine voice commands — the "what can I say" book + +Everything here is spoken to the speaker after the wake word: **"Hey Jarvis, …"** + +How it decides who answers you: +- **Exact-ish phrases** (sections 1–4) are matched **locally on your node** — instant, + free, works with no internet and no API key. +- **Anything else** goes to **Claude ("Archy")**, which either calls the same node + tools behind the scenes (so loose phrasings still get real numbers) or just + answers the question. Needs the Anthropic API key that Pine seeds. +- **Mesh announcements** need nobody to say anything — the speaker pipes up on its + own when a mesh message arrives. + +--- + +## 1. Bitcoin — block height (local, instant) + +- "what's the block height" +- "what's the current block height" +- "what is the block height" +- "block height" +- "current block height" +- "how many blocks" +- "how many blocks are there" + +## 2. Peers — bitcoin **and** mesh in one answer (local, instant) + +The answer includes both your bitcoin peer count and your mesh peer count. + +- "how many peers" +- "how many peers do I have" +- "how many peers is the node connected to" +- "peer count" +- "node peer count" + +## 3. Sync status (local, instant) + +Fully synced → it tells you the block it's synced to. Still syncing → the percent. + +- "is the node synced" +- "is bitcoin synced" +- "is the node fully synced" +- "is bitcoin fully synced" +- "how synced is the node" +- "how synced is bitcoin" +- "sync status" +- "bitcoin sync status" +- "sync progress" +- "sync percentage" + +## 4. Lightning balance (local, instant) + +- "what's my lightning balance" +- "what is my lightning balance" +- "lightning balance" +- "how many sats do I have" +- "how many sats are in my wallet" + +--- + +## 5. Same questions, said like a human (Claude routes to the node) + +The point of the AI brain: you don't have to remember the magic words. All of +these end in the same real numbers as sections 1–4: + +- "how tall is the chain right now" +- "what block are we on" +- "is my bitcoin thing done downloading yet" +- "how far along is the sync" +- "are we caught up with the blockchain" +- "how's my node doing" +- "is everything okay with the node" +- "how many people is my node talking to" +- "is anyone connected to my node" +- "am I rich in lightning" +- "how much money is in my lightning wallet" +- "do I have any sats" +- "what's my node's status" + +## 6. Mesh + +**Hands-free announcements** — when a mesh text arrives, the speaker announces it +by itself: *"New mesh message from ⟨sender⟩: ⟨text⟩"*. Nothing to say; just have +someone send you one. + +**Asking about the mesh:** + +- "how many peers" — the local answer already includes mesh peers +- "how many mesh peers do I have" +- "am I connected to the mesh" +- "what was the last mesh message" +- "who sent the last mesh message" +- "read me the latest mesh message" +- "did I get any mesh messages" + +(The last-message questions go through Claude reading the mesh sensor — phrasing +is free-form.) + +## 7. Ask the AI anything + +Short spoken answers, one or two sentences, no robot-reading-markdown. A sampler +by mood: + +**Bitcoin & lightning, explained** +- "what actually happens when a block is mined" +- "explain the halving like I'm five" +- "what's the difference between on-chain and lightning" +- "why do confirmations matter" +- "what's a mempool" +- "is it normal for sync to take days" + +**Everyday brain** +- "why is the sky blue" +- "how long do I boil an egg" +- "what can I cook with eggs and spinach" +- "what's 15 percent of 84" +- "how many ounces in a kilo" +- "what's 21 million divided by 8 billion" +- "how do you say good morning in Portuguese" +- "give me a word that rhymes with orange" + +**Fun** +- "tell me a joke" +- "tell me a bitcoin joke" +- "give me a fun fact" +- "tell me a two-sentence scary story" +- "settle an argument: is a hotdog a sandwich" + +**Advice-ish** +- "what should I name my node" +- "give me one tip for keeping my seed phrase safe" +- "what's a good way to explain my node to my mum" + +Follow-ups work conversationally — ask something, then "and why is that?" without +re-explaining yourself. + +## 8. Built-in assistant basics (Home Assistant, local) + +- "what time is it" +- "what's the date today" +- "set a timer for 5 minutes" / "cancel the timer" / "how long is left on the + timer" — *timer support depends on the PineVoice satellite build; try it once + and you'll know.* +- "nevermind" / "cancel" — bail out of a listening session. + +## 9. Smart home (only if you've got devices in Home Assistant) + +Pine rides on Home Assistant Assist, so if you ever add exposed devices +(lights, plugs, sensors), the standard grammar lights up automatically: + +- "turn on the living room light" / "turn off everything" +- "is the front door locked" +- "what's the temperature inside" + +No devices → these politely fail; nothing to test today. + +## 10. Known not-to-work (yet) — don't burn time on these + +- **Sending** a mesh message by voice ("tell Bob I'm on my way") — receive/announce + only, for now. +- Controlling the node by voice ("restart bitcoin", "install an app") — read-only + on purpose. +- Long memory across sessions — each conversation is fresh. + +--- + +## If something misbehaves + +Say exactly what you said, what it answered (or didn't), and roughly when — the +node keeps logs of every pipeline run and it's usually a one-look diagnosis.