@rubytech/taskmaster 1.0.42 → 1.0.44

package/dist/gateway/server-methods/apikeys.js

@@ -14,12 +14,12 @@ import { readConfigFileSnapshot, writeConfigFile } from "../../config/config.js"
 import { ErrorCodes, errorShape } from "../protocol/index.js";
 import { formatForLog } from "../ws-log.js";
 const PROVIDER_CATALOG = [
-    { id: "anthropic", name: "Anthropic", category: "AI Model" },
+    { id: "anthropic", name: "Anthropic", category: "AI Model", primary: true },
+    { id: "google", name: "Google", category: "Voice & Video", primary: true },
+    { id: "tavily", name: "Tavily", category: "Web Search", primary: true },
     { id: "openai", name: "OpenAI", category: "AI Model" },
-    { id: "google", name: "Google", category: "AI Model" },
     { id: "replicate", name: "Replicate", category: "AI Model" },
     { id: "hume", name: "Hume", category: "Voice" },
-    { id: "tavily", name: "Tavily", category: "Web Search" },
     { id: "brave", name: "Brave", category: "Web Search" },
     { id: "elevenlabs", name: "ElevenLabs", category: "Voice" },
 ];

package/dist/gateway/server.impl.js

@@ -1,6 +1,7 @@
 import { listAgentIds, resolveAgentWorkspaceDir, resolveDefaultAgentId, } from "../agents/agent-scope.js";
 import { initSubagentRegistry } from "../agents/subagent-registry.js";
-import { registerSkillsChangeListener } from "../agents/skills/refresh.js";
+import { bumpSkillsSnapshotVersion, registerSkillsChangeListener, } from "../agents/skills/refresh.js";
+import { syncBundledSkillsToWorkspace } from "../agents/skills/workspace.js";
 import { listChannelPlugins } from "../channels/plugins/index.js";
 import { createDefaultDeps } from "../cli/deps.js";
 import { formatCliCommand } from "../cli/command-format.js";
@@ -146,6 +147,36 @@ export async function startGatewayServer(port = 18789, opts = {}) {
     initSubagentRegistry();
     const defaultAgentId = resolveDefaultAgentId(cfgAtStart);
     const defaultWorkspaceDir = resolveAgentWorkspaceDir(cfgAtStart, defaultAgentId);
+    // Sync bundled skills to each workspace root (new skills only, never overwrites).
+    // Agent workspace dirs may point to subdirs (e.g. ~/taskmaster/agents/public);
+    // skills/ lives at the root (e.g. ~/taskmaster/skills/), so strip /agents/{id}.
+    {
+        const roots = new Set();
+        for (const agentId of listAgentIds(cfgAtStart)) {
+            const agentWs = resolveAgentWorkspaceDir(cfgAtStart, agentId);
+            const rootMatch = agentWs.replace(/\/+$/, "").match(/^(.+)\/agents\/[^/]+$/);
+            roots.add(rootMatch ? rootMatch[1] : agentWs);
+        }
+        let anySynced = false;
+        for (const root of roots) {
+            try {
+                const { synced } = await syncBundledSkillsToWorkspace(root);
+                if (synced.length > 0) {
+                    anySynced = true;
+                    log.info(`synced bundled skills to ${root}: ${synced.join(", ")}`);
+                }
+            }
+            catch (err) {
+                log.warn(`failed to sync bundled skills to ${root}: ${String(err)}`);
+            }
+        }
+        // Force existing sessions to rebuild their skills snapshot on the next message.
+        // Without this, sessions from a previous boot keep stale snapshots because
+        // their version (a high timestamp) exceeds the post-restart globalVersion (1).
+        if (anySynced) {
+            bumpSkillsSnapshotVersion({ reason: "manual" });
+        }
+    }
     const baseMethods = listGatewayMethods();
     const { pluginRegistry, gatewayMethods: baseGatewayMethods } = loadGatewayPlugins({
         cfg: cfgAtStart,

package/dist/memory/manager.js

@@ -140,6 +140,34 @@ function isPathAllowedByScope(relPath, scope, ctx, operation = "read") {
     // Read uses read scope
     return checkPatterns(relPath, scope.read, ctx);
 }
+/**
+ * Check if a file path could ever be accessible under any session context.
+ * Used during indexing where no peer/channel context is available.
+ * Template placeholders ({peer}, {channel}, {agentId}) are expanded to wildcards
+ * so that files reachable by any peer are still indexed.
+ */
+function isPathIndexableByScope(relPath, scope) {
+    if (!scope)
+        return true;
+    const patterns = scope.read;
+    if (!patterns)
+        return true;
+    const { include, exclude } = patterns;
+    if (!include || include.length === 0)
+        return true;
+    // Expand template variables to wildcards — any peer could connect
+    const expandTemplates = (p) => p.replaceAll("{peer}", "*").replaceAll("{channel}", "*").replaceAll("{agentId}", "*");
+    const matchesInclude = include.some((p) => matchGlobPattern(expandTemplates(p), relPath));
+    if (!matchesInclude)
+        return false;
+    // Only apply static excludes (no templates) — template excludes are session-specific
+    if (exclude && exclude.length > 0) {
+        const staticExcludes = exclude.filter((p) => !p.includes("{"));
+        if (staticExcludes.some((p) => matchGlobPattern(p, relPath)))
+            return false;
+    }
+    return true;
+}
 /**
  * Check if a DM peer has virtual group membership for a given group path.
  * If the path is inside memory/groups/{groupId}/ and a member file exists
@@ -1137,7 +1165,15 @@ export class MemoryIndexManager {
     }
     async syncMemoryFiles(params) {
         const files = await listMemoryFiles(this.workspaceDir);
-        const fileEntries = await Promise.all(files.map(async (file) => buildFileEntry(file, this.workspaceDir)));
+        const allEntries = await Promise.all(files.map(async (file) => buildFileEntry(file, this.workspaceDir)));
+        // Filter to files this agent's scope can access — prevents cross-agent indexing
+        const scope = this.settings.scope;
+        const fileEntries = scope
+            ? allEntries.filter((entry) => isPathIndexableByScope(entry.path, scope))
+            : allEntries;
+        if (scope && fileEntries.length < allEntries.length) {
+            log.debug(`memory sync: scope filtered ${allEntries.length - fileEntries.length} files for ${this.agentId}`);
+        }
         log.debug("memory sync: indexing memory files", {
             files: fileEntries.length,
             needsFullReindex: params.needsFullReindex,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/taskmaster",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "description": "AI-powered business assistant for small businesses",
   "publishConfig": {
     "access": "public"
@@ -77,66 +77,12 @@
     "dist/filler/**",
     "dist/license/**"
   ],
-  "scripts": {
-    "dev": "node scripts/run-node.mjs",
-    "postinstall": "node scripts/postinstall.js",
-    "prepack": "pnpm build && pnpm ui:build",
-    "docs:list": "node scripts/docs-list.js",
-    "docs:bin": "node scripts/build-docs-list.mjs",
-    "docs:dev": "cd docs && mint dev",
-    "docs:build": "cd docs && pnpm dlx --reporter append-only mint broken-links",
-    "build": "tsc -p tsconfig.json && node --import tsx scripts/canvas-a2ui-copy.ts && node --import tsx scripts/copy-hook-metadata.ts && node --import tsx scripts/write-build-info.ts",
-    "plugins:sync": "node --import tsx scripts/sync-plugin-versions.ts",
-    "release:check": "node --import tsx scripts/release-check.ts",
-    "ui:install": "node scripts/ui.js install",
-    "ui:dev": "node scripts/ui.js dev",
-    "ui:build": "node scripts/ui.js build",
-    "start": "node scripts/run-node.mjs",
-    "taskmaster": "node scripts/run-node.mjs",
-    "gateway:watch": "node scripts/watch-node.mjs gateway --force",
-    "logs": "npx tsx scripts/session-viewer.ts",
-    "gateway:dev": "TASKMASTER_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway",
-    "gateway:dev:reset": "TASKMASTER_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway --reset",
-    "tui": "node scripts/run-node.mjs tui",
-    "tui:dev": "TASKMASTER_PROFILE=dev node scripts/run-node.mjs tui",
-    "taskmaster:rpc": "node scripts/run-node.mjs agent --mode rpc --json",
-    "lint": "oxlint --type-aware src test",
-    "lint:fix": "pnpm format:fix && oxlint --type-aware --fix src test",
-    "format": "oxfmt --check src test",
-    "format:fix": "oxfmt --write src test",
-    "test": "node scripts/test-parallel.mjs",
-    "test:watch": "vitest",
-    "test:ui": "pnpm --dir ui test",
-    "test:force": "node --import tsx scripts/test-force.ts",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "test:live": "TASKMASTER_LIVE_TEST=1 vitest run --config vitest.live.config.ts",
-    "test:docker:onboard": "bash scripts/e2e/onboard-docker.sh",
-    "test:docker:gateway-network": "bash scripts/e2e/gateway-network-docker.sh",
-    "test:docker:live-models": "bash scripts/test-live-models-docker.sh",
-    "test:docker:live-gateway": "bash scripts/test-live-gateway-models-docker.sh",
-    "test:docker:qr": "bash scripts/e2e/qr-import-docker.sh",
-    "test:docker:doctor-switch": "bash scripts/e2e/doctor-install-switch-docker.sh",
-    "test:docker:plugins": "bash scripts/e2e/plugins-docker.sh",
-    "test:docker:cleanup": "bash scripts/test-cleanup-docker.sh",
-    "test:docker:all": "pnpm test:docker:live-models && pnpm test:docker:live-gateway && pnpm test:docker:onboard && pnpm test:docker:gateway-network && pnpm test:docker:qr && pnpm test:docker:doctor-switch && pnpm test:docker:plugins && pnpm test:docker:cleanup",
-    "test:all": "pnpm lint && pnpm build && pnpm test && pnpm test:e2e && pnpm test:live && pnpm test:docker:all",
-    "test:install:e2e": "bash scripts/test-install-sh-e2e-docker.sh",
-    "test:install:smoke": "bash scripts/test-install-sh-docker.sh",
-    "test:install:e2e:openai": "TASKMASTER_E2E_MODELS=openai bash scripts/test-install-sh-e2e-docker.sh",
-    "test:install:e2e:anthropic": "TASKMASTER_E2E_MODELS=anthropic bash scripts/test-install-sh-e2e-docker.sh",
-    "protocol:gen": "node --import tsx scripts/protocol-gen.ts",
-    "protocol:check": "pnpm protocol:gen && git diff --exit-code -- dist/protocol.schema.json",
-    "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh",
-    "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500"
-  },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "engines": {
     "node": ">=22.12.0"
   },
-  "packageManager": "pnpm@10.23.0",
   "dependencies": {
     "@agentclientprotocol/sdk": "0.13.1",
     "@aws-sdk/client-bedrock": "^3.975.0",
@@ -226,14 +172,6 @@
     "vitest": "^4.0.18",
     "wireit": "^0.14.12"
   },
-  "pnpm": {
-    "minimumReleaseAge": 2880,
-    "overrides": {
-      "@sinclair/typebox": "0.34.47",
-      "hono": "4.11.4",
-      "tar": "7.5.4"
-    }
-  },
   "vitest": {
     "coverage": {
       "provider": "v8",
@@ -262,5 +200,57 @@
       "**/vendor/**",
       "dist/Taskmaster.app/**"
     ]
+  },
+  "scripts": {
+    "dev": "node scripts/run-node.mjs",
+    "postinstall": "node scripts/postinstall.js",
+    "docs:list": "node scripts/docs-list.js",
+    "docs:bin": "node scripts/build-docs-list.mjs",
+    "docs:dev": "cd docs && mint dev",
+    "docs:build": "cd docs && pnpm dlx --reporter append-only mint broken-links",
+    "build": "tsc -p tsconfig.json && node --import tsx scripts/canvas-a2ui-copy.ts && node --import tsx scripts/copy-hook-metadata.ts && node --import tsx scripts/write-build-info.ts",
+    "plugins:sync": "node --import tsx scripts/sync-plugin-versions.ts",
+    "release:check": "node --import tsx scripts/release-check.ts",
+    "ui:install": "node scripts/ui.js install",
+    "ui:dev": "node scripts/ui.js dev",
+    "ui:build": "node scripts/ui.js build",
+    "start": "node scripts/run-node.mjs",
+    "taskmaster": "node scripts/run-node.mjs",
+    "gateway:watch": "node scripts/watch-node.mjs gateway --force",
+    "logs": "npx tsx scripts/session-viewer.ts",
+    "gateway:dev": "TASKMASTER_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway",
+    "gateway:dev:reset": "TASKMASTER_SKIP_CHANNELS=1 node scripts/run-node.mjs --dev gateway --reset",
+    "tui": "node scripts/run-node.mjs tui",
+    "tui:dev": "TASKMASTER_PROFILE=dev node scripts/run-node.mjs tui",
+    "taskmaster:rpc": "node scripts/run-node.mjs agent --mode rpc --json",
+    "lint": "oxlint --type-aware src test",
+    "lint:fix": "pnpm format:fix && oxlint --type-aware --fix src test",
+    "format": "oxfmt --check src test",
+    "format:fix": "oxfmt --write src test",
+    "test": "node scripts/test-parallel.mjs",
+    "test:watch": "vitest",
+    "test:ui": "pnpm --dir ui test",
+    "test:force": "node --import tsx scripts/test-force.ts",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:live": "TASKMASTER_LIVE_TEST=1 vitest run --config vitest.live.config.ts",
+    "test:docker:onboard": "bash scripts/e2e/onboard-docker.sh",
+    "test:docker:gateway-network": "bash scripts/e2e/gateway-network-docker.sh",
+    "test:docker:live-models": "bash scripts/test-live-models-docker.sh",
+    "test:docker:live-gateway": "bash scripts/test-live-gateway-models-docker.sh",
+    "test:docker:qr": "bash scripts/e2e/qr-import-docker.sh",
+    "test:docker:doctor-switch": "bash scripts/e2e/doctor-install-switch-docker.sh",
+    "test:docker:plugins": "bash scripts/e2e/plugins-docker.sh",
+    "test:docker:cleanup": "bash scripts/test-cleanup-docker.sh",
+    "test:docker:all": "pnpm test:docker:live-models && pnpm test:docker:live-gateway && pnpm test:docker:onboard && pnpm test:docker:gateway-network && pnpm test:docker:qr && pnpm test:docker:doctor-switch && pnpm test:docker:plugins && pnpm test:docker:cleanup",
+    "test:all": "pnpm lint && pnpm build && pnpm test && pnpm test:e2e && pnpm test:live && pnpm test:docker:all",
+    "test:install:e2e": "bash scripts/test-install-sh-e2e-docker.sh",
+    "test:install:smoke": "bash scripts/test-install-sh-docker.sh",
+    "test:install:e2e:openai": "TASKMASTER_E2E_MODELS=openai bash scripts/test-install-sh-e2e-docker.sh",
+    "test:install:e2e:anthropic": "TASKMASTER_E2E_MODELS=anthropic bash scripts/test-install-sh-e2e-docker.sh",
+    "protocol:gen": "node --import tsx scripts/protocol-gen.ts",
+    "protocol:check": "pnpm protocol:gen && git diff --exit-code -- dist/protocol.schema.json",
+    "canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh",
+    "check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500"
   }
-}
+}

package/skills/google-ai/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: google-ai
+description: Help users get a free Google AI (Gemini) API key via browser automation.
+metadata: {"taskmaster":{"emoji":"🔑"}}
+---
+
+# Google AI Setup
+
+Guides users through obtaining a Google AI (Gemini) API key using browser automation, with real-time screenshots sent via WhatsApp so the user can see what's happening.
+
+## When to activate
+
+- BOOTSTRAP detects missing Google/Gemini API key
+- User needs voice note transcription or video analysis
+- User asks for help getting a Google AI key
+
+## What it unlocks
+
+- Voice note transcription (audio to text)
+- Video analysis (key frame extraction + description)
+- Free tier with generous monthly quota, no credit card required
+
+## References
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Browser-assisted setup | User wants help getting the key | `references/browser-setup.md` |
+
+Load the reference and follow its instructions. Send screenshots at each step so the user can see progress.

package/skills/google-ai/references/browser-setup.md

@@ -0,0 +1,90 @@
+# Google AI API Key — Browser Setup
+
+Step-by-step browser automation to obtain a Google AI (Gemini) API key. Send screenshots at each step so the user can follow along.
+
+---
+
+## Prerequisites
+
+- User has a Google account (Gmail or business email)
+- Browser tool available
+- WhatsApp or chat channel for sending screenshots
+
+---
+
+## Step 1: Explain
+
+Tell the user what you're doing and why:
+
+> "I need a Google AI key so I can understand voice notes and videos you send me. Let me get you a free one — I'll do it in the browser and show you what's happening."
+
+Ask which Google account to use. If they don't have one, guide them to accounts.google.com first.
+
+## Step 2: Open Google AI Studio
+
+Navigate to `https://aistudio.google.com` and take a screenshot. Send it to the user.
+
+## Step 3: Sign in (if needed)
+
+If a login page appears:
+
+1. Tell the user you see the sign-in page
+2. Enter their email address
+3. Ask the user for their password — type it and continue
+4. If 2FA is required, ask the user to complete it on their device, then continue
+5. Screenshot after login
+
+## Step 4: Navigate to API Keys
+
+Navigate to `https://aistudio.google.com/api-keys` and take a screenshot. Send it: "Here's your API keys dashboard."
+
+## Step 5: Get the key
+
+Take a snapshot and check the page content.
+
+**If a key already exists in the table:**
+- Click the key name to view details
+- Copy the key from the modal (starts with `AIza`, ~39 characters)
+- Screenshot: "You already have a key — I've grabbed it."
+
+**If no key exists:**
+- Click "Create API key"
+- Follow any prompts (usually instant)
+- Copy the new key
+- Screenshot: "Created a new key for you."
+
+## Step 6: Add to Taskmaster
+
+Tell the user how to add the key:
+
+> "Open your browser and go to your Taskmaster setup page.
+>
+> 1. Click **'Manage'** in the API Keys section
+> 2. Find the **Google** row (says 'Voice & Video')
+> 3. Paste your key into the field
+> 4. Click **Save**
+>
+> Let me know when it's done and I'll test it!"
+
+## Step 7: Confirm
+
+Once the user confirms the key is saved:
+
+> "Google AI is now enabled. You can send me voice notes and videos — I'll understand them both."
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Sign-in fails / 2FA required | Ask user to complete 2FA on their device |
+| "Enable API" prompt appears | Click the enable button, wait, proceed |
+| Key exists but not visible | Navigate to the key via table, click to reveal |
+| Browser automation fails | Fall back to manual: "Can you go to aistudio.google.com and..." |
+
+## What the user gets
+
+- Free tier: image analysis, video analysis, audio transcription
+- Generous monthly quota sufficient for small business use
+- No credit card required

package/skills/tavily/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: tavily
+description: Help users get a free Tavily API key for web search via browser automation.
+metadata: {"taskmaster":{"emoji":"🔑"}}
+---
+
+# Tavily Setup
+
+Guides users through obtaining a Tavily API key using browser automation, with real-time screenshots sent via WhatsApp so the user can see what's happening.
+
+## When to activate
+
+- BOOTSTRAP detects missing Tavily API key
+- User needs web search capabilities
+- User asks for help getting a Tavily key
+
+## What it unlocks
+
+- Web search (look up prices, suppliers, regulations, opening hours)
+- 1,000 free search credits per month, no credit card required
+
+## References
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Browser-assisted setup | User wants help getting the key | `references/browser-setup.md` |
+
+Load the reference and follow its instructions. Send screenshots at each step so the user can see progress.

package/skills/tavily/references/browser-setup.md

@@ -0,0 +1,100 @@
+# Tavily API Key — Browser Setup
+
+Step-by-step browser automation to obtain a Tavily API key. Send screenshots at each step so the user can follow along.
+
+---
+
+## Prerequisites
+
+- User has a Google account (ideally the same one used for Google AI setup)
+- Browser tool available
+- WhatsApp or chat channel for sending screenshots
+
+---
+
+## Step 1: Explain
+
+Tell the user what you're doing and why:
+
+> "I need web search so I can look things up for you — prices, suppliers, your website, anything online. Let me get you a free Tavily key. Takes about 2 minutes."
+
+## Step 2: Open Tavily
+
+Navigate to `https://app.tavily.com` and take a screenshot. Send it to the user.
+
+## Step 3: Sign up via Google OAuth (preferred)
+
+Google OAuth avoids CAPTCHAs — always try this first.
+
+1. Take a snapshot and find the "Continue with Google" button
+2. Click it and screenshot
+3. If multiple Google accounts appear, select the one used for Google AI setup
+4. Grant permissions when the consent screen appears
+5. Screenshot at each stage
+
+## Step 4: Dismiss modals
+
+After signup, modals may appear ("Stay updated", "Welcome"). Close or skip each one.
+
+## Step 5: Extract the API key
+
+Take a snapshot of the dashboard.
+
+- Find the API key in the table (starts with `tvly-`, ~40 characters)
+- If the key is masked, click the eye icon to reveal it
+- Screenshot: "Here's your Tavily dashboard. Copying your API key..."
+- Copy the key value
+
+## Step 6: Add to Taskmaster
+
+Tell the user how to add the key:
+
+> "Open your browser and go to your Taskmaster setup page.
+>
+> 1. Click **'Manage'** in the API Keys section
+> 2. Find the **Tavily** row (says 'Web Search')
+> 3. Paste your key into the field
+> 4. Click **Save**
+>
+> Let me know when it's done and I'll test it!"
+
+## Step 7: Confirm
+
+Once the user confirms the key is saved:
+
+> "Web search is now enabled. Try asking me to look something up — 'What's the price of 15mm copper pipe?' or 'Search for the best coffee machines.'"
+
+---
+
+## Alternative: Email signup (if Google OAuth fails)
+
+Use only if the user refuses Google account or OAuth fails.
+
+1. Navigate to app.tavily.com and click "Sign up"
+2. Enter the user's email address
+3. **Stop at the CAPTCHA** — screenshot it and send to the user
+4. Ask: "What's the code shown in the image?"
+5. Enter the code and submit
+6. Ask the user to check their email for a verification link
+7. Once verified, sign in and extract the API key from the dashboard
+
+**Common issues with email signup:**
+- CAPTCHA wrong — refresh page, get new CAPTCHA, try again
+- Email not arriving — check spam, wait 5 minutes, resend
+- Verification link expired — request new one from Tavily login page
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Already logged in from a previous session | Extract the key directly from the dashboard |
+| "Account already exists" | Switch to login flow, sign in, extract key |
+| Browser stuck or page won't load | Fall back to manual: "Can you go to app.tavily.com and..." |
+
+## What the user gets
+
+- Free tier: 1,000 search credits per month
+- Sufficient for small business onboarding and daily use
+- No credit card required

package/taskmaster-docs/USER-GUIDE.md

@@ -328,7 +328,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 API keys (see API Keys below). Image descriptions use your Claude connection.
+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.
 
 ### Customer Records
 
@@ -427,7 +427,7 @@ Your assistant can open and interact with websites in a built-in browser — fil
 | Complete multi-step tasks | Navigate through checkout flows, registration pages, or dashboards |
 
 **Try asking:**
-- "Sign up for a free Brave Search API key for me"
+- "Help me get a free Tavily API key"
 - "Go to the Travis Perkins website and find the price of 15mm copper pipe"
 - "Log into my supplier portal and check my order status"
 
@@ -448,13 +448,20 @@ During setup, you connect to Claude in one of two ways:
 
 #### Optional API Keys
 
-These unlock additional capabilities. All are optional — your assistant works without them.
+These unlock additional capabilities. All are optional — your assistant works without them. The Setup page shows the recommended keys prominently, with additional keys available under "Additional keys".
 
 | Provider | What it unlocks | Free tier? |
 |----------|----------------|------------|
-| **Brave** | Web search — lets your assistant search the internet | Yes (free plan available) |
-| **Tavily** | Web search — alternative search provider | Yes (free plan available) |
-| **Google** | Voice note transcription, video analysis, alternative AI models | Yes (limited free tier) |
+| **Tavily** | Web search — lets your assistant search the internet | Yes (free plan available) |
+| **Google** | Voice note transcription and video analysis | Yes (limited free tier) |
+
+> **Note:** Image analysis does not need an extra API key — Claude has built-in vision and analyses images directly.
+
+Additional keys for advanced use cases:
+
+| Provider | What it unlocks | Free tier? |
+|----------|----------------|------------|
+| **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) |
 | **Replicate** | Image and media AI models | No |
@@ -469,12 +476,31 @@ These unlock additional capabilities. All are optional — your assistant works
 
 #### Recommended Free Keys
 
-To get the most out of your assistant at no extra cost:
+To get the most out of your assistant at no extra cost, we recommend signing up for two free services: **Tavily** (web search) and **Google AI** (voice notes and video). Both are free and take a couple of minutes each.
+
+> **Tip:** Your assistant can do this for you. Just ask — for example, "Help me get a Tavily API key" — and it will use the browser to walk through the process. You can watch on the Browser page and step in if needed. The instructions below are for doing it yourself.
+
+#### Getting a Tavily Key (Web Search)
+
+1. Go to [app.tavily.com](https://app.tavily.com)
+2. Click **"Continue with Google"** (easiest — no CAPTCHA) or sign up with your email
+3. If using Google, select your Google account and grant permission
+4. You'll land on the Tavily dashboard — your API key is shown in the **API Keys** table
+5. If the key is hidden, click the **eye icon** to reveal it
+6. **Copy the key** (it starts with `tvly-`)
+7. Go to your Taskmaster **Setup** page, click the **API Keys** row, find **Tavily**, paste the key, and click **Save**
+
+You get 1,000 free search credits per month — more than enough for daily business use.
+
+#### Getting a Google AI Key (Voice Notes & Video)
 
-- **Brave Search** — sign up at [brave.com/search/api](https://brave.com/search/api) for free web search
-- **Google AI** — sign up at [aistudio.google.com](https://aistudio.google.com) for voice note transcription and video analysis
+1. Go to [aistudio.google.com](https://aistudio.google.com) and sign in with your Google account
+2. Click **API keys** in the left sidebar (or go directly to [aistudio.google.com/api-keys](https://aistudio.google.com/api-keys))
+3. If you already have a key listed, click the key name to view it. If not, click **"Create API key"**
+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**
 
-> **Tip:** Your assistant can help you sign up for these accounts and get the API keys. Just ask — for example, "Sign up for a free Brave Search API key" — and it will use the browser to walk through the process. You can watch on the Browser page and step in if needed.
+The free tier is generous — no credit card required and sufficient for small business use.
 
 ---