@rubytech/taskmaster 1.0.64 → 1.0.65

package/dist/gateway/server-methods/public-chat.js

@@ -0,0 +1,110 @@
+/**
+ * RPC handlers for public chat: OTP verification and session resolution.
+ */
+import { loadConfig } from "../../config/config.js";
+import { ErrorCodes, errorShape } from "../protocol/index.js";
+import { requestOtp, verifyOtp } from "../public-chat/otp.js";
+import { deliverOtp } from "../public-chat/deliver-otp.js";
+import { buildPublicSessionKey, resolvePublicAgentId } from "../public-chat/session.js";
+/** Minimal phone format check: starts with +, digits only, 7–15 digits. */
+function isValidPhone(phone) {
+    return /^\+\d{7,15}$/.test(phone);
+}
+export const publicChatHandlers = {
+    /**
+     * Request an OTP code — sends a 6-digit code to the given phone via WhatsApp.
+     * Params: { phone: string }
+     */
+    "public.otp.request": async ({ params, respond, context }) => {
+        const phone = typeof params.phone === "string" ? params.phone.trim() : "";
+        if (!phone || !isValidPhone(phone)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid phone number"));
+            return;
+        }
+        const cfg = loadConfig();
+        if (!cfg.publicChat?.enabled) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "public chat disabled"));
+            return;
+        }
+        const result = requestOtp(phone);
+        if (!result.ok) {
+            respond(false, { retryAfterMs: result.retryAfterMs }, errorShape(ErrorCodes.INVALID_REQUEST, "rate limited — try again shortly"));
+            return;
+        }
+        try {
+            await deliverOtp(phone, result.code);
+        }
+        catch (err) {
+            context.logGateway.warn(`public-chat OTP delivery failed: ${String(err)}`);
+            respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, "failed to send verification code"));
+            return;
+        }
+        respond(true, { ok: true });
+    },
+    /**
+     * Verify an OTP code and return the session key.
+     * Params: { phone: string, code: string, name?: string }
+     */
+    "public.otp.verify": async ({ params, respond }) => {
+        const phone = typeof params.phone === "string" ? params.phone.trim() : "";
+        const code = typeof params.code === "string" ? params.code.trim() : "";
+        const name = typeof params.name === "string" ? params.name.trim() : undefined;
+        if (!phone || !isValidPhone(phone)) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid phone number"));
+            return;
+        }
+        if (!code) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "code required"));
+            return;
+        }
+        const cfg = loadConfig();
+        if (!cfg.publicChat?.enabled) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "public chat disabled"));
+            return;
+        }
+        const result = verifyOtp(phone, code);
+        if (!result.ok) {
+            const messages = {
+                not_found: "no pending verification for this number",
+                expired: "verification code expired",
+                max_attempts: "too many attempts — request a new code",
+                invalid: "incorrect code",
+            };
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, messages[result.error] ?? "verification failed"));
+            return;
+        }
+        const agentId = resolvePublicAgentId(cfg);
+        const sessionKey = buildPublicSessionKey(agentId, phone);
+        respond(true, {
+            ok: true,
+            sessionKey,
+            agentId,
+            phone,
+            name,
+        });
+    },
+    /**
+     * Resolve a session key for anonymous public chat.
+     * Params: { cookieId: string }
+     */
+    "public.session": async ({ params, respond }) => {
+        const cookieId = typeof params.cookieId === "string" ? params.cookieId.trim() : "";
+        if (!cookieId || cookieId.length < 8 || cookieId.length > 128) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "invalid cookieId"));
+            return;
+        }
+        const cfg = loadConfig();
+        if (!cfg.publicChat?.enabled) {
+            respond(false, undefined, errorShape(ErrorCodes.INVALID_REQUEST, "public chat disabled"));
+            return;
+        }
+        const agentId = resolvePublicAgentId(cfg);
+        const identifier = `anon-${cookieId}`;
+        const sessionKey = buildPublicSessionKey(agentId, identifier);
+        respond(true, {
+            ok: true,
+            sessionKey,
+            agentId,
+        });
+    },
+};

package/dist/gateway/server-methods/sessions-transcript.js

@@ -1,22 +1,13 @@
 import fs from "node:fs/promises";
 import { loadConfig } from "../../config/config.js";
 import { ErrorCodes, errorShape, formatValidationErrors, validateSessionsTranscriptParams, } from "../protocol/index.js";
-import { loadCombinedSessionStoreForGateway, resolveSessionTranscriptCandidates, } from "../session-utils.js";
+import { listAgentsForGateway, loadCombinedSessionStoreForGateway, resolveSessionTranscriptCandidates, } from "../session-utils.js";
 const DEFAULT_LIMIT = 200;
-const DEFAULT_MAX_BYTES_PER_FILE = 128_000;
-const CONTENT_MAX_CHARS = 2048;
-const MAX_SESSIONS = 20;
-const ACTIVE_WINDOW_MS = 24 * 60 * 60 * 1000;
 function extractAgentId(sessionKey) {
     // Keys look like "agent:public:dm:+447..." — second segment is the agent ID.
     const parts = sessionKey.split(":");
     return parts.length >= 2 ? parts[1] : "unknown";
 }
-function truncate(text, max) {
-    if (text.length <= max)
-        return text;
-    return text.slice(0, max);
-}
 function resolveTimestamp(entry, fileMtimeMs) {
     if (typeof entry.timestamp === "string" && entry.timestamp)
         return entry.timestamp;
@@ -39,7 +30,7 @@ function extractTextFromContentBlocks(blocks) {
     }
     return parts.join("\n");
 }
-function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs, maxChars = CONTENT_MAX_CHARS) {
+function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs) {
     const entries = [];
     const ts = resolveTimestamp(line, fileMtimeMs);
     const model = line.message?.model;
@@ -57,7 +48,7 @@ function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs,
             agentId,
             timestamp: ts,
             type: "error",
-            content: truncate(content, maxChars),
+            content,
             ...(model ? { model } : {}),
         });
         return entries;
@@ -74,7 +65,7 @@ function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs,
             agentId,
             timestamp: ts,
             type: "tool",
-            content: truncate(content, maxChars),
+            content,
             ...(line.toolName ? { toolName: line.toolName } : {}),
             ...(model ? { model } : {}),
         });
@@ -93,7 +84,7 @@ function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs,
                 agentId,
                 timestamp: ts,
                 type: entryType,
-                content: truncate(msg.content, maxChars),
+                content: msg.content,
                 ...(model ? { model } : {}),
             });
             return entries;
@@ -113,7 +104,7 @@ function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs,
                     agentId,
                     timestamp: ts,
                     type: "thinking",
-                    content: truncate(text, maxChars),
+                    content: text,
                     ...(model ? { model } : {}),
                 });
             }
@@ -127,7 +118,7 @@ function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs,
                     agentId,
                     timestamp: ts,
                     type: "tool",
-                    content: truncate(content, maxChars),
+                    content,
                     ...(toolName ? { toolName } : {}),
                     ...(model ? { model } : {}),
                 });
@@ -143,7 +134,7 @@ function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs,
                     agentId,
                     timestamp: ts,
                     type: entryType,
-                    content: truncate(text, maxChars),
+                    content: text,
                     ...(model ? { model } : {}),
                 });
             }
@@ -161,7 +152,7 @@ function expandLineToEntries(line, sessionId, sessionKey, agentId, fileMtimeMs,
                     agentId,
                     timestamp: ts,
                     type: entryType,
-                    content: truncate(text, maxChars),
+                    content: text,
                     ...(model ? { model } : {}),
                 });
             }
@@ -215,46 +206,29 @@ export const sessionsTranscriptHandlers = {
         }
         const p = params;
         const limit = p.limit ?? DEFAULT_LIMIT;
-        const maxBytesPerFile = p.maxBytesPerFile ?? DEFAULT_MAX_BYTES_PER_FILE;
         const inputCursors = p.cursors ?? {};
-        const contentMaxChars = p.full ? Infinity : CONTENT_MAX_CHARS;
         const agentFilter = p.agents && p.agents.length > 0 ? new Set(p.agents) : null;
         try {
             const cfg = loadConfig();
             const { storePath, store } = loadCombinedSessionStoreForGateway(cfg);
             const storeKeys = Object.keys(store);
-            // Filter to sessions updated within last 24 hours
-            const now = Date.now();
-            const cutoff = now - ACTIVE_WINDOW_MS;
-            const staleKeys = Object.entries(store)
-                .filter(([, entry]) => (entry.updatedAt ?? 0) < cutoff)
-                .map(([key, entry]) => `${key}(${entry.updatedAt ?? 0})`);
-            let activeSessions = Object.entries(store)
-                .filter(([, entry]) => {
-                const updatedAt = entry.updatedAt ?? 0;
-                return updatedAt >= cutoff;
-            })
-                .sort(([, a], [, b]) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))
-                .slice(0, MAX_SESSIONS);
+            // All sessions sorted by recency — no time cutoff, no count cap.
+            let sessions = Object.entries(store).sort(([, a], [, b]) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));
             // Apply agent filter if provided
             if (agentFilter) {
-                activeSessions = activeSessions.filter(([key]) => {
+                sessions = sessions.filter(([key]) => {
                     const agentId = extractAgentId(key);
                     return agentFilter.has(agentId);
                 });
             }
-            // Diagnostic: log store resolution so we can trace "missing session logs" reports.
-            context.logGateway.info(`sessions.transcript: storePath=${storePath} storeKeys=${storeKeys.length} active=${activeSessions.length} stale=${staleKeys.length} cutoffAge=24h`);
+            context.logGateway.info(`sessions.transcript: storePath=${storePath} storeKeys=${storeKeys.length} sessions=${sessions.length}`);
             if (storeKeys.length === 0) {
                 context.logGateway.warn(`sessions.transcript: combined store is empty — no agents found or no session entries`);
             }
-            else if (activeSessions.length === 0) {
-                context.logGateway.warn(`sessions.transcript: all ${storeKeys.length} sessions are stale (>24h): ${staleKeys.slice(0, 5).join(", ")}`);
-            }
             const allEntries = [];
             const cursors = {};
             const agentIds = new Set();
-            for (const [sessionKey, sessionEntry] of activeSessions) {
+            for (const [sessionKey, sessionEntry] of sessions) {
                 const sessionId = sessionEntry.sessionId;
                 if (!sessionId)
                     continue;
@@ -263,8 +237,7 @@ export const sessionsTranscriptHandlers = {
                 const sources = [{ sid: sessionId, file: sessionEntry.sessionFile }];
                 const prev = sessionEntry.previousSessions;
                 if (Array.isArray(prev)) {
-                    // Include recent previous sessions (newest first, limit 3 to bound IO)
-                    for (const p of prev.slice(-3).reverse()) {
+                    for (const p of prev.slice().reverse()) {
                         if (p.sessionId)
                             sources.push({ sid: p.sessionId, file: p.sessionFile });
                     }
@@ -294,7 +267,8 @@ export const sessionsTranscriptHandlers = {
                         result = await readTranscriptTail({
                             filePath,
                             cursor,
-                            maxBytes: maxBytesPerFile,
+                            // Read entire file when no cursor — no byte cap
+                            maxBytes: Infinity,
                         });
                     }
                     catch {
@@ -311,7 +285,7 @@ export const sessionsTranscriptHandlers = {
                         catch {
                             continue;
                         }
-                        const expanded = expandLineToEntries(parsed, source.sid, sessionKey, agentId, result.fileMtimeMs, contentMaxChars);
+                        const expanded = expandLineToEntries(parsed, source.sid, sessionKey, agentId, result.fileMtimeMs);
                         allEntries.push(...expanded);
                     }
                 }
@@ -323,9 +297,18 @@ export const sessionsTranscriptHandlers = {
                 return tb - ta;
             });
             const entries = allEntries.slice(0, limit);
+            // Include configured agents so UI filter chips appear even when an
+            // agent has no sessions yet. When an agent filter is active (account
+            // scoping), only add config agents that match the filter — otherwise
+            // agents from other accounts leak into the chip list.
+            const { agents: configAgents } = listAgentsForGateway(cfg);
+            for (const a of configAgents) {
+                if (!agentFilter || agentFilter.has(a.id))
+                    agentIds.add(a.id);
+            }
             const agents = Array.from(agentIds).sort();
-            if (allEntries.length === 0 && activeSessions.length > 0) {
-                context.logGateway.warn(`sessions.transcript: ${activeSessions.length} active session(s) but 0 transcript entries — files may be missing or unreadable`);
+            if (allEntries.length === 0 && sessions.length > 0) {
+                context.logGateway.warn(`sessions.transcript: ${sessions.length} session(s) but 0 transcript entries — files may be missing or unreadable`);
             }
             respond(true, { entries, cursors, agents }, undefined);
         }

package/dist/gateway/server-methods.js

@@ -32,6 +32,7 @@ import { usageHandlers } from "./server-methods/usage.js";
 import { voicewakeHandlers } from "./server-methods/voicewake.js";
 import { webHandlers } from "./server-methods/web.js";
 import { wizardHandlers } from "./server-methods/wizard.js";
+import { publicChatHandlers } from "./server-methods/public-chat.js";
 import { workspacesHandlers } from "./server-methods/workspaces.js";
 const ADMIN_SCOPE = "operator.admin";
 const READ_SCOPE = "operator.read";
@@ -40,6 +41,15 @@ const APPROVALS_SCOPE = "operator.approvals";
 const PAIRING_SCOPE = "operator.pairing";
 const APPROVAL_METHODS = new Set(["exec.approval.request", "exec.approval.resolve"]);
 const NODE_ROLE_METHODS = new Set(["node.invoke.result", "node.event", "skills.bins"]);
+/** Methods accessible to public-chat role (no PIN, no gateway auth). */
+const PUBLIC_ROLE_METHODS = new Set([
+    "chat.send",
+    "chat.history",
+    "chat.abort",
+    "public.otp.request",
+    "public.otp.verify",
+    "public.session",
+]);
 const PAIRING_METHODS = new Set([
     "node.pair.request",
     "node.pair.list",
@@ -115,6 +125,12 @@ function authorizeGatewayMethod(method, client) {
         return null;
     const role = client.connect.role ?? "operator";
     const scopes = client.connect.scopes ?? [];
+    // Public role: only allow explicitly listed methods
+    if (role === "public") {
+        if (PUBLIC_ROLE_METHODS.has(method))
+            return null;
+        return errorShape(ErrorCodes.INVALID_REQUEST, `unauthorized: public role cannot call ${method}`);
+    }
     if (NODE_ROLE_METHODS.has(method)) {
         if (role === "node")
             return null;
@@ -218,6 +234,7 @@ export const coreGatewayHandlers = {
     ...memoryHandlers,
     ...recordsHandlers,
     ...workspacesHandlers,
+    ...publicChatHandlers,
 };
 export async function handleGatewayRequest(opts) {
     const { req, respond, client, isWebchatConnect, context } = opts;

package/dist/hooks/bundled/conversation-archive/handler.js

@@ -65,11 +65,17 @@ function formatTime(timestamp) {
     });
 }
 /**
- * Format date for section header
+ * Format date for section header.
+ * Uses local date (consistent with formatTime) — NOT UTC.
+ * Previously used toISOString() which is UTC, causing date/time mismatches
+ * near midnight when local timezone differs from UTC.
  */
 function formatDate(timestamp) {
     const date = timestamp instanceof Date ? timestamp : new Date(timestamp);
-    return date.toISOString().split("T")[0]; // YYYY-MM-DD
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
 }
 /**
  * Get monthly log filename
@@ -84,7 +90,7 @@ function getMonthlyLogFilename(timestamp) {
  * Archive a message to the conversation log
  */
 async function archiveMessage(params) {
-    const { workspaceDir, subdir, role, text, timestamp, fileHeader } = params;
+    const { workspaceDir, subdir, role, text, timestamp, fileHeader, channel } = params;
     // Build path: memory/{subdir}/conversations/YYYY-MM.md
     const conversationsDir = path.join(workspaceDir, "memory", subdir, "conversations");
     await fs.mkdir(conversationsDir, { recursive: true });
@@ -121,7 +127,8 @@ async function archiveMessage(params) {
     }
     // Format the message - escape any markdown in the text
     const cleanText = text?.trim() || "(no text)";
-    entryParts.push(`### ${timeStr} — ${role}`);
+    const channelTag = channel ? ` [${channel}]` : "";
+    entryParts.push(`### ${timeStr} — ${role}${channelTag}`);
     entryParts.push(cleanText);
     entryParts.push("");
     const entry = entryParts.join("\n");
@@ -155,6 +162,8 @@ const archiveConversation = async (event) => {
         }
         // Get timestamp from context or event
         const timestamp = context.timestamp ?? event.timestamp;
+        // Channel identifier from hook context (e.g. "whatsapp", "webchat", "imessage")
+        const channel = context.channel ?? undefined;
         // Determine conversation type from session key and route to correct archive path
         const peer = extractPeerFromSessionKey(event.sessionKey);
         const groupId = peer ? null : extractGroupIdFromSessionKey(event.sessionKey);
@@ -165,7 +174,7 @@ const archiveConversation = async (event) => {
             const subdir = isAdminAgent ? "admin" : `users/${peer}`;
             const inboundRole = isAdminAgent ? "Admin" : "User";
             const role = event.action === "inbound" ? inboundRole : "Assistant";
-            await archiveMessage({ workspaceDir, subdir, role, text, timestamp });
+            await archiveMessage({ workspaceDir, subdir, role, text, timestamp, channel });
         }
         else if (groupId) {
             // Group message — archive under memory/groups/{groupId}/
@@ -193,12 +202,20 @@ const archiveConversation = async (event) => {
                 text,
                 timestamp,
                 fileHeader,
+                channel,
             });
         }
         else if (isWebchat) {
             // Webchat (control panel) — archive under memory/admin/conversations/
             const role = event.action === "inbound" ? "Admin" : "Assistant";
-            await archiveMessage({ workspaceDir, subdir: "admin", role, text, timestamp });
+            await archiveMessage({
+                workspaceDir,
+                subdir: "admin",
+                role,
+                text,
+                timestamp,
+                channel: channel ?? "webchat",
+            });
         }
         else {
             // Unknown session key format — skip

package/dist/plugins/runtime/index.js

@@ -11,6 +11,7 @@ import { createReplyDispatcherWithTyping } from "../../auto-reply/reply/reply-di
 import { finalizeInboundContext } from "../../auto-reply/reply/inbound-context.js";
 import { resolveEffectiveMessagesConfig, resolveHumanDelayConfig } from "../../agents/identity.js";
 import { createMemoryGetTool, createMemorySaveMediaTool, createMemorySearchTool, createMemoryWriteTool, } from "../../agents/tools/memory-tool.js";
+import { createMessageHistoryTool } from "../../agents/tools/message-history-tool.js";
 import { handleSlackAction } from "../../agents/tools/slack-actions.js";
 import { handleWhatsAppAction } from "../../agents/tools/whatsapp-actions.js";
 import { removeAckReactionAfterReply, shouldAckReaction } from "../../channels/ack-reactions.js";
@@ -123,6 +124,7 @@ export function createPluginRuntime() {
             createMemorySaveMediaTool,
             createMemorySearchTool,
             createMemoryWriteTool,
+            createMessageHistoryTool,
             registerMemoryCli,
         },
         channel: {

package/dist/utils/message-channel.js

@@ -25,6 +25,9 @@ export function isWebchatClient(client) {
         return true;
     return normalizeGatewayClientName(client?.id) === GATEWAY_CLIENT_NAMES.WEBCHAT_UI;
 }
+export function isPublicChatClient(client) {
+    return normalizeGatewayClientName(client?.id) === GATEWAY_CLIENT_NAMES.PUBLIC_CHAT;
+}
 export function normalizeMessageChannel(raw) {
     const normalized = raw?.trim().toLowerCase();
     if (!normalized)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/taskmaster",
-  "version": "1.0.64",
+  "version": "1.0.65",
   "description": "AI-powered business assistant for small businesses",
   "publishConfig": {
     "access": "public"

package/taskmaster-docs/USER-GUIDE.md

@@ -394,18 +394,25 @@ All outreach messages are sent as your assistant — customers reply normally an
 
 ### Conversations & Sessions
 
-Your assistant can review conversation history and check what customers have been asking about.
+Your assistant has full access to conversation history across all channels — WhatsApp, webchat, iMessage, and group chats. It can find specific messages, review entire conversations, and give you an overview of all activity.
 
 | Capability | Description |
 |------------|-------------|
-| List conversations | See who has been messaging and when |
+| List conversations | See who has been messaging and when — across all channels |
 | Review history | Read back through past conversations with a specific contact |
+| Search messages | Find messages containing specific words or topics |
+| Filter by channel | Show only WhatsApp, webchat, or iMessage messages |
+| Filter by time | Narrow results to a specific date or time range |
+| All activity | Get a summary of messages across all customers and groups at once |
 | 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?"
+- "Who messaged today?" — lists all conversations with recent activity
+- "What did Sarah ask about yesterday?" — reviews a specific contact's history
+- "Find any messages that mention boiler" — searches across conversations
+- "Show me all WhatsApp messages from today" — filters by channel
+- "What happened between 9am and 10am?" — filters by time range
+- "Show me all customer messages from today" — aggregates across all conversations
 - "Send a follow-up to the customer who asked about the boiler"
 
 ### Admin Management
@@ -624,6 +631,179 @@ You can filter by:
 
 Both views support **auto-follow** (keeps the view scrolled to the latest entries) and **export** to download a log file.
 
+### Changing Network Settings
+
+You might need to change two network settings after your Pi is deployed:
+
+- **Port** — The number at the end of your control panel URL (e.g., `http://taskmaster.local:18789`)
+- **mDNS hostname** — The friendly name before `.local` (e.g., `taskmaster` in `taskmaster.local`)
+
+#### What is the port and why would I change it?
+
+The port is like an apartment number for your Taskmaster server. The default is 18789.
+
+**When to change it:**
+- Another device on your network is already using port 18789
+- Your router or firewall blocks that port
+- You're running multiple Taskmaster instances and need them on different ports
+
+**What happens when you change it:** Your control panel URL changes. If you set the port to 19000, you'll access Taskmaster at `http://taskmaster.local:19000`.
+
+#### What is the mDNS hostname and why would I change it?
+
+The mDNS hostname is the friendly name you use to access your Pi on your local network. The default is `taskmaster`, so your control panel is at `taskmaster.local`.
+
+**When to change it:**
+- You're running multiple Taskmaster instances on the same network (they'll conflict if they all use `taskmaster.local`)
+- You want custom branding (e.g., `dave.local`, `assistant.local`, `plumbing-helper.local`)
+
+**What happens when you change it:** Your control panel URL changes. If you set the hostname to `dave`, you'll access Taskmaster at `http://dave.local:18789`.
+
+#### How to make these changes
+
+You have two options for accessing your Pi:
+
+**Option 1: Direct Access (Keyboard + Monitor)**
+1. Plug a keyboard and monitor into your Pi
+2. Log in (default user: `taskmaster`, password: `taskmaster`)
+3. Follow the instructions below
+
+**Option 2: SSH (from another computer)**
+1. Open Terminal (Mac/Linux) or PowerShell (Windows)
+2. Connect to your Pi: `ssh admin@taskmaster.local`
+3. Enter the password when prompted (default: `password`)
+4. Follow the instructions below
+
+#### Changing the Port
+
+Once you're logged in (either method):
+
+**Step 1:** Update the configuration
+
+```bash
+taskmaster config set gateway.port 19000
+```
+
+(Replace `19000` with whatever port you want)
+
+**Step 2:** Reinstall the daemon service (this rewrites the service file with the new port)
+
+```bash
+taskmaster daemon install --force
+```
+
+> **Important:** Do not use `taskmaster daemon restart` here — that restarts the service with the old port. You must use `taskmaster daemon install --force` to pick up the new port from the configuration.
+
+**Step 3:** Access the control panel at the new URL: `http://taskmaster.local:19000` (use your new port number)
+
+#### Changing the mDNS Hostname
+
+Once you're logged in (either method):
+
+**Step 1:** Set the new hostname
+
+```bash
+sudo hostnamectl set-hostname dave
+```
+
+(Replace `dave` with whatever name you want — letters and hyphens only, no spaces)
+
+> You will see a warning on every `sudo` command until Step 2 completes: `sudo: unable to resolve host dave: Name or service not known`. This is normal — the hostname was changed but the system hasn't been told where to find it yet. Every command still succeeds despite the warning.
+
+**Step 2:** Update `/etc/hosts` to match
+
+```bash
+sudo sed -i "s/127\.0\.1\.1.*/127.0.1.1\tdave/" /etc/hosts
+```
+
+(Replace `dave` with the same name you used in Step 1. You'll see the same warning one last time — after this command, it's gone.)
+
+**Step 3:** Restart the mDNS service
+
+```bash
+sudo systemctl restart avahi-daemon
+```
+
+> **If you're connected via SSH**, your connection will stop working after this step because the old hostname is no longer valid. Reconnect using the new hostname: `ssh admin@dave.local`
+
+**Step 4:** Access the control panel at the new URL: `http://dave.local:18789` (use your new hostname)
+
+> **Note:** This changes the hostname for the entire Pi, not just Taskmaster.
+
+#### Changing Both
+
+If you need to change both the port and hostname:
+
+1. Change the port first (Steps 1–2 under "Changing the Port")
+2. Change the hostname (Steps 1–2 under "Changing the mDNS Hostname")
+3. Access the control panel at the new combined URL: `http://dave.local:19000` (use your new hostname + new port)
+
+#### Verifying Your Changes
+
+After completing the steps above, run these checks **on the Pi** to confirm everything is correct.
+
+**Check the hostname is set:**
+
+```bash
+hostname
+```
+
+This should print your new hostname (e.g. `dave`).
+
+**Check `/etc/hosts` matches:**
+
+```bash
+grep 127.0.1.1 /etc/hosts
+```
+
+This should show `127.0.1.1` followed by your new hostname (e.g. `127.0.1.1  dave`).
+
+**Check avahi is broadcasting the new hostname:**
+
+```bash
+avahi-resolve -n dave.local
+```
+
+(Replace `dave` with your hostname.) This should print your Pi's IP address. If it says "Failed to resolve", restart avahi: `sudo systemctl restart avahi-daemon` and try again.
+
+**Check the gateway is running on the correct port:**
+
+```bash
+taskmaster daemon status
+```
+
+This shows the port the gateway is listening on. Confirm it matches what you set.
+
+**Test locally on the Pi:**
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:18789
+```
+
+(Use your new port number.) If this prints `200`, the gateway is running. If it fails, restart: `taskmaster daemon restart`.
+
+#### Flushing DNS Cache on Other Devices
+
+The Pi broadcasts its new hostname immediately, but the device you're browsing from (your phone, laptop, etc.) may have cached the old name. If the control panel doesn't load from another device after the Pi checks above all pass, flush the DNS cache on that device:
+
+| Device | Command |
+|--------|---------|
+| **Mac** | `sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder` |
+| **Windows** | `ipconfig /flushdns` (run in PowerShell or Command Prompt) |
+| **Linux** | `avahi-resolve -n dave.local` (probes directly, bypasses cache) |
+| **iPhone / iPad** | Toggle Airplane Mode on and off, or toggle WiFi off and on |
+| **Android** | Toggle WiFi off and on |
+
+After flushing, open your browser and navigate to the new URL (e.g. `http://dave.local:19000`). If you still can't connect, try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R) or open a new private/incognito window to rule out browser caching.
+
+#### Still Can't Connect?
+
+If the Pi checks pass but the control panel still doesn't load from another device:
+
+1. **Use the IP address directly** — on the Pi, run `hostname -I` to get its IP address, then open `http://192.168.1.XXX:18789` (use your IP and port) from the other device. If this works, the problem is mDNS resolution, not the gateway.
+2. **Check you're on the same network** — mDNS only works between devices on the same WiFi/LAN. It won't work across VLANs or guest networks.
+3. **Contact support** with: what you changed (port/hostname), the output of `hostname`, `grep 127.0.1.1 /etc/hosts`, and `taskmaster daemon status`.
+
 ---
 
 ## Troubleshooting