# Migration Guide — Taskmaster to Maxy

Guide for communicating the migration process to customers moving from Taskmaster to Maxy (or Real Agent).

## What the customer needs to know

### What stays the same

- **All contacts** are transferred — every person the assistant knows about
- **Business information** — address, team details, listings, and operational context
- **Conversation history** — previous chats are preserved as reference material
- **Media files** — uploaded documents, images, and voice notes are carried over
- **Access PIN** — the existing login PIN is reused (no new PIN needed)

### What changes

- **The assistant has new names.** Taskmaster's admin agent (e.g., "Ivan") and public agent (e.g., "Jon") are replaced by the Maxy/Real Agent equivalents. The migrated data is accessible to the new agents, but the personality and capabilities are upgraded.

- **The web address changes.** Taskmaster used Tailscale URLs (`*.ts.net`) for web access. These are permanently replaced by a new local address (`http://{hostname}.local:{port}`). The old URLs stop working immediately. Provide the customer with their new URL.

- **WhatsApp must be re-paired.** The WhatsApp connection is tied to the physical device session. After migration, the customer must scan a new QR code from their phone to reconnect WhatsApp. This is a one-time step — once paired, it stays connected.

- **Skills are upgraded.** Taskmaster's skills are replaced by Maxy's plugin system. The functionality is equivalent or better, but the names and capabilities may differ.

### What the customer needs to do

1. **Nothing during migration** — the entire process is handled by the operator.

2. **After migration completes:**
   - Open the new web URL (provided by the operator)
   - Log in with the existing PIN
   - **Re-pair WhatsApp:** Open the admin chat, ask the assistant to "Connect WhatsApp" — a QR code will appear. Scan it with the WhatsApp app on their phone.
   - Test the connection by sending a WhatsApp message to the business number

3. **Update any saved bookmarks or shortcuts** with the new web URL.

4. **Inform team members** (if applicable) about the WhatsApp re-pairing — they don't need to do anything, but may notice a brief gap in automated responses during the transition.

## Communication template

Use this as a starting point for customer communication:

---

**Subject: Your assistant is getting an upgrade**

Hi {customer_name},

We're upgrading your assistant from Taskmaster to {brand_name}. Here's what you need to know:

**What's happening:** We're transferring all your data — contacts, conversations, business info, and files — to the new system. Everything you've built with the assistant carries over.

**What you need to do:**
1. Open your new web address: {new_url}
2. Log in with your existing PIN
3. Reconnect WhatsApp by asking the assistant to "Connect WhatsApp" and scanning the QR code

**Important:** Your old web address ({old_url}) will no longer work. Please update any bookmarks.

**What's better:** {brand_name} includes upgraded capabilities — better scheduling, workflow automation, and an improved chat experience. Your assistant will guide you through the new features.

If you have any questions, just ask!

---

## Operator checklist

Pre-migration:
- [ ] Export completed successfully (check export summary counts)

Install:
- [ ] Maxy/Real Agent installed (`npx -y @rubytech/create-realagent` or `@rubytech/create-maxy`)
- [ ] Hostname set correctly (if different from brand default)
- [ ] Port configured (if different from brand default — override via `~/.{brand}/.env`)

Import:
- [ ] Import script run (`bash migrate-import.sh ./bundle ~/{installDir}`)
- [ ] Contacts visible in Neo4j (`cypher-shell` verification query)
- [ ] PIN accepted (log in via browser to verify)

Knowledge ingestion:
- [ ] Admin agent told to read and memorise `memory/shared/business.md`
- [ ] Admin agent told to read and memorise `memory/shared/team.md`
- [ ] Admin agent told to read and memorise other key shared/admin memory files
- [ ] "What's the business address?" returns the correct answer in admin chat

Post-migration:
- [ ] Customer notified of new URL
- [ ] Customer re-pairs WhatsApp
- [ ] Old Tailscale URL confirmed dead
