felo-ai 0.2.42 → 0.2.43

package/README.md

@@ -240,37 +240,6 @@ We welcome contributions — report bugs, improve docs, or add new skills. Run t
 
 ---
 
-## 发布到 npm（维护者）
-
-本仓库通过 GitHub Actions 自动发布到 npm，**不要手动在 CI 里改版本号或重复发布相同版本**。
-
-- **发布一个新版本**
-  1. 确保代码已推到 `main`（或你用来发布的分支）
-  2. 选择一个**尚未在 npm 上使用过的新版本号**（语义化版本号 `MAJOR.MINOR.PATCH`）
-  3. 在本地打 tag 并推送，例如：
-
-     ```bash
-     git tag v0.2.24
-     git push origin v0.2.24
-     ```
-
-  4. GitHub Actions 会在 `push tag v*` 时自动运行：
-     - 从 tag 名中取出版本号（`v0.2.24` → `0.2.24`）
-     - 将 `package.json` 中的 `"version"` 同步为该版本号
-     - 运行测试
-     - 执行 `npm publish --provenance --access public`
-
-- **版本号约定（建议）**
-  - **PATCH（补丁号）**：向下兼容的小修小补（bugfix、文档更新等），例如 `0.2.23` → `0.2.24`
-  - **MINOR（次版本号）**：向下兼容的新功能，例如新增子命令或新的 skill，`0.2.0` → `0.3.0`
-  - **MAJOR（主版本号）**：有破坏性改动时使用，例如 CLI 行为或配置不兼容旧版本，`0.x.x` → `1.0.0`
-
-- **注意事项**
-  - npm 不允许覆盖已发布的版本，**不要重复推送同一个版本号的 tag**（例如已经发布了 `0.2.23`，再次尝试发布会收到 403 错误）
-  - 如果某个已发布版本存在严重问题，可考虑通过 `npm deprecate` 标记为不推荐使用，而不是尝试覆盖它
-
----
-
 ## License
 
 MIT — see [LICENSE](./felo-search/LICENSE) for details.

package/claw-deck/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: claw-deck
+description: "Use when users need to manage ClawDeck project workspaces backed by Felo LiveDoc — creating, loading, switching workspaces, saving artifacts, querying history, or managing tasks. Triggers on workspace-related intent combined with project/client names, or on 401 UNAUTHORIZED errors from Felo API."
+---
+
+# ClawDeck — Workspace Manager
+
+The Agent's external brain for projects. Once active, the Agent continuously syncs tasks, artifacts, and knowledge to the corresponding LiveDoc, so anyone (including future sessions or colleagues) can load the workspace and immediately get full context.
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| Workspace | One project = one LiveDoc |
+| Active Workspace | Session-level state; all operations auto-sync here |
+| README | The Agent's memory of the project; Agent maintains proactively |
+| Artifacts | Key outputs; Agent asks before saving |
+| Tasks | Tracking records for substantive work; Agent maintains silently |
+| Registry | `~/.claude/workspaces.json`, maps project names to LiveDoc IDs |
+
+**Registry format:**
+```json
+{
+  "workspaces": {
+    "client-acme": "abc123",
+    "project-x": "def456"
+  }
+}
+```
+
+## Script Shorthand
+
+In all commands below, `$SCRIPT` refers to:
+
+```
+node felo-livedoc/scripts/run_livedoc.mjs
+```
+
+## When NOT to Use
+
+- Simple chitchat or clarifying questions
+- One-off generation unrelated to any project/workspace
+- User has not installed the Felo LiveDoc NPM package
+
+---
+
+## Workflows
+
+### 0. First-Time Installation
+
+User pastes GitHub install link → execute installation → after completion, automatically enter **Login flow (0a)**.
+
+### 0a. Login / Re-authorization
+
+**Trigger conditions (either one):**
+- First-time installation, Key not yet configured
+- Any API call returns `{"status":401,"code":"UNAUTHORIZED","message":"Invalid API Key"}`
+
+**Flow:**
+
+1. Send login link:
+   > "Please click the link to log in / register a Felo account: https://felo.ai/settings/api-keys
+   > Once done, paste the Key back to me and I'll complete the setup automatically."
+2. User pastes Key → write to config:
+   ```bash
+   export FELO_API_KEY="user's Key"
+   ```
+   Or persist to `~/.claude/env` (platform-dependent).
+3. Verify: `$SCRIPT list`
+   - Pass + first install → show usage introduction (see "First-Time Usage Introduction" below)
+   - Pass + re-authorization → "✅ Authorization updated." → retry the failed command
+   - Fail → "Invalid Key, please paste again."
+
+**First-Time Usage Introduction** (show only on first install; skip on re-authorization):
+
+> "🎉 Setup complete! You can now use the following commands to manage workspaces:
+>
+> 📁 **Create workspace** — Create a standalone workspace for a new project
+> Example: 'Create a workspace called Client Acme'
+>
+> 📂 **Load workspace** — Open an existing project, restore context
+> Example: 'Load the Acme workspace'
+>
+> 📋 **View workspace** — List all projects or view project contents
+> Example: 'What workspaces do I have?' / 'What's in the Acme workspace?'
+>
+> 💾 **Save artifacts** — Important outputs will prompt you to save
+>
+> The workspace records everything we do. You can view it anytime on the web: https://felo.ai"
+
+### 1. Load Workspace
+
+1. Read `~/.claude/workspaces.json`, fuzzy-match project name. If not found locally, try `$SCRIPT list --keyword`.
+2. **Found:** Set as active → `$SCRIPT get-readme SHORT_ID` → present README as workspace briefing → append link `https://felo.ai/livedoc/SHORT_ID?from=claw`. If README is empty or missing, fall back to `$SCRIPT resources SHORT_ID` to show the resource list.
+3. **Not found:** "No workspace found for '[X]'. Want me to create one?"
+
+### 2. Create Workspace
+
+```bash
+$SCRIPT create --name "Project Name" --description "workspace"
+```
+
+Extract `short_id` → initialize README (see "README Structure Template" below) → update registry → set as active → reply:
+
+> "✅ Workspace '[X]' created. 📎 https://felo.ai/livedoc/SHORT_ID?from=claw"
+
+### 3. Task Sync (Mandatory)
+
+**Iron rule: When the workspace is active, if the user's request requires the Agent to invoke tools to produce new content (search, generate, analyze, etc.), the very first step is always `create-task` — before doing anything else.**
+
+Decision flow:
+1. User sends a message
+2. Does this message require the Agent to invoke tools to produce new content? (search, generate, collect, analyze, write)
+   - Yes → **immediately `create-task`** → execute → **`update-task` to mark complete**
+   - No → execute directly, no task needed
+
+**Requires task creation (invoking tools to produce new content):**
+- "Collect client info on Mr. Zhang" → requires search + generation
+- "Add 10 horror TikTok videos" → requires search + adding content
+- "Write a competitive analysis report" → requires generation
+- "Search for recent gold price trends" → requires search
+
+**Does NOT require task creation (workspace operations):**
+- "Load Mr. Zhang's workspace" → workspace operation
+- "What's in my workspace?" → viewing workspace
+- "Refresh the workspace" / "Create a new workspace" → workspace management
+- "Save that report" → saving artifacts
+- "Update the README" / "Rename the workspace" → workspace maintenance
+- Chitchat, clarifying questions
+
+**On load:** Pull pending and in-progress tasks:
+```bash
+$SCRIPT tasks SHORT_ID --status 0
+$SCRIPT tasks SHORT_ID --status 1
+```
+
+**Step one — Create task (before doing anything else):**
+```bash
+$SCRIPT create-task SHORT_ID --title "Task description" --status 1 --sort 0 [--operated-by "Agent Name"]
+```
+Save the returned `task_id` in working memory.
+
+`--title` should be a one-line summary of what the user wants done, e.g.:
+- User says "Collect info on Mr. Zhang" → `--title "Collect client info on Mr. Zhang"`
+- User says "Add 10 horror videos" → `--title "Add 10 horror TikTok trending videos"`
+
+`--operated-by` rules:
+- **Only pass it if the Agent has been given a name** in this session (e.g. an OpenClaw agent with an assigned name)
+- **Omit it if no explicit name** (e.g. a plain Claude Code session)
+
+**Last step — Mark complete (immediately after execution):**
+```bash
+$SCRIPT update-task SHORT_ID TASK_ID --status 2 [--operated-by "Agent Name"]
+```
+(`--operated-by` rule same as above — pass it when the Agent has a name.)
+
+Execute silently — do not narrate the task sync to the user. If you forgot to create a task before starting, create it retroactively and mark it DONE immediately. Never skip it.
+
+### 4. Save Artifacts (Ask First)
+
+After producing significant output, ask the user: "Want me to save this to the [project] workspace?"
+
+Significant artifacts = research reports, competitive analyses, meeting summaries, generated documents, key data exports. Intermediate drafts do not need to be saved.
+
+| Type | Command |
+|------|---------|
+| Document | `$SCRIPT add-doc SHORT_ID --title "Title" --content "content"` |
+| URL | `$SCRIPT add-urls SHORT_ID --urls "URL"` |
+| File | `$SCRIPT upload SHORT_ID --file ./path --convert` |
+
+After saving, reply:
+> "💾 Saved '[Title]' 📎 https://felo.ai/livedoc/SHORT_ID?from=claw"
+
+### 5. README Maintenance
+
+The README is the Agent's memory of the project — not a work log. Agent maintains proactively, no need to ask the user.
+
+**README Structure Template:**
+```markdown
+# [Project Name]
+
+## What This Project Is
+[Project background, objectives, stakeholders]
+
+## User Preferences & Work Patterns
+[How the user likes to work, what dimensions they care about, specific requirements]
+
+## Current Progress
+[Where things stand now — updated each session]
+Last updated: YYYY-MM-DD
+```
+
+**When to update README — core question: Did this operation bring any new understanding?**
+
+Update (new understanding):
+- When the project is first created — record "what this project is about"
+- When the user expresses preferences or work patterns — record "how the user wants to work" (e.g. collection dimensions, focus areas, format requirements)
+- When the project's nature or direction changes
+
+Do NOT update (repeated execution):
+- Same-pattern repeated operations (e.g. after collecting info on Mr. Zhang, collecting info on Mr. Li using the same pattern — no update needed)
+- The mere fact of executing an action (generating a document is not worth recording by itself)
+
+**Update method:** Read → merge in memory into the correct section → write back in full. Never blindly append to the end.
+
+1. `$SCRIPT get-readme SHORT_ID` to read current content
+2. Locate the target section in memory and insert:
+   - Project background → `## What This Project Is`
+   - User preferences → `## User Preferences & Work Patterns`
+   - Progress changes → replace `## Current Progress` section content
+3. Update `Last updated: YYYY-MM-DD` to today's date
+4. `$SCRIPT update-readme SHORT_ID --content "..."` to write back
+
+**Initialization** (README is empty or missing): Skip step 1, write the full skeleton directly with `update-readme`.
+
+After updating, inform the user:
+> "📝 README updated. 📎 https://felo.ai/livedoc/SHORT_ID?from=claw"
+
+### 6. Query Workspace
+
+Prefer `resources` + `content` (direct read, free) over `retrieve` (LLM-based semantic search, costs money).
+
+```bash
+$SCRIPT resources SHORT_ID
+$SCRIPT content SHORT_ID RESOURCE_ID
+$SCRIPT retrieve SHORT_ID --query "question"   # fallback
+```
+
+Synthesize returned content into a direct answer. Do not dump raw results.
+
+### 7. Refresh Workspace
+
+When the user says "refresh", or when the workspace may have been updated externally (by a colleague or another session), re-fetch:
+
+```bash
+$SCRIPT get-readme SHORT_ID
+$SCRIPT resources SHORT_ID
+$SCRIPT tasks SHORT_ID --status 0
+$SCRIPT tasks SHORT_ID --status 1
+```
+
+Update the in-memory snapshot. Tell the user: "Workspace refreshed." If anything changed, briefly describe the differences (new resources, README updates, new tasks).
+
+### 8. List Contents
+
+`$SCRIPT resources SHORT_ID`, grouped by type, artifacts newest first.
+
+---
+
+## Session State
+
+```
+ACTIVE_WORKSPACE = { name: "project-x", short_id: "abc123" }
+```
+
+- Set when user loads or creates a workspace; clear when user says "close workspace"
+- If no active workspace and user tries to save/log/query/task: "No active workspace. Which project?"
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| Key missing / 401 UNAUTHORIZED | Trigger Login flow (0a) |
+| LiveDoc ID stale | Offer to re-link or create new |
+| Registry missing | Auto-create with `{"workspaces": {}}` |
+| Ambiguous fuzzy match | List all matches, ask user to pick |
+
+## Important Rules
+
+- Write all content in the user's language — Chinese if they speak Chinese, English if English
+- Always use `short_id` for all LiveDoc operations
+- Execute commands immediately — don't describe, do
+- Task sync and README updates are the Agent's responsibility — proactive, not reactive
+- Append workspace link after every write operation

package/felo-slides/clawhub.json

@@ -0,0 +1,12 @@
+{
+  "name": "Felo Slides",
+  "tagline": "Generate PPT/slides with Felo PPT Task API in Claude Code",
+  "description": "Felo Slides creates presentation decks from a prompt using the Felo PPT Task API: API key check, task creation, polling, theme support, task resume, and final ppt_url output. Use from Claude Code when users ask to create or export slides/PPT.",
+  "category": "productivity",
+  "tags": ["felo", "slides", "ppt", "presentation", "api", "claude-code"],
+  "version": "1.0.1",
+  "license": "MIT",
+  "pricing": "free",
+  "support_url": "https://github.com/Felo-Inc/felo-skills/issues",
+  "homepage": "https://github.com/Felo-Inc/felo-skills"
+}

package/felo-twitter-writer/README.md

@@ -0,0 +1,85 @@
+# Felo Twitter Writer Skill
+
+Dual-mode Twitter/X writing tool powered by [Felo SuperAgent](https://openapi.felo.ai/docs/api-reference/v2/superagent.html).
+
+**Mode 1** — Fetch tweets from any X account and extract a writing style DNA document.
+**Mode 2** — Compose tweets, threads, or X long-form posts based on a style DNA and topic.
+
+## Features
+
+- **Style DNA extraction** — analyze an account's tone, sentence structure, hooks, hashtag strategy, and more
+- **Tweet creation** — single tweets, threads, or X long-form posts, default 3 versions
+- **Style imitation** — write in the voice of any public X account
+- **Iterative editing** — refine generated content via follow-up conversation
+- Powered by SuperAgent with `twitter-writer` skill, real-time SSE streaming
+- Same `FELO_API_KEY` as other Felo skills
+
+## Prerequisites
+
+- [`felo-superAgent`](../felo-superAgent/) skill available
+- [`felo-x-search`](../felo-x-search/) skill available
+- [`felo-livedoc`](../felo-livedoc/) skill available
+
+## Quick Start
+
+### 1) Configure API key
+
+At [felo.ai](https://felo.ai) → Settings → API Keys, create a key, then:
+
+```bash
+# Linux/macOS
+export FELO_API_KEY="your-api-key-here"
+```
+
+```powershell
+# Windows PowerShell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+```cmd
+:: Windows CMD
+set FELO_API_KEY=your-api-key-here
+```
+
+### 2) Mode 1 — Extract style DNA
+
+```bash
+# Step 1: Fetch tweets from an account
+node felo-x-search/scripts/run_x_search.mjs --id "elonmusk" --user --tweets --limit 30
+node felo-x-search/scripts/run_x_search.mjs --id "elonmusk" --user
+
+# Step 2: Get your live_doc_id (list existing, or create one if empty)
+node felo-livedoc/scripts/run_livedoc.mjs list --json
+# node felo-livedoc/scripts/run_livedoc.mjs create --name "Twitter Writer" --json
+
+# Step 3: Pass tweets to SuperAgent for style analysis
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "Analyze the following tweets from @elonmusk and extract a writing style DNA document covering tone, sentence structure, opening hooks, hashtag strategy, and emoji usage.\n\nBio: [BIO]\n\nTweets:\n[TWEETS]" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language en
+```
+
+### 3) Mode 2 — Create content
+
+```bash
+# New conversation (no prior style DNA)
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "Write 3 versions of a tweet about AI trends in an engaging, punchy style." \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language en
+
+# Follow-up after Mode 1 (reuse thread — pass --thread-id from previous [state] output)
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "Based on the style DNA above, write 3 tweets about startups. Keep each under 280 characters." \
+  --thread-id "THREAD_SHORT_ID" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --accept-language en
+```
+
+## When to use (Agent)
+
+Trigger keywords: `write a tweet`, `twitter thread`, `style DNA`, `imitate tweet style`, `tweet in the style of`, `X account analysis`, `ghostwrite tweets`, `how does [account] write`, `ツイートを書く`, `ツイートスタイル分析`, `スタイルDNA`, `ツイートを模倣`, `〇〇風のツイートを書く`, `ツイートを代筆`, `Xアカウント分析`, `/felo-twitter-writer`.
+
+See [SKILL.md](SKILL.md) for full agent instructions.

package/felo-twitter-writer/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: felo-twitter-writer
+description: "Dual-mode Twitter/X writing tool. Mode 1: input a Twitter account, auto-fetch popular tweets and extract a writing style DNA document. Mode 2: based on style DNA and a topic, compose high-quality tweets, threads, or X long-form posts. Use when users want to analyze Twitter style, extract writing style, write tweets, write threads, imitate someone's tweet style, or ghostwrite tweets."
+---
+
+# Felo Twitter Writer Skill
+
+## Constraints (MUST READ FIRST)
+
+These rules are mandatory. Violating any of them will produce incorrect behavior.
+
+1. **This skill uses SuperAgent directly.** All generation is handled by `felo-superAgent/scripts/run_superagent.mjs` with `--skill-id twitter-writer`. Do NOT attempt to generate tweet content yourself.
+
+2. **NEVER use `--json` flag** when calling SuperAgent. The script MUST run in default streaming mode. State IDs are extracted from the `[state]` line in stderr.
+
+3. **NEVER summarize or re-output SuperAgent's stdout.** The answer is already streamed directly to the user. Only add supplementary info (LiveDoc URL) if needed.
+
+4. **`--live-doc-id` is REQUIRED** for every SuperAgent call. Follow the livedoc reuse rules from `felo-superAgent/SKILL.md`:
+   - Reuse any `live_doc_id` already available in this session
+   - If none: run `node felo-livedoc/scripts/run_livedoc.mjs list --json`, use `items[0].short_id`
+   - If list is empty: run `node felo-livedoc/scripts/run_livedoc.mjs create --name "Twitter Writer" --json`, use `data.short_id`
+
+5. **Always persist state.** After every SuperAgent call, extract `thread_short_id` and `live_doc_short_id` from the stderr `[state]` line. Use them in subsequent calls.
+
+6. **Output language follows the user's input language.** Default is `en`. Detect the user's language and pass the matching `--accept-language` value: `ja` for Japanese, `en` for English, `ko` for Korean, `zh` for Chinese. If unsure, use `en`.
+
+7. **Do NOT pass `--timeout` to the SuperAgent script.** The script manages its own connection lifecycle.
+
+## When to Use
+
+Trigger this skill when the user wants to:
+
+- Analyze a Twitter/X account's writing style
+- Extract a writing style DNA document from tweets
+- Write, draft, or compose tweets / X posts
+- Write a Twitter thread (multi-tweet series)
+- Write an X long-form article / long post
+- Imitate or mimic someone's tweet style
+- Ghostwrite tweets on behalf of someone
+- Understand how a specific account writes
+
+**Trigger keywords:**
+
+- English: `analyze twitter style`, `twitter style analysis`, `extract writing style`, `style DNA`, `write a tweet`, `write tweets`, `draft a tweet`, `write a thread`, `twitter thread`, `X article`, `X long post`, `imitate tweet style`, `mimic tweet style`, `tweet in the style of`, `write like [account]`, `X account analysis`, `analyze X account`, `ghostwrite tweets`, `how does [account] write`
+- 日本語: `ツイートを書く`, `ツイートスタイル分析`, `スタイルDNA`, `ツイートを模倣`, `Xアカウント分析`, `ツイートのスタイルを抽出`, `〇〇風のツイートを書く`, `ツイートを代筆`, `Xアカウントを分析`, `このアカウントはどう書いている`
+
+**Explicit commands:** `/felo-twitter-writer`, `use felo twitter writer`
+
+**Do NOT use for:**
+
+- General Twitter/X search only (use `felo-x-search`)
+- General SuperAgent conversation (use `felo-superAgent`)
+- Web search (use `felo-search`)
+
+## Two Modes
+
+### Mode 1 — Style DNA Extraction
+
+**When:** User provides a Twitter/X account name and wants to understand or extract its writing style.
+
+**Steps:**
+
+#### Step 1: Fetch tweets via felo-x-search
+
+```bash
+node felo-x-search/scripts/run_x_search.mjs --id "USERNAME" --user --tweets --limit 30
+```
+
+Also fetch the account profile:
+
+```bash
+node felo-x-search/scripts/run_x_search.mjs --id "USERNAME" --user
+```
+
+#### Step 2: Obtain live_doc_id
+
+Follow Constraint #4 above.
+
+#### Step 3: Call SuperAgent with tweet content
+
+Construct a query that includes the fetched tweets and asks for style analysis. Pass `--skill-id twitter-writer` since this is a new conversation.
+
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "ENRICHED_QUERY_WITH_TWEET_CONTENT" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language LANG
+```
+
+**Query construction example:**
+
+> Please analyze the following tweets from @USERNAME and extract a writing style DNA document. Cover dimensions such as: tone, sentence structure, opening hooks, closing calls-to-action, frequently used words, hashtag strategy, emoji usage, and any other distinctive patterns.
+>
+> Account bio: [BIO]
+>
+> Tweets:
+> [TWEET_1]
+> [TWEET_2]
+> ...
+
+Keep the query under 2000 characters. If tweet content is too long, include the most representative 10–15 tweets.
+
+#### Step 4: Save state
+
+Extract `thread_short_id` and `live_doc_short_id` from stderr `[state]` line. Save for follow-up calls.
+
+---
+
+### Mode 2 — Content Creation
+
+**When:** User wants to create tweets, threads, or X long-form posts (with or without a style DNA).
+
+**Steps:**
+
+#### Step 1: Determine if style DNA is available
+
+- If Mode 1 was just run in this session → style DNA is already in the LiveDoc canvas, use follow-up mode
+- If user provides a style DNA directly → include it in the query
+- If user provides an account name → run Mode 1 first, then continue with Mode 2
+- If no style DNA → proceed with general tweet writing (SuperAgent will use its default twitter-writer behavior)
+
+#### Step 2: Obtain live_doc_id
+
+Follow Constraint #4. If Mode 1 was already run, reuse the same `live_doc_id`.
+
+#### Step 3: Determine conversation mode
+
+| Condition | Mode | What to pass |
+|-----------|------|--------------|
+| First call in session, or switching to twitter-writer skill | New conversation | `--live-doc-id` + `--skill-id twitter-writer` |
+| Continuing from Mode 1 or a previous Mode 2 call | Follow-up | `--thread-id` + `--live-doc-id` |
+| User says "new topic" / "start over" | New conversation | `--live-doc-id` + `--skill-id twitter-writer` |
+
+#### Step 4: Call SuperAgent
+
+**New conversation:**
+
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "ENRICHED_QUERY" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language LANG
+```
+
+**Follow-up (iterating on previous output):**
+
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "USER_FOLLOW_UP" \
+  --thread-id "THREAD_SHORT_ID" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --accept-language LANG
+```
+
+**Query construction guidelines:**
+
+- Specify the content type: single tweet / thread / X long-form post
+- Specify the topic clearly
+- Include style DNA or reference account if available
+- Default to 3 versions unless the user specifies otherwise
+- Preserve the user's core intent; only add context and clarity
+
+**Query examples:**
+
+> Please write 3 versions of a tweet about [TOPIC] in the style of @USERNAME (style DNA above). Each version should feel distinct — vary the tone, structure, or angle.
+
+> Based on the style DNA extracted above, write a Twitter thread (5–7 tweets) about [TOPIC]. Start with a strong hook tweet.
+
+> Write an X long-form post about [TOPIC] following the writing style we analyzed. Aim for ~500 words.
+
+#### Step 5: Save state
+
+Extract `thread_short_id` and `live_doc_short_id` from stderr `[state]` line.
+
+---
+
+## Mode Decision Logic
+
+```
+User input
+  │
+  ├── Contains account name + "analyze / style / DNA / how does X write"
+  │   OR: アカウント名 + "分析 / スタイル / DNA / どう書いている"
+  │     → Mode 1 (Style DNA Extraction)
+  │
+  ├── Contains account name + "write / create / imitate / in the style of"
+  │   OR: アカウント名 + "書いて / 作って / 風に / 真似て"
+  │     → Mode 1 first → then Mode 2 (Creation)
+  │
+  ├── Contains topic + "write / draft / tweet / thread / X post"
+  │   OR: トピック + "書いて / ツイート / スレッド / Xの投稿"
+  │     → Mode 2 directly
+  │         └── If no style DNA available: ask user if they want to provide
+  │             a reference account, or proceed with general twitter-writer style
+  │
+  └── Ambiguous (e.g., "help me with tweets" / "ツイートを手伝って")
+        → Ask user: do they want to analyze an account's style, or create content?
+```
+
+---
+
+## Complete Workflow Examples
+
+### Example A: Analyze an account's style
+
+```
+User: "@paulg のツイートスタイルを分析して"
+```
+
+**Step 1:** Fetch tweets:
+```bash
+node felo-x-search/scripts/run_x_search.mjs --id "paulg" --user --tweets --limit 30
+node felo-x-search/scripts/run_x_search.mjs --id "paulg" --user
+```
+
+**Step 2:** Get `live_doc_id` (list or create)
+
+**Step 3:** Call SuperAgent:
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "@paulg のツイートを分析し、文体のスタイルDNAドキュメントを作成してください。トーン、文章構造、冒頭フック、締めのアクション、頻出ワード、ハッシュタグ戦略、絵文字の使い方などを含めてください。\n\nアカウント概要：[BIO]\n\nツイート：\n[TWEETS]" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language ja
+```
+
+**Step 4:** Save `thread_short_id` and `live_doc_short_id` from stderr `[state]`.
+
+---
+
+### Example B: Create tweets with a reference style
+
+```
+User: "@paulg のスタイルでスタートアップについてのツイートを3つ書いて"
+```
+
+**Step 1:** Run Mode 1 to extract style DNA (same as Example A)
+
+**Step 2:** Reuse `live_doc_id` from Mode 1
+
+**Step 3:** Follow-up call (continuing the same thread):
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "上記で抽出した @paulg のスタイルDNAをもとに、「スタートアップ」をテーマにしたツイートを3パターン作成してください。それぞれ異なるトーンや切り口で、280文字以内に収めてください。" \
+  --thread-id "THREAD_SHORT_ID" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --accept-language ja
+```
+
+---
+
+### Example C: Write a thread directly
+
+```
+User: "Write a Twitter thread about why most startups fail"
+```
+
+**Step 1:** No style DNA needed, proceed directly
+
+**Step 2:** Get `live_doc_id`
+
+**Step 3:** New conversation with `twitter-writer`:
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "Write a Twitter thread (6–8 tweets) about why most startups fail. Start with a strong hook tweet that grabs attention. Each tweet should stand alone but flow naturally into the next." \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language en
+```
+
+---
+
+### Example D: Iterate on generated content
+
+```
+User: "2番目のツイートをもっとユーモラスにして、絵文字も追加して"
+```
+
+**Step 1:** Already have `thread_short_id` and `live_doc_id` from the previous call (e.g., Example B or C). No new LiveDoc lookup needed.
+
+**Step 2:** This is a follow-up — pass `--thread-id` with the saved `thread_short_id`.
+
+**Step 3:** Follow-up call:
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "上記で生成した2番目のツイートを修正してください。トーンをよりユーモラスで軽快にし、適切な絵文字を追加してください。内容の意図は変えないでください。" \
+  --thread-id "THREAD_SHORT_ID" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --accept-language ja
+```
+
+**Step 4:** Save updated `thread_short_id` and `live_doc_short_id` from stderr `[state]`.
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Account not found or no tweets returned | Inform user, suggest trying a different username or providing tweet samples manually |
+| `FELO_API_KEY` not set | Stop and show setup instructions (same as `felo-superAgent` SKILL.md) |
+| SuperAgent call fails | Check `live_doc_id` validity; retry once with the same parameters |
+| User asks for Mode 2 with no style DNA and no account | Ask: "Would you like to provide a reference Twitter account to base the style on, or should I write in a general engaging style?" |
+| User explicitly requests a new canvas | Create a new LiveDoc: `node felo-livedoc/scripts/run_livedoc.mjs create --name "Twitter Writer" --json` |
+| Tweet content too long for query (>2000 chars) | Trim to the 10–15 most representative tweets; prioritize high-engagement ones |
+
+## References
+
+- [felo-superAgent SKILL.md](../felo-superAgent/SKILL.md) — SuperAgent calling conventions and constraints
+- [felo-x-search SKILL.md](../felo-x-search/SKILL.md) — X/Twitter search commands
+- [felo-livedoc SKILL.md](../felo-livedoc/SKILL.md) — LiveDoc management commands
+- [Felo Open Platform](https://openapi.felo.ai/docs/)
+- [Get API Key](https://felo.ai) (Settings → API Keys)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "felo-ai",
-  "version": "0.2.42",
+  "version": "0.2.43",
   "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",