bland-cli 0.2.8 → 0.2.9

package/README.md

@@ -126,9 +126,9 @@ nodes:
       Greet the customer warmly. Ask how you can help them today.
     edges:
       - target: identify_issue
-        condition: "Customer describes their problem"
+        label: "Customer describes their problem"
       - target: transfer_human
-        condition: "Customer asks for a human"
+        label: "Customer asks for a human"
 
   identify_issue:
     type: default
@@ -140,9 +140,9 @@ nodes:
         description: "billing, technical, or general"
     edges:
       - target: billing_help
-        condition: "issue_type is billing"
+        label: "Issue is about billing"
       - target: tech_help
-        condition: "issue_type is technical"
+        label: "Issue is technical"
 
   billing_help:
     type: default
@@ -438,6 +438,8 @@ Add to your Claude Code config:
 
 | Tool | What it does |
 |------|-------------|
+| `bland_guide_list` | List all available guides (start here) |
+| `bland_guide_get` | Read a specific guide by slug |
 | `bland_call_send` | Make a phone call |
 | `bland_call_list` | List recent calls |
 | `bland_call_get` | Get call details and transcript |
@@ -455,6 +457,71 @@ Add to your Claude Code config:
 | `bland_knowledge_list` | List knowledge bases |
 | `bland_audio_generate` | Generate TTS audio |
 
+## For LLMs
+
+The CLI ships with a built-in guide system designed to give LLMs (Claude, Cursor, GPT, etc.) the context they need to build good pathways — not just call the API, but actually understand how phone conversations work.
+
+### How it works
+
+When an LLM connects via MCP, it receives:
+
+1. **`instructions`** — a condensed overview of the Bland platform, pathway architecture, common mistakes, and recommended workflow. This loads automatically on connect.
+2. **`bland_guide_list` / `bland_guide_get`** — tools to pull long-form guides on demand for deeper context.
+
+The guides are also available to humans via the CLI:
+
+```bash
+bland guide                  # List all guides
+bland guide phone-tone       # Writing natural phone prompts
+bland guide pathways         # Node/edge architecture and execution model
+bland guide tools            # Webhook and custom tools on nodes
+bland guide testing          # Chat, simulate, node tests
+bland guide variables        # Extracting and using caller data
+```
+
+### What the guides cover
+
+| Guide | What it teaches |
+|-------|----------------|
+| `phone-tone` | How to write prompts that sound like a real person on the phone — not a chatbot. Covers back-channeling, brevity, empathy, and topic transitions. |
+| `pathways` | How the conversation graph works: nodes, edges, global nodes, variables, the global prompt, and the execution model. |
+| `tools` | Attaching webhook and custom tools to nodes for real-time data (check availability, look up orders). Covers `speech`, `behavior`, and `response_data`. |
+| `testing` | The full testing workflow: `pathway chat` for interactive testing, `simulate` for end-to-end AI personas, `node-test` for stress-testing individual nodes. |
+| `variables` | Extracting structured data from natural conversation with `extract_variables`, using `{{curly_braces}}` in prompts, and `spelling_precision` for names/emails. |
+
+### Why this matters
+
+LLMs building pathways make predictable mistakes:
+- Writing edge labels as boolean conditions (`if intent == "booking"`) instead of natural language (`Caller wants to book an appointment`)
+- Making prompts too verbose and chat-like instead of concise and phone-natural
+- Forgetting global nodes for edge cases callers will absolutely hit
+- Not setting a global prompt for tone, so every node sounds different
+- Building without testing — the guides teach `pathway chat --verbose` first, real calls second
+
+The guide system fixes this by giving the LLM opinionated, Bland-specific knowledge before it starts writing. It's the difference between an LLM that can call the API and one that actually builds good phone agents.
+
+### Default phone tone
+
+When you scaffold a new pathway with `bland pathway init`, the global prompt comes pre-loaded with phone-tone instructions:
+
+```yaml
+global:
+  prompt: |
+    Sound natural and midwestern. Everything you say is spoken aloud on a phone call.
+    Play this game silently for every reply: what is the most accurate response,
+    then how can I reduce it to the fewest words without sounding rude?
+    Never recontextualize — no 'just to confirm', 'you said', 'got it'.
+    Use 'gotcha', 'yup', 'cool'.
+    Back-channel freely: 'mhmm', 'uh huh', 'right'.
+    Acknowledge emotions in stride.
+    Topic transitions are natural breaks — slightly more formal.
+    Within a topic, keep it tight.
+    After collecting one field, move immediately: 'And last?' not
+    'Could you also provide your last name?'
+```
+
+This sets the baseline voice for every node. LLMs using the MCP tools will also receive this guidance through the `phone-tone` guide.
+
 ## Local Webhook Development
 
 Forward Bland webhooks to your local dev server without ngrok:

package/dist/index.js

@@ -26,7 +26,7 @@ const program = new Command();
 program
     .name("bland")
     .description("The official Bland AI command-line interface")
-    .version("0.2.8");
+    .version("0.2.9");
 // Register all command groups
 registerAuthCommand(program);
 registerCallCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bland-cli",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "The official Bland AI command-line interface",
   "type": "module",
   "main": "dist/index.js",