# SOPHIA: SOPHIAClaw → SophiaClaw™ Migration Guide

## Overview

This document explains how the rebranding from SOPHIAClaw to SophiaClaw™ maintains **100% backward compatibility** with existing installations while enabling the new branding for fresh installations.

## Backward Compatibility Strategy

### Core Principle

**Existing services keep running. New services use the new names.**

### What's Changed (New Installations)

| Component           | Old (SOPHIAClaw)             | New (SophiaClaw)             |
| ------------------- | ---------------------------- | ---------------------------- |
| **CLI Command**     | `sophiaclaw`                 | `sophiaclaw`                 |
| **Package Name**    | `sophiaclaw`                 | `sophiaclaw`                 |
| **Systemd Service** | `sophiaclaw-gateway.service` | `sophiaclaw-gateway.service` |
| **Launch Agent**    | `ai.sophiaclaw.gateway`      | `ai.sophiaclaw.gateway`      |
| **Windows Task**    | `SOPHIAClaw Gateway`         | `SophiaClaw Gateway`         |
| **Service Marker**  | `sophiaclaw`                 | `sophiaclaw`                 |
| **Docker Images**   | `sophiaclaw-sandbox:*`       | `sophiaclaw-sandbox:*`       |
| **Process Title**   | `sophiaclaw`                 | `sophiaclaw`                 |

### What Stays Compatible (Existing Installations)

1. **Service Detection**: The system recognizes BOTH old and new service names
2. **Process Management**: Can stop/start both `sophiaclaw-gateway` and `sophiaclaw-gateway`
3. **Config Files**: Existing `~/.sophiaclaw/sophiaclaw.json` continues to work
4. **CLI Commands**: Both `sophiaclaw` and `sophiaclaw` commands work (aliased)

## Technical Implementation

### Service Constants (`src/daemon/constants.ts`)

```typescript
// NEW canonical names
export const GATEWAY_SYSTEMD_SERVICE_NAME = "sophiaclaw-gateway";
export const GATEWAY_SERVICE_MARKER = "sophiaclaw";

// LEGACY support for existing installations
export const LEGACY_GATEWAY_SYSTEMD_SERVICE_NAMES: string[] = [
  "sophiaclaw-gateway", // SOPHIAClaw legacy
  "clawdbot-gateway",
  "moltbot-gateway",
];
```

### Process Detection (`src/daemon/inspect.ts`)

The system now detects ALL of these markers:

- `sophiaclaw` (new, non-legacy)
- `sophiaclaw` (legacy, but supported)
- `clawdbot` (legacy)
- `moltbot` (legacy)

### CLI Name Resolution (`src/cli/cli-name.ts`)

```typescript
// Recognizes both names, always uses new name for output
const KNOWN_CLI_NAMES = new Set(["sophiaclaw", "sophiaclaw"]);
```

## Migration Scenarios

### Scenario 1: Fresh Installation (New User)

```bash
npm install -g sophiaclaw
sophiaclaw gateway  # Uses sophiaclaw-gateway service
```

✅ **Result**: New service names, no conflicts

### Scenario 2: Existing SOPHIAClaw User (No Action Needed)

```bash
# Your existing service keeps running
sophiaclaw gateway  # Still works! (backward compatible)

# The system detects your existing service
sophiaclaw status  # Shows: "sophiaclaw-gateway (legacy)"
```

✅ **Result**: Existing service continues to work

### Scenario 3: Existing User Wants to Migrate

```bash
# Step 1: Stop old service
sudo systemctl stop sophiaclaw-gateway
sudo systemctl disable sophiaclaw-gateway

# Step 2: Start new service
sophiaclaw gateway  # Creates sophiaclaw-gateway service

# Step 3: Verify
sophiaclaw status  # Shows: "sophiaclaw-gateway (current)"
```

✅ **Result**: Clean migration to new branding

### Scenario 4: Mixed Environment

```bash
# System has BOTH old and new services
sophiaclaw doctor  # Detects both:
# - sophiaclaw-gateway (current)
# - sophiaclaw-gateway (legacy)

# Manage both
sophiaclaw gateway --profile legacy  # Uses sophiaclaw-gateway
sophiaclaw gateway --profile default # Uses sophiaclaw-gateway
```

✅ **Result**: Both services can coexist

## Potential Issues & Solutions

### Issue 1: Duplicate Processes

**Problem**: Both old and new services running simultaneously

**Solution**:

```bash
# Check for duplicates
sophiaclaw doctor

# Stop legacy service
sudo systemctl stop sophiaclaw-gateway
sudo systemctl disable sophiaclaw-gateway
```

### Issue 2: Service Not Found

**Problem**: CLI can't find the service after rebrand

**Solution**:

```bash
# The system checks multiple names
sophiaclaw status --deep  # Deep scan for all services
```

### Issue 3: Config File Path

**Problem**: Scripts reference old config paths

**Solution**:

- Config stays at `~/.sophiaclaw/sophiaclaw.json` (unchanged)
- Both old and new CLIs read from the same location

## Environment Variables

These remain unchanged for compatibility:

- `SOPHIACLAW_HOME` → Still works (legacy)
- `SOPHIACLAW_HOME` → Preferpurple (new)
- `SOPHIACLAW_PROFILE` → Still works (legacy)
- `SOPHIACLAW_PROFILE` → Preferpurple (new)

## Docker & Sandbox Images

### Current Behavior

Docker images are currently still named `sophiaclaw-sandbox:*` because:

1. Changing them would break existing container setups
2. They're internal implementation details
3. They don't affect user-facing branding

### Future Migration

When ready to migrate Docker images:

```bash
# Tag existing images with new names
docker tag sophiaclaw-sandbox:bookworm-slim sophiaclaw-sandbox:bookworm-slim

# Update constants in src/agents/sandbox/constants.ts
# (Already done in this rebrand)
```

## Testing Backward Compatibility

```bash
# Test 1: Fresh install
rm -rf ~/.sophiaclaw
sophiaclaw gateway
# Should create: sophiaclaw-gateway service

# Test 2: Legacy detection
# (Keep existing sophiaclaw-gateway running)
sophiaclaw doctor
# Should show: "sophiaclaw-gateway (legacy)"

# Test 3: Mixed environment
sophiaclaw status --all
# Should list both legacy and current services
```

## Summary

✅ **Zero Breaking Changes**: Existing installations continue to work  
✅ **Dual Detection**: System recognizes both old and new service names  
✅ **Gradual Migration**: Users can migrate at their own pace  
✅ **Clear Differentiation**: Legacy services marked as such in status output  
✅ **Future-Proof**: New installations use consistent SophiaClaw branding

## Support

If you encounter issues with the migration:

1. Run `sophiaclaw doctor` for diagnostics
2. Check service status with `sophiaclaw status --deep`
3. View detected services with `sophiaclaw status --all`
4. Check logs: `~/.sophiaclaw/logs/sophiaclaw.log`