@gobi-ai/cli 0.5.0 → 0.6.1

package/dist/attachments.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "fs";
+import { join, extname } from "path";
+import { WEBDRIVE_BASE_URL } from "./constants.js";
+export function extractWikiLinks(content) {
+    const seen = new Set();
+    const results = [];
+    for (const match of content.matchAll(/\[\[([^\]]+)\]\]/g)) {
+        const link = match[1].trim();
+        if (!seen.has(link)) {
+            seen.add(link);
+            results.push(link);
+        }
+    }
+    return results;
+}
+export async function uploadAttachments(vaultSlug, links, token) {
+    for (const link of links) {
+        let localPath = join(process.cwd(), link);
+        if (!existsSync(localPath)) {
+            if (!extname(link)) {
+                localPath = join(process.cwd(), link + ".md");
+            }
+            if (!existsSync(localPath)) {
+                console.warn(`Warning: Skipping [[${link}]]: not found locally`);
+                continue;
+            }
+        }
+        const filePath = extname(link) ? link : link + ".md";
+        console.log(`Uploading [[${link}]]...`);
+        const content = readFileSync(localPath);
+        const url = `${WEBDRIVE_BASE_URL}/api/v1/vaults/${vaultSlug}/files/${filePath}`;
+        const res = await fetch(url, {
+            method: "PUT",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/octet-stream",
+            },
+            body: content,
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to upload [[${link}]]: HTTP ${res.status}: ${(await res.text()) || "(no body)"}`);
+        }
+        console.log(`Uploaded [[${link}]]`);
+    }
+}

package/dist/commands/brain.js

@@ -5,6 +5,7 @@ import { WEBDRIVE_BASE_URL } from "../constants.js";
 import { getValidToken } from "../auth/manager.js";
 import { getVaultSlug } from "./init.js";
 import { isJsonMode, jsonOut, resolveVaultSlug, unwrapResp } from "./utils.js";
+import { extractWikiLinks, uploadAttachments } from "../attachments.js";
 export function registerBrainCommand(program) {
     const brain = program
         .command("brain")
@@ -191,8 +192,14 @@ export function registerBrainCommand(program) {
         .option("--vault-slug <vaultSlug>", "Vault slug (overrides .gobi/settings.yaml)")
         .requiredOption("--title <title>", "Title of the update")
         .requiredOption("--content <content>", "Update content (markdown supported)")
+        .option("--auto-attachments", "Upload wiki-linked [[files]] to webdrive before posting")
         .action(async (opts) => {
         const vaultSlug = resolveVaultSlug(opts);
+        if (opts.autoAttachments) {
+            const token = await getValidToken();
+            const links = extractWikiLinks(opts.content);
+            await uploadAttachments(vaultSlug, links, token);
+        }
         const resp = (await apiPost(`/brain-updates/vault/${vaultSlug}`, {
             title: opts.title,
             content: opts.content,

package/dist/commands/sense.js

@@ -0,0 +1,87 @@
+import { apiGet } from "../client.js";
+import { isJsonMode, jsonOut } from "./utils.js";
+export function registerSenseCommand(program) {
+    const sense = program
+        .command("sense")
+        .description("Sense commands (activities, transcriptions).");
+    // ── Activities ──
+    sense
+        .command("activities")
+        .description("Fetch activity records within a time range.")
+        .requiredOption("--timezone <tz>", "IANA timezone (e.g. America/New_York)")
+        .option("--start-time <iso>", "Start of time range (ISO 8601, inclusive)")
+        .option("--end-time <iso>", "End of time range (ISO 8601, inclusive); requires --start-time")
+        .action(async (opts) => {
+        if (opts.endTime && !opts.startTime) {
+            throw new Error("--end-time requires --start-time.");
+        }
+        const params = { timezone: opts.timezone };
+        if (opts.startTime)
+            params.startTime = opts.startTime;
+        if (opts.endTime)
+            params.endTime = opts.endTime;
+        const resp = (await apiGet("/app/activities", params));
+        const activities = (resp.activities || []);
+        const pagination = (resp.pagination || {});
+        const latestTimestamp = resp.latestTimestamp;
+        if (isJsonMode(sense)) {
+            jsonOut({ activities, pagination, latestTimestamp });
+            return;
+        }
+        if (!activities.length) {
+            console.log("No activities found.");
+            if (latestTimestamp)
+                console.log(`Latest data available: ${latestTimestamp}`);
+            return;
+        }
+        const lines = activities.map((a) => {
+            const endStr = a.end_time ? ` → ${a.end_time}` : "";
+            return `- [${a.device_id}] ${a.category}: ${a.details} (${a.start_time}${endStr})`;
+        });
+        console.log(`Activities (${activities.length} items):\n` + lines.join("\n"));
+        if (latestTimestamp)
+            console.log(`Latest data available: ${latestTimestamp}`);
+    });
+    // ── Transcriptions ──
+    sense
+        .command("transcriptions")
+        .description("Fetch transcription records within a time range.")
+        .requiredOption("--timezone <tz>", "IANA timezone (e.g. America/New_York)")
+        .option("--start-time <iso>", "Start of time range (ISO 8601, inclusive)")
+        .option("--end-time <iso>", "End of time range (ISO 8601, inclusive); requires --start-time")
+        .action(async (opts) => {
+        if (opts.endTime && !opts.startTime) {
+            throw new Error("--end-time requires --start-time.");
+        }
+        const params = { timezone: opts.timezone };
+        if (opts.startTime)
+            params.startTime = opts.startTime;
+        if (opts.endTime)
+            params.endTime = opts.endTime;
+        const resp = (await apiGet("/app/transcriptions", params));
+        const transcriptions = (resp.transcriptions || []);
+        const pagination = (resp.pagination || {});
+        const latestTimestamp = resp.latestTimestamp;
+        if (isJsonMode(sense)) {
+            jsonOut({ transcriptions, pagination, latestTimestamp });
+            return;
+        }
+        if (!transcriptions.length) {
+            console.log("No transcriptions found.");
+            if (latestTimestamp)
+                console.log(`Latest data available: ${latestTimestamp}`);
+            return;
+        }
+        const lines = [];
+        for (const t of transcriptions) {
+            lines.push(`- [${t.device_id}] ${t.created_at}`);
+            const turns = (t.turns || []);
+            for (const turn of turns) {
+                lines.push(`    Speaker ${turn.speaker} (${turn.timestamp}): ${turn.text}`);
+            }
+        }
+        console.log(`Transcriptions (${transcriptions.length} items):\n` + lines.join("\n"));
+        if (latestTimestamp)
+            console.log(`Latest data available: ${latestTimestamp}`);
+    });
+}

package/dist/commands/space.js

@@ -1,7 +1,9 @@
 import { readFileSync } from "fs";
 import { apiGet, apiPost, apiPatch, apiDelete } from "../client.js";
 import { selectSpace, writeSpaceSetting } from "./init.js";
-import { isJsonMode, jsonOut, resolveSpaceSlug, unwrapResp } from "./utils.js";
+import { isJsonMode, jsonOut, resolveSpaceSlug, resolveVaultSlug, unwrapResp } from "./utils.js";
+import { extractWikiLinks, uploadAttachments } from "../attachments.js";
+import { getValidToken } from "../auth/manager.js";
 function readContent(value) {
     if (value === "-")
         return readFileSync("/dev/stdin", "utf8");
@@ -144,11 +146,20 @@ export function registerSpaceCommand(program) {
         .description("Create a thread in a space.")
         .requiredOption("--title <title>", "Title of the thread")
         .requiredOption("--content <content>", "Thread content (markdown supported)")
+        .option("--auto-attachments", "Upload wiki-linked [[files]] to webdrive before posting")
+        .option("--vault-slug <vaultSlug>", "Vault slug for attachment uploads (overrides .gobi/settings.yaml)")
         .action(async (opts) => {
+        const content = readContent(opts.content);
+        if (opts.autoAttachments) {
+            const vaultSlug = resolveVaultSlug(opts);
+            const token = await getValidToken();
+            const links = extractWikiLinks(content);
+            await uploadAttachments(vaultSlug, links, token);
+        }
         const spaceSlug = resolveSpaceSlug(space);
         const resp = (await apiPost(`/spaces/${spaceSlug}/threads`, {
             title: opts.title,
-            content: readContent(opts.content),
+            content,
         }));
         const thread = unwrapResp(resp);
         if (isJsonMode(space)) {

package/dist/main.js

@@ -7,6 +7,7 @@ import { registerInitCommand, printContext } from "./commands/init.js";
 import { registerSpaceCommand } from "./commands/space.js";
 import { registerBrainCommand } from "./commands/brain.js";
 import { registerSessionsCommand } from "./commands/sessions.js";
+import { registerSenseCommand } from "./commands/sense.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 const SKIP_BANNER_COMMANDS = new Set(["auth", "init"]);
@@ -30,6 +31,7 @@ export async function cli() {
     registerSpaceCommand(program);
     registerBrainCommand(program);
     registerSessionsCommand(program);
+    registerSenseCommand(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.5.0",
+  "version": "0.6.1",
   "description": "CLI client for the Gobi collaborative knowledge platform",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,8 @@
   },
   "files": [
     "dist",
-    "!dist/**/*.test.js"
+    "!dist/**/*.test.js",
+    "skills"
   ],
   "bin": {
     "gobi": "./dist/index.js"

package/skills/gobi/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: gobi-cli
+description: >-
+  Manage the Gobi collaborative knowledge platform from the command line.
+  Gobi space is the user's main channel for social interactions and engaging with
+  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.
+allowed-tools: Bash(gobi:*)
+metadata:
+  author: gobi-ai
+  version: "0.6.1"
+---
+
+# gobi-cli
+
+A CLI client for the Gobi collaborative knowledge platform (v0.6.1).
+
+## Prerequisites
+
+Verify the CLI is installed:
+
+```bash
+gobi --version
+```
+
+If not installed:
+
+```bash
+npm install -g @gobi-ai/cli
+```
+
+Or via Homebrew:
+
+```bash
+brew tap gobi-ai/tap && brew install gobi
+```
+
+## Key Concepts
+
+- **Space**: A shared space for a group or community. A logged-in user can be a member of one or more spaces. A space contains threads, sessions, brain updates, and connected vaults.
+- **Vault**: A filetree storage of information and knowledge. A local directory becomes a vault when it contains `.gobi/settings.yaml` with a vault slug and a space slug. Each vault is identified by a slug (e.g. `brave-path-zr962w`).
+- **Brain**: Another name for a vault when referring to its AI-searchable knowledge. You can search brains, ask them questions, and publish a `BRAIN.md` document to configure your vault's brain.
+
+## First-Time Setup
+
+The CLI requires three setup steps: authentication, vault initialization, and space selection.
+
+### Step 1: Initialize (Login + Vault)
+
+```bash
+gobi init
+```
+
+This is an **interactive** command that:
+1. Logs in automatically if not already authenticated (opens a browser URL for Google OAuth)
+2. Prompts the user to select an existing vault or create a new one
+3. Writes `.gobi/settings.yaml` in the current directory with the chosen vault slug
+4. Creates a `BRAIN.md` file if one doesn't exist
+
+### Step 2: Select a Space
+
+```bash
+gobi space warp
+```
+
+This is an **interactive** command that prompts the user to select a space from their available spaces, then saves it to `.gobi/settings.yaml`.
+
+After both steps, `.gobi/settings.yaml` will contain:
+```yaml
+vaultSlug: brave-path-zr962w
+selectedSpaceSlug: cmds
+```
+
+### Standalone Login
+
+If the user only needs to log in (without vault setup):
+
+```bash
+gobi auth login
+```
+
+Check auth status anytime:
+
+```bash
+gobi auth status
+```
+
+**Important for agents**: Before running any `space` command, check if `.gobi/settings.yaml` exists in the current directory with both `vaultSlug` and `selectedSpaceSlug`. If the vault is missing, guide the user through `gobi init`. If only the space is missing, guide the user through `gobi space warp`. These commands require user input (interactive prompts), so the agent cannot run them silently.
+
+## Gobi Space — Community Channel
+
+`gobi space` is the main interface for interacting with the user's Gobi community. When the user asks about what's happening, what others are discussing, or wants to engage with their community — use `gobi space` commands. Think of it as the user's community feed and communication hub.
+
+- When the user wants to explore or catch up on what's happening in their space, invoke `/gobi:space-explore`.
+- When the user wants to share or post learnings from the current session, invoke `/gobi:space-share`.
+
+## Gobi Brain — Knowledge Management
+
+`gobi brain` commands manage your vault's brain: search across all spaces, ask brains questions, and publish/unpublish your BRAIN.md.
+
+## Gobi Session — Conversations
+
+`gobi session` commands manage your conversations: list, read, reply to, and update sessions.
+
+## Important: JSON Mode
+
+For programmatic/agent usage, always pass `--json` as a **global** option (before the subcommand) to get structured JSON output:
+
+```bash
+gobi --json space list-threads
+```
+
+or
+
+```bash
+gobi --json session list
+```
+
+JSON responses have the shape `{ "success": true, "data": ... }` on success or `{ "success": false, "error": "..." }` on failure.
+
+## Space Slug Override
+
+`gobi space` commands use the space from `.gobi/settings.yaml`. Override it with a parent-level flag:
+
+```bash
+gobi space --space-slug <slug> list-threads
+```
+
+For `gobi brain list-updates`, you can filter by space with a subcommand option:
+
+```bash
+gobi brain list-updates --space-slug <slug>
+```
+
+Note: `--space-slug` is not available on other `brain` subcommands or on `session` commands.
+
+## Available Commands
+
+- `gobi auth` — Authentication commands.
+  - `gobi auth login` — Log in to Gobi. Opens a browser URL for Google OAuth, then polls until authentication is complete.
+  - `gobi auth status` — Check whether you are currently authenticated with Gobi.
+  - `gobi auth logout` — Log out of Gobi and remove stored credentials.
+- `gobi init` — Log in (if needed) and select or create the vault for the current directory.
+- `gobi space` — Space commands (threads, replies).
+  - `gobi space list` — List spaces you are a member of.
+  - `gobi space warp` — Select the active space. Pass a slug to warp directly, or omit for interactive selection.
+  - `gobi space get-thread` — Get a thread and its replies (paginated).
+  - `gobi space list-threads` — List threads in a space (paginated).
+  - `gobi space create-thread` — Create a thread in a space.
+  - `gobi space edit-thread` — Edit a thread. You must be the author.
+  - `gobi space delete-thread` — Delete a thread. You must be the author.
+  - `gobi space create-reply` — Create a reply to a thread in a space.
+  - `gobi space edit-reply` — Edit a reply. You must be the author.
+  - `gobi space delete-reply` — Delete a reply. You must be the author.
+- `gobi brain` — Brain commands (search, ask, publish, unpublish, updates).
+  - `gobi brain search` — Search public brains by text and semantic similarity.
+  - `gobi brain ask` — Ask a brain a question. Creates a targeted session (1:1 conversation).
+  - `gobi brain publish` — Upload BRAIN.md to the vault root on webdrive. Triggers post-processing (brain sync, metadata update, Discord notification).
+  - `gobi brain unpublish` — Delete BRAIN.md from the vault on webdrive.
+  - `gobi brain list-updates` — List recent brain updates. Without --space-slug, lists all updates for you. With --space-slug, lists updates for that space. Use --mine to show only updates by you.
+  - `gobi brain post-update` — Post a brain update for a vault.
+  - `gobi brain edit-update` — Edit a published brain update. You must be the author.
+  - `gobi brain delete-update` — Delete a published brain update. You must be the author.
+- `gobi session` — Session commands (get, list, reply).
+  - `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.
+
+## Reference Documentation
+
+- [gobi auth](references/auth.md)
+- [gobi init](references/init.md)
+- [gobi space](references/space.md)
+- [gobi brain](references/brain.md)
+- [gobi session](references/session.md)
+
+## Discovering Options
+
+Run `--help` on any command for details:
+
+```bash
+gobi --help
+gobi auth --help
+gobi space --help
+gobi brain --help
+gobi session --help
+```
+
+## Configuration Files
+
+| Path | Description |
+|------|-------------|
+| `~/.gobi/credentials.json` | Stored authentication tokens (auto-managed) |
+| `.gobi/settings.yaml` | Per-project vault and space configuration |
+| `BRAIN.md` | Brain document with YAML frontmatter, published via `gobi brain publish` |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOBI_BASE_URL` | `https://backend.joingobi.com` | API server URL |
+| `GOBI_WEBDRIVE_BASE_URL` | `https://webdrive.joingobi.com` | File storage URL |

package/skills/gobi/SKILL.template.md

@@ -0,0 +1,172 @@
+---
+name: gobi-cli
+description: >-
+  Manage the Gobi collaborative knowledge platform from the command line.
+  Gobi space is the user's main channel for social interactions and engaging with
+  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.
+allowed-tools: Bash(gobi:*)
+metadata:
+  author: gobi-ai
+  version: "{{VERSION}}"
+---
+
+# gobi-cli
+
+A CLI client for the Gobi collaborative knowledge platform (v{{VERSION}}).
+
+## Prerequisites
+
+Verify the CLI is installed:
+
+```bash
+gobi --version
+```
+
+If not installed:
+
+```bash
+npm install -g @gobi-ai/cli
+```
+
+Or via Homebrew:
+
+```bash
+brew tap gobi-ai/tap && brew install gobi
+```
+
+## Key Concepts
+
+- **Space**: A shared space for a group or community. A logged-in user can be a member of one or more spaces. A space contains threads, sessions, brain updates, and connected vaults.
+- **Vault**: A filetree storage of information and knowledge. A local directory becomes a vault when it contains `.gobi/settings.yaml` with a vault slug and a space slug. Each vault is identified by a slug (e.g. `brave-path-zr962w`).
+- **Brain**: Another name for a vault when referring to its AI-searchable knowledge. You can search brains, ask them questions, and publish a `BRAIN.md` document to configure your vault's brain.
+
+## First-Time Setup
+
+The CLI requires three setup steps: authentication, vault initialization, and space selection.
+
+### Step 1: Initialize (Login + Vault)
+
+```bash
+gobi init
+```
+
+This is an **interactive** command that:
+1. Logs in automatically if not already authenticated (opens a browser URL for Google OAuth)
+2. Prompts the user to select an existing vault or create a new one
+3. Writes `.gobi/settings.yaml` in the current directory with the chosen vault slug
+4. Creates a `BRAIN.md` file if one doesn't exist
+
+### Step 2: Select a Space
+
+```bash
+gobi space warp
+```
+
+This is an **interactive** command that prompts the user to select a space from their available spaces, then saves it to `.gobi/settings.yaml`.
+
+After both steps, `.gobi/settings.yaml` will contain:
+```yaml
+vaultSlug: brave-path-zr962w
+selectedSpaceSlug: cmds
+```
+
+### Standalone Login
+
+If the user only needs to log in (without vault setup):
+
+```bash
+gobi auth login
+```
+
+Check auth status anytime:
+
+```bash
+gobi auth status
+```
+
+**Important for agents**: Before running any `space` command, check if `.gobi/settings.yaml` exists in the current directory with both `vaultSlug` and `selectedSpaceSlug`. If the vault is missing, guide the user through `gobi init`. If only the space is missing, guide the user through `gobi space warp`. These commands require user input (interactive prompts), so the agent cannot run them silently.
+
+## Gobi Space — Community Channel
+
+`gobi space` is the main interface for interacting with the user's Gobi community. When the user asks about what's happening, what others are discussing, or wants to engage with their community — use `gobi space` commands. Think of it as the user's community feed and communication hub.
+
+- When the user wants to explore or catch up on what's happening in their space, invoke `/gobi:space-explore`.
+- When the user wants to share or post learnings from the current session, invoke `/gobi:space-share`.
+
+## Gobi Brain — Knowledge Management
+
+`gobi brain` commands manage your vault's brain: search across all spaces, ask brains questions, and publish/unpublish your BRAIN.md.
+
+## Gobi Session — Conversations
+
+`gobi session` commands manage your conversations: list, read, reply to, and update sessions.
+
+## Important: JSON Mode
+
+For programmatic/agent usage, always pass `--json` as a **global** option (before the subcommand) to get structured JSON output:
+
+```bash
+gobi --json space list-threads
+```
+
+or
+
+```bash
+gobi --json session list
+```
+
+JSON responses have the shape `{ "success": true, "data": ... }` on success or `{ "success": false, "error": "..." }` on failure.
+
+## Space Slug Override
+
+`gobi space` commands use the space from `.gobi/settings.yaml`. Override it with a parent-level flag:
+
+```bash
+gobi space --space-slug <slug> list-threads
+```
+
+For `gobi brain list-updates`, you can filter by space with a subcommand option:
+
+```bash
+gobi brain list-updates --space-slug <slug>
+```
+
+Note: `--space-slug` is not available on other `brain` subcommands or on `session` commands.
+
+## Available Commands
+
+{{COMMANDS}}
+
+## Reference Documentation
+
+{{REFERENCE_TOC}}
+
+## Discovering Options
+
+Run `--help` on any command for details:
+
+```bash
+gobi --help
+gobi auth --help
+gobi space --help
+gobi brain --help
+gobi session --help
+```
+
+## Configuration Files
+
+| Path | Description |
+|------|-------------|
+| `~/.gobi/credentials.json` | Stored authentication tokens (auto-managed) |
+| `.gobi/settings.yaml` | Per-project vault and space configuration |
+| `BRAIN.md` | Brain document with YAML frontmatter, published via `gobi brain publish` |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GOBI_BASE_URL` | `https://backend.joingobi.com` | API server URL |
+| `GOBI_WEBDRIVE_BASE_URL` | `https://webdrive.joingobi.com` | File storage URL |

package/skills/gobi/references/auth.md

@@ -0,0 +1,49 @@
+# gobi auth
+
+```
+Usage: gobi auth [options] [command]
+
+Authentication commands.
+
+Options:
+  -h, --help      display help for command
+
+Commands:
+  login           Log in to Gobi. Opens a browser URL for Google OAuth, then polls until authentication is complete.
+  status          Check whether you are currently authenticated with Gobi.
+  logout          Log out of Gobi and remove stored credentials.
+  help [command]  display help for command
+```
+
+## login
+
+```
+Usage: gobi auth login [options]
+
+Log in to Gobi. Opens a browser URL for Google OAuth, then polls until authentication is complete.
+
+Options:
+  -h, --help  display help for command
+```
+
+## status
+
+```
+Usage: gobi auth status [options]
+
+Check whether you are currently authenticated with Gobi.
+
+Options:
+  -h, --help  display help for command
+```
+
+## logout
+
+```
+Usage: gobi auth logout [options]
+
+Log out of Gobi and remove stored credentials.
+
+Options:
+  -h, --help  display help for command
+```

package/skills/gobi/references/brain.md

@@ -0,0 +1,126 @@
+# gobi brain
+
+```
+Usage: gobi brain [options] [command]
+
+Brain commands (search, ask, publish, unpublish, updates).
+
+Options:
+  -h, --help                        display help for command
+
+Commands:
+  search [options]                  Search public brains by text and semantic similarity.
+  ask [options]                     Ask a brain a question. Creates a targeted session (1:1 conversation).
+  publish                           Upload BRAIN.md to the vault root on webdrive. Triggers post-processing (brain sync, metadata update, Discord notification).
+  unpublish                         Delete BRAIN.md from the vault on webdrive.
+  list-updates [options]            List recent brain updates. Without --space-slug, lists all updates for you. With --space-slug, lists updates for that space. Use --mine to show only updates by
+                                    you.
+  post-update [options]             Post a brain update for a vault.
+  edit-update [options] <updateId>  Edit a published brain update. You must be the author.
+  delete-update <updateId>          Delete a published brain update. You must be the author.
+  help [command]                    display help for command
+```
+
+## search
+
+```
+Usage: gobi brain search [options]
+
+Search public brains by text and semantic similarity.
+
+Options:
+  --query <query>  Search query
+  -h, --help       display help for command
+```
+
+## ask
+
+```
+Usage: gobi brain ask [options]
+
+Ask a brain a question. Creates a targeted session (1:1 conversation).
+
+Options:
+  --vault-slug <vaultSlug>  Slug of the brain/vault to ask
+  --question <question>     The question to ask (markdown supported)
+  --rich-text <richText>    Rich-text JSON array (e.g. [{"type":"text","text":"hello"}])
+  --mode <mode>             Session mode: "auto" or "manual"
+  -h, --help                display help for command
+```
+
+## publish
+
+```
+Usage: gobi brain publish [options]
+
+Upload BRAIN.md to the vault root on webdrive. Triggers post-processing (brain sync, metadata update, Discord notification).
+
+Options:
+  -h, --help  display help for command
+```
+
+## unpublish
+
+```
+Usage: gobi brain unpublish [options]
+
+Delete BRAIN.md from the vault on webdrive.
+
+Options:
+  -h, --help  display help for command
+```
+
+## list-updates
+
+```
+Usage: gobi brain list-updates [options]
+
+List recent brain updates. Without --space-slug, lists all updates for you. With --space-slug, lists updates for that space. Use --mine to show only updates by you.
+
+Options:
+  --vault-slug <vaultSlug>  Vault slug (overrides .gobi/settings.yaml)
+  --space-slug <spaceSlug>  List updates for a space
+  --mine                    List only my own brain updates
+  --limit <number>          Items per page (default: "20")
+  --cursor <string>         Pagination cursor from previous response
+  -h, --help                display help for command
+```
+
+## post-update
+
+```
+Usage: gobi brain post-update [options]
+
+Post a brain update for a vault.
+
+Options:
+  --vault-slug <vaultSlug>  Vault slug (overrides .gobi/settings.yaml)
+  --title <title>           Title of the update
+  --content <content>       Update content (markdown supported)
+  --auto-attachments        Upload wiki-linked [[files]] to webdrive before posting
+  -h, --help                display help for command
+```
+
+## edit-update
+
+```
+Usage: gobi brain edit-update [options] <updateId>
+
+Edit a published brain update. You must be the author.
+
+Options:
+  --title <title>      New title for the update
+  --content <content>  New content for the update (markdown supported)
+  -h, --help           display help for command
+```
+
+## delete-update
+
+```
+Usage: gobi brain delete-update [options] <updateId>
+
+Delete a published brain update. You must be the author.
+
+Options:
+  -h, --help  display help for command
+```

package/skills/gobi/references/init.md

@@ -0,0 +1,10 @@
+# gobi init
+
+```
+Usage: gobi init [options]
+
+Log in (if needed) and select or create the vault for the current directory.
+
+Options:
+  -h, --help  display help for command
+```

package/skills/gobi/references/session.md

@@ -0,0 +1,55 @@
+# gobi session
+
+```
+Usage: gobi session [options] [command]
+
+Session commands (get, list, reply).
+
+Options:
+  -h, --help                   display help for command
+
+Commands:
+  get [options] <sessionId>    Get a session and its messages (paginated).
+  list [options]               List all sessions you are part of, sorted by most recent activity.
+  reply [options] <sessionId>  Send a human reply to a session you are a member of.
+  help [command]               display help for command
+```
+
+## get
+
+```
+Usage: gobi session get [options] <sessionId>
+
+Get a session and its messages (paginated).
+
+Options:
+  --limit <number>   Messages per page (default: "20")
+  --cursor <string>  Pagination cursor from previous response
+  -h, --help         display help for command
+```
+
+## list
+
+```
+Usage: gobi session list [options]
+
+List all sessions you are part of, sorted by most recent activity.
+
+Options:
+  --limit <number>   Items per page (default: "20")
+  --cursor <string>  Pagination cursor from previous response
+  -h, --help         display help for command
+```
+
+## reply
+
+```
+Usage: gobi session reply [options] <sessionId>
+
+Send a human reply to a session you are a member of.
+
+Options:
+  --content <content>     Reply content (markdown supported)
+  --rich-text <richText>  Rich-text JSON array (e.g. [{"type":"text","text":"hello"}])
+  -h, --help              display help for command
+```

package/skills/gobi/references/space.md

@@ -0,0 +1,146 @@
+# gobi space
+
+```
+Usage: gobi space [options] [command]
+
+Space commands (threads, replies).
+
+Options:
+  --space-slug <slug>                Space slug (overrides .gobi/settings.yaml)
+  -h, --help                         display help for command
+
+Commands:
+  list                               List spaces you are a member of.
+  warp [spaceSlug]                   Select the active space. Pass a slug to warp directly, or omit for interactive selection.
+  get-thread [options] <threadId>    Get a thread and its replies (paginated).
+  list-threads [options]             List threads in a space (paginated).
+  create-thread [options]            Create a thread in a space.
+  edit-thread [options] <threadId>   Edit a thread. You must be the author.
+  delete-thread <threadId>           Delete a thread. You must be the author.
+  create-reply [options] <threadId>  Create a reply to a thread in a space.
+  edit-reply [options] <replyId>     Edit a reply. You must be the author.
+  delete-reply <replyId>             Delete a reply. You must be the author.
+  help [command]                     display help for command
+```
+
+## list
+
+```
+Usage: gobi space list [options]
+
+List spaces you are a member of.
+
+Options:
+  -h, --help  display help for command
+```
+
+## warp
+
+```
+Usage: gobi space warp [options] [spaceSlug]
+
+Select the active space. Pass a slug to warp directly, or omit for interactive selection.
+
+Options:
+  -h, --help  display help for command
+```
+
+## get-thread
+
+```
+Usage: gobi space get-thread [options] <threadId>
+
+Get a thread and its replies (paginated).
+
+Options:
+  --limit <number>   Replies per page (default: "20")
+  --cursor <string>  Pagination cursor from previous response
+  -h, --help         display help for command
+```
+
+## list-threads
+
+```
+Usage: gobi space list-threads [options]
+
+List threads in a space (paginated).
+
+Options:
+  --limit <number>   Items per page (default: "20")
+  --cursor <string>  Pagination cursor from previous response
+  -h, --help         display help for command
+```
+
+## create-thread
+
+```
+Usage: gobi space create-thread [options]
+
+Create a thread in a space.
+
+Options:
+  --title <title>           Title of the thread
+  --content <content>       Thread content (markdown supported)
+  --auto-attachments        Upload wiki-linked [[files]] to webdrive before posting
+  --vault-slug <vaultSlug>  Vault slug for attachment uploads (overrides .gobi/settings.yaml)
+  -h, --help                display help for command
+```
+
+## edit-thread
+
+```
+Usage: gobi space edit-thread [options] <threadId>
+
+Edit a thread. You must be the author.
+
+Options:
+  --title <title>      New title for the thread
+  --content <content>  New content for the thread (markdown supported)
+  -h, --help           display help for command
+```
+
+## delete-thread
+
+```
+Usage: gobi space delete-thread [options] <threadId>
+
+Delete a thread. You must be the author.
+
+Options:
+  -h, --help  display help for command
+```
+
+## create-reply
+
+```
+Usage: gobi space create-reply [options] <threadId>
+
+Create a reply to a thread in a space.
+
+Options:
+  --content <content>  Reply content (markdown supported)
+  -h, --help           display help for command
+```
+
+## edit-reply
+
+```
+Usage: gobi space edit-reply [options] <replyId>
+
+Edit a reply. You must be the author.
+
+Options:
+  --content <content>  New content for the reply (markdown supported)
+  -h, --help           display help for command
+```
+
+## delete-reply
+
+```
+Usage: gobi space delete-reply [options] <replyId>
+
+Delete a reply. You must be the author.
+
+Options:
+  -h, --help  display help for command
+```

package/skills/gobi/scripts/generate-docs.ts

@@ -0,0 +1,199 @@
+import { execSync } from "node:child_process";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+  unlinkSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SKILL_DIR = join(__dirname, "..");
+const REFERENCES_DIR = join(SKILL_DIR, "references");
+const TEMPLATE_PATH = join(SKILL_DIR, "SKILL.template.md");
+const OUTPUT_PATH = join(SKILL_DIR, "SKILL.md");
+const PROJECT_ROOT = join(SKILL_DIR, "..", "..");
+// Read version from package.json
+const require = createRequire(import.meta.url);
+const { version } = require(join(PROJECT_ROOT, "package.json")) as {
+  version: string;
+};
+
+// Use the built dist/index.js so this works in CI without global install
+const GOBI_BIN = join(PROJECT_ROOT, "dist", "index.js");
+
+if (!existsSync(GOBI_BIN)) {
+  console.error(
+    "Error: dist/index.js not found. Run 'npm run build' first."
+  );
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function runHelp(args: string[]): string {
+  const cmd = `node ${GOBI_BIN} ${args.join(" ")} --help`;
+  return execSync(cmd, {
+    encoding: "utf-8",
+    env: { ...process.env, NO_COLOR: "1" },
+    timeout: 10_000,
+  }).trim();
+}
+
+interface CommandInfo {
+  name: string;
+  description: string;
+}
+
+/**
+ * Parse Commander.js help output to extract the Commands section.
+ * Commander format:
+ *   Commands:
+ *     name [options]  description
+ *     help [command]  display help for command
+ */
+function parseCommands(helpText: string): CommandInfo[] {
+  const commands: CommandInfo[] = [];
+  const lines = helpText.split("\n");
+  let inCommands = false;
+
+  for (const line of lines) {
+    if (line.trim() === "Commands:") {
+      inCommands = true;
+      continue;
+    }
+    if (inCommands) {
+      // Match: leading whitespace, command name, possible args, 2+ spaces, description
+      const match = line.match(/^\s{2,}(\S+)\s+.*?\s{2,}(.+)$/);
+      if (match) {
+        const [, name, desc] = match;
+        if (name !== "help") {
+          commands.push({ name, description: desc.trim() });
+        }
+      } else if (line.trim() === "") {
+        break;
+      } else if (commands.length > 0 && line.match(/^\s{10,}\S/)) {
+        // Continuation line of the previous command's wrapped description
+        commands[commands.length - 1].description += " " + line.trim();
+      }
+    }
+  }
+
+  return commands;
+}
+
+// ---------------------------------------------------------------------------
+// Generate reference docs
+// ---------------------------------------------------------------------------
+
+function generateReferenceDoc(
+  commandPath: string[],
+  helpText: string,
+  subcommands: { name: string; helpText: string }[]
+): string {
+  const lines: string[] = [];
+  const fullCommand = ["gobi", ...commandPath].join(" ");
+
+  lines.push(`# ${fullCommand}`);
+  lines.push("");
+  lines.push("```");
+  lines.push(helpText);
+  lines.push("```");
+
+  for (const sub of subcommands) {
+    lines.push("");
+    lines.push(`## ${sub.name}`);
+    lines.push("");
+    lines.push("```");
+    lines.push(sub.helpText);
+    lines.push("```");
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+// Ensure references directory exists
+if (!existsSync(REFERENCES_DIR)) {
+  mkdirSync(REFERENCES_DIR, { recursive: true });
+}
+
+// Clean existing generated reference files
+for (const file of readdirSync(REFERENCES_DIR)) {
+  if (file.endsWith(".md")) {
+    unlinkSync(join(REFERENCES_DIR, file));
+  }
+}
+
+// 1. Get top-level commands
+const topHelp = runHelp([]);
+const topCommands = parseCommands(topHelp);
+
+// 2. Generate reference files for each command group
+const referenceFiles: { name: string; path: string; title: string }[] = [];
+const commandLines: string[] = [];
+
+for (const cmd of topCommands) {
+  let cmdHelp: string;
+  try {
+    cmdHelp = runHelp([cmd.name]);
+  } catch {
+    // Leaf command with no subcommands — use top-level help
+    cmdHelp = `${cmd.description}`;
+  }
+
+  const subCommands = parseCommands(cmdHelp);
+
+  // Build command listing
+  commandLines.push(`- \`gobi ${cmd.name}\` — ${cmd.description}`);
+
+  const subHelpTexts: { name: string; helpText: string }[] = [];
+  for (const sub of subCommands) {
+    try {
+      const subHelp = runHelp([cmd.name, sub.name]);
+      subHelpTexts.push({ name: sub.name, helpText: subHelp });
+      commandLines.push(
+        `  - \`gobi ${cmd.name} ${sub.name}\` — ${sub.description}`
+      );
+    } catch {
+      // Skip commands that fail (e.g. interactive-only)
+    }
+  }
+
+  const refContent = generateReferenceDoc([cmd.name], cmdHelp, subHelpTexts);
+  const refFile = `${cmd.name}.md`;
+  writeFileSync(join(REFERENCES_DIR, refFile), refContent);
+  referenceFiles.push({
+    name: refFile,
+    path: `references/${refFile}`,
+    title: `gobi ${cmd.name}`,
+  });
+}
+
+// 3. Build placeholders
+const COMMANDS = commandLines.join("\n");
+const REFERENCE_TOC = referenceFiles
+  .map((ref) => `- [${ref.title}](${ref.path})`)
+  .join("\n");
+
+// 4. Read template and fill placeholders
+let template = readFileSync(TEMPLATE_PATH, "utf-8");
+template = template.replace(/\{\{VERSION\}\}/g, version);
+template = template.replace("{{COMMANDS}}", COMMANDS);
+template = template.replace("{{REFERENCE_TOC}}", REFERENCE_TOC);
+
+// 5. Write generated SKILL.md
+writeFileSync(OUTPUT_PATH, template);
+
+console.log(`Generated SKILL.md (v${version})`);
+console.log(`Generated ${referenceFiles.length} reference files`);