@rubytech/taskmaster 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/taskmaster",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "AI-powered business assistant for small businesses",
   "publishConfig": {
     "access": "public"
@@ -195,7 +195,8 @@
   },
   "optionalDependencies": {
     "@napi-rs/canvas": "^0.1.88",
-    "node-llama-cpp": "3.15.0"
+    "node-llama-cpp": "3.15.0",
+    "sherpa-onnx-node": "^1.12.26"
   },
   "devDependencies": {
     "@grammyjs/types": "^3.23.0",

package/scripts/postinstall.js

@@ -311,6 +311,81 @@ function ensurePlatformDeps() {
   }
 }
 
+/**
+ * Download the sherpa-onnx speech recognition model for offline voice note
+ * transcription. Runs on global installs (deployed devices) and dev setups
+ * where sherpa-onnx-node is available. The model is platform-independent;
+ * only the native bindings (installed via npm optionalDeps) are platform-specific.
+ */
+function ensureSherpaOnnxModel() {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+  if (!homeDir) return;
+
+  const libDir = path.join(homeDir, ".taskmaster", "lib", "sherpa-onnx");
+  const modelDir = path.join(libDir, "nemo-ctc-en-conformer-small");
+  const modelFile = path.join(modelDir, "model.int8.onnx");
+  const tokensFile = path.join(modelDir, "tokens.txt");
+
+  // Already downloaded — nothing to do
+  if (fs.existsSync(modelFile) && fs.existsSync(tokensFile)) return;
+
+  // Only download if sherpa-onnx-node is installed (optional dep)
+  try {
+    const repoRoot = getRepoRoot();
+    const sherpaEntry = path.join(repoRoot, "node_modules", "sherpa-onnx-node");
+    if (!fs.existsSync(sherpaEntry)) return;
+  } catch {
+    return;
+  }
+
+  // Check that curl and tar are available (always true on macOS/Linux)
+  const hasCurl = spawnSync("curl", ["--version"], { stdio: "ignore" }).status === 0;
+  const hasTar = spawnSync("tar", ["--version"], { stdio: "ignore" }).status === 0;
+  if (!hasCurl || !hasTar) return;
+
+  const archiveUrl =
+    "https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-nemo-ctc-en-conformer-small.tar.bz2";
+  const archiveName = "nemo-ctc-en-conformer-small.tar.bz2";
+  const archivePath = path.join(libDir, archiveName);
+  const extractedDir = path.join(libDir, "sherpa-onnx-nemo-ctc-en-conformer-small");
+
+  console.log("[postinstall] Downloading sherpa-onnx speech recognition model…");
+  fs.mkdirSync(libDir, { recursive: true });
+
+  const curl = spawnSync("curl", ["-fsSL", "-o", archivePath, archiveUrl], {
+    stdio: "inherit",
+    timeout: 300_000,
+  });
+  if (curl.status !== 0) {
+    console.warn("[postinstall] sherpa-onnx model download failed (voice notes will use cloud STT)");
+    try { fs.unlinkSync(archivePath); } catch {}
+    return;
+  }
+
+  const tar = spawnSync("tar", ["-xjf", archivePath, "-C", libDir], {
+    stdio: "inherit",
+    timeout: 120_000,
+  });
+  if (tar.status !== 0) {
+    console.warn("[postinstall] sherpa-onnx model extraction failed (voice notes will use cloud STT)");
+    try { fs.unlinkSync(archivePath); } catch {}
+    return;
+  }
+
+  // Rename extracted directory (strip sherpa-onnx- prefix)
+  if (fs.existsSync(extractedDir) && extractedDir !== modelDir) {
+    try { fs.rmSync(modelDir, { recursive: true, force: true }); } catch {}
+    fs.renameSync(extractedDir, modelDir);
+  }
+
+  // Clean up: archive, full-precision model (keep int8), test wavs
+  try { fs.unlinkSync(archivePath); } catch {}
+  try { fs.unlinkSync(path.join(modelDir, "model.onnx")); } catch {}
+  try { fs.rmSync(path.join(modelDir, "test_wavs"), { recursive: true, force: true }); } catch {}
+
+  console.log("[postinstall] sherpa-onnx model installed (offline voice note transcription)");
+}
+
 function main() {
   const repoRoot = getRepoRoot();
   process.chdir(repoRoot);
@@ -318,6 +393,7 @@ function main() {
   ensureExecutable(path.join(repoRoot, "dist", "entry.js"));
   setupGitHooks({ repoRoot });
   ensurePlatformDeps();
+  ensureSherpaOnnxModel();
 
   if (!shouldApplyPnpmPatchedDependenciesFallback()) {
     return;

package/skills/business-assistant/references/crm.md

@@ -1,9 +1,33 @@
 # Customer Records (CRM)
 
+## Contacts as Source of Truth
+
+The **contact record** is the highest-level directory for every customer relationship. Its phone number and name are the canonical identifiers — all user-scoped data (memory profiles, conversations, documents, events) hangs off the contact via the phone number.
+
+| Concept | What it is | Storage |
+|---------|-----------|---------|
+| **Contact record** | Structured directory entry (phone, name, pipeline status, address) | `~/.taskmaster/records.json` via `contact_*` tools |
+| **User memory** | Freeform narrative, conversation history, media, documents | `memory/users/{phone}/` via `memory_*` tools |
+
+The contact record determines the relationship. User memory provides the detail. A memory profile without a contact record is orphaned data. A contact record without memory is a directory entry awaiting context.
+
 ## Tools
 
-- `contact_lookup` — Search by phone number or name. Use before every customer interaction.
-- `contact_update` — Update record fields. Use after every meaningful event.
+| Tool | Access | Purpose |
+|------|--------|---------|
+| `contact_create` | Admin only | Create a new contact record (phone + name + optional fields) |
+| `contact_lookup` | All agents | Search by phone number or name. Use before every customer interaction |
+| `contact_update` | Admin only | Update record fields or rename a contact. Use after every meaningful event |
+| `contact_delete` | Admin only | Remove a contact record. Does not delete user memory |
+
+### Creating a Contact Record vs Creating User Memory
+
+These are distinct operations:
+
+- **`contact_create`** — Creates a structured directory entry in the secure records store. Use when you have a name and phone number for a new customer.
+- **`memory_write` to `memory/users/{phone}/profile.md`** — Creates or updates the freeform narrative profile. Use to store context, personality, preferences, and history.
+
+On first meaningful interaction, do **both**: create the contact record, then write an initial memory profile.
 
 ## When to Create a Record
 
@@ -26,7 +50,7 @@ Update the contact record after every event that changes the customer's status o
 
 | Field | Description | Example |
 |-------|-------------|---------|
-| `name` | Full name | `Mrs Sarah Jenkins` |
+| `name` | Full name (set via `contact_create`, update via `contact_update` with field `name`) | `Mrs Sarah Jenkins` |
 | `status` | Pipeline stage | `enquiry`, `quoted`, `booked`, `completed`, `invoiced`, `paid`, `archived` |
 | `address` | Full postal address | `42 Oak Lane, Stansted, CM23 4AB` |
 | `postcode` | Extracted postcode (for geographic clustering) | `CM23 4AB` |
@@ -53,15 +77,15 @@ enquiry → quoted → booked → completed → invoiced → paid
 
 Update the status at each transition. This enables the business owner to see their pipeline at a glance.
 
-## Memory vs Records
+## Contact Records vs User Memory
 
 Contact records and memory serve different purposes. Use both.
 
-| | Contact Records | Memory |
+| | Contact Records | User Memory |
 |---|---|---|
-| **Store** | `contact_lookup` / `contact_update` | `memory/users/{phone}/profile.md` |
+| **Store** | `contact_create` / `contact_update` / `contact_lookup` | `memory/users/{phone}/profile.md` |
 | **Structure** | Key-value fields (name, status, address, etc.) | Freeform narrative |
-| **Purpose** | Pipeline tracking, structured queries | Context, personality, history |
+| **Purpose** | Directory entry, pipeline tracking, structured queries | Context, personality, history |
 | **Example** | `status: invoiced`, `postcode: CM23 4AB` | "Mrs Jenkins is elderly, lives alone, prefers morning appointments. She had a boiler service last month and was very happy with the work." |
 
 When searching for a customer, check **both**: `contact_lookup` for structured data, `memory_search` for context.
@@ -72,6 +96,6 @@ Customer documents are filed at `memory/users/{phone}/documents/`. The phone num
 
 When creating documents for a customer, always:
 1. Verify the contact record exists (`contact_lookup`)
-2. Create or update the record if needed (`contact_update`)
+2. Create the record if needed (`contact_create`) or update it (`contact_update`)
 3. File the document in the correct path
 4. Update the contact record status

package/taskmaster-docs/USER-GUIDE.md

@@ -171,6 +171,8 @@ The very first time you open the dashboard, you'll be asked to **set a PIN** (4-
 
 When you return, a login screen asks for your PIN. If you have multiple accounts, pick the account you want to operate on from the dropdown and enter the account PIN (this is different to the admin PIN). If you log into the admin account, you have access to all the other registered accounts.
 
+Each PIN field has an **eye icon** on the right — tap it to reveal the PIN digits so you can check what you've typed. Tap again to hide them.
+
 ### Account PINs
 
 If you share your device with other people (e.g. a business partner who manages a different account), each account can have its own PIN:
@@ -238,6 +240,15 @@ You can send files to your assistant by dragging and dropping them onto the chat
 
 **Via WhatsApp** you can also send **voice notes** and **videos** — these are automatically transcribed or analysed before your assistant sees them (see "Voice Notes & Video" below).
 
+### Voice Notes (Chat Page)
+
+You can record and send voice notes directly from the Chat page. When the message box is empty, a microphone button appears in place of the send button.
+
+- **Tap** the microphone to start recording. A recording indicator with a timer appears. Tap the **send button** to send, or the **trash button** to discard.
+- **Press and hold** the microphone to record hands-free. Release to send automatically, or slide left to cancel.
+
+Your assistant transcribes the voice note and responds to the content, the same as a WhatsApp voice note.
+
 ### Sending Messages While the Assistant is Working
 
 If your assistant is busy thinking, you can still type and send more messages. They appear immediately in the chat as normal messages and are delivered to your assistant in order once it finishes its current task.
@@ -289,12 +300,16 @@ The Files page shows a **status indicator** next to the Re-index button — a gr
 | Search knowledge | Find information across all your business files and notes |
 | Read files | Open and read any file in your workspace |
 | Write and update files | Create new notes, update existing files, or reorganise content |
+| List files and folders | Browse what's in any workspace directory |
+| Delete files and folders | Remove files or folders you no longer need (protected paths like agents/ cannot be deleted) |
 | Save photos | Store images to customer folders or your workspace |
 
 **Try asking:**
 - "What's our pricing for a full bathroom refit?"
 - "Save a note that Mrs. Jones prefers morning appointments"
 - "What do we know about the customer on +44 7700 900123?"
+- "List what's in memory/users"
+- "Delete the file memory/public/old-pricelist.md"
 
 ### Web Search
 
@@ -310,6 +325,21 @@ Your assistant can search the web and read web pages to find information for you
 - "What are the opening hours for Travis Perkins in Bromley?"
 - "Read this page and summarise it: https://example.com/article"
 
+### Weather
+
+Your assistant can check the weather for any location — current conditions, forecasts, humidity, wind, and more. No API key is needed.
+
+| Capability | Description |
+|------------|-------------|
+| Current conditions | Temperature, weather conditions, humidity, and wind speed for any city |
+| Forecasts | Multi-day weather forecasts for planning ahead |
+| Any location | Look up weather by city name, airport code, or coordinates |
+
+**Try asking:**
+- "What's the weather like in London?"
+- "Will it rain tomorrow in Manchester?"
+- "What's the forecast for this week?"
+
 ### Images & Documents
 
 Your assistant can analyse photos you send it and read common document formats.
@@ -354,7 +384,7 @@ When someone sends a voice note, image, or video, your assistant processes it au
 | Images | Automatically described — your assistant sees what's in the picture |
 | Video | Key frames extracted and described — your assistant understands the content |
 
-Voice note transcription and video analysis require a Google AI (Gemini) API key (see API Keys below). Image analysis uses your Claude connection directly — no extra key needed.
+Voice note transcription works out of the box — Taskmaster includes a built-in offline speech recognition model that runs locally on your device with no API key required. For higher accuracy or video analysis, add a Google AI (Gemini) API key (see API Keys below). Image analysis uses your Claude connection directly — no extra key needed.
 
 ### Customer Records
 
@@ -466,6 +496,23 @@ Your assistant can open and interact with websites in a built-in browser — fil
 
 > **Tip:** Keep the Browser page open while your assistant browses — you can see exactly what it's doing and step in if a site asks for a CAPTCHA or login.
 
+### Business Idea Validation
+
+Thinking about a new product, service, or direction for your business? Your assistant can walk you through the process of validating the idea before you invest time and money — from initial concept through customer discovery and assumption testing to a clear product brief.
+
+| Phase | What happens |
+|-------|-------------|
+| Discovery | Clarify your idea, define your target customer, plan customer conversations, and assess the market |
+| Validation | Identify the riskiest assumptions in your idea and design quick tests to check them |
+| Product brief | Turn the validated concept into a clear document — problem, audience, features, success metrics, and next steps |
+
+Your assistant guides you through each phase conversationally — you don't need to know any frameworks or jargon. Just describe your idea and it will ask the right questions.
+
+**Try asking:**
+- "I have an idea for a new service — can you help me think it through?"
+- "Help me validate whether this product idea is worth pursuing"
+- "I want to write a product brief for a new offering"
+
 ---
 
 ### API Keys
@@ -496,16 +543,17 @@ Additional keys for advanced use cases:
 |----------|----------------|------------|
 | **Brave** | Web search — alternative to Tavily | Yes (free plan available) |
 | **OpenAI** | Voice note transcription, alternative AI models | No |
-| **ElevenLabs** | Text-to-speech (for future voice features) | Yes (limited free tier) |
+| **ElevenLabs** | Text-to-speech voice replies | Yes (limited free tier) |
 | **Replicate** | Image and media AI models | No |
-| **Hume** | Voice and emotion AI | No |
+| **Hume** | Text-to-speech voice replies (expressive voice) | Yes |
 
 #### Managing Keys
 
 1. Go to the **Setup** page
 2. Click on the **API Keys** row in the status dashboard
 3. Enter a key next to any provider and click **Save**
-4. To remove a key, click **Remove** next to it
+4. To temporarily turn off a key without losing it, click the **power icon** next to it — the row dims and the key stops being used. Click the power icon again to re-enable it.
+5. To permanently remove a key, click the **trash icon** next to it
 
 #### Recommended Free Keys
 
@@ -533,7 +581,7 @@ You get 1,000 free search credits per month — more than enough for daily busin
 4. **Copy the key** (it starts with `AIza`)
 5. Go to your Taskmaster **Setup** page, click the **API Keys** row, find **Google**, paste the key, and click **Save**
 
-The free tier works for low-volume use (a handful of voice notes or images per day). For higher volumes, you'll need to enable billing in your Google Cloud account — see [Google AI pricing](https://ai.google.dev/pricing) for details.
+Voice notes work without this key (using the built-in offline model), but adding a Google key enables higher-accuracy cloud transcription and video analysis. The free tier works for low-volume use (a handful of voice notes or images per day). For higher volumes, you'll need to enable billing in your Google Cloud account — see [Google AI pricing](https://ai.google.dev/pricing) for details.
 
 ---
 
@@ -1381,6 +1429,31 @@ You can control your assistant's behaviour by typing slash commands in any conve
 | `/activation always` | Make the assistant respond to every group message (not just @mentions) |
 | `/activation mention` | Make the assistant only respond when @mentioned in groups |
 
+### Voice replies (Text-to-Speech)
+
+Your assistant can reply with voice notes instead of text. Two providers are available out of the box:
+
+| Provider | Requires API key? | Notes |
+|----------|------------------|-------|
+| **Edge** (Microsoft) | No — free, works immediately | Good quality neural voices, many languages |
+| **Hume** | Yes — add in Setup > API Keys | Expressive, emotionally-aware voice (Octave TTS) |
+
+Voice replies are controlled with the `/tts` command:
+
+| Command | What it does |
+|---------|-------------|
+| `/tts` | Show current TTS status and available providers |
+| `/tts always` | Every reply is sent as a voice note |
+| `/tts inbound` | Reply with voice only when you send a voice note |
+| `/tts off` | Turn off voice replies |
+| `/tts provider edge` | Use Microsoft Edge TTS (free, no key needed) |
+| `/tts provider hume` | Use Hume Octave TTS (requires Hume API key) |
+| `/tts status` | Show current mode, provider, and fallback chain |
+
+**How it works:** When TTS is enabled, the assistant writes its reply as normal text, and the system automatically converts it to a voice note before sending. If the selected provider fails (e.g. missing API key), it falls back to the next available provider. Emojis are automatically stripped so they don't get read aloud.
+
+**Quick start:** Just type `/tts always` — Edge TTS will work immediately with no setup. To upgrade to Hume's expressive voice, add a Hume API key in the Control Panel and type `/tts provider hume`.
+
 ### Examples
 
 > **You:** `/filler`
@@ -1392,6 +1465,12 @@ You can control your assistant's behaviour by typing slash commands in any conve
 > **You:** `/think high`
 > **System:** Thinking level set to high.
 
+> **You:** `/tts always`
+> **System:** TTS mode set to always.
+
+> **You:** `/tts provider hume`
+> **System:** TTS provider set to hume (fallbacks: edge).
+
 ---
 
 ## Groups

package/templates/beagle/agents/admin/AGENTS.md

@@ -80,11 +80,13 @@ stripe refunds create --payment-intent {pi_id}
 
 ## Customer Record Management
 
-You have write access to customer records (`contact_update`). Use this for:
+You have full access to customer records (`contact_create`, `contact_update`, `contact_delete`). Use this for:
+- Creating contact records on first meaningful interaction
 - Updating trust scores after job completion
 - Setting blacklist status after fee escalation
 - Reinstating customers after payment
 - Recording provider opt-out/opt-in
+- Deleting records for data erasure requests
 
 The public agent (Beagle) can read records but cannot modify them — this prevents prompt injection from changing payment status.
 
@@ -93,7 +95,7 @@ The public agent (Beagle) can read records but cannot modify them — this preve
 ## Data Compliance (Admin-Side Execution)
 
 When the Beagle agent receives a data erasure request, you execute the deletion sequence:
-1. Delete the customer record (`contact_update` with DELETE)
+1. Delete the customer record (`contact_delete`)
 2. Clear the memory profile
 3. Redact booking files (replace customer phone/name with [REDACTED])
 4. Delete member files from booking groups

package/templates/taskmaster/agents/admin/AGENTS.md

@@ -106,6 +106,7 @@ You have tool access within your workspace:
 - Session management
 - Config commands
 - File system access (within workspace)
+- **Contact management** — `contact_create`, `contact_lookup`, `contact_update`, `contact_delete` (see skill reference `references/crm.md`)
 - **Document reading** — use `document_read` to extract text from PDFs, DOCX, XLSX, PPTX files
 - **Message relay** — use `relay_message` to inject a missed WhatsApp message into the public agent's session (see below)