@gobi-ai/cli 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gobi-ai/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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.5.0"
+---
+
+# gobi-cli
+
+A CLI client for the Gobi collaborative knowledge platform (v0.5.0).
+
+## 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,125 @@
+# 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)
+  -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,144 @@
+# 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)
+  -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`);