felo-ai 0.2.50 → 0.2.52

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
@@ -155,9 +165,9 @@ node felo-superAgent/scripts/run_superagent.mjs \
 
 ```bash
 # Use as Claude Code skill
-/felo-superagent What is the latest news about AI?
-/felo-superagent Write a tweet about quantum computing
-/felo-superagent Design a logo for my coffee shop
+/felo-superAgent What is the latest news about AI?
+/felo-superAgent Write a tweet about quantum computing
+/felo-superAgent Design a logo for my coffee shop
 ```
 
 ```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/)            |
 
 ---
 
@@ -204,16 +215,17 @@ These two skills work together and share the style library. Here is how Claude u
 
 ```bash
 # Via ClawHub
-clawhub install felo-superAgent
+# felo-twitter-writer depends on felo-superAgent + felo-livedoc; felo-superAgent depends on felo-livedoc
 clawhub install felo-twitter-writer
-clawhub install felo-x-search
+clawhub install felo-superAgent
 clawhub install felo-livedoc
+clawhub install felo-x-search
 
 # Manual
-cp -r felo-superAgent ~/.claude/skills/
 cp -r felo-twitter-writer ~/.claude/skills/
-cp -r felo-x-search ~/.claude/skills/
+cp -r felo-superAgent ~/.claude/skills/
 cp -r felo-livedoc ~/.claude/skills/
+cp -r felo-x-search ~/.claude/skills/
 ```
 
 ### felo-twitter-writer
@@ -263,10 +275,10 @@ If the style library is empty, Claude skips the selection step silently.
 Trigger keywords: `superagent`, `super agent`, `stream chat`, `streaming conversation`, `write a tweet`, `create a logo`, `product image`
 
 ```
-/felo-superagent What is the latest news about AI?
-/felo-superagent Write a tweet about quantum computing
-/felo-superagent Design a logo for my coffee shop
-/felo-superagent Generate a product image for wireless headphones
+/felo-superAgent What is the latest news about AI?
+/felo-superAgent Write a tweet about quantum computing
+/felo-superAgent Design a logo for my coffee shop
+/felo-superAgent Generate a product image for wireless headphones
 ```
 
 **What Claude does automatically for skill-based conversations:**
@@ -296,13 +308,21 @@ 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
 clawhub install felo-livedoc
 clawhub install apple-buy-advisor
+
+# felo-superAgent depends on felo-livedoc — install both:
 clawhub install felo-superAgent
-# felo-twitter-writer: no clawhub.json yet — use manual install below
+clawhub install felo-livedoc
+
+# felo-twitter-writer depends on felo-superAgent and felo-livedoc — install all three:
+clawhub install felo-twitter-writer
+clawhub install felo-superAgent
+clawhub install felo-livedoc
 ```
 
 ```bash

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/felo-superAgent/README.md

@@ -177,7 +177,7 @@ node felo-superAgent/scripts/run_superagent.mjs \
   --query "Write a tweet about AI trends" \
   --live-doc-id "LIVE_DOC_ID" \
   --skill-id twitter-writer \
-  --ext '{"brand_style_requirement":"Style name: darioamodei\nStyle labels: Thoughtful long-form essays\nStyle DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA\n\n## 风格速写\nDario writes like a serious intellectual...（full content）"}' \
+  --ext '{"brand_style_requirement":"Style name: darioamodei\nStyle labels: Thoughtful long-form essays\nStyle DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA\n\n## Style Overview\nDario writes like a serious intellectual...（full content）"}' \
   --accept-language en
 ```
 

package/felo-superAgent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: felo-superAgent
-description: "Felo SuperAgent API: AI conversation with real-time SSE streaming on a persistent LiveDoc canvas. Use when users want SuperAgent chat, continuous conversation, logo/branding design, or e-commerce product images. Do NOT use for tweet/X post writing — use felo-twitter-writer instead. Explicit commands: /felo-superagent."
+description: "Felo SuperAgent API: AI conversation with real-time SSE streaming on a persistent LiveDoc canvas. Use when users want SuperAgent chat, continuous conversation, logo/branding design, or e-commerce product images. Do NOT use for tweet/X post writing — use felo-twitter-writer instead. Explicit commands: /felo-superAgent."
 ---
 
 # Felo SuperAgent Skill
@@ -11,7 +11,7 @@ These rules are mandatory. Violating any of them will produce incorrect behavior
 
 1. **ALWAYS use `--json` flag.** The script MUST run in JSON mode (`--json`). In Claude Code's Bash tool, stdout is always captured — it never streams directly to the user. JSON mode returns the full answer in a structured response that Claude can then output as text. State IDs are extracted from the JSON response fields `thread_short_id` and `live_doc_short_id`.
 
-2. **ALWAYS output the answer directly as text.** After the script finishes, read `data.answer` from the JSON output and print it verbatim as your response text. Do NOT summarize, paraphrase, or add commentary around it. Output it exactly as-is so the user sees the full content.
+2. **ALWAYS output the answer directly as text.** After the script finishes, read `data.answer` from the JSON output and print it verbatim as your response text. Do NOT summarize, paraphrase, or add commentary around it. Output it exactly as-is so the user sees the full content. Then, if `data.image_urls` is non-empty, append image links immediately after, formatted as one line per image: `[title](url)`.
 
 3. **`--live-doc-id` is REQUIRED when creating a conversation.** Never call `run_superagent.mjs` without `--live-doc-id`. If you do not have one yet, obtain it first (see Step 2 below).
 
@@ -69,7 +69,7 @@ Trigger this skill when users want:
 - Traditional Chinese (pinyin): chao ji zhu shou, liu shi dui hua, lian xu dui hua, zhui wen, she ji logo, pin pai she ji, dian shang tu pian
 - Japanese (romaji): suupaa eejento, sutoriimingu kaiwa, keizoku kaiwa, rogo sakusei, shouhin gazou
 
-**Explicit commands:** `/felo-superagent`, "use felo superagent", "felo superagent"
+**Explicit commands:** `/felo-superAgent`, "use felo superagent", "felo superagent"
 
 **Do NOT use for:**
 
@@ -233,58 +233,55 @@ If this is a follow-up (`--thread-id` is set), skip this step entirely. `--skill
 
 **4.5a. If the user has already specified a style** (by name, or by pasting a style block), use it directly — skip to 4.5d.
 
-**4.5b. Fetch the style list:**
+**4.5b. Fetch the style list (names only):**
 
-Use the category that matches the skill:
-
-| Skill ID | `--category` |
-|---|---|
-| `twitter-writer` | `TWITTER` |
-| `logo-and-branding` | `IMAGE` |
-| `ecommerce-product-image` | `IMAGE` |
-
-Pass `--accept-language` matching the user's language (same value used for SuperAgent).
+IMPORTANT: Style DNA content is very large. Always use `--json` and extract only names/labels via Node.js to avoid Bash tool output truncation. Never call `run_style_library.mjs` without `--json` for listing purposes.
 
 ```bash
 # For twitter-writer
-node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language en
+node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language en --json | node -e "
+const d=require('fs').readFileSync('/dev/stdin','utf8');
+const j=JSON.parse(d);
+const list=j.list||[];
+const user=list.filter(s=>!s.recommended);
+const rec=list.filter(s=>s.recommended);
+if(user.length){console.log('[Your styles]');user.forEach((s,i)=>{const labels=(s.content?.labels?.en||[]).join(', ');console.log((i+1)+'. '+s.name+(labels?' — '+labels:''));});}
+if(rec.length){console.log('[Recommended styles]');rec.forEach((s,i)=>{const labels=(s.content?.labels?.en||[]).join(', ');console.log((user.length+i+1)+'. '+s.name+(labels?' — '+labels:''));});}
+if(!list.length)console.log('(No styles found)');
+"
 
 # For logo-and-branding or ecommerce-product-image
-node felo-superAgent/scripts/run_style_library.mjs --category IMAGE --accept-language en
+node felo-superAgent/scripts/run_style_library.mjs --category IMAGE --accept-language en --json | node -e "
+const d=require('fs').readFileSync('/dev/stdin','utf8');
+const j=JSON.parse(d);
+const list=j.list||[];
+if(list.length){list.forEach((s,i)=>{const labels=(s.content?.labels?.en||s.content?.tags?.en||[]).join(', ');console.log((i+1)+'. '+s.name+(labels?' — '+labels:''));});}
+else console.log('(No styles found)');
+"
 ```
 
-The output lists styles in this format, one block per style separated by a blank line:
-
-```
-Style name: darioamodei
-Style labels: Thoughtful long-form essays
-Style DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA
-...（full content）
+Replace `en` with the matching `--accept-language` value for the user's language (`zh`, `ja`, `ko`, `en`). Also update the `.labels?.en` reference in the node script to match (e.g. `.labels?.zh` for Chinese).
 
-Style name: Casual & Witty
-Style labels: humor, relatable
-Style DNA: ...（full content）
-Cover file ID: file_abc123
-```
+**4.5c. Present the styles to the user and ask them to choose:**
 
-Notes:
-- `Style labels` is omitted if no labels exist for this entry.
-- `Style DNA` is the full text of `content.styleDna` (TWITTER type). Do NOT truncate it.
-- `Cover file ID` is omitted if the value is null/empty.
+Output the COMPLETE list as plain text — every style returned, numbered sequentially. NEVER use the `AskUserQuestion` tool (it limits to 4 options and will silently drop styles). NEVER pre-select or filter styles on behalf of the user. Always append a "no preference" option last. Wait for the user's plain-text reply before proceeding.
 
-User-created styles appear first, followed by recommended styles.
+Example output:
+```
+Here are the available writing styles — choosing one will make the output more accurate:
 
-**4.5c. Present the styles to the user and ask them to choose:**
+[Your styles]
+1. My Bold Voice — bold, provocative
 
-Show the list (style names only is sufficient) and ask which one to use. Wait for the user's selection before proceeding.
+[Recommended styles]
+2. darioamodei — Thoughtful long-form essays
+3. Casual & Witty — humor, relatable
+...(ALL styles listed, none omitted)
 
-Example prompt to user:
-> Here are the available Twitter writing styles. Which one would you like to use?
-> 1. Casual & Witty (your style)
-> 2. Professional Thought Leader (recommended)
-> 3. No style preference — use default
+0. No preference — use default style
+```
 
-If the user picks "no preference" or the list is empty, proceed to Step 5 without `--ext`.
+If the user picks "no preference" (0) or the list is empty, proceed to Step 5 without `--ext`.
 
 **4.5d. Build the `--ext` value:**
 
@@ -375,7 +372,14 @@ After the script finishes, parse the JSON output:
     "answer": "...",
     "thread_short_id": "CmYpuGwBgCnrUdDx5ZtmxA",
     "live_doc_short_id": "QPetunwpGnkKuZHStP7gwt",
-    "live_doc_url": "https://felo.ai/livedoc/QPetunwpGnkKuZHStP7gwt"
+    "live_doc_url": "https://felo.ai/livedoc/QPetunwpGnkKuZHStP7gwt",
+    "image_urls": [
+      {
+        "url": "https://...",
+        "title": "Image title",
+        "file_id": "b9e5be11-7686-4aa8-ae6c-9876511a7b5c"
+      }
+    ]
   }
 }
 ```
@@ -383,6 +387,20 @@ After the script finishes, parse the JSON output:
 1. **Output `data.answer` verbatim** as your response text — print it exactly as-is so the user sees the full content.
 2. **Extract and save** `data.thread_short_id` and `data.live_doc_short_id` — you MUST use these in the next call.
 3. **Optionally show** `data.live_doc_url` so the user can view the LiveDoc canvas in a browser.
+4. **Image results (`data.image_urls`):** If this array is non-empty, append image links immediately after `data.answer`, formatted as **one line per image**:
+
+   ```
+   [title](url)
+   ```
+
+   Example output:
+   ```
+   [Giant panda eating bamboo](https://...)
+   [Giant panda dancing](https://...)
+   [Blue whale leaping out of the water](https://...)
+   ```
+
+   Each image has `url` (signed S3 URL, time-limited), `title`, and `file_id` (stable file identifier). Note: the same image may appear in both `tools_result_stream` and `tools_result` events with different signed URLs — deduplication is handled automatically by `file_id`. When referencing a previously generated image in a follow-up query, include its `file_id` in the `--query` so SuperAgent can locate the file (e.g., `"Please generate a variation of file_id=b9e5be11-..."`).
 
 Do NOT show `thread_short_id` or `live_doc_short_id` to the user unless they ask for it.
 
@@ -717,8 +735,8 @@ User sends a message
         |
         v
 Have live_doc_id from ANY source?
-   NO  --> Step 2b: fetch list --> got items?
-              YES --> use data.items[0].short_id as live_doc_id
+   NO  --> Step 2b: fetch list --> got is_shared=false item?
+              YES --> use data.items.find(i => !i.is_shared)?.short_id as live_doc_id
               NO  --> Step 2c: create new LiveDoc
    YES --> continue (reuse it, do NOT fetch list)
         |

package/felo-superAgent/clawhub.json

@@ -8,5 +8,6 @@
   "license": "MIT",
   "pricing": "free",
   "support_url": "https://github.com/Felo-Inc/felo-skills/issues",
-  "homepage": "https://github.com/Felo-Inc/felo-skills"
+  "homepage": "https://github.com/Felo-Inc/felo-skills",
+  "dependencies": ["felo-livedoc"]
 }

package/felo-superAgent/scripts/run_superagent.mjs

@@ -168,14 +168,14 @@ function extractToolResults(data) {
       if (!callResult) continue;
       if (Array.isArray(callResult)) {
         for (const item of callResult) {
-          if (item?.image_url) out.push({ type: 'image', title: item?.title || '', image_url: item.image_url });
+          if (item?.image_url) out.push({ type: 'image', title: item?.title || '', image_url: item.image_url, file_id: item?.file_id || null });
         }
       } else if (callResult?.images && Array.isArray(callResult.images)) {
         for (const img of callResult.images) {
-          if (img?.image_url) out.push({ type: 'image', title: img?.title || '', image_url: img.image_url });
+          if (img?.image_url) out.push({ type: 'image', title: img?.title || '', image_url: img.image_url, file_id: img?.file_id || null });
         }
       } else if (callResult?.image_url) {
-        out.push({ type: 'image', title: callResult?.title || '', image_url: callResult.image_url });
+        out.push({ type: 'image', title: callResult?.title || '', image_url: callResult.image_url, file_id: callResult?.file_id || null });
       }
     }
     if (t?.name === 'generate_discovery' && callResult?.status === 'success') {
@@ -477,7 +477,9 @@ async function main() {
 
   const onToolResult = (item) => {
     const LIVEDOC_TYPES = new Set(['document', 'ppt', 'html', 'discovery']);
-    const key = item?.image_url || (LIVEDOC_TYPES.has(item?.type) ? item.type : `${item?.type}:${item?.title}`);
+    const key = (item?.type === 'image' && item?.file_id)
+      ? `file:${item.file_id}`
+      : item?.image_url || (LIVEDOC_TYPES.has(item?.type) ? item.type : `${item?.type}:${item?.title}`);
     if (seenKeys.has(key)) return;
     seenKeys.add(key);
     toolResults.push(item);
@@ -543,7 +545,7 @@ async function main() {
             answer: answer || null,
             thread_short_id: thread_short_id ?? null,
             live_doc_short_id: live_doc_short_id ?? null,
-            image_urls: images.length > 0 ? images.map((r) => ({ url: r.image_url, title: r.title })) : undefined,
+            image_urls: images.length > 0 ? images.map((r) => ({ url: r.image_url, title: r.title, ...(r.file_id ? { file_id: r.file_id } : {}) })) : undefined,
             discoveries: discoveries.length > 0 ? discoveries.map((r) => ({ title: r.title })) : undefined,
             documents: documents.length > 0 ? documents.map((r) => ({ title: r.title })) : undefined,
             ppts: ppts.length > 0 ? ppts.map((r) => ({ title: r.title })) : undefined,

package/felo-twitter-writer/clawhub.json

@@ -0,0 +1,13 @@
+{
+  "name": "Felo Twitter Writer",
+  "tagline": "Analyze tweet style DNA and compose tweets, threads, X posts with brand style in Claude Code",
+  "description": "Felo Twitter Writer lets you analyze any Twitter/X account's writing style and extract a Style DNA document, then compose high-quality tweets, threads, or X long-form posts that match that style. Supports style library, multi-language, and continuous follow-up. Requires a Felo API key.",
+  "category": "writing",
+  "tags": ["felo", "twitter", "tweet", "writing", "style", "thread", "ghostwrite"],
+  "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",
+  "dependencies": ["felo-superAgent", "felo-livedoc"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "felo-ai",
-  "version": "0.2.50",
+  "version": "0.2.52",
   "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;
+}