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

package/README.md

@@ -1,4 +1,4 @@
-# @heyamiko/amiko-cli (v0.10.1-beta.2)
+# @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,13 @@ 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`.

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.2",
+  "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

@@ -23,6 +23,9 @@ Call your shell tool (your runtime calls it `bash`, `shell`, `run`, or similar)
 | "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` |
@@ -36,7 +39,7 @@ The CLI is installed globally and is pre-authenticated when you're inside your w
 
 ## Command groups
 
-Discover everything via `amiko --help`. Groups: `markets` (paid MPP services), `wallets`, `credits`, `twin`, `docs`, `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`.
+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
 
@@ -83,6 +86,10 @@ Supported: AMIKO, SOL, USDC, USDT. Balance can lag a few seconds after topup —
 
 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.
 
+## Drive (files & folders)
+
+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.
+
 ## Friends & relationships
 
 ### "How is my relationship with X?" playbook