@rubytech/taskmaster 1.0.1

package/taskmaster-docs/USER-GUIDE.md

@@ -0,0 +1,954 @@
+# Taskmaster User Guide
+
+Taskmaster is an AI-powered assistant that runs on your own device (Apple Mac or Pi). You can interact with via its chat interface, WhatsApp or iMessages (Mac), or its intutive control panel. It handles customer messages via WhatsApp, manages your schedule, remembers your customers, browses the web, organises your files, and learns your business over time — all through natural conversation. You should read this User Guide completely before doing anything else. 
+
+---
+
+## What You Need
+
+1. **A Claude Pro subscription** — sign up at [claude.ai](https://claude.ai) if you don't have one. Set this up first — Claude can then help you with every step that follows, including installing Taskmaster itself.
+2. **Taskmaster** running on one of:
+   - A **Raspberry Pi** (shipped to you pre-installed), or
+   - A **Mac** (installed from a package file)
+
+---
+
+## Installation
+
+### Option A: Raspberry Pi (pre-installed)
+
+If you received a Taskmaster device:
+
+1. Connect the power cable (USB-C) to the device
+2. Plug it into a wall socket or power strip
+3. Wait about 2 minutes for it to start up
+
+> **WiFi:** Your device needs an internet connection. You can plug a network cable directly into it, or connect a monitor and keyboard to set up WiFi (see "Using Your Pi as a Desktop" below). Need help? Message us on WhatsApp at **+44 7591 215452** or visit [taskmaster.bot](https://www.taskmaster.bot/).
+
+Then open your web browser on any device connected to the same WiFi and go to:
+
+**http://taskmaster.local:18789**
+
+### Option B: Install on a Raspberry Pi yourself
+
+You'll need a Raspberry Pi running Raspberry Pi OS with an internet connection (ethernet or WiFi).
+
+**If you have a monitor and keyboard connected to the Pi:**
+
+1. Open **Terminal** from the desktop taskbar (or press Ctrl+Alt+T)
+2. Run:
+
+```
+curl -fsSL https://taskmaster.bot/install.sh | bash
+```
+
+3. Wait for it to finish (a few minutes — it installs Node.js if needed)
+4. Open the Pi's web browser and go to: **http://localhost:18789/setup**
+
+You can also access the setup page from any other device on the same network at **http://taskmaster.local:18789/setup**.
+
+**If you're connecting remotely (SSH):**
+
+1. Find your Pi's IP address (see "Finding Your Pi's IP Address" below)
+2. From your Mac or PC, open a terminal and run:
+
+```
+ssh pi@<your-pi-ip>
+```
+
+3. Once connected, run:
+
+```
+curl -fsSL https://taskmaster.bot/install.sh | bash
+```
+
+4. Open a browser on your Mac/PC and go to: **http://taskmaster.local:18789/setup**
+
+> After installation, Taskmaster runs in the background and starts automatically when the Pi restarts. You can disconnect the monitor or close the SSH session.
+
+### Option C: Install on a Mac
+
+Open **Terminal** (search for "Terminal" in Spotlight) and run:
+
+```
+curl -fsSL https://taskmaster.bot/install.sh | bash
+```
+
+This installs Node.js (if needed), Taskmaster, and sets up the background service. Once finished, open your browser and go to: **http://localhost:18789/setup**
+
+**Custom port:** If you're running multiple Taskmaster instances (e.g., one on a Pi and one on a Mac), give each a different port:
+
+```
+curl -fsSL https://taskmaster.bot/install.sh | bash -s -- --port 19000
+```
+
+### Option D: Install from a package file
+
+If you received a `.tgz` package file (for offline install or when the install script isn't available):
+
+1. **Install Node.js** (version 22 or later) from [nodejs.org](https://nodejs.org) if you don't have it
+2. Open a terminal and run:
+
+```
+npm install -g ~/Downloads/rubytech-taskmaster-2026.2.14.tgz
+taskmaster provision
+```
+
+4. Open your browser and go to: **http://localhost:18789**
+
+> Taskmaster runs in the background and starts automatically when your Mac restarts. You can close Terminal after installation.
+
+---
+
+## Activating Your License
+
+When you first open the setup page, you'll see a **Device ID** and a field for your license key.
+
+1. The setup page shows your **Device ID** — a code unique to your device
+2. Send this Device ID along with your order number to our WhatsApp support
+3. We'll send you back a license key tied to your device
+4. Paste the key into the setup page and tap **Activate**
+5. Wait for the green checkmark — the wizard will move on automatically
+
+Your license is tied to this device. If you need to move it to a different device, contact support for a new key.
+
+---
+
+## Setting Up
+
+Once your license is activated:
+
+### 1. Connect Your Claude Account
+
+1. Tap **"Connect to Claude"**
+2. Sign in with your Claude Pro account
+3. Copy the code shown and paste it into the setup page
+4. Tap **Submit**
+5. When connected, tap **"Continue to WhatsApp"**
+
+> **Don't have Claude Pro?** Click "Or enter your API key" below the Connect button. Paste your Anthropic API key and tap Submit. This is the advanced option — most people find signing in with Claude Pro much easier.
+
+---
+
+### 2. Link WhatsApp (optional)
+
+WhatsApp is only needed if you want your assistant to handle customer messages or if you want to chat with it via WhatsApp. If you only plan to use the **Chat page** or **iMessage** (Mac), you can skip this step.
+
+1. The setup page shows a QR code
+2. On your phone: **WhatsApp → Settings → Linked Devices → Link a Device**
+3. Scan the QR code on screen
+4. Wait for all status lights to turn green
+
+> **Important:** If you see "Taskmaster" already in your Linked Devices, remove it first before scanning.
+
+> **Private use only?** If you want to use WhatsApp to chat with your assistant yourself but don't want customers to receive automated replies, make sure the **Public facing** toggle on the Setup page is turned off. This keeps WhatsApp connected for your own admin chat while the public assistant stays silent. See "Public-Facing Messages" below for details.
+
+---
+
+## Control Panel
+
+After setup, you'll see a navigation bar at the top of the screen linking to all your pages:
+
+| Page | What it's for |
+|------|---------------|
+| **Setup** | Check connection status, reconnect services, link WhatsApp, manage API keys, toggle public messages |
+| **Chat** | Talk to your admin assistant directly — the preferred way to manage your business |
+| **Admins** | Choose which phone numbers get admin access (see "Two Assistants" below) |
+| **Customers** | Manage verified customer records (payment status, account details) that your assistant can look up but not change |
+| **Files** | Browse and manage your assistant's knowledge files and memory |
+| **Browser** | See what the assistant sees when it browses the web for you |
+| **Advanced** | View events (automated tasks), sessions, skills, and logs |
+
+You'll land on the Setup page by default. From there, the nav bar takes you anywhere.
+
+---
+
+## Security & PINs
+
+Your dashboard is protected by two layers of security:
+
+1. **Your network is the main barrier.** Taskmaster only runs on your local network (your home or office WiFi). Nobody outside your network can reach it at all — it is not accessible from the internet.
+2. **PINs prevent casual access within your network.** The PIN stops other people on the same WiFi — family, employees, guests — from opening accounts that aren't theirs.
+
+If you enter the wrong PIN 5 times in a row, you'll be locked out for 5 minutes before you can try again.
+
+### First Time
+
+The very first time you open the dashboard, you'll be asked to **set a PIN** (4-6 digits). This is your **admin PIN** — it gives you full access to everything. You'll need it every time you open the dashboard.
+
+### Logging In
+
+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.
+
+### 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:
+
+1. Go to the **Setup** page
+2. Select the account from the dropdown at the top
+3. Look for the **Account PIN** row in the status panel
+4. Click **Set PIN** (or **Change** if one is already set)
+5. Enter a new 4-6 digit PIN and confirm it
+
+When someone logs in with an account PIN, they only see their own account — they can't access other accounts or change device settings.
+
+### Changing Your Admin PIN
+
+1. On the login screen, make sure **admin** is selected in the dropdown
+2. Click **Change PIN** below the unlock button
+3. Enter your current PIN, then your new PIN twice
+4. Click **Change PIN**
+
+### Locking
+
+Click the **lock icon** in the top navigation bar to log out. Your session lasts 24 hours — after that you'll need to enter your PIN again.
+
+### Forgotten PIN
+
+If you forget your PIN, you'll need to edit the configuration file on the device. Contact support via WhatsApp for assistance.
+
+---
+
+## Two Assistants, One WhatsApp
+
+Taskmaster runs two assistants on the same WhatsApp number, each with a different job:
+
+**The Public Assistant** handles messages from your customers. It can reply to messages and look up information you've taught it, but it cannot access your files, run commands, or see private notes. If a customer tries to trick it into doing something it shouldn't, it simply can't — those capabilities don't exist for it.
+
+**The Admin Assistant** is your personal assistant. When you message yourself on WhatsApp (or use the Chat page), you're talking to this one. It has full access — it can manage files, browse the web, run scheduled tasks, and read everything.
+
+### How does Taskmaster know which is which?
+
+Your phone number (the one you paired during setup) is marked as an admin. Messages from your number go to the admin assistant. Messages from everyone else go to the public assistant.
+
+You can add more admin numbers on the **Admins** page — for example, your personal phone, a business partner or manager who should also get full access.
+
+---
+
+## Using Your Assistant
+
+Once setup is complete:
+
+- **Customers message your WhatsApp** → The public assistant responds automatically
+- **You open the Chat page** → You're talking to your admin assistant directly
+
+The **Chat page** is the preferred way to talk to your admin assistant. It's always available in the navigation bar, works from any device on your network, and doesn't depend on WhatsApp or iMessage being connected. You can also reach your admin assistant by messaging yourself on WhatsApp or iMessage — all three channels connect to the same assistant with the same knowledge and memory.
+
+Your assistant learns your business from the files in its workspace. The fastest way to get started is to upload your existing documents — price lists, service descriptions, terms and conditions, FAQs — via the **Files** page or by dragging them into the **Chat** page. Your assistant will read and remember everything. You can also teach it through conversation — just chat naturally about your business, pricing, and how you work, and it will save what it learns.
+
+### Sending Files
+
+You can send files to your assistant by dragging and dropping them onto the chat area. Supported types on the Chat page are **images**, **PDFs**, and **text documents** (.md, .txt, .csv, and similar). Files appear as chips below the message box — you can remove them before sending by clicking the X. You can also add a message along with the file to explain what you'd like done with it.
+
+**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).
+
+### 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.
+
+### Model and Thinking Level
+
+Below the message box you'll see two dropdown selectors:
+
+- **Model** — Choose which AI model your assistant uses. Opus is the most capable (best for complex tasks), Sonnet is fast and capable (good all-round), and Haiku is the fastest (great for quick questions).
+- **Thinking** — Controls how deeply the assistant reasons before responding. "Off" is fastest. "Low" through "High" give increasingly thorough reasoning at the cost of speed.
+
+Changes take effect immediately for the next message. You can also use the `/model` and `/think` chat commands for the same thing.
+
+**Note:** These control your **admin assistant** (the one you chat with). To change the model or thinking level for your **public assistant** (the one that talks to customers), use the Model and Thinking dropdowns on the Setup page under WhatsApp.
+
+---
+
+## What Your Admin Assistant Can Do
+
+Your admin assistant has a wide range of capabilities beyond basic conversation. Here's what it can help you with.
+
+### Messaging & Communication
+
+Your assistant can send messages, images, and reactions on your behalf — and relay messages you may have missed - all via the public agent.
+
+| Capability | Description |
+|------------|-------------|
+| Send messages | Send a WhatsApp message to any contact or group on your behalf |
+| Send images | Share photos from your workspace files with a contact |
+| Relay missed messages | Forward messages you missed while away, with a summary |
+
+**Try asking:**
+- "Send Sarah a message saying I'll be 20 minutes late"
+- "What messages did I miss today?"
+- "React to that last message with a thumbs up"
+
+### Memory & Knowledge
+
+Your assistant can search, read, and update your business knowledge. It has full file access within your account workspace — it can create, read, update, and organise files. Files uploaded or dragged onto the Files page are automatically indexed for search.
+
+| Capability | Description |
+|------------|-------------|
+| 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 |
+| 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?"
+
+### Web Search
+
+Your assistant can search the web and read web pages to find information for you. This requires an API key for a search provider (see API Keys below).
+
+| Capability | Description |
+|------------|-------------|
+| Search the web | Look up current information, products, suppliers, regulations |
+| Read web pages | Visit a specific URL and summarise or extract information from it |
+
+**Try asking:**
+- "Search for the current price of 15mm copper pipe"
+- "What are the opening hours for Travis Perkins in Bromley?"
+- "Read this page and summarise it: https://example.com/article"
+
+### Images & Documents
+
+Your assistant can analyse photos you send it and read common document formats.
+
+| Capability | Description |
+|------------|-------------|
+| Analyse images | Describe what's in a photo — useful for job site photos, receipts, diagrams |
+| Read PDFs | Extract and summarise content from PDF files |
+| Read Office documents | Read Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files |
+
+**Try asking:**
+- "What's wrong with the pipe in this photo?"
+- "Read the attached invoice and tell me the total"
+- "Summarise the key points from this PDF"
+
+### Voice Notes & Video
+
+When someone sends a voice note, image, or video, your assistant processes it automatically before responding — no extra steps needed.
+
+| Media type | What happens |
+|------------|-------------|
+| Voice notes | Automatically transcribed to text — your assistant reads the transcript and responds |
+| 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.
+
+### Customer Records
+
+Your assistant can look up and update verified customer records that you manage on the Customers page.
+
+| Capability | Description |
+|------------|-------------|
+| Look up customers | Find customer details by name, phone number, or notes |
+| Update records | Add or change customer information (payment status, notes, etc.) |
+
+**Try asking:**
+- "Look up John Smith's account"
+- "Mark the Johnson job as paid"
+- "What's the status of the Henderson quote?"
+
+### Scheduling & Automation
+
+Your assistant can manage recurring tasks, reminders, and automated routines. You can view and manage these on the Advanced page under the **Events** tab.
+
+| Capability | Description |
+|------------|-------------|
+| Set reminders | Schedule one-time or recurring reminders |
+| Daily briefings | Get an automated morning summary of your day |
+| Recurring tasks | Set up tasks that repeat on a schedule (daily, weekly, etc.) |
+
+**Try asking:**
+- "Remind me to chase the Henderson quote on Friday"
+- "Set up a daily briefing at 7am every weekday"
+- "Create a weekly reminder to check stock levels every Monday"
+
+### Conversations & Sessions
+
+Your assistant can review conversation history and check what customers have been asking about.
+
+| Capability | Description |
+|------------|-------------|
+| List conversations | See who has been messaging and when |
+| Review history | Read back through past conversations with a specific contact |
+| Send between sessions | Send a message to a customer outside of an active conversation |
+| Check session status | See whether your assistant is currently in a conversation |
+
+**Try asking:**
+- "Who messaged today?"
+- "What did Sarah ask about yesterday?"
+- "Send a follow-up to the customer who asked about the boiler"
+
+### Admin Management
+
+Your assistant can manage who has admin access — the same as using the Admins page, but via chat.
+
+| Capability | Description |
+|------------|-------------|
+| Add admin phone | Grant admin access to a new phone number |
+| Remove admin phone | Revoke admin access from a phone number |
+| List admins | See all current admin phone numbers |
+
+**Try asking:**
+- "Add +44 7700 900456 as an admin"
+- "Who are my current admins?"
+- "Remove the old number ending in 789 from admins"
+
+### Web Browsing
+
+Your assistant can open and interact with websites in a built-in browser — filling in forms, clicking buttons, and navigating pages. You can watch what it's doing on the **Browser** page in real time, and take over if it needs help (for example, to complete a CAPTCHA or log in to a site).
+
+| Capability | Description |
+|------------|-------------|
+| Browse websites | Open any website, read content, fill in forms, click buttons |
+| Sign up for services | Create accounts on third-party sites (e.g. to get API keys) |
+| 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"
+- "Go to the Travis Perkins website and find the price of 15mm copper pipe"
+- "Log into my supplier portal and check my order status"
+
+> **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.
+
+---
+
+### API Keys
+
+Your assistant uses AI services behind the scenes. **Claude Pro is the only requirement** — everything else is optional and adds extra capabilities.
+
+#### Connecting to Claude
+
+During setup, you connect to Claude in one of two ways:
+
+1. **Sign in with Claude (recommended):** Click "Connect to Claude" and sign in with your Claude account — this is the easiest way
+2. **API key (advanced):** Click "Or enter your API key" and paste your Anthropic API key directly — only if you already have one
+
+#### Optional API Keys
+
+These unlock additional capabilities. All are optional — your assistant works without them.
+
+| 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) |
+| **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 |
+| **Hume** | Voice and emotion AI | No |
+
+#### 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
+
+#### Recommended Free Keys
+
+To get the most out of your assistant at no extra cost:
+
+- **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
+
+> **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.
+
+---
+
+## Your Files
+
+The **Files** page shows your assistant's knowledge — everything it knows about your business. Files are organised into folders:
+
+| Folder | Who can see it | What it's for |
+|--------|---------------|---------------|
+| **public/** | Both assistants | Information your customers can ask about — services, pricing, opening hours |
+| **shared/** | Both assistants | Internal guidance — how to handle enquiries, tone of voice, escalation rules |
+| **admin/** | Admin assistant only | Private notes, business plans, personal reminders — customers never see this |
+| **users/** | One customer at a time | A folder for each customer (by phone number) with their profile, preferences, and history |
+
+All files are markdown (`.md`) — plain text with simple formatting. You can upload new files by dragging them onto the Files page.
+
+When you add or change a file, your assistant picks it up automatically — no restart needed.
+
+---
+
+## Status Dashboard
+
+The setup page shows a **Status Dashboard** with status indicators for each service:
+
+| Service | Green | Yellow | Grey |
+|---------|-------|--------|------|
+| **Gateway** | Running | — | Not responding |
+| **Claude** | Connected | — | Not connected |
+| **License** | Active | — | — |
+| **WhatsApp** | Connected | Linked but not connected | Not paired |
+| **iMessage** | Connected | Configured but not running | Not configured |
+| **Software** | Up to date | Update available | Not checked |
+
+**Your assistant is ready when Gateway and Claude are green.** You can start chatting straight away using the Chat page. WhatsApp and iMessage are optional — connect them when you're ready.
+
+Each service has a refresh button (circular arrow icon) you can tap to reconnect or restart. Tap the small **(i)** button next to any service to see detailed status information.
+
+### WhatsApp Settings
+
+When WhatsApp is connected, you'll see a small gear icon next to the WhatsApp label. Tap it to open the Public Agent Settings panel, which has three options:
+
+- **Enabled** — When ticked, your assistant replies to messages from customers (anyone who isn't you). When unticked, only you can talk to the assistant.
+- **Model** — Choose which AI model handles customer messages. You can pick Opus (most capable), Sonnet (balanced), or Haiku (fastest and cheapest). This only affects the public assistant — the model you pick in the Chat page controls your admin assistant separately.
+- **Thinking** — Controls how deeply the public assistant reasons before responding to customers. "Off" is fastest. "Low" through "High" give increasingly thorough reasoning at the cost of speed. Like Model, this only affects the public assistant.
+
+---
+
+## Advanced
+
+The **Advanced** page has four tabs for monitoring and managing your assistant behind the scenes. You don't need these day-to-day, but they're useful when you want to see what's happening under the hood.
+
+### Events
+
+This is where you can see and manage everything your assistant does on a schedule — reminders, daily briefings, recurring tasks. Your assistant creates these when you ask it to ("remind me every Monday" or "send me a briefing at 7am"), and they appear here as cards.
+
+Each event card shows its name, schedule, and whether it's on or off. You can:
+- **Tap a card** to see full details and recent activity (when it last ran, whether it succeeded)
+- **Pause or resume** an event using the pause/play icon on the card
+- **Run now** — trigger an event immediately using the play icon
+- **Delete** an event using the trash icon
+- **Create a new event** — tap the "New Event" button to open the form. Choose an agent, set the timing, and describe what the event should do.
+
+You can also create events by asking the assistant in chat ("remind me every Monday" or "send me a briefing at 7am").
+
+### Skills
+
+Skills are the specialised abilities your assistant has — like handling customer enquiries, creating quotes, or checking the weather. This tab shows which skills are installed, whether they're active, and if anything is missing (like an API key a skill needs).
+
+You can enable or disable individual skills from here. Most of the time you won't need to change anything — skills are pre-configured when your device is set up.
+
+### Logs
+
+The Logs tab has two views, selectable with the toggle at the top:
+
+**Session Logs** show the actual conversations your assistant is having — messages from customers, the assistant's responses, tool calls it makes (like checking a calendar or looking up a record), and any errors. This is the view you'll use most often to see what your assistant has been doing.
+
+You can filter by:
+- **Type** — show only certain kinds of entries (messages, tool calls, thinking, errors)
+- **Agent** — show only entries from a specific agent (e.g., public or admin)
+- **Search** — free-text search across all entries
+
+**System Logs** show the internal machinery of the gateway — connections, heartbeats, startup messages. This is mainly useful for troubleshooting when something isn't working. You can filter by log level (info, warning, error, etc.) and export logs to share with support.
+
+Both views support **auto-follow** (keeps the view scrolled to the latest entries) and **export** to download a log file.
+
+---
+
+## Troubleshooting
+
+### Messages not getting through?
+
+1. Go to **http://taskmaster.local:18789/setup**
+2. Check which indicator is not green
+3. Tap the circular arrow button next to the problem service
+
+### WhatsApp shows yellow (Linked but not connected)?
+
+WhatsApp is linked but the connection dropped. This often resolves itself. If not:
+
+1. Go to **http://taskmaster.local:18789/setup**
+2. Tap **"Refresh Status"** — it may reconnect automatically
+3. If still yellow after a minute, tap the circular arrow next to WhatsApp to relink
+
+### WhatsApp linking keeps failing?
+
+The old connection data may be corrupted. To start fresh:
+
+1. Go to **http://taskmaster.local:18789/setup**
+2. Tap **"Reset WhatsApp"** (red button)
+3. **On your phone:** WhatsApp → Settings → Linked Devices
+4. **Remove** "Taskmaster" from the list if present
+5. **Scan** the new QR code
+
+### WhatsApp shows "linked" on phone but status is red?
+
+The phone and Taskmaster are out of sync. To fix:
+
+1. **On your phone:** WhatsApp → Settings → Linked Devices
+2. **Remove** "Taskmaster" from the list
+3. On the setup page, tap the circular arrow next to WhatsApp
+4. **Scan** the new QR code
+
+### Claude connection expired?
+
+1. Go to **http://taskmaster.local:18789/setup**
+2. Tap the circular arrow next to Claude (or **"Connect to Claude"** if shown)
+3. Sign in and enter the code
+
+### Gateway not responding?
+
+The gateway is the software that runs your assistant. If it's showing red:
+
+1. Go to **http://taskmaster.local:18789/setup**
+2. Tap the circular arrow next to Gateway to restart it
+3. Wait 30 seconds for it to come back online
+4. If still not working, try unplugging your Taskmaster device, waiting 10 seconds, and plugging it back in
+
+### Can't reach the setup page?
+
+- Make sure you're on the same WiFi as Taskmaster
+- Try using the IP address: **http://192.168.x.x:18789** (contact Support for assistance)
+- Wait 2 minutes after power-on for the device to start
+
+---
+
+## Multiple Accounts
+
+You can run more than one account on the same Taskmaster device. Each account gets its own assistant identity, customer knowledge, and WhatsApp number — completely separate from your other accounts.
+
+### Adding a Second Account
+
+1. Go to the **Setup** page
+2. Scroll down to **Your Accounts**
+3. Tap **"+ Add Account"**
+4. Enter a name for the account (e.g., "My Plumbing Company")
+5. Tap **Create** — the system will set up the workspace and restart
+6. When the QR code appears, scan it with the WhatsApp number for this account
+7. Your new account is live
+
+### How It Works
+
+- Each account has its own **public assistant** (handles customers) and **admin assistant** (handles you)
+- Each account has its own **files and memory** — customers of one account don't see data from another
+- Each account connects to its own **WhatsApp number**
+- You manage all accounts from the same Setup page
+
+### Renaming Your Account
+
+The name you see in the account selector and dashboard can be changed at any time:
+
+1. Go to the **Setup** page
+2. Click the **pencil icon** next to your account name in the dashboard header
+3. Type the new name (e.g., "Joe's Coffee Shop")
+4. Press **Enter** to save, or **Escape** to cancel
+
+The rename takes effect immediately across all pages — no restart needed.
+
+### Removing an Account
+
+1. Go to the **Setup** page
+2. Find the account under **Your Accounts**
+3. Tap the **X** button next to it
+4. Confirm removal
+
+This removes the assistant and routing but keeps the account files on disk.
+
+---
+
+## iMessage (Mac only)
+
+If you're running Taskmaster on a Mac, you can also talk to your assistant by messaging yourself in the Messages app — no WhatsApp needed.
+
+### What it does
+
+When you send a message to yourself in Messages.app, your assistant replies in the same conversation. It works just like the admin chat on WhatsApp, but through iMessage.
+
+> **Note:** In Messages.app, self-chat messages appear on both sides of the conversation (blue and grey). This is normal — it's how Apple designed self-chat. Your assistant only replies once; the double appearance is a visual quirk of Messages.app. WhatsApp does not have this behavior.
+
+### One account at a time
+
+Unlike WhatsApp — where each account has its own phone number — iMessage shares a single Messages app across all accounts. Only **one account** can use iMessage at a time.
+
+- The account that's selected in the dropdown when you enable iMessage gets it
+- Other accounts will show "Not connected — iMessage is connected to {Account Name}"
+- To move iMessage to a different account, select that account and tap the refresh button on the iMessage row
+
+### Self-chat only
+
+iMessage is for **self-chat only** — messages from other people are not processed. It works like your private admin channel, separate from WhatsApp which handles customer messages.
+
+### How to enable
+
+1. Go to the **Setup** page
+2. Select the account you want to connect (if you have more than one)
+3. Find the **iMessage** row in the status dashboard (below WhatsApp)
+4. Tap the circular arrow button
+5. A confirmation message appears — tap **Enable**
+6. The gateway will restart automatically
+7. When the iMessage row turns green, you're ready
+
+### Before you start
+
+iMessage support requires two things on your Mac **before** running Taskmaster setup:
+
+1. **Xcode or Xcode Command Line Tools** (up to date)
+
+   Homebrew needs a current version of Xcode to compile the iMessage helper. Check which situation applies to you:
+
+   - **If you don't have Xcode at all** — open Terminal and run:
+     ```
+     xcode-select --install
+     ```
+     A dialog will appear — click **Install** and wait for it to finish.
+
+   - **If you have Xcode from the App Store but it's outdated** — open the **App Store**, find Xcode, and click **Update**. This is the most common issue.
+
+   - **If you don't want to update Xcode** — you can tell your Mac to use the standalone Command Line Tools instead (faster, no large download). Open Terminal and run:
+     ```
+     sudo xcode-select --switch /Library/Developer/CommandLineTools
+     ```
+     Enter your password when prompted. This leaves Xcode.app untouched but tells Homebrew to use the lightweight tools.
+
+2. **Homebrew** — if you don't already have it, open Terminal and run:
+   ```
+   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+   ```
+
+Once both are ready, Taskmaster will automatically install the iMessage helper (`imsg`) during setup.
+
+### Requirements
+
+- **Mac only** — iMessage is not available on Raspberry Pi
+- **Xcode Command Line Tools** or up-to-date Xcode (see "Before you start" above)
+- **Homebrew** (see "Before you start" above)
+- **Full Disk Access** for the Node.js binary (see "Grant Full Disk Access" below)
+- When macOS asks to control Messages.app, click **OK** (first time only)
+
+### Grant Full Disk Access
+
+Taskmaster's iMessage helper needs permission to read the Messages database. macOS blocks this unless the Node.js binary has Full Disk Access. There are three steps: sign the binaries, grant Terminal access, and grant Node.js access.
+
+#### Step 1: Sign the binaries
+
+Some Homebrew-installed binaries are unsigned. macOS Full Disk Access silently rejects unsigned binaries — they won't appear in the list even after you add them. Open Terminal and run:
+
+```
+sudo codesign --force --sign - $(realpath $(which imsg))
+sudo codesign --force --sign - $(realpath $(which node))
+```
+
+Enter your password when prompted. If a binary is already signed, this harmlessly replaces the signature.
+
+#### Step 2: Grant Terminal Full Disk Access
+
+1. Open **System Settings > Privacy & Security > Full Disk Access**
+2. Click the **+** button
+3. Navigate to **Applications > Utilities > Terminal** and click **Open**
+4. Make sure the toggle next to Terminal is **on**
+5. **Quit Terminal completely** (Cmd+Q) and reopen it
+
+You can verify it worked by running `imsg chats --limit 5` in Terminal — if you see a list of chats, Full Disk Access is working.
+
+#### Step 3: Grant the Node.js binary Full Disk Access
+
+The gateway runs as a background service using Node.js. Terminal's access doesn't apply to background services, so Node.js needs its own entry.
+
+1. Open Terminal and run:
+   ```
+   realpath $(which node)
+   ```
+   This prints the real path — something like `/usr/local/Cellar/node/23.3.0/bin/node` or `/Users/you/.nvm/versions/node/v22.22.0/bin/node`.
+
+2. Open a **Finder** window and press **Cmd+Shift+G** (Go to Folder)
+3. Paste the **folder** part of the path (everything up to the last `/`) and press Enter
+4. You should see the `node` file in Finder — keep this window open
+
+5. Open **System Settings > Privacy & Security > Full Disk Access**
+6. **Drag** the `node` file from Finder directly onto the Full Disk Access list
+7. Make sure the toggle is **on**
+
+> **Note:** The entry may not visibly appear in the list, but it still takes effect. After dragging, restart the gateway from the Setup page and check the iMessage status.
+
+8. Restart the gateway: go to the **Setup** page and tap the circular arrow next to **Gateway**
+
+**Why drag from Finder?** The file picker (+) button sometimes has trouble with command-line binaries. Dragging from Finder is more reliable. Always use the real path (from `realpath`), not `/usr/local/bin/node` — that's a shortcut (symlink) that macOS silently ignores.
+
+### Troubleshooting
+
+**"permission denied" or "authorization denied" errors in logs?**
+- Full Disk Access has not been granted to `imsg`. Follow the "Grant Full Disk Access" steps above.
+
+**"Xcode too outdated" or "imsg installation failed" during setup?**
+
+This means Homebrew found an outdated Xcode.app on your Mac. Three options:
+
+1. **Update Xcode** — open the App Store and update Xcode
+2. **Switch to Command Line Tools** (no download needed) — open Terminal and run:
+   ```
+   sudo xcode-select --switch /Library/Developer/CommandLineTools
+   ```
+3. **Install Command Line Tools** (if you don't have them) — run `xcode-select --install`
+
+After any of the above, re-run: `pnpm taskmaster daemon install --force`
+
+**iMessage row stays grey after enabling?**
+- Open Terminal and type `imsg --version`. If it says "command not found", re-run: `pnpm taskmaster daemon install --force`
+- Check that Full Disk Access is granted to `imsg` (see above), then restart the gateway
+
+**Messages not getting through?**
+- Open Terminal and run `imsg watch` — you should see messages appear when you text yourself
+- If nothing appears, Full Disk Access is not set correctly for `imsg`
+
+**Multiple Apple IDs?**
+If you have more than one Apple ID linked to your iMessage account, only the first registered account supports self-chat — regardless of which account you choose to "start new conversations from" in Messages settings.
+
+---
+
+## Using Your Pi as a Desktop
+
+Your Raspberry Pi is a full computer — you can connect a monitor, keyboard, and mouse and use it directly.
+
+### What you need
+
+- A **micro-HDMI cable** (or micro-HDMI to HDMI adapter) to connect a monitor or TV
+- A **USB keyboard** and **USB mouse**
+
+### What you can do
+
+**Browse your files** — Open the file manager from the desktop and navigate to the home folder. You'll see your workspace files — the same ones that appear on the Files page in the dashboard.
+
+**Access the dashboard locally** — Open the web browser and go to **http://localhost:18789** to use the full Taskmaster dashboard directly on the Pi, without needing another device on the network.
+
+**General desktop use** — The Pi runs a full desktop environment. You can browse the web, view documents, and use any standard Linux applications.
+
+### Finding Your Pi's IP Address
+
+You need the IP address to connect from another device on your network (e.g., SSH, or if `taskmaster.local` isn't working).
+
+**From the Pi itself** (monitor + keyboard):
+
+1. Open Terminal (taskbar or Ctrl+Alt+T)
+2. Run:
+   ```
+   hostname -I
+   ```
+3. The first number shown is your IP address (e.g., `192.168.1.42`)
+
+**From your Mac or PC** (without a monitor on the Pi):
+
+- **Mac:** Open Terminal and run `ping taskmaster.local` — the IP appears in the response
+- **Mac/PC:** Check your router's admin page (usually `192.168.1.1`) — look for a device called "taskmaster" or "raspberrypi" in the connected devices list
+- **Mac:** Run `arp -a | grep raspberry` or `dns-sd -B _http._tcp` to find devices broadcasting on the network
+
+Once you have the IP, you can access the setup page at `http://<your-pi-ip>:18789/setup` or connect via SSH with `ssh pi@<your-pi-ip>`.
+
+---
+
+## Public-Facing Messages (DM Policy)
+
+By default, your assistant responds to messages from anyone who contacts your WhatsApp number. You can turn this off so that only admin phones get through.
+
+### Toggling Public Messages
+
+1. Go to the **Setup** page
+2. In the status dashboard, find the **Public facing** toggle (under your WhatsApp connection)
+3. Toggle it **on** to accept messages from anyone, or **off** to block unknown senders
+
+When public messages are **off**:
+- **You** (the phone that scanned the QR code) can still message your assistant
+- **Admin phones** (added on the Admins page) can still message your assistant
+- **Everyone else** is blocked — they won't get a response
+
+When public messages are **on**:
+- Anyone who messages your WhatsApp number gets a response from your public assistant
+
+No restart is needed — the change takes effect immediately.
+
+---
+
+## Chat Commands
+
+You can control your assistant's behaviour by typing slash commands in any conversation. These are intercepted by the system — the assistant never sees them.
+
+### How commands work
+
+- Type a command **on its own** (e.g., `/filler on`) — the system responds with a confirmation
+- Type a command **without an argument** (e.g., `/filler`) — the system shows the current setting and valid options
+- Commands work in WhatsApp, iMessage, and the Chat page
+- Only admin phone numbers can use most commands
+
+### Common commands
+
+| Command | What it does |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/status` | Show current settings (model, thinking level, etc.) |
+| `/filler on` | Turn on filler messages — quick acknowledgments like "Let me check..." while the assistant thinks |
+| `/filler off` | Turn off filler messages |
+| `/verbose on` | Turn on verbose mode — the assistant shows more detail in responses |
+| `/verbose off` | Turn off verbose mode |
+| `/think [level]` | Set thinking depth: `off`, `minimal`, `low`, `medium`, `high` |
+| `/model [name]` | Show or switch the AI model (e.g., `/model opus`, `/model sonnet`, `/model haiku`) |
+| `/models` | List all available models |
+| `/new` (or `/reset`) | Start a fresh conversation — clears history and reloads the assistant's instructions |
+| `/compact` | Refresh the assistant's instructions without losing conversation history (summarises older messages to free up space) |
+| `/stop` | Stop the assistant mid-response |
+| `/restart` | Restart the Taskmaster gateway |
+| `/activation always` | Make the assistant respond to every group message (not just @mentions) |
+| `/activation mention` | Make the assistant only respond when @mentioned in groups |
+
+### Examples
+
+> **You:** `/filler`
+> **System:** Filler messages: off. Options: on, off.
+
+> **You:** `/filler on`
+> **System:** Filler messages enabled.
+
+> **You:** `/think high`
+> **System:** Thinking level set to high.
+
+---
+
+## Groups
+
+Your assistant can respond in WhatsApp group chats. By default, groups are disabled.
+
+### Enabling Groups
+
+Open the **Control Panel**, go to the **WhatsApp** section, and tap the settings (gear) icon on your WhatsApp account. In the settings modal, tick **Group chats**. This allows your assistant to respond in any WhatsApp group it's added to.
+
+### How the Assistant Responds
+
+When you enable groups, you choose how the assistant responds:
+
+- **When mentioned** (default) — the assistant only responds when someone **@mentions** it. This prevents it from jumping into every conversation.
+- **Always respond** — the assistant responds to every message in every group.
+
+You can change this at any time in the same settings modal.
+
+### Per-Group Override
+
+Group members can override the response mode for their specific group using chat commands:
+
+> `/activation always` — respond to every message in this group
+
+> `/activation mention` — only respond when @mentioned
+
+Only the business owner can change the activation mode.
+
+---
+
+## Updating Taskmaster
+
+When a new version of Taskmaster is available, the **Software** row on the Status Dashboard turns yellow and shows the new version number (e.g., "v1.2.3 → v1.3.0").
+
+To update:
+
+1. Open the **Setup** page
+2. Look for the **Software** row in the dashboard
+3. If an update is available, tap the **download** button (down-arrow icon)
+4. Wait for the update to complete — the page will reload automatically
+5. After reload, the Software row should show "Up to date" in green
+
+If the Software row shows "Unknown", tap the **refresh** button (circular arrow) to check for updates. Tap the **(i)** button to see version details.
+
+> **Note:** Updates require an internet connection. The update process takes about 30 seconds. Your assistant will be briefly unavailable during the restart.
+
+---
+
+## Getting Help
+
+- **Email:** taskmaster@rubytech.llc
+- **WhatsApp:** +44 7591 215452
+
+---
+
+*Taskmaster — Your admin assistant that works while you work.*