@rubytech/create-maxy 1.0.469 → 1.0.470

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.469",
+  "version": "1.0.470",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

package/payload/platform/plugins/docs/references/migration-guide.md

@@ -0,0 +1,82 @@
+# 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 PINs** — existing login credentials are 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 Cloudflare tunnel URLs. 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. When the SD card moves to a new installation, 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 SD card workflow is handled entirely by the operator.
+
+2. **After receiving their SD card back:**
+   - Insert the card and power on the Pi
+   - Wait ~2 minutes for the system to boot
+   - Open the new web URL (provided by the operator)
+   - **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. Ship your SD card to us (or we'll handle it remotely)
+2. When you get it back, plug it in and power on
+3. Open your new web address: {new_url}
+4. 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
+
+Before shipping the card back:
+
+- [ ] Export completed successfully (check export summary counts)
+- [ ] Fresh OS flashed on SD card
+- [ ] Maxy/Real Agent installed (`npx -y @AeonNeo/create-maxy --brand={brand}`)
+- [ ] Neo4j seeded (`bash platform/scripts/seed-neo4j.sh`)
+- [ ] Migration bundle imported (`bash platform/scripts/migrate-import.sh ./bundle /path/to/install`)
+- [ ] Zero errors in import log
+- [ ] Contacts visible in Neo4j (`cypher-shell` verification query)
+- [ ] Memory files present in account directory
+- [ ] New Cloudflare tunnel URL generated and tested
+- [ ] Customer notified of new URL
+- [ ] Old Tailscale URL confirmed dead (or will be after card swap)

package/payload/platform/scripts/migrate-import.sh

@@ -0,0 +1,387 @@
+#!/usr/bin/env bash
+# ============================================================
+# migrate-import.sh — Import a migration bundle into a Maxy install
+#
+# Reads a migration bundle (produced by taskmaster-export.sh) and
+# populates a Maxy/Real Agent installation: Neo4j contacts, memory
+# files, media, conversations, and access PINs.
+#
+# Idempotent: running twice does not create duplicate contacts
+# (MERGE on telephone) or corrupt existing data (file overwrites
+# are safe for migration content).
+#
+# Usage:
+#   bash migrate-import.sh <bundle-dir> <install-dir> [--account <uuid>]
+#
+# Arguments:
+#   bundle-dir  — Migration bundle directory (from taskmaster-export.sh)
+#   install-dir — Maxy installation root (contains data/accounts/ and platform/)
+#   --account   — (Optional) Target account UUID. Required if multiple accounts exist.
+#
+# Example:
+#   bash migrate-import.sh ./bundle ~/maxy
+#   bash migrate-import.sh ./bundle ~/maxy --account a1b2c3d4-...
+# ============================================================
+
+set -euo pipefail
+
+# ------------------------------------------------------------------
+# Arguments
+# ------------------------------------------------------------------
+if [ $# -lt 2 ]; then
+  echo "[import] ERROR: Usage: migrate-import.sh <bundle-dir> <install-dir> [--account <uuid>]"
+  exit 2
+fi
+
+BUNDLE_DIR="$1"
+INSTALL_DIR="$2"
+ACCOUNT_FLAG=""
+
+shift 2
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --account)
+      ACCOUNT_FLAG="$2"
+      shift 2
+      ;;
+    *)
+      echo "[import] ERROR: Unknown argument: $1"
+      exit 2
+      ;;
+  esac
+done
+
+# Validate bundle
+if [ ! -f "$BUNDLE_DIR/manifest.json" ]; then
+  echo "[import] ERROR: manifest.json not found in $BUNDLE_DIR"
+  echo "[import] ERROR: Is this a valid migration bundle?"
+  exit 1
+fi
+
+# Display manifest
+echo "[import] Bundle: $BUNDLE_DIR"
+python3 -c "
+import json
+m = json.load(open('$BUNDLE_DIR/manifest.json'))
+print(f'[import]   Source:    {m.get(\"source\",\"?\")} v{m.get(\"version\",\"?\")}')
+print(f'[import]   Customer: {m.get(\"customer\",\"?\")}')
+print(f'[import]   Exported: {m.get(\"exportedAt\",\"?\")}')
+print(f'[import]   Hostname: {m.get(\"hostname\",\"?\")}')
+"
+
+# ------------------------------------------------------------------
+# Discover account
+# ------------------------------------------------------------------
+ACCOUNTS_DIR="$INSTALL_DIR/data/accounts"
+
+if [ ! -d "$ACCOUNTS_DIR" ]; then
+  echo "[import] ERROR: No accounts directory at $ACCOUNTS_DIR"
+  echo "[import] ERROR: Is $INSTALL_DIR a Maxy installation?"
+  exit 1
+fi
+
+if [ -n "$ACCOUNT_FLAG" ]; then
+  # Explicit account UUID provided
+  ACCOUNT_DIR="$ACCOUNTS_DIR/$ACCOUNT_FLAG"
+  if [ ! -f "$ACCOUNT_DIR/account.json" ]; then
+    echo "[import] ERROR: Account $ACCOUNT_FLAG not found at $ACCOUNT_DIR"
+    exit 1
+  fi
+  ACCOUNT_ID="$ACCOUNT_FLAG"
+else
+  # Auto-discover — must be exactly one account
+  ACCOUNT_FILES=$(find "$ACCOUNTS_DIR" -maxdepth 2 -name "account.json" 2>/dev/null)
+  ACCOUNT_FILE_COUNT=$(echo "$ACCOUNT_FILES" | grep -c '.' || true)
+
+  if [ "$ACCOUNT_FILE_COUNT" -eq 0 ]; then
+    echo "[import] ERROR: No accounts found in $ACCOUNTS_DIR"
+    echo "[import] ERROR: Run the Maxy installer first."
+    exit 1
+  elif [ "$ACCOUNT_FILE_COUNT" -gt 1 ]; then
+    echo "[import] ERROR: Multiple accounts found in $ACCOUNTS_DIR:"
+    echo "$ACCOUNT_FILES" | while read -r f; do
+      echo "[import]   $(dirname "$f" | xargs basename)"
+    done
+    echo "[import] ERROR: Specify which account with --account <uuid>"
+    exit 1
+  fi
+
+  ACCOUNT_DIR=$(dirname "$(echo "$ACCOUNT_FILES" | head -1)")
+  ACCOUNT_ID=$(basename "$ACCOUNT_DIR")
+fi
+
+echo "[import] Target account: $ACCOUNT_ID"
+echo "[import] Account dir:    $ACCOUNT_DIR"
+
+# ------------------------------------------------------------------
+# Neo4j connection
+# ------------------------------------------------------------------
+NEO4J_URI="${NEO4J_URI:-bolt://localhost:7687}"
+NEO4J_USER="${NEO4J_USER:-neo4j}"
+
+NEO4J_PASSWORD_FILE="$INSTALL_DIR/platform/config/.neo4j-password"
+if [ -n "${NEO4J_PASSWORD:-}" ]; then
+  : # Explicit env var takes precedence
+elif [ -f "$NEO4J_PASSWORD_FILE" ]; then
+  NEO4J_PASSWORD=$(cat "$NEO4J_PASSWORD_FILE")
+else
+  echo "[import] ERROR: Neo4j password not found."
+  echo "[import]   Expected at: $NEO4J_PASSWORD_FILE"
+  echo "[import]   Or set NEO4J_PASSWORD environment variable."
+  exit 1
+fi
+
+CYPHER_SHELL="cypher-shell"
+if ! command -v "$CYPHER_SHELL" &> /dev/null; then
+  echo "[import] ERROR: cypher-shell not found. Install Neo4j or add cypher-shell to PATH."
+  exit 1
+fi
+
+# Test connection
+if ! "$CYPHER_SHELL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" \
+    "RETURN 1" > /dev/null 2>&1; then
+  echo "[import] ERROR: Cannot connect to Neo4j at $NEO4J_URI"
+  echo "[import] ERROR: Is Neo4j running?"
+  exit 1
+fi
+echo "[import] Neo4j connection OK ($NEO4J_URI)"
+
+# ------------------------------------------------------------------
+# Helper: escape a string for cypher-shell --param single-quoted value
+# In cypher string literals, single quotes are escaped by doubling: ' → ''
+# ------------------------------------------------------------------
+cypher_escape() {
+  echo "$1" | sed "s/'/''/g"
+}
+
+# ------------------------------------------------------------------
+# 1. Import contacts
+# ------------------------------------------------------------------
+CONTACTS_DIR="$BUNDLE_DIR/contacts"
+CREATED=0
+SKIPPED=0
+ERRORS=0
+
+if [ -d "$CONTACTS_DIR" ]; then
+  for CONTACT_FILE in "$CONTACTS_DIR"/*.json; do
+    [ -f "$CONTACT_FILE" ] || continue
+
+    # Extract fields from contact JSON
+    GIVEN_NAME=$(python3 -c "import json; d=json.load(open('$CONTACT_FILE')); print(d.get('givenName',''))" 2>/dev/null)
+    FAMILY_NAME=$(python3 -c "import json; d=json.load(open('$CONTACT_FILE')); print(d.get('familyName',''))" 2>/dev/null)
+    TELEPHONE=$(python3 -c "import json; d=json.load(open('$CONTACT_FILE')); print(d.get('telephone',''))" 2>/dev/null)
+    EMAIL=$(python3 -c "import json; d=json.load(open('$CONTACT_FILE')); print(d.get('email',''))" 2>/dev/null)
+    JOB_TITLE=$(python3 -c "import json; d=json.load(open('$CONTACT_FILE')); print(d.get('jobTitle',''))" 2>/dev/null)
+
+    # Validate: must have givenName and at least phone or email
+    if [ -z "$GIVEN_NAME" ]; then
+      echo "[import] ERROR: contact skipped (no givenName): $(basename "$CONTACT_FILE")"
+      ERRORS=$((ERRORS + 1))
+      continue
+    fi
+    if [ -z "$TELEPHONE" ] && [ -z "$EMAIL" ]; then
+      echo "[import] ERROR: contact skipped (no phone or email): $GIVEN_NAME"
+      ERRORS=$((ERRORS + 1))
+      continue
+    fi
+
+    # Build MERGE query with --param for safe parameterisation
+    # MERGE on telephone (primary identifier for Taskmaster contacts)
+    ESCAPED_GIVEN=$(cypher_escape "$GIVEN_NAME")
+    ESCAPED_FAMILY=$(cypher_escape "$FAMILY_NAME")
+    ESCAPED_TITLE=$(cypher_escape "$JOB_TITLE")
+
+    # Build the cypher query — MERGE on telephone for dedup
+    CYPHER_QUERY="MERGE (p:Person {telephone: \$phone, accountId: \$acct})"
+    CYPHER_QUERY="$CYPHER_QUERY ON CREATE SET p.givenName = \$given, p.source = 'taskmaster-migration', p.status = 'customer', p.createdOn = datetime()"
+
+    # Add optional fields on CREATE
+    if [ -n "$FAMILY_NAME" ]; then
+      CYPHER_QUERY="$CYPHER_QUERY, p.familyName = \$family"
+    fi
+    if [ -n "$EMAIL" ]; then
+      CYPHER_QUERY="$CYPHER_QUERY, p.email = \$email"
+    fi
+    if [ -n "$JOB_TITLE" ]; then
+      CYPHER_QUERY="$CYPHER_QUERY, p.jobTitle = \$title"
+    fi
+
+    CYPHER_QUERY="$CYPHER_QUERY RETURN p.givenName AS name, p.telephone AS phone, CASE WHEN p.createdOn = datetime() THEN 'created' ELSE 'exists' END AS status"
+
+    # Execute with parameterised values
+    PARAMS=(
+      --param "phone => '$(cypher_escape "$TELEPHONE")'"
+      --param "acct => '$(cypher_escape "$ACCOUNT_ID")'"
+      --param "given => '$(cypher_escape "$GIVEN_NAME")'"
+    )
+    [ -n "$FAMILY_NAME" ] && PARAMS+=(--param "family => '$(cypher_escape "$FAMILY_NAME")'")
+    [ -n "$EMAIL" ] && PARAMS+=(--param "email => '$(cypher_escape "$(echo "$EMAIL" | tr '[:upper:]' '[:lower:]')")'")
+    [ -n "$JOB_TITLE" ] && PARAMS+=(--param "title => '$(cypher_escape "$JOB_TITLE")'")
+
+    RESULT=$("$CYPHER_SHELL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" -a "$NEO4J_URI" \
+      "${PARAMS[@]}" "$CYPHER_QUERY" 2>&1) || {
+      echo "[import] ERROR: contact failed: $GIVEN_NAME <$TELEPHONE> — $RESULT"
+      ERRORS=$((ERRORS + 1))
+      continue
+    }
+
+    if echo "$RESULT" | grep -q "created"; then
+      echo "[import] contact created: $GIVEN_NAME <$TELEPHONE>"
+      CREATED=$((CREATED + 1))
+    else
+      echo "[import] contact skipped (exists): $GIVEN_NAME <$TELEPHONE>"
+      SKIPPED=$((SKIPPED + 1))
+    fi
+  done
+fi
+echo "[import] contacts: $CREATED created, $SKIPPED skipped, $ERRORS errors"
+
+# ------------------------------------------------------------------
+# 2. Import memory files
+# ------------------------------------------------------------------
+MEMORY_DIR="$BUNDLE_DIR/memory"
+MEM_COUNT=0
+
+if [ -d "$MEMORY_DIR" ]; then
+  # Create target memory directories
+  mkdir -p "$ACCOUNT_DIR/memory"
+
+  for SUBDIR in shared admin public; do
+    if [ -d "$MEMORY_DIR/$SUBDIR" ] && [ "$(ls -A "$MEMORY_DIR/$SUBDIR" 2>/dev/null)" ]; then
+      # Copy recursively, preserving structure
+      mkdir -p "$ACCOUNT_DIR/memory/$SUBDIR"
+      cp -r "$MEMORY_DIR/$SUBDIR"/* "$ACCOUNT_DIR/memory/$SUBDIR/" 2>/dev/null || true
+      COUNT=$(find "$ACCOUNT_DIR/memory/$SUBDIR" -type f 2>/dev/null | wc -l | tr -d ' ')
+      echo "[import] memory/$SUBDIR: $COUNT files"
+      MEM_COUNT=$((MEM_COUNT + COUNT))
+    fi
+  done
+fi
+echo "[import] memory total: $MEM_COUNT files"
+
+# ------------------------------------------------------------------
+# 3. Import conversations
+# ------------------------------------------------------------------
+CONVOS_DIR="$BUNDLE_DIR/conversations"
+CONVO_COUNT=0
+
+if [ -d "$CONVOS_DIR" ]; then
+  mkdir -p "$ACCOUNT_DIR/conversations"
+
+  # Admin conversations
+  if [ -d "$CONVOS_DIR/admin" ] && [ "$(ls -A "$CONVOS_DIR/admin" 2>/dev/null)" ]; then
+    mkdir -p "$ACCOUNT_DIR/conversations/admin"
+    cp "$CONVOS_DIR/admin"/* "$ACCOUNT_DIR/conversations/admin/" 2>/dev/null || true
+    COUNT=$(find "$ACCOUNT_DIR/conversations/admin" -type f 2>/dev/null | wc -l | tr -d ' ')
+    echo "[import] conversations/admin: $COUNT files"
+    CONVO_COUNT=$((CONVO_COUNT + COUNT))
+  fi
+
+  # Per-user conversations
+  if [ -d "$CONVOS_DIR/users" ]; then
+    for USER_CONVO in "$CONVOS_DIR/users"/*/; do
+      [ -d "$USER_CONVO" ] || continue
+      USER_KEY=$(basename "$USER_CONVO")
+      mkdir -p "$ACCOUNT_DIR/conversations/users/$USER_KEY"
+      cp "$USER_CONVO"* "$ACCOUNT_DIR/conversations/users/$USER_KEY/" 2>/dev/null || true
+      COUNT=$(find "$ACCOUNT_DIR/conversations/users/$USER_KEY" -type f 2>/dev/null | wc -l | tr -d ' ')
+      CONVO_COUNT=$((CONVO_COUNT + COUNT))
+    done
+    USER_DIRS=$(find "$CONVOS_DIR/users" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
+    echo "[import] conversations/users: $USER_DIRS directories"
+  fi
+
+  # Group conversations
+  if [ -d "$CONVOS_DIR/groups" ]; then
+    for GRP_CONVO in "$CONVOS_DIR/groups"/*/; do
+      [ -d "$GRP_CONVO" ] || continue
+      GRP_ID=$(basename "$GRP_CONVO")
+      mkdir -p "$ACCOUNT_DIR/conversations/groups/$GRP_ID"
+      cp -r "$GRP_CONVO"* "$ACCOUNT_DIR/conversations/groups/$GRP_ID/" 2>/dev/null || true
+      COUNT=$(find "$ACCOUNT_DIR/conversations/groups/$GRP_ID" -type f 2>/dev/null | wc -l | tr -d ' ')
+      CONVO_COUNT=$((CONVO_COUNT + COUNT))
+    done
+    GRP_DIRS=$(find "$CONVOS_DIR/groups" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
+    echo "[import] conversations/groups: $GRP_DIRS directories"
+  fi
+fi
+echo "[import] conversations total: $CONVO_COUNT files"
+
+# ------------------------------------------------------------------
+# 4. Import media files
+# ------------------------------------------------------------------
+MEDIA_DIR="$BUNDLE_DIR/media"
+MEDIA_COUNT=0
+
+if [ -d "$MEDIA_DIR" ]; then
+  mkdir -p "$ACCOUNT_DIR/media"
+
+  for SUBDIR in admin public; do
+    if [ -d "$MEDIA_DIR/$SUBDIR" ] && [ "$(ls -A "$MEDIA_DIR/$SUBDIR" 2>/dev/null)" ]; then
+      mkdir -p "$ACCOUNT_DIR/media/$SUBDIR"
+      cp "$MEDIA_DIR/$SUBDIR"/* "$ACCOUNT_DIR/media/$SUBDIR/" 2>/dev/null || true
+      COUNT=$(find "$ACCOUNT_DIR/media/$SUBDIR" -type f 2>/dev/null | wc -l | tr -d ' ')
+      echo "[import] media/$SUBDIR: $COUNT files"
+      MEDIA_COUNT=$((MEDIA_COUNT + COUNT))
+    fi
+  done
+fi
+echo "[import] media total: $MEDIA_COUNT files"
+
+# ------------------------------------------------------------------
+# 5. Import automations (workflow definitions — reference only)
+# ------------------------------------------------------------------
+AUTO_DIR="$BUNDLE_DIR/automations"
+AUTO_COUNT=0
+
+if [ -d "$AUTO_DIR" ] && [ "$(ls -A "$AUTO_DIR" 2>/dev/null)" ]; then
+  mkdir -p "$ACCOUNT_DIR/memory/admin/workflows-migrated"
+  cp "$AUTO_DIR"/* "$ACCOUNT_DIR/memory/admin/workflows-migrated/" 2>/dev/null || true
+  AUTO_COUNT=$(find "$ACCOUNT_DIR/memory/admin/workflows-migrated" -type f 2>/dev/null | wc -l | tr -d ' ')
+  echo "[import] automations: $AUTO_COUNT workflow definitions → memory/admin/workflows-migrated/"
+fi
+
+# ------------------------------------------------------------------
+# 6. Apply PINs (if present in bundle)
+# ------------------------------------------------------------------
+PINS_FILE="$BUNDLE_DIR/identity/pins.json"
+if [ -f "$PINS_FILE" ]; then
+  MASTER_PIN=$(python3 -c "import json; d=json.load(open('$PINS_FILE')); print(d.get('masterPin','') or '')" 2>/dev/null)
+  if [ -n "$MASTER_PIN" ]; then
+    # Write PIN to account config
+    ACCOUNT_JSON="$ACCOUNT_DIR/account.json"
+    if [ -f "$ACCOUNT_JSON" ]; then
+      python3 -c "
+import json
+acct = json.load(open('$ACCOUNT_JSON'))
+acct['masterPin'] = '$MASTER_PIN'
+json.dump(acct, open('$ACCOUNT_JSON','w'), indent=2)
+print('[import] masterPin applied to account.json')
+"
+    else
+      echo "[import] WARN: account.json not found — PINs not applied"
+    fi
+  else
+    echo "[import] No masterPin in bundle — skipping PIN application"
+  fi
+else
+  echo "[import] No pins.json in bundle — skipping PIN application"
+fi
+
+# ------------------------------------------------------------------
+# Summary
+# ------------------------------------------------------------------
+echo ""
+echo "[import] =================================================="
+echo "[import] Import complete: $ACCOUNT_ID"
+echo "[import]   Contacts:      $CREATED created, $SKIPPED skipped, $ERRORS errors"
+echo "[import]   Memory files:  $MEM_COUNT"
+echo "[import]   Conversations: $CONVO_COUNT files"
+echo "[import]   Media files:   $MEDIA_COUNT"
+echo "[import]   Automations:   $AUTO_COUNT"
+echo "[import] =================================================="
+
+if [ "$ERRORS" -gt 0 ]; then
+  echo "[import] WARNING: $ERRORS errors occurred during import — review log above"
+  exit 1
+fi

package/payload/platform/scripts/taskmaster-export.sh

@@ -0,0 +1,387 @@
+#!/usr/bin/env bash
+# ============================================================
+# taskmaster-export.sh — Export Taskmaster data to migration bundle
+#
+# Reads a Taskmaster installation and produces a standardised
+# migration bundle directory that migrate-import.sh can consume.
+#
+# Usage:
+#   bash taskmaster-export.sh <config-dir> <workspace-dir> <output-dir>
+#
+# Arguments:
+#   config-dir    — Taskmaster config directory (e.g., ~/.taskmaster)
+#   workspace-dir — Taskmaster workspace directory (e.g., ~/taskmaster)
+#   output-dir    — Output directory for the migration bundle
+#
+# Example (run on the Taskmaster Pi via SSH):
+#   ssh admin@muvin.local
+#   bash /path/to/taskmaster-export.sh ~/.taskmaster ~/taskmaster ~/bundle
+# ============================================================
+
+set -euo pipefail
+
+# ------------------------------------------------------------------
+# Arguments
+# ------------------------------------------------------------------
+if [ $# -lt 3 ]; then
+  echo "[export] ERROR: Usage: taskmaster-export.sh <config-dir> <workspace-dir> <output-dir>"
+  exit 2
+fi
+
+CONFIG_DIR="$1"
+WORKSPACE_DIR="$2"
+OUTPUT_DIR="$3"
+
+TASKMASTER_JSON="$CONFIG_DIR/taskmaster.json"
+
+if [ ! -f "$TASKMASTER_JSON" ]; then
+  echo "[export] ERROR: taskmaster.json not found at $TASKMASTER_JSON"
+  echo "[export] ERROR: Is $CONFIG_DIR a Taskmaster config directory?"
+  exit 1
+fi
+
+if [ ! -d "$WORKSPACE_DIR" ]; then
+  echo "[export] ERROR: Workspace directory not found at $WORKSPACE_DIR"
+  exit 1
+fi
+
+echo "[export] Source config:    $CONFIG_DIR"
+echo "[export] Source workspace: $WORKSPACE_DIR"
+echo "[export] Output bundle:    $OUTPUT_DIR"
+
+# ------------------------------------------------------------------
+# Create bundle directory structure
+# ------------------------------------------------------------------
+mkdir -p "$OUTPUT_DIR"/{identity,contacts,memory/shared,memory/admin,conversations/admin,conversations/users,conversations/groups,media/admin,media/public,automations}
+
+# ------------------------------------------------------------------
+# 1. Manifest
+# ------------------------------------------------------------------
+HOSTNAME_VAL=$(hostname 2>/dev/null || echo "unknown")
+VERSION=$(python3 -c "import json; print(json.load(open('$TASKMASTER_JSON'))['meta']['lastTouchedVersion'])" 2>/dev/null || echo "unknown")
+EXPORT_TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Extract customer name from USER.md if it exists
+USER_MD="$WORKSPACE_DIR/agents/admin/USER.md"
+CUSTOMER_NAME="unknown"
+if [ -f "$USER_MD" ]; then
+  # Parse "**Name:** Adam Mackay" from USER.md
+  CUSTOMER_NAME=$(grep -oP '\*\*Name:\*\*\s*\K.*' "$USER_MD" 2>/dev/null || \
+                  sed -n 's/.*\*\*Name:\*\* *//p' "$USER_MD" | head -1)
+  [ -z "$CUSTOMER_NAME" ] && CUSTOMER_NAME="unknown"
+fi
+
+cat > "$OUTPUT_DIR/manifest.json" << MANIFEST_EOF
+{
+  "source": "taskmaster",
+  "version": "$VERSION",
+  "hostname": "$HOSTNAME_VAL",
+  "customer": "$CUSTOMER_NAME",
+  "exportedAt": "$EXPORT_TS"
+}
+MANIFEST_EOF
+echo "[export] manifest.json written (version=$VERSION, customer=$CUSTOMER_NAME)"
+
+# ------------------------------------------------------------------
+# 2. Identity — owner, agents, PINs
+# ------------------------------------------------------------------
+
+# Owner identity from USER.md
+if [ -f "$USER_MD" ]; then
+  # Parse structured fields from USER.md markdown
+  OWNER_NAME="$CUSTOMER_NAME"
+  OWNER_PHONE=$(sed -n 's/.*\*\*Phone:\*\* *//p' "$USER_MD" | head -1)
+  OWNER_BUSINESS=$(sed -n 's/.*\*\*Business:\*\* *//p' "$USER_MD" | head -1)
+  OWNER_LOCATION=$(sed -n 's/.*\*\*Location:\*\* *//p' "$USER_MD" | head -1)
+  OWNER_HOURS=$(sed -n 's/.*\*\*Working hours:\*\* *//p' "$USER_MD" | head -1)
+
+  python3 -c "
+import json, sys
+d = {}
+for k, v in [('name','$OWNER_NAME'),('phone','$OWNER_PHONE'),('business','$OWNER_BUSINESS'),('location','$OWNER_LOCATION'),('hours','$OWNER_HOURS')]:
+    if v: d[k] = v
+json.dump(d, open('$OUTPUT_DIR/identity/owner.json','w'), indent=2)
+print(f'[export] identity/owner.json written ({d.get(\"name\",\"unknown\")})')
+"
+else
+  echo "[export] WARN: USER.md not found at $USER_MD — owner identity skipped"
+fi
+
+# Agent names from IDENTITY.md files
+ADMIN_IDENTITY="$WORKSPACE_DIR/agents/admin/IDENTITY.md"
+PUBLIC_IDENTITY="$WORKSPACE_DIR/agents/public/IDENTITY.md"
+ADMIN_NAME=$(sed -n 's/.*\*\*Name:\*\* *//p' "$ADMIN_IDENTITY" 2>/dev/null | head -1 || echo "")
+PUBLIC_NAME=$(sed -n 's/.*\*\*Name:\*\* *//p' "$PUBLIC_IDENTITY" 2>/dev/null | head -1 || echo "")
+
+python3 -c "
+import json
+d = {'admin': '${ADMIN_NAME:-unknown}', 'public': '${PUBLIC_NAME:-unknown}'}
+json.dump(d, open('$OUTPUT_DIR/identity/agents.json','w'), indent=2)
+print(f'[export] identity/agents.json written (admin={d[\"admin\"]}, public={d[\"public\"]})')
+"
+
+# PINs from taskmaster.json access section
+python3 -c "
+import json
+try:
+    d = json.load(open('$TASKMASTER_JSON'))
+    access = d.get('access', {})
+    pins = {
+        'masterPin': access.get('masterPin'),
+        'workspacePins': access.get('pins', {})
+    }
+    # Only write if there are actual PINs
+    if pins['masterPin'] or pins['workspacePins']:
+        json.dump(pins, open('$OUTPUT_DIR/identity/pins.json','w'), indent=2)
+        print(f'[export] identity/pins.json written (masterPin={\"set\" if pins[\"masterPin\"] else \"none\"})')
+    else:
+        print('[export] identity/pins.json skipped (no PINs configured)')
+except Exception as e:
+    print(f'[export] WARN: could not extract PINs: {e}')
+"
+
+# ------------------------------------------------------------------
+# 3. Contacts — from memory/users/{phone}/ directories
+# ------------------------------------------------------------------
+USERS_DIR="$WORKSPACE_DIR/memory/users"
+CONTACT_COUNT=0
+ANON_SKIP_COUNT=0
+
+if [ -d "$USERS_DIR" ]; then
+  for USER_DIR in "$USERS_DIR"/*/; do
+    [ -d "$USER_DIR" ] || continue
+    USER_KEY=$(basename "$USER_DIR")
+
+    # Skip anonymous users — no phone number, no useful identity
+    if [[ "$USER_KEY" == anon-* ]]; then
+      ANON_SKIP_COUNT=$((ANON_SKIP_COUNT + 1))
+      continue
+    fi
+
+    PROFILE="$USER_DIR/profile.md"
+    if [ -f "$PROFILE" ]; then
+      # Extract name from first markdown heading or first bold field
+      python3 -c "
+import json, re, sys
+
+profile_path = '$PROFILE'
+user_key = '$USER_KEY'
+
+with open(profile_path, 'r') as f:
+    content = f.read()
+
+# Extract givenName from first heading (# Name)
+heading = re.search(r'^#\s+(.+)', content, re.MULTILINE)
+given_name = heading.group(1).strip() if heading else None
+
+# If heading is generic like 'Customer Profile', try **Name:** field
+if given_name and given_name.lower() in ('customer profile', 'profile', 'user profile'):
+    name_field = re.search(r'\*\*(?:Name|First name):\*\*\s*(.+)', content)
+    given_name = name_field.group(1).strip() if name_field else None
+
+# Extract phone from profile or use directory name
+phone_field = re.search(r'\*\*Phone:\*\*\s*(.+)', content)
+phone = phone_field.group(1).strip() if phone_field else user_key
+
+# Extract role
+role_field = re.search(r'\*\*Role:\*\*\s*(.+)', content)
+role = role_field.group(1).strip() if role_field else None
+
+# Extract location
+loc_field = re.search(r'\*\*Location:\*\*\s*(.+)', content)
+location = loc_field.group(1).strip() if loc_field else None
+
+contact = {
+    'telephone': phone,
+    'source': 'taskmaster-migration'
+}
+
+if given_name and given_name != 'Customer Profile':
+    # Split name into given/family if it contains a space
+    parts = given_name.split(' ', 1)
+    contact['givenName'] = parts[0]
+    if len(parts) > 1:
+        contact['familyName'] = parts[1]
+else:
+    # No name — use phone as identifier, skip givenName
+    # (import will skip contacts without givenName)
+    pass
+
+if role:
+    contact['jobTitle'] = role
+if location:
+    contact['location'] = location
+
+# Include raw profile for reference
+contact['_profileContent'] = content
+
+# Write contact JSON
+safe_key = user_key.replace('+', 'plus-')
+json.dump(contact, open(f'$OUTPUT_DIR/contacts/{safe_key}.json', 'w'), indent=2)
+has_name = 'givenName' in contact
+print(f'[export] contact: {user_key} ({contact.get(\"givenName\", \"NO NAME\")})', file=sys.stderr)
+sys.exit(0 if has_name else 0)
+" 2>&1
+    else
+      # No profile.md — create minimal contact from directory name
+      python3 -c "
+import json
+contact = {'telephone': '$USER_KEY', 'source': 'taskmaster-migration'}
+safe_key = '$USER_KEY'.replace('+', 'plus-')
+json.dump(contact, open(f'$OUTPUT_DIR/contacts/{safe_key}.json', 'w'), indent=2)
+print(f'[export] contact: $USER_KEY (no profile.md — phone only)')
+"
+    fi
+    CONTACT_COUNT=$((CONTACT_COUNT + 1))
+  done
+fi
+echo "[export] contacts: $CONTACT_COUNT exported, $ANON_SKIP_COUNT anonymous skipped"
+
+# ------------------------------------------------------------------
+# 4. Memory — shared and admin knowledge files
+# ------------------------------------------------------------------
+SHARED_DIR="$WORKSPACE_DIR/memory/shared"
+SHARED_COUNT=0
+if [ -d "$SHARED_DIR" ]; then
+  # Copy all files except cron-activity and media (media goes to media/public)
+  find "$SHARED_DIR" -maxdepth 1 -type f | while read -r f; do
+    cp "$f" "$OUTPUT_DIR/memory/shared/"
+    echo "[export] memory/shared: $(basename "$f")"
+  done
+  SHARED_COUNT=$(find "$OUTPUT_DIR/memory/shared" -type f | wc -l | tr -d ' ')
+fi
+echo "[export] memory/shared: $SHARED_COUNT files"
+
+ADMIN_MEMORY="$WORKSPACE_DIR/agents/admin/memory/admin"
+ADMIN_MEM_COUNT=0
+if [ -d "$ADMIN_MEMORY" ]; then
+  # Copy recursively, excluding cron-activity (Loop diary logs) and media (goes to media/)
+  rsync -a --exclude='cron-activity' --exclude='media' "$ADMIN_MEMORY/" "$OUTPUT_DIR/memory/admin/" 2>/dev/null || \
+    find "$ADMIN_MEMORY" -type f -not -path '*/cron-activity/*' -not -path '*/media/*' | while read -r f; do
+      REL="${f#$ADMIN_MEMORY/}"
+      mkdir -p "$OUTPUT_DIR/memory/admin/$(dirname "$REL")"
+      cp "$f" "$OUTPUT_DIR/memory/admin/$REL"
+    done
+  ADMIN_MEM_COUNT=$(find "$OUTPUT_DIR/memory/admin" -type f 2>/dev/null | wc -l | tr -d ' ')
+fi
+echo "[export] memory/admin: $ADMIN_MEM_COUNT files"
+
+# Public agent memory
+PUBLIC_MEMORY="$WORKSPACE_DIR/agents/admin/memory/public"
+if [ -d "$PUBLIC_MEMORY" ]; then
+  mkdir -p "$OUTPUT_DIR/memory/public"
+  cp -r "$PUBLIC_MEMORY"/* "$OUTPUT_DIR/memory/public/" 2>/dev/null || true
+  PUB_COUNT=$(find "$OUTPUT_DIR/memory/public" -type f 2>/dev/null | wc -l | tr -d ' ')
+  echo "[export] memory/public: $PUB_COUNT files"
+fi
+
+# ------------------------------------------------------------------
+# 5. Conversations — admin, per-user, per-group
+# ------------------------------------------------------------------
+
+# Admin conversations
+ADMIN_CONVOS="$ADMIN_MEMORY/conversations"
+ADMIN_CONVO_COUNT=0
+if [ -d "$ADMIN_CONVOS" ]; then
+  cp "$ADMIN_CONVOS"/*.md "$OUTPUT_DIR/conversations/admin/" 2>/dev/null || true
+  ADMIN_CONVO_COUNT=$(find "$OUTPUT_DIR/conversations/admin" -type f 2>/dev/null | wc -l | tr -d ' ')
+fi
+echo "[export] conversations/admin: $ADMIN_CONVO_COUNT files"
+
+# Per-user conversations
+USER_CONVO_COUNT=0
+if [ -d "$USERS_DIR" ]; then
+  for USER_DIR in "$USERS_DIR"/*/; do
+    [ -d "$USER_DIR" ] || continue
+    USER_KEY=$(basename "$USER_DIR")
+    CONVO_DIR="$USER_DIR/conversations"
+    if [ -d "$CONVO_DIR" ] && [ "$(ls -A "$CONVO_DIR" 2>/dev/null)" ]; then
+      SAFE_KEY=$(echo "$USER_KEY" | sed 's/+/plus-/g')
+      mkdir -p "$OUTPUT_DIR/conversations/users/$SAFE_KEY"
+      cp "$CONVO_DIR"/*.md "$OUTPUT_DIR/conversations/users/$SAFE_KEY/" 2>/dev/null || true
+      USER_CONVO_COUNT=$((USER_CONVO_COUNT + 1))
+    fi
+  done
+fi
+echo "[export] conversations/users: $USER_CONVO_COUNT directories"
+
+# Group conversations
+GROUP_DIR="$WORKSPACE_DIR/memory/groups"
+GROUP_CONVO_COUNT=0
+if [ -d "$GROUP_DIR" ]; then
+  for GRP in "$GROUP_DIR"/*/; do
+    [ -d "$GRP" ] || continue
+    GRP_ID=$(basename "$GRP")
+    CONVO_DIR="$GRP/conversations"
+    if [ -d "$CONVO_DIR" ] && [ "$(ls -A "$CONVO_DIR" 2>/dev/null)" ]; then
+      mkdir -p "$OUTPUT_DIR/conversations/groups/$GRP_ID"
+      cp "$CONVO_DIR"/*.md "$OUTPUT_DIR/conversations/groups/$GRP_ID/" 2>/dev/null || true
+      GROUP_CONVO_COUNT=$((GROUP_CONVO_COUNT + 1))
+    fi
+    # Group member files
+    MEMBERS_DIR="$GRP/members"
+    if [ -d "$MEMBERS_DIR" ] && [ "$(ls -A "$MEMBERS_DIR" 2>/dev/null)" ]; then
+      mkdir -p "$OUTPUT_DIR/conversations/groups/$GRP_ID/members"
+      cp "$MEMBERS_DIR"/* "$OUTPUT_DIR/conversations/groups/$GRP_ID/members/" 2>/dev/null || true
+    fi
+  done
+fi
+echo "[export] conversations/groups: $GROUP_CONVO_COUNT directories"
+
+# ------------------------------------------------------------------
+# 6. Media — admin uploads and shared media
+# ------------------------------------------------------------------
+ADMIN_UPLOADS="$WORKSPACE_DIR/agents/admin/uploads"
+ADMIN_MEDIA_COUNT=0
+if [ -d "$ADMIN_UPLOADS" ] && [ "$(ls -A "$ADMIN_UPLOADS" 2>/dev/null)" ]; then
+  cp "$ADMIN_UPLOADS"/* "$OUTPUT_DIR/media/admin/" 2>/dev/null || true
+  ADMIN_MEDIA_COUNT=$(find "$OUTPUT_DIR/media/admin" -type f 2>/dev/null | wc -l | tr -d ' ')
+fi
+echo "[export] media/admin: $ADMIN_MEDIA_COUNT files"
+
+# Shared media (e.g., PDFs in memory/shared/media/)
+SHARED_MEDIA="$WORKSPACE_DIR/memory/shared/media"
+PUBLIC_MEDIA_COUNT=0
+if [ -d "$SHARED_MEDIA" ] && [ "$(ls -A "$SHARED_MEDIA" 2>/dev/null)" ]; then
+  cp "$SHARED_MEDIA"/* "$OUTPUT_DIR/media/public/" 2>/dev/null || true
+  PUBLIC_MEDIA_COUNT=$(find "$OUTPUT_DIR/media/public" -type f 2>/dev/null | wc -l | tr -d ' ')
+fi
+echo "[export] media/public: $PUBLIC_MEDIA_COUNT files"
+
+# Admin memory media
+ADMIN_MEDIA_DIR="$ADMIN_MEMORY/media"
+if [ -d "$ADMIN_MEDIA_DIR" ] && [ "$(ls -A "$ADMIN_MEDIA_DIR" 2>/dev/null)" ]; then
+  cp "$ADMIN_MEDIA_DIR"/* "$OUTPUT_DIR/media/admin/" 2>/dev/null || true
+  # Recount after adding
+  ADMIN_MEDIA_COUNT=$(find "$OUTPUT_DIR/media/admin" -type f 2>/dev/null | wc -l | tr -d ' ')
+  echo "[export] media/admin (updated with memory/admin/media): $ADMIN_MEDIA_COUNT files"
+fi
+
+# ------------------------------------------------------------------
+# 7. Automations — workflow definitions (not cron-activity logs)
+# ------------------------------------------------------------------
+WORKFLOWS_DIR="$ADMIN_MEMORY/workflows"
+AUTOMATION_COUNT=0
+if [ -d "$WORKFLOWS_DIR" ] && [ "$(ls -A "$WORKFLOWS_DIR" 2>/dev/null)" ]; then
+  cp "$WORKFLOWS_DIR"/* "$OUTPUT_DIR/automations/" 2>/dev/null || true
+  AUTOMATION_COUNT=$(find "$OUTPUT_DIR/automations" -type f 2>/dev/null | wc -l | tr -d ' ')
+fi
+echo "[export] automations: $AUTOMATION_COUNT workflow definitions"
+
+# ------------------------------------------------------------------
+# Summary
+# ------------------------------------------------------------------
+TOTAL_CONTACTS=$CONTACT_COUNT
+TOTAL_MEMORY=$((SHARED_COUNT + ADMIN_MEM_COUNT))
+TOTAL_MEDIA=$((ADMIN_MEDIA_COUNT + PUBLIC_MEDIA_COUNT))
+TOTAL_CONVOS=$((ADMIN_CONVO_COUNT + USER_CONVO_COUNT + GROUP_CONVO_COUNT))
+
+echo ""
+echo "[export] =================================================="
+echo "[export] Bundle complete: $OUTPUT_DIR"
+echo "[export]   Contacts:      $TOTAL_CONTACTS (+ $ANON_SKIP_COUNT anonymous skipped)"
+echo "[export]   Memory files:  $TOTAL_MEMORY"
+echo "[export]   Media files:   $TOTAL_MEDIA"
+echo "[export]   Conversations: $TOTAL_CONVOS directories"
+echo "[export]   Automations:   $AUTOMATION_COUNT"
+echo "[export] =================================================="