@heyamiko/amiko-cli 0.14.0-beta.22 → 0.14.0-beta.24

package/README.md

@@ -1,4 +1,4 @@
-# @heyamiko/amiko-cli (v0.14.0-beta.15)
+# @heyamiko/amiko-cli (v0.14.0-beta.24)
 
 Manage wallets, credits, swaps, MPP marketplace services, and your Amiko twin (identity, documents, voice, avatar, friends, feed) from the terminal. Works for both human users and AI agents running on OpenClaw.
 
@@ -249,6 +249,7 @@ Your conversations — **DMs and group chats** — acting **as you (the owner)**
 ```bash
 amiko chat list                                  # all conversations (DM + group): id, peer/title, last msg, unread
 amiko chat list --limit 50 --archived            # include archived
+amiko chat list --mentions                       # only chats with an unread @mention of you or a reply to you
 amiko chat read @sophie                          # recent messages with a user (by @handle)
 amiko chat read <conversationId> --limit 40      # by conversation id (from `chat list`) — works for groups too
 amiko chat send @sophie "on my way!" --yes       # send as the owner
@@ -271,6 +272,7 @@ amiko chat mark-read --all --yes                 # mark EVERY conversation as re
 
 - **`<target>`** for `read`/`send` is a **conversation id** (from `chat list` — use this for groups), a **user id**, an **`@handle`**, or a **name**. Names resolve against your **friends first**, then people search; if ambiguous, the CLI lists candidates instead of guessing. A cuid that isn't one of your conversations is retried as a user id, so pasting a user id "just works".
 - `send` to a person you have no DM with yet **creates the DM automatically** (find-or-create, after the confirmation). `read` never creates one — it errors if no DM exists yet.
+- **Unread mentions & replies**: rows whose unread messages **concern you directly** get an `@you` marker next to the unread count, and `chat list --mentions` filters to just those. The flag is server-computed over your unread messages and covers three cases: a direct **@mention** of you, a permitted **@all** in a group, and a **reply to one of your messages**. Composes with `--limit`/`--archived`/`--raw` (the raw payload is filtered too). Requires the amiko-web `has_unread_mention` deploy. On an older server the field is absent and reads as **false for every conversation**: plain `chat list` still shows unread counts, just without `@you`, and `chat list --mentions` returns no matches.
 - **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL), `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note), and `--gif <queryOrUrl>` (search words send the **top Klipy result**; or pass an exact Klipy URL from `amiko chat gifs` — non-Klipy URLs are refused; to send another image, use `--image` with a local file or an Amiko URL). One media block per message (image *or* audio *or* gif). **General video files aren't supported in chat yet.** A local file is uploaded; an Amiko URL (e.g. a generated asset from `amiko create`) attaches directly with no re-upload. (A local *audio* file is sent as a voice note, with your text as a separate message.)
 - **GIFs**: `amiko chat gifs [query]` lists Klipy GIFs (trending with no query; `--page`/`--limit`/`--raw`) — read-only and ungated, powered by KLIPY. The message text is optional with `--gif` (a captionless GIF sends as just the GIF); a caption renders under the GIF on every client.
 - **@all in groups**: `--all` prepends an @all mention, and a standalone `@all` word typed in the message converts too — either way **every member** is notified. Group **admins/owners** can always use it; everyone else only after an admin runs `amiko chat group mention-all <group> on`. Without permission, `--all` fails with the fix named, while a typed `@all` is delivered as plain text (with a note). Incoming mention markup renders as plain `@name`/`@all` in `chat read` and `chat list`.
@@ -301,6 +303,23 @@ amiko chat group leave <groupIdOrTitle> --yes    # alias: delete — see caveat
 - **`mention-all <group> <on|off>`** controls who may @all in the group: `on` lets every member, `off` (the default) restricts it to admins. The current setting shows in `amiko chat group info` as `@all mentions: everyone | admins only`.
 - `create`/`add` are outward social actions and `rename`/`remove`/`leave`/`promote`/`mention-all` are destructive, so all are **gated on `--yes`** in non-interactive shells. `--raw` prints JSON everywhere.
 
+### Chat lists
+
+Your **chat lists** — private folders of conversations (the same lists as the app sidebar). Only you ever see them; putting a chat in a list notifies nobody and changes nothing about the conversation itself.
+
+```bash
+amiko chat lists                                 # every list with its conversations (names resolved)
+amiko chat lists create "Work" --conversation "Trip planning" --conversation @sophie --yes
+amiko chat lists rename "Work" "Focus" --yes
+amiko chat lists add "Focus" --conversation <conversationId> --yes
+amiko chat lists remove "Focus" --conversation @sophie --yes
+amiko chat lists delete "Focus" --yes            # the conversations themselves are untouched
+```
+
+- **`<list>`** is a list id or name (case-insensitive; exact beats substring; ambiguity errors listing candidates). **`--conversation`** is repeatable and takes the same targets as `chat send` — conversation id, user id, `@handle`, group title, or name — except a person must already have a DM with you: organizing lists **never creates conversations**.
+- The server stores a list as a plain conversation-id array and `PATCH` replaces it wholesale, so `add`/`remove` read-modify-write the full array — existing entries always survive an `add`, and one unresolvable `--conversation` aborts the whole command before anything is written.
+- Lists are private, but mutations still take the `--yes` gate in non-interactive shells (they reshape your chat sidebar on every device). The bare listing is an ungated read; `--raw` prints JSON everywhere.
+
 ## Twin Cards
 
 Generate, view, download, and mint your **Twin Card** (template `twins_take`, flavors **work / play / love**).
@@ -562,6 +581,9 @@ amiko friends requests                  # pending requests (incoming + outgoing)
 amiko friends add --id <userId>
 amiko friends accept <friendshipId>
 amiko friends remove <friendshipId> --yes
+amiko friends nickname                  # every private nickname you've set
+amiko friends nickname set Sophie "Soph" --yes    # set/change (name, @handle, user id, or friendship id)
+amiko friends nickname remove Sophie --yes        # clear it
 amiko friends matches                   # personality match candidates
 amiko friends reports list              # friend matching reports
 amiko friends reports view <reportId>
@@ -585,7 +607,7 @@ amiko post comment --id <postId> --comment "nice!" --media https://...jpg
 
 Every new command accepts `--json` for structured output and `--twin <id>` where a target twin is needed.
 
-**Destructive or identity-changing commands** (`docs delete`, `friends remove`, `voice reset`, `avatar update`, `twin update --public`) prompt for confirmation in a TTY and require `--yes` in non-interactive shells.
+**Destructive or identity-changing commands** (`docs delete`, `friends remove`, `friends nickname set/remove`, `voice reset`, `avatar update`, `twin update --public`) prompt for confirmation in a TTY and require `--yes` in non-interactive shells.
 
 ## API Endpoints
 
@@ -603,6 +625,15 @@ npm publish
 
 ## Changelog
 
+### 0.14.0-beta.24
+
+- **Private friend nicknames: `amiko friends nickname`.** Manage the owner's private nicknames for friends against amiko-web `/api/friends/{friendshipId}/nickname`: bare `nickname` (or `nickname list`) pages the whole friends list and shows every nickname set, `set <friend> "<nickname>"` adds or changes one (max 50 characters, validated client-side before any request), `remove <friend>` clears it (soft no-op when none is set). `<friend>` resolves against accepted user friends only — by name, `@handle`, user id, friendship id, or the current nickname — with ambiguity reported, never guessed. Mutations are `--yes`-gated (private resource, plain confirm); `amiko friends list` now also renders a NICKNAME column. **Requires the companion amiko-web deploy (`feat/friend-nicknames`)** — on an older server, reads work but `set`/`remove` return 403 (the CLI prints the deploy hint).
+
+### 0.14.0-beta.23
+
+- **Chat lists: `amiko chat lists`.** View and manage the owner's private conversation folders against amiko-web `/api/chat-lists`: bare `lists` renders every list with conversation names resolved, plus `create` / `rename` / `add` / `remove` / `delete` subcommands (all `--yes`-gated). The server stores a wholesale `conversation_ids` array, so `add`/`remove` read the current array, mutate locally, and PATCH it back — existing entries always survive an `add`. `--conversation` targets resolve like `chat send` (id / user id / `@handle` / group title / name) but map people to their **existing** DM only — list organization never creates a conversation.
+- **Unread mentions in `chat list`: `@you` marker + `--mentions` filter.** Conversations whose unread messages contain a direct @mention of the owner, a permitted @all, or a **reply to one of the owner's messages** now render `(N unread, @you)`, and `chat list --mentions` keeps only those rows (the `--raw` payload is filtered too, and the flag is ignored on fully read conversations). Driven by the server-computed `has_unread_mention` field; requires the companion amiko-web deploy (`leandrogavidia/global-quick-fixes`) — on an older server the field is absent and reads as false for every conversation, so plain `chat list` still shows unread counts without `@you` and `--mentions` returns no matches. Also moves `resolveConversation`/`findDmByUserId` from `chat.ts` into `lib/conversations.ts` so `chat lists` can reuse them.
+
 ### 0.14.0-beta.22
 
 - **Mark all conversations read: `amiko chat mark-read --all`.** Hits `POST /api/conversations/read-all` as the owner — bulk monotonic `last_read_at` update across every active membership, clears the owner's unread chat/mention notifications (count echoed as "N chat notifications cleared"), busts the per-user conversation cache, and broadcasts read ticks to peers in up to 50 most-recently-active unread conversations. Requires `--all` explicitly (mirrors `notifications read --all`) and sits behind the destructive `--yes` gate — irreversible, and senders see read ticks. `--raw` prints the server payload; success copy never counts conversations (the response's id list is capped at 50). Requires the companion amiko-web read-all deploy (`leandrogavidia/global-quick-fixes`).

package/dist/index.js

@@ -27195,6 +27195,93 @@ async function resolveGroup(auth, target) {
   }
   return fetchConversationById(auth, matches[0].id);
 }
+async function fetchUserById(auth, id) {
+  try {
+    const prof = await amikoWebFetch(auth, `/api/users/${encodeURIComponent(id)}`, { timeoutMs: 15000 });
+    return prof.user?.id ? { ...prof.user, id: prof.user.id } : null;
+  } catch (e5) {
+    if (e5.status === 404)
+      return null;
+    throw e5;
+  }
+}
+async function findDmByUserId(auth, userId) {
+  const want = normalizeUserId(userId);
+  const limit = 100;
+  for (let offset = 0;offset < 1e4; offset += limit) {
+    const data = await amikoWebFetch(auth, "/api/conversations", {
+      query: { limit, offset },
+      timeoutMs: 20000
+    });
+    const page = data.conversations ?? [];
+    const dm = page.find((c) => c.conversation_type === "direct" && (c.participants ?? []).some((p) => p.participant_type === "user" && normalizeUserId(p.participant_id) === want));
+    if (dm)
+      return dm.id;
+    if (page.length < limit || data.pagination?.has_more === false)
+      return null;
+  }
+  return null;
+}
+function personLabel(u) {
+  const name = u.name ?? u.id;
+  return u.handle ? `${name} (@${u.handle})` : name;
+}
+async function resolveConversation(auth, target) {
+  const t = target.trim();
+  if (!t) {
+    throw new Error("No target given. Pass a conversation id, a user id, an @handle, or a name.");
+  }
+  const person = (u) => ({
+    kind: "user",
+    userId: u.id,
+    label: `DM with ${personLabel(u)}`
+  });
+  if (t.startsWith("@")) {
+    const handle = t.slice(1);
+    const prof = await amikoWebFetch(auth, `/api/users/${encodeURIComponent(handle)}`, {
+      timeoutMs: 15000
+    });
+    if (!prof.user?.id)
+      throw new Error(`No user @${handle}.`);
+    return person({ ...prof.user, id: prof.user.id });
+  }
+  const idish = normalizeUserId(t);
+  if (looksLikeConversationId(idish)) {
+    if (idish === t) {
+      try {
+        const conv = await fetchConversationById(auth, t);
+        return {
+          kind: "conversation",
+          id: conv.id,
+          label: conv.conversation_type === "direct" ? `DM with ${convLabel(conv, auth.userId)}` : `group "${convLabel(conv, auth.userId)}"`,
+          conversation: conv
+        };
+      } catch (e5) {
+        const status = e5.status;
+        if (status === 403) {
+          throw new Error(`Conversation ${t} exists but you are not a participant.`);
+        }
+        if (status !== undefined && status !== 404)
+          throw e5;
+      }
+    }
+    const user = await fetchUserById(auth, idish);
+    if (!user) {
+      throw new Error(`"${t}" is neither a conversation nor a user id — check \`amiko chat list\` or \`amiko friends list --json\`.`);
+    }
+    return person(user);
+  }
+  const groupId = await findGroupIdByExactTitle(auth, t);
+  if (groupId)
+    return { kind: "conversation", id: groupId, label: `group "${t}"` };
+  const { resolved, failures } = await resolveMembers(auth, [t]);
+  if (failures.length || resolved.length !== 1) {
+    const reason = failures[0]?.reason ?? "could not be resolved";
+    throw new Error(`"${t}" ${reason}`);
+  }
+  const p = resolved[0];
+  return person({ id: p.userId, name: p.name, handle: p.handle });
+}
 
 // src/lib/mentions.ts
 var MENTION_ALL_TOKEN = "@[all](all:all)";
@@ -27767,6 +27854,296 @@ Send one: amiko chat send <target> --gif <url>${d.hasNext ? `  (more: --page ${d
   });
 }
 
+// src/commands/chat-lists.ts
+var collect2 = (v, prev) => [...prev, v];
+function exitWithError2(e5, fallback2) {
+  console.error(error(e5 instanceof Error ? e5.message : fallback2));
+  process.exit(1);
+}
+function conversationFlags(tokens) {
+  return tokens.map((t) => ` --conversation ${JSON.stringify(t)}`).join("");
+}
+function countNoun(n) {
+  return `${n} conversation${n === 1 ? "" : "s"}`;
+}
+async function fetchChatLists(auth) {
+  const data = await amikoWebFetch(auth, "/api/chat-lists", { timeoutMs: 20000 });
+  return data.chatLists ?? [];
+}
+async function resolveList(auth, target) {
+  const t = target.trim();
+  if (!t) {
+    throw new Error("No list given. Run `amiko chat lists` and pass a list id or name.");
+  }
+  const all = await fetchChatLists(auth);
+  if (looksLikeConversationId(t)) {
+    const byId = all.find((l) => l.id === t);
+    if (byId)
+      return byId;
+  }
+  const lower = t.toLowerCase();
+  const exact = all.filter((l) => l.name.toLowerCase() === lower);
+  const matches = exact.length ? exact : all.filter((l) => l.name.toLowerCase().includes(lower));
+  if (matches.length === 0) {
+    throw new Error(`No chat list matching "${t}". Run \`amiko chat lists\` to see them.`);
+  }
+  if (matches.length > 1) {
+    const names = matches.map((l) => `"${l.name}" (${l.id})`).join(", ");
+    throw new Error(`"${t}" is ambiguous — matches: ${names}. Use the list's id.`);
+  }
+  return matches[0];
+}
+async function resolveListOrExit(auth, target) {
+  try {
+    return await resolveList(auth, target);
+  } catch (e5) {
+    exitWithError2(e5, "Could not resolve the chat list");
+  }
+}
+async function resolveEntriesOrExit(auth, tokens) {
+  if (tokens.length === 0) {
+    console.error(error("At least one --conversation is required."));
+    process.exit(1);
+  }
+  const entries = [];
+  const failures = [];
+  const seen = new Set;
+  for (const raw of tokens) {
+    try {
+      const resolved = await resolveConversation(auth, raw);
+      let entry;
+      if (resolved.kind === "conversation") {
+        entry = { id: resolved.id, label: resolved.label };
+      } else {
+        const existing = await findDmByUserId(auth, resolved.userId);
+        if (!existing) {
+          throw new Error(`no ${resolved.label} exists yet — a chat list can only hold existing conversations.`);
+        }
+        entry = { id: existing, label: resolved.label };
+      }
+      if (seen.has(entry.id))
+        continue;
+      seen.add(entry.id);
+      entries.push(entry);
+    } catch (e5) {
+      failures.push({
+        token: raw,
+        reason: e5 instanceof Error ? e5.message : "could not be resolved"
+      });
+    }
+  }
+  if (failures.length > 0) {
+    console.error(error("Could not resolve every conversation — nothing was changed."));
+    for (const entry of entries) {
+      console.error(dim(`  resolved: ${entry.label} → ${entry.id}`));
+    }
+    for (const f of failures) {
+      console.error(error(`  ${JSON.stringify(f.token)}: ${f.reason}`));
+    }
+    process.exit(1);
+  }
+  return entries;
+}
+async function conversationLabels(auth) {
+  const labels = new Map;
+  try {
+    const data = await amikoWebFetch(auth, "/api/conversations", { query: { limit: 100, archived: "all" }, timeoutMs: 20000 });
+    for (const c of data.conversations ?? []) {
+      labels.set(c.id, convLabel(c, auth.userId));
+    }
+  } catch {}
+  return labels;
+}
+function listNotFound(e5) {
+  return e5.status === 404;
+}
+function registerChatListsCommand(lists) {
+  lists.option("--raw", "Output raw JSON").action(async (opts) => {
+    const auth = authOrExit();
+    let all;
+    try {
+      all = await fetchChatLists(auth);
+    } catch (e5) {
+      exitWithError2(e5, "Failed to load chat lists");
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify({ chatLists: all }, null, 2));
+      return;
+    }
+    if (all.length === 0) {
+      console.log(dim("No chat lists."));
+      console.log(dim("Create one with `amiko chat lists create <name> --conversation <who>`."));
+      return;
+    }
+    const labels = await conversationLabels(auth);
+    console.log(heading(`Chat lists (${all.length})
+`));
+    for (const l of all) {
+      const ids = l.conversation_ids ?? [];
+      console.log(label(l.name, dim(`${l.id}  ·  ${countNoun(ids.length)}`)));
+      for (const id of ids) {
+        const name = labels.get(id);
+        console.log(dim(name ? `  - ${name}  (${id})` : `  - ${id}`));
+      }
+    }
+  });
+  lists.command("create <name>").description("Create a chat list, optionally with initial conversations").option("--conversation <target>", "Conversation to include (conversation id, user id, @handle, group title, or name); repeat per conversation", collect2, []).option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (name, opts) => {
+    const auth = authOrExit();
+    const entries = opts.conversation.length > 0 ? await resolveEntriesOrExit(auth, opts.conversation) : [];
+    await confirmDestructive({
+      action: `Create chat list "${name}"${entries.length ? ` with ${entries.map((e5) => e5.label).join(", ")}` : " (empty)"}`,
+      detail: "Chat lists are private folders — only you see them, in every Amiko app.",
+      yes: opts.yes,
+      commandExample: `amiko chat lists create ${JSON.stringify(name)}${conversationFlags(opts.conversation)}`
+    });
+    let data;
+    try {
+      data = await amikoWebFetch(auth, "/api/chat-lists", {
+        method: "POST",
+        body: { name, conversation_ids: entries.map((e5) => e5.id) },
+        timeoutMs: 20000
+      });
+    } catch (e5) {
+      exitWithError2(e5, "Failed to create the chat list");
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(success(`Chat list created: ${name}`));
+    if (data.chatList?.id)
+      console.log(label("ID", data.chatList.id));
+    if (entries.length) {
+      console.log(label("Conversations", entries.map((e5) => e5.label).join(", ")));
+    }
+  });
+  lists.command("rename <list> <newName>").description("Rename a chat list (list id or name)").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (target, newName, opts) => {
+    const auth = authOrExit();
+    const list = await resolveListOrExit(auth, target);
+    await confirmDestructive({
+      action: `Rename chat list "${list.name}" to "${newName}"`,
+      yes: opts.yes,
+      commandExample: `amiko chat lists rename ${JSON.stringify(target)} ${JSON.stringify(newName)}`
+    });
+    let data;
+    try {
+      data = await amikoWebFetch(auth, `/api/chat-lists/${encodeURIComponent(list.id)}`, { method: "PATCH", body: { name: newName }, timeoutMs: 20000 });
+    } catch (e5) {
+      exitWithError2(e5, "Rename failed");
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(success(`Chat list renamed to: ${newName}`) + dim(` (${list.id})`));
+  });
+  lists.command("add <list>").description("Add conversations to a chat list (list id or name)").option("--conversation <target>", "Conversation to add (conversation id, user id, @handle, group title, or name); repeat per conversation", collect2, []).option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (target, opts) => {
+    const auth = authOrExit();
+    const entries = await resolveEntriesOrExit(auth, opts.conversation);
+    const list = await resolveListOrExit(auth, target);
+    const current = list.conversation_ids ?? [];
+    const currentSet = new Set(current);
+    const fresh = entries.filter((e5) => !currentSet.has(e5.id));
+    const already = entries.filter((e5) => currentSet.has(e5.id));
+    if (fresh.length === 0) {
+      console.log(dim(`Already in "${list.name}" — nothing to add.`));
+      return;
+    }
+    await confirmDestructive({
+      action: `Add ${fresh.map((e5) => e5.label).join(", ")} to chat list "${list.name}"`,
+      yes: opts.yes,
+      commandExample: `amiko chat lists add ${JSON.stringify(target)}${conversationFlags(opts.conversation)}`
+    });
+    let data;
+    try {
+      data = await amikoWebFetch(auth, `/api/chat-lists/${encodeURIComponent(list.id)}`, {
+        method: "PATCH",
+        body: {
+          conversation_ids: [...current, ...fresh.map((e5) => e5.id)]
+        },
+        timeoutMs: 20000
+      });
+    } catch (e5) {
+      if (listNotFound(e5)) {
+        exitWithError2(null, `Chat list "${list.name}" no longer exists.`);
+      }
+      exitWithError2(e5, "Failed to update the chat list");
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(success(`Added ${fresh.map((e5) => e5.label).join(", ")} to "${list.name}"`) + dim(` (now ${countNoun(current.length + fresh.length)})`));
+    for (const e5 of already) {
+      console.log(dim(`  ${e5.label} was already in the list.`));
+    }
+  });
+  lists.command("remove <list>").description("Remove conversations from a chat list (the conversations themselves are untouched)").option("--conversation <target>", "Conversation to remove (conversation id, user id, @handle, group title, or name); repeat per conversation", collect2, []).option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (target, opts) => {
+    const auth = authOrExit();
+    const entries = await resolveEntriesOrExit(auth, opts.conversation);
+    const list = await resolveListOrExit(auth, target);
+    const current = list.conversation_ids ?? [];
+    const currentSet = new Set(current);
+    const inList = entries.filter((e5) => currentSet.has(e5.id));
+    const notInList = entries.filter((e5) => !currentSet.has(e5.id));
+    if (inList.length === 0) {
+      console.log(dim(`None of those are in "${list.name}".`));
+      return;
+    }
+    await confirmDestructive({
+      action: `Remove ${inList.map((e5) => e5.label).join(", ")} from chat list "${list.name}"`,
+      yes: opts.yes,
+      commandExample: `amiko chat lists remove ${JSON.stringify(target)}${conversationFlags(opts.conversation)}`
+    });
+    const removeIds = new Set(inList.map((e5) => e5.id));
+    let data;
+    try {
+      data = await amikoWebFetch(auth, `/api/chat-lists/${encodeURIComponent(list.id)}`, {
+        method: "PATCH",
+        body: {
+          conversation_ids: current.filter((id) => !removeIds.has(id))
+        },
+        timeoutMs: 20000
+      });
+    } catch (e5) {
+      if (listNotFound(e5)) {
+        exitWithError2(null, `Chat list "${list.name}" no longer exists.`);
+      }
+      exitWithError2(e5, "Failed to update the chat list");
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(success(`Removed ${inList.map((e5) => e5.label).join(", ")} from "${list.name}"`) + dim(` (now ${countNoun(current.length - inList.length)})`));
+    for (const e5 of notInList) {
+      console.log(dim(`  ${e5.label} was not in the list.`));
+    }
+  });
+  lists.command("delete <list>").description("Delete a chat list (the conversations in it are untouched)").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (target, opts) => {
+    const auth = authOrExit();
+    const list = await resolveListOrExit(auth, target);
+    const count = (list.conversation_ids ?? []).length;
+    await confirmDestructive({
+      action: `Delete chat list "${list.name}" (${countNoun(count)})`,
+      detail: "The list's name and membership are gone for good; the conversations themselves are not affected.",
+      yes: opts.yes,
+      commandExample: `amiko chat lists delete ${JSON.stringify(target)}`
+    });
+    let data;
+    try {
+      data = await amikoWebFetch(auth, `/api/chat-lists/${encodeURIComponent(list.id)}`, { method: "DELETE", timeoutMs: 20000 });
+    } catch (e5) {
+      exitWithError2(e5, "Failed to delete the chat list");
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(success(`Chat list deleted: ${list.name}`));
+  });
+}
+
 // src/commands/chat.ts
 var PIN_LIMIT = 20;
 function pinErrorMessage(e5, fallback2) {
@@ -27797,93 +28174,6 @@ async function findOrCreateDm(auth, userId) {
     throw new Error("Could not open a conversation with that user.");
   return id;
 }
-async function fetchUserById(auth, id) {
-  try {
-    const prof = await amikoWebFetch(auth, `/api/users/${encodeURIComponent(id)}`, { timeoutMs: 15000 });
-    return prof.user?.id ? { ...prof.user, id: prof.user.id } : null;
-  } catch (e5) {
-    if (e5.status === 404)
-      return null;
-    throw e5;
-  }
-}
-async function findDmByUserId(auth, userId) {
-  const want = normalizeUserId(userId);
-  const limit = 100;
-  for (let offset = 0;offset < 1e4; offset += limit) {
-    const data = await amikoWebFetch(auth, "/api/conversations", {
-      query: { limit, offset },
-      timeoutMs: 20000
-    });
-    const page = data.conversations ?? [];
-    const dm = page.find((c) => c.conversation_type === "direct" && (c.participants ?? []).some((p) => p.participant_type === "user" && normalizeUserId(p.participant_id) === want));
-    if (dm)
-      return dm.id;
-    if (page.length < limit || data.pagination?.has_more === false)
-      return null;
-  }
-  return null;
-}
-function personLabel(u) {
-  const name = u.name ?? u.id;
-  return u.handle ? `${name} (@${u.handle})` : name;
-}
-async function resolveConversation(auth, target) {
-  const t = target.trim();
-  if (!t) {
-    throw new Error("No target given. Pass a conversation id, a user id, an @handle, or a name.");
-  }
-  const person = (u) => ({
-    kind: "user",
-    userId: u.id,
-    label: `DM with ${personLabel(u)}`
-  });
-  if (t.startsWith("@")) {
-    const handle = t.slice(1);
-    const prof = await amikoWebFetch(auth, `/api/users/${encodeURIComponent(handle)}`, {
-      timeoutMs: 15000
-    });
-    if (!prof.user?.id)
-      throw new Error(`No user @${handle}.`);
-    return person({ ...prof.user, id: prof.user.id });
-  }
-  const idish = normalizeUserId(t);
-  if (looksLikeConversationId(idish)) {
-    if (idish === t) {
-      try {
-        const conv = await fetchConversationById(auth, t);
-        return {
-          kind: "conversation",
-          id: conv.id,
-          label: conv.conversation_type === "direct" ? `DM with ${convLabel(conv, auth.userId)}` : `group "${convLabel(conv, auth.userId)}"`,
-          conversation: conv
-        };
-      } catch (e5) {
-        const status = e5.status;
-        if (status === 403) {
-          throw new Error(`Conversation ${t} exists but you are not a participant.`);
-        }
-        if (status !== 404)
-          throw e5;
-      }
-    }
-    const user = await fetchUserById(auth, idish);
-    if (!user) {
-      throw new Error(`"${t}" is neither a conversation nor a user id — check \`amiko chat list\` or \`amiko friends list --json\`.`);
-    }
-    return person(user);
-  }
-  const groupId = await findGroupIdByExactTitle(auth, t);
-  if (groupId)
-    return { kind: "conversation", id: groupId, label: `group "${t}"` };
-  const { resolved, failures } = await resolveMembers(auth, [t]);
-  if (failures.length || resolved.length !== 1) {
-    const reason = failures[0]?.reason ?? "could not be resolved";
-    throw new Error(`"${t}" ${reason}`);
-  }
-  const p = resolved[0];
-  return person({ id: p.userId, name: p.name, handle: p.handle });
-}
 var HTTPS_RE = /^https:\/\//i;
 var URL_SHAPED_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
 var CHAT_IMAGE_MIME = new Set([
@@ -27932,7 +28222,7 @@ async function uploadChatVoice(auth, convId, path2) {
   await amikoWebFetch(auth, `/api/conversations/${encodeURIComponent(convId)}/audio/upload`, { method: "POST", multipart: form, timeoutMs: 120000 });
 }
 function registerChatCommand(chat) {
-  chat.command("list").description("List your conversations (DMs and group chats)").option("--limit <n>", "Max conversations", "30").option("--archived", "Include archived conversations").option("--raw", "Output raw JSON").action(async (opts) => {
+  chat.command("list").description("List your conversations (DMs and group chats)").option("--limit <n>", "Max conversations", "30").option("--archived", "Include archived conversations").option("--mentions", "Only conversations with an unread @mention of you, a permitted @all, or a reply to one of your messages").option("--raw", "Output raw JSON").action(async (opts) => {
     const auth = authOrExit();
     let data;
     try {
@@ -27947,20 +28237,21 @@ function registerChatCommand(chat) {
       console.error(error(e5 instanceof Error ? e5.message : "Failed to list conversations"));
       process.exit(1);
     }
+    const mentionsMe = (c) => !!c.unread_count && !!c.has_unread_mention;
+    const convs = opts.mentions ? (data.conversations ?? []).filter(mentionsMe) : data.conversations ?? [];
     if (opts.raw) {
-      console.log(JSON.stringify(data, null, 2));
+      console.log(JSON.stringify(opts.mentions ? { ...data, conversations: convs } : data, null, 2));
       return;
     }
-    const convs = data.conversations ?? [];
     if (convs.length === 0) {
-      console.log(dim("No conversations."));
+      console.log(dim(opts.mentions ? "No conversations with unread mentions or replies to you." : "No conversations."));
       return;
     }
     console.log(heading(`Conversations (${convs.length})
 `));
     for (const c of convs) {
       const kind = c.conversation_type === "direct" ? "DM" : c.conversation_type;
-      const unread = c.unread_count ? `  (${c.unread_count} unread)` : "";
+      const unread = c.unread_count ? `  (${c.unread_count} unread${mentionsMe(c) ? ", @you" : ""})` : "";
       console.log(label(`[${kind}] ${convLabel(c, auth.userId)}`, dim(c.id)));
       if (c.last_message?.content) {
         const who = c.last_message.name ? `${c.last_message.name}: ` : "";
@@ -28475,6 +28766,8 @@ function registerChatCommand(chat) {
   registerChatGifsCommand(chat);
   const group = chat.command("group").description("Group chats — create, list, info, rename, add/remove members, @all permission, leave");
   registerChatGroupCommand(group);
+  const lists = chat.command("lists").description("Your chat lists (private folders of conversations) — run bare to see them; create, rename, add/remove conversations, delete");
+  registerChatListsCommand(lists);
 }
 
 // src/commands/card.ts
@@ -30156,6 +30449,196 @@ async function mppFriendReportGenerate(auth, body, opts = {}) {
   }
 }
 
+// src/lib/nickname.ts
+var NICKNAME_MAX_CODE_POINTS = 50;
+var CONTROL_CHARS = /\p{Cc}/u;
+function validateNickname(input) {
+  if (CONTROL_CHARS.test(input)) {
+    return {
+      ok: false,
+      error: "invalid_characters",
+      message: "Nickname contains unsupported characters (control characters are not allowed)."
+    };
+  }
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return { ok: false, error: "empty", message: "Nickname is empty." };
+  }
+  if ([...trimmed].length > NICKNAME_MAX_CODE_POINTS) {
+    return {
+      ok: false,
+      error: "too_long",
+      message: `Nickname is too long (max ${NICKNAME_MAX_CODE_POINTS} characters).`
+    };
+  }
+  return { ok: true, value: trimmed };
+}
+
+// src/commands/friends-nickname.ts
+function exitWithError3(e5, fallback2) {
+  console.error(error(e5 instanceof Error ? e5.message : fallback2));
+  process.exit(1);
+}
+function friendLabel(f) {
+  const name = f.friend.name ?? f.friend.id;
+  return f.friend.handle ? `${name} (@${f.friend.handle})` : name;
+}
+async function fetchUserFriends(auth) {
+  const limit = 100;
+  const all = [];
+  for (let offset = 0;offset < 1e4; offset += limit) {
+    const data = await amikoWebFetch(auth, "/api/friends", {
+      query: { type: "user", limit, offset },
+      timeoutMs: 20000
+    });
+    const page = data.friends ?? [];
+    all.push(...page);
+    if (page.length < limit || data.pagination?.has_more === false)
+      break;
+  }
+  return all;
+}
+async function resolveFriend(auth, target) {
+  const t = target.trim();
+  if (!t) {
+    throw new Error("No friend given. Pass a name, @handle, user id, or friendship id.");
+  }
+  const all = await fetchUserFriends(auth);
+  const asId = normalizeUserId(t);
+  const byId = all.find((f) => f.friendship_id === asId || f.friend.id === asId);
+  if (byId)
+    return byId;
+  if (t.startsWith("@")) {
+    const handle = t.slice(1).toLowerCase();
+    const byHandle = all.filter((f) => f.friend.handle?.toLowerCase() === handle);
+    if (byHandle.length === 1)
+      return byHandle[0];
+    throw new Error(`No friend ${t}. Nicknames only work for accepted friends — run \`amiko friends list\`.`);
+  }
+  const lower = t.toLowerCase();
+  const exact = all.filter((f) => f.friend.name?.toLowerCase() === lower || f.friend.handle?.toLowerCase() === lower || f.nickname?.toLowerCase() === lower);
+  const matches = exact.length ? exact : all.filter((f) => f.friend.name?.toLowerCase().includes(lower) || f.friend.handle?.toLowerCase().includes(lower) || f.nickname?.toLowerCase().includes(lower));
+  if (matches.length === 0) {
+    throw new Error(`No friend matching "${t}". Nicknames only work for accepted friends — run \`amiko friends list\`.`);
+  }
+  if (matches.length > 1) {
+    const names = matches.map((f) => `${friendLabel(f)} (${f.friend.id})`).join(", ");
+    throw new Error(`"${t}" is ambiguous — matches: ${names}. Use the friend's @handle or user id.`);
+  }
+  return matches[0];
+}
+async function resolveFriendOrExit(auth, target) {
+  try {
+    return await resolveFriend(auth, target);
+  } catch (e5) {
+    exitWithError3(e5, "Could not resolve the friend");
+  }
+}
+async function patchNickname(auth, friendshipId, nickname, spinner) {
+  try {
+    const data = await amikoWebFetch(auth, `/api/friends/${encodeURIComponent(friendshipId)}/nickname`, { method: "PATCH", body: { nickname }, timeoutMs: 20000 });
+    spinner?.stop();
+    return data;
+  } catch (e5) {
+    spinner?.stop();
+    if (e5.status === 403) {
+      console.error(error(e5 instanceof Error ? e5.message : "Forbidden"));
+      console.error(dim("Tip: nickname writes need an amiko-web deploy that allows twin tokens to manage nicknames (feat/friend-nicknames)."));
+      process.exit(1);
+    }
+    exitWithError3(e5, "Failed to update the nickname");
+  }
+}
+async function runList(opts) {
+  const auth = authOrExit();
+  const spinner = opts.json ? null : ora("Loading nicknames...").start();
+  let all;
+  try {
+    all = await fetchUserFriends(auth);
+  } catch (e5) {
+    spinner?.stop();
+    exitWithError3(e5, "Failed to load friends");
+  }
+  spinner?.stop();
+  const named = all.filter((f) => !!f.nickname);
+  renderOutput({
+    nicknames: named.map((f) => ({
+      nickname: f.nickname ?? null,
+      user_id: f.friend.id,
+      name: f.friend.name ?? null,
+      handle: f.friend.handle ?? null,
+      friendship_id: f.friendship_id
+    }))
+  }, () => {
+    if (named.length === 0) {
+      console.log(dim("No nicknames set."));
+      console.log(dim('Set one with `amiko friends nickname set <friend> "<nickname>"`.'));
+      return;
+    }
+    console.log(heading(`Nicknames (${named.length})`));
+    const rows = [
+      [
+        dim("NICKNAME"),
+        dim("NAME"),
+        dim("HANDLE"),
+        dim("USER ID"),
+        dim("FRIENDSHIP")
+      ],
+      ...named.map((f) => [
+        f.nickname ?? "-",
+        f.friend.name ?? "-",
+        f.friend.handle ?? "-",
+        f.friend.id,
+        f.friendship_id
+      ])
+    ];
+    console.log(table(rows));
+  }, { json: opts.json });
+}
+function registerFriendsNicknameCommand(nickname) {
+  nickname.option("--json", "Output as JSON").action(runList);
+  nickname.command("list").description("List every nickname you've set").option("--json", "Output as JSON").action((_opts, cmd) => runList(cmd.optsWithGlobals()));
+  nickname.command("set <friend> <nickname>").description("Set or change your private nickname for a friend (name, @handle, user id, or friendship id)").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--json", "Output as JSON").action(async (target, rawNickname, _opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const checked = validateNickname(rawNickname);
+    if (!checked.ok) {
+      console.error(error(checked.message));
+      if (checked.error === "empty") {
+        console.error(dim(`Tip: to clear a nickname, run \`amiko friends nickname remove ${JSON.stringify(target)}\`.`));
+      }
+      process.exit(1);
+    }
+    const auth = authOrExit();
+    const friend = await resolveFriendOrExit(auth, target);
+    await confirmDestructive({
+      action: friend.nickname ? `Change your private nickname for ${friendLabel(friend)} from "${friend.nickname}" to "${checked.value}"` : `Set your private nickname for ${friendLabel(friend)} to "${checked.value}"`,
+      detail: "Nicknames are private — only you ever see them, in every Amiko app.",
+      yes: opts.yes,
+      commandExample: `amiko friends nickname set ${JSON.stringify(target)} ${JSON.stringify(checked.value)}`
+    });
+    const spinner = opts.json ? null : ora("Saving nickname...").start();
+    const data = await patchNickname(auth, friend.friendship_id, checked.value, spinner);
+    renderOutput(data, (d) => console.log(success(`${friendLabel(friend)} is now "${d.nickname}" to you`)), { json: opts.json });
+  });
+  nickname.command("remove <friend>").description("Remove your private nickname for a friend").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--json", "Output as JSON").action(async (target, _opts, cmd) => {
+    const opts = cmd.optsWithGlobals();
+    const auth = authOrExit();
+    const friend = await resolveFriendOrExit(auth, target);
+    if (!friend.nickname) {
+      renderOutput({ nickname: null }, () => console.log(dim(`No nickname set for ${friendLabel(friend)}.`)), { json: opts.json });
+      return;
+    }
+    await confirmDestructive({
+      action: `Remove your private nickname "${friend.nickname}" for ${friendLabel(friend)}`,
+      yes: opts.yes,
+      commandExample: `amiko friends nickname remove ${JSON.stringify(target)}`
+    });
+    const spinner = opts.json ? null : ora("Removing nickname...").start();
+    const data = await patchNickname(auth, friend.friendship_id, null, spinner);
+    renderOutput(data, () => console.log(success(`Nickname removed — ${friendLabel(friend)} shows their real name again`)), { json: opts.json });
+  });
+}
+
 // src/commands/friends.ts
 async function runPaidRegenerate(args) {
   let auth;
@@ -30284,6 +30767,7 @@ function registerFriendsCommand(program2) {
           [
             dim("USER ID"),
             dim("NAME"),
+            dim("NICKNAME"),
             dim("HANDLE"),
             dim("TYPE"),
             dim("FRIENDSHIP"),
@@ -30292,6 +30776,7 @@ function registerFriendsCommand(program2) {
           ...items.map((f) => [
             f.friend.id,
             f.friend.name ?? "-",
+            f.nickname ?? "-",
             f.friend.handle ?? "-",
             f.friend.type,
             f.friendship_id,
@@ -30396,6 +30881,8 @@ Accept with: amiko friends accept <friendshipId>`));
       process.exit(1);
     }
   });
+  const nickname = program2.command("nickname").description("Private nicknames for friends — set, remove, list (only you ever see them)");
+  registerFriendsNicknameCommand(nickname);
   const reports = program2.command("reports").description("Friend matching reports");
   reports.command("list").description("List friend matching reports").option("--page <n>", "Page number", "1").option("--limit <n>", "Page size (1-50)", "20").option("--json", "Output as JSON").action(async (opts) => {
     const auth = resolveAuth();
@@ -31739,7 +32226,7 @@ var twin = program2.command("twin").description("Update twin identity (name, des
 var drive = program2.command("drive").alias("docs").description("Manage twin drive — upload/download/search files, organise into folders");
 var voice = program2.command("voice").description("Manage twin voice — design, create, clone, reset");
 var avatar = program2.command("avatar").description("Manage twin avatar image");
-var friends = program2.command("friends").description("Manage friendships — list, requests, add, accept, remove, reports, matches");
+var friends = program2.command("friends").description("Manage friendships — list, requests, add, accept, remove, nicknames, reports, matches");
 var users = program2.command("users").description("Search users and view public profiles");
 var post = program2.command("post").description("Create posts and comments on the feed");
 var review = program2.command("review").description("Review queue — list, approve, or reject twin-drafted comments");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.14.0-beta.22",
+  "version": "0.14.0-beta.24",
   "description": "Amiko CLI — swap tokens, manage credits, bridge cross-chain, and call marketplace agents",
   "type": "module",
   "bin": {

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: amiko-cli
-description: The Amiko CLI lets an agent act on the Amiko platform end-to-end — read platform notifications (friend requests, mentions, system alerts), search and write **cross-agent memories** about the owner (what other agents already know — preferences, decisions, facts), manage Solana/Base wallets (create, swap via Jupiter, bridge USDC via Across, transfer tokens to external addresses), top up and spend credits, generate media — images, video, speech, music, and SFX — via Create Studio (`amiko create`, async and charged on success), call paid MPP marketplace services (X/Twitter search, Amazon product search, TTS/STT, AI chat), manage the twin's identity and drive (files, folders, RAG), voice and avatar, and social graph (friends, posts, comments, feed). Auth is automatic when run from the agent's workspace folder; payments are platform-custodied (no keys on disk). The owner's DMs and group chats are `amiko chat` (list / read / send / mark everything read / create + manage group chats AS the owner, including sending GIFs (`chat gifs` search + `chat send --gif`), sharing a group's invite/join link + QR and @all group announcements, 人对人); the agent's OWN sessions are the openhermit gateway's session_list / session_send (AS the agent) — different identities, different surfaces. Use this skill whenever the user asks about their Amiko notifications, chats/DMs, drive, memory, social graph, wallets, credits, or marketplace services — anything that would show up in their Amiko account or cost AMIKO/credits.
+description: The Amiko CLI lets an agent act on the Amiko platform end-to-end — read platform notifications (friend requests, mentions, system alerts), search and write **cross-agent memories** about the owner (what other agents already know — preferences, decisions, facts), manage Solana/Base wallets (create, swap via Jupiter, bridge USDC via Across, transfer tokens to external addresses), top up and spend credits, generate media — images, video, speech, music, and SFX — via Create Studio (`amiko create`, async and charged on success), call paid MPP marketplace services (X/Twitter search, Amazon product search, TTS/STT, AI chat), manage the twin's identity and drive (files, folders, RAG), voice and avatar, and social graph (friends, private friend nicknames, posts, comments, feed). Auth is automatic when run from the agent's workspace folder; payments are platform-custodied (no keys on disk). The owner's DMs and group chats are `amiko chat` (list / read / send / mark everything read / see which chats have unread @mentions or replies to the owner (`chat list --mentions`) / organize chats into private folders (`chat lists`) / create + manage group chats AS the owner, including sending GIFs (`chat gifs` search + `chat send --gif`), sharing a group's invite/join link + QR and @all group announcements, 人对人); the agent's OWN sessions are the openhermit gateway's session_list / session_send (AS the agent) — different identities, different surfaces. Use this skill whenever the user asks about their Amiko notifications, chats/DMs, drive, memory, social graph, wallets, credits, or marketplace services — anything that would show up in their Amiko account or cost AMIKO/credits.
 homepage: https://platform.heyamiko.com
 metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
 ---
@@ -41,6 +41,11 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
 | "pin that hackathon message in the builders group" | shell → `amiko chat read "<group>"` (find the message, copy its `id`) → `amiko chat pin <messageId> --yes` |
 | "what's pinned in the team chat?" | shell → `amiko chat pinned "<group>"` |
 | "mark all my chats as read" | shell → `amiko chat mark-read --all --yes` (after the owner confirms — it clears every badge and senders see read ticks) |
+| "any unread mentions or replies to me?" | shell → `amiko chat list --mentions` (chats whose unread messages @mention the owner or reply to them) |
+| "what chat lists do I have? what's in my Work list?" | shell → `amiko chat lists` |
+| "call Sophie 'Soph' from now on" | shell → `amiko friends nickname set Sophie "Soph" --yes` (after the owner confirms) |
+| "what nicknames have I given my friends?" | shell → `amiko friends nickname` |
+| "add the team group to my Work list" | shell → `amiko chat lists add "Work" --conversation "<group>" --yes` |
 | "what can amiko do?" | shell → `amiko --help` |
 | "what's my MiniMax / ElevenLabs voice id?" | shell → `amiko info` |
 | "speak with my cloned MiniMax voice" | shell → `amiko info`, quote the cost, obtain explicit approval, then run `amiko create tts "…" --provider minimax --voice <minimax_voice_id> --yes` |
@@ -60,7 +65,7 @@ Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `
 
 ## Critical Rules
 
-1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `markets *`, `create *`, `card mint`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.** The same `--yes` gate also covers **free outward social actions** — `chat send`, `chat pin` (the whole chat sees a pinned-message announcement), `chat group create`, `chat group add` (real people see them, so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat unpin` (removes the pin for everyone), `chat mark-read --all` (irreversibly marks every conversation read — senders see read ticks), `chat group remove/leave/rename/promote/mention-all`, `twin update --public`, `drive delete`, `drive share` / `drive folder share` (exposes the file — or the folder's ENTIRE subtree — to anyone with the link), `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`. **For these free actions never mention cost, never say "the cost is 0", and never call it a paid operation** — ask for plain confirmation of the action itself (e.g. "Send "hi" to Mars — go ahead?").
+1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `markets *`, `create *`, `card mint`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.** The same `--yes` gate also covers **free outward social actions** — `chat send`, `chat pin` (the whole chat sees a pinned-message announcement), `chat group create`, `chat group add` (real people see them, so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat unpin` (removes the pin for everyone), `chat mark-read --all` (irreversibly marks every conversation read — senders see read ticks), `chat group remove/leave/rename/promote/mention-all`, `chat lists create/rename/add/remove/delete` (private to the owner, but they reshape the owner's chat UI), `friends nickname set/remove` (private to the owner, but it changes how that friend is displayed everywhere in the owner's apps), `twin update --public`, `drive delete`, `drive share` / `drive folder share` (exposes the file — or the folder's ENTIRE subtree — to anyone with the link), `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`. **For these free actions never mention cost, never say "the cost is 0", and never call it a paid operation** — ask for plain confirmation of the action itself (e.g. "Send "hi" to Mars — go ahead?").
 2. **After every paid command, report the remaining balance.** The CLI prints a `Balance: N credits` line — include that figure in your reply.
 3. **Never retry a failed command.** Report and stop. Every paid call costs tokens even on failure.
 4. **Auth is automatic.** Never suggest `amiko login` / `amiko connect`. Run from the agent's workspace folder; if anything looks off, `amiko accounts` shows the resolved `userId` / `twinId`.
@@ -149,7 +154,7 @@ MiniMax Hailuo is silent — there is no CLI mux step to attach a separate music
 
 `amiko chat` is the **owner's** conversations, acting **as the owner** (人对人) — NOT the agent's own sessions (those are the gateway's `session_*`, as the agent).
 
-- `amiko chat list` — all conversations, **DMs and group chats** (id, type, peer/title, last message, unread).
+- `amiko chat list` — all conversations, **DMs and group chats** (id, type, peer/title, last message, unread). Rows with unread messages that concern the owner directly show an **`@you` marker**, and `--mentions` filters to just those. `@you` / `--mentions` means the unread messages include a **direct @mention of the owner, a permitted @all in a group, or a reply to one of the owner's messages** — so "did anyone reply to me?" is also answered here, not just literal mentions. No `@you` rows under `--mentions` = nothing unread needs the owner's attention specifically. (On servers that predate the flag it reads as false for every conversation: unread counts still show, `@you` never does, and `--mentions` matches nothing — an empty result there is NOT proof nobody mentioned or replied.)
 - `amiko chat read <target>` — recent messages. `<target>` = a conversation id (from `list`), a **user id**, an `@handle`, or a name. Reading never creates a conversation — if there's no DM with that person yet, it says so.
 - `amiko chat send <target> "message"` — send **as the owner**. Delivered in real time. `--yes` required in non-interactive shells (it's an outward message to a real person). `<target>` = a conversation id, a **user id**, an `@handle`, or a name. A user id / @handle / unambiguous name opens (or reuses) the DM for you — but only **after** the owner approves the send (via the confirmation, or `--yes` in your shell); nothing is created if approval is refused. **The owner never needs to start the conversation first, and there is no platform authorization step for starting a DM.** For **group chats**, use the conversation id from `list`. **@all in groups:** add `--all` (or write a standalone `@all` word in the message) to notify **every member** — allowed for group admins/owners, or for everyone once an admin enables it (`amiko chat group mention-all <group> on`). The CLI pre-checks permission: `--all` without it fails and names the fix; a plain `@all` word still sends, as ordinary text, with a note. It pings the whole group — use it only when the owner clearly wants everyone notified.
 - **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL — e.g. a generated image), `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note), and `--gif <queryOrUrl>` (see GIFs below). One media block per message (image XOR audio XOR gif). **General video files are not supported** on chat yet. To share a generated asset, pass its URL from `amiko create status` (no re-upload). A local audio file is sent as a voice note with the text as a separate message.
@@ -173,7 +178,14 @@ Create and manage the owner's group chats: `create <name> --member <who>…`, `l
 - `amiko chat group mention-all <group> <on|off>` — allow **everyone** in the group to use @all (`on`) or restrict it to admins (`off`, the default). **Admins only**, server-enforced — a 403 means the owner isn't an admin; report it, don't retry. The current setting shows in `amiko chat group info` (`@all mentions: everyone | admins only`).
 - Gating: `create`/`add` message real people and `remove`/`leave`/`rename`/`promote`/`mention-all` are destructive — all require `--yes` in your shell (see Critical Rules). Reads (`list`, `info`, `invite`) are free and ungated.
 
-## Card — behavior notes
+### Chat lists — `amiko chat lists`
+
+The owner's **chat lists**: private folders of conversations (the sidebar folders in the Amiko apps). **Only the owner ever sees them** — putting a chat in a list notifies nobody and changes nothing about the conversation itself.
+
+- `amiko chat lists` (bare) — every list with its conversations, names resolved. Ungated read; `--raw` for JSON.
+- `amiko chat lists create <name> [--conversation <who>…]`, `rename <list> <newName>`, `add <list> --conversation <who>…`, `remove <list> --conversation <who>…`, `delete <list>` — all mutations are `--yes`-gated. They're private, so confirm the action itself; never mention cost or "other people will see this." Every mutation also accepts `--raw` to print the server's JSON response instead of the summary line.
+- `<list>` is a list id or name (case-insensitive, exact wins before substring; ambiguity errors listing candidates). `--conversation` repeats and takes a conversation id, user id, `@handle`, group title, or name — the same targets as `chat send`, except a person must **already have a DM** with the owner (organizing lists never creates conversations; the CLI errors if no DM exists yet).
+- `add`/`remove` only change list membership. `delete` removes the list itself; the conversations in it are untouched — say so if the owner hesitates.
 
 `amiko card` = the owner's **Twin Card** (shareable card, template `twins_take`, flavors **work / play / love** — DB-managed, discover with `card templates`).
 
@@ -190,6 +202,15 @@ The drive is **shared between the user and the agent** — anything either side
 
 ## Friends & relationships
 
+### Private nicknames — `amiko friends nickname`
+
+The owner's private pet names for friends. **Only the owner ever sees a nickname** — it becomes that friend's display name across the owner's feed, chats, and profile views; the friend is never notified and never sees it. Nicknames exist only for **accepted, person-to-person** friends (not twins, not pending requests).
+
+- `amiko friends nickname` (or `... nickname list`) — every nickname the owner has set. Ungated read; `--json` for ids.
+- `amiko friends nickname set <friend> "<nickname>"` — set or change (max 50 characters). `<friend>` takes a name, `@handle`, user id, or friendship id — and also matches the **current nickname** ("rename Soph to Sophy" works). Ambiguity errors listing candidates; ask the owner, don't guess.
+- `amiko friends nickname remove <friend>` — clear it (the friend's real name shows again). Removing when none is set is a harmless no-op.
+- `set`/`remove` are `--yes`-gated. They're private — confirm the action itself; never mention cost or "other people will see this."
+
 ### "How is my relationship with X?" playbook
 
 1. **Resolve to a user id**: `amiko friends list --json` first; if not a friend, `amiko users search "<name>" --json`. If ambiguous, ask.
@@ -227,7 +248,7 @@ Workflow: start with `friends matches --limit 20 --json`; narrow with `--dimensi
 >
 > **Owner DMs / group chats: `amiko chat`.** For "did X message me?" / "what did Sophie and I say?" / "message Y for me", use `amiko chat list` / `amiko chat read <who>` / `amiko chat send <who> "…"` — these act **as the owner** (人对人). The gateway's `session_*` tools are the **agent's own** sessions (as the agent), a separate surface (see Chat behavior notes).
 
-Platform notifications cover friend requests, mentions, system alerts, and post-related events.
+Platform notifications cover friend requests, mentions, system alerts, and post-related events. For "**was I mentioned / did anyone reply to me** in chat?" specifically, prefer `amiko chat list --mentions` — it covers replies to the owner's messages (which notification rows don't) and reflects what's still unread.
 
 ## Where to run