@mu-cabin/muc-cli 0.6.0 → 0.6.1

package/README.md

@@ -32,12 +32,18 @@ JSON
 
 消费程序保存最后一条成功处理的事件游标，重连时通过 `cursor` 继续。`events.list` 用于持久化事件补取。后台离线期间的历史消息通过 `messages.list/search` 查询，不能把本地事件为空当作离线期间没有消息。
 
+启动配置错误会直接返回原因，不再仅等待超时。`daemon logs` 返回安全的错误代码、说明和处理提示，不输出原始异常或凭据。
+
 普通命令按需启动 daemon；`daemon status/logs/stop` 不会启动后台。升级可执行文件前先停止相应配置根的 daemon，更新后再启动。被踢下线或主动停止的 profile 保留停止状态，须明确登录或 `runtime resume` 才能恢复。
 
 完整参数见 [REFERENCE.md](REFERENCE.md)，agent 操作说明见 [skills/muc/SKILL.md](skills/muc/SKILL.md)。文件消息默认不附加尾注；文字和图片仍遵循原有尾注设置。发送结果不明时查询原 delivery/idempotency key，不自动重发。
 
 ## 从旧 CLI 迁移
 
+0.6.1 支持单账号平铺配置和 `activeProfile + profiles` 多账号配置；后者保留全部 profile，并将默认账号映射为 `selectedProfileId`。不同租户、缺失默认账号或无法解密的记住密码会拒绝迁移并保留原文件。
+
+迁移后会在启动时登记消息数据库中的账号，确保群信息和消息同步可正常落库。
+
 首次启动会识别当前配置根中的旧版 `config.json` / `credentials.json`，保留设备、插槽、账号、token、记住密码和消息尾注，并生成私有的 `*.v1.backup.json` 备份。迁移只处理所选配置根；旧后台仍运行时会拒绝迁移。旧消息日志、assistant 配置和旧版命令不迁入。
 
 旧 `send/history/listen/assistant/daemon-*` 命令改用新版 `exec` 和 `daemon` 命令，Skill 合并为 `skills/muc`。此版本不提供 TUI、机器人执行后端和独立升级控制面。不要直接将旧二进制指向迁移后的目录；回退须停止新后台后在独立目录恢复旧备份及原 `remember.salt`。

package/REFERENCE.md

@@ -1,6 +1,6 @@
 # MUC 命令契约
 
-本文件描述 0.6.0 的命令契约。旧的 `send/history/daemon-*` 命令已移除。
+本文件描述 0.6.1 的命令契约。旧的 `send/history/daemon-*` 命令已移除。
 
 ## 命令结构
 

package/dist/muc.mjs

@@ -11956,26 +11956,29 @@ function deriveKey(root) {
     maxmem: 64 * 1024 * 1024
   });
 }
-function encryptRemembered(plaintext, root) {
+function encryptRemembered(plaintext, root, profile) {
   if (!plaintext) throw new Error("encryptRemembered: empty plaintext");
   const key = deriveKey(root);
   const iv = randomBytes2(IV_BYTES);
   const cipher = createCipheriv("aes-256-gcm", key, iv);
+  if (profile !== void 0) cipher.setAAD(Buffer.from(profile, "utf8"));
   const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
   const tag = cipher.getAuthTag();
-  return `v1.${iv.toString("base64")}.${tag.toString("base64")}.${ct.toString("base64")}`;
+  return `${profile === void 0 ? "v1" : "v2"}.${iv.toString("base64")}.${tag.toString("base64")}.${ct.toString("base64")}`;
 }
-function decryptRemembered(blob, root) {
+function decryptRemembered(blob, root, profile) {
   try {
     if (typeof blob !== "string") return null;
     const parts = blob.split(".");
-    if (parts.length !== 4 || parts[0] !== "v1") return null;
+    if (parts.length !== 4 || !["v1", "v2"].includes(parts[0]) || parts[0] === "v2" && profile === void 0) return null;
+    if (!existsSync(saltFile(root))) return null;
     const iv = Buffer.from(parts[1], "base64");
     const tag = Buffer.from(parts[2], "base64");
     const ct = Buffer.from(parts[3], "base64");
     if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) return null;
     const key = deriveKey(root);
     const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    if (parts[0] === "v2") decipher.setAAD(Buffer.from(profile, "utf8"));
     decipher.setAuthTag(tag);
     const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
     return pt.toString("utf8");
@@ -12117,6 +12120,103 @@ var LegacyCredentials = external_exports.object({
   rememberedPwd: external_exports.string().optional()
 });
 var Journal = external_exports.object({ config: NativeProfileDocumentSchema, credentials: CredentialDocumentSchema }).strict();
+var MultiProfile = LegacyConfig.omit({
+  schemaVersion: true,
+  appKey: true,
+  appId: true,
+  signSecretRest: true,
+  signSecretSecure: true,
+  pwdDesKey: true
+}).extend({
+  account: external_exports.string().min(1),
+  generation: external_exports.string().uuid(),
+  deviceId: LegacyCredentials.shape.deviceId,
+  deviceName: LegacyCredentials.shape.deviceName,
+  identity: external_exports.object({ uid: external_exports.string().optional(), employeeId: external_exports.string().optional(), name: external_exports.string().optional() }).optional()
+});
+var MultiConfig = external_exports.object({
+  schemaVersion: external_exports.literal(1),
+  activeProfile: NativeProfileIdSchema,
+  profiles: external_exports.record(NativeProfileIdSchema, MultiProfile)
+});
+var MultiCredentials = external_exports.object({ schemaVersion: external_exports.literal(1), profiles: external_exports.record(NativeProfileIdSchema, external_exports.object({
+  tenant: LegacyConfig.pick({ appKey: true, appId: true, signSecretRest: true, signSecretSecure: true, pwdDesKey: true, savedAt: true }).optional(),
+  session: LegacyCredentials.omit({ uid: true, empId: true, name: true, deviceId: true, deviceName: true }).extend({
+    appVersion: external_exports.string().min(1),
+    rememberedPassword: external_exports.string().min(1).optional()
+  }).optional()
+})) });
+function convertMulti(root, raw, secrets) {
+  const old = MultiConfig.parse(raw);
+  const creds = MultiCredentials.parse(secrets ?? { schemaVersion: 1, profiles: {} });
+  if (!Object.hasOwn(old.profiles, old.activeProfile)) throw new CliConfigError("CONFIG_INVALID", "Legacy default profile does not exist. Original files are unchanged.");
+  if (Object.keys(creds.profiles).some((id) => !Object.hasOwn(old.profiles, id))) throw new CliConfigError("CONFIG_INVALID", "Legacy credentials contain an unknown profile. Original files are unchanged.");
+  const profiles = {};
+  const credentials = { schemaVersion: 2, profiles: {} };
+  for (const [id, oldProfile] of Object.entries(old.profiles)) {
+    const profile = createNativeProfile({
+      id,
+      endpoints: {
+        restOrigin: new URL(oldProfile.restHost).origin,
+        imHost: oldProfile.imHost,
+        imPort: oldProfile.imPort,
+        fileHost: oldProfile.fileHost,
+        filePort: oldProfile.filePort
+      },
+      slot: slotFromChatOs(oldProfile.defaultChatOs ?? "iPad"),
+      cliSignature: oldProfile.messageTail === void 0 ? { mode: "builtin" } : oldProfile.messageTail === "" ? { mode: "disabled" } : { mode: "custom", text: oldProfile.messageTail }
+    }, { generation: oldProfile.generation, now: () => oldProfile.savedAt });
+    profile.device = { id: oldProfile.deviceId, name: oldProfile.deviceName };
+    profile.identity = {
+      account: oldProfile.account.toUpperCase(),
+      ...oldProfile.identity?.employeeId ? { employeeId: oldProfile.identity.employeeId } : {},
+      ...oldProfile.identity?.name ? { displayName: oldProfile.identity.name } : {}
+    };
+    profiles[id] = NativeProfileSchema.parse(profile);
+    const secret = creds.profiles[id];
+    if (secret?.tenant) {
+      const t = secret.tenant;
+      const tenant = NativeTenantSecretSchema.parse({
+        schemaVersion: 2,
+        appKey: t.appKey,
+        appId: t.appId,
+        signSecretRest: t.signSecretRest,
+        signSecretSecure: t.signSecretSecure,
+        passwordKey: t.pwdDesKey,
+        savedAtMs: t.savedAt
+      });
+      const { savedAtMs: _, ...identity } = tenant;
+      const { savedAtMs: __, ...existing } = credentials.tenant ?? tenant;
+      if (JSON.stringify(identity) !== JSON.stringify(existing)) throw new CliConfigError("CONFIG_INVALID", "Legacy profiles use different tenants; migrate them to separate config roots. Original files are unchanged.");
+      credentials.tenant = tenant;
+    }
+    if (secret?.session) {
+      const s = secret.session;
+      credentials.profiles[profile.storageKey] = {
+        session: NativeSessionSecretSchema.parse({
+          schemaVersion: 2,
+          accessToken: s.accessToken,
+          tokenPassword: s.tokenPwd,
+          restPlatform: s.restPlatform ?? 5,
+          appVersion: s.appVersion,
+          savedAtMs: s.savedAt,
+          accessTokenExpireAtMs: s.accessTokenExpireAt,
+          tokenPasswordExpireAtMs: s.tokenPwdExpireAt
+        }),
+        ...s.rememberedPwd ? { rememberedPwd: s.rememberedPwd } : {}
+      };
+    }
+  }
+  const next = Journal.parse({ config: { schemaVersion: 2, selectedProfileId: old.activeProfile, profiles }, credentials });
+  for (const [id, secret] of Object.entries(creds.profiles)) {
+    if (secret.session?.rememberedPassword) {
+      const password = decryptRemembered(secret.session.rememberedPassword, root, id);
+      if (password === null) throw new CliConfigError("CONFIG_INVALID", "Legacy remembered password could not be decrypted. Preserve the original remember.salt and account profile; original configuration files are unchanged.");
+      next.credentials.profiles[profiles[id].storageKey].rememberedPwd = encryptRemembered(password, root);
+    }
+  }
+  return next;
+}
 async function importLegacyStorage(root) {
   try {
     const journalPath = join6(root, ".migration-v2.json");
@@ -12128,47 +12228,8 @@ async function importLegacyStorage(root) {
       await commit(root, Journal.parse(pending));
       return true;
     }
-    const legacy = LegacyConfig.parse(config);
     const rawCredentials = await readPrivateJson(join6(root, "credentials.json"));
-    const credentials = rawCredentials === void 0 ? void 0 : LegacyCredentials.parse(rawCredentials);
-    const profile = createNativeProfile({
-      id: "default",
-      endpoints: { restOrigin: new URL(legacy.restHost).origin, imHost: legacy.imHost, imPort: legacy.imPort, fileHost: legacy.fileHost, filePort: legacy.filePort },
-      slot: slotFromChatOs(legacy.defaultChatOs ?? "iPad"),
-      cliSignature: legacy.messageTail === void 0 ? { mode: "builtin" } : legacy.messageTail === "" ? { mode: "disabled" } : { mode: "custom", text: legacy.messageTail }
-    });
-    if (credentials) {
-      profile.device = { id: credentials.deviceId, name: credentials.deviceName };
-      profile.identity = { account: credentials.uid.toUpperCase(), ...credentials.empId ? { employeeId: credentials.empId } : {}, ...credentials.name ? { displayName: credentials.name } : {} };
-    }
-    const tenant = NativeTenantSecretSchema.parse({
-      schemaVersion: 2,
-      appKey: legacy.appKey,
-      appId: legacy.appId,
-      signSecretRest: legacy.signSecretRest,
-      signSecretSecure: legacy.signSecretSecure,
-      ...legacy.pwdDesKey ? { passwordKey: legacy.pwdDesKey } : {},
-      savedAtMs: legacy.savedAt
-    });
-    const restPlatform = credentials?.restPlatform ?? 5;
-    const next = Journal.parse({
-      config: { schemaVersion: 2, selectedProfileId: profile.id, profiles: { [profile.id]: NativeProfileSchema.parse(profile) } },
-      credentials: { schemaVersion: 2, tenant, profiles: credentials ? {
-        [profile.storageKey]: {
-          session: NativeSessionSecretSchema.parse({
-            schemaVersion: 2,
-            accessToken: credentials.accessToken,
-            tokenPassword: credentials.tokenPwd,
-            restPlatform,
-            appVersion: restPlatform === 1 ? "3.3.0301" : "3.3.1-250925001",
-            savedAtMs: credentials.savedAt,
-            accessTokenExpireAtMs: credentials.accessTokenExpireAt,
-            tokenPasswordExpireAtMs: credentials.tokenPwdExpireAt
-          }),
-          ...credentials.rememberedPwd ? { rememberedPwd: credentials.rememberedPwd } : {}
-        }
-      } : {} }
-    });
+    const next = config && typeof config === "object" && "profiles" in config ? convertMulti(root, config, rawCredentials) : convertSingle(config, rawCredentials);
     await backupOnce(root, "config.v1.backup.json", config);
     if (rawCredentials !== void 0) await backupOnce(root, "credentials.v1.backup.json", rawCredentials);
     await writePrivateJson(root, ".migration-v2.json", next);
@@ -12176,9 +12237,52 @@ async function importLegacyStorage(root) {
     return true;
   } catch (error) {
     if (error instanceof CliConfigError) throw error;
-    throw new CliConfigError("CONFIG_INVALID", "Legacy configuration could not be imported. Original backups are retained; inspect the local files privately.");
+    throw new CliConfigError("CONFIG_INVALID", "Legacy configuration could not be imported. Original files or migration backups are retained; inspect the local files privately.");
   }
 }
+function convertSingle(config, rawCredentials) {
+  const legacy = LegacyConfig.parse(config);
+  const credentials = rawCredentials === void 0 ? void 0 : LegacyCredentials.parse(rawCredentials);
+  const profile = createNativeProfile({
+    id: "default",
+    endpoints: { restOrigin: new URL(legacy.restHost).origin, imHost: legacy.imHost, imPort: legacy.imPort, fileHost: legacy.fileHost, filePort: legacy.filePort },
+    slot: slotFromChatOs(legacy.defaultChatOs ?? "iPad"),
+    cliSignature: legacy.messageTail === void 0 ? { mode: "builtin" } : legacy.messageTail === "" ? { mode: "disabled" } : { mode: "custom", text: legacy.messageTail }
+  });
+  if (credentials) {
+    profile.device = { id: credentials.deviceId, name: credentials.deviceName };
+    profile.identity = { account: credentials.uid.toUpperCase(), ...credentials.empId ? { employeeId: credentials.empId } : {}, ...credentials.name ? { displayName: credentials.name } : {} };
+  }
+  const tenant = NativeTenantSecretSchema.parse({
+    schemaVersion: 2,
+    appKey: legacy.appKey,
+    appId: legacy.appId,
+    signSecretRest: legacy.signSecretRest,
+    signSecretSecure: legacy.signSecretSecure,
+    ...legacy.pwdDesKey ? { passwordKey: legacy.pwdDesKey } : {},
+    savedAtMs: legacy.savedAt
+  });
+  const restPlatform = credentials?.restPlatform ?? 5;
+  const next = Journal.parse({
+    config: { schemaVersion: 2, selectedProfileId: profile.id, profiles: { [profile.id]: NativeProfileSchema.parse(profile) } },
+    credentials: { schemaVersion: 2, tenant, profiles: credentials ? {
+      [profile.storageKey]: {
+        session: NativeSessionSecretSchema.parse({
+          schemaVersion: 2,
+          accessToken: credentials.accessToken,
+          tokenPassword: credentials.tokenPwd,
+          restPlatform,
+          appVersion: restPlatform === 1 ? "3.3.0301" : "3.3.1-250925001",
+          savedAtMs: credentials.savedAt,
+          accessTokenExpireAtMs: credentials.accessTokenExpireAt,
+          tokenPasswordExpireAtMs: credentials.tokenPwdExpireAt
+        }),
+        ...credentials.rememberedPwd ? { rememberedPwd: credentials.rememberedPwd } : {}
+      }
+    } : {} }
+  });
+  return next;
+}
 async function backupOnce(root, name, value) {
   if (await readPrivateJson(join6(root, name)) === void 0) await writePrivateJson(root, name, value);
 }
@@ -12212,7 +12316,7 @@ async function assertLegacyStopped(root) {
 // package.json
 var package_default = {
   name: "@mu-cabin/muc-cli",
-  version: "0.6.0",
+  version: "0.6.1",
   description: "Standalone agent-first MUC CLI with an embedded background daemon",
   license: "MIT",
   type: "module",
@@ -22832,6 +22936,14 @@ var NativeDaemonCore = class _NativeDaemonCore {
         state,
         ...delivery === void 0 ? {} : { delivery }
       });
+      for (const profile of await core.profiles.list()) {
+        await state.ensureProfile({
+          profileId: profile.id,
+          ...profile.identity?.account === void 0 ? {} : { accountId: profile.identity.account },
+          ...profile.identity?.displayName === void 0 ? {} : { displayName: profile.identity.displayName },
+          updatedAtMs: profile.updatedAtMs
+        });
+      }
       core.#ownsState = ownsState;
       core.#ownsDelivery = ownsDelivery;
       return core;
@@ -30076,6 +30188,8 @@ async function ensureDaemon(options) {
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
+  let spawned;
+  let spawnFailed = false;
   if (!existingOwner) {
     await ensurePrivateDirectory(join15(root, "run"));
     const logPath = join15(root, "run", "daemon.log");
@@ -30092,7 +30206,10 @@ async function ensureDaemon(options) {
         "daemon",
         "run"
       ], { detached: true, stdio: ["ignore", log.fd, log.fd], windowsHide: true });
-      child.on("error", () => void 0);
+      spawned = child;
+      child.on("error", () => {
+        spawnFailed = true;
+      });
       child.unref();
     } finally {
       await log.close();
@@ -30106,6 +30223,12 @@ async function ensureDaemon(options) {
     } catch (error) {
       if (!(error instanceof DaemonUnavailableError)) throw error;
     }
+    if (spawnFailed || spawned && (spawned.exitCode !== null || spawned.signalCode !== null)) {
+      const entries = await readDiagnosticLog(join15(root, "run", "daemon.log"));
+      const failure = entries.findLast((e) => e.pid === spawned?.pid && e.event === "start-failed");
+      if (failure?.error && failure.error.code !== "CLI_UNEXPECTED_FAILURE") throw new CliConfigError(failure.error.code, failure.error.message, failure.error.code === "CONFIG_INVALID" ? 7 : 1);
+      if (spawnFailed) throw new CliConfigError("DAEMON_START_FAILED", "The daemon process could not be spawned. Check the installed Node executable.", 1);
+    }
     await delay(80);
   }
   throw new CliConfigError("DAEMON_START_FAILED", "The daemon did not become ready. Inspect muc daemon logs.", 1);
@@ -30132,29 +30255,7 @@ async function runDaemonCommand(command2, io) {
   }
   if (command2.action === "run") return runForegroundDaemon(root, io);
   if (command2.action === "logs") {
-    const path = join15(root, "run", "daemon.log");
-    await assertPrivateRegularOrMissing(path);
-    const handle = await open9(path, "r").catch((e) => {
-      if (e.code === "ENOENT") return void 0;
-      throw e;
-    });
-    if (!handle) return { entries: [] };
-    try {
-      const size = (await handle.stat()).size;
-      const buffer = Buffer.alloc(Math.min(size, 64 * 1024));
-      await handle.read(buffer, 0, buffer.length, Math.max(0, size - buffer.length));
-      const entries = buffer.toString("utf8").split("\n").flatMap((line) => {
-        try {
-          const v = LogSchema.safeParse(JSON.parse(line));
-          return v.success ? [v.data] : [];
-        } catch {
-          return [];
-        }
-      }).slice(-100);
-      return { entries };
-    } finally {
-      await handle.close();
-    }
+    return { entries: await readDiagnosticLog(join15(root, "run", "daemon.log")) };
   }
   let client;
   try {
@@ -30178,12 +30279,12 @@ async function runDaemonCommand(command2, io) {
   }
 }
 async function runForegroundDaemon(root, io) {
-  const log = (event) => io.writeStderr(JSON.stringify({ time: (/* @__PURE__ */ new Date()).toISOString(), event }) + "\n");
+  const log = (event, error) => io.writeStderr(JSON.stringify({ time: (/* @__PURE__ */ new Date()).toISOString(), event, pid: process.pid, ...error === void 0 ? {} : { error: diagnosticError(error) } }) + "\n");
   let runtime;
   try {
     runtime = await NativeV2DaemonRuntime.open({ configRoot: root, onBackgroundError: () => log("background-error") });
   } catch (error) {
-    log("start-failed");
+    log("start-failed", error);
     throw error;
   }
   let stop;
@@ -30204,6 +30305,9 @@ async function runForegroundDaemon(root, io) {
     await stopped;
     log("stopped");
     return { stopped: true };
+  } catch (error) {
+    log("start-failed", error);
+    throw error;
   } finally {
     process.off("SIGTERM", onSignal);
     process.off("SIGINT", onSignal);
@@ -30233,8 +30337,48 @@ var InitSchema = external_exports.object({
 }).strict();
 var LogSchema = external_exports.object({
   time: external_exports.string().datetime(),
-  event: external_exports.enum(["started", "stopped", "start-failed", "stop-failed", "background-error"])
+  event: external_exports.enum(["started", "stopped", "start-failed", "stop-failed", "background-error"]),
+  pid: external_exports.number().int().positive().optional(),
+  error: external_exports.object({ code: external_exports.string(), message: external_exports.string(), hint: external_exports.string() }).strict().optional()
 }).strict();
+var diagnostics = {
+  CONFIG_INVALID: { message: "Configuration could not be loaded or migrated.", hint: "Check config.json and credentials.json privately. Preserve the originals and migration backups; do not paste credentials into diagnostics." },
+  LEGACY_DAEMON_RUNNING: { message: "An old daemon is still using this config root.", hint: "Stop the old CLI daemon for this root before retrying." },
+  CLI_UNEXPECTED_FAILURE: { message: "The daemon could not start.", hint: "Check the local configuration, file permissions and installed Node version." }
+};
+function diagnosticError(error) {
+  const code = error instanceof CliConfigError && Object.hasOwn(diagnostics, error.code) ? error.code : "CLI_UNEXPECTED_FAILURE";
+  return { code, ...diagnostics[code] };
+}
+async function readDiagnosticLog(path) {
+  await assertPrivateRegularOrMissing(path);
+  const handle = await open9(path, "r").catch((e) => {
+    if (e.code === "ENOENT") return void 0;
+    throw e;
+  });
+  if (!handle) return [];
+  try {
+    const size = (await handle.stat()).size;
+    const buffer = Buffer.alloc(Math.min(size, 64 * 1024));
+    await handle.read(buffer, 0, buffer.length, Math.max(0, size - buffer.length));
+    return buffer.toString("utf8").split("\n").flatMap((line) => {
+      try {
+        const parsed = LogSchema.safeParse(JSON.parse(line));
+        if (!parsed.success) return [];
+        const value = parsed.data;
+        if (value.error) {
+          const code = Object.hasOwn(diagnostics, value.error.code) ? value.error.code : "CLI_UNEXPECTED_FAILURE";
+          value.error = { code, ...diagnostics[code] };
+        }
+        return [value];
+      } catch {
+        return [];
+      }
+    }).slice(-100);
+  } finally {
+    await handle.close();
+  }
+}
 
 // src/ipc/qr-code.ts
 var import_qrcode = __toESM(require_lib(), 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mu-cabin/muc-cli",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Standalone agent-first MUC CLI with an embedded background daemon",
   "license": "MIT",
   "type": "module",

package/skills/muc/references/profiles-and-lifecycle.md

@@ -6,7 +6,7 @@ The default root is `~/.muc`; `MUC_CONFIG_DIR` and `--config-root` select an iso
 
 - `muc daemon start`: start the background process for this root.
 - `muc daemon status`: inspect without starting it.
-- `muc daemon logs`: read safe diagnostic events, never raw credentials.
+- `muc daemon logs`: read safe diagnostic events with error codes and recovery hints, never raw credentials.
 - `muc daemon stop`: stop this background process; existing credentials and stored messages remain.
 - `muc runtime status --profile-id <id>`: inspect the profile connection.
 - `muc runtime ensure|start|resume|stop --profile-id <id>`: change only the requested profile runtime. Do not use resume to bypass an authentication failure or displacement.
@@ -18,3 +18,5 @@ User-terminal login: `muc login --account <uid> [--profile-id <id>] [--remember]
 The daemon performs accessToken → tokenPwd → remembered-password recovery, with `/emp/get` attempted first. Network errors do not downgrade credentials. Exhausted recovery requires explicit login. Existing profiles preserve their device slot on reauthentication.
 
 Use `muc profile logout --profile-id <id>` only when the user requests logout; it clears that profile's session and remembered password.
+
+Legacy migration supports flat single-account and activeProfile/profiles multi-account roots. It preserves profile IDs, the selected default, device slots and recovery credentials, with private backups and a resumable journal. Different tenants, a missing default or an undecryptable remembered password fail without overwriting the originals. Preserve remember.salt; do not reinitialize or delete credentials to bypass migration errors.