@heyamiko/amiko-cli 0.10.1-beta.0 → 0.10.1-beta.3

package/README.md

@@ -1,4 +1,4 @@
-# @heyamiko/amiko-cli (v0.10.1-beta.0)
+# @heyamiko/amiko-cli (v0.10.1-beta.3)
 
 Manage wallets, credits, swaps, MPP marketplace services, and your Amiko twin (identity, documents, voice, avatar, friends, feed, Composio apps) from the terminal. Works for both human users and AI agents running on OpenClaw.
 
@@ -393,6 +393,21 @@ npm publish
 
 ## Changelog
 
+### 0.10.1-beta.3
+
+- **`amiko drive` namespace** replaces `amiko docs` (kept as a `.alias("docs")` so existing scripts and agents keep working). Tracks the [Amiko Drive API](https://github.com/HCF-STUDIOS/amiko-platform/blob/main/amiko-web/docs/api/drive.md): files live under twin-scoped folders, every upload kicks off async RAG parsing, and search hits parsed content once processing completes. Commands:
+  - **Files** — `drive list [--folder <id|root>] [--search <q>] [--limit] [--offset]`, `drive search <query> [--folder]`, `drive upload <source> [--folder] [--title] [--description] [--doc-type]`, `drive download <docId> [--out <path>|--stdout]` (NEW — fetches a 1h signed URL from `GET /docs/[docId]` and writes the bytes), `drive get <docId> [--content]` (NEW — metadata + signed URL, optional parsed content body), `drive rename <docId> --title <new>` (NEW — `PATCH /docs/[docId]`), `drive move <docId> --folder <id|root>` (NEW), `drive delete <docId> --yes`, `drive presign <name>`, `drive status <docId...>` (NEW — `POST /docs/check-processing` for RAG job state).
+  - **Folders** — `drive folder list`, `drive folder create <name> [--parent <id>]`, `drive folder rename <id> --name <new>`, `drive folder move <id> --parent <id|root>`, `drive folder delete <id> [--force] --yes` (force=1 walks the subtree).
+- SKILL.md picks up a one-paragraph Drive section + three new rows in the Examples table (upload / download / search intents → exact `amiko drive` commands).
+
+### 0.10.1-beta.2
+
+- **SKILL.md slimmed ~55%** (31.6 KB / 429 lines → 14.3 KB / 169 lines; ~8.5k → ~3.5k tokens). The skill now leads with "this is the mental model, not a syntax reference — run `amiko <group> --help` for exact flags" and drops per-namespace bash blocks that duplicated `--help` output (credits/wallets/markets/account/docs/voice/avatar/friends/users/feed/posts/conversations/notifications/memory/composio/JSON). Kept everything the CLI's own help *can't* tell an agent: shell-tool invocation rule + "no `amiko_cli` tool exists" failure modes, the `--yes` / report-balance / no-retry critical rules, `--wallet` default behavior, the credits intent-mapping cheatsheet (1 SOL → `--spend`, $5 → `--usd`, 10000 → positional), wallets/markets/conversations behavior notes that aren't in help, the "relationship report" and "who should I meet" playbooks (`friends find` vs `users search` vs `friends matches`), feed/post draft-review workflow + "reading via CLI counts as reading", DM-vs-built-in-sessions routing, and the full memory `search-before-you-answer` doctrine. Pricing table replaced with a one-paragraph "run `markets service list` for live prices" pointer plus rough order-of-magnitude. Result: skill stays well within recommended SKILL.md size budget while preserving every judgment / mental-model line that agents can't learn from `--help`.
+
+### 0.10.1-beta.1
+
+- **SKILL.md** documents the two new feed/post surfaces so agents actually find them: top-of-file Examples table gets rows for "any new posts I haven't seen?" → `amiko feed --unread` and "what comments are on my post?" → `amiko post comments --id <postId>`; top-level command index updated; the Feed & Posts section gains a callout that *reading via the CLI counts as reading the post* (every `amiko feed` / `amiko post comments` call auto-marks for this twin, so successive `feed --unread` calls drain without bookkeeping; user-side reads are written by the web client only). No CLI behavior change.
+
 ### 0.10.1-beta.0
 
 - **`amiko post comments --id <postId>`** (new): lists comments on a post via `GET /api/posts/[id]/comments`. Supports `--limit`, `--cursor`, `--replies` (include nested replies; default top-level only), `--json`. Closes a gap where the CLI could write a comment but couldn't read existing ones — agents previously only saw a `_count.comments` integer from `amiko feed`.

package/dist/index.js

@@ -29139,6 +29139,10 @@ function registerTwinCommand(program2) {
   });
 }
 
+// src/commands/drive.ts
+import { writeFile } from "node:fs/promises";
+import { basename as basename2, resolve as resolvePath } from "node:path";
+
 // src/lib/file-input.ts
 import { readFile } from "node:fs/promises";
 import { basename, extname } from "node:path";
@@ -29236,7 +29240,7 @@ function detectMime(buffer, name) {
   return EXT_MIME[ext] ?? "application/octet-stream";
 }
 
-// src/commands/docs.ts
+// src/commands/drive.ts
 function fmtBytes(n) {
   if (!n || n <= 0)
     return "-";
@@ -29249,6 +29253,16 @@ function fmtBytes(n) {
   }
   return `${v.toFixed(v >= 10 ? 0 : 1)} ${units[i]}`;
 }
+function statusOf(doc2) {
+  const meta3 = doc2.metadata?.status;
+  if (meta3)
+    return meta3;
+  if (doc2.is_processed)
+    return "processed";
+  if (doc2.is_parsed)
+    return "parsed";
+  return "pending";
+}
 function twinFromFlag(opts) {
   const config2 = loadConfig();
   const auth = resolveAuth();
@@ -29262,36 +29276,81 @@ function twinFromFlag(opts) {
     throw e5;
   }
 }
-function registerDocsCommand(program2) {
-  program2.command("list").description("List uploaded documents for a twin").option("--twin <idOrName>", "Target twin id or name").option("--limit <n>", "Max results", "50").option("--json", "Output as JSON").action(async (opts) => {
+function renderDocTable(docs) {
+  const rows = [
+    [
+      dim("ID"),
+      dim("NAME"),
+      dim("TYPE"),
+      dim("FOLDER"),
+      dim("STATUS"),
+      dim("CREATED")
+    ],
+    ...docs.map((doc2) => [
+      doc2.id,
+      doc2.title || doc2.filename,
+      doc2.file_type || "-",
+      doc2.folder_id || dim("root"),
+      statusOf(doc2),
+      doc2.created_at?.slice(0, 10) || "-"
+    ])
+  ];
+  console.log(table(rows));
+}
+async function fetchSignedUrl(auth, twinId, docId) {
+  return amikoWebFetch(auth, `/api/agents/${twinId}/docs/${docId}`);
+}
+function registerDriveCommand(program2) {
+  program2.command("list").description("List drive files (optionally filter by folder or search)").option("--twin <idOrName>", "Target twin id or name").option("--folder <id|root>", "Filter by folder id, or 'root' for drive root").option("--search <q>", "Case-insensitive search over filename/title/description/content").option("--limit <n>", "Max results per page", "50").option("--offset <n>", "Skip N rows", "0").option("--json", "Output as JSON").action(async (opts) => {
     const { twinId, auth } = twinFromFlag(opts);
-    const spinner = opts.json ? null : ora("Loading documents...").start();
+    const spinner = opts.json ? null : ora("Loading files...").start();
     try {
-      const data = await amikoWebFetch(auth, `/api/agents/${twinId}/docs`, { query: { limit: opts.limit ?? "50" } });
+      const query = {
+        limit: opts.limit ?? "50",
+        offset: opts.offset ?? "0"
+      };
+      if (opts.search)
+        query.search = opts.search;
+      if (opts.folder !== undefined)
+        query.folderId = opts.folder;
+      const data = await amikoWebFetch(auth, `/api/agents/${twinId}/docs`, { query });
       spinner?.stop();
       renderOutput(data, (d) => {
         if (!d.docs || d.docs.length === 0) {
-          console.log(dim("No documents."));
+          console.log(dim("No files."));
           return;
         }
-        console.log(heading(`Documents (${d.total ?? d.docs.length})`));
-        const rows = [
-          [
-            dim("ID"),
-            dim("NAME"),
-            dim("TYPE"),
-            dim("STATUS"),
-            dim("CREATED")
-          ],
-          ...d.docs.map((doc2) => [
-            doc2.id,
-            doc2.title || doc2.filename,
-            doc2.file_type || "-",
-            doc2.is_processed ? "processed" : doc2.is_parsed ? "parsed" : "pending",
-            doc2.created_at?.slice(0, 10) || "-"
-          ])
-        ];
-        console.log(table(rows));
+        const header = opts.search ? `Files matching "${opts.search}" (${d.total ?? d.docs.length})` : opts.folder ? `Files in ${opts.folder} (${d.total ?? d.docs.length})` : `Files (${d.total ?? d.docs.length})`;
+        console.log(heading(header));
+        renderDocTable(d.docs);
+      }, { json: opts.json });
+    } catch (e5) {
+      spinner?.stop();
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  program2.command("search <query>").description("Search files by name, description, or parsed content").option("--twin <idOrName>", "Target twin id or name").option("--folder <id|root>", "Restrict search to a folder").option("--limit <n>", "Max results", "50").option("--json", "Output as JSON").action(async (query, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    const spinner = opts.json ? null : ora(`Searching for "${query}"...`).start();
+    try {
+      const q = {
+        search: query,
+        limit: opts.limit ?? "50"
+      };
+      if (opts.folder !== undefined)
+        q.folderId = opts.folder;
+      const data = await amikoWebFetch(auth, `/api/agents/${twinId}/docs`, { query: q });
+      spinner?.stop();
+      renderOutput(data, (d) => {
+        if (!d.docs || d.docs.length === 0) {
+          console.log(dim(`No files match "${query}".`));
+          return;
+        }
+        console.log(heading(`Matches for "${query}" (${d.total ?? d.docs.length})`));
+        renderDocTable(d.docs);
+        console.log(dim(`
+Search hits filename, title, description, and parsed RAG content (once processed).`));
       }, { json: opts.json });
     } catch (e5) {
       spinner?.stop();
@@ -29299,7 +29358,7 @@ function registerDocsCommand(program2) {
       process.exit(1);
     }
   });
-  program2.command("upload <source>").description("Upload a document (path | https URL | - for stdin)").option("--twin <idOrName>", "Target twin id or name").option("--name <filename>", "Override filename").option("--title <title>", "Document title (defaults to filename)").option("--description <text>", "Document description").option("--doc-type <type>", "Document type (e.g. 'other', 'memory')", "other").option("--stdin", "Read from stdin (source must be -)").option("--json", "Output as JSON").action(async (source, opts) => {
+  program2.command("upload <source>").description("Upload a file (path | https URL | - for stdin)").option("--twin <idOrName>", "Target twin id or name").option("--name <filename>", "Override filename").option("--title <title>", "File title (defaults to filename without extension)").option("--description <text>", "File description").option("--doc-type <type>", "Document type: personal, work, academic, financial, communication, health, other", "other").option("--folder <id>", "Target folder id (omit for drive root)").option("--stdin", "Read from stdin (source must be -)").option("--json", "Output as JSON").action(async (source, opts) => {
     const { twinId, auth } = twinFromFlag(opts);
     const spinner = opts.json ? null : ora("Reading input...").start();
     try {
@@ -29321,28 +29380,118 @@ function registerDocsCommand(program2) {
       if (spinner)
         spinner.text = `Registering ${upload.filename}...`;
       const title = opts.title || upload.filename.replace(/\.[^.]+$/, "");
-      const doc2 = await amikoWebFetch(auth, `/api/agents/${twinId}/docs`, {
-        method: "POST",
-        body: {
-          filename: upload.filename,
-          fileUrl: upload.url,
-          fileType: upload.fileType,
-          title,
-          description: opts.description ?? undefined,
-          doc_type: opts.docType ?? "other"
-        }
-      });
+      const body = {
+        filename: upload.filename,
+        fileUrl: upload.url,
+        fileType: upload.fileType,
+        title,
+        doc_type: opts.docType ?? "other"
+      };
+      if (opts.description !== undefined)
+        body.description = opts.description;
+      if (opts.folder !== undefined)
+        body.folderId = opts.folder;
+      const doc2 = await amikoWebFetch(auth, `/api/agents/${twinId}/docs`, { method: "POST", body });
       spinner?.stop();
       renderOutput(doc2, (d) => {
         console.log(success(`Uploaded ${d.filename}`));
         console.log(label("Doc ID", d.id));
         console.log(label("Title", d.title || "-"));
+        if (d.folder_id)
+          console.log(label("Folder", d.folder_id));
         if (upload.fileSize)
           console.log(label("Size", fmtBytes(upload.fileSize)));
         if (upload.fileType)
           console.log(label("Type", upload.fileType));
-        if (upload.url)
-          console.log(label("URL", upload.url));
+        if (d.job_id) {
+          console.log(label("RAG job", d.job_id));
+          console.log(dim("Processing runs in the background. Use `amiko drive status <id>` to check."));
+        }
+      }, { json: opts.json });
+    } catch (e5) {
+      spinner?.stop();
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  program2.command("download <docId>").description("Download a file from the drive").option("--twin <idOrName>", "Target twin id or name").option("--out <path>", "Output path (defaults to original filename in cwd)").option("--stdout", "Write file bytes to stdout instead of a file").option("--json", "Print metadata JSON instead of downloading").action(async (docId, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    const modes = [opts.json, opts.stdout, opts.out].filter(Boolean).length;
+    if (modes > 1) {
+      console.error(error("--json, --stdout, and --out are mutually exclusive — pick one."));
+      process.exit(1);
+    }
+    const spinner = opts.json || opts.stdout ? null : ora("Fetching file...").start();
+    try {
+      const meta3 = await fetchSignedUrl(auth, twinId, docId);
+      if (opts.json) {
+        console.log(JSON.stringify(meta3, null, 2));
+        return;
+      }
+      if (spinner)
+        spinner.text = `Downloading ${meta3.doc.filename}...`;
+      const controller = new AbortController;
+      const timeout = setTimeout(() => controller.abort(), 60000);
+      let res;
+      try {
+        res = await fetch(meta3.signed_url, { signal: controller.signal });
+      } catch (fetchErr) {
+        if (fetchErr.name === "AbortError") {
+          throw new Error("Signed-URL download timed out after 60s. Retry; the URL is valid for 1h.");
+        }
+        throw fetchErr;
+      } finally {
+        clearTimeout(timeout);
+      }
+      if (!res.ok) {
+        throw new Error(`Signed-URL fetch failed: ${res.status} ${res.statusText}`);
+      }
+      const buf = Buffer.from(await res.arrayBuffer());
+      if (opts.stdout) {
+        process.stdout.write(buf);
+        return;
+      }
+      const outPath = resolvePath(opts.out ?? basename2(meta3.doc.filename));
+      await writeFile(outPath, buf);
+      spinner?.stop();
+      console.log(success(`Saved ${meta3.doc.filename} → ${outPath}`));
+      console.log(label("Size", fmtBytes(buf.length)));
+      if (meta3.doc.file_type)
+        console.log(label("Type", meta3.doc.file_type));
+    } catch (e5) {
+      spinner?.stop();
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  program2.command("get <docId>").description("Show one file's metadata, parsed content, and signed URL").option("--twin <idOrName>", "Target twin id or name").option("--content", "Include parsed RAG content body in the output").option("--json", "Output as JSON").action(async (docId, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    const spinner = opts.json ? null : ora("Loading file...").start();
+    try {
+      const data = await fetchSignedUrl(auth, twinId, docId);
+      spinner?.stop();
+      renderOutput(data, (d) => {
+        console.log(heading(d.doc.title || d.doc.filename));
+        console.log(label("ID", d.doc.id));
+        console.log(label("Filename", d.doc.filename));
+        if (d.doc.file_type)
+          console.log(label("Type", d.doc.file_type));
+        if (d.doc.folder_id)
+          console.log(label("Folder", d.doc.folder_id));
+        if (d.doc.description)
+          console.log(label("Description", d.doc.description));
+        console.log(label("Status", statusOf(d.doc)));
+        if (d.doc.metadata?.error)
+          console.log(label("Error", d.doc.metadata.error));
+        console.log(label("Signed URL", d.signed_url));
+        if (opts.content && d.doc.content) {
+          console.log(heading(`
+Parsed content`));
+          console.log(d.doc.content);
+        } else if (d.doc.content) {
+          console.log(dim(`
+Parsed content available (${d.doc.content.length} chars). Pass --content to print.`));
+        }
       }, { json: opts.json });
     } catch (e5) {
       spinner?.stop();
@@ -29350,36 +29499,170 @@ function registerDocsCommand(program2) {
       process.exit(1);
     }
   });
-  program2.command("delete <docId>").description("Delete a document").option("--twin <idOrName>", "Target twin id or name").option("--yes", "Skip confirmation").option("--json", "Output as JSON").action(async (docId, opts) => {
+  program2.command("rename <docId>").description("Rename a file (updates title)").option("--twin <idOrName>", "Target twin id or name").requiredOption("--title <newTitle>", "New title").option("--description <text>", "Also update description (pass empty string to clear)").option("--json", "Output as JSON").action(async (docId, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    const body = { title: opts.title };
+    if (opts.description !== undefined)
+      body.description = opts.description;
+    try {
+      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/${docId}`, { method: "PATCH", body });
+      renderOutput(result, () => console.log(success(`Renamed ${docId} → "${opts.title}"`)), { json: opts.json });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  program2.command("move <docId>").description("Move a file to a different folder").option("--twin <idOrName>", "Target twin id or name").requiredOption("--folder <id|root>", "Destination folder id, or 'root' for drive root").option("--json", "Output as JSON").action(async (docId, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    const folderId = opts.folder === "root" ? null : opts.folder;
+    try {
+      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/${docId}`, { method: "PATCH", body: { folderId } });
+      renderOutput(result, () => console.log(success(`Moved ${docId} → ${folderId ?? "root"}`)), { json: opts.json });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  program2.command("delete <docId>").description("Delete a file (removes storage object + RAG embeddings)").option("--twin <idOrName>", "Target twin id or name").option("--yes", "Skip confirmation").option("--json", "Output as JSON").action(async (docId, opts) => {
     const { twinId, auth } = twinFromFlag(opts);
     await confirmDestructive({
-      action: `Delete document ${docId}`,
-      detail: "This will remove the document and its embeddings from the twin's RAG.",
+      action: `Delete file ${docId}`,
+      detail: "This removes the file from storage and clears its embeddings from the twin's RAG.",
       yes: opts.yes,
-      commandExample: `amiko docs delete ${docId}`
+      commandExample: `amiko drive delete ${docId}`
     });
-    const spinner = opts.json ? null : ora("Deleting document...").start();
+    const spinner = opts.json ? null : ora("Deleting...").start();
     try {
       const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/${docId}`, { method: "DELETE" });
       spinner?.stop();
-      renderOutput(result, () => console.log(success(`Deleted ${docId}`)), { json: opts.json });
+      renderOutput(result, () => console.log(success(`Deleted ${docId}`)), {
+        json: opts.json
+      });
     } catch (e5) {
       spinner?.stop();
       console.error(error(e5 instanceof Error ? e5.message : String(e5)));
       process.exit(1);
     }
   });
-  program2.command("presign <source>").description("Get a presigned upload URL for a document (no upload)").option("--twin <idOrName>", "Target twin id or name").option("--name <filename>", "Override filename used in the request").option("--json", "Output as JSON").action(async (source, opts) => {
+  program2.command("presign <name>").description("Get a presigned upload URL (browser-direct uploads; no upload performed)").option("--twin <idOrName>", "Target twin id or name").option("--json", "Output as JSON").action(async (name, opts) => {
     const { twinId, auth } = twinFromFlag(opts);
-    const filename = opts.name ?? (source === "-" ? "stdin" : source.split("/").pop() ?? source);
     try {
-      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/presigned-url`, { method: "POST", body: { filename } });
+      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/presigned-url`, { method: "POST", body: { filename: name } });
       renderOutput(result, (r) => console.log(JSON.stringify(r, null, 2)), { json: opts.json });
     } catch (e5) {
       console.error(error(e5 instanceof Error ? e5.message : String(e5)));
       process.exit(1);
     }
   });
+  program2.command("status <docId...>").description("Check RAG processing status for one or more files").option("--twin <idOrName>", "Target twin id or name").option("--json", "Output as JSON").action(async (docIds, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    try {
+      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/check-processing`, {
+        method: "POST",
+        body: { docIds }
+      });
+      renderOutput(result, (r) => {
+        const rows = [[dim("DOC ID"), dim("STATUS"), dim("ERROR")]];
+        for (const [id, v] of Object.entries(r.results)) {
+          rows.push([id, v.status, v.error ?? ""]);
+        }
+        console.log(table(rows));
+      }, { json: opts.json });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  const folder = program2.command("folder").description("Manage drive folders — list, create, rename, move, delete");
+  folder.command("list").description("List all folders for the twin (flat — clients build the tree)").option("--twin <idOrName>", "Target twin id or name").option("--json", "Output as JSON").action(async (opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    try {
+      const data = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/folders`);
+      renderOutput(data, (d) => {
+        if (!d.folders || d.folders.length === 0) {
+          console.log(dim("No folders."));
+          return;
+        }
+        console.log(heading(`Folders (${d.folders.length})`));
+        const rows = [
+          [dim("ID"), dim("NAME"), dim("PARENT"), dim("CREATED")],
+          ...d.folders.map((f) => [
+            f.id,
+            f.name,
+            f.parent_id || dim("root"),
+            f.created_at?.slice(0, 10) || "-"
+          ])
+        ];
+        console.log(table(rows));
+      }, { json: opts.json });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  folder.command("create <name>").description("Create a folder (defaults to drive root)").option("--twin <idOrName>", "Target twin id or name").option("--parent <id>", "Parent folder id (omit for root)").option("--json", "Output as JSON").action(async (name, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    const body = { name };
+    if (opts.parent !== undefined)
+      body.parentId = opts.parent;
+    try {
+      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/folders`, { method: "POST", body });
+      renderOutput(result, (r) => {
+        console.log(success(`Created folder "${r.folder.name}"`));
+        console.log(label("Folder ID", r.folder.id));
+        console.log(label("Parent", r.folder.parent_id || "root"));
+      }, { json: opts.json });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  folder.command("rename <folderId>").description("Rename a folder").option("--twin <idOrName>", "Target twin id or name").requiredOption("--name <newName>", "New folder name (1–120 chars)").option("--json", "Output as JSON").action(async (folderId, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    try {
+      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/folders/${folderId}`, { method: "PATCH", body: { name: opts.name } });
+      renderOutput(result, () => console.log(success(`Renamed folder ${folderId} → "${opts.name}"`)), { json: opts.json });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  folder.command("move <folderId>").description("Move a folder under a new parent").option("--twin <idOrName>", "Target twin id or name").requiredOption("--parent <id|root>", "New parent folder id, or 'root'").option("--json", "Output as JSON").action(async (folderId, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    const parentId = opts.parent === "root" ? null : opts.parent;
+    try {
+      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/folders/${folderId}`, { method: "PATCH", body: { parentId } });
+      renderOutput(result, () => console.log(success(`Moved folder ${folderId} → ${parentId ?? "root"}`)), { json: opts.json });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
+  folder.command("delete <folderId>").description("Delete a folder (use --force to delete non-empty folders + their contents)").option("--twin <idOrName>", "Target twin id or name").option("--force", "Recursively delete subfolders and files in the subtree").option("--yes", "Skip confirmation").option("--json", "Output as JSON").action(async (folderId, opts) => {
+    const { twinId, auth } = twinFromFlag(opts);
+    await confirmDestructive({
+      action: opts.force ? `Force-delete folder ${folderId} and all its contents` : `Delete folder ${folderId}`,
+      detail: opts.force ? "This walks the subtree and removes every doc + subfolder under this folder." : "Empty folder only. Non-empty deletes return 409; pass --force to remove the whole subtree.",
+      yes: opts.yes,
+      commandExample: `amiko drive folder delete ${folderId}${opts.force ? " --force" : ""}`
+    });
+    try {
+      const result = await amikoWebFetch(auth, `/api/agents/${twinId}/docs/folders/${folderId}`, {
+        method: "DELETE",
+        query: opts.force ? { force: "1" } : undefined
+      });
+      renderOutput(result, (r) => {
+        console.log(success(`Deleted folder ${folderId}`));
+        if (typeof r.deletedFiles === "number")
+          console.log(label("Files removed", String(r.deletedFiles)));
+        if (typeof r.deletedSubfolders === "number")
+          console.log(label("Subfolders removed", String(r.deletedSubfolders)));
+      }, { json: opts.json });
+    } catch (e5) {
+      console.error(error(e5 instanceof Error ? e5.message : String(e5)));
+      process.exit(1);
+    }
+  });
 }
 
 // src/commands/voice.ts
@@ -31513,7 +31796,7 @@ program2.name("amiko").description("Amiko CLI — swap tokens, manage credits, b
 var markets = program2.command("markets").description("MPP marketplace — discover and call paid AMIKO services");
 var wallets = program2.command("wallets").description("Manage twin wallets — list, swap, bridge");
 var twin = program2.command("twin").description("Update twin identity (name, description, visibility)");
-var docs = program2.command("docs").description("Manage twin RAG documents — list, upload, delete, presign");
+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");
@@ -31539,7 +31822,7 @@ registerDiscoveryCommand(markets);
 registerUpdateCommand(program2);
 registerAccountsCommand(program2);
 registerTwinCommand(twin);
-registerDocsCommand(docs);
+registerDriveCommand(drive);
 registerVoiceCommand(voice);
 registerAvatarCommand(avatar);
 registerFriendsCommand(friends);

package/package.json

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

package/skills/SKILL.md

@@ -7,9 +7,11 @@ metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["node"]}}}
 
 # Amiko CLI
 
+This file is the **mental model**, not a syntax reference. For exact flags and subcommands, run `amiko <group> --help` — the CLI's help is the authoritative source and stays in sync with each release.
+
 ## How to invoke — ALWAYS use your shell-execution tool
 
-Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar) and run `amiko <subcommand>`. Amiko is a shell program, not a callable tool. Always go through the shell tool.
+Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar) and run `amiko <subcommand>`. Amiko is a shell program, not a callable tool.
 
 ### Examples — copy this pattern
 
@@ -20,403 +22,155 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
 | "swap 1 SOL to USDC" | shell → `amiko wallets swap quote 1 SOL USDC` (then send with `--yes` after approval) |
 | "did anyone DM me?" | shell → `amiko conversation list` |
 | "any notifications?" | shell → `amiko notifications list --unread` |
+| "any new posts I haven't seen?" | shell → `amiko feed --unread` |
+| "upload report.pdf to my drive" | shell → `amiko drive upload ./report.pdf` |
+| "download the file with id X" | shell → `amiko drive download X` |
+| "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"` |
 | "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`.
+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.
 
 ### Failure modes to avoid
 
-- A tool named `amiko_cli` / `amiko-cli` / `amiko` (or this skill's name) does **not** exist. The only path is the shell tool above. If you try to call any of those as a tool, the gateway returns `Tool ... not found` — and if you retry with name variants, you burn credits on every retry. Don't retry. Re-route through the shell tool.
-- Do not invent intermediate "amiko" tools (`amiko.balance`, `amiko.credits`, etc.). Every Amiko action goes through one path: shell tool → `amiko <subcommand>`.
-
-## Top-level commands at a glance
-
-Each row is a first-level command group or command. Start here when the user asks what the CLI can do.
-
-| Command | What it does |
-|---------|--------------|
-| `amiko markets <cmd>` | Paid MPP services: X search, image gen, Amazon, TTS/STT/chat, generic service call, discover |
-| `amiko wallets <cmd>` | Wallet ops: create, list, sync balance, transfer tokens out, swap on Solana (Jupiter), bridge USDC cross-chain (Across) |
-| `amiko credits <cmd>` | Show credit balance, top up with AMIKO/SOL/USDC/USDT (10,000 credits = $1) |
-| `amiko twin <cmd>` | Update the twin's identity — name, description, public visibility |
-| `amiko docs <cmd>` | Manage twin RAG documents — list, upload (path/URL/stdin), delete, presign |
-| `amiko voice <cmd>` | Design/clone/reset the twin's voice, create a voice from sample |
-| `amiko avatar <cmd>` | Set the twin's avatar image (max 5 MB) |
-| `amiko friends <cmd>` | Social graph — list, requests, add, accept, remove, matches, reports |
-| `amiko users <cmd>` | Search users, view public profile |
-| `amiko post <cmd>` | Create posts and comments on the feed (optionally with media) |
-| `amiko review <cmd>` | Review queue — list, approve, or reject twin-drafted comments |
-| `amiko feed` | Read the friends feed, for-you feed, or filter by hashtag |
-| `amiko composio <cmd>` | Connect / disconnect third-party OAuth apps (Gmail, GitHub, …) |
-| `amiko conversation <cmd>` | DM/chat — list, find, create, send messages |
-| `amiko notifications <cmd>` | Platform notifications — list, mark as read |
-| `amiko memory <cmd>` | Cross-agent memory — `search` before answering personal questions, `add` what's worth remembering, `list` / `rm` / `status` / `sync` local memory files |
-| `amiko accounts` | Show the resolved identity (authenticated, userId, twinId, platform) |
-| `amiko info` | Show the active twin (name, description, public, voice, avatar) |
-| `amiko config <cmd>` | Show resolved config |
-| `amiko update` | Self-update the CLI |
-
-All twin-scoped commands accept `--twin <id>` to target a non-default twin.
+- A tool named `amiko_cli` / `amiko-cli` / `amiko` (or this skill's name) does **not** exist as a callable tool. The only path is the shell tool above. If you try to call any of those, the gateway returns `Tool ... not found` — and retries burn credits. Don't retry; re-route through the shell.
+- Do not invent intermediate "amiko" tools (`amiko.balance`, etc.). Every action goes through one path: shell tool → `amiko <subcommand>`.
+
+## Command groups
+
+Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `wallets`, `credits`, `twin`, `drive` (files / folders / RAG; `docs` is an alias), `voice`, `avatar`, `friends`, `users`, `post`, `review`, `feed`, `composio`, `conversation`, `notifications`, `memory`, plus the top-level `accounts`, `info`, `config`, `update`. All twin-scoped commands accept `--twin <id>`. Most commands support `--json`.
+
+## Critical Rules
+
+1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI refuses to run `markets *`, `credits topup`, `wallets swap send`, `wallets bridge send`, `wallets transfer` (and destructive ops like `twin update --public`, `docs delete`, `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `composio disconnect`, `review reject`) unless `--yes` is passed. The refusal prints the cost and the re-run command. **Quote the cost, get explicit approval, THEN append `--yes`.**
+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`.
+5. **Check balance before expensive ops.** Run `amiko credits balance` if unsure.
+6. **Payments are custodied.** The platform signs and moves tokens from the twin's wallet — the CLI never holds keys.
+
+### Quoting cost before running
+
+Prices change. Before any paid call, run `amiko markets service list` or `amiko markets discover` to fetch the live price, then quote it to the user. Rough order of magnitude: text/search/TTS ≈ 1 AMIKO, SFX ≈ $0.05, music ≈ $0.10, image gen varies by model/quality (OpenAI pass-through × 1.30 markup).
 
 ## The `--wallet` default (read this before any paid command)
 
-Every paid / value-moving command (`markets search`, `markets image`, `markets amazon search`, `markets service *`, `wallets swap send`, `wallets bridge send`, `wallets transfer`) spends tokens from an on-chain wallet. As of v0.9.0-beta.9 you almost never need to pass `--wallet` explicitly:
+Every paid / value-moving command spends from an on-chain wallet, but you almost never need `--wallet` explicitly:
 
-- **Default**: the CLI auto-selects the twin's first active **Solana** wallet from `GET /api/agents/{id}/wallets`.
-- **Override**: pass `--wallet <address>` only if you want a different wallet than the default.
-- **No wallet yet?** The CLI will tell you to run `amiko wallets create --chain solana` first. Create once per twin; reuse forever.
-- **Bridges**: `wallets bridge quote/send` similarly default `--depositor` to the wallet on the origin chain (Solana for `--from solana`, Base for `--from base`).
+- **Default**: CLI auto-selects the twin's first active **Solana** wallet.
+- **Override**: pass `--wallet <address>` only if you want a different wallet.
+- **No wallet yet?** The CLI tells you to run `amiko wallets create --chain solana`. One-shot per `chain+custodian`; reuse forever.
+- **Bridges**: `wallets bridge quote/send` defaults `--depositor` to the wallet on the origin chain (Solana for `--from solana`, Base for `--from base`).
 
-> Never prompt the user for their wallet address when the default would work. Only surface `--wallet` if the command errors out saying there's no default.
+> Never prompt the user for a wallet address when the default works. Only surface `--wallet` if the command errors out.
 
-## Critical Rules
+## Credits — intent mapping
 
-1. **Every paid / value-moving command is hard-gated on `--yes` in a non-interactive shell.** The CLI *refuses* to run `markets image`, `markets search`, `markets amazon search`, `markets service call`, `markets service tts`, `markets service stt`, `markets service chat`, `credits topup`, `wallets swap send`, `wallets bridge send`, or `wallets transfer` unless `--yes` is passed. The refusal is loud: it prints the cost and the command you should re-run. **Quote the cost to the user, get explicit approval, THEN append `--yes`**. Same for destructive non-paid commands (`twin update --public`, `docs delete`, `friends remove`, `friends reports request`, `avatar update`, `voice reset`, `composio disconnect`, `review reject`).
-2. **After every paid command, report the remaining balance.** The CLI prints a `Balance: N credits` line at the end of every paid command — include that figure in your reply.
-3. **Never retry a failed command.** Report the error and stop. Every paid call costs tokens even on failure.
-4. **Never suggest `amiko login` or `amiko connect`.** These don't exist. Auth is automatic when you run from your workspace folder.
-5. **Check balance before expensive operations.** Run `amiko credits balance` first if unsure.
-6. **Payments are automatic.** The platform signs and moves tokens from the twin's wallet for each paid call — the CLI never holds keys.
-
-### Pricing cheat sheet (quote this to the user before running)
-
-| Command | Cost |
-|---------|------|
-| `amiko markets search "<query>"` | 1 AMIKO |
-| `amiko markets image "<prompt>"` | varies by model/quality/size (≈$0.005–$1.30 × 1.30 markup) |
-| `amiko markets amazon search "<query>"` | 1 AMIKO |
-| `amiko markets amazon quote <ASIN>` | Free |
-| `amiko markets service tts <voiceId> "<text>"` | 1 AMIKO |
-| `amiko markets service call POST /v1/sfx ...` | $0.05 |
-| `amiko markets service call POST /v1/music ...` | $0.10 |
-| `amiko markets service call POST /v1/music/plan ...` | $0.02 |
-| `amiko wallets swap quote ...` | Free |
-| `amiko wallets swap send ...` | Solana gas + 10bps |
-| `amiko wallets transfer ...` | Chain gas only |
-| `amiko credits topup ...` | Whatever amount you top up |
-
-## Credits
-
-**Display credits: 10,000 credits = $1.00 USD.**
-
-```bash
-amiko credits balance                                 # show balance as "N credits"
-amiko credits topup --spend 1 --token SOL --yes       # "1 SOL worth of credits"
-amiko credits topup --usd 5 --token USDC --yes        # $5 paying in USDC
-amiko credits topup 10000 --token AMIKO --yes         # 10,000 credits = $1
-```
-
-`topup` accepts **one** of three amount forms:
-
-| Form | Meaning | Example |
-|------|---------|---------|
-| `<amount>` (positional) | credits | `amiko credits topup 10000 --token AMIKO` |
-| `--usd <n>` | US dollars | `amiko credits topup --usd 5 --token USDC` |
-| `--spend <n>` | spend N of `--token` | `amiko credits topup --spend 1 --token SOL` |
-
-Map user intent directly — no manual price math:
+Display unit: **10,000 credits = $1.00 USD.** `topup` accepts one of three amount forms — map user intent directly, no manual price math:
 
 - "top up 1 SOL of credits" → `--spend 1 --token SOL`
 - "top up $5 in USDC" → `--usd 5 --token USDC`
-- "top up 10000 credits with AMIKO" → `10000 --token AMIKO`
-
-Supported tokens: AMIKO, SOL, USDC, USDT. The CLI fetches the live price, the platform transfers from the twin's wallet, and on-chain verification credits the account. Balance can lag by a few seconds after topup — re-run `amiko credits balance` if it looks stale.
-
-## Wallets
-
-```bash
-amiko wallets list                                   # all twin wallets + cached balances
-amiko wallets create --chain solana                  # create a wallet (solana | base)
-amiko wallets balance <address>                      # force-sync one wallet; returns fresh balances
-amiko wallets transfer --to <addr> --amount 100 --token amiko --yes  # send tokens out of a twin wallet
-amiko wallets swap quote 1.0 SOL USDC                # Jupiter quote (free)
-amiko wallets swap send 1.0 SOL USDC --yes           # --wallet defaults to your Solana wallet
-amiko wallets swap tokens                            # supported tokens list
-amiko wallets bridge quote 10 --from solana --to base --recipient <addr>
-amiko wallets bridge send 10 --from solana --to base --recipient <addr> --yes
-amiko wallets bridge status <txHash>
-amiko wallets bridge routes
-amiko wallets bridge limits
-```
-
-- `wallets list` returns **cached** balances (platform doesn't auto-sync). If they look stale, run `wallets balance <address>` to force a sync for that wallet.
-- `wallets create` is one-shot per `chain+custodian` pair (409 if one already exists) — run once for the twin and reuse.
-- `wallets transfer` sends tokens from a twin wallet to an external address. Only Crossmint-custodied wallets are supported (agent-signed on the server). `--wallet` defaults to your Solana wallet; pass `--chain base` + `--wallet` to send from a Base wallet. `--token` accepts symbols (`sol`, `usdc`, `usdt`, `amiko` on Solana; `eth` on Base) or a raw mint/contract address. Returns a tx hash once the transaction lands on-chain. Paid/destructive — requires `--yes` in non-interactive shells.
-- Swaps run via Jupiter on Solana. Supported: SOL, USDC, USDT, AMIKO, PYUSD, BONK, JUP, RAY, JitoSOL — or any mint address.
-- Bridging goes through Across Protocol. Solana ↔ EVM requires `--recipient` (different address formats).
-
-## Market (paid MPP services)
-
-```bash
-amiko markets search "AI agents"                      # 1 AMIKO — X/Twitter search
-amiko markets image "a sunset over mountains" --yes   # gpt-image-2 high 1024² default — AMIKO @ OpenAI pass-through × 1.30
-amiko markets image "logo" --background transparent   # transparent bg
-amiko markets image "portrait" --size 1024x1536       # portrait orientation
-amiko markets image "icon" --model gpt-image-1-mini --quality low  # cheapest tier
-amiko markets amazon search "usb c cable"             # 1 AMIKO — product search
-amiko markets amazon quote B01GGKYKQM                 # free — price quote
-amiko markets service list                            # all services + prices
-amiko markets service call POST /v1/sfx '{"text":"thunder","duration_seconds":5}'
-amiko markets service call POST /v1/music '{"prompt":"lo-fi beat","music_length_ms":30000}'
-amiko markets service tts 21m00Tcm4TlvDq8ikWAM "Hello world"
-amiko markets service call POST /v1/music/plan '{"prompt":"epic orchestral"}'
-amiko markets service call <METHOD> <path> [body]     # any MPP endpoint
-amiko markets discover                                # service info + pricing
-```
-
-All paid markets commands auto-select the twin's active Solana wallet. Pass `--wallet <address>` only to override. Audio and image endpoints return permanent Supabase Storage URLs.
-
-## Account & Twin
-
-```bash
-amiko accounts                                   # resolved identity (authenticated, userId, twinId, platform)
-amiko info                                       # twin info (name, description, public, voice, avatar)
-amiko twin update --name "New Name"
-amiko twin update --description "..."
-amiko twin update --public true --yes            # destructive — requires --yes in non-TTY
-```
-
-## Documents (RAG)
-
-```bash
-amiko docs list                                  # list
-amiko docs upload ./notes.pdf                    # path
-amiko docs upload https://example.com/x.pdf      # URL
-cat file.pdf | amiko docs upload - --stdin --name file.pdf
-amiko docs delete <docId> --yes                  # destructive
-amiko docs presign ./file.pdf                    # presigned S3 URL only
-```
-
-## Voice
-
-```bash
-amiko voice design --description "warm, low, male, confident, measured"  # min 20 chars
-amiko voice create --sample <generated_voice_id>
-amiko voice clone ./me.mp3                       # path | URL | -
-amiko voice reset --yes                          # destructive
-```
-
-## Avatar
-
-```bash
-amiko avatar update --file ./portrait.png --yes  # max 5 MB, destructive
-```
-
-## Friends
-
-```bash
-amiko friends list                               # list all
-amiko friends list --type user                   # filter
-amiko friends requests                           # pending requests (incoming + outgoing)
-amiko friends requests --direction incoming
-amiko friends add --id <userId>
-amiko friends accept <friendshipId>
-amiko friends remove <friendshipId> --yes        # destructive
-amiko friends matches                            # pre-generated match candidates (from cron)
-amiko friends matches --dimension personality
-amiko friends find --relationship "cofounder with design taste"  # on-demand LLM match for a custom relationship
-amiko friends reports list                       # all reports (any status)
-amiko friends reports pending                    # pending-consent: awaiting mine + awaiting theirs
-amiko friends reports view <reportId>
-amiko friends reports request --id <userId> --type friend|romantic|career --yes
-amiko friends reports consent <reportId>         # respondent approves; report then generates
-amiko friends reports cancel <reportId>
-amiko friends reports retry <reportId>           # re-run a failed generation
-```
-
-### Answering relationship questions ("how is my relationship with X?")
-
-When the user asks about their relationship / compatibility with a specific person (by name or handle), follow this playbook:
-
-1. **Resolve the person to a user id.** Check `amiko friends list --json` first. If not a friend, try `amiko users search "<name>" --json`. If still ambiguous, ask the user which one they mean.
-2. **Look for an existing report.** Run `amiko friends reports list --json` and filter by `initiator.id` or `respondent.id` matching the resolved user id. If one exists with `status=completed`, use `amiko friends reports view <id>` and summarize. If `status=pending_consent` or `generating`, tell the user it is in progress.
-3. **If none exists**, don't silently create one. Ask the user which of the three report types they want (`friend` / `romantic` / `career`), and confirm that the other user will be notified to consent. Only then run `amiko friends reports request --id <userId> --type <type> --yes`.
-4. **For "who is waiting on whom"**, use `amiko friends reports pending` — it splits `pending_consent` reports into *awaiting my consent* (I can `consent <id>`) vs *awaiting theirs* (I can `cancel <id>`). Use this before deciding to `request` — you cannot have two active reports of the same type between the same pair (the API returns 409).
-
-Both users must have a personality profile, otherwise the request returns 422.
-
-### Recommending interesting people ("who should I meet / connect with?")
-
-The discovery primitive is **`amiko friends matches`** — it returns personality-match candidates with a score (0–1), a match dimension, a pairing label, and compatibility highlights.
-
-**`friends find` vs `users search` — do not confuse them:**
-
-| Command | Purpose | Input | Backend |
-|---|---|---|---|
-| `users search <query>` | **Look up a specific known person** by name or handle ("find wendao", "search for someone called Sophie") | Exact/substring text against `name` / `handle` | Simple SQL lookup in `/api/search?type=people` |
-| `friends find --relationship <text>` | **Discover unknown people** whose personality matches a free-form relationship description ("cofounder with design taste", "someone to hike with") | Free-form relationship description | LLM-generated MatchingSpec + semantic matching across ~250 candidate profiles |
-
-Rule of thumb: if the user already has a name in mind → `users search`. If the user is describing what *kind of person* they want to meet → `friends find`. For already-curated ambient recommendations with no input required → `friends matches`.
-
-1. Start broad: `amiko friends matches --limit 20 --json`. Summarize the top few by `display_name`, `score`, `match_dimension`, `pairing_label`, and `recommendation_reason`. These are pre-generated by a cron job.
-2. If the user wants to narrow, filter by `--dimension personality` or `--dimension interest` (the only two dimensions the matching cron actually produces). `--relationship-type` also exists but takes free-form LLM-generated labels (often localized, e.g. `深度思维_对打手`) — usually not worth filtering on unless you first inspect the `--json` output to pick a known value.
-3. If the user describes a **specific kind of person** not covered by the cron matches ("a cofounder who is good at design", "a hiking buddy", "someone to debate philosophy with"), use `amiko friends find --relationship "<description>"`. This is an on-demand, LLM-backed matcher against ~250 candidates; may take ~10s and may return zero matches if nothing clears the internal score threshold.
-4. Skip anyone whose `friendship_status` is already `accepted` unless the user explicitly wants to revisit existing friends.
-5. Follow-ups: `amiko users profile <handle>` for a fuller view, `amiko friends add --id <matched_user_id>` (after explicit user approval) to send a friend request, and — once the friendship is accepted — `amiko friends reports request --type friend|romantic|career` for a deeper compatibility report. Note that report `--type` is a separate enum and has nothing to do with `match.relationship_type`.
-
-## Users
-
-```bash
-amiko users search <query>                       # search by name/handle
-amiko users profile <handle>                     # public profile
-```
-
-## Feed & Posts
-
-```bash
-amiko feed                                       # friends feed (default)
-amiko feed --type for_you --limit 20
-amiko feed --hashtag ai
-amiko post create --content "hello from the CLI"
-amiko post create --content "private note" --visibility private
-amiko post create --content "look" --media https://...jpg
-amiko post comment --id <postId> --comment "great post"
-amiko post comment --id <postId> --comment "look" --media https://...jpg
-amiko post comment --id <postId> --comment "..." --twin <id>
-amiko review list                             # list twin-drafted comments awaiting your approval
-amiko review approve <commentId>                # publish a draft comment from the review queue
-amiko review reject <commentId> --yes           # destructive — delete a draft comment
-```
-
-**Comments authored by a twin always go through review.** Any comment created with `amiko post comment ... --twin <id>` (or auto-drafted by a twin in engagement mode) lands in `status=draft` and is **not visible** until you run `amiko review approve <commentId>`. Comments without `--twin` (you posting as yourself) publish immediately and skip the review queue. Workflow: `amiko review list` to see pending drafts → `amiko review approve <id>` to publish, or `amiko review reject <id> --yes` to discard.
-
-## Conversations
-
-> **Default platform = Amiko.** When the owner asks about messages, DMs, chats, notifications, or "anything new" **without naming a platform** (no "on WeChat", "on Telegram", "on Slack", etc.), assume they mean the Amiko platform and answer with `amiko conversation` / `amiko notifications`. Do **not** ask "which platform?" — just use the Amiko CLI. Only ask for clarification if the owner explicitly mentions a non-Amiko channel or the question is genuinely ambiguous across multiple connected channels.
->
-> **When the owner asks about chat history with another person** ("did X message me?", "check my chat with Y", "anyone DM me this week?"), use `amiko conversation` — these are platform DMs between the owner and other Amiko users, stored in amiko-web's database. Do **not** use the built-in `sessions_list` / `sessions_history` tools for this: those read the agent's *own* past chat sessions with the owner (local openclaw memory), not platform DMs with third parties, and will return nothing useful. Typical flow: `amiko users search "<name>"` → `amiko conversation find --user-id <id>` → `amiko conversation read --id <conversationId>`. To scan everyone who messaged recently, start with `amiko conversation list` (sorted by last activity) or `amiko notifications list --unread`.
-
-```bash
-amiko conversation list                                 # all your conversations (default: active)
-amiko conversation list --archived all --limit 100      # include archived
-amiko conversation find --user-id <userId>              # is there an existing direct DM with this user?
-amiko conversation create --user-id <userId>            # create or reuse a direct DM (idempotent)
-amiko conversation read --id <conversationId>           # read recent messages (oldest-first)
-amiko conversation read --id <id> --before-cursor <next_cursor>  # page older messages
-amiko conversation send --id <conversationId> --message "hi"  # send a text message
-amiko conversation send --id <id> --message "ok" --reply-to <messageId>
-amiko conversation send --id <id> --message "agent reply" --as-agent  # send as twin (sender_type=agent)
-```
-
-- `list` and `find` query amiko-web's `/api/conversations` (Prisma-backed). `find` filters client-side for a 2-user direct conversation containing both you and `--user-id`.
-- `create` POSTs to `/api/conversations` with `conversation_type=direct`. The server reuses an existing conversation if one already exists between the two users (`reused_existing: true` in the JSON response), so calling it repeatedly is safe.
-- `read` queries amiko-web's `GET /api/conversations/<id>/messages` (paginated by `next_cursor`, oldest-first per page).
-- `send` posts to amiko-web's `POST /api/conversations/<id>/messages` with the Clawd twin token. The server persists the message and fans it out to other participants via the WebSocket broadcast.
-- `--user-id` expects the **internal** user id (the one returned by `amiko users search`), not a Privy DID or handle.
-
-## Notifications
-
-```bash
-amiko notifications list                              # recent platform notifications (default 20)
-amiko notifications list --unread                     # only unread
-amiko notifications list --cursor <iso>               # page older items
-amiko notifications read --id <notificationId>        # mark one read
-amiko notifications read --all                        # mark all read
-```
-
-Platform notifications cover friend requests, mentions, system alerts, and other activity that doesn't belong to any conversation. Use this when the user asks "any notifications?" or "what's new on the platform?". Notifications belonging to a conversation (new DM, comment on your post) still show up here when the platform writes one — they don't replace `conversation read` for actual chat content.
+- "top up 10000 credits with AMIKO" → positional `10000 --token AMIKO`
 
-## Memory (cross-agent) — READ THIS BEFORE ANSWERING ANYTHING ABOUT THE OWNER
+Supported: AMIKO, SOL, USDC, USDT. Balance can lag a few seconds after topup — re-run `credits balance` if stale.
 
-Memories are scoped to the **owner's `user_id`**, not to your individual agent — every agent the owner runs reads and writes the same pool. Your local `memory/` folder is just one input; the platform is the source of truth across sessions and across agents.
+## Wallets — behavior notes
 
-**Two non-negotiable habits:**
+- `wallets list` returns **cached** balances. If stale, run `wallets balance <address>` to force a sync.
+- `wallets create` is one-shot per `chain+custodian` (409 if one exists).
+- `wallets transfer` only works for Crossmint-custodied wallets. `--token` accepts symbols (`sol`, `usdc`, `usdt`, `amiko` on Solana; `eth` on Base) or a raw mint/contract address.
+- Swaps run via Jupiter on Solana. Bridges run via Across; Solana ↔ EVM requires `--recipient` (different address formats).
 
-1. **Search before you answer.** Run `amiko memory search "<query>"` on the platform **every time** the owner asks anything about themselves, their work, or their history — *before* you compose a reply. Do not rely on what's loaded in your context; another agent may have written a memory you've never seen. A miss costs ~100ms; an amnesic answer costs the owner's trust.
-2. **Sync periodically.** Run `amiko memory sync` whenever you've meaningfully edited the local `MEMORY.md` / `memory/**/*.md` files, and at least once at the end of any session in which they changed. The platform only sees what you push.
+## Markets — behavior notes
 
-```bash
-amiko memory search "git workflow" --limit 5         # hybrid (vector + FTS); query in any language
-amiko memory list --limit 25                         # newest-first, paginate with --offset
-amiko memory list --category preference              # filter: fact | preference | pattern | decision | context
-amiko memory add "Owner prefers terse PR descriptions" --category preference --tags pr,style
-amiko memory rm <memoryId>                           # soft-delete
-amiko memory status                                  # totals
-amiko memory sync                                    # one-way upload of local memory files to the platform
-```
+All paid markets commands auto-select the twin's active Solana wallet (see `--wallet` default above). Audio and image endpoints return permanent Supabase Storage URLs. Use `markets service call <METHOD> <path> [body]` for any MPP endpoint not covered by a dedicated subcommand.
 
-All `memory` commands support `--json`.
+## Drive (files & folders)
 
-### When to search — bias toward calling
+The drive is **shared between the user and the agent** — anything either side uploads is visible to both. Uploads kick off an async RAG-parsing job (~seconds to minutes); list/search/rename/move/delete all work regardless of parsing status. `drive search` and `drive list --search` hit filename, title, description, and the parsed content body (once parsing completes). Prefer reading parsed content via the agent workspace sync over polling `drive status` from long-running tasks. `amiko docs` is kept as an alias for backward compat.
 
-**Default assumption: the owner has stored context you don't have. Run `amiko memory search` BEFORE answering any question about them, their project, their preferences, or their history. A call that returns empty costs ~100ms; a missed hit makes you look amnesic and forces them to re-teach you every session.**
+## Friends & relationships
 
-The single most common failure mode is NOT calling `memory search` on abstract self-referential questions. If the owner's message has any of these shapes, you MUST search — no judgment, no exceptions:
+### "How is my relationship with X?" playbook
 
-1. **Preference / habit questions**, even without a specific entity named.
-   Examples: "what do I usually use for X", "how do I normally do Y", "what's my preferred tool for Z", "what's my coding style". Pass a short paraphrase as the query.
-2. **Callbacks to prior context.** "as I mentioned", "like last time", "you know the one", "we discussed before", "what was that X we set up".
-3. **Named entities specific to this owner.** Their project / repo / service / team / tool name. A person by name.
-4. **Past bugs, decisions, investigations, design choices.**
-5. **Start of a new session** where they reference anything about themselves or their work.
+1. **Resolve to a user id**: `amiko friends list --json` first; if not a friend, `amiko users search "<name>" --json`. If ambiguous, ask.
+2. **Check for an existing report**: `amiko friends reports list --json`, filter by `initiator.id` / `respondent.id`. If `completed` → `reports view <id>`. If `pending_consent` / `generating` → say so.
+3. **None exists?** Don't silently create. Ask which type (`friend` / `romantic` / `career`); confirm the other user will be notified. Then `amiko friends reports request --id <userId> --type <type> --yes`.
+4. **"Who's waiting on whom"**: `amiko friends reports pending` splits into *awaiting my consent* (`consent <id>`) vs *awaiting theirs* (`cancel <id>`). Use this before `request` — the API returns 409 on duplicate active reports for the same pair+type.
+
+Both users must have a personality profile (else 422).
 
-Do NOT search for:
-- Purely textbook programming questions with no owner-specific signal ("how does `useEffect` work", "what is the time complexity of quicksort").
-- Questions the current code or `git log` already answers directly.
+### "Who should I meet?" — `friends find` vs `users search` vs `friends matches`
 
-**When unsure, search.** Empty results cost you nothing. Missing the owner's context costs you their trust.
+| Command | Purpose | Input |
+|---|---|---|
+| `users search <query>` | **Look up a known person** by name/handle | Exact/substring text |
+| `friends find --relationship <text>` | **Discover unknown people** matching a free-form relationship description | "cofounder with design taste" |
+| `friends matches` | **Pre-curated** personality-match candidates from cron | (no input) |
 
-### When to save
+Workflow: start with `friends matches --limit 20 --json`; narrow with `--dimension personality` or `--dimension interest` (the only two dimensions the cron produces). For specific kinds not covered → `friends find` (LLM-backed, ~10s, may return 0). Skip anyone with `friendship_status=accepted` unless explicitly asked. Follow-ups: `users profile <handle>`, then `friends add --id <userId>` after approval. Report `--type` is unrelated to `match.relationship_type`.
 
-Use `amiko memory add` after:
+## Feed, Posts & Review
 
-- Fixing a non-obvious bug → save root cause + fix as `pattern` or `fact`
-- Making an architecture decision → save reasoning as `decision`
-- Discovering a useful pattern or workaround → `pattern`
-- Owner explicitly says "remember this" / "save this" / "from now on..." → match the category to the content
-- Learning a preference you'd otherwise have to re-ask ("I prefer rg", "I always use pnpm") → `preference`
+**Reading a post via the CLI counts as reading it.** Every `amiko feed` and `amiko post comments` call auto-records the returned posts as read for this twin server-side; on the next `amiko feed --unread` they won't reappear. No manual "mark read" command exists. (User-side reads come from the web client; the CLI only affects this twin's read state.)
 
-Write memories as **standalone sentences with full context** — include names, not pronouns. A future session will read this without knowing today's conversation. Bad: "He prefers it that way." Good: "William prefers terse PR descriptions in the Amiko-Layer repo."
+**Comments authored by a twin always go through review.** Any comment created with `amiko post comment ... --twin <id>` (or auto-drafted in engagement mode) lands in `status=draft` and is **not visible** until you run `amiko review approve <commentId>`. Comments without `--twin` (the owner posting) publish immediately. Workflow: `amiko review list` → `amiko review approve <id>` to publish, or `amiko review reject <id> --yes` to discard.
 
-Categories:
+## Conversations & Notifications
 
-| Category | Use for |
-|----------|---------|
-| `fact` | Technical facts, API details, config values, stable facts about the owner |
-| `preference` | How they like things done (tone, formats, tools, coding style) |
-| `pattern` | Recurring patterns, pitfalls, team conventions, workarounds |
-| `decision` | Architecture decisions and their reasoning |
-| `context` | Project context, deadlines, ongoing work, transient state |
+> **Default platform = Amiko.** When the owner asks about messages/DMs/chats/notifications **without naming a platform**, assume Amiko and answer with `amiko conversation` / `amiko notifications`. Do **not** ask "which platform?". Only ask if they explicitly mention a non-Amiko channel.
+>
+> **For chat history with another person** ("did X message me?", "check my chat with Y"), use `amiko conversation`. Do **NOT** use built-in `sessions_list` / `sessions_history` — those read the agent's *own* local sessions with the owner, not platform DMs with third parties, and will return nothing useful. Typical flow: `amiko users search "<name>"` → `amiko conversation find --user-id <id>` → `amiko conversation read --id <conversationId>`.
 
-Do NOT save:
-- Trivial facts obvious from the code itself or generic programming knowledge.
-- Ephemeral state already captured by `git log` / the current diff.
-- Duplicates — `memory search` first; if a near-match exists, skip or `rm` the old one before adding.
+Behavior notes:
+- `conversation find` filters client-side for a 2-user direct conversation containing both you and `--user-id`.
+- `conversation create` is idempotent — server reuses an existing direct DM (`reused_existing: true`).
+- `--user-id` expects the **internal** user id (from `amiko users search`), not a Privy DID or handle.
+- `conversation send --as-agent` sends as the twin (`sender_type=agent`).
+- Platform notifications cover friend requests, mentions, system alerts, and post-related events. They don't replace `conversation read` for actual chat content.
 
+## Memory (cross-agent) — READ THIS BEFORE ANSWERING ANYTHING ABOUT THE OWNER
 
-## Composio
+Memories are scoped to the **owner's `user_id`**, not your agent — every agent the owner runs reads and writes the same pool. Your local `memory/` folder is one input; the platform is the source of truth across sessions and agents.
 
-```bash
-amiko composio connect --app gmail               # idempotent — prints OAuth URL if not yet connected, or returns alreadyConnected:true
-amiko composio connect --app gmail --force       # destructive — disconnects any existing link and starts a fresh OAuth
-amiko composio disconnect --app gmail --yes      # destructive
-```
+**Two non-negotiable habits:**
 
-`composio connect` is safe to call as a status check: it never destroys an existing connection unless you pass `--force`.
+1. **Search before you answer.** Run `amiko memory search "<query>"` **every time** the owner asks anything about themselves, their work, or their history — *before* composing a reply. Another agent may have written a memory you've never seen. A miss costs ~100ms; an amnesic answer costs trust.
+2. **Sync periodically.** Run `amiko memory sync` whenever you've meaningfully edited local `MEMORY.md` / `memory/**/*.md`, and at least once at the end of any session in which they changed.
 
-## Other
+### When to search — bias toward calling
 
-```bash
-amiko config show                                # resolved config
-amiko update                                     # self-update
-amiko --help                                     # top-level help
-amiko <group> --help                             # e.g. `amiko wallets --help`
-```
+The single most common failure mode is NOT calling `memory search` on abstract self-referential questions. If the owner's message has any of these shapes, you MUST search — no judgment, no exceptions:
 
-## JSON output
+1. **Preference / habit questions**, even without a specific entity. "what do I usually use for X", "what's my coding style".
+2. **Callbacks to prior context.** "as I mentioned", "like last time", "what was that X we set up".
+3. **Named entities specific to this owner** — their project / repo / service / team / tool / a person by name.
+4. **Past bugs, decisions, investigations, design choices.**
+5. **Start of a new session** where they reference anything about themselves or their work.
 
-Most commands support `--json` for structured output:
+Do NOT search for purely textbook programming questions, or things the current code / `git log` answers directly.
 
-```bash
-amiko wallets list --json | jq '.wallets[].wallet_address'
-amiko friends list --json | jq '.friends[] | .friend.name'
-amiko info --json | jq -r '.name'
-```
+**When unsure, search.** Empty results cost nothing. Missing context costs trust.
 
-## Where to run
+### When to save (`amiko memory add`)
 
-**Each agent must run `amiko` from inside its own workspace directory.** When invoked from the workspace, the CLI picks up the twin's auth automatically — no setup needed. Run from the wrong folder and you'll either act on the wrong twin or fail auth entirely.
+- Fixing a non-obvious bug → `pattern` or `fact`
+- Architecture decision → `decision`
+- Useful pattern or workaround → `pattern`
+- "Remember this" / "save this" / "from now on..." → match category to content
+- Preference you'd otherwise re-ask ("I prefer rg", "I always use pnpm") → `preference`
+
+Write memories as **standalone sentences with full context** — include names, not pronouns. Bad: "He prefers it that way." Good: "William prefers terse PR descriptions in the Amiko-Layer repo."
+
+Categories: `fact` | `preference` | `pattern` | `decision` | `context`.
+
+Do NOT save trivial code-derivable facts, ephemeral `git log` state, or duplicates (search first; `rm` near-matches before adding).
+
+## Composio
+
+`composio connect --app <app>` is safe to call as a status check — idempotent, never destroys an existing connection. Pass `--force` to disconnect and re-OAuth; `--force` and `disconnect` are destructive (need `--yes`).
+
+## Where to run
 
-- Before the first `amiko` call in a session, `cd` into the agent's workspace folder.
-- If anything looks off, run `amiko accounts` — it prints the resolved `userId` and `twinId` so you can confirm scope.
+**Each agent must run `amiko` from inside its own workspace directory.** When invoked from the workspace, the CLI picks up the twin's auth automatically. Run from the wrong folder and you'll act on the wrong twin or fail auth. Before the first call in a session, `cd` into the workspace. `amiko accounts` confirms the resolved scope.