felo-ai 0.2.50 → 0.2.51

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>Ask anything. Get current answers. Generate slides from a prompt.</strong>
+  <strong>Ask anything. Get current answers. Generate slides and mindmaps from a prompt.</strong>
 </p>
 
 <p align="center">
@@ -15,7 +15,7 @@
   <a href="./felo-search/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
 </p>
 
-**Felo AI CLI** — Real-time search, PPT generation, web fetch, YouTube subtitles, X (Twitter) search, SuperAgent conversation, and Twitter writing from the terminal. Also works as Claude Code skills. Supports Chinese, English, Japanese, and Korean.
+**Felo AI CLI** — Real-time search, PPT generation, mindmap creation, web fetch, YouTube subtitles, and X (Twitter) search, SuperAgent conversation, and Twitter writing from the terminal. Also works as Claude Code skills. Supports Chinese, English, Japanese, and Korean.
 
 <p align="center">
   <a href="https://felo.ai">Felo AI</a> · <a href="https://openapi.felo.ai/docs/">Docs</a> · <a href="https://openapi.felo.ai/docs/api-reference/v2/chat.html">API Reference</a> · <a href="./docs/EXAMPLES.md">Examples</a> · <a href="./docs/FAQ.md">FAQ</a> · <a href="https://clawhub.ai/u/wangzhiming1999">ClawHub</a> · <a href="https://discord.gg/9W8NubHA">Discord</a> · <a href="https://x.com/felo_ai">X (Twitter)</a>
@@ -50,6 +50,7 @@ $env:FELO_API_KEY="..."             # Windows (PowerShell)
 | ---------------------------------------- | ----------------------------------------------------- |
 | `felo search "<query>"`                  | Search for current info (weather, news, prices, etc.) |
 | `felo slides "<prompt>"`                 | Generate PPT; returns link when done                  |
+| `felo mindmap "<query>"`                 | Generate mindmap; returns link immediately            |
 | `felo web-fetch --url <url>`             | Fetch webpage content (markdown/text/html)            |
 | `felo youtube-subtitling -v <url-or-id>` | Fetch YouTube video subtitles                         |
 | `felo x "<query>"`                       | Search X (Twitter) tweets, users, and replies         |
@@ -78,6 +79,15 @@ felo slides "Felo product intro, 3 slides"
 felo slides "Q4 2024 business review, 10 pages" --poll-timeout 300
 ```
 
+**Mindmap**
+
+```bash
+felo mindmap "AI trends in 2024"
+felo mindmap "Project timeline" --layout TIMELINE
+felo mindmap "Problem analysis" --layout FISHBONE --json
+felo mindmap-layouts                    # List available layouts
+```
+
 **Web Fetch** — [full options →](./felo-web-fetch/README.md)
 
 ```bash
@@ -180,7 +190,7 @@ felo style-library IMAGE --accept-language zh-Hans
 
 ## Skills Overview
 
-9 skills across search, content generation, web scraping, social media, knowledge base, shopping advice, Twitter writing, and AI conversation:
+10 skills across search, content generation, web scraping, social media, knowledge base, and shopping advice:
 
 | Skill | Description | Docs |
 |---|---|---|
@@ -193,6 +203,7 @@ felo style-library IMAGE --accept-language zh-Hans
 | **apple-buy-advisor** | Research and compare Apple products before you buy | [→](./apple-buy-advisor/) |
 | **felo-twitter-writer** | Analyze tweet style DNA; compose tweets, threads, X posts with brand style | [→](./felo-twitter-writer/README.md) |
 | **felo-superAgent** | AI conversation with real-time streaming, brand style support, continuous threads | [→](./felo-superAgent/README.md) |
+| **felo-mindmap**            | Generate mindmaps with various layouts                        | [→](./felo-mindmap/)            |
 
 ---
 
@@ -296,6 +307,7 @@ For skill-based new conversations, Claude fetches the matching style library, pr
 # Via ClawHub (recommended)
 clawhub install felo-search
 clawhub install felo-slides
+clawhub install felo-mindmap
 clawhub install felo-web-fetch
 clawhub install felo-youtube-subtitling
 clawhub install felo-x-search

package/felo-mindmap/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felo Mindmap Skill Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/felo-mindmap/README.md

@@ -0,0 +1,71 @@
+# Felo Mindmap
+
+Generate mindmaps with Felo Mindmap API in Claude Code.
+
+## Features
+
+- Create mindmaps from any topic or question
+- Support for 6 layout types: MIND_MAP, TIMELINE, FISHBONE, etc.
+- Add mindmaps to existing LiveDoc
+- Simple synchronous API (no waiting)
+
+## Setup
+
+1. Get your API key from [felo.ai](https://felo.ai) -> Settings -> API Keys
+2. Set environment variable:
+
+```bash
+export FELO_API_KEY="your-api-key-here"
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+node felo-mindmap/scripts/run_mindmap_task.mjs --query "Artificial Intelligence trends in 2024"
+```
+
+### With Layout Type
+
+```bash
+node felo-mindmap/scripts/run_mindmap_task.mjs --query "Project timeline" --layout TIMELINE
+```
+
+### With Existing LiveDoc
+
+```bash
+node felo-mindmap/scripts/run_mindmap_task.mjs --query "Meeting notes" --livedoc-short-id "abc123"
+```
+
+### JSON Output
+
+```bash
+node felo-mindmap/scripts/run_mindmap_task.mjs --query "Topic" --json
+```
+
+## Layout Types
+
+| Layout | Description |
+|--------|-------------|
+| `MIND_MAP` | Classic mind map (default) |
+| `LOGICAL_STRUCTURE` | Logical structure diagram |
+| `ORGANIZATION_STRUCTURE` | Organization chart |
+| `CATALOG_ORGANIZATION` | Catalog organization chart |
+| `TIMELINE` | Timeline diagram |
+| `FISHBONE` | Fishbone diagram |
+
+## CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `--query <text>` | Mindmap topic (required) |
+| `--layout <type>` | Layout type (default: MIND_MAP) |
+| `--livedoc-short-id <id>` | Add to existing LiveDoc |
+| `--timeout <seconds>` | Request timeout (default: 60) |
+| `--json` | Output as JSON |
+| `--help` | Show help |
+
+## License
+
+MIT

package/felo-mindmap/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: felo-mindmap
+description: "Generate mindmaps with Felo Mindmap API in Claude Code. Use when users ask to create/make/generate mindmaps, mind maps, or thinking maps, or when explicit commands like /felo-mindmap are used. Handles API key check, mindmap creation with various layouts, and final mindmap_url output."
+---
+
+# Felo Mindmap Skill
+
+## When to Use
+
+Trigger this skill for requests about creating mindmap files:
+
+- Create/generate mindmaps from a topic or question
+- Turn ideas into a structured mindmap
+- Build a mindmap with different layout types (timeline, fishbone, etc.)
+- Export mindmap content into a shareable link
+
+Trigger keywords:
+
+- Chinese prompts about making mindmaps (思维导图, 脑图)
+- English: mindmap, mind map, thinking map, generate mindmap
+- Explicit commands: `/felo-mindmap`, "use felo mindmap"
+
+Do NOT use this skill for:
+
+- Real-time information lookup (use `felo-search`)
+- Questions about local codebase files
+- Pure text tasks that do not require mindmap generation
+
+## Setup
+
+### 1. Get API key
+
+1. Visit [felo.ai](https://felo.ai)
+2. Open Settings -> API Keys
+3. Create and copy your API key
+
+### 2. Configure environment variable
+
+Linux/macOS:
+
+```bash
+export FELO_API_KEY="your-api-key-here"
+```
+
+Windows PowerShell:
+
+```powershell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+## How to Execute
+
+Use Bash tool commands and follow this workflow exactly.
+
+### Step 1: Precheck API key
+
+```bash
+if [ -z "$FELO_API_KEY" ]; then
+  echo "ERROR: FELO_API_KEY not set"
+  exit 1
+fi
+```
+
+If key is missing, stop and return setup instructions.
+
+### Step 2: Run Node Script
+
+Use the bundled script:
+
+```bash
+node felo-mindmap/scripts/run_mindmap_task.mjs \
+  --query "USER_PROMPT_HERE" \
+  --timeout 60
+```
+
+To specify a layout type:
+
+```bash
+node felo-mindmap/scripts/run_mindmap_task.mjs \
+  --query "USER_PROMPT_HERE" \
+  --layout "TIMELINE" \
+  --timeout 60
+```
+
+Available layout types:
+- `MIND_MAP` (default) - Classic mind map
+- `LOGICAL_STRUCTURE` - Logical structure diagram
+- `ORGANIZATION_STRUCTURE` - Organization chart
+- `CATALOG_ORGANIZATION` - Catalog organization chart
+- `TIMELINE` - Timeline diagram
+- `FISHBONE` - Fishbone diagram
+
+To add mindmap to an existing LiveDoc:
+
+```bash
+node felo-mindmap/scripts/run_mindmap_task.mjs \
+  --query "USER_PROMPT_HERE" \
+  --livedoc-short-id "EXISTING_LIVEDOC_ID"
+```
+
+Script behavior:
+
+- Creates mindmap via `POST https://openapi.felo.ai/v2/mindmap`
+- Returns immediately (synchronous API, no polling needed)
+- Prints `mindmap_url` on success
+
+Optional debug output:
+
+```bash
+node felo-mindmap/scripts/run_mindmap_task.mjs \
+  --query "USER_PROMPT_HERE" \
+  --json
+```
+
+This outputs structured JSON including:
+
+- `resource_id`
+- `status`
+- `mindmap_url`
+- `livedoc_short_id`
+
+### Step 3: Return structured result
+
+On success, return:
+
+- `mindmap_url` immediately
+- if `--json` is used, also include `resource_id`, `livedoc_short_id`
+
+## Output Format
+
+Use this response structure:
+
+```markdown
+## Mindmap Generation Result
+
+- Resource ID: <resource_id>
+- Status: <status>
+- Mindmap URL: <mindmap_url>
+- LiveDoc Short ID: <livedoc_short_id>
+```
+
+Error format:
+
+```markdown
+## Mindmap Generation Failed
+
+- Error Type: <error code or category>
+- Message: <readable message>
+- Suggested Action: <next step>
+```
+
+## Error Handling
+
+Known API error codes:
+
+- `INVALID_API_KEY` (401): key invalid or revoked
+- `MINDMAP_CREATE_FAILED` (502): mindmap creation failed
+- `LIVEDOC_CREATE_FAILED` (502): failed to create LiveDoc
+- `LIVEDOC_NOT_FOUND` (404): specified LiveDoc not found
+- `LLM_SERVICE_UNAVAILABLE` (503): LLM service is unavailable
+- `LLM_REQUEST_TIMEOUT` (504): LLM request timed out
+
+## Important Notes
+
+- Always execute this skill when user intent is mindmap generation.
+- The API is synchronous - no polling required.
+- Keep API calls minimal: one request per mindmap.
+
+## References
+
+- [Felo Mindmap API](https://openapi.felo.ai/docs/api-reference/v2/mindmap.html)
+- [Felo Open Platform](https://openapi.felo.ai/docs/)

package/felo-mindmap/clawhub.json

@@ -0,0 +1,12 @@
+{
+  "name": "Felo Mindmap",
+  "tagline": "Generate mindmaps with Felo Mindmap API in Claude Code",
+  "description": "Felo Mindmap creates mindmaps from a prompt using the Felo Mindmap API. Supports multiple layout types (MIND_MAP, TIMELINE, FISHBONE, etc.) and LiveDoc integration. Use from Claude Code when users ask to create or generate mindmaps.",
+  "category": "productivity",
+  "tags": ["felo", "mindmap", "mind map", "thinking map", "api", "claude-code"],
+  "version": "1.0.0",
+  "license": "MIT",
+  "pricing": "free",
+  "support_url": "https://github.com/Felo-Inc/felo-skills/issues",
+  "homepage": "https://github.com/Felo-Inc/felo-skills"
+}

package/felo-mindmap/scripts/run_mindmap_task.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+const DEFAULT_API_BASE = 'https://openapi.felo.ai';
+const DEFAULT_TIMEOUT_SEC = 60;
+const DEFAULT_LAYOUT = 'MIND_MAP';
+
+const VALID_LAYOUTS = [
+  'MIND_MAP',
+  'LOGICAL_STRUCTURE',
+  'ORGANIZATION_STRUCTURE',
+  'CATALOG_ORGANIZATION',
+  'TIMELINE',
+  'FISHBONE',
+];
+
+function usage() {
+  console.error(
+    [
+      'Usage:',
+      '  node felo-mindmap/scripts/run_mindmap_task.mjs --query "your prompt" [options]',
+      '',
+      'Options:',
+      '  --query <text>              Mindmap topic (required)',
+      '  --layout <type>             Layout type (default: MIND_MAP)',
+      '  --livedoc-short-id <id>     Add to existing LiveDoc',
+      '  --timeout <seconds>         Request timeout, default 60',
+      '  --json                      Print JSON output',
+      '  --help                      Show this help',
+      '',
+      'Layout Types:',
+      '  MIND_MAP              Classic mind map (default)',
+      '  LOGICAL_STRUCTURE     Logical structure diagram',
+      '  ORGANIZATION_STRUCTURE Organization chart',
+      '  CATALOG_ORGANIZATION  Catalog organization chart',
+      '  TIMELINE              Timeline diagram',
+      '  FISHBONE              Fishbone diagram',
+    ].join('\n')
+  );
+}
+
+function parseArgs(argv) {
+  const out = {
+    query: '',
+    layout: DEFAULT_LAYOUT,
+    livedocShortId: '',
+    timeoutSec: DEFAULT_TIMEOUT_SEC,
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+    } else if (a === '--json') {
+      out.json = true;
+    } else if (a === '--query') {
+      out.query = argv[i + 1] ?? '';
+      i += 1;
+    } else if (a === '--layout') {
+      out.layout = argv[i + 1] ?? '';
+      i += 1;
+    } else if (a === '--livedoc-short-id') {
+      out.livedocShortId = argv[i + 1] ?? '';
+      i += 1;
+    } else if (a === '--timeout') {
+      out.timeoutSec = Number.parseInt(argv[i + 1] ?? '', 10);
+      i += 1;
+    } else if (!a.startsWith('-') && !out.query) {
+      out.query = a;
+    }
+  }
+
+  if (!Number.isFinite(out.timeoutSec) || out.timeoutSec <= 0) {
+    out.timeoutSec = DEFAULT_TIMEOUT_SEC;
+  }
+
+  return out;
+}
+
+function getMessage(payload) {
+  return (
+    payload?.message ||
+    payload?.error ||
+    payload?.msg ||
+    payload?.code ||
+    'Unknown error'
+  );
+}
+
+function isApiError(payload) {
+  const status = payload?.status;
+  const code = payload?.code;
+  if (typeof status === 'string' && status.toLowerCase() === 'error') return true;
+  if (typeof code === 'string' && code && code.toUpperCase() !== 'OK') return true;
+  return false;
+}
+
+async function fetchJson(url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { ...init, signal: controller.signal });
+    let body = {};
+    try {
+      body = await res.json();
+    } catch {
+      body = {};
+    }
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${getMessage(body)}`);
+    }
+    if (isApiError(body)) {
+      throw new Error(getMessage(body));
+    }
+    return body;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function createMindmap(apiKey, apiBase, query, layout, livedocShortId, timeoutMs) {
+  const reqBody = { query, layout };
+  if (livedocShortId) {
+    reqBody.livedoc_short_id = livedocShortId;
+  }
+
+  const payload = await fetchJson(
+    `${apiBase}/v2/mindmap`,
+    {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(reqBody),
+    },
+    timeoutMs
+  );
+
+  const data = payload?.data ?? {};
+  return data;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    process.exit(0);
+  }
+  if (!args.query) {
+    usage();
+    process.exit(1);
+  }
+
+  const apiKey = process.env.FELO_API_KEY?.trim();
+  if (!apiKey) {
+    console.error('ERROR: FELO_API_KEY not set');
+    console.error('');
+    console.error('Setup instructions:');
+    console.error('1. Visit https://felo.ai');
+    console.error('2. Open Settings -> API Keys');
+    console.error('3. Create and copy your API key');
+    console.error('4. Set environment variable: export FELO_API_KEY="your-api-key"');
+    process.exit(1);
+  }
+
+  // Validate layout type
+  const layoutUpper = args.layout.toUpperCase();
+  if (!VALID_LAYOUTS.includes(layoutUpper)) {
+    console.error(`ERROR: Invalid layout type "${args.layout}"`);
+    console.error('');
+    console.error('Available layout types:');
+    VALID_LAYOUTS.forEach((l) => console.error(`  - ${l}`));
+    process.exit(1);
+  }
+
+  const apiBase = (process.env.FELO_API_BASE?.trim() || DEFAULT_API_BASE).replace(/\/$/, '');
+  const timeoutMs = args.timeoutSec * 1000;
+
+  try {
+    const data = await createMindmap(
+      apiKey,
+      apiBase,
+      args.query,
+      layoutUpper,
+      args.livedocShortId,
+      timeoutMs
+    );
+
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          {
+            status: 'ok',
+            data: {
+              resource_id: data.resource_id ?? null,
+              mindmap_status: data.status ?? null,
+              mindmap_url: data.mindmap_url ?? null,
+              livedoc_short_id: data.livedoc_short_id ?? null,
+              message: data.message ?? null,
+            },
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(data.mindmap_url || data.message || 'Mindmap created successfully');
+    }
+  } catch (err) {
+    const errMsg = err?.message || err;
+    console.error(`ERROR: ${errMsg}`);
+
+    // Provide helpful guidance for known error patterns
+    if (errMsg.includes('401') || errMsg.includes('INVALID_API_KEY')) {
+      console.error('');
+      console.error('Your API key may be invalid or expired.');
+      console.error('Please check your API key at https://felo.ai -> Settings -> API Keys');
+    } else if (errMsg.includes('timeout') || errMsg.includes('AbortError')) {
+      console.error('');
+      console.error('Request timed out. Try increasing --timeout or retry later.');
+    }
+
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "felo-ai",
-  "version": "0.2.50",
+  "version": "0.2.51",
   "description": "Felo AI CLI - real-time search, PPT generation, SuperAgent conversation, LiveDoc management, web fetch, YouTube subtitles, LiveDoc knowledge base, and X (Twitter) search from the terminal",
   "type": "module",
   "main": "src/cli.js",

package/src/cli.js

@@ -4,6 +4,7 @@ import { createRequire } from "module";
 import { Command } from "commander";
 import { search } from "./search.js";
 import { slides, listPptThemes } from "./slides.js";
+import { mindmap, listMindmapLayouts } from "./mindmap.js";
 import { superAgent, listLiveDocs, listLiveDocResources, listStyleLibrary } from "./superAgent.js";
 import { appleBuyAdvisor } from "./appleBuyAdvisor.js";
 import { webFetch } from "./webFetch.js";
@@ -137,6 +138,36 @@ program
     flushStdioThenExit(code);
   });
 
+program
+  .command("mindmap")
+  .description("Generate a mindmap from a prompt (synchronous API)")
+  .argument("<query>", "mindmap topic or question")
+  .option("-l, --layout <type>", "layout type (default: MIND_MAP)")
+  .option("--livedoc-short-id <id>", "add to existing LiveDoc")
+  .option("-j, --json", "output raw JSON with resource_id and livedoc_short_id")
+  .option("-t, --timeout <seconds>", "request timeout in seconds", "60")
+  .action(async (query, opts) => {
+    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
+    const code = await mindmap(query, {
+      layout: opts.layout,
+      livedocShortId: opts.livedocShortId,
+      json: opts.json,
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
+program
+  .command("mindmap-layouts")
+  .description("List available mindmap layout types")
+  .option("-j, --json", "output raw JSON")
+  .action(async (opts) => {
+    const code = await listMindmapLayouts({ json: opts.json });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
 program
   .command("superagent")
   .description(

package/src/mindmap.js

@@ -0,0 +1,185 @@
+import {
+  getApiKey,
+  fetchWithTimeoutAndRetry,
+  NO_KEY_MESSAGE,
+} from "./search.js";
+
+const DEFAULT_API_BASE = "https://openapi.felo.ai";
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const DEFAULT_LAYOUT = "MIND_MAP";
+
+const VALID_LAYOUTS = [
+  "MIND_MAP",
+  "LOGICAL_STRUCTURE",
+  "ORGANIZATION_STRUCTURE",
+  "CATALOG_ORGANIZATION",
+  "TIMELINE",
+  "FISHBONE",
+];
+
+/** API base URL (default https://openapi.felo.ai). Override via FELO_API_BASE env or config if needed. */
+async function getApiBase() {
+  let base = process.env.FELO_API_BASE?.trim();
+  if (!base) {
+    const { getConfigValue } = await import("./config.js");
+    const v = await getConfigValue("FELO_API_BASE");
+    base = typeof v === "string" ? v.trim() : "";
+  }
+  const normalized = (base || DEFAULT_API_BASE).replace(/\/$/, "");
+  return normalized;
+}
+
+/**
+ * Create a mindmap. Returns { resource_id, status, mindmap_url, livedoc_short_id } or throws.
+ * Uses fetchWithTimeoutAndRetry for 5xx retry.
+ * @param {string} apiKey
+ * @param {string} query
+ * @param {string} layout
+ * @param {string} livedocShortId
+ * @param {number} timeoutMs
+ * @param {string} apiBase
+ */
+async function createMindmap(apiKey, query, layout, livedocShortId, timeoutMs, apiBase) {
+  const url = `${apiBase}/v2/mindmap`;
+  const body = { query: query.trim(), layout };
+  if (livedocShortId) {
+    body.livedoc_short_id = livedocShortId;
+  }
+
+  const res = await fetchWithTimeoutAndRetry(
+    url,
+    {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    },
+    timeoutMs
+  );
+
+  const data = await res.json().catch(() => ({}));
+
+  if (data.status === "error") {
+    const msg = data.message || data.code || "Unknown error";
+    throw new Error(msg);
+  }
+
+  if (!res.ok) {
+    const msg =
+      data.message || data.error || res.statusText || `HTTP ${res.status}`;
+    throw new Error(msg);
+  }
+
+  const payload = data.data;
+  if (!payload) {
+    throw new Error("Unexpected response: missing data");
+  }
+
+  return payload;
+}
+
+/**
+ * Run mindmap: create mindmap and output URL or error.
+ * @returns {Promise<number>} exit code (0 success, 1 failure)
+ */
+export async function mindmap(query, options = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) {
+    console.error(NO_KEY_MESSAGE.trim());
+    return 1;
+  }
+
+  const requestTimeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const layout = (options.layout || DEFAULT_LAYOUT).toUpperCase();
+
+  // Validate layout
+  if (!VALID_LAYOUTS.includes(layout)) {
+    console.error(`Error: Invalid layout "${options.layout}"`);
+    console.error("");
+    console.error("Available layouts:");
+    VALID_LAYOUTS.forEach((l) => console.error(`  - ${l}`));
+    return 1;
+  }
+
+  try {
+    const apiBase = await getApiBase();
+
+    process.stderr.write("Creating mindmap...\n");
+
+    const result = await createMindmap(
+      apiKey,
+      query,
+      layout,
+      options.livedocShortId,
+      requestTimeoutMs,
+      apiBase
+    );
+
+    const mindmapUrl = result.mindmap_url;
+    const livedocShortId = result.livedoc_short_id;
+    const resourceId = result.resource_id;
+
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            status: "ok",
+            data: {
+              resource_id: resourceId,
+              mindmap_status: result.status,
+              mindmap_url: mindmapUrl,
+              livedoc_short_id: livedocShortId,
+              message: result.message,
+            },
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      if (mindmapUrl) {
+        process.stderr.write("Mindmap ready. Open this link to view:\n");
+        console.log(mindmapUrl);
+      } else {
+        console.error("Error: No mindmap_url in response");
+        return 1;
+      }
+    }
+
+    return 0;
+  } catch (err) {
+    console.error("Error:", err.message || err);
+    return 1;
+  }
+}
+
+/**
+ * List available layout types for mindmap.
+ * @returns {Promise<number>} exit code (0 success)
+ */
+export async function listMindmapLayouts(options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify({ layouts: VALID_LAYOUTS }, null, 2));
+    return 0;
+  }
+
+  console.log("Available mindmap layouts:\n");
+  const layoutDescriptions = {
+    MIND_MAP: "Classic mind map (default)",
+    LOGICAL_STRUCTURE: "Logical structure diagram",
+    ORGANIZATION_STRUCTURE: "Organization chart",
+    CATALOG_ORGANIZATION: "Catalog organization chart",
+    TIMELINE: "Timeline diagram",
+    FISHBONE: "Fishbone diagram",
+  };
+
+  for (const l of VALID_LAYOUTS) {
+    const desc = layoutDescriptions[l] || "";
+    console.log(`  ${l.padEnd(22)} ${desc}`);
+  }
+
+  return 0;
+}