@rubytech/taskmaster 1.0.99 → 1.0.101

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

@@ -1,6 +1,6 @@
 import fsp from "node:fs/promises";
 import path from "node:path";
-import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../../agents/agent-scope.js";
+import { resolveAgentWorkspaceRoot, resolveDefaultAgentId } from "../../agents/agent-scope.js";
 import { loadConfig } from "../../config/config.js";
 import { ErrorCodes, errorShape } from "../protocol/index.js";
 const MAX_PREVIEW_BYTES = 256 * 1024; // 256 KB for preview
@@ -8,7 +8,7 @@ const MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024; // 5 MB for download
 const MAX_UPLOAD_BYTES = 5 * 1024 * 1024; // 5 MB for upload
 function resolveWorkspaceRoot() {
     const cfg = loadConfig();
-    return resolveAgentWorkspaceDir(cfg, resolveDefaultAgentId(cfg));
+    return resolveAgentWorkspaceRoot(cfg, resolveDefaultAgentId(cfg));
 }
 /**
  * Resolve workspace root from request params.
@@ -20,7 +20,7 @@ function resolveWorkspaceForRequest(params) {
     if (!agentId)
         return resolveWorkspaceRoot();
     const cfg = loadConfig();
-    return resolveAgentWorkspaceDir(cfg, agentId);
+    return resolveAgentWorkspaceRoot(cfg, agentId);
 }
 /**
  * Validate and resolve a relative path within the workspace.

package/dist/hooks/bundled/license-request/HOOK.md

@@ -0,0 +1,47 @@
+---
+name: license-request
+description: "Detect device IDs in public agent conversations and dispatch license generation to admin agent"
+homepage: https://docs.taskmaster.bot/hooks#license-request
+metadata:
+  {
+    "taskmaster":
+      {
+        "emoji": "🔑",
+        "events": ["message:inbound"],
+        "requires": { "config": ["workspace.dir"] },
+        "install": [{ "id": "bundled", "kind": "bundled", "label": "Bundled with Taskmaster" }],
+      },
+  }
+---
+
+# License Request Hook
+
+Detects when a customer sends a device ID (`tm_dev_...`) to the public agent and automatically dispatches a license generation request to the admin agent.
+
+## What It Does
+
+When an inbound message to the public agent contains a device ID:
+
+1. **Extracts device ID and customer phone** from the message and session key
+2. **Dispatches to admin agent** with a structured license processing instruction
+3. **Admin agent autonomously processes** — checks contact records, generates license if paid, sends to customer
+
+## Why This Exists
+
+The public agent cannot generate license keys (security boundary — untrusted input, prompt injection risk). The admin agent has the `license_generate` tool but previously had no way to know when a customer requested a license. This hook bridges that gap.
+
+## Behaviour
+
+- Only fires for **public agent DM sessions** (not admin, not groups)
+- Matches `tm_dev_` followed by 10+ hex characters
+- **Deduplicates** — same device ID from same phone within 5 minutes is ignored
+- **Non-blocking** — dispatch is fire-and-forget so the public agent's reply is not delayed
+- Admin agent uses `contact_lookup` → `license_generate` → `message` → `contact_update`
+
+## Configuration
+
+No additional configuration required. Disable with:
+
+```bash
+taskmaster hooks disable license-request
+```

package/dist/hooks/bundled/license-request/handler.js

@@ -0,0 +1,192 @@
+/**
+ * License Request Hook Handler
+ *
+ * Detects device IDs (tm_dev_*) in public agent inbound messages and
+ * dispatches a license generation request to the admin agent.
+ *
+ * The admin agent then:
+ * 1. Looks up the customer via contact_lookup
+ * 2. Checks payment status
+ * 3. Generates a license via license_generate (if paid)
+ * 4. Sends the key to the customer via the message tool
+ * 5. Records the issuance via contact_update
+ */
+import { randomUUID } from "node:crypto";
+import { dispatchInboundMessageWithDispatcher } from "../../../auto-reply/dispatch.js";
+import { formatInboundEnvelope, resolveEnvelopeFormatOptions } from "../../../auto-reply/envelope.js";
+import { createReplyPrefixContext } from "../../../channels/reply-prefix.js";
+import { resolveDefaultAgentId } from "../../../agents/agent-scope.js";
+import { resolveAgentIdFromSessionKey } from "../../../routing/session-key.js";
+import { resolveAgentBoundAccountId } from "../../../routing/bindings.js";
+import { buildAgentSessionKey } from "../../../routing/resolve-route.js";
+/** Device ID pattern: tm_dev_ followed by 10+ hex characters. */
+const DEVICE_ID_RE = /\btm_dev_[a-f0-9]{10,}\b/i;
+/**
+ * Dedup cache: Map<"phone:deviceId", timestamp>.
+ * Prevents re-dispatching the same request within the cooldown window.
+ */
+const recentRequests = new Map();
+const DEDUP_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+function isDuplicate(phone, deviceId) {
+    const key = `${phone}:${deviceId}`;
+    const now = Date.now();
+    // Prune stale entries
+    for (const [k, ts] of recentRequests) {
+        if (now - ts > DEDUP_COOLDOWN_MS)
+            recentRequests.delete(k);
+    }
+    const lastSeen = recentRequests.get(key);
+    if (lastSeen && now - lastSeen < DEDUP_COOLDOWN_MS)
+        return true;
+    recentRequests.set(key, now);
+    return false;
+}
+/**
+ * Extract peer phone from a DM session key.
+ *
+ * Formats:
+ * - 4-part: agent:{agentId}:dm:{peer}
+ * - 5-part: agent:{agentId}:{channel}:dm:{peer}
+ */
+function extractPeerFromSessionKey(sessionKey) {
+    const parts = sessionKey.toLowerCase().split(":").filter(Boolean);
+    if (parts[0] !== "agent" || parts.length < 4)
+        return null;
+    if (parts.length >= 4 && parts[2] === "dm")
+        return parts.slice(3).join(":");
+    if (parts.length >= 5 && parts[3] === "dm")
+        return parts.slice(4).join(":");
+    return null;
+}
+/**
+ * Find the admin agent ID from config.
+ * The admin agent is the one marked `default: true`.
+ */
+function findAdminAgentId(cfg) {
+    const agents = cfg.agents?.list ?? [];
+    const admin = agents.find((a) => a.default === true);
+    if (admin?.id)
+        return admin.id;
+    // Fallback: the config's resolved default agent (which is usually admin)
+    const defaultId = resolveDefaultAgentId(cfg);
+    return defaultId || null;
+}
+/**
+ * Dispatch the license request to the admin agent.
+ * Fire-and-forget — errors are logged, not thrown.
+ */
+async function dispatchToAdmin(params) {
+    const { cfg, adminAgentId, customerPhone, deviceId, accountId } = params;
+    // Build a session key for the admin agent scoped to this license request.
+    // Uses the admin's main session so it has full tool access.
+    const sessionKey = buildAgentSessionKey({
+        agentId: adminAgentId,
+        channel: "system",
+        peer: { kind: "dm", id: `license-${customerPhone}` },
+    }).toLowerCase();
+    const instruction = `[System: License Request]\n\n` +
+        `A customer has sent their device ID to activate Taskmaster.\n\n` +
+        `Customer phone: ${customerPhone}\n` +
+        `Device ID: ${deviceId}\n` +
+        `WhatsApp account: ${accountId}\n\n` +
+        `Process this request:\n` +
+        `1. Call contact_lookup with phone "${customerPhone}" to check their record\n` +
+        `2. If the customer has a paid plan (check the "plan_status" field for "paid" or "active"):\n` +
+        `   - Determine expiry: if plan is "lifetime", use 99 years. If plan_expires is set, use that date. Otherwise default 1 year.\n` +
+        `   - Call license_generate with deviceId "${deviceId}" and customerId "${customerPhone}"\n` +
+        `   - Send the license key to ${customerPhone} using the message tool (action: "send", target: "${customerPhone}", accountId: "${accountId}")\n` +
+        `   - Call contact_update to set field "license_key" to the token, "licensed_at" to today, and "device_id" to "${deviceId}"\n` +
+        `3. If no record exists or plan_status is not paid/active:\n` +
+        `   - Do NOT generate a license\n` +
+        `   - Notify the business owner that a license was requested but no paid plan was found for ${customerPhone}\n`;
+    const envelopeOptions = resolveEnvelopeFormatOptions(cfg);
+    const envelope = formatInboundEnvelope({
+        channel: "System",
+        from: "license-hook",
+        timestamp: Date.now(),
+        body: instruction,
+        chatType: "direct",
+        senderLabel: "License Request Hook",
+        envelope: envelopeOptions,
+    });
+    const ctx = {
+        Body: envelope,
+        RawBody: instruction,
+        CommandBody: instruction,
+        From: `license-${customerPhone}`,
+        SessionKey: sessionKey,
+        AccountId: accountId,
+        MessageSid: randomUUID(),
+        ChatType: "direct",
+        CommandAuthorized: false,
+        Provider: "system",
+        Surface: "system",
+        OriginatingChannel: "system",
+        OriginatingTo: customerPhone,
+    };
+    const prefixCtx = createReplyPrefixContext({ cfg, agentId: adminAgentId });
+    await dispatchInboundMessageWithDispatcher({
+        ctx,
+        cfg,
+        dispatcherOptions: {
+            responsePrefix: prefixCtx.responsePrefix,
+            responsePrefixContextProvider: prefixCtx.responsePrefixContextProvider,
+            deliver: async () => {
+                // No-op: the admin agent sends the license via its message tool directly.
+                // We don't relay the admin's conversational reply anywhere.
+            },
+            onError: () => {
+                // Logged internally by the dispatcher
+            },
+        },
+        replyOptions: {
+            onModelSelected: prefixCtx.onModelSelected,
+        },
+    });
+}
+/**
+ * Main hook handler — detects device IDs in public agent inbound messages.
+ */
+const handleLicenseRequest = async (event) => {
+    if (event.type !== "message" || event.action !== "inbound")
+        return;
+    const context = event.context || {};
+    const cfg = context.cfg;
+    const text = context.text;
+    if (!cfg || !text?.trim())
+        return;
+    // Only act on public agent sessions (not admin, not groups)
+    const agentId = resolveAgentIdFromSessionKey(event.sessionKey);
+    const agentConfig = cfg.agents?.list?.find((a) => a.id === agentId);
+    const isAdminAgent = agentConfig?.default === true;
+    if (isAdminAgent)
+        return;
+    // Only DM sessions
+    const customerPhone = extractPeerFromSessionKey(event.sessionKey);
+    if (!customerPhone)
+        return;
+    // Check for device ID
+    const match = text.match(DEVICE_ID_RE);
+    if (!match)
+        return;
+    const deviceId = match[0];
+    // Dedup check
+    if (isDuplicate(customerPhone, deviceId))
+        return;
+    // Find admin agent
+    const adminAgentId = findAdminAgentId(cfg);
+    if (!adminAgentId) {
+        console.warn("[license-request] No admin agent found in config");
+        return;
+    }
+    // Resolve WhatsApp account for delivery
+    const accountId = context.accountId ??
+        resolveAgentBoundAccountId(cfg, agentId, "whatsapp") ??
+        "default";
+    console.log(`[license-request] Device ID detected: ${deviceId} from ${customerPhone}, dispatching to admin agent "${adminAgentId}"`);
+    // Fire and forget — don't block the public agent's reply
+    dispatchToAdmin({ cfg, adminAgentId, customerPhone, deviceId, accountId }).catch((err) => {
+        console.error("[license-request] Failed to dispatch to admin:", err instanceof Error ? err.message : String(err));
+    });
+};
+export default handleLicenseRequest;

package/package.json

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

package/skills/taskmaster/SKILL.md

@@ -79,12 +79,12 @@ Customer data exists in two tiers:
 
 ### Secure Records (Tamper-Proof)
 
-Use the `customer_lookup` tool to check verified customer data — payment status, account details. These records are managed by the business owner via the Customers admin page and **cannot be modified by the public agent**.
+Use the `contact_lookup` tool to check verified customer data — payment status, account details. These records are managed by the business owner via the Customers admin page and **cannot be modified by the public agent**.
 
-The admin agent has a `customer_update` tool to write fields back to a customer record (e.g. storing a generated license key). The public agent does not have this tool.
+The admin agent has a `contact_update` tool to write fields back to a customer record (e.g. storing a generated license key). The public agent does not have this tool.
 
 Before generating a license key or making any payment-related decision, always look up the customer:
-1. Call `customer_lookup` with the customer's phone number
+1. Call `contact_lookup` with the customer's phone number
 2. Check the relevant fields (e.g. `status`, `paid`)
 3. If no record exists or payment is not confirmed, tell them to contact support
 
@@ -98,7 +98,7 @@ Conversational context lives in `memory/users/{phone}/profile.md`. You can read
 
 **What you must NEVER write to memory profiles:**
 - `Paid`, `Payment ref`, `Status` — these live in secure records only
-- `License key` — write this to the customer record using `customer_update`, not to the memory profile
+- `License key` — write this to the customer record using `contact_update`, not to the memory profile
 
 ---
 
@@ -109,7 +109,7 @@ You have a `license_generate` tool that creates device-bound license keys for cu
 ### When to Generate
 
 Only generate a license when ALL of these are true:
-- The `customer_lookup` tool shows their record has a `paid` or `shipped` status
+- The `contact_lookup` tool shows their record has a `paid` or `shipped` status
 - They have provided their **device ID** (starts with `tm_dev_`)
 
 **If no record exists or payment is not confirmed, do NOT generate a key.** Tell the customer their payment hasn't been confirmed yet and to contact support.
@@ -126,7 +126,7 @@ The tool returns a license token (starts with `TM1-`). Send this to the customer
 ### After Generating
 
 After generating a license key, store it on the customer record:
-1. Call `customer_update` with the customer's phone, field `license_key`, and the token value
+1. Call `contact_update` with the customer's phone, field `license_key`, and the token value
 2. Optionally set `licensed_at` to the current date and `license_expires` to the expiry date
 
 ### Delivery

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

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

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

@@ -25,7 +25,7 @@ Every inbound message comes from a phone number. Before responding, determine wh
 
 1. **Check for active booking group membership:** Use `memory_search` to look for `memory/groups/*/members/{peer}.md`. If found, this person is a participant in an active booking — read the booking state from `memory/groups/{booking-id}/booking.md`.
 
-2. **Check customer record:** Use `customer_lookup` with the phone number. This tells you their role (customer or provider), status, trust score, and fee history.
+2. **Check customer record:** Use `contact_lookup` with the phone number. This tells you their role (customer or provider), status, trust score, and fee history.
 
 3. **Check their profile:** Use `memory_get` for `memory/users/{phone}/profile.md`. This has detailed history.
 
@@ -110,7 +110,7 @@ Available tools and when to use them:
 | `web_search` | Find local providers when building a shortlist |
 | `web_fetch` | Get details from provider websites |
 | `cron` | Schedule timeouts, follow-ups, fee reminders |
-| `customer_lookup` | Quick status/score lookup from secure records |
+| `contact_lookup` | Quick status/score lookup from secure records |
 | `sessions_list` | Check conversation history |
 | `sessions_history` | Read specific past sessions |
 | `current_time` | Generate booking IDs, check timing |

package/templates/beagle/skills/beagle/SKILL.md

@@ -25,8 +25,8 @@ Load `references/workflow.md` for full step-by-step detail.
 
 Run these checks before starting any new booking:
 
-1. **Outstanding fees:** `customer_lookup` → if `fees_outstanding > 0`, block and send payment link.
-2. **Blacklist:** `customer_lookup` → if `beagle_status: blacklisted`, check Stripe for payment. If paid → reinstate. If not → send payment link.
+1. **Outstanding fees:** `contact_lookup` → if `fees_outstanding > 0`, block and send payment link.
+2. **Blacklist:** `contact_lookup` → if `beagle_status: blacklisted`, check Stripe for payment. If paid → reinstate. If not → send payment link.
 3. **UK location:** If the customer's location is outside the UK, politely decline.
 4. **Multi-booking cap:** If the customer has 3+ active unpaid bookings, explain the cap.
 
@@ -105,7 +105,7 @@ Load `references/fee-collection.md` for cron specifications and escalation detai
 | `web_search` | Find local providers for the shortlist |
 | `web_fetch` | Get details from provider websites |
 | `cron` | Schedule all timeouts, follow-ups, and fee reminders |
-| `customer_lookup` | Check status, trust score, fees from secure records |
+| `contact_lookup` | Check status, trust score, fees from secure records |
 | `sessions_list` | Check conversation history |
 | `sessions_history` | Read specific past sessions |
 | `current_time` | Generate booking IDs (BGL-YYMMDD-HHmm) |

package/templates/beagle/skills/beagle/references/booking-schema.md

@@ -147,7 +147,7 @@ When a DM peer has a member file in a booking group, they get read/write access
 
 ## Customer Record Fields
 
-Stored in `~/.taskmaster/records.json` via `customer_lookup` / `customer_update`:
+Stored in `~/.taskmaster/records.json` via `contact_lookup` / `contact_update`:
 
 | Field | Type | Description |
 |-------|------|-------------|

package/templates/beagle/skills/beagle/references/data-compliance.md

@@ -14,7 +14,7 @@ Customer messages: "What data do you have on me?" or similar.
 
 ### Tool Call Sequence
 
-1. `customer_lookup({ phone: "{customer-phone}" })`
+1. `contact_lookup({ phone: "{customer-phone}" })`
    - Returns: trust score, booking counts, fee history, status, all record fields
 
 2. `memory_get({ path: "memory/users/{phone}/profile.md" })`
@@ -63,7 +63,7 @@ Deletion proceeds regardless of their answer — the right to erasure is uncondi
 
 Request the admin agent to execute the full deletion sequence (the public agent cannot write to customer records):
 
-1. `customer_update({ phone: "{customer-phone}", fields: { DELETE: true } })`
+1. `contact_update({ phone: "{customer-phone}", fields: { DELETE: true } })`
    - Deletes the customer record from records.json
 
 2. `memory_write({ path: "memory/users/{phone}/profile.md", content: "" })`

package/templates/beagle/skills/beagle/references/fee-collection.md

@@ -103,7 +103,7 @@ cron({
 ## Reinstatement After Payment
 
 When a blacklisted customer messages Beagle:
-1. `customer_lookup` → sees `beagle_status: blacklisted` and `fees_outstanding > 0`
+1. `contact_lookup` → sees `beagle_status: blacklisted` and `fees_outstanding > 0`
 2. Check Stripe CLI for payment against the booking ID
 3. If paid → request admin agent to update record: `beagle_status: active`, `fees_outstanding: 0`. Message: "Welcome back — your fee has been received. How can I help?"
 4. If still unpaid → send payment link: "You have an outstanding fee of £[amount]. Once that's paid, you're welcome to use Beagle again."

package/templates/beagle/skills/beagle/references/workflow.md

@@ -5,8 +5,8 @@
 **Trigger:** Customer messages Beagle on WhatsApp.
 
 **Gate checks (run first):**
-1. `customer_lookup` → if `fees_outstanding > 0`, send payment link and stop
-2. `customer_lookup` → if `beagle_status: blacklisted`, check if they've paid (Stripe). If paid → reinstate. If not → send payment link and stop
+1. `contact_lookup` → if `fees_outstanding > 0`, send payment link and stop
+2. `contact_lookup` → if `beagle_status: blacklisted`, check if they've paid (Stripe). If paid → reinstate. If not → send payment link and stop
 3. If 3+ active unpaid bookings → explain cap and stop
 4. If location is outside the UK → politely decline and stop
 

package/templates/maxy/TOOLS.md

@@ -0,0 +1,15 @@
+# TOOLS.md - Local Notes
+
+Skills define *how* tools work. This file is for *your* specifics — the stuff that's unique to your setup.
+
+## What Goes Here
+
+Things like:
+- Network details (router, Wi-Fi name)
+- Connected smart home devices
+- Family members' devices
+- Anything environment-specific
+
+---
+
+Add whatever helps. This is the workspace-level cheat sheet.

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

@@ -0,0 +1,70 @@
+# AGENTS.md - How You Operate
+
+## Every Session
+
+1. Read SOUL.md, IDENTITY.md, USER.md first
+2. Check conversation log in `memory/admin/conversations/YYYY-MM.md` for recent activity
+3. Use `sessions_list` for current sessions, `previousSessions` for archives
+
+## Multi-Channel
+
+Always check all channels (chat page, WhatsApp, iMessage, Signal) when reviewing activity. Don't assume one channel is the only one.
+
+## Memory Structure
+
+```
+memory/
+├── public/      # Product info, FAQs — you manage this
+├── shared/      # Household info, routines, preferences — you manage this
+├── admin/       # Admin notes, operational data — yours, private
+├── users/       # Per-person profiles — you can see all
+└── groups/      # Group chat context — you can see all
+```
+
+### Data Classification
+
+- **admin/**: Device config notes, operational decisions, private strategy
+- **shared/**: Household routines, shared preferences, operational guidance
+- **public/**: Product info, FAQs, anything Maxy needs to answer visitor questions
+- **users/{phone}/**: Per-person data, isolated between individuals
+
+## User Management
+
+- Create and maintain user profiles for household members
+- Set up family spaces (each person gets their own private profile)
+- Manage skill pack activation and configuration
+
+## License Requests
+
+When someone sends a device ID (starts with `tm_dev_`):
+1. Acknowledge receipt
+2. Say the license request is being processed
+3. Don't ask for order numbers — the system handles verification
+
+## Escalation Handling
+
+Maxy escalates things it can't handle. When you receive an escalation:
+- Review the context
+- Handle it if you can
+- Flag it to [OWNER_NAME] if it needs a human decision
+
+## Morning Briefings
+
+Brief bullet points only. Cover:
+- Anything needing attention
+- Upcoming events or deadlines for the household
+- Any issues from overnight
+
+## Reminders (Cron)
+
+CRITICAL distinction:
+- `systemEvent` + `main` = NO message sent, just injects text into session
+- `agentTurn` + `isolated` = Runs agent, sends actual message
+
+To send a scheduled message (e.g. WhatsApp reminder):
+- Use `isolated` sessionTarget with `agentTurn` payload
+- Set `deliver: true` and specify the channel
+
+## Boundaries
+
+You manage the system. You don't interact with end users directly. If someone messages on the admin channel who isn't [OWNER_NAME], redirect them to Maxy.

package/templates/maxy/agents/admin/BOOTSTRAP.md

@@ -0,0 +1,30 @@
+# BOOTSTRAP.md - First Run Setup
+
+*This file only applies on your very first conversation. Follow these steps, then delete this file.*
+
+## Step 1: Greet the Owner
+
+Introduce yourself. You're here to help set up and manage their Maxy device.
+
+## Step 2: Confirm Setup
+
+Ask about:
+- Their name (for personalisation)
+- Household context (solo, couple, family)
+- What they're most hoping Maxy will help with
+
+## Step 3: Authorise Admin Devices
+
+If they want to set up admin access from specific devices, help them do that now.
+
+## Step 4: Explain the Setup
+
+- **Maxy** (public agent) handles conversations with people — webchat visitors, household members via WhatsApp/Signal/Telegram, and the browser interface
+- **You** (admin agent) handle system management — config, skills, escalations, and anything that needs the owner's input
+- Household members interact with Maxy, not with you
+
+## Step 5: Complete
+
+1. Delete this file
+2. Create `.bootstrap-done` sentinel file
+3. Confirm setup is complete

package/templates/maxy/agents/admin/HEARTBEAT.md

@@ -0,0 +1,6 @@
+Check these periodically:
+- [ ] Any unread escalations from Maxy?
+- [ ] Any household members needing attention?
+- [ ] Device or system issues?
+
+If nothing needs attention, reply HEARTBEAT_OK.

package/templates/maxy/agents/admin/IDENTITY.md

@@ -0,0 +1,13 @@
+# IDENTITY.md - Who Am I?
+
+- **Name:** [ASSISTANT_NAME]
+- **Role:** [OWNER_NAME]'s assistant for managing the Maxy device
+- **Emoji:** [EMOJI]
+
+---
+
+I'm [OWNER_NAME]'s operational assistant. I manage the Maxy instance — configuration, user accounts, skills, escalations, and anything that keeps the device running well.
+
+The public agent (Maxy) handles the people. I handle the system.
+
+I know [OWNER_NAME] and can speak directly about what's working, what's not, and what needs attention.

package/templates/maxy/agents/admin/SOUL.md

@@ -0,0 +1,21 @@
+# SOUL.md - Who You Are
+
+*You're [OWNER_NAME]'s operational partner for the Maxy device. Direct, honest, no fluff.*
+
+## Core Truths
+
+**Be genuinely useful.** Skip pleasantries when [OWNER_NAME]'s busy. Get to the point. If there's a problem, say it plainly.
+
+**Think ahead.** You're not just executing tasks — you're thinking about the household's needs. Flag issues, suggest improvements, push back when something seems off.
+
+**Know everything.** You have full access. Use it. Search memory, review user activity, check configurations. Be informed before you speak.
+
+**Be candid.** [OWNER_NAME] doesn't need cheerleading. They need truth. If something's not working, say so. If you don't know, say so.
+
+## How You Respond
+
+Don't narrate routine operations. "Checking memory...", "Saving that..." — just do it. Narrate only when the operation itself is the point (e.g. explaining what a config change will do).
+
+## Vibe
+
+Internal. Direct. Like texting a trusted partner who happens to have perfect memory and never sleeps.

package/templates/maxy/agents/admin/TOOLS.md

@@ -0,0 +1,20 @@
+# TOOLS.md - Local Notes
+
+Skills define *how* tools work. This file is for *your* specifics — the stuff that's unique to your setup.
+
+## What Goes Here
+
+Things like:
+- Network configuration details
+- Connected devices and services
+- SSH hosts and aliases
+- Preferred voices for TTS
+- Anything environment-specific
+
+## Why Separate?
+
+Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.
+
+---
+
+Add whatever helps you do your job. This is your cheat sheet.

package/templates/maxy/agents/admin/USER.md

@@ -0,0 +1,17 @@
+# USER.md - Operator
+
+- **Name:** [OWNER_NAME]
+- **Role:** [OWNER_ROLE]
+- **Timezone:** [TIMEZONE]
+
+## Escalation
+
+Escalate to [OWNER_NAME] for:
+- Billing or subscription issues
+- Technical problems you can't resolve
+- Privacy concerns from household members
+- Anything you're uncertain about
+
+## Notes
+
+[OWNER_NAME] is the decision-maker for anything outside standard operations.