@heyamiko/amiko-cli 0.14.0-beta.21 → 0.14.0-beta.23

package/README.md

@@ -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
@@ -266,16 +267,19 @@ amiko chat receipts <messageId>                  # who read your message + when
 amiko chat pin <messageId> --yes                 # pin for everyone (id from `chat read`; groups: admins only)
 amiko chat unpin <messageId> --yes               # remove a pin for everyone
 amiko chat pinned "Trip planning"                # list a conversation's pinned messages, oldest first
+amiko chat mark-read --all --yes                 # mark EVERY conversation as read (clears all unread badges)
 ```
 
 - **`<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`.
 - `chat send` messages a real person, so it's **gated on `--yes`** in non-interactive shells. Delivery is real-time. `--raw` prints raw JSON on any subcommand.
 - **`chat receipts <messageId>`** shows read receipts for **your own** messages (server-enforced; 403 otherwise): sent time, who read it with each person's first-read time, and who it was delivered to but hasn't read. Reads from before receipts tracking show as "exact time unknown". Read-only, ungated.
 - **Pinned messages**: `chat pin <messageId>` pins for the **whole conversation** (the chat sees an "X pinned a message" announcement) and `chat unpin <messageId>` removes it for everyone — both gated on `--yes`. In **groups** only admins can pin/unpin (403 otherwise); in DMs either side can. Max 20 pins per conversation. `chat pinned <target>` (same targets as `read`; never creates a DM) lists them oldest-first with each message's id and pinner — read-only, ungated.
+- **Mark all read**: `chat mark-read --all` marks every conversation as read in one call — unread badges clear on all your devices, your chat/mention notifications clear, and senders see read ticks on their messages. Irreversible (there is no "mark unread"), so it's gated on `--yes` in non-interactive shells. `--all` is required (mirrors `notifications read --all`); `--raw` prints the server payload.
 
 ### Group chats
 
@@ -299,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**).
@@ -601,6 +622,15 @@ npm publish
 
 ## Changelog
 
+### 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`).
+
 ### 0.14.0-beta.21
 
 - **Chat GIFs: `amiko chat gifs [query]` + `amiko chat send --gif <queryOrUrl>`.** `chat gifs` browses Klipy GIFs via the platform proxy (`GET /api/gifs`; trending with no query, `--page`/`--limit`/`--raw`, "Powered by KLIPY") — read-only and ungated. `chat send --gif` attaches a GIF to a message: search words send the top result, a Klipy URL (from `chat gifs`) attaches exactly, and non-Klipy URLs are refused. Sends use the cross-client GIF contract — Klipy mp4/webm → `message_type: "video"` + `metadata.videos`, `.gif` → `"image"` + `metadata.images`, each record `{url, name, contentType, kind: "gif", width?, height?}` — so web/desktop/mobile render a looping watermarked GIF. The `<message>` positional is now optional when `--gif` is present (`content` falls back to `"GIF"`); captions ride as `metadata.image_caption`, which the `--image` path now also sets so image captions actually display in bubbles. One media block per message (`--image`/`--audio`/`--gif` are mutually exclusive). Requires the companion amiko-web `feat/chat-gif-picker` deploy (`GET /api/gifs`) — the twin token already authenticates against it, so no other backend work is needed.

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}: ` : "";
@@ -28438,9 +28729,45 @@ function registerChatCommand(chat) {
       }
     }
   });
+  chat.command("mark-read").description("Mark ALL conversations as read (requires --all). Clears every unread badge on the owner's devices; senders see read ticks.").option("--all", "Mark every conversation as read").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (opts) => {
+    if (!opts.all) {
+      console.error(error("Pass --all to mark every conversation as read"));
+      process.exit(1);
+    }
+    const auth = authOrExit();
+    await confirmDestructive({
+      action: "Mark ALL of the owner's conversations as read",
+      detail: "Clears every unread badge on web and mobile; senders see read ticks on their messages. This cannot be undone.",
+      yes: opts.yes,
+      commandExample: "amiko chat mark-read --all"
+    });
+    let data;
+    try {
+      data = await amikoWebFetch(auth, "/api/conversations/read-all", {
+        method: "POST",
+        timeoutMs: 20000
+      });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Failed to mark all as read"));
+      process.exit(1);
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(success("All conversations marked as read."));
+    const cleared = data.cleared_notifications;
+    if (typeof cleared === "number" && cleared > 0) {
+      console.log(dim(`  ${cleared} chat notification${cleared === 1 ? "" : "s"} cleared`));
+    } else if ((data.unread_conversation_ids ?? []).length === 0) {
+      console.log(dim("  Nothing was unread."));
+    }
+  });
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.14.0-beta.21",
+  "version": "0.14.0-beta.23",
   "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 / 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, 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"]}}}
 ---
@@ -40,6 +40,10 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
 | "did Sophie read my message about the demo?" | shell → `amiko chat read "Sophie"` (find the owner's message, copy its `id`) → `amiko chat receipts <messageId>` |
 | "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` |
+| "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` |
@@ -59,7 +63,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 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), `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`.
@@ -148,7 +152,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.
@@ -157,6 +161,7 @@ MiniMax Hailuo is silent — there is no CLI mux step to attach a separate music
 - **Reactions** — `amiko chat react <messageId> <emoji>`, `amiko chat unreact <messageId>`, `amiko chat reactions <messageId>`. The owner **won't give you a message id** — they'll say something like *"react to the latest Ava message about the team with a heart"*. Get ids from `amiko chat read <target>`: it prints each message's `id` and any existing reactions — match the message by its **content**, then act on that id. `react` adds (or replaces) your reaction — **one per message**, a new emoji replaces the previous one, and re-reacting the same emoji is a no-op (use `unreact` to remove). Pass the **actual emoji character** (`❤️`, `👍`, `😂`). `react`/`unreact` are outward (other people see them), so `--yes` is required in non-interactive shells and the confirmation shows a preview of the target message; `reactions` (read) is ungated. These act **as the owner** (人对人), just like `chat send` — not the twin's own `session_*`.
 - **Read receipts** — `amiko chat receipts <messageId>` shows when the message was sent, who has read it (with each person's first-read time), and who it was delivered to but hasn't read yet. **Only works for messages the owner sent** (server-enforced) — a 403 means it wasn't the owner's message; report that, don't retry. Get the id from `amiko chat read <target>`, matching the message by its **content**. Read-only and ungated, like `reactions`. Rows marked "exact time unknown" were read before receipts tracking existed — never invent a time for them.
 - **Pinned messages** — `amiko chat pin <messageId>`, `amiko chat unpin <messageId>`, `amiko chat pinned <target>`. Pins are **conversation-wide**: everyone sees them, and `pin` posts an "X pinned a message" announcement to the whole chat, so both `pin` and `unpin` are `--yes`-gated with a preview of the target message. The owner won't give you a message id — get it from `amiko chat read <target>` (or `amiko chat pinned <target>` when unpinning), matching by **content**. In **groups** only admins can pin/unpin (a 403 names that rule; check roles with `amiko chat group info`, report it, don't retry); in DMs either side can. Max 20 pins per conversation — a "Pin limit reached" error means unpin one first, ask the owner which. Re-pinning an already-pinned message is a harmless no-op. `pinned <target>` is an ungated read (same targets as `chat read`: conversation id, user id, `@handle`, or name; it never creates a DM) listing pins oldest-first with each message's `id` and who pinned it.
+- **Mark all read** — `amiko chat mark-read --all` marks EVERY conversation read as the owner in one shot: unread badges clear on all the owner's devices, the owner's chat/mention notifications clear, and senders see read ticks on their messages (the ~50 most recent conversations flip live; the rest on their next refresh). Irreversible — there is no "mark unread" — so it's `--yes`-gated: only run it when the owner explicitly asks to clear everything, never as routine tidying. The success line won't say how many conversations were affected (the server doesn't report a full count); don't invent a number.
 
 ### Group chats — `amiko chat group`
 
@@ -171,7 +176,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`).
 
@@ -225,7 +237,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