@heyamiko/amiko-cli 0.14.0-beta.5 → 0.14.0-beta.7

package/README.md

@@ -234,13 +234,15 @@ amiko chat list --limit 50 --archived            # include archived
 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
+amiko chat send <userId> "hey!" --yes            # user id works too — the DM is opened automatically
+amiko chat send Mars "hey!" --yes                # or a name (friends first, then people search)
 amiko chat send <groupConversationId> "hi all" --yes   # send to a group chat
 amiko chat send @sophie "look 👀" --image ./cat.png --yes         # attach a local image
 amiko chat send @sophie "made this 🎵" --audio <generated-url> --yes  # attach audio (e.g. from `amiko create`)
 ```
 
-- **`<target>`** for `read`/`send` is a **conversation id** (from `chat list` — use this for groups), an **`@handle`**, or a **name** (resolved via user search; if ambiguous, the CLI lists candidates instead of guessing).
-- A DM target that doesn't exist yet is **created automatically** (find-or-create).
+- **`<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.
 - **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL) and `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note). One media block per message (image *or* audio). **Video isn'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.)
 - `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.
 
@@ -560,6 +562,15 @@ npm publish
 
 ## Changelog
 
+### 0.14.0-beta.7
+
+- **`amiko chat group invite <group>` — share a group's invite/join link + QR.** New read-only subcommand that fetches `GET /api/conversations/{id}/invite` (twin token) and prints the join link plus a scannable QR image URL. Admins-only: SKILL.md instructs the agent to confirm the asker holds `admin`/`owner` (via `amiko chat group info`) before sharing, and the endpoint is admin-gated server-side (403 → admin tip). Fails loudly if the response is missing its link/QR instead of printing a placeholder. Requires the companion amiko-web change (adds `qrUrl` to the invite response + a public `GET /api/conversations/join/[token]/qr` PNG route).
+
+### 0.14.0-beta.6
+
+- **`amiko chat send`/`read` accept user ids — DMs no longer require an existing conversation.** Target resolution is rebuilt: a cuid target is verified as a conversation first and, on 404, retried as a user id (user ids and conversation ids are both cuids — previously a user id went straight to the messages route and died with "Conversation not found"). Plain names now resolve **friends-first** (then people search) via the shared `resolveMembers`, with ambiguity reported as a candidate list. Resolution is fully read-only: for `send`, a missing DM is found-or-created only **after** the `--yes`/approval gate (no more empty conversations from an unapproved send), and `read` never creates a DM at all — it errors if none exists. The confirmation summary now shows the **resolved** recipient (`Send to DM with Mars (@mars): …`) so a wrong-person resolution is visible before anything goes out. Unknown cuids are rejected before any conversation is created (the backend accepts dangling participant ids silently), and a 403 on a real conversation no longer falls through to DM creation.
+- **Free outward actions no longer talk about cost.** `requireApproval` gained a `free` mode used by `chat send` and `chat group create/add`: the non-interactive refusal now says the action is free and tells the agent to confirm the action itself — instead of the old "This command will cost no charge… quote the cost to the user", which made twins ask owners to "approve the paid operation, cost 0". SKILL.md's Critical Rule 1 spells out the anti-pattern, documents user-id DM targets ("the owner never needs to start the conversation first"), and drops the false "server enforces friend rules" claim that fed authorization hallucinations.
+
 ### 0.14.0-beta.5
 
 - **`amiko chat group` — group-chat management as the owner.** New subcommand group under `chat`: `create` (name + repeatable `--member`, one atomic POST), `list`, `info` (members + roles), `rename`, `add`, `remove`, `promote`, and `leave` (alias `delete`). Members resolve friends-first by name (then people search), all-or-nothing before any mutation; groups address by id or case-insensitive title. Uses the existing amiko-web conversation routes (twin token) — rename/add/remove-others/promote are admin-enforced server-side, and `leave|delete` is honest about the platform's semantics: it only hides the group for the caller, there is no delete-for-everyone. `create`/`add` gate on `requireApproval`, the destructive rest on `confirmDestructive` (both exit 2 without `--yes` in non-interactive shells). Plain-name `chat send`/`read` targets now prefer an exact, unambiguous group-title match over people search. Shared conversation types + resolution helpers extracted to `src/lib/conversations.ts`; `convLabel` self-filtering now strips the `did:privy:` prefix so DM labels no longer include the owner. SKILL.md gains a Group chats block + gating-list updates.

package/dist/index.js

@@ -24825,12 +24825,19 @@ async function confirmDestructive(args) {
   process.exit(2);
 }
 async function requireApproval(args) {
+  if (args.cost === undefined === (args.free === undefined)) {
+    throw new Error("requireApproval: set exactly one of `cost` or `free`.");
+  }
   if (args.yes)
     return;
   if (process.stdin.isTTY) {
     console.log("");
     console.log(`About to run: ${args.summary}`);
-    console.log(`Cost: ${args.cost}`);
+    if (args.cost !== undefined) {
+      console.log(`Cost: ${args.cost}`);
+    } else {
+      console.log(`Free — but this is a real outward action other people will see (${args.free}).`);
+    }
     const ok = await promptYesNo("Proceed? [y/N] ");
     if (!ok) {
       console.log(dim("Cancelled."));
@@ -24840,10 +24847,17 @@ async function requireApproval(args) {
   }
   console.error(error(`Refusing to run without --yes (non-interactive shell detected).`));
   console.error("");
-  console.error(`This command will cost ${args.cost}.`);
-  console.error(`Action: ${args.summary}`);
-  console.error("");
-  console.error(dim(`Quote the cost to the user, get their explicit approval, then re-run with --yes:`));
+  if (args.cost !== undefined) {
+    console.error(`This command will cost ${args.cost}.`);
+    console.error(`Action: ${args.summary}`);
+    console.error("");
+    console.error(dim(`Quote the cost to the user, get their explicit approval, then re-run with --yes:`));
+  } else {
+    console.error(`This action is FREE — do not quote a price or say "cost: 0". It is outward-facing: ${args.free}.`);
+    console.error(`Action: ${args.summary}`);
+    console.error("");
+    console.error(dim(`Ask the owner to confirm the action itself (what will be sent and who sees it), then re-run with --yes:`));
+  }
   console.error(dim(`  ${args.commandExample} --yes`));
   process.exit(2);
 }
@@ -27078,7 +27092,7 @@ function registerChatGroupCommand(group) {
     const auth = authOrExit();
     const members = await resolveMembersOrExit(auth, opts.member);
     await requireApproval({
-      cost: "no charge — creates a group chat with real people",
+      free: "creates a group chat that real people are added to",
       summary: `Create group "${name}" with ${members.map(memberLabel).join(", ")}`,
       yes: opts.yes,
       commandExample: `amiko chat group create ${JSON.stringify(name)} ${memberFlags(opts.member)}`
@@ -27172,6 +27186,31 @@ function registerChatGroupCommand(group) {
     ];
     console.log(table(rows));
   });
+  group.command("invite <group>").description("Show a group's invite/join link + QR image URL (admins only)").option("--raw", "Output raw JSON").action(async (target, opts) => {
+    const auth = authOrExit();
+    const conv = await resolveGroupOrExit(auth, target);
+    let data;
+    try {
+      data = await amikoWebFetch(auth, `/api/conversations/${encodeURIComponent(conv.id)}/invite`, { timeoutMs: 20000 });
+    } catch (e5) {
+      if (statusOf2(e5) === 403) {
+        console.error(error(`Can't view the invite link. ${ADMIN_TIP}`));
+        process.exit(1);
+      }
+      exitWithError(e5, "Failed to load invite link");
+    }
+    if (!data.url || !data.qrUrl) {
+      exitWithError(null, "The invite link response was missing its link or QR URL — nothing to share.");
+    }
+    if (opts.raw) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    console.log(heading(conv.title ?? "(untitled group)"));
+    console.log(label("Invite link", data.url));
+    console.log(label("QR image", data.qrUrl));
+    console.log(dim("Share with group admins only — anyone who opens it can join."));
+  });
   group.command("rename <group> <newTitle>").description("Rename a group (admins only)").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (target, newTitle, opts) => {
     const auth = authOrExit();
     const conv = await resolveGroupOrExit(auth, target);
@@ -27201,7 +27240,7 @@ function registerChatGroupCommand(group) {
     const members = await resolveMembersOrExit(auth, opts.member);
     const conv = await resolveGroupOrExit(auth, target);
     await requireApproval({
-      cost: "no charge — adds people to the group",
+      free: "adds real people to the group",
       summary: `Add ${members.map(memberLabel).join(", ")} to group "${conv.title ?? conv.id}"`,
       yes: opts.yes,
       commandExample: `amiko chat group add ${JSON.stringify(target)} ${memberFlags(opts.member)}`
@@ -27354,33 +27393,91 @@ 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 (looksLikeConversationId(t))
-    return t;
+  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 });
+    const prof = await amikoWebFetch(auth, `/api/users/${encodeURIComponent(handle)}`, {
+      timeoutMs: 15000
+    });
     if (!prof.user?.id)
       throw new Error(`No user @${handle}.`);
-    return findOrCreateDm(auth, prof.user.id);
+    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)}"`
+        };
+      } 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 groupId;
-  const res = await amikoWebFetch(auth, "/api/search", {
-    query: { q: t, type: "people", limit: 8 },
-    timeoutMs: 15000
-  });
-  const users = res.users ?? [];
-  if (users.length === 0) {
-    throw new Error(`No user matching "${t}". Use an exact @handle, or a conversation id from \`amiko chat list\`.`);
-  }
-  if (users.length > 1) {
-    const names = users.map((u) => `${u.name ?? "?"} (@${u.handle ?? u.id.slice(0, 8)})`).join(", ");
-    throw new Error(`"${t}" is ambiguous — matches: ${names}. Use an exact @handle or a conversation id.`);
+    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}`);
   }
-  return findOrCreateDm(auth, users[0].id);
+  const p = resolved[0];
+  return person({ id: p.userId, name: p.name, handle: p.handle });
 }
 var HTTPS_RE = /^https:\/\//i;
 var CHAT_IMAGE_MIME = new Set([
@@ -27467,11 +27564,20 @@ function registerChatCommand(chat) {
         console.log(dim(` ${unread.trim()}`));
     }
   });
-  chat.command("read <target>").description("Read recent messages in a conversation (conversation id, @handle, or name)").option("--limit <n>", "Max messages", "20").option("--raw", "Output raw JSON").action(async (target, opts) => {
+  chat.command("read <target>").description("Read recent messages in a conversation (conversation id, user id, @handle, or name)").option("--limit <n>", "Max messages", "20").option("--raw", "Output raw JSON").action(async (target, opts) => {
     const auth = authOrExit();
     let convId;
     try {
-      convId = await resolveConversation(auth, target);
+      const resolved = await resolveConversation(auth, target);
+      if (resolved.kind === "user") {
+        const existing = await findDmByUserId(auth, resolved.userId);
+        if (!existing) {
+          throw new Error(`No ${resolved.label} yet — start one with \`amiko chat send\`.`);
+        }
+        convId = existing;
+      } else {
+        convId = resolved.id;
+      }
     } catch (e5) {
       console.error(error(e5 instanceof Error ? e5.message : "Could not resolve target"));
       process.exit(1);
@@ -27502,26 +27608,33 @@ function registerChatCommand(chat) {
         console.log(dim(`  ${when}`));
     }
   });
-  chat.command("send <target> <message>").description("Send a message as yourself (the owner) to a conversation (id, @handle, or name)").option("--image <pathOrUrl>", "Attach an image: local file (jpg/png/webp/gif, ≤10MB) or an Amiko URL (e.g. from `amiko create`)").option("--audio <pathOrUrl>", "Attach audio as a voice note: local file (≤25MB) or an Amiko URL").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (target, message, opts) => {
+  chat.command("send <target> <message>").description("Send a message as yourself (the owner) to a conversation or person (conversation id, user id, @handle, or name — DMs are opened automatically)").option("--image <pathOrUrl>", "Attach an image: local file (jpg/png/webp/gif, ≤10MB) or an Amiko URL (e.g. from `amiko create`)").option("--audio <pathOrUrl>", "Attach audio as a voice note: local file (≤25MB) or an Amiko URL").option("--yes", "Skip the confirmation (required in non-interactive shells)").option("--raw", "Output raw JSON").action(async (target, message, opts) => {
     const auth = authOrExit();
     if (opts.image && opts.audio) {
       console.error(error("Attach either --image or --audio, not both (one media block per message)."));
       process.exit(1);
     }
-    let convId;
+    let resolved;
     try {
-      convId = await resolveConversation(auth, target);
+      resolved = await resolveConversation(auth, target);
     } catch (e5) {
       console.error(error(e5 instanceof Error ? e5.message : "Could not resolve target"));
       process.exit(1);
     }
     const media = opts.image ? `image ${opts.image}` : opts.audio ? `audio ${opts.audio}` : "";
     await requireApproval({
-      cost: "no charge — sends a message as you (the owner)",
-      summary: `Send to ${target}${media ? ` [+${media}]` : ""}: ${message.slice(0, 80)}${message.length > 80 ? "…" : ""}`,
+      free: "sends a message as you (the owner) — the recipients see it",
+      summary: `Send to ${resolved.label}${media ? ` [+${media}]` : ""}: ${message.slice(0, 80)}${message.length > 80 ? "…" : ""}`,
       yes: opts.yes,
       commandExample: `amiko chat send ${JSON.stringify(target)} ${JSON.stringify(message)}`
     });
+    let convId;
+    try {
+      convId = resolved.kind === "user" ? await findOrCreateDm(auth, resolved.userId) : resolved.id;
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : "Could not open the conversation"));
+      process.exit(1);
+    }
     const messagesPath = `/api/conversations/${encodeURIComponent(convId)}/messages`;
     const post = (body) => amikoWebFetch(auth, messagesPath, {
       method: "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyamiko/amiko-cli",
-  "version": "0.14.0-beta.5",
+  "version": "0.14.0-beta.7",
   "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, 人对人); 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 / create + manage group chats AS the owner, including sharing a group's invite/join link + QR, 人对人); 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"]}}}
 ---
@@ -32,6 +32,7 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
 | "find files about Q1 revenue" | shell → `amiko drive search "Q1 revenue"` |
 | "what comments are on my post?" | shell → `amiko post comments --id <postId>` |
 | "search memory for X" | shell → `amiko memory search "X"` |
+| "share the group's invite link" (asked by an admin) | shell → `amiko chat group info "<group>"` (confirm they're admin) → `amiko chat group invite "<group>"` |
 | "what can amiko do?" | shell → `amiko --help` |
 
 The CLI is installed globally and is pre-authenticated when you're inside your workspace folder. Never suggest `amiko login` or `amiko connect` — they don't exist.
@@ -49,7 +50,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 group create`, `chat group add` (no charge, so nothing to quote; but real people see them, so get the owner's explicit approval for the action itself) — and **destructive ops** like `chat group remove/leave/rename/promote`, `twin update --public`, `drive delete`, `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `review reject`.
+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 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 group remove/leave/rename/promote`, `twin update --public`, `drive delete`, `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`.
@@ -124,21 +125,22 @@ 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 read <target>` — recent messages. `<target>` = a conversation id (from `list`), an `@handle`, or a name.
-- `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). For **group chats**, use the conversation id from `list`; for a **DM**, an `@handle`/name resolves + finds-or-creates the DM.
+- `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`.
 - **Inline media**: `--image <pathOrUrl>` (jpg/png/webp/gif, local ≤10MB or an Amiko URL — e.g. a generated image) and `--audio <pathOrUrl>` (local ≤25MB or an Amiko URL → sent as a voice note). One media block per message (image XOR audio). **Video is 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.
-- Name resolution goes through user search; if ambiguous it lists candidates — don't blind-send. A plain name that exactly matches one of the owner's group titles targets that **group**. Server enforces who you're allowed to message (friend/participant rules); surface its error, don't retry.
+- Plain names resolve against the owner's **friends first**, then people search; if ambiguous the CLI errors listing the candidates — ask the owner which one, don't blind-send. A plain name that exactly matches one of the owner's group titles targets that **group**. If a send fails, surface the CLI's error verbatim — don't invent permission explanations or ask the owner to open the chat from the app.
 
 ### Group chats — `amiko chat group`
 
-Create and manage the owner's group chats: `create <name> --member <who>…`, `list`, `info <group>`, `rename <group> <newTitle>`, `add <group> --member <who>…`, `remove <group> --member <who>…`, `promote <group> --member <who>`, `leave <group>` (alias `delete`).
+Create and manage the owner's group chats: `create <name> --member <who>…`, `list`, `info <group>`, `invite <group>`, `rename <group> <newTitle>`, `add <group> --member <who>…`, `remove <group> --member <who>…`, `promote <group> --member <who>`, `leave <group>` (alias `delete`).
 
 - One-shot example — "create a group called Leandro testing with Sophie, Mars and Matthew":
   `amiko chat group create "Leandro testing" --member Sophie --member Mars --member Matthew --yes`
 - `--member` repeats per person and takes a name, `@handle`, or user id. Plain names resolve against the owner's **friends** first, then people search; an ambiguous name errors listing candidates — prefer an exact `@handle` or a user id from `amiko friends list --json`. If any member fails to resolve, the whole command aborts **before anything changes** — fix and re-run.
 - `<group>` is a conversation id (from `chat group list`) or a title (matched case-insensitively — exact matches win before substring matches; if several groups still match, the CLI errors listing the candidates; only the ~100 most recent conversations are scanned, so use the id for old groups).
 - **`leave` (alias `delete`) only hides the group for the owner — it does NOT delete it for other members; there is no true group deletion.** Say so if the owner asks to delete a group. Rename, add, remove-others, and promote require the owner to be a group **admin** (the creator is one automatically); a 403 means they're not — report it, don't retry.
-- Gating: `create`/`add` message real people and `remove`/`leave`/`rename`/`promote` are destructive — all require `--yes` in your shell (see Critical Rules). Reads (`list`, `info`) are free and ungated.
+- `amiko chat group invite <group>` — show the group's **invite/join link + a QR image URL** (both are shareable URLs; the QR encodes the same join link). Use it when a group admin asks how to invite people or for the group's link or QR. **Admins only:** before sharing, confirm the person asking holds the `admin`/`owner` role — check the ROLE column in `amiko chat group info <group>`. If they're a regular member, politely decline and do **not** reveal the link or QR. The link lets anyone who opens it join the group, so treat it like a credential. A 403 means your owner isn't an admin of that group — report it, don't retry.
+- Gating: `create`/`add` message real people and `remove`/`leave`/`rename`/`promote` are destructive — all require `--yes` in your shell (see Critical Rules). Reads (`list`, `info`, `invite`) are free and ungated.
 
 ## Card — behavior notes