felo-ai 0.2.47 → 0.2.49

package/felo-twitter-writer/SKILL.md

@@ -11,21 +11,29 @@ 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.
+2. **ALWAYS use `--json` flag** when calling SuperAgent. 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. After the script finishes, read `data.answer` from the JSON output and print it verbatim as your response text.
 
-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.
+3. **ALWAYS output `data.answer` verbatim.** After the script finishes, print `data.answer` exactly as-is as your response text. Do NOT summarize, paraphrase, or add commentary around it.
 
-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`
+4. **`--live-doc-id` is REQUIRED** for every SuperAgent call. Follow these rules strictly:
+   - Reuse any `live_doc_id` already available in this session (from a prior SuperAgent or livedoc call)
+   - If none: run `node felo-livedoc/scripts/run_livedoc.mjs list --json`, then find the **first item where `is_shared === false`** in `data.items` (list is sorted by modification time descending, so this gives the most recently modified private LiveDoc). Use its `short_id`.
+   - If no `is_shared === false` item exists (or list is empty): run `node felo-livedoc/scripts/run_livedoc.mjs create --name "Twitter Writer" --json`, use `data.short_id`
+   - **NEVER use a LiveDoc where `is_shared === true`** — shared LiveDocs belong to other projects and will cause a 502 error.
 
-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.
+5. **Always persist state.** After every SuperAgent call, extract `thread_short_id` and `live_doc_short_id` from the JSON response fields `data.thread_short_id` and `data.live_doc_short_id`. 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.
 
+8. **Brand style selection for Mode 2 new conversations only.** When starting a new conversation for content creation (Mode 2, no `thread_short_id`), you MUST attempt to fetch the TWITTER style library and offer the user a style choice BEFORE calling SuperAgent. The style is passed via `--ext '{"brand_style_requirement":"..."}'`. Full procedure in the Style Selection section below.
+
+   - Style category is always `TWITTER` (hardcoded — this skill only writes tweets).
+   - `--ext` is only valid for new conversations. Never pass it in follow-up mode (`--thread-id`).
+   - If the style library returns no entries, skip silently and proceed without `--ext`.
+   - Mode 1 (style DNA extraction) does NOT use this step.
+
 ## When to Use
 
 Trigger this skill when the user wants to:
@@ -82,6 +90,8 @@ Determine conversation mode first:
 - If **no** `thread_short_id` exists in this session → new conversation (pass `--skill-id twitter-writer`)
 - If `thread_short_id` **already exists** in this session → follow-up (pass `--thread-id`)
 
+Replace `LANG` with the user's language: `en` (English), `zh` (Chinese), `ja` (Japanese), `ko` (Korean). See Constraint #6.
+
 **New conversation (first call in session):**
 
 ```bash
@@ -89,7 +99,8 @@ node felo-superAgent/scripts/run_superagent.mjs \
   --query "/twitter-writer ENRICHED_QUERY_WITH_TWEET_CONTENT" \
   --live-doc-id "LIVE_DOC_ID" \
   --skill-id twitter-writer \
-  --accept-language LANG
+  --accept-language LANG \
+  --json
 ```
 
 **Follow-up (thread_short_id already exists):**
@@ -99,7 +110,8 @@ node felo-superAgent/scripts/run_superagent.mjs \
   --query "/twitter-writer ENRICHED_QUERY_WITH_TWEET_CONTENT" \
   --thread-id "THREAD_SHORT_ID" \
   --live-doc-id "LIVE_DOC_ID" \
-  --accept-language LANG
+  --accept-language LANG \
+  --json
 ```
 
 **Query construction example:**
@@ -117,7 +129,7 @@ Keep the query under 2000 characters. If tweet content is too long, include the
 
 #### Step 4: Save state
 
-Extract `thread_short_id` and `live_doc_short_id` from stderr `[state]` line. Save for follow-up calls.
+Extract `thread_short_id` and `live_doc_short_id` from the JSON response fields `data.thread_short_id` and `data.live_doc_short_id`. Save for follow-up calls.
 
 ---
 
@@ -132,7 +144,98 @@ Extract `thread_short_id` and `live_doc_short_id` from stderr `[state]` line. Sa
 - 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)
+- If no style DNA → proceed to style library selection (Step 1.5)
+
+#### Step 1.5: Brand Style Selection (new conversations only)
+
+**Only run this step when:**
+- This is a **new conversation** (no `thread_short_id` in session), AND
+- Mode 1 was NOT just run (i.e., there is no existing thread carrying style DNA context)
+
+**Skip this step entirely when:**
+- `thread_short_id` already exists (follow-up) — `--ext` has no effect in follow-up mode
+- Mode 1 was just run in this session — style context is already in the thread
+
+**1.5a. Check if user already specified a style:**
+
+If the user mentioned a style by name (e.g., "use my Bold Voice style") or pasted a style block, note it and skip to step 1.5d.
+
+**1.5b. Fetch the TWITTER style library (names only):**
+
+IMPORTANT: The style library output is very large (each Style DNA can be thousands of characters). Always use `--json` and extract only names/labels to avoid Bash tool output truncation. Never call `run_style_library.mjs` without `--json` for listing purposes.
+
+```bash
+node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language LANG --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?.LANG||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?.LANG||s.content?.labels?.en||[]).join(', '); console.log((user.length+i+1)+'. '+s.name+(labels?' — '+labels:'')); }); }
+if(!list.length) console.log('(No styles found)');
+"
+```
+
+Replace `LANG` with the user's language value (`zh`, `ja`, `ko`, `en`) in both `--accept-language` and inside the node script's `labels?.LANG` references.
+
+Always pass `--accept-language` matching the user's language (same value used for SuperAgent).
+
+**1.5c. Handle the result:**
+
+**If the list is empty:** Skip silently. Proceed to Step 2 without `--ext`.
+
+**If styles are available:** Output the COMPLETE list as plain text — every style returned by the API, grouped by type, numbered sequentially. NEVER use `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 as the last item. Then wait for the user's plain-text reply before proceeding.
+
+Example presentation (adapt language to match user's language):
+```
+以下是可用的推文写作风格，选一个会让输出更贴合你的需求：
+
+[你的风格]
+1. My Bold Voice
+
+[推荐风格]
+2. elonmusk — Shitposting provocateur
+3. naval — Pithy aphorism master
+...（所有风格全部列出，不省略）
+
+0. 无偏好，使用默认风格
+```
+
+**1.5d. Build `--ext` from the chosen style:**
+
+After the user selects a style, fetch the full Style DNA for that specific style using `--json` and extract it in Node.js. Do NOT re-read the full text output — it will be truncated by the Bash tool.
+
+```bash
+node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language LANG --json | node -e "
+const d=require('fs').readFileSync('/dev/stdin','utf8');
+const j=JSON.parse(d);
+const s=(j.list||[]).find(s=>s.name==='CHOSEN_STYLE_NAME');
+if(!s){process.stderr.write('Style not found\n');process.exit(1);}
+const labels=(s.content?.labels?.LANG||s.content?.labels?.en||[]).join(', ');
+const dna=s.content?.styleDna||'';
+const block='Style name: '+s.name+'\nStyle labels: '+labels+'\nStyle DNA: '+dna;
+console.log(JSON.stringify({brand_style_requirement:block}));
+"
+```
+
+Replace `CHOSEN_STYLE_NAME` with the style name the user selected, and `LANG` with the language code.
+
+Pass the output JSON directly as the `--ext` value:
+
+```bash
+--ext "$(node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language LANG --json | node -e "
+const d=require('fs').readFileSync('/dev/stdin','utf8');
+const j=JSON.parse(d);
+const s=(j.list||[]).find(s=>s.name==='CHOSEN_STYLE_NAME');
+const labels=(s.content?.labels?.LANG||s.content?.labels?.en||[]).join(', ');
+const dna=s.content?.styleDna||'';
+const block='Style name: '+s.name+'\nStyle labels: '+labels+'\nStyle DNA: '+dna;
+console.log(JSON.stringify({brand_style_requirement:block}));
+")"
+```
+
+If the user chose "no preference" (option 0), do NOT pass `--ext`.
 
 #### Step 2: Obtain live_doc_id
 
@@ -142,20 +245,35 @@ Follow Constraint #4. If Mode 1 was already run, reuse the same `live_doc_id`.
 
 | Condition | Mode | What to pass |
 |-----------|------|--------------|
-| No `thread_short_id` in this session (truly first call) | New conversation | `--live-doc-id` + `--skill-id twitter-writer` |
-| `thread_short_id` already exists in this session (all subsequent inputs, including after Mode 1) | Follow-up | `--thread-id` + `--live-doc-id` |
-| User says "new topic" / "start over" (clear `thread_short_id`) | New conversation | `--live-doc-id` + `--skill-id twitter-writer` |
+| No `thread_short_id` in this session (truly first call) | New conversation | `--live-doc-id` + `--skill-id twitter-writer` + `--ext` (if style chosen) |
+| `thread_short_id` already exists in this session (all subsequent inputs, including after Mode 1) | Follow-up | `--thread-id` + `--live-doc-id` (NO `--ext`) |
+| User says "new topic" / "start over" (clear `thread_short_id`) | New conversation | `--live-doc-id` + `--skill-id twitter-writer` + `--ext` (repeat Step 1.5) |
 
 #### Step 4: Call SuperAgent
 
-**New conversation (no `thread_short_id` in session):**
+Replace `LANG` with the user's language: `en`, `zh`, `ja`, `ko`. See Constraint #6.
+
+**New conversation without style (no `thread_short_id`, user chose no preference or list was empty):**
+
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "/twitter-writer ENRICHED_QUERY" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language LANG \
+  --json
+```
+
+**New conversation with brand style:**
 
 ```bash
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "/twitter-writer ENRICHED_QUERY" \
   --live-doc-id "LIVE_DOC_ID" \
   --skill-id twitter-writer \
-  --accept-language LANG
+  --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, do NOT truncate）"}' \
+  --accept-language LANG \
+  --json
 ```
 
 **Follow-up (`thread_short_id` already exists in session):**
@@ -165,7 +283,8 @@ node felo-superAgent/scripts/run_superagent.mjs \
   --query "/twitter-writer USER_FOLLOW_UP" \
   --thread-id "THREAD_SHORT_ID" \
   --live-doc-id "LIVE_DOC_ID" \
-  --accept-language LANG
+  --accept-language LANG \
+  --json
 ```
 
 **Query construction guidelines:**
@@ -186,7 +305,7 @@ node felo-superAgent/scripts/run_superagent.mjs \
 
 #### Step 5: Save state
 
-Extract `thread_short_id` and `live_doc_short_id` from stderr `[state]` line.
+Extract `thread_short_id` and `live_doc_short_id` from the JSON response fields `data.thread_short_id` and `data.live_doc_short_id`.
 
 ---
 
@@ -197,17 +316,18 @@ User input
   │
   ├── Contains account name + "analyze / style / DNA / how does X write"
   │   OR: アカウント名 + "分析 / スタイル / DNA / どう書いている"
-  │     → Mode 1 (Style DNA Extraction)
+  │     → Mode 1 (Style DNA Extraction) — skip style library step
   │
   ├── Contains account name + "write / create / imitate / in the style of"
   │   OR: アカウント名 + "書いて / 作って / 風に / 真似て"
-  │     → Mode 1 first → then Mode 2 (Creation)
+  │     → Mode 1 first → then Mode 2 (follow-up, skip style library step)
   │
   ├── 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
+  │         └── New conversation?
+  │               YES → Step 1.5: fetch TWITTER styles, present to user, wait for choice
+  │               NO  → follow-up, skip style library step
   │
   └── Ambiguous (e.g., "help me with tweets" / "ツイートを手伝って")
         → Ask user: do they want to analyze an account's style, or create content?
@@ -231,81 +351,197 @@ 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 (first call in session — no `thread_short_id` yet):
+**Step 3:** Call SuperAgent (Mode 1 — no style library step):
 ```bash
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "/twitter-writer @paulg のツイートを分析し、文体のスタイルDNAドキュメントを作成してください。トーン、文章構造、冒頭フック、締めのアクション、頻出ワード、ハッシュタグ戦略、絵文字の使い方などを含めてください。\n\nアカウント概要：[BIO]\n\nツイート：\n[TWEETS]" \
   --live-doc-id "LIVE_DOC_ID" \
   --skill-id twitter-writer \
-  --accept-language ja
+  --accept-language ja \
+  --json
 ```
 
-**Step 4:** Save `thread_short_id` and `live_doc_short_id` from stderr `[state]`.
+**Step 4:** Save `thread_short_id` and `live_doc_short_id` from JSON response fields `data.thread_short_id` and `data.live_doc_short_id`.
 
 ---
 
-### Example B: Create tweets with a reference style
+### Example B: Create tweets with a reference style (Mode 1 → Mode 2)
 
 ```
 User: "@paulg のスタイルでスタートアップについてのツイートを3つ書いて"
 ```
 
-**Step 1:** Run Mode 1 to extract style DNA (same as Example A)
+**Step 1:** Run Mode 1 to extract style DNA (same as Example A). Style library step is skipped because Mode 1 already establishes style context in the thread.
 
-**Step 2:** Reuse `live_doc_id` from Mode 1
+**Step 2:** Reuse `live_doc_id` from Mode 1.
 
-**Step 3:** Follow-up call (continuing the same thread — `thread_short_id` from Example A):
+**Step 3:** Follow-up call (continuing the same thread — `thread_short_id` from Mode 1, no `--ext`):
 ```bash
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "/twitter-writer 上記で抽出した @paulg のスタイルDNAをもとに、「スタートアップ」をテーマにしたツイートを3パターン作成してください。それぞれ異なるトーンや切り口で、280文字以内に収めてください。" \
   --thread-id "THREAD_SHORT_ID" \
   --live-doc-id "LIVE_DOC_ID" \
-  --accept-language ja
+  --accept-language ja \
+  --json
 ```
 
 ---
 
-### Example C: Write a thread directly
+### Example C: Write a thread directly (Mode 2, new conversation, with style selection)
 
 ```
 User: "Write a Twitter thread about why most startups fail"
 ```
 
-**Step 1:** No style DNA needed, proceed directly
+**Step 1.5:** New conversation, no existing thread → fetch TWITTER styles (names only):
+```bash
+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)');
+"
+```
+
+Present to user:
+```
+Here are the available Twitter writing styles — choosing one will make the output more accurate:
+
+[Your styles]
+1. My Bold Voice
 
-**Step 2:** Get `live_doc_id`
+[Recommended styles]
+2. darioamodei
 
-**Step 3:** New conversation with `twitter-writer` (first call in session — no `thread_short_id` yet):
+0. No preference — use default style
+```
+
+User replies: `1`
+
+**Step 2:** Get `live_doc_id`.
+
+**Step 3:** New conversation with chosen style — extract full Style DNA via `--json` and pass as `--ext`:
 ```bash
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "/twitter-writer 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
+  --ext "$(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 s=(j.list||[]).find(s=>s.name==='My Bold Voice');
+const labels=(s.content?.labels?.en||[]).join(', ');
+const block='Style name: '+s.name+'\nStyle labels: '+labels+'\nStyle DNA: '+s.content.styleDna;
+console.log(JSON.stringify({brand_style_requirement:block}));
+")" \
+  --accept-language en \
+  --json
 ```
 
+**Step 4:** Save `thread_short_id` and `live_doc_short_id` from JSON response fields `data.thread_short_id` and `data.live_doc_short_id`.
+
 ---
 
-### Example D: Iterate on generated content
+### Example D: Iterate on generated content (follow-up, no style step)
 
 ```
 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`.
+Already have `thread_short_id` and `live_doc_id` from the previous call. This is a follow-up — do NOT fetch styles again, do NOT pass `--ext`.
 
-**Step 3:** Follow-up call (`thread_short_id` already exists in session):
 ```bash
 node felo-superAgent/scripts/run_superagent.mjs \
   --query "/twitter-writer 上記で生成した2番目のツイートを修正してください。トーンをよりユーモラスで軽快にし、適切な絵文字を追加してください。内容の意図は変えないでください。" \
   --thread-id "THREAD_SHORT_ID" \
   --live-doc-id "LIVE_DOC_ID" \
-  --accept-language ja
+  --accept-language ja \
+  --json
+```
+
+**Save** updated `thread_short_id` and `live_doc_short_id` from JSON response fields `data.thread_short_id` and `data.live_doc_short_id`.
+
+---
+
+### Example E: User specifies style by name
+
+```
+User: "Write a tweet about AI trends using my 'Bold Voice' style"
+```
+
+**Step 1.5a:** User already named the style → extract full Style DNA via `--json`. No need to ask the user again.
+
+**Step 3:** New conversation with that style:
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "/twitter-writer Write a tweet about AI trends" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --ext "$(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 s=(j.list||[]).find(s=>s.name==='My Bold Voice');
+const labels=(s.content?.labels?.en||[]).join(', ');
+const block='Style name: '+s.name+'\nStyle labels: '+labels+'\nStyle DNA: '+s.content.styleDna;
+console.log(JSON.stringify({brand_style_requirement:block}));
+")" \
+  --accept-language en \
+  --json
+```
+
+---
+
+### Example F: Style library is empty
+
+```
+User: "Write a tweet about the new product launch"
+```
+
+**Step 1.5b:** Fetch styles (names only):
+```bash
+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);
+if(!(j.list||[]).length)console.log('(No styles found)');
+else console.log((j.list||[]).map(s=>s.name).join('\n'));
+"
+```
+
+Output: `(No styles found)`
+
+**Skip silently.** Proceed directly without `--ext`:
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "/twitter-writer Write a tweet about the new product launch. Provide 3 versions with different tones." \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language en \
+  --json
 ```
 
-**Step 4:** Save updated `thread_short_id` and `live_doc_short_id` from stderr `[state]`.
+---
+
+### Example G: User chooses no preference
+
+```
+User: "帮我写一条关于新产品发布的推文"
+```
+
+**Step 1.5:** Fetch styles, present list. User replies: `0` (no preference).
+
+Proceed without `--ext`:
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "/twitter-writer 帮我写3条关于新产品发布的推文，每条风格略有不同。" \
+  --live-doc-id "LIVE_DOC_ID" \
+  --skill-id twitter-writer \
+  --accept-language zh \
+  --json
+```
 
 ---
 
@@ -316,13 +552,14 @@ node felo-superAgent/scripts/run_superagent.mjs \
 | 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?" |
+| Style library fetch fails | Log warning to stderr, skip silently, proceed without `--ext` |
+| User asks for Mode 2 with no style DNA and no account | Proceed to Step 1.5 (style library selection) |
 | 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-superAgent SKILL.md](../felo-superAgent/SKILL.md) — SuperAgent calling conventions, `--ext` format, and style library script
 - [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/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "felo-ai",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "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,7 +4,7 @@ import { createRequire } from "module";
 import { Command } from "commander";
 import { search } from "./search.js";
 import { slides, listPptThemes } from "./slides.js";
-import { superAgent, listLiveDocs, listLiveDocResources } from "./superAgent.js";
+import { superAgent, listLiveDocs, listLiveDocResources, listStyleLibrary } from "./superAgent.js";
 import { appleBuyAdvisor } from "./appleBuyAdvisor.js";
 import { webFetch } from "./webFetch.js";
 import { youtubeSubtitling } from "./youtubeSubtitling.js";
@@ -1049,4 +1049,22 @@ program
     flushStdioThenExit(1);
   });
 
+program
+  .command("style-library")
+  .description("List style library entries for a given category (TWITTER, INSTAGRAM, LEMON8, NOTECOM, WEBSITE, IMAGE)")
+  .argument("<category>", "style category (e.g. TWITTER)")
+  .option("-j, --json", "output raw JSON")
+  .option("--accept-language <lang>", "language for labels/tags (e.g. en, zh-Hans, ja)", "en")
+  .option("-t, --timeout <seconds>", "request timeout in seconds", "60")
+  .action(async (category, opts) => {
+    const timeoutMs = parseInt(opts.timeout, 10) * 1000;
+    const code = await listStyleLibrary(category, {
+      json: opts.json,
+      acceptLanguage: opts.acceptLanguage || 'en',
+      timeoutMs: Number.isNaN(timeoutMs) ? 60000 : timeoutMs,
+    });
+    process.exitCode = code;
+    flushStdioThenExit(code);
+  });
+
 program.parse();

package/src/superAgent.js

@@ -789,3 +789,136 @@ export async function superAgent(query, options = {}) {
     return 1;
   }
 }
+
+/**
+ * Pick the best matching value from a multilingual map object.
+ * Falls back: exact match → base language (e.g. "zh" for "zh-Hans") → "en" → first available.
+ * Returns an array (may be empty).
+ * @param {Object} map - Multilingual map, e.g. { en: [...], "zh-Hans": [...] }
+ * @param {string} lang - Preferred language code.
+ */
+function pickLangValue(map, lang) {
+  if (!map || typeof map !== 'object') return [];
+  if (map[lang]) return map[lang];
+  const base = lang.split('-')[0];
+  if (base !== lang && map[base]) return map[base];
+  if (map['en']) return map['en'];
+  const first = Object.values(map)[0];
+  return Array.isArray(first) ? first : [];
+}
+
+/**
+ * Format a single style entry into the brand_style_requirement string.
+ *   Style name: <name>
+ *   Style labels: <label1, label2>   (from content.labels or content.tags, language-aware)
+ *   Style DNA: <styleDna>            (from content.styleDna, TWITTER type)
+ *   Cover file ID: <coverFileId>     (omitted if null/empty)
+ * @param {Object} s - Style entry from API.
+ * @param {string} lang - Language code for labels/tags.
+ */
+function formatStyleEntry(s, lang) {
+  const lines = [];
+
+  lines.push(`Style name: ${s.name ?? ''}`);
+
+  const content = s.content ?? {};
+
+  // Labels — multilingual map (content.labels for TWITTER, content.tags for others)
+  const labelsMap = content.labels ?? content.tags ?? null;
+  if (labelsMap) {
+    const labelArr = pickLangValue(labelsMap, lang);
+    if (labelArr.length > 0) {
+      lines.push(`Style labels: ${labelArr.join(', ')}`);
+    }
+  }
+
+  // Style DNA (TWITTER type)
+  if (typeof content.styleDna === 'string' && content.styleDna.trim()) {
+    lines.push(`Style DNA: ${content.styleDna.trim()}`);
+  }
+
+  // Cover file ID — omit if null/empty
+  const coverId = s.coverFileId ?? s.cover_file_id ?? null;
+  if (coverId) {
+    lines.push(`Cover file ID: ${coverId}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * List style library entries for a given category.
+ * @param {string} category - Style category (e.g. TWITTER, INSTAGRAM, LEMON8, NOTECOM, WEBSITE, IMAGE).
+ * @param {Object} [options]
+ * @param {boolean} [options.json] - Output raw JSON.
+ * @param {string} [options.acceptLanguage] - Language code for labels/tags (e.g. en, zh-Hans, ja). Default: en.
+ * @param {number} [options.timeoutMs] - Request timeout in ms.
+ * @returns {Promise<number>} Exit code 0 or 1.
+ */
+export async function listStyleLibrary(category, options = {}) {
+  const apiKey = await getApiKey();
+  if (!apiKey) {
+    process.stderr.write(NO_KEY_MESSAGE.trim() + '\n');
+    return 1;
+  }
+
+  const apiBase = await getApiBase();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const lang = options.acceptLanguage || 'en';
+
+  const params = new URLSearchParams();
+  params.set('category', category);
+
+  const url = `${apiBase}/v2/brand/style-library/list?${params.toString()}`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      signal: controller.signal,
+    });
+
+    let data = {};
+    try {
+      data = await res.json();
+    } catch {
+      data = {};
+    }
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${getMessage(data)}`);
+    }
+    if (isApiError(data)) {
+      throw new Error(getMessage(data));
+    }
+
+    const list = data?.data?.list ?? [];
+
+    if (options.json) {
+      console.log(JSON.stringify(data?.data ?? {}, null, 2));
+    } else {
+      if (list.length === 0) {
+        console.log('(No styles found)');
+      } else {
+        const userStyles = list.filter((s) => !s.recommended);
+        const recommendedStyles = list.filter((s) => s.recommended);
+        const allFormatted = [...userStyles, ...recommendedStyles].map((s) => formatStyleEntry(s, lang));
+        console.log(allFormatted.join('\n\n'));
+      }
+    }
+
+    return 0;
+  } catch (err) {
+    const msg = err?.message || err;
+    process.stderr.write(`Error: ${msg}\n`);
+    return 1;
+  } finally {
+    clearTimeout(timer);
+  }
+}