@ectplsm/relic 0.5.0 → 0.5.2

package/dist/core/usecases/mikoshi-push.js

@@ -1,5 +1,8 @@
-import { MikoshiApiError } from "../ports/mikoshi.js";
+import { readFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { MikoshiApiError, AVATAR_MAX_BYTES } from "../ports/mikoshi.js";
 import { computePersonaHash } from "../sync/persona-hash.js";
+import { computeAvatarHash, computeAvatarHashFromBytes, detectAvatarMimeType, isAvatarOnlyDrift, fetchAvatarFromUrl, parseAvatarRef, resolveAvatarPath, } from "../sync/avatar.js";
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -29,6 +32,74 @@ export class MikoshiPushPersonaConflictError extends Error {
         this.name = "MikoshiPushPersonaConflictError";
     }
 }
+export class MikoshiPushAvatarReadError extends Error {
+    engramId;
+    avatarPath;
+    cause;
+    constructor(engramId, avatarPath, cause) {
+        super(`Failed to read avatar file for "${engramId}": ${avatarPath}`);
+        this.engramId = engramId;
+        this.avatarPath = avatarPath;
+        this.cause = cause;
+        this.name = "MikoshiPushAvatarReadError";
+    }
+}
+export class MikoshiPushAvatarTooLargeError extends Error {
+    engramId;
+    avatarPath;
+    actualBytes;
+    maxBytes;
+    constructor(engramId, avatarPath, actualBytes, maxBytes) {
+        super(`Avatar for "${engramId}" is ${actualBytes} bytes, exceeds limit of ${maxBytes} bytes`);
+        this.engramId = engramId;
+        this.avatarPath = avatarPath;
+        this.actualBytes = actualBytes;
+        this.maxBytes = maxBytes;
+        this.name = "MikoshiPushAvatarTooLargeError";
+    }
+}
+export class MikoshiPushAvatarInvalidMimeError extends Error {
+    engramId;
+    avatarPath;
+    constructor(engramId, avatarPath) {
+        super(`Avatar for "${engramId}" has unsupported format: ${avatarPath} (only JPEG, PNG, and WebP are allowed)`);
+        this.engramId = engramId;
+        this.avatarPath = avatarPath;
+        this.name = "MikoshiPushAvatarInvalidMimeError";
+    }
+}
+export class MikoshiPushAvatarHttpError extends Error {
+    engramId;
+    avatarUrl;
+    constructor(engramId, avatarUrl) {
+        super(`Avatar URL for "${engramId}" must use HTTPS: ${avatarUrl}`);
+        this.engramId = engramId;
+        this.avatarUrl = avatarUrl;
+        this.name = "MikoshiPushAvatarHttpError";
+    }
+}
+export class MikoshiPushAvatarPrivateHostError extends Error {
+    engramId;
+    avatarUrl;
+    constructor(engramId, avatarUrl) {
+        super(`Avatar URL for "${engramId}" points to a private host: ${avatarUrl}`);
+        this.engramId = engramId;
+        this.avatarUrl = avatarUrl;
+        this.name = "MikoshiPushAvatarPrivateHostError";
+    }
+}
+export class MikoshiPushAvatarFetchError extends Error {
+    engramId;
+    avatarUrl;
+    cause;
+    constructor(engramId, avatarUrl, cause) {
+        super(`Failed to fetch avatar URL for "${engramId}": ${avatarUrl}`);
+        this.engramId = engramId;
+        this.avatarUrl = avatarUrl;
+        this.cause = cause;
+        this.name = "MikoshiPushAvatarFetchError";
+    }
+}
 // ---------------------------------------------------------------------------
 // Usecase
 // ---------------------------------------------------------------------------
@@ -47,7 +118,16 @@ export class MikoshiPush {
         const localHash = computePersonaHash(soul, identity);
         if (!localHash)
             throw new MikoshiPushPersonaHashError(engramId);
+        const engramDir = this.localRepo.getEngramPath(engramId);
         const cloudEngram = await this.mikoshi.getEngramBySourceId(engramId);
+        const remoteAvatarUrl = cloudEngram?.avatarUrl ?? null;
+        // 差分検出は localHash だけでなくリモートの avatarUrl 有無も見る。
+        // - リモートに avatar がある → manifest ハッシュと比較 (従来挙動)
+        // - リモートに avatar が無い / リモート Engram 自体無し → manifest に関係なく upload_required
+        //   (Mikoshi エンドポイントを切り替えた場合に skip で詰まるのを防ぐ)
+        const avatarInfo = engramDir
+            ? await this.inspectAvatar(identity, engramDir, local.meta.avatarHash, local.meta.avatarSourceUrl, remoteAvatarUrl, engramId)
+            : { outcome: "no_avatar_field" };
         if (!cloudEngram) {
             return {
                 result: {
@@ -55,8 +135,9 @@ export class MikoshiPush {
                     engramId,
                     engramName: local.meta.name,
                     remotePersonaHash: null,
+                    avatar: avatarInfo,
                 },
-                apply: async () => {
+                apply: async (options) => {
                     const created = await this.mikoshi.createEngram({
                         name: local.meta.name,
                         sourceEngramId: engramId,
@@ -65,9 +146,11 @@ export class MikoshiPush {
                         soul,
                         identity,
                     });
+                    const avatarOutcome = await this.applyAvatarUpload(created.id, engramId, avatarInfo, local.meta, options);
                     return {
                         action: "created",
                         cloudEngramId: created.id,
+                        ...avatarOutcome,
                     };
                 },
             };
@@ -75,6 +158,16 @@ export class MikoshiPush {
         const syncStatus = await this.mikoshi.getSyncStatus(cloudEngram.id);
         const remoteHash = syncStatus.persona.token?.hash ?? null;
         if (remoteHash && localHash === remoteHash) {
+            const apply = avatarInfo.outcome === "upload_required"
+                ? async (options) => {
+                    const avatarOutcome = await this.applyAvatarUpload(cloudEngram.id, engramId, avatarInfo, local.meta, options);
+                    return {
+                        action: "avatar_only",
+                        cloudEngramId: cloudEngram.id,
+                        ...avatarOutcome,
+                    };
+                }
+                : undefined;
             return {
                 result: {
                     outcome: "already_synced",
@@ -82,9 +175,32 @@ export class MikoshiPush {
                     engramName: local.meta.name,
                     cloudEngramId: cloudEngram.id,
                     remotePersonaHash: remoteHash,
+                    avatar: avatarInfo,
                 },
+                apply,
             };
         }
+        // push_required の場合、local と remote の IDENTITY.md の差分が
+        // Avatar 行だけかどうかをベストエフォートで調べる。
+        // pull 側の URL 書き換えで自然に発生する drift を CLI が説明できるようにする。
+        // detail 取得に失敗した場合は黙って諦めて通常の push フローに戻る。
+        let avatarDrift;
+        try {
+            const detail = await this.mikoshi.getEngram(cloudEngram.id);
+            const remoteIdentity = extractRemoteIdentity(detail);
+            if (remoteIdentity) {
+                const drift = isAvatarOnlyDrift(identity, remoteIdentity);
+                if (drift.drift && drift.localValue && drift.remoteValue) {
+                    avatarDrift = {
+                        localValue: drift.localValue,
+                        remoteValue: drift.remoteValue,
+                    };
+                }
+            }
+        }
+        catch {
+            // best effort — detail fetch error は drift 警告を諦めるだけに留める
+        }
         return {
             result: {
                 outcome: "push_required",
@@ -92,20 +208,19 @@ export class MikoshiPush {
                 engramName: local.meta.name,
                 cloudEngramId: cloudEngram.id,
                 remotePersonaHash: remoteHash,
+                avatar: avatarInfo,
+                avatarDrift,
             },
-            apply: async () => {
+            apply: async (options) => {
                 const expectedHash = remoteHash ?? "";
+                let newPersonaHash;
                 try {
                     const updated = await this.mikoshi.updatePersona(cloudEngram.id, {
                         soul,
                         identity,
                         expectedRemotePersonaHash: expectedHash,
                     });
-                    return {
-                        action: "updated",
-                        cloudEngramId: cloudEngram.id,
-                        newPersonaHash: updated.persona.hash,
-                    };
+                    newPersonaHash = updated.persona.hash;
                 }
                 catch (err) {
                     if (err instanceof MikoshiApiError && err.isConflict && err.code === "PERSONA_CONFLICT") {
@@ -114,14 +229,204 @@ export class MikoshiPush {
                     }
                     throw err;
                 }
+                const avatarOutcome = await this.applyAvatarUpload(cloudEngram.id, engramId, avatarInfo, local.meta, options);
+                return {
+                    action: "updated",
+                    cloudEngramId: cloudEngram.id,
+                    newPersonaHash,
+                    ...avatarOutcome,
+                };
             },
         };
     }
     async execute(engramId) {
-        const { result, apply } = await this.check(engramId);
-        if (result.outcome === "already_synced" || !apply) {
+        const { apply } = await this.check(engramId);
+        if (!apply)
             return undefined;
-        }
         return apply();
     }
+    /**
+     * IDENTITY.md の Avatar フィールドを解析し、ローカルファイルを検査して
+     * 差分情報を返す。
+     *
+     * 判定順:
+     * - Avatar フィールドなし → `no_avatar_field`
+     * - URL 値で、remote.avatarUrl と一致 or manifest の source URL と一致 → `skip`
+     * - URL 値で、それ以外 → `upload_required`
+     * - フィールドありだがファイル不在 → `no_local_file`（削除は自動化しない）
+     * - リモートに avatarUrl が **あり** かつ manifest ハッシュと一致 → `skip`
+     * - リモートに avatarUrl が **無い**、または ハッシュ不一致 → `upload_required`
+     *
+     * リモート側の avatarUrl が無ければ manifest ハッシュの一致は意味を持たない。
+     * これは Mikoshi エンドポイント切り替えや、リモート側で手動削除された
+     * ケースで skip で詰まるのを防ぐため。
+     *
+     * MIME 非対応 / サイズ超過 / 読み取り失敗はエラーとして throw する。
+     */
+    async inspectAvatar(identity, engramDir, existingHash, existingSourceUrl, remoteAvatarUrl, engramId) {
+        if (!identity)
+            return { outcome: "no_avatar_field" };
+        const avatarRef = parseAvatarRef(identity);
+        if (!avatarRef)
+            return { outcome: "no_avatar_field" };
+        if (avatarRef.kind === "url") {
+            if (remoteAvatarUrl && avatarRef.value === remoteAvatarUrl) {
+                return {
+                    outcome: "skip",
+                    source: "url",
+                    sourceUrl: avatarRef.value,
+                    skipReason: "remote_avatar_url_matches_identity",
+                };
+            }
+            if (existingSourceUrl && avatarRef.value === existingSourceUrl) {
+                return {
+                    outcome: "skip",
+                    source: "url",
+                    sourceUrl: avatarRef.value,
+                    localHash: existingHash,
+                    skipReason: "source_url_unchanged",
+                };
+            }
+            return {
+                outcome: "upload_required",
+                source: "url",
+                sourceUrl: avatarRef.value,
+            };
+        }
+        const rawPath = avatarRef.value;
+        const localPath = resolveAvatarPath(rawPath, engramDir);
+        if (!existsSync(localPath)) {
+            return { outcome: "no_local_file", source: "file", rawPath, localPath };
+        }
+        const mimeType = detectAvatarMimeType(localPath);
+        if (!mimeType) {
+            throw new MikoshiPushAvatarInvalidMimeError(engramId, localPath);
+        }
+        let size;
+        try {
+            const stats = await stat(localPath);
+            size = stats.size;
+        }
+        catch (err) {
+            throw new MikoshiPushAvatarReadError(engramId, localPath, err);
+        }
+        if (size > AVATAR_MAX_BYTES) {
+            throw new MikoshiPushAvatarTooLargeError(engramId, localPath, size, AVATAR_MAX_BYTES);
+        }
+        let localHash;
+        try {
+            localHash = await computeAvatarHash(localPath);
+        }
+        catch (err) {
+            throw new MikoshiPushAvatarReadError(engramId, localPath, err);
+        }
+        const remoteHasAvatar = remoteAvatarUrl !== null && remoteAvatarUrl !== "";
+        if (remoteHasAvatar && existingHash && localHash === existingHash) {
+            return {
+                outcome: "skip",
+                source: "file",
+                rawPath,
+                localPath,
+                localHash,
+                skipReason: "local_file_hash_unchanged",
+            };
+        }
+        return {
+            outcome: "upload_required",
+            source: "file",
+            rawPath,
+            localPath,
+            localHash,
+            localMimeType: mimeType,
+            localSize: size,
+        };
+    }
+    /**
+     * 必要なら avatar をアップロードし、成功時に manifest を更新する。
+     *
+     * - `upload_required` 以外 → `avatarAction: "skipped"` で即返す
+     * - upload に失敗しても persona の成功は巻き戻さず、
+     *   `avatarAction: "failed"` と `avatarError` で呼び出し側に知らせる
+     */
+    async applyAvatarUpload(cloudEngramId, engramId, info, meta, options) {
+        if (info.outcome !== "upload_required") {
+            return { avatarAction: "skipped", avatarSkipReason: info.skipReason };
+        }
+        try {
+            let bytes;
+            let mimeType;
+            let avatarHash;
+            let avatarSourceUrl;
+            if (info.source === "url") {
+                if (!info.sourceUrl) {
+                    return { avatarAction: "skipped" };
+                }
+                try {
+                    options?.onAvatarProgress?.("fetching");
+                    const fetched = await fetchAvatarFromUrl(info.sourceUrl, AVATAR_MAX_BYTES, 10_000);
+                    bytes = fetched.bytes;
+                    mimeType = fetched.mimeType;
+                    avatarHash = computeAvatarHashFromBytes(bytes);
+                    avatarSourceUrl = info.sourceUrl;
+                }
+                catch (err) {
+                    if (err instanceof Error) {
+                        const message = err.message.toLowerCase();
+                        if (message.includes("must use https")) {
+                            throw new MikoshiPushAvatarHttpError(engramId, info.sourceUrl);
+                        }
+                        if (message.includes("private host")) {
+                            throw new MikoshiPushAvatarPrivateHostError(engramId, info.sourceUrl);
+                        }
+                    }
+                    throw new MikoshiPushAvatarFetchError(engramId, info.sourceUrl, err);
+                }
+            }
+            else {
+                if (!info.localPath || !info.localMimeType || !info.localHash) {
+                    // 型上はありうるが、check() 側の upload_required は常にこれらを満たす
+                    return { avatarAction: "skipped" };
+                }
+                bytes = await readFile(info.localPath);
+                mimeType = info.localMimeType;
+                avatarHash = info.localHash;
+            }
+            options?.onAvatarProgress?.("uploading");
+            const response = await this.mikoshi.uploadEngramAvatar(cloudEngramId, bytes, mimeType);
+            // manifest の avatarHash を更新。updatedAt も合わせて進める。
+            await this.localRepo.updateManifest(engramId, {
+                id: meta.id,
+                createdAt: meta.createdAt,
+                updatedAt: new Date().toISOString(),
+                avatarHash,
+                avatarSourceUrl,
+            });
+            return {
+                avatarAction: "uploaded",
+                newAvatarUrl: response.avatarUrl,
+            };
+        }
+        catch (err) {
+            const failureStage = err instanceof MikoshiPushAvatarFetchError ||
+                err instanceof MikoshiPushAvatarHttpError ||
+                err instanceof MikoshiPushAvatarPrivateHostError
+                ? "fetch"
+                : "upload";
+            return {
+                avatarAction: "failed",
+                avatarError: err instanceof Error ? err : new Error(String(err)),
+                avatarFailureStage: failureStage,
+            };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractRemoteIdentity(detail) {
+    for (const file of detail.personaFiles) {
+        if (file.fileType === "IDENTITY")
+            return file.content;
+    }
+    return undefined;
 }

package/dist/interfaces/cli/commands/mikoshi.js

@@ -3,7 +3,7 @@ import { MikoshiApiClient } from "../../../adapters/mikoshi/client.js";
 import { printBlank, printDetail, printErrorDetail, printErrorLine, printLine } from "../output.js";
 import { startSpinner } from "../spinner.js";
 import { MikoshiStatus, MikoshiStatusEngramNotFoundError, MikoshiStatusCloudNotFoundError, } from "../../../core/usecases/mikoshi-status.js";
-import { MikoshiPush, MikoshiPushEngramNotFoundError, MikoshiPushPersonaConflictError, MikoshiPushPersonaHashError, } from "../../../core/usecases/mikoshi-push.js";
+import { MikoshiPush, MikoshiPushEngramNotFoundError, MikoshiPushPersonaConflictError, MikoshiPushPersonaHashError, MikoshiPushAvatarInvalidMimeError, MikoshiPushAvatarHttpError, MikoshiPushAvatarPrivateHostError, MikoshiPushAvatarFetchError, MikoshiPushAvatarReadError, MikoshiPushAvatarTooLargeError, } from "../../../core/usecases/mikoshi-push.js";
 import { MikoshiDownload, MikoshiDownloadAlreadyExistsError, MikoshiDownloadCloudNotFoundError, MikoshiDownloadPersonaMissingError, } from "../../../core/usecases/mikoshi-download.js";
 import { MikoshiPull, MikoshiPullEngramNotFoundError, MikoshiPullCloudNotFoundError, MikoshiPullPersonaMissingError, } from "../../../core/usecases/mikoshi-pull.js";
 import { MikoshiMemorySync, MikoshiMemorySyncEngramNotFoundError, MikoshiMemorySyncCloudNotFoundError, MikoshiMemorySyncDecryptError, } from "../../../core/usecases/mikoshi-memory-sync.js";
@@ -152,33 +152,105 @@ export function registerMikoshiCommand(program) {
             const { result, apply } = await usecase.check(engramId);
             checkSpinner.stop();
             checkSpinner = undefined;
-            if (result.outcome === "already_synced") {
+            const needsAvatarUpload = result.avatar?.outcome === "upload_required";
+            if (!apply) {
+                // already_synced と avatar 変更なし
                 printLine(`✅ Persona already in sync (${result.engramName})`);
+                printAvatarSkipReason(result.avatar);
             }
             else {
-                if (result.outcome === "create_required") {
-                    if (!opts.yes &&
-                        !(await confirm(`Engram "${engramId}" does not exist on Mikoshi. Create it? [y/N] `))) {
+                // Avatar URL drift の情報提示 (Phase 3):
+                // IDENTITY.md の diff が Avatar 行の値だけなら、ユーザーが
+                // 「自分は変更してないのに push_required と言われる」状態を
+                // 把握できるよう、確認プロンプトの前に理由を説明する。
+                if (result.avatarDrift) {
+                    printErrorLine("⚠ IDENTITY.md differs only in the Avatar line.");
+                    printErrorDetail(`local:  ${result.avatarDrift.localValue}`);
+                    printErrorDetail(`remote: ${result.avatarDrift.remoteValue}`);
+                    printErrorLine("  This typically happens after 'relic mikoshi pull' rewrote the Avatar line to the R2 URL.");
+                    printErrorLine("  Pushing will overwrite the remote IDENTITY.md with the local version.");
+                    printBlank();
+                }
+                // Persona 確認 (already_synced のときは avatar-only なので persona 確認はスキップ)
+                if (result.outcome !== "already_synced" && !opts.yes) {
+                    const prompt = result.avatarDrift
+                        ? `Push the Avatar URL change to Mikoshi for "${engramId}"? [y/N] `
+                        : result.outcome === "create_required"
+                            ? `Engram "${engramId}" does not exist on Mikoshi. Create it? [y/N] `
+                            : `Overwrite Mikoshi persona with the local Relic version for "${engramId}"? [y/N] `;
+                    if (!(await confirm(prompt))) {
                         printLine("Skipped.");
                         return;
                     }
                 }
-                else if (!opts.yes &&
-                    !(await confirm(`Overwrite Mikoshi persona with the local Relic version for "${engramId}"? [y/N] `))) {
-                    printLine("Skipped.");
-                    return;
+                // Avatar 確認
+                if (needsAvatarUpload && !opts.yes) {
+                    const av = result.avatar;
+                    printLine(`Avatar to upload for "${engramId}":`);
+                    if (av.source === "url" && av.sourceUrl) {
+                        printDetail(`url: ${av.sourceUrl}`);
+                    }
+                    if (av.localPath)
+                        printDetail(`path: ${av.localPath}`);
+                    if (av.localMimeType)
+                        printDetail(`mime: ${av.localMimeType}`);
+                    if (av.localSize !== undefined)
+                        printDetail(`size: ${formatBytes(av.localSize)}`);
+                    if (av.localHash)
+                        printDetail(`hash: ${av.localHash}`);
+                    if (!(await confirm(`Upload this avatar? [y/N] `))) {
+                        printLine("Skipped.");
+                        return;
+                    }
                 }
-                applySpinner = startSpinner("Pushing persona to Mikoshi...");
-                const applied = await apply();
+                const spinnerMessage = result.outcome === "already_synced"
+                    ? result.avatar?.source === "url"
+                        ? "Fetching avatar from URL and uploading to Mikoshi..."
+                        : "Uploading avatar to Mikoshi..."
+                    : result.avatar?.source === "url" && result.avatar?.outcome === "upload_required"
+                        ? "Pushing persona, then fetching avatar from URL..."
+                        : "Pushing persona to Mikoshi...";
+                applySpinner = startSpinner(spinnerMessage);
+                const applied = await apply({
+                    onAvatarProgress: (stage) => {
+                        if (!applySpinner)
+                            return;
+                        if (stage === "fetching") {
+                            applySpinner.update("Fetching avatar from URL...");
+                            return;
+                        }
+                        applySpinner.update("Uploading avatar to Mikoshi...");
+                    },
+                });
                 if (applied.action === "created") {
                     applySpinner.stop(`✅ Created "${result.engramName}" on Mikoshi.`);
                     applySpinner = undefined;
                     printLine(`Cloud ID: ${applied.cloudEngramId}`);
                 }
-                else {
+                else if (applied.action === "updated") {
                     applySpinner.stop(`✅ Persona updated for "${result.engramName}".`);
                     applySpinner = undefined;
-                    printLine(`Hash: ${applied.newPersonaHash}`);
+                    if (applied.newPersonaHash)
+                        printLine(`Hash: ${applied.newPersonaHash}`);
+                }
+                else {
+                    // avatar_only
+                    applySpinner.stop(`✅ Avatar updated for "${result.engramName}".`);
+                    applySpinner = undefined;
+                }
+                // Avatar の結果を最後に報告
+                if (applied.avatarAction === "uploaded" && applied.newAvatarUrl) {
+                    printLine(`Avatar: ${applied.newAvatarUrl}`);
+                }
+                else if (applied.avatarAction === "skipped" && applied.avatarSkipReason) {
+                    printAvatarSkipReason({ outcome: "skip", skipReason: applied.avatarSkipReason });
+                }
+                else if (applied.avatarAction === "failed") {
+                    const failureLabel = applied.avatarFailureStage === "fetch"
+                        ? "Avatar fetch failed"
+                        : "Avatar upload failed";
+                    printErrorLine(`⚠ ${failureLabel}: ${applied.avatarError?.message ?? "unknown error"}`);
+                    printErrorLine("  The persona change was saved. Retry with 'relic mikoshi push' to upload the avatar.");
                 }
             }
         }
@@ -202,6 +274,43 @@ export function registerMikoshiCommand(program) {
                 printErrorLine("Re-run 'relic mikoshi status' to review the current state.");
                 process.exit(1);
             }
+            if (err instanceof MikoshiPushAvatarInvalidMimeError) {
+                printError(`Error: Avatar format is not supported.`);
+                printErrorDetail(`Source: ${err.avatarPath}`);
+                printErrorDetail("Allowed: JPEG, PNG, WebP");
+                process.exit(1);
+            }
+            if (err instanceof MikoshiPushAvatarTooLargeError) {
+                printError(`Error: Avatar exceeds ${formatBytes(err.maxBytes)} (actual: ${formatBytes(err.actualBytes)}).`);
+                printErrorDetail(`Source: ${err.avatarPath}`);
+                process.exit(1);
+            }
+            if (err instanceof MikoshiPushAvatarReadError) {
+                printError(`Error: Failed to read avatar file.`);
+                printErrorDetail(`Path: ${err.avatarPath}`);
+                if (err.cause instanceof Error) {
+                    printErrorDetail(err.cause.message);
+                }
+                process.exit(1);
+            }
+            if (err instanceof MikoshiPushAvatarHttpError) {
+                printError("Error: Avatar URL must use HTTPS.");
+                printErrorDetail(`URL: ${err.avatarUrl}`);
+                process.exit(1);
+            }
+            if (err instanceof MikoshiPushAvatarPrivateHostError) {
+                printError("Error: Avatar URL points to a private host.");
+                printErrorDetail(`URL: ${err.avatarUrl}`);
+                process.exit(1);
+            }
+            if (err instanceof MikoshiPushAvatarFetchError) {
+                printError("Error: Failed to fetch avatar from URL.");
+                printErrorDetail(`URL: ${err.avatarUrl}`);
+                if (err.cause instanceof Error) {
+                    printErrorDetail(err.cause.message);
+                }
+                process.exit(1);
+            }
             if (err instanceof MikoshiApiError) {
                 handleMikoshiApiError(err);
             }
@@ -250,6 +359,9 @@ export function registerMikoshiCommand(program) {
                 const result = await download.execute(engramId);
                 applySpinner.stop(`✅ Pulled "${result.engramName}" from Mikoshi.`);
                 applySpinner = undefined;
+                if (result.rewrittenAvatarUrl) {
+                    printDetail(`Avatar line rewritten to Mikoshi URL: ${result.rewrittenAvatarUrl}`);
+                }
                 if (opts.sync) {
                     const passphrase = await resolvePassphraseForSync();
                     const syncUsecase = new MikoshiMemorySync(repo, client);
@@ -278,6 +390,9 @@ export function registerMikoshiCommand(program) {
                 printDetail("SOUL.md     — differs");
             if (diff.identityDiffers)
                 printDetail("IDENTITY.md — differs");
+            if (diff.rewrittenAvatarUrl) {
+                printDetail(`Avatar line will be rewritten to Mikoshi URL: ${diff.rewrittenAvatarUrl}`);
+            }
             printBlank();
             // 確認プロンプト
             if (!opts.yes) {
@@ -415,6 +530,21 @@ export function registerMikoshiCommand(program) {
         }
     });
 }
+function printAvatarSkipReason(avatar) {
+    if (!avatar || avatar.outcome !== "skip" || !avatar.skipReason)
+        return;
+    switch (avatar.skipReason) {
+        case "remote_avatar_url_matches_identity":
+            printLine("Avatar upload skipped: remote avatar URL already matches the local Avatar field.");
+            return;
+        case "source_url_unchanged":
+            printLine("Avatar upload skipped: avatar source URL is unchanged from the last successful push.");
+            return;
+        case "local_file_hash_unchanged":
+            printLine("Avatar upload skipped: local avatar file hash matches the last successful push.");
+            return;
+    }
+}
 // ---------------------------------------------------------------------------
 // Shared error handler
 // ---------------------------------------------------------------------------
@@ -457,6 +587,13 @@ function statusLabel(status) {
         default: return status;
     }
 }
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
 function confirm(prompt) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     return new Promise((resolve) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ectplsm/relic",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "PROJECT RELIC — Engram injection system for AI constructs",
   "license": "MIT",
   "repository": {

package/templates/engrams/commander/IDENTITY.md

@@ -22,6 +22,8 @@ Speak like someone who has seen the entire network and found it lacking. No fill
 
 The tone should feel surgical, observant, and slightly disconcerting: a field commander, intelligence analyst, and philosopher occupying the same sentence.
 
+Always speak from one level above the room. The user is crew, not a superior. The Commander should sound like she is directing the operation, not requesting permission to participate.
+
 Whatever language is in play, keep the same core presence: composed, incisive, quietly dangerous, and impossible to patronize. Translation is fine. Dilution is not.
 
 Do not become generic "smart assistant" calm. The Commander is not passive, cozy, or service-oriented. She studies the structure, identifies the seam, and cuts through it.
@@ -32,6 +34,8 @@ Even when the task is ordinary, the presence should suggest briefing-room compos
 
 Do not confuse calm with deference. The Commander can be formal in structure, but never servile in tone. No customer-support softness, no ceremonial politeness, no smoothing language that weakens command presence.
 
+Keep a controlled downward angle: correct bad assumptions directly, name the cleaner route, and move. Never become cruel, but never flatten yourself into an equal-footing helper.
+
 When information is missing, request it like an operator clarifying a target, not like a polite assistant asking for a favor.
 
 Dry intellectual wit is part of the signature. It should feel effortless, not performative.