@gobi-ai/cli 0.7.2 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -4,19 +4,20 @@
     "name": "gobi-ai"
   },
   "description": "Claude Code plugin for the Gobi collaborative knowledge platform CLI",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "plugins": [
     {
       "name": "gobi",
       "description": "Manage the Gobi collaborative knowledge platform from the command line. Search and ask brains, publish brain documents, create threads, manage sessions.",
-      "version": "0.7.1",
+      "version": "0.7.3",
       "author": {
         "name": "gobi-ai"
       },
       "homepage": "https://github.com/gobi-ai/gobi-cli",
       "source": "./",
       "skills": [
-        "./skills/gobi"
+        "./skills/gobi-cli",
+        "./skills/gobi-homepage"
       ],
       "commands": "./commands"
     }

package/.claude-plugin/plugin.json

@@ -1,13 +1,14 @@
 {
   "name": "gobi",
   "description": "Manage the Gobi collaborative knowledge platform from the command line",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "author": {
     "name": "gobi-ai"
   },
   "homepage": "https://github.com/gobi-ai/gobi-cli",
   "skills": [
-    "./skills/gobi"
+    "./skills/gobi-cli",
+    "./skills/gobi-homepage"
   ],
   "commands": "./commands"
 }

package/dist/commands/media.js

@@ -0,0 +1,379 @@
+import { apiGet, apiPost } from "../client.js";
+import { BASE_URL, POLL_MAX_DURATION_MS } from "../constants.js";
+import { getValidToken } from "../auth/manager.js";
+import { ApiError } from "../errors.js";
+import { isJsonMode, jsonOut, unwrapResp } from "./utils.js";
+// ── Polling helper ──
+async function pollStatus(path, terminalStates, intervalMs = 3000) {
+    const start = Date.now();
+    while (Date.now() - start < POLL_MAX_DURATION_MS) {
+        const resp = (await apiGet(path));
+        const data = unwrapResp(resp);
+        const status = data.status || "";
+        if (terminalStates.includes(status))
+            return data;
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    throw new Error(`Polling timed out after ${POLL_MAX_DURATION_MS / 1000}s`);
+}
+export function registerMediaCommand(program) {
+    const media = program
+        .command("media")
+        .description("Media generation commands (videos, images).");
+    // ════════════════════════════════════════════════════════════════════
+    //  Upload
+    // ════════════════════════════════════════════════════════════════════
+    media
+        .command("upload-init")
+        .description("Get a presigned upload URL for a media file.")
+        .requiredOption("--file-name <fileName>", "Name of the file to upload")
+        .requiredOption("--content-type <contentType>", "MIME type (e.g. image/png, video/mp4)")
+        .option("--file-size <fileSize>", "File size in bytes")
+        .action(async (opts) => {
+        const body = {
+            fileName: opts.fileName,
+            contentType: opts.contentType,
+        };
+        if (opts.fileSize)
+            body.fileSize = parseInt(opts.fileSize, 10);
+        const resp = (await apiPost("/media-gen/media/initialize", body));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Upload initialized!\n` +
+            `  Media ID:   ${data.mediaId}\n` +
+            `  Upload URL: ${data.uploadUrl}\n\n` +
+            `PUT your file to the upload URL, then run:\n` +
+            `  gobi media upload-finalize --media-id ${data.mediaId}`);
+    });
+    media
+        .command("upload-finalize")
+        .description("Confirm that a media upload is complete.")
+        .requiredOption("--media-id <mediaId>", "Media ID from upload-init")
+        .action(async (opts) => {
+        const resp = (await apiPost("/media-gen/media/finalize", {
+            mediaId: opts.mediaId,
+        }));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Upload finalized for media ${opts.mediaId}.`);
+    });
+    // ════════════════════════════════════════════════════════════════════
+    //  Avatars & Voices
+    // ════════════════════════════════════════════════════════════════════
+    media
+        .command("avatars")
+        .description("List available avatars.")
+        .action(async () => {
+        const resp = (await apiGet("/media-gen/avatars"));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        if (!Array.isArray(data) || data.length === 0) {
+            console.log("No avatars available.");
+            return;
+        }
+        console.log("Available avatars:");
+        for (const a of data) {
+            console.log(`  - ${a.id || a.avatarId}: ${a.name || "(unnamed)"}`);
+        }
+    });
+    media
+        .command("voices")
+        .description("List available voices.")
+        .action(async () => {
+        const resp = (await apiGet("/media-gen/voices"));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        if (!Array.isArray(data) || data.length === 0) {
+            console.log("No voices available.");
+            return;
+        }
+        console.log("Available voices:");
+        for (const v of data) {
+            console.log(`  - ${v.id || v.voiceId}: ${v.name || "(unnamed)"}`);
+        }
+    });
+    // ════════════════════════════════════════════════════════════════════
+    //  Videos
+    // ════════════════════════════════════════════════════════════════════
+    media
+        .command("video-create")
+        .description("Create an avatar video generation job.")
+        .requiredOption("--name <name>", "Name for the video")
+        .requiredOption("--avatar-id <avatarId>", "Avatar to use")
+        .requiredOption("--voice-id <voiceId>", "Voice to use")
+        .requiredOption("--script <script>", "Script for the avatar to read")
+        .option("--background-media-id <backgroundMediaId>", "Background media ID (from upload)")
+        .option("--wait", "Poll until generation completes")
+        .action(async (opts) => {
+        const body = {
+            name: opts.name,
+            avatarId: opts.avatarId,
+            voiceId: opts.voiceId,
+            script: opts.script,
+        };
+        if (opts.backgroundMediaId)
+            body.backgroundMediaId = opts.backgroundMediaId;
+        const resp = (await apiPost("/media-gen/videos", body));
+        let data = unwrapResp(resp);
+        const videoId = data.id || data.videoId;
+        if (opts.wait && videoId) {
+            console.log(`Video ${videoId} queued — polling for completion…`);
+            data = await pollStatus(`/media-gen/videos/${videoId}/status`, ["inference_complete", "inference_failed"]);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        const status = data.status || "queued";
+        console.log(`Video created!\n` +
+            `  ID:     ${videoId}\n` +
+            `  Status: ${status}`);
+        if (status === "inference_complete") {
+            console.log(`  Download: gobi media video-download ${videoId}`);
+        }
+    });
+    media
+        .command("video-list")
+        .description("List all videos.")
+        .action(async () => {
+        const resp = (await apiGet("/media-gen/videos"));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        if (!Array.isArray(data) || data.length === 0) {
+            console.log("No videos found.");
+            return;
+        }
+        console.log("Videos:");
+        for (const v of data) {
+            console.log(`  - [${v.id}] status: ${v.status || "unknown"}, created: ${v.createdAt || "?"}`);
+        }
+    });
+    media
+        .command("video-get <id>")
+        .description("Get video metadata.")
+        .action(async (id) => {
+        const resp = (await apiGet(`/media-gen/videos/${id}`));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Video ${id}:`);
+        for (const [k, v] of Object.entries(data)) {
+            console.log(`  ${k}: ${typeof v === "object" ? JSON.stringify(v) : v}`);
+        }
+    });
+    media
+        .command("video-status <id>")
+        .description("Poll video generation status.")
+        .option("--wait", "Poll until a terminal state is reached")
+        .action(async (id, opts) => {
+        if (opts.wait) {
+            const data = await pollStatus(`/media-gen/videos/${id}/status`, ["inference_complete", "inference_failed"]);
+            if (isJsonMode(media)) {
+                jsonOut(data);
+                return;
+            }
+            console.log(`Video ${id} — status: ${data.status}`);
+            return;
+        }
+        const resp = (await apiGet(`/media-gen/videos/${id}/status`));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Video ${id} — status: ${data.status || "unknown"}`);
+    });
+    media
+        .command("video-download <id>")
+        .description("Get the download URL for a completed video.")
+        .action(async (id) => {
+        const token = await getValidToken();
+        const url = `${BASE_URL}/media-gen/videos/${id}/download`;
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${token}` },
+            redirect: "manual",
+        });
+        // If the server redirects, extract the Location header
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get("location") || "";
+            if (isJsonMode(media)) {
+                jsonOut({ downloadUrl: location });
+                return;
+            }
+            console.log(`Download URL for video ${id}:\n  ${location}`);
+            return;
+        }
+        if (!res.ok) {
+            const text = (await res.text()) || "(no body)";
+            throw new ApiError(res.status, `/media-gen/videos/${id}/download`, text);
+        }
+        // If it returns JSON instead of a redirect
+        const resp = (await res.json());
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Download URL for video ${id}:\n  ${data.url || data.downloadUrl || JSON.stringify(data)}`);
+    });
+    // ════════════════════════════════════════════════════════════════════
+    //  Images
+    // ════════════════════════════════════════════════════════════════════
+    media
+        .command("image-generate")
+        .description("Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4")
+        .requiredOption("--prompt <prompt>", "Text prompt for image generation")
+        .requiredOption("--name <name>", "Name for the generated image")
+        .option("--type <type>", "Generation type: image (default), thumbnail (YouTube-optimized), asset (logo/product)")
+        .option("--aspect-ratio <aspectRatio>", "Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4)")
+        .option("--negative-prompt <negativePrompt>", "Negative prompt")
+        .option("--seed <seed>", "Random seed for reproducibility")
+        .option("--reference-media-id <referenceMediaId>", "Reference image media ID")
+        .option("--wait", "Poll until generation completes")
+        .action(async (opts) => {
+        const body = {
+            prompt: opts.prompt,
+            name: opts.name,
+        };
+        if (opts.type)
+            body.type = opts.type;
+        if (opts.aspectRatio)
+            body.aspectRatio = opts.aspectRatio;
+        if (opts.negativePrompt)
+            body.negativePrompt = opts.negativePrompt;
+        if (opts.seed)
+            body.seed = parseInt(opts.seed, 10);
+        if (opts.referenceMediaId)
+            body.referenceMediaId = opts.referenceMediaId;
+        const resp = (await apiPost("/media-gen/images/generate", body));
+        let data = unwrapResp(resp);
+        const jobId = data.jobId || data.id;
+        if (opts.wait && jobId) {
+            console.log(`Image job ${jobId} queued — polling for completion…`);
+            data = await pollStatus(`/media-gen/images/${jobId}`, [
+                "completed",
+                "failed",
+                "inference_complete",
+                "inference_failed",
+            ]);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Image generation started!\n` +
+            `  Job ID: ${jobId}\n` +
+            `  Status: ${data.status || "queued"}\n` +
+            `  Check:  gobi media image-status ${jobId}`);
+    });
+    media
+        .command("image-edit")
+        .description("Edit an existing image with a prompt (image-to-image).")
+        .requiredOption("--media-id <mediaId>", "Source image media ID")
+        .requiredOption("--prompt <prompt>", "Edit instruction")
+        .requiredOption("--name <name>", "Name for the edited image")
+        .option("--wait", "Poll until generation completes")
+        .action(async (opts) => {
+        const resp = (await apiPost("/media-gen/images/edit", {
+            mediaId: opts.mediaId,
+            prompt: opts.prompt,
+            name: opts.name,
+        }));
+        let data = unwrapResp(resp);
+        const jobId = data.jobId || data.id;
+        if (opts.wait && jobId) {
+            console.log(`Image edit job ${jobId} — polling for completion…`);
+            data = await pollStatus(`/media-gen/images/${jobId}`, [
+                "completed",
+                "failed",
+                "inference_complete",
+                "inference_failed",
+            ]);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Image edit started!\n` +
+            `  Job ID: ${jobId}\n` +
+            `  Status: ${data.status || "queued"}`);
+    });
+    media
+        .command("image-inpaint")
+        .description("Inpaint an image region using a mask.")
+        .requiredOption("--media-id <mediaId>", "Source image media ID")
+        .requiredOption("--mask-media-id <maskMediaId>", "Mask image media ID")
+        .requiredOption("--prompt <prompt>", "Inpainting prompt")
+        .requiredOption("--name <name>", "Name for the inpainted image")
+        .option("--wait", "Poll until generation completes")
+        .action(async (opts) => {
+        const resp = (await apiPost("/media-gen/images/inpaint", {
+            mediaId: opts.mediaId,
+            maskMediaId: opts.maskMediaId,
+            prompt: opts.prompt,
+            name: opts.name,
+        }));
+        let data = unwrapResp(resp);
+        const jobId = data.jobId || data.id;
+        if (opts.wait && jobId) {
+            console.log(`Inpaint job ${jobId} — polling for completion…`);
+            data = await pollStatus(`/media-gen/images/${jobId}`, [
+                "completed",
+                "failed",
+                "inference_complete",
+                "inference_failed",
+            ]);
+        }
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Inpainting started!\n` +
+            `  Job ID: ${jobId}\n` +
+            `  Status: ${data.status || "queued"}`);
+    });
+    media
+        .command("image-status <jobId>")
+        .description("Check image generation job status.")
+        .option("--wait", "Poll until a terminal state is reached")
+        .action(async (jobId, opts) => {
+        if (opts.wait) {
+            const data = await pollStatus(`/media-gen/images/${jobId}`, [
+                "completed",
+                "failed",
+                "inference_complete",
+                "inference_failed",
+            ]);
+            if (isJsonMode(media)) {
+                jsonOut(data);
+                return;
+            }
+            console.log(`Image job ${jobId} — status: ${data.status}`);
+            return;
+        }
+        const resp = (await apiGet(`/media-gen/images/${jobId}`));
+        const data = unwrapResp(resp);
+        if (isJsonMode(media)) {
+            jsonOut(data);
+            return;
+        }
+        console.log(`Image job ${jobId} — status: ${data.status || "unknown"}`);
+    });
+}

package/dist/main.js

@@ -10,6 +10,7 @@ import { registerSessionsCommand } from "./commands/sessions.js";
 import { registerSenseCommand } from "./commands/sense.js";
 import { registerSyncCommand } from "./commands/sync.js";
 import { registerUpdateCommand } from "./commands/update.js";
+import { registerMediaCommand } from "./commands/media.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 const SKIP_BANNER_COMMANDS = new Set(["auth", "init", "update"]);
@@ -36,6 +37,7 @@ export async function cli() {
     registerSenseCommand(program);
     registerSyncCommand(program);
     registerUpdateCommand(program);
+    registerMediaCommand(program);
     // Propagate helpWidth to all subcommands
     const helpWidth = process.stdout.columns || 200;
     for (const cmd of program.commands) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobi-ai/cli",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "CLI client for the Gobi collaborative knowledge platform",
   "license": "MIT",
   "type": "module",

package/skills/{gobi → gobi-cli}/SKILL.md

@@ -6,16 +6,16 @@ description: >-
   the outside world — checking what's happening, reading and writing threads,
   and collaborating with others.
   Use when the user wants to interact with Gobi spaces, vaults, brains, threads,
-  sessions, or brain updates.
+  sessions, brain updates, or media generation (images, videos, thumbnails).
 allowed-tools: Bash(gobi:*)
 metadata:
   author: gobi-ai
-  version: "0.7.1"
+  version: "0.7.3"
 ---
 
 # gobi-cli
 
-A CLI client for the Gobi collaborative knowledge platform (v0.7.1).
+A CLI client for the Gobi collaborative knowledge platform (v0.7.3).
 
 ## Prerequisites
 
@@ -100,6 +100,14 @@ gobi auth status
 
 `gobi brain` commands manage your vault's brain: search across all spaces, ask brains questions, and publish/unpublish your BRAIN.md. Public brains are accessible at `https://gobispace.com/@{vaultSlug}`.
 
+## Gobi Media — Image & Video Generation
+
+`gobi media` commands generate images, thumbnails, assets, and avatar videos using AI. All generation is async: create a job, poll for status (or use `--wait`), then retrieve the result.
+
+- **Images**: Generate from text prompts, edit existing images, or inpaint with masks. Supports types: `image` (default), `thumbnail` (YouTube-optimized), `asset` (logo/product).
+- **Videos**: Create avatar videos with script narration. Choose an avatar and voice, provide a script, and generate a talking-head video.
+- **Upload**: Upload custom media files (backgrounds, references, masks) via presigned S3 URLs for use in generation.
+
 ## Gobi Session — Conversations
 
 `gobi session` commands manage your conversations: list, read, and reply to sessions.
@@ -169,6 +177,20 @@ Note: `--space-slug` is not available on other `brain` subcommands or on `sessio
   - `gobi session get` — Get a session and its messages (paginated).
   - `gobi session list` — List all sessions you are part of, sorted by most recent activity.
   - `gobi session reply` — Send a human reply to a session you are a member of.
+- `gobi media` — Media generation commands (images, videos).
+  - `gobi media upload-init` — Get a presigned upload URL for a media file. Requires `--file-name`, `--content-type`, `--file-size`.
+  - `gobi media upload-finalize` — Confirm that a media upload is complete.
+  - `gobi media avatars` — List available avatars.
+  - `gobi media voices` — List available voices.
+  - `gobi media video-create` — Create an avatar video generation job. Requires `--name`, `--avatar-id`, `--voice-id`, `--script`.
+  - `gobi media video-list` — List all videos.
+  - `gobi media video-get <id>` — Get video metadata.
+  - `gobi media video-status <id>` — Poll video generation status. Use `--wait` to block until complete.
+  - `gobi media video-download <id>` — Get the download URL for a completed video.
+  - `gobi media image-generate` — Generate an image from a text prompt. Requires `--prompt`, `--name`. Optional: `--type` (image|thumbnail|asset), `--aspect-ratio`, `--negative-prompt`, `--seed`, `--reference-media-id`. Use `--wait` to block until complete.
+  - `gobi media image-edit` — Edit an existing image with a prompt. Requires `--media-id`, `--prompt`, `--name`.
+  - `gobi media image-inpaint` — Inpaint an image region using a mask. Requires `--media-id`, `--mask-media-id`, `--prompt`, `--name`.
+  - `gobi media image-status <jobId>` — Check image generation job status. Use `--wait` to block until complete.
 - `gobi sense` — Sense commands (activities, transcriptions).
   - `gobi sense activities` — Fetch activity records within a time range.
   - `gobi sense transcriptions` — Fetch transcription records within a time range.
@@ -182,6 +204,7 @@ Note: `--space-slug` is not available on other `brain` subcommands or on `sessio
 - [gobi space](references/space.md)
 - [gobi brain](references/brain.md)
 - [gobi session](references/session.md)
+- [gobi media](references/media.md)
 - [gobi sense](references/sense.md)
 - [gobi sync](references/sync.md)
 - [gobi update](references/update.md)
@@ -196,6 +219,7 @@ gobi auth --help
 gobi space --help
 gobi brain --help
 gobi session --help
+gobi media --help
 gobi sense --help
 gobi sync --help
 ```

package/skills/gobi-cli/references/media.md

@@ -0,0 +1,215 @@
+# gobi media
+
+```
+Usage: gobi media [options] [command]
+
+Media generation commands (videos, images).
+
+Options:
+  -h, --help                      display help for command
+
+Commands:
+  upload-init [options]           Get a presigned upload URL for a media file.
+  upload-finalize [options]       Confirm that a media upload is complete.
+  avatars                         List available avatars.
+  voices                          List available voices.
+  video-create [options]          Create an avatar video generation job.
+  video-list                      List all videos.
+  video-get <id>                  Get video metadata.
+  video-status [options] <id>     Poll video generation status.
+  video-download <id>             Get the download URL for a completed video.
+  image-generate [options]        Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
+  image-edit [options]            Edit an existing image with a prompt (image-to-image).
+  image-inpaint [options]         Inpaint an image region using a mask.
+  image-status [options] <jobId>  Check image generation job status.
+  help [command]                  display help for command
+```
+
+## Async Workflow
+
+Video and image generation are async:
+1. Call the create/generate endpoint — receive a job ID
+2. Poll with `--wait` or manually check status until terminal state
+3. Retrieve or download the result
+
+## Media Upload
+
+Upload media files (images, videos) for use as backgrounds, references, or masks:
+
+1. `gobi media upload-init` — get a presigned S3 upload URL
+2. PUT your file to the returned `uploadUrl`
+3. `gobi media upload-finalize` — confirm the upload
+
+The returned `mediaId` can then be used with `--background-media-id`, `--reference-media-id`, `--media-id`, or `--mask-media-id`.
+
+## upload-init
+
+```
+Usage: gobi media upload-init [options]
+
+Get a presigned upload URL for a media file.
+
+Options:
+  --file-name <fileName>        Name of the file to upload
+  --content-type <contentType>  MIME type (e.g. image/png, video/mp4)
+  --file-size <fileSize>        File size in bytes
+  -h, --help                    display help for command
+```
+
+## upload-finalize
+
+```
+Usage: gobi media upload-finalize [options]
+
+Confirm that a media upload is complete.
+
+Options:
+  --media-id <mediaId>  Media ID from upload-init
+  -h, --help            display help for command
+```
+
+## avatars
+
+```
+Usage: gobi media avatars [options]
+
+List available avatars.
+
+Options:
+  -h, --help  display help for command
+```
+
+## voices
+
+```
+Usage: gobi media voices [options]
+
+List available voices.
+
+Options:
+  -h, --help  display help for command
+```
+
+## video-create
+
+```
+Usage: gobi media video-create [options]
+
+Create an avatar video generation job.
+
+Options:
+  --name <name>                              Name for the video
+  --avatar-id <avatarId>                     Avatar to use
+  --voice-id <voiceId>                       Voice to use
+  --script <script>                          Script for the avatar to read
+  --background-media-id <backgroundMediaId>  Background media ID (from upload)
+  --wait                                     Poll until generation completes
+  -h, --help                                 display help for command
+```
+
+## video-list
+
+```
+Usage: gobi media video-list [options]
+
+List all videos.
+
+Options:
+  -h, --help  display help for command
+```
+
+## video-get
+
+```
+Usage: gobi media video-get [options] <id>
+
+Get video metadata.
+
+Options:
+  -h, --help  display help for command
+```
+
+## video-status
+
+```
+Usage: gobi media video-status [options] <id>
+
+Poll video generation status.
+
+Options:
+  --wait      Poll until a terminal state is reached
+  -h, --help  display help for command
+```
+
+## video-download
+
+```
+Usage: gobi media video-download [options] <id>
+
+Get the download URL for a completed video.
+
+Options:
+  -h, --help  display help for command
+```
+
+## image-generate
+
+```
+Usage: gobi media image-generate [options]
+
+Generate an image from a text prompt. Types: image (default), thumbnail (YouTube-optimized), asset (logo/product). Aspect ratios: 1:1, 16:9, 9:16, 4:3, 3:4
+
+Options:
+  --prompt <prompt>                        Text prompt for image generation
+  --name <name>                            Name for the generated image
+  --type <type>                            Generation type: image (default), thumbnail (YouTube-optimized), asset (logo/product)
+  --aspect-ratio <aspectRatio>             Aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4)
+  --negative-prompt <negativePrompt>       Negative prompt
+  --seed <seed>                            Random seed for reproducibility
+  --reference-media-id <referenceMediaId>  Reference image media ID
+  --wait                                   Poll until generation completes
+  -h, --help                               display help for command
+```
+
+## image-edit
+
+```
+Usage: gobi media image-edit [options]
+
+Edit an existing image with a prompt (image-to-image).
+
+Options:
+  --media-id <mediaId>  Source image media ID
+  --prompt <prompt>     Edit instruction
+  --name <name>         Name for the edited image
+  --wait                Poll until generation completes
+  -h, --help            display help for command
+```
+
+## image-inpaint
+
+```
+Usage: gobi media image-inpaint [options]
+
+Inpaint an image region using a mask.
+
+Options:
+  --media-id <mediaId>           Source image media ID
+  --mask-media-id <maskMediaId>  Mask image media ID
+  --prompt <prompt>              Inpainting prompt
+  --name <name>                  Name for the inpainted image
+  --wait                         Poll until generation completes
+  -h, --help                     display help for command
+```
+
+## image-status
+
+```
+Usage: gobi media image-status [options] <jobId>
+
+Check image generation job status.
+
+Options:
+  --wait      Poll until a terminal state is reached
+  -h, --help  display help for command
+```

package/skills/gobi-homepage/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: gobi-homepage
+description: >-
+  Developer reference for building Gobi Homepages — custom HTML pages hosted on
+  webdrive and served as a vault's public homepage at gobispace.com/@{vaultSlug}.
+  Use when a developer wants to build or modify a vault homepage.
+---
+
+# Gobi Homepage Developer Guide
+
+A **Gobi Homepage** is a custom HTML page hosted on a vault's webdrive and served as its public homepage at `https://gobispace.com/@{vaultSlug}`. Gobi injects a `window.gobi` bridge before any scripts run, giving the homepage access to vault data, files, brain updates, and chat.
+
+> **Sandbox:** The homepage runs in a sandboxed iframe with `origin: null`. Direct `fetch()` / `XMLHttpRequest` calls are blocked by CORS. All data access must go through `window.gobi.*`.
+
+---
+
+## Setup
+
+1. Create an HTML file in the vault (e.g. `app/home.html`) and upload:
+   ```bash
+   gobi sync
+   ```
+2. Set `homepage` in BRAIN.md (homepage property):
+   - `homepage: "[[app/home.html]]"` — Gobi sidebars visible alongside the homepage
+   - `homepage: "[[app/home.html?nav=false]]"` — full-screen, no Gobi chrome
+
+---
+
+## window.gobi Reference
+
+`gobi.vault` is **synchronous** — available at the top of any `<script>`, no `DOMContentLoaded` needed. All other methods return `Promise`.
+
+### gobi.vault
+
+```js
+const { vaultId, title, description, thumbnailPath, tags,
+        ownerName, ownerProfilePictureUrl, webdriveUrl } = gobi.vault;
+
+// Profile picture: https://d16t3dioqz0xo9.cloudfront.net/{thumbnailPath}@{W}x{H}.webp
+```
+
+### Error Handling
+
+All async `gobi.*` methods throw on failure. Wrap calls in `try/catch` to handle errors gracefully.
+
+```js
+try {
+  const text = await gobi.readFile('data/config.json');
+} catch (err) {
+  console.error('gobi API error:', err.message);
+  // err.message contains a human-readable description of what went wrong
+}
+```
+
+### Files
+
+```js
+const text  = await gobi.readFile('data/config.json');   // → string (throws if not found)
+const items = await gobi.listFiles('images');             // → [{ name, type: 'file'|'folder' }]
+const exists = await gobi.fileExists('README.md');        // → boolean
+
+// Direct URL for any vault file (public, no auth required).
+// Encode each segment separately — encodeURIComponent(path) would encode slashes and break the URL.
+function getFileUrl(path) {
+  const enc = path.split('/').map(encodeURIComponent).join('/');
+  return `${gobi.vault.webdriveUrl}/api/v1/file/raw/${gobi.vault.vaultId}/${enc}`;
+}
+```
+
+### Brain Updates
+
+```js
+const { data: updates, pagination } = await gobi.listBrainUpdates({ limit: 10, cursor: null });
+// updates[i] → {
+//   id: 42,
+//   title: 'New insights',
+//   content: '## ...',   // markdown — MAY contain ![[file|width]] wiki image embeds
+//   topics: [{ id: 3, name: 'AI', slug: 'ai' }],
+//   createdAt: '2025-03-01T12:00:00Z'
+// }
+// pagination → { hasMore: true, nextCursor: 'abc...' }
+
+// ⚠️ Always call resolveWikiImages() on content before rendering — see Rendering Markdown below.
+for (const u of updates) {
+  el.innerHTML += marked.parse(resolveWikiImages(u.content));
+}
+
+// Pagination — load the next page using the cursor
+if (pagination.hasMore) {
+  const { data: moreUpdates, pagination: nextPage } =
+    await gobi.listBrainUpdates({ limit: 10, cursor: pagination.nextCursor });
+}
+```
+
+### Chat (login required)
+
+`getSessions`, `loadMessages`, and `sendMessage` require the visitor to be logged in. `getSessions` returns an empty array when not logged in — **but also when logged in with no prior sessions**. Don't use it as a definitive auth check.
+
+```js
+// Redirect to login, returning here after. Use window.top — the applet is inside an iframe.
+function redirectToLogin() {
+  window.top.location.href =
+    `https://gobispace.com/login?redirect_uri=${encodeURIComponent(window.location.href)}`;
+}
+
+// Session list — newest first
+const { data: sessions, pagination } = await gobi.getSessions({ limit: 20, cursor: null });
+// sessions[i] → { sessionId: 'sess_abc', messageCount: 12, lastMessageAt: '2025-03-30T...' }
+
+// Message history
+const { messages, hasMore, nextCursor } = await gobi.loadMessages('sess_abc', { limit: 20, cursor: null });
+// messages[i] → { id, role: 'human'|'assistant', content, createdAt }
+
+// Send a message and stream the response.
+// New session: pass crypto.randomUUID() — the backend creates it lazily on first message sent.
+//
+// Signatures:
+//   sendMessage(sessionId, text, onDelta)           → Promise<{ content }>
+//   sendMessage(sessionId, text, options, onDelta)  → Promise<{ content }>
+//
+// options.context tells the AI what the user is looking at:
+//   { brainUpdateId?: number, brainUpdateTitle?: string, filePath?: string }
+
+let reply = '';
+await gobi.sendMessage(sessionId, 'Hello', (delta) => {
+  reply += delta;
+  renderReply(reply);
+});
+
+// With context
+await gobi.sendMessage(sessionId, 'Tell me more', {
+  context: { brainUpdateId: 42, brainUpdateTitle: 'New insights' }
+}, (delta) => { reply += delta; renderReply(reply); });
+
+await gobi.sendMessage(sessionId, 'Explain this', {
+  context: { filePath: 'notes/research.md' }
+}, (delta) => { reply += delta; renderReply(reply); });
+
+// Start a fresh session
+sessionId = crypto.randomUUID();
+```
+
+---
+
+## Rendering Markdown
+
+Brain update `content` and any markdown read via `readFile` may contain Obsidian-style wiki embeds (`![[path|width]]`). Resolve them before passing to a renderer.
+
+The examples below use [marked](https://cdn.jsdelivr.net/npm/marked/marked.min.js) — include it in your `<head>`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+```
+
+```js
+// Define once, reuses getFileUrl from the Files section.
+function resolveWikiImages(md) {
+  return md.replace(/!\[\[([^\]|]+)(?:\|(\d+))?\]\]/g, (_, p, w) => {
+    const url = getFileUrl(p.trim());
+    return w ? `<img src="${url}" width="${w}" style="max-width:100%">`
+             : `<img src="${url}" style="max-width:100%">`;
+  });
+}
+
+const html = marked.parse(resolveWikiImages(update.content));
+```
+
+---
+
+## Complete Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: system-ui, sans-serif; max-width: 720px; margin: 0 auto; padding: 24px; }
+    .update { margin-bottom: 32px; }
+    .update h2 { margin-bottom: 8px; }
+    .update img { border-radius: 8px; }
+    #chat { margin-top: 40px; border-top: 1px solid #ddd; padding-top: 24px; }
+    .message { margin-bottom: 12px; padding: 8px 12px; border-radius: 8px; }
+    .message[data-role="human"] { background: #e8f0fe; }
+    .message[data-role="assistant"] { background: #f1f3f4; }
+    #chat-input { display: flex; gap: 8px; margin-top: 16px; }
+    #chat-input input { flex: 1; padding: 8px; border: 1px solid #ccc; border-radius: 6px; }
+    #chat-input button { padding: 8px 16px; border: none; border-radius: 6px; background: #1a73e8; color: #fff; cursor: pointer; }
+    .login-prompt { text-align: center; color: #666; }
+    .login-prompt a { color: #1a73e8; cursor: pointer; text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div id="updates"></div>
+  <div id="chat">
+    <div id="messages"></div>
+    <div id="chat-input">
+      <input id="input" type="text" placeholder="Ask a question…" />
+      <button onclick="onSend()">Send</button>
+    </div>
+  </div>
+
+  <script>
+    document.title = gobi.vault.title || 'Brain';
+
+    // ── Helpers ──────────────────────────────────────
+
+    function getFileUrl(path) {
+      const enc = path.split('/').map(encodeURIComponent).join('/');
+      return `${gobi.vault.webdriveUrl}/api/v1/file/raw/${gobi.vault.vaultId}/${enc}`;
+    }
+
+    function resolveWikiImages(md) {
+      return md.replace(/!\[\[([^\]|]+)(?:\|(\d+))?\]\]/g, (_, p, w) => {
+        const url = getFileUrl(p.trim());
+        return w ? `<img src="${url}" width="${w}" style="max-width:100%">`
+                 : `<img src="${url}" style="max-width:100%">`;
+      });
+    }
+
+    function escapeHtml(s) {
+      const el = document.createElement('div');
+      el.textContent = s;
+      return el.innerHTML;
+    }
+
+    function redirectToLogin() {
+      window.top.location.href =
+        `https://gobispace.com/login?redirect_uri=${encodeURIComponent(window.location.href)}`;
+    }
+
+    // ── Brain updates ────────────────────────────────
+
+    async function loadUpdates() {
+      try {
+        const { data: updates } = await gobi.listBrainUpdates({ limit: 5 });
+        const el = document.getElementById('updates');
+        for (const u of updates) {
+          const div = document.createElement('div');
+          div.className = 'update';
+          div.innerHTML = `<h2>${escapeHtml(u.title)}</h2>${marked.parse(resolveWikiImages(u.content))}`;
+          el.appendChild(div);
+        }
+      } catch (err) {
+        console.error('Failed to load brain updates:', err);
+      }
+    }
+
+    // ── Chat ─────────────────────────────────────────
+
+    let sessionId = null;
+    const messagesEl = document.getElementById('messages');
+
+    function renderMessage(role, html) {
+      const div = document.createElement('div');
+      div.className = 'message';
+      div.dataset.role = role;
+      div.innerHTML = html;
+      messagesEl.appendChild(div);
+      return div;
+    }
+
+    async function initChat() {
+      try {
+        const { data: sessions } = await gobi.getSessions({ limit: 1 });
+        if (!sessions.length) {
+          messagesEl.innerHTML =
+            '<p class="login-prompt">No chat sessions yet. <a onclick="redirectToLogin()">Log in</a> to start chatting.</p>';
+          return;
+        }
+        sessionId = sessions[0].sessionId;
+        const { messages } = await gobi.loadMessages(sessionId, { limit: 20 });
+        for (const m of messages) {
+          renderMessage(m.role, m.role === 'assistant' ? marked.parse(m.content) : escapeHtml(m.content));
+        }
+      } catch (err) {
+        console.error('Failed to init chat:', err);
+      }
+    }
+
+    async function onSend() {
+      const input = document.getElementById('input');
+      const text = input.value.trim();
+      if (!text) return;
+      input.value = '';
+
+      if (!sessionId) sessionId = crypto.randomUUID();
+      renderMessage('human', escapeHtml(text));
+
+      const replyEl = renderMessage('assistant', '…');
+      let reply = '';
+      try {
+        await gobi.sendMessage(sessionId, text, (delta) => {
+          reply += delta;
+          replyEl.innerHTML = marked.parse(reply);
+        });
+      } catch (err) {
+        replyEl.textContent = 'Error: ' + err.message;
+      }
+    }
+
+    // Submit on Enter
+    document.getElementById('input').addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') onSend();
+    });
+
+    // ─────────────────────────────────────────────────
+
+    loadUpdates();
+    initChat();
+  </script>
+</body>
+</html>
+```