SaylorTwift HF Staff commited on
Commit
674d56a
·
verified ·
1 Parent(s): 6aa76ed

Add files using upload-large-folder tool

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. optional-skills/blockchain/hyperliquid/scripts/hyperliquid_client.py +1660 -0
  2. optional-skills/creative/ai-presenter-video/LICENSE +21 -0
  3. optional-skills/creative/ai-presenter-video/SKILL.md +196 -0
  4. optional-skills/creative/ai-presenter-video/assets/job.template.json +83 -0
  5. optional-skills/creative/ai-presenter-video/references/editing.md +65 -0
  6. optional-skills/creative/ai-presenter-video/references/generation.md +83 -0
  7. optional-skills/creative/ai-presenter-video/references/qa-recovery.md +73 -0
  8. optional-skills/creative/ai-presenter-video/scripts/finalize_delivery.sh +166 -0
  9. optional-skills/creative/ai-presenter-video/scripts/init_job.py +151 -0
  10. optional-skills/creative/ai-presenter-video/scripts/preflight.py +177 -0
  11. optional-skills/creative/archify/SKILL.md +52 -0
  12. optional-skills/creative/ascii-art/SKILL.md +322 -0
  13. optional-skills/creative/audiocraft-audio-generation/SKILL.md +569 -0
  14. optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md +666 -0
  15. optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md +504 -0
  16. optional-skills/creative/baoyu-article-illustrator/PORT_NOTES.md +48 -0
  17. optional-skills/creative/baoyu-article-illustrator/SKILL.md +207 -0
  18. optional-skills/creative/baoyu-article-illustrator/prompts/system.md +32 -0
  19. optional-skills/creative/baoyu-article-illustrator/references/palettes/macaron.md +33 -0
  20. optional-skills/creative/baoyu-article-illustrator/references/palettes/mono-ink.md +42 -0
  21. optional-skills/creative/baoyu-article-illustrator/references/palettes/neon.md +33 -0
  22. optional-skills/creative/baoyu-article-illustrator/references/palettes/warm.md +32 -0
  23. optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md +426 -0
  24. optional-skills/creative/baoyu-article-illustrator/references/style-presets.md +80 -0
  25. optional-skills/creative/baoyu-article-illustrator/references/styles.md +224 -0
  26. optional-skills/creative/baoyu-article-illustrator/references/styles/blueprint.md +57 -0
  27. optional-skills/creative/baoyu-article-illustrator/references/styles/chalkboard.md +62 -0
  28. optional-skills/creative/baoyu-article-illustrator/references/styles/editorial.md +59 -0
  29. optional-skills/creative/baoyu-article-illustrator/references/styles/elegant.md +56 -0
  30. optional-skills/creative/baoyu-article-illustrator/references/styles/fantasy-animation.md +58 -0
  31. optional-skills/creative/baoyu-article-illustrator/references/styles/flat-doodle.md +61 -0
  32. optional-skills/creative/baoyu-article-illustrator/references/styles/flat.md +59 -0
  33. optional-skills/creative/baoyu-article-illustrator/references/styles/ink-notes.md +90 -0
  34. optional-skills/creative/baoyu-article-illustrator/references/styles/intuition-machine.md +57 -0
  35. optional-skills/creative/baoyu-article-illustrator/references/styles/minimal.md +58 -0
  36. optional-skills/creative/baoyu-article-illustrator/references/styles/nature.md +58 -0
  37. optional-skills/creative/baoyu-article-illustrator/references/styles/notion.md +58 -0
  38. optional-skills/creative/baoyu-article-illustrator/references/styles/pixel-art.md +57 -0
  39. optional-skills/creative/baoyu-article-illustrator/references/styles/playful.md +59 -0
  40. optional-skills/creative/baoyu-article-illustrator/references/styles/retro.md +59 -0
  41. optional-skills/creative/baoyu-article-illustrator/references/styles/scientific.md +59 -0
  42. optional-skills/creative/baoyu-article-illustrator/references/styles/screen-print.md +70 -0
  43. optional-skills/creative/baoyu-article-illustrator/references/styles/sketch-notes.md +56 -0
  44. optional-skills/creative/baoyu-article-illustrator/references/styles/sketch.md +57 -0
  45. optional-skills/creative/baoyu-article-illustrator/references/styles/vector-illustration.md +57 -0
  46. optional-skills/creative/baoyu-article-illustrator/references/styles/vintage.md +59 -0
  47. optional-skills/creative/baoyu-article-illustrator/references/styles/warm.md +58 -0
  48. optional-skills/creative/baoyu-article-illustrator/references/styles/watercolor.md +58 -0
  49. optional-skills/creative/baoyu-article-illustrator/references/usage.md +50 -0
  50. optional-skills/creative/baoyu-article-illustrator/references/workflow.md +332 -0
optional-skills/blockchain/hyperliquid/scripts/hyperliquid_client.py ADDED
@@ -0,0 +1,1660 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """
3
+ Hyperliquid CLI Tool for Hermes Agent
4
+ -------------------------------------
5
+ Queries the Hyperliquid info endpoint for market and account data.
6
+ Uses only Python standard library - no external packages required.
7
+
8
+ Usage:
9
+ python3 hyperliquid_client.py dexs
10
+ python3 hyperliquid_client.py markets [--dex DEX] [--limit N]
11
+ python3 hyperliquid_client.py spots [--limit N]
12
+ python3 hyperliquid_client.py candles <coin> [--interval 1h] [--hours 24]
13
+ python3 hyperliquid_client.py funding <coin> [--hours 72]
14
+ python3 hyperliquid_client.py l2 <coin> [--levels 10]
15
+ python3 hyperliquid_client.py state [address] [--dex DEX]
16
+ python3 hyperliquid_client.py spot-balances [address]
17
+ python3 hyperliquid_client.py fills [address] [--hours N] [--limit N]
18
+ python3 hyperliquid_client.py orders [address] [--limit N]
19
+ python3 hyperliquid_client.py review [address] [--coin COIN] [--hours N]
20
+ python3 hyperliquid_client.py export <coin> [--interval 1h] [--hours N]
21
+
22
+ Environment:
23
+ HYPERLIQUID_API_URL Override API base URL
24
+ (default: https://api.hyperliquid.xyz)
25
+ HYPERLIQUID_USER_ADDRESS Default address for state/fills/orders/review commands
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import argparse
31
+ import datetime as dt
32
+ import json
33
+ import os
34
+ import sys
35
+ import time
36
+ import urllib.error
37
+ import urllib.request
38
+ from collections import Counter
39
+ from pathlib import Path
40
+ from typing import Any, Dict, Iterable, List, Optional
41
+
42
+
43
+ USER_AGENT = "HermesAgent/1.0"
44
+ DEFAULT_USER_ENV = "HYPERLIQUID_USER_ADDRESS"
45
+ DEFAULT_API_BASE = "https://api.hyperliquid.xyz"
46
+
47
+
48
+ def _hermes_home() -> Path:
49
+ return Path(os.environ.get("HERMES_HOME", "~/.hermes")).expanduser()
50
+
51
+
52
+ def _dotenv_paths() -> List[Path]:
53
+ paths: List[Path] = []
54
+ project_env = Path.cwd() / ".env"
55
+ if project_env.exists():
56
+ paths.append(project_env)
57
+
58
+ user_env = _hermes_home() / ".env"
59
+ if user_env.exists():
60
+ paths.append(user_env)
61
+
62
+ return paths
63
+
64
+
65
+ def _load_dotenv_values() -> Dict[str, str]:
66
+ values: Dict[str, str] = {}
67
+ for env_path in _dotenv_paths():
68
+ try:
69
+ lines = env_path.read_text(encoding="utf-8").splitlines()
70
+ except UnicodeDecodeError:
71
+ lines = env_path.read_text(encoding="latin-1").splitlines()
72
+
73
+ for raw_line in lines:
74
+ line = raw_line.strip()
75
+ if not line or line.startswith("#") or "=" not in line:
76
+ continue
77
+ key, _, value = raw_line.partition("=")
78
+ key = key.strip()
79
+ value = value.strip()
80
+ if value.startswith('"') and value.endswith('"') and len(value) >= 2:
81
+ value = value[1:-1].replace('\\"', '"').replace('\\\\', '\\')
82
+ values[key] = value
83
+ return values
84
+
85
+
86
+ def _env_lookup(key: str, default: str = "") -> str:
87
+ value = os.environ.get(key, "").strip()
88
+ if value:
89
+ return value
90
+ dotenv_value = _load_dotenv_values().get(key, "").strip()
91
+ if dotenv_value:
92
+ return dotenv_value
93
+ return default
94
+
95
+
96
+ def _api_base() -> str:
97
+ return _env_lookup("HYPERLIQUID_API_URL", DEFAULT_API_BASE).rstrip("/")
98
+
99
+
100
+ def _info_url() -> str:
101
+ api_base = _api_base()
102
+ if api_base.endswith("/info"):
103
+ return api_base
104
+ return f"{api_base}/info"
105
+
106
+
107
+ def _resolve_user(user: Optional[str]) -> str:
108
+ candidate = (user or "").strip()
109
+ if candidate:
110
+ return candidate
111
+
112
+ env_value = _env_lookup(DEFAULT_USER_ENV, "")
113
+ if env_value:
114
+ return env_value
115
+
116
+ sys.exit(
117
+ "Missing Hyperliquid address. Pass <address> explicitly or set "
118
+ f"{DEFAULT_USER_ENV} in your environment or {_hermes_home() / '.env'}."
119
+ )
120
+
121
+
122
+ def _post_info(payload: Dict[str, Any], timeout: int = 20, retries: int = 2) -> Any:
123
+ data = json.dumps(payload).encode("utf-8")
124
+ headers = {
125
+ "Content-Type": "application/json",
126
+ "Accept": "application/json",
127
+ "User-Agent": USER_AGENT,
128
+ }
129
+
130
+ for attempt in range(retries + 1):
131
+ request = urllib.request.Request(_info_url(), data=data, headers=headers, method="POST")
132
+ try:
133
+ with urllib.request.urlopen(request, timeout=timeout) as response:
134
+ body = json.load(response)
135
+ return body
136
+ except urllib.error.HTTPError as exc:
137
+ if exc.code == 429 and attempt < retries:
138
+ time.sleep(1.5 * (attempt + 1))
139
+ continue
140
+ sys.exit(f"Hyperliquid HTTP error: {exc}")
141
+ except urllib.error.URLError as exc:
142
+ sys.exit(f"Hyperliquid connection error: {exc}")
143
+ except json.JSONDecodeError as exc:
144
+ sys.exit(f"Hyperliquid response was not valid JSON: {exc}")
145
+
146
+ return None
147
+
148
+
149
+ def _safe_float(value: Any) -> Optional[float]:
150
+ try:
151
+ if value is None or value == "":
152
+ return None
153
+ return float(value)
154
+ except (TypeError, ValueError):
155
+ return None
156
+
157
+
158
+ def _limit_items(items: List[Dict[str, Any]], limit: int) -> List[Dict[str, Any]]:
159
+ if limit <= 0:
160
+ return items
161
+ return items[:limit]
162
+
163
+
164
+ def _hours_ago_ms(hours: float, now_ms: Optional[int] = None) -> int:
165
+ end_ms = now_ms if now_ms is not None else int(time.time() * 1000)
166
+ return end_ms - int(hours * 60 * 60 * 1000)
167
+
168
+
169
+ def _format_timestamp_ms(value: Any) -> str:
170
+ try:
171
+ ts_ms = int(value)
172
+ except (TypeError, ValueError):
173
+ return "-"
174
+ return dt.datetime.utcfromtimestamp(ts_ms / 1000).strftime("%Y-%m-%d %H:%M:%S UTC")
175
+
176
+
177
+ def _compact_number(value: Any, decimals: int = 2) -> str:
178
+ number = _safe_float(value)
179
+ if number is None:
180
+ return "-"
181
+ sign = "-" if number < 0 else ""
182
+ number = abs(number)
183
+ if number >= 1_000_000_000:
184
+ return f"{sign}{number / 1_000_000_000:.{decimals}f}B"
185
+ if number >= 1_000_000:
186
+ return f"{sign}{number / 1_000_000:.{decimals}f}M"
187
+ if number >= 1_000:
188
+ return f"{sign}{number / 1_000:.{decimals}f}K"
189
+ if number >= 100:
190
+ return f"{sign}{number:.2f}"
191
+ if number >= 1:
192
+ return f"{sign}{number:.4f}".rstrip("0").rstrip(".")
193
+ return f"{sign}{number:.6f}".rstrip("0").rstrip(".")
194
+
195
+
196
+ def _format_price(value: Any) -> str:
197
+ number = _safe_float(value)
198
+ if number is None:
199
+ return "-"
200
+ if abs(number) >= 1000:
201
+ return f"{number:,.2f}"
202
+ if abs(number) >= 1:
203
+ return f"{number:,.4f}".rstrip("0").rstrip(".")
204
+ return f"{number:,.6f}".rstrip("0").rstrip(".")
205
+
206
+
207
+ def _format_percent(value: Any, decimals: int = 2) -> str:
208
+ number = _safe_float(value)
209
+ if number is None:
210
+ return "-"
211
+ return f"{number:+.{decimals}f}%"
212
+
213
+
214
+ def _format_fraction_percent(value: Any, decimals: int = 4) -> str:
215
+ number = _safe_float(value)
216
+ if number is None:
217
+ return "-"
218
+ return f"{number * 100:+.{decimals}f}%"
219
+
220
+
221
+ def _percent_change(current: Any, previous: Any) -> Optional[float]:
222
+ curr = _safe_float(current)
223
+ prev = _safe_float(previous)
224
+ if curr is None or prev is None or prev == 0:
225
+ return None
226
+ return ((curr - prev) / prev) * 100
227
+
228
+
229
+ def _short_address(address: Any) -> str:
230
+ if not isinstance(address, str) or len(address) < 12:
231
+ return str(address)
232
+ return f"{address[:6]}...{address[-4:]}"
233
+
234
+
235
+ def _render_table(headers: List[tuple[str, str]], rows: List[Dict[str, Any]]) -> str:
236
+ if not rows:
237
+ return "(no data)"
238
+
239
+ prepared_rows: List[List[str]] = []
240
+ widths = [len(label) for label, _ in headers]
241
+
242
+ for row in rows:
243
+ rendered = []
244
+ for index, (_label, key) in enumerate(headers):
245
+ value = row.get(key, "")
246
+ text = str(value)
247
+ rendered.append(text)
248
+ if len(text) > widths[index]:
249
+ widths[index] = len(text)
250
+ prepared_rows.append(rendered)
251
+
252
+ lines = []
253
+ header_line = " ".join(label.ljust(widths[idx]) for idx, (label, _key) in enumerate(headers))
254
+ separator = " ".join("-" * widths[idx] for idx in range(len(headers)))
255
+ lines.extend([header_line, separator])
256
+
257
+ for rendered in prepared_rows:
258
+ lines.append(" ".join(rendered[idx].ljust(widths[idx]) for idx in range(len(rendered))))
259
+ return "\n".join(lines)
260
+
261
+
262
+ def _normalize_dexs(payload: Any) -> List[Dict[str, Any]]:
263
+ rows: List[Dict[str, Any]] = []
264
+ if not isinstance(payload, list):
265
+ return rows
266
+
267
+ for index, item in enumerate(payload):
268
+ if item is None:
269
+ rows.append(
270
+ {
271
+ "index": index,
272
+ "name": "",
273
+ "label": "first-perp-dex",
274
+ "full_name": "First perp dex",
275
+ "deployer": "-",
276
+ "asset_caps": 0,
277
+ }
278
+ )
279
+ continue
280
+
281
+ if not isinstance(item, dict):
282
+ continue
283
+
284
+ caps = item.get("assetToStreamingOiCap") or []
285
+ rows.append(
286
+ {
287
+ "index": index,
288
+ "name": item.get("name", ""),
289
+ "label": item.get("name") or "first-perp-dex",
290
+ "full_name": item.get("fullName") or "-",
291
+ "deployer": item.get("deployer") or "-",
292
+ "asset_caps": len(caps) if isinstance(caps, list) else 0,
293
+ }
294
+ )
295
+ return rows
296
+
297
+
298
+ def _normalize_perp_markets(payload: Any) -> List[Dict[str, Any]]:
299
+ if not isinstance(payload, list) or len(payload) < 2:
300
+ return []
301
+
302
+ meta = payload[0] if isinstance(payload[0], dict) else {}
303
+ ctxs = payload[1] if isinstance(payload[1], list) else []
304
+ universe = meta.get("universe") if isinstance(meta, dict) else []
305
+ if not isinstance(universe, list):
306
+ return []
307
+
308
+ rows: List[Dict[str, Any]] = []
309
+ for index, spec in enumerate(universe):
310
+ if not isinstance(spec, dict):
311
+ continue
312
+ ctx = ctxs[index] if index < len(ctxs) and isinstance(ctxs[index], dict) else {}
313
+ mark_px = ctx.get("markPx") or ctx.get("midPx") or ctx.get("oraclePx")
314
+ row = {
315
+ "coin": spec.get("name", f"asset-{index}"),
316
+ "mark_px": mark_px,
317
+ "mid_px": ctx.get("midPx"),
318
+ "oracle_px": ctx.get("oraclePx"),
319
+ "prev_day_px": ctx.get("prevDayPx"),
320
+ "change_pct": _percent_change(mark_px, ctx.get("prevDayPx")),
321
+ "funding": ctx.get("funding"),
322
+ "premium": ctx.get("premium"),
323
+ "open_interest": ctx.get("openInterest"),
324
+ "day_ntl_vlm": ctx.get("dayNtlVlm"),
325
+ "day_base_vlm": ctx.get("dayBaseVlm"),
326
+ "max_leverage": spec.get("maxLeverage"),
327
+ "sz_decimals": spec.get("szDecimals"),
328
+ "is_delisted": bool(spec.get("isDelisted")),
329
+ "only_isolated": bool(spec.get("onlyIsolated")),
330
+ "margin_mode": spec.get("marginMode") or "-",
331
+ }
332
+ rows.append(row)
333
+ return rows
334
+
335
+
336
+ def _normalize_spot_markets(payload: Any) -> List[Dict[str, Any]]:
337
+ if not isinstance(payload, list) or len(payload) < 2:
338
+ return []
339
+
340
+ meta = payload[0] if isinstance(payload[0], dict) else {}
341
+ ctxs = payload[1] if isinstance(payload[1], list) else []
342
+ pairs = meta.get("universe") if isinstance(meta, dict) else []
343
+ tokens = meta.get("tokens") if isinstance(meta, dict) else []
344
+ token_lookup = {}
345
+ if isinstance(tokens, list):
346
+ for token in tokens:
347
+ if isinstance(token, dict) and "index" in token:
348
+ token_lookup[token["index"]] = token.get("name", str(token["index"]))
349
+
350
+ rows: List[Dict[str, Any]] = []
351
+ if not isinstance(pairs, list):
352
+ return rows
353
+
354
+ for index, pair in enumerate(pairs):
355
+ if not isinstance(pair, dict):
356
+ continue
357
+ ctx = ctxs[index] if index < len(ctxs) and isinstance(ctxs[index], dict) else {}
358
+ raw_name = pair.get("name", f"@{index}")
359
+ tokens_for_pair = pair.get("tokens") if isinstance(pair.get("tokens"), list) else []
360
+ display_name = raw_name
361
+ if "/" not in raw_name and len(tokens_for_pair) == 2:
362
+ base = token_lookup.get(tokens_for_pair[0], str(tokens_for_pair[0]))
363
+ quote = token_lookup.get(tokens_for_pair[1], str(tokens_for_pair[1]))
364
+ display_name = f"{base}/{quote} ({raw_name})"
365
+
366
+ mark_px = ctx.get("markPx") or ctx.get("midPx")
367
+ rows.append(
368
+ {
369
+ "pair": raw_name,
370
+ "display_name": display_name,
371
+ "mark_px": mark_px,
372
+ "mid_px": ctx.get("midPx"),
373
+ "prev_day_px": ctx.get("prevDayPx"),
374
+ "change_pct": _percent_change(mark_px, ctx.get("prevDayPx")),
375
+ "day_ntl_vlm": ctx.get("dayNtlVlm"),
376
+ }
377
+ )
378
+ return rows
379
+
380
+
381
+ def _normalize_candles(payload: Any) -> List[Dict[str, Any]]:
382
+ rows: List[Dict[str, Any]] = []
383
+ if not isinstance(payload, list):
384
+ return rows
385
+
386
+ for candle in payload:
387
+ if not isinstance(candle, dict):
388
+ continue
389
+ rows.append(
390
+ {
391
+ "time": candle.get("t") or candle.get("time"),
392
+ "open": candle.get("o"),
393
+ "high": candle.get("h"),
394
+ "low": candle.get("l"),
395
+ "close": candle.get("c"),
396
+ "volume": candle.get("v"),
397
+ "trades": candle.get("n"),
398
+ }
399
+ )
400
+
401
+ rows.sort(key=lambda item: int(item.get("time") or 0))
402
+ return rows
403
+
404
+
405
+ def _normalize_funding_history(payload: Any) -> List[Dict[str, Any]]:
406
+ rows: List[Dict[str, Any]] = []
407
+ if not isinstance(payload, list):
408
+ return rows
409
+
410
+ for item in payload:
411
+ if not isinstance(item, dict):
412
+ continue
413
+ rows.append(
414
+ {
415
+ "coin": item.get("coin", "-"),
416
+ "funding_rate": item.get("fundingRate"),
417
+ "premium": item.get("premium"),
418
+ "time": item.get("time"),
419
+ }
420
+ )
421
+
422
+ rows.sort(key=lambda item: int(item.get("time") or 0))
423
+ return rows
424
+
425
+
426
+ def _normalize_book_levels(payload: Any) -> Dict[str, List[Dict[str, Any]]]:
427
+ if not isinstance(payload, dict):
428
+ return {"bids": [], "asks": []}
429
+
430
+ levels = payload.get("levels")
431
+ if not isinstance(levels, list) or len(levels) < 2:
432
+ return {"bids": [], "asks": []}
433
+
434
+ def convert(side: Iterable[Any]) -> List[Dict[str, Any]]:
435
+ converted = []
436
+ for entry in side:
437
+ if isinstance(entry, dict):
438
+ converted.append(
439
+ {
440
+ "px": entry.get("px"),
441
+ "sz": entry.get("sz"),
442
+ "orders": entry.get("n"),
443
+ }
444
+ )
445
+ elif isinstance(entry, (list, tuple)) and len(entry) >= 2:
446
+ converted.append(
447
+ {
448
+ "px": entry[0],
449
+ "sz": entry[1],
450
+ "orders": entry[2] if len(entry) > 2 else None,
451
+ }
452
+ )
453
+ return converted
454
+
455
+ return {"bids": convert(levels[0]), "asks": convert(levels[1])}
456
+
457
+
458
+ def _normalize_positions(payload: Any) -> Dict[str, Any]:
459
+ if not isinstance(payload, dict):
460
+ return {"summary": {}, "positions": []}
461
+
462
+ positions: List[Dict[str, Any]] = []
463
+ for item in payload.get("assetPositions", []):
464
+ if not isinstance(item, dict):
465
+ continue
466
+ position = item.get("position") if isinstance(item.get("position"), dict) else item
467
+ if not isinstance(position, dict):
468
+ continue
469
+ leverage = position.get("leverage") if isinstance(position.get("leverage"), dict) else {}
470
+ positions.append(
471
+ {
472
+ "coin": position.get("coin", "-"),
473
+ "size": position.get("szi"),
474
+ "entry_px": position.get("entryPx"),
475
+ "position_value": position.get("positionValue"),
476
+ "unrealized_pnl": position.get("unrealizedPnl"),
477
+ "return_on_equity": position.get("returnOnEquity"),
478
+ "liquidation_px": position.get("liquidationPx"),
479
+ "margin_used": position.get("marginUsed"),
480
+ "leverage": leverage.get("value"),
481
+ "leverage_type": leverage.get("type"),
482
+ }
483
+ )
484
+
485
+ positions.sort(
486
+ key=lambda item: abs(_safe_float(item.get("position_value")) or 0.0),
487
+ reverse=True,
488
+ )
489
+
490
+ summary = payload.get("marginSummary") if isinstance(payload.get("marginSummary"), dict) else {}
491
+ cross_summary = (
492
+ payload.get("crossMarginSummary") if isinstance(payload.get("crossMarginSummary"), dict) else {}
493
+ )
494
+
495
+ return {
496
+ "summary": {
497
+ "account_value": summary.get("accountValue"),
498
+ "total_ntl_pos": summary.get("totalNtlPos"),
499
+ "total_raw_usd": summary.get("totalRawUsd"),
500
+ "withdrawable": payload.get("withdrawable"),
501
+ "cross_account_value": cross_summary.get("accountValue"),
502
+ },
503
+ "positions": positions,
504
+ }
505
+
506
+
507
+ def _normalize_spot_balances(payload: Any) -> List[Dict[str, Any]]:
508
+ if not isinstance(payload, dict):
509
+ return []
510
+
511
+ rows: List[Dict[str, Any]] = []
512
+ for item in payload.get("balances", []):
513
+ if not isinstance(item, dict):
514
+ continue
515
+ rows.append(
516
+ {
517
+ "coin": item.get("coin", item.get("token", "-")),
518
+ "total": item.get("total"),
519
+ "hold": item.get("hold"),
520
+ "entry_ntl": item.get("entryNtl"),
521
+ }
522
+ )
523
+
524
+ rows.sort(key=lambda item: abs(_safe_float(item.get("entry_ntl")) or 0.0), reverse=True)
525
+ return rows
526
+
527
+
528
+ def _normalize_fills(payload: Any) -> List[Dict[str, Any]]:
529
+ rows: List[Dict[str, Any]] = []
530
+ if not isinstance(payload, list):
531
+ return rows
532
+
533
+ for item in payload:
534
+ if not isinstance(item, dict):
535
+ continue
536
+ fill = item.get("fill") if isinstance(item.get("fill"), dict) else item
537
+ rows.append(
538
+ {
539
+ "coin": fill.get("coin", "-"),
540
+ "dir": fill.get("dir") or fill.get("side") or "-",
541
+ "px": fill.get("px"),
542
+ "sz": fill.get("sz"),
543
+ "closed_pnl": fill.get("closedPnl"),
544
+ "fee": fill.get("fee"),
545
+ "fee_token": fill.get("feeToken"),
546
+ "start_position": fill.get("startPosition"),
547
+ "time": fill.get("time"),
548
+ "hash": fill.get("hash"),
549
+ "oid": fill.get("oid"),
550
+ "twap_id": item.get("twapId"),
551
+ }
552
+ )
553
+
554
+ rows.sort(key=lambda item: int(item.get("time") or 0), reverse=True)
555
+ return rows
556
+
557
+
558
+ def _normalize_orders(payload: Any) -> List[Dict[str, Any]]:
559
+ rows: List[Dict[str, Any]] = []
560
+ if not isinstance(payload, list):
561
+ return rows
562
+
563
+ for item in payload:
564
+ if not isinstance(item, dict):
565
+ continue
566
+ order = item.get("order") if isinstance(item.get("order"), dict) else item
567
+ rows.append(
568
+ {
569
+ "coin": order.get("coin", "-"),
570
+ "side": order.get("side", "-"),
571
+ "limit_px": order.get("limitPx") or order.get("px"),
572
+ "size": order.get("sz") or order.get("origSz"),
573
+ "timestamp": item.get("statusTimestamp")
574
+ or order.get("timestamp")
575
+ or order.get("time"),
576
+ "status": item.get("status") or order.get("status") or "-",
577
+ "oid": order.get("oid"),
578
+ "order_type": order.get("orderType") or "-",
579
+ }
580
+ )
581
+
582
+ rows.sort(key=lambda item: int(item.get("timestamp") or 0), reverse=True)
583
+ return rows
584
+
585
+
586
+ def _direction_bucket(direction: Any) -> str:
587
+ text = str(direction or "").strip().lower()
588
+ if "open" in text and "long" in text:
589
+ return "open_long"
590
+ if "close" in text and "long" in text:
591
+ return "close_long"
592
+ if "open" in text and "short" in text:
593
+ return "open_short"
594
+ if "close" in text and "short" in text:
595
+ return "close_short"
596
+ if text in {"b", "buy"}:
597
+ return "buy"
598
+ if text in {"s", "sell"}:
599
+ return "sell"
600
+ return "other"
601
+
602
+
603
+ def _average(values: Iterable[Optional[float]]) -> Optional[float]:
604
+ clean_values = [value for value in values if value is not None]
605
+ if not clean_values:
606
+ return None
607
+ return round(sum(clean_values) / len(clean_values), 12)
608
+
609
+
610
+ def _is_spot_coin(coin: str) -> bool:
611
+ return "/" in coin or coin.startswith("@")
612
+
613
+
614
+ def _safe_info_query(payload: Dict[str, Any]) -> Any:
615
+ try:
616
+ return _post_info(payload)
617
+ except SystemExit:
618
+ return None
619
+
620
+
621
+ def _market_context_for_coin(coin: str, interval: str, start_ms: int, end_ms: int) -> Dict[str, Any]:
622
+ candles = _normalize_candles(
623
+ _safe_info_query(
624
+ {
625
+ "type": "candleSnapshot",
626
+ "req": {
627
+ "coin": coin,
628
+ "interval": interval,
629
+ "startTime": start_ms,
630
+ "endTime": end_ms,
631
+ },
632
+ }
633
+ )
634
+ )
635
+ funding_history: List[Dict[str, Any]] = []
636
+ if not _is_spot_coin(coin):
637
+ funding_history = _normalize_funding_history(
638
+ _safe_info_query(
639
+ {
640
+ "type": "fundingHistory",
641
+ "coin": coin,
642
+ "startTime": start_ms,
643
+ "endTime": end_ms,
644
+ }
645
+ )
646
+ )
647
+
648
+ candle_change = None
649
+ if candles:
650
+ candle_change = _percent_change(candles[-1].get("close"), candles[0].get("open"))
651
+
652
+ funding_average = _average(_safe_float(item.get("funding_rate")) for item in funding_history)
653
+ return {
654
+ "coin": coin,
655
+ "interval": interval,
656
+ "candle_count": len(candles),
657
+ "price_change_pct": candle_change,
658
+ "window_open": candles[0].get("open") if candles else None,
659
+ "window_close": candles[-1].get("close") if candles else None,
660
+ "average_funding_rate": funding_average,
661
+ "funding_samples": len(funding_history),
662
+ }
663
+
664
+
665
+ def _build_coin_review(coin: str, fills: List[Dict[str, Any]], interval: str, start_ms: int, end_ms: int) -> Dict[str, Any]:
666
+ pnl_values = [_safe_float(fill.get("closed_pnl")) for fill in fills]
667
+ fee_values = [_safe_float(fill.get("fee")) for fill in fills]
668
+ scored = [value for value in pnl_values if value is not None]
669
+ wins = [value for value in scored if value > 0]
670
+ losses = [value for value in scored if value < 0]
671
+ breakeven = [value for value in scored if value == 0]
672
+
673
+ direction_counts = Counter(_direction_bucket(fill.get("dir")) for fill in fills)
674
+ market_context = _market_context_for_coin(coin, interval, start_ms, end_ms)
675
+ total_pnl = sum(value for value in pnl_values if value is not None)
676
+ total_fees = sum(value for value in fee_values if value is not None)
677
+ net_after_fees = total_pnl - total_fees
678
+
679
+ if direction_counts["open_long"] > direction_counts["open_short"]:
680
+ open_bias = "long"
681
+ elif direction_counts["open_short"] > direction_counts["open_long"]:
682
+ open_bias = "short"
683
+ elif direction_counts["open_long"] or direction_counts["open_short"]:
684
+ open_bias = "mixed"
685
+ else:
686
+ open_bias = "none"
687
+
688
+ return {
689
+ "coin": coin,
690
+ "fill_count": len(fills),
691
+ "realized_pnl": total_pnl,
692
+ "total_fees": total_fees,
693
+ "net_after_fees": net_after_fees,
694
+ "wins": len(wins),
695
+ "losses": len(losses),
696
+ "breakeven": len(breakeven),
697
+ "win_rate_pct": (len(wins) / (len(wins) + len(losses)) * 100) if (len(wins) + len(losses)) else None,
698
+ "open_long_count": direction_counts["open_long"],
699
+ "open_short_count": direction_counts["open_short"],
700
+ "close_long_count": direction_counts["close_long"],
701
+ "close_short_count": direction_counts["close_short"],
702
+ "open_bias": open_bias,
703
+ "market_context": market_context,
704
+ }
705
+
706
+
707
+ def _review_findings(summary: Dict[str, Any], coin_reviews: List[Dict[str, Any]]) -> List[str]:
708
+ findings: List[str] = []
709
+
710
+ if summary["fill_count"] == 0:
711
+ return ["No fills were found in the requested review window."]
712
+
713
+ if summary["outcome_fill_count"] == 0:
714
+ findings.append("Most fills in this window look like opens or adjustments, so realized-outcome review is limited until positions close.")
715
+
716
+ if summary["net_after_fees"] < 0:
717
+ findings.append(
718
+ f"Net realized PnL after fees was negative ({_compact_number(summary['net_after_fees'])} USDC-equivalent units in reported fill terms)."
719
+ )
720
+ elif summary["net_after_fees"] > 0:
721
+ findings.append(
722
+ f"Net realized PnL after fees was positive ({_compact_number(summary['net_after_fees'])} USDC-equivalent units in reported fill terms)."
723
+ )
724
+
725
+ realized_abs = abs(summary["realized_pnl"])
726
+ if summary["total_fees"] > 0:
727
+ if realized_abs == 0:
728
+ findings.append("Fees were non-trivial while realized PnL stayed flat, which usually means churn without enough edge.")
729
+ elif summary["total_fees"] / realized_abs >= 0.25:
730
+ ratio_pct = (summary["total_fees"] / realized_abs) * 100
731
+ findings.append(f"Fees consumed about {ratio_pct:.1f}% of absolute realized PnL, so execution efficiency is materially affecting results.")
732
+
733
+ if summary["fill_count"] >= 20 and summary["net_after_fees"] < 0:
734
+ win_rate = summary.get("win_rate_pct")
735
+ if win_rate is None or win_rate < 45:
736
+ findings.append("Activity was high relative to results, which suggests overtrading in this review window.")
737
+
738
+ if coin_reviews:
739
+ worst_coin = min(coin_reviews, key=lambda item: item["net_after_fees"])
740
+ best_coin = max(coin_reviews, key=lambda item: item["net_after_fees"])
741
+ if worst_coin["net_after_fees"] < 0:
742
+ findings.append(
743
+ f"The weakest coin was {worst_coin['coin']} with net after fees of {_compact_number(worst_coin['net_after_fees'])}."
744
+ )
745
+ if best_coin["net_after_fees"] > 0 and best_coin["coin"] != worst_coin["coin"]:
746
+ findings.append(
747
+ f"The strongest coin was {best_coin['coin']} with net after fees of {_compact_number(best_coin['net_after_fees'])}."
748
+ )
749
+
750
+ for item in coin_reviews:
751
+ market_change = item["market_context"].get("price_change_pct")
752
+ if item["net_after_fees"] >= 0 or market_change is None:
753
+ continue
754
+ if market_change > 2 and item["open_short_count"] > item["open_long_count"]:
755
+ findings.append(f"{item['coin']}: losses came while leaning short into a rising market window.")
756
+ elif market_change < -2 and item["open_long_count"] > item["open_short_count"]:
757
+ findings.append(f"{item['coin']}: losses came while leaning long into a falling market window.")
758
+
759
+ deduped: List[str] = []
760
+ for finding in findings:
761
+ if finding not in deduped:
762
+ deduped.append(finding)
763
+ return deduped[:6]
764
+
765
+
766
+ def _recent_fill_rows(fills: List[Dict[str, Any]], limit: int) -> List[Dict[str, Any]]:
767
+ rows = []
768
+ for fill in _limit_items(fills, limit):
769
+ rows.append(
770
+ {
771
+ "time": fill.get("time"),
772
+ "coin": fill.get("coin"),
773
+ "dir": fill.get("dir"),
774
+ "px": fill.get("px"),
775
+ "sz": fill.get("sz"),
776
+ "closed_pnl": fill.get("closed_pnl"),
777
+ "fee": fill.get("fee"),
778
+ "fee_token": fill.get("fee_token"),
779
+ }
780
+ )
781
+ return rows
782
+
783
+
784
+ def _coin_slug(coin: str) -> str:
785
+ slug = str(coin or "market").strip().lower()
786
+ for old, new in (("/", "-"), (":", "-"), ("@", "spot-"), (" ", "-")):
787
+ slug = slug.replace(old, new)
788
+ return slug or "market"
789
+
790
+
791
+ def _default_export_path(coin: str, interval: str, hours: float) -> Path:
792
+ hour_label = str(int(hours)) if float(hours).is_integer() else str(hours).replace(".", "p")
793
+ filename = f"hyperliquid-{_coin_slug(coin)}-{interval}-{hour_label}h.json"
794
+ return Path.cwd() / filename
795
+
796
+
797
+ def _write_json_file(path: Path, payload: Dict[str, Any]) -> None:
798
+ path.parent.mkdir(parents=True, exist_ok=True)
799
+ path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
800
+
801
+
802
+ def _export_summary(candles: List[Dict[str, Any]], funding_history: List[Dict[str, Any]]) -> Dict[str, Any]:
803
+ candle_change = None
804
+ if candles:
805
+ candle_change = _percent_change(candles[-1].get("close"), candles[0].get("open"))
806
+ return {
807
+ "candle_count": len(candles),
808
+ "funding_count": len(funding_history),
809
+ "window_open": candles[0].get("open") if candles else None,
810
+ "window_close": candles[-1].get("close") if candles else None,
811
+ "price_change_pct": candle_change,
812
+ "average_funding_rate": _average(_safe_float(item.get("funding_rate")) for item in funding_history),
813
+ }
814
+
815
+
816
+ def run_dexs(_args: argparse.Namespace) -> Dict[str, Any]:
817
+ payload = _post_info({"type": "perpDexs"})
818
+ rows = _normalize_dexs(payload)
819
+ return {"api_url": _info_url(), "count": len(rows), "dexs": rows}
820
+
821
+
822
+ def run_markets(args: argparse.Namespace) -> Dict[str, Any]:
823
+ payload: Dict[str, Any] = {"type": "metaAndAssetCtxs"}
824
+ if args.dex:
825
+ payload["dex"] = args.dex
826
+ rows = _normalize_perp_markets(_post_info(payload))
827
+
828
+ if args.sort == "name":
829
+ rows.sort(key=lambda item: item["coin"])
830
+ elif args.sort == "oi":
831
+ rows.sort(key=lambda item: _safe_float(item.get("open_interest")) or 0.0, reverse=True)
832
+ elif args.sort == "funding_abs":
833
+ rows.sort(key=lambda item: abs(_safe_float(item.get("funding")) or 0.0), reverse=True)
834
+ elif args.sort == "change_abs":
835
+ rows.sort(key=lambda item: abs(_safe_float(item.get("change_pct")) or 0.0), reverse=True)
836
+ else:
837
+ rows.sort(key=lambda item: _safe_float(item.get("day_ntl_vlm")) or 0.0, reverse=True)
838
+
839
+ return {
840
+ "dex": args.dex or "",
841
+ "count": len(rows),
842
+ "sort": args.sort,
843
+ "markets": _limit_items(rows, args.limit),
844
+ }
845
+
846
+
847
+ def run_spots(args: argparse.Namespace) -> Dict[str, Any]:
848
+ rows = _normalize_spot_markets(_post_info({"type": "spotMetaAndAssetCtxs"}))
849
+
850
+ if args.sort == "name":
851
+ rows.sort(key=lambda item: item["display_name"])
852
+ elif args.sort == "change_abs":
853
+ rows.sort(key=lambda item: abs(_safe_float(item.get("change_pct")) or 0.0), reverse=True)
854
+ else:
855
+ rows.sort(key=lambda item: _safe_float(item.get("day_ntl_vlm")) or 0.0, reverse=True)
856
+
857
+ return {"count": len(rows), "sort": args.sort, "pairs": _limit_items(rows, args.limit)}
858
+
859
+
860
+ def run_candles(args: argparse.Namespace) -> Dict[str, Any]:
861
+ end_ms = int(time.time() * 1000)
862
+ start_ms = _hours_ago_ms(args.hours, end_ms)
863
+ payload = {
864
+ "type": "candleSnapshot",
865
+ "req": {
866
+ "coin": args.coin,
867
+ "interval": args.interval,
868
+ "startTime": start_ms,
869
+ "endTime": end_ms,
870
+ },
871
+ }
872
+ candles = _normalize_candles(_post_info(payload))
873
+ summary = {}
874
+ if candles:
875
+ highs = [_safe_float(item.get("high")) for item in candles]
876
+ lows = [_safe_float(item.get("low")) for item in candles]
877
+ clean_highs = [value for value in highs if value is not None]
878
+ clean_lows = [value for value in lows if value is not None]
879
+ summary = {
880
+ "first_time": candles[0]["time"],
881
+ "last_time": candles[-1]["time"],
882
+ "open": candles[0]["open"],
883
+ "close": candles[-1]["close"],
884
+ "high": max(clean_highs) if clean_highs else None,
885
+ "low": min(clean_lows) if clean_lows else None,
886
+ "change_pct": _percent_change(candles[-1]["close"], candles[0]["open"]),
887
+ }
888
+ return {
889
+ "coin": args.coin,
890
+ "interval": args.interval,
891
+ "hours": args.hours,
892
+ "count": len(candles),
893
+ "summary": summary,
894
+ "candles": _limit_items(candles, args.limit),
895
+ }
896
+
897
+
898
+ def run_funding(args: argparse.Namespace) -> Dict[str, Any]:
899
+ end_ms = int(time.time() * 1000)
900
+ start_ms = _hours_ago_ms(args.hours, end_ms)
901
+ payload = {"type": "fundingHistory", "coin": args.coin, "startTime": start_ms, "endTime": end_ms}
902
+ rows = _normalize_funding_history(_post_info(payload))
903
+ avg_rate = None
904
+ if rows:
905
+ values = [_safe_float(item.get("funding_rate")) for item in rows]
906
+ clean_values = [value for value in values if value is not None]
907
+ if clean_values:
908
+ avg_rate = sum(clean_values) / len(clean_values)
909
+ return {
910
+ "coin": args.coin,
911
+ "hours": args.hours,
912
+ "count": len(rows),
913
+ "average_funding_rate": avg_rate,
914
+ "history": _limit_items(list(reversed(rows)), args.limit),
915
+ }
916
+
917
+
918
+ def run_l2(args: argparse.Namespace) -> Dict[str, Any]:
919
+ payload: Dict[str, Any] = {"type": "l2Book", "coin": args.coin}
920
+ if args.n_sig_figs is not None:
921
+ payload["nSigFigs"] = args.n_sig_figs
922
+ if args.mantissa is not None:
923
+ payload["mantissa"] = args.mantissa
924
+ raw = _post_info(payload)
925
+ levels = _normalize_book_levels(raw)
926
+ return {
927
+ "coin": args.coin,
928
+ "time": raw.get("time") if isinstance(raw, dict) else None,
929
+ "bids": _limit_items(levels["bids"], args.levels),
930
+ "asks": _limit_items(levels["asks"], args.levels),
931
+ }
932
+
933
+
934
+ def run_state(args: argparse.Namespace) -> Dict[str, Any]:
935
+ user = _resolve_user(args.user)
936
+ payload: Dict[str, Any] = {"type": "clearinghouseState", "user": user}
937
+ if args.dex:
938
+ payload["dex"] = args.dex
939
+ normalized = _normalize_positions(_post_info(payload))
940
+ return {
941
+ "user": user,
942
+ "dex": args.dex or "",
943
+ "summary": normalized["summary"],
944
+ "positions": normalized["positions"],
945
+ }
946
+
947
+
948
+ def run_spot_balances(args: argparse.Namespace) -> Dict[str, Any]:
949
+ user = _resolve_user(args.user)
950
+ payload = {"type": "spotClearinghouseState", "user": user}
951
+ rows = _normalize_spot_balances(_post_info(payload))
952
+ return {"user": user, "count": len(rows), "balances": _limit_items(rows, args.limit)}
953
+
954
+
955
+ def run_fills(args: argparse.Namespace) -> Dict[str, Any]:
956
+ user = _resolve_user(args.user)
957
+ payload: Dict[str, Any] = {"user": user}
958
+ if args.hours is not None:
959
+ payload["type"] = "userFillsByTime"
960
+ payload["startTime"] = _hours_ago_ms(args.hours)
961
+ else:
962
+ payload["type"] = "userFills"
963
+ if args.aggregate_by_time:
964
+ payload["aggregateByTime"] = True
965
+ rows = _normalize_fills(_post_info(payload))
966
+ return {
967
+ "user": user,
968
+ "hours": args.hours,
969
+ "aggregate_by_time": args.aggregate_by_time,
970
+ "count": len(rows),
971
+ "fills": _limit_items(rows, args.limit),
972
+ }
973
+
974
+
975
+ def run_orders(args: argparse.Namespace) -> Dict[str, Any]:
976
+ user = _resolve_user(args.user)
977
+ payload = {"type": "historicalOrders", "user": user}
978
+ rows = _normalize_orders(_post_info(payload))
979
+ return {"user": user, "count": len(rows), "orders": _limit_items(rows, args.limit)}
980
+
981
+
982
+ def run_review(args: argparse.Namespace) -> Dict[str, Any]:
983
+ user = _resolve_user(args.user)
984
+ end_ms = int(time.time() * 1000)
985
+ start_ms = _hours_ago_ms(args.hours, end_ms)
986
+ payload: Dict[str, Any] = {"type": "userFillsByTime", "user": user, "startTime": start_ms}
987
+ if args.aggregate_by_time:
988
+ payload["aggregateByTime"] = True
989
+
990
+ fills = _normalize_fills(_post_info(payload))
991
+ if args.coin:
992
+ target = args.coin.lower()
993
+ fills = [fill for fill in fills if str(fill.get("coin", "")).lower() == target]
994
+ fills = _limit_items(fills, args.fills)
995
+
996
+ grouped: Dict[str, List[Dict[str, Any]]] = {}
997
+ for fill in fills:
998
+ grouped.setdefault(fill.get("coin", "-"), []).append(fill)
999
+
1000
+ coin_reviews = [
1001
+ _build_coin_review(coin, coin_fills, args.interval, start_ms, end_ms)
1002
+ for coin, coin_fills in sorted(grouped.items(), key=lambda item: len(item[1]), reverse=True)
1003
+ ]
1004
+
1005
+ pnl_values = [_safe_float(fill.get("closed_pnl")) for fill in fills]
1006
+ fee_values = [_safe_float(fill.get("fee")) for fill in fills]
1007
+ scored = [value for value in pnl_values if value is not None]
1008
+ wins = [value for value in scored if value > 0]
1009
+ losses = [value for value in scored if value < 0]
1010
+ direction_counts = Counter(_direction_bucket(fill.get("dir")) for fill in fills)
1011
+ total_pnl = sum(value for value in pnl_values if value is not None)
1012
+ total_fees = sum(value for value in fee_values if value is not None)
1013
+
1014
+ summary = {
1015
+ "fill_count": len(fills),
1016
+ "scored_fill_count": len(scored),
1017
+ "outcome_fill_count": len(wins) + len(losses),
1018
+ "unique_coins": len(grouped),
1019
+ "realized_pnl": total_pnl,
1020
+ "total_fees": total_fees,
1021
+ "net_after_fees": total_pnl - total_fees,
1022
+ "wins": len(wins),
1023
+ "losses": len(losses),
1024
+ "breakeven": len([value for value in scored if value == 0]),
1025
+ "win_rate_pct": (len(wins) / (len(wins) + len(losses)) * 100) if (len(wins) + len(losses)) else None,
1026
+ "open_long_count": direction_counts["open_long"],
1027
+ "open_short_count": direction_counts["open_short"],
1028
+ "close_long_count": direction_counts["close_long"],
1029
+ "close_short_count": direction_counts["close_short"],
1030
+ }
1031
+
1032
+ return {
1033
+ "user": user,
1034
+ "coin_filter": args.coin,
1035
+ "hours": args.hours,
1036
+ "interval": args.interval,
1037
+ "fills_requested": args.fills,
1038
+ "summary": summary,
1039
+ "findings": _review_findings(summary, coin_reviews),
1040
+ "coin_reviews": coin_reviews,
1041
+ "recent_fills": _recent_fill_rows(fills, args.recent),
1042
+ }
1043
+
1044
+
1045
+ def run_export(args: argparse.Namespace) -> Dict[str, Any]:
1046
+ end_ms = args.end_time_ms if args.end_time_ms is not None else int(time.time() * 1000)
1047
+ start_ms = _hours_ago_ms(args.hours, end_ms)
1048
+
1049
+ candle_payload = {
1050
+ "type": "candleSnapshot",
1051
+ "req": {
1052
+ "coin": args.coin,
1053
+ "interval": args.interval,
1054
+ "startTime": start_ms,
1055
+ "endTime": end_ms,
1056
+ },
1057
+ }
1058
+ candles = _normalize_candles(_post_info(candle_payload))
1059
+
1060
+ funding_history: List[Dict[str, Any]] = []
1061
+ if not _is_spot_coin(args.coin):
1062
+ funding_history = _normalize_funding_history(
1063
+ _safe_info_query(
1064
+ {
1065
+ "type": "fundingHistory",
1066
+ "coin": args.coin,
1067
+ "startTime": start_ms,
1068
+ "endTime": end_ms,
1069
+ }
1070
+ )
1071
+ )
1072
+
1073
+ output_path = Path(args.output) if args.output else _default_export_path(args.coin, args.interval, args.hours)
1074
+ payload = {
1075
+ "schema_version": "hyperliquid-market-export-v1",
1076
+ "source": {
1077
+ "api_url": _info_url(),
1078
+ "interval": args.interval,
1079
+ "coin": args.coin,
1080
+ "market_type": "spot" if _is_spot_coin(args.coin) else "perp",
1081
+ },
1082
+ "window": {
1083
+ "start_time_ms": start_ms,
1084
+ "end_time_ms": end_ms,
1085
+ "hours": args.hours,
1086
+ },
1087
+ "summary": _export_summary(candles, funding_history),
1088
+ "candles": candles,
1089
+ "funding_history": funding_history,
1090
+ }
1091
+ _write_json_file(output_path, payload)
1092
+ return {
1093
+ "coin": args.coin,
1094
+ "interval": args.interval,
1095
+ "hours": args.hours,
1096
+ "output_path": str(output_path),
1097
+ "summary": payload["summary"],
1098
+ "schema_version": payload["schema_version"],
1099
+ }
1100
+
1101
+
1102
+ def render_dexs(data: Dict[str, Any]) -> str:
1103
+ rows = [
1104
+ {
1105
+ "label": item["label"],
1106
+ "full_name": item["full_name"],
1107
+ "deployer": _short_address(item["deployer"]),
1108
+ "asset_caps": item["asset_caps"],
1109
+ }
1110
+ for item in data["dexs"]
1111
+ ]
1112
+ return "\n".join(
1113
+ [
1114
+ f"API: {data['api_url']}",
1115
+ f"Perp dexs: {data['count']}",
1116
+ "",
1117
+ _render_table(
1118
+ [
1119
+ ("Dex", "label"),
1120
+ ("Full Name", "full_name"),
1121
+ ("Deployer", "deployer"),
1122
+ ("Asset Caps", "asset_caps"),
1123
+ ],
1124
+ rows,
1125
+ ),
1126
+ ]
1127
+ )
1128
+
1129
+
1130
+ def render_markets(data: Dict[str, Any]) -> str:
1131
+ rows = [
1132
+ {
1133
+ "coin": item["coin"],
1134
+ "mark_px": _format_price(item["mark_px"]),
1135
+ "change_pct": _format_percent(item["change_pct"]),
1136
+ "funding": _format_fraction_percent(item["funding"]),
1137
+ "open_interest": _compact_number(item["open_interest"]),
1138
+ "day_ntl_vlm": _compact_number(item["day_ntl_vlm"]),
1139
+ }
1140
+ for item in data["markets"]
1141
+ ]
1142
+ lines = [
1143
+ f"Dex: {data['dex'] or 'first-perp-dex'}",
1144
+ f"Markets returned: {len(data['markets'])} of {data['count']}",
1145
+ "",
1146
+ _render_table(
1147
+ [
1148
+ ("Coin", "coin"),
1149
+ ("Mark", "mark_px"),
1150
+ ("Chg", "change_pct"),
1151
+ ("Funding", "funding"),
1152
+ ("OI", "open_interest"),
1153
+ ("24h Vol", "day_ntl_vlm"),
1154
+ ],
1155
+ rows,
1156
+ ),
1157
+ ]
1158
+ return "\n".join(lines)
1159
+
1160
+
1161
+ def render_spots(data: Dict[str, Any]) -> str:
1162
+ rows = [
1163
+ {
1164
+ "pair": item["display_name"],
1165
+ "mark_px": _format_price(item["mark_px"]),
1166
+ "change_pct": _format_percent(item["change_pct"]),
1167
+ "day_ntl_vlm": _compact_number(item["day_ntl_vlm"]),
1168
+ }
1169
+ for item in data["pairs"]
1170
+ ]
1171
+ return "\n".join(
1172
+ [
1173
+ f"Spot pairs returned: {len(data['pairs'])} of {data['count']}",
1174
+ "",
1175
+ _render_table(
1176
+ [
1177
+ ("Pair", "pair"),
1178
+ ("Mark", "mark_px"),
1179
+ ("Chg", "change_pct"),
1180
+ ("24h Vol", "day_ntl_vlm"),
1181
+ ],
1182
+ rows,
1183
+ ),
1184
+ ]
1185
+ )
1186
+
1187
+
1188
+ def render_candles(data: Dict[str, Any]) -> str:
1189
+ rows = [
1190
+ {
1191
+ "time": _format_timestamp_ms(item["time"]),
1192
+ "open": _format_price(item["open"]),
1193
+ "high": _format_price(item["high"]),
1194
+ "low": _format_price(item["low"]),
1195
+ "close": _format_price(item["close"]),
1196
+ "volume": _compact_number(item["volume"]),
1197
+ }
1198
+ for item in data["candles"]
1199
+ ]
1200
+ summary = data.get("summary") or {}
1201
+ lines = [
1202
+ f"Coin: {data['coin']}",
1203
+ f"Interval: {data['interval']}",
1204
+ f"Hours: {data['hours']}",
1205
+ f"Candles returned: {len(data['candles'])} of {data['count']}",
1206
+ ]
1207
+ if summary:
1208
+ lines.extend(
1209
+ [
1210
+ f"Open -> Close: {_format_price(summary.get('open'))} -> {_format_price(summary.get('close'))}",
1211
+ f"Range: {_format_price(summary.get('low'))} to {_format_price(summary.get('high'))}",
1212
+ f"Change: {_format_percent(summary.get('change_pct'))}",
1213
+ ]
1214
+ )
1215
+ lines.extend(
1216
+ [
1217
+ "",
1218
+ _render_table(
1219
+ [
1220
+ ("Time", "time"),
1221
+ ("Open", "open"),
1222
+ ("High", "high"),
1223
+ ("Low", "low"),
1224
+ ("Close", "close"),
1225
+ ("Volume", "volume"),
1226
+ ],
1227
+ rows,
1228
+ ),
1229
+ ]
1230
+ )
1231
+ return "\n".join(lines)
1232
+
1233
+
1234
+ def render_funding(data: Dict[str, Any]) -> str:
1235
+ rows = [
1236
+ {
1237
+ "time": _format_timestamp_ms(item["time"]),
1238
+ "coin": item["coin"],
1239
+ "funding": _format_fraction_percent(item["funding_rate"]),
1240
+ "premium": _format_fraction_percent(item["premium"]),
1241
+ }
1242
+ for item in data["history"]
1243
+ ]
1244
+ lines = [
1245
+ f"Coin: {data['coin']}",
1246
+ f"Hours: {data['hours']}",
1247
+ f"Entries returned: {len(data['history'])} of {data['count']}",
1248
+ f"Average funding: {_format_fraction_percent(data['average_funding_rate'])}",
1249
+ "",
1250
+ _render_table(
1251
+ [
1252
+ ("Time", "time"),
1253
+ ("Coin", "coin"),
1254
+ ("Funding", "funding"),
1255
+ ("Premium", "premium"),
1256
+ ],
1257
+ rows,
1258
+ ),
1259
+ ]
1260
+ return "\n".join(lines)
1261
+
1262
+
1263
+ def render_l2(data: Dict[str, Any]) -> str:
1264
+ bid_rows = [
1265
+ {"px": _format_price(item["px"]), "sz": _compact_number(item["sz"]), "orders": item["orders"] or "-"}
1266
+ for item in data["bids"]
1267
+ ]
1268
+ ask_rows = [
1269
+ {"px": _format_price(item["px"]), "sz": _compact_number(item["sz"]), "orders": item["orders"] or "-"}
1270
+ for item in data["asks"]
1271
+ ]
1272
+ lines = [
1273
+ f"Coin: {data['coin']}",
1274
+ f"Book time: {_format_timestamp_ms(data['time'])}",
1275
+ "",
1276
+ "Bids",
1277
+ _render_table([("Price", "px"), ("Size", "sz"), ("Orders", "orders")], bid_rows),
1278
+ "",
1279
+ "Asks",
1280
+ _render_table([("Price", "px"), ("Size", "sz"), ("Orders", "orders")], ask_rows),
1281
+ ]
1282
+ return "\n".join(lines)
1283
+
1284
+
1285
+ def render_state(data: Dict[str, Any]) -> str:
1286
+ summary = data["summary"]
1287
+ position_rows = [
1288
+ {
1289
+ "coin": item["coin"],
1290
+ "size": item["size"],
1291
+ "entry_px": _format_price(item["entry_px"]),
1292
+ "position_value": _compact_number(item["position_value"]),
1293
+ "unrealized_pnl": _compact_number(item["unrealized_pnl"]),
1294
+ "roe": _format_fraction_percent(item["return_on_equity"], 2),
1295
+ "liq": _format_price(item["liquidation_px"]),
1296
+ "lev": f"{item['leverage'] or '-'}x",
1297
+ }
1298
+ for item in data["positions"]
1299
+ ]
1300
+
1301
+ lines = [
1302
+ f"User: {data['user']}",
1303
+ f"Dex: {data['dex'] or 'first-perp-dex'}",
1304
+ f"Account value: {summary.get('account_value') or '-'}",
1305
+ f"Total notional position: {summary.get('total_ntl_pos') or '-'}",
1306
+ f"Withdrawable: {summary.get('withdrawable') or '-'}",
1307
+ f"Positions: {len(data['positions'])}",
1308
+ ]
1309
+ if position_rows:
1310
+ lines.extend(
1311
+ [
1312
+ "",
1313
+ _render_table(
1314
+ [
1315
+ ("Coin", "coin"),
1316
+ ("Size", "size"),
1317
+ ("Entry", "entry_px"),
1318
+ ("Pos Val", "position_value"),
1319
+ ("uPnL", "unrealized_pnl"),
1320
+ ("ROE", "roe"),
1321
+ ("Liq", "liq"),
1322
+ ("Lev", "lev"),
1323
+ ],
1324
+ position_rows,
1325
+ ),
1326
+ ]
1327
+ )
1328
+ return "\n".join(lines)
1329
+
1330
+
1331
+ def render_spot_balances(data: Dict[str, Any]) -> str:
1332
+ rows = [
1333
+ {
1334
+ "coin": item["coin"],
1335
+ "total": _compact_number(item["total"]),
1336
+ "hold": _compact_number(item["hold"]),
1337
+ "entry_ntl": _compact_number(item["entry_ntl"]),
1338
+ }
1339
+ for item in data["balances"]
1340
+ ]
1341
+ return "\n".join(
1342
+ [
1343
+ f"User: {data['user']}",
1344
+ f"Balances returned: {len(data['balances'])} of {data['count']}",
1345
+ "",
1346
+ _render_table(
1347
+ [
1348
+ ("Coin", "coin"),
1349
+ ("Total", "total"),
1350
+ ("Hold", "hold"),
1351
+ ("Entry Ntl", "entry_ntl"),
1352
+ ],
1353
+ rows,
1354
+ ),
1355
+ ]
1356
+ )
1357
+
1358
+
1359
+ def render_fills(data: Dict[str, Any]) -> str:
1360
+ rows = [
1361
+ {
1362
+ "time": _format_timestamp_ms(item["time"]),
1363
+ "coin": item["coin"],
1364
+ "dir": item["dir"],
1365
+ "px": _format_price(item["px"]),
1366
+ "sz": _compact_number(item["sz"]),
1367
+ "closed_pnl": _compact_number(item["closed_pnl"]),
1368
+ "fee": f"{_compact_number(item['fee'])} {item['fee_token'] or ''}".strip(),
1369
+ }
1370
+ for item in data["fills"]
1371
+ ]
1372
+ lines = [
1373
+ f"User: {data['user']}",
1374
+ f"Aggregate by time: {data['aggregate_by_time']}",
1375
+ f"Fills returned: {len(data['fills'])} of {data['count']}",
1376
+ "",
1377
+ _render_table(
1378
+ [
1379
+ ("Time", "time"),
1380
+ ("Coin", "coin"),
1381
+ ("Dir", "dir"),
1382
+ ("Px", "px"),
1383
+ ("Sz", "sz"),
1384
+ ("Closed PnL", "closed_pnl"),
1385
+ ("Fee", "fee"),
1386
+ ],
1387
+ rows,
1388
+ ),
1389
+ ]
1390
+ return "\n".join(lines)
1391
+
1392
+
1393
+ def render_orders(data: Dict[str, Any]) -> str:
1394
+ rows = [
1395
+ {
1396
+ "time": _format_timestamp_ms(item["timestamp"]),
1397
+ "coin": item["coin"],
1398
+ "side": item["side"],
1399
+ "limit_px": _format_price(item["limit_px"]),
1400
+ "size": _compact_number(item["size"]),
1401
+ "status": item["status"],
1402
+ "oid": item["oid"] or "-",
1403
+ }
1404
+ for item in data["orders"]
1405
+ ]
1406
+ return "\n".join(
1407
+ [
1408
+ f"User: {data['user']}",
1409
+ f"Orders returned: {len(data['orders'])} of {data['count']}",
1410
+ "",
1411
+ _render_table(
1412
+ [
1413
+ ("Time", "time"),
1414
+ ("Coin", "coin"),
1415
+ ("Side", "side"),
1416
+ ("Px", "limit_px"),
1417
+ ("Sz", "size"),
1418
+ ("Status", "status"),
1419
+ ("OID", "oid"),
1420
+ ],
1421
+ rows,
1422
+ ),
1423
+ ]
1424
+ )
1425
+
1426
+
1427
+ def render_review(data: Dict[str, Any]) -> str:
1428
+ summary = data["summary"]
1429
+ coin_rows = [
1430
+ {
1431
+ "coin": item["coin"],
1432
+ "fills": item["fill_count"],
1433
+ "net": _compact_number(item["net_after_fees"]),
1434
+ "win_rate": _format_percent(item["win_rate_pct"]),
1435
+ "trend": _format_percent(item["market_context"].get("price_change_pct")),
1436
+ "funding": _format_fraction_percent(item["market_context"].get("average_funding_rate")),
1437
+ "bias": item["open_bias"],
1438
+ }
1439
+ for item in data["coin_reviews"]
1440
+ ]
1441
+ recent_rows = [
1442
+ {
1443
+ "time": _format_timestamp_ms(item["time"]),
1444
+ "coin": item["coin"],
1445
+ "dir": item["dir"],
1446
+ "px": _format_price(item["px"]),
1447
+ "sz": _compact_number(item["sz"]),
1448
+ "closed_pnl": _compact_number(item["closed_pnl"]),
1449
+ "fee": f"{_compact_number(item['fee'])} {item['fee_token'] or ''}".strip(),
1450
+ }
1451
+ for item in data["recent_fills"]
1452
+ ]
1453
+
1454
+ lines = [
1455
+ f"User: {data['user']}",
1456
+ f"Review window: {data['hours']} hours",
1457
+ f"Coin filter: {data['coin_filter'] or 'all traded coins'}",
1458
+ f"Fills analyzed: {summary['fill_count']}",
1459
+ f"Unique coins: {summary['unique_coins']}",
1460
+ f"Realized PnL: {_compact_number(summary['realized_pnl'])}",
1461
+ f"Fees: {_compact_number(summary['total_fees'])}",
1462
+ f"Net after fees: {_compact_number(summary['net_after_fees'])}",
1463
+ f"Win rate: {_format_percent(summary['win_rate_pct'])}",
1464
+ ]
1465
+
1466
+ if data["findings"]:
1467
+ lines.extend(["", "Findings"])
1468
+ for finding in data["findings"]:
1469
+ lines.append(f"- {finding}")
1470
+
1471
+ if coin_rows:
1472
+ lines.extend(
1473
+ [
1474
+ "",
1475
+ "Coin Breakdown",
1476
+ _render_table(
1477
+ [
1478
+ ("Coin", "coin"),
1479
+ ("Fills", "fills"),
1480
+ ("Net", "net"),
1481
+ ("Win Rate", "win_rate"),
1482
+ ("Trend", "trend"),
1483
+ ("Funding", "funding"),
1484
+ ("Bias", "bias"),
1485
+ ],
1486
+ coin_rows,
1487
+ ),
1488
+ ]
1489
+ )
1490
+
1491
+ if recent_rows:
1492
+ lines.extend(
1493
+ [
1494
+ "",
1495
+ "Recent Fills",
1496
+ _render_table(
1497
+ [
1498
+ ("Time", "time"),
1499
+ ("Coin", "coin"),
1500
+ ("Dir", "dir"),
1501
+ ("Px", "px"),
1502
+ ("Sz", "sz"),
1503
+ ("Closed PnL", "closed_pnl"),
1504
+ ("Fee", "fee"),
1505
+ ],
1506
+ recent_rows,
1507
+ ),
1508
+ ]
1509
+ )
1510
+
1511
+ return "\n".join(lines)
1512
+
1513
+
1514
+ def render_export(data: Dict[str, Any]) -> str:
1515
+ summary = data["summary"]
1516
+ return "\n".join(
1517
+ [
1518
+ f"Coin: {data['coin']}",
1519
+ f"Interval: {data['interval']}",
1520
+ f"Hours: {data['hours']}",
1521
+ f"Schema: {data['schema_version']}",
1522
+ f"Output: {data['output_path']}",
1523
+ f"Candles: {summary['candle_count']}",
1524
+ f"Funding samples: {summary['funding_count']}",
1525
+ f"Window open -> close: {_format_price(summary.get('window_open'))} -> {_format_price(summary.get('window_close'))}",
1526
+ f"Price change: {_format_percent(summary.get('price_change_pct'))}",
1527
+ f"Average funding: {_format_fraction_percent(summary.get('average_funding_rate'))}",
1528
+ ]
1529
+ )
1530
+
1531
+
1532
+ def _add_json_flag(parser: argparse.ArgumentParser) -> None:
1533
+ parser.add_argument("--json", action="store_true", help="Print raw JSON output")
1534
+
1535
+
1536
+ def build_parser() -> argparse.ArgumentParser:
1537
+ parser = argparse.ArgumentParser(description="Hyperliquid CLI Tool for Hermes Agent")
1538
+ subparsers = parser.add_subparsers(dest="command", required=True)
1539
+
1540
+ dexs = subparsers.add_parser("dexs", help="List available perpetual dexs")
1541
+ _add_json_flag(dexs)
1542
+ dexs.set_defaults(func=run_dexs, renderer=render_dexs)
1543
+
1544
+ markets = subparsers.add_parser("markets", help="List perpetual market contexts")
1545
+ markets.add_argument("--dex", default="", help="Perp dex name; empty means first perp dex")
1546
+ markets.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
1547
+ markets.add_argument(
1548
+ "--sort",
1549
+ choices=["volume", "oi", "funding_abs", "change_abs", "name"],
1550
+ default="volume",
1551
+ help="Sort mode",
1552
+ )
1553
+ _add_json_flag(markets)
1554
+ markets.set_defaults(func=run_markets, renderer=render_markets)
1555
+
1556
+ spots = subparsers.add_parser("spots", help="List spot market contexts")
1557
+ spots.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
1558
+ spots.add_argument(
1559
+ "--sort",
1560
+ choices=["volume", "change_abs", "name"],
1561
+ default="volume",
1562
+ help="Sort mode",
1563
+ )
1564
+ _add_json_flag(spots)
1565
+ spots.set_defaults(func=run_spots, renderer=render_spots)
1566
+
1567
+ candles = subparsers.add_parser("candles", help="Fetch candle history for a market")
1568
+ candles.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC" or "mydex:BTC"')
1569
+ candles.add_argument("--interval", default="1h", help="Candle interval, e.g. 1m, 15m, 1h, 4h, 1d")
1570
+ candles.add_argument("--hours", type=float, default=24.0, help="Lookback window in hours")
1571
+ candles.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
1572
+ _add_json_flag(candles)
1573
+ candles.set_defaults(func=run_candles, renderer=render_candles)
1574
+
1575
+ funding = subparsers.add_parser("funding", help="Fetch funding history for a perp market")
1576
+ funding.add_argument("coin", help='Coin name, e.g. "BTC" or "mydex:COIN"')
1577
+ funding.add_argument("--hours", type=float, default=72.0, help="Lookback window in hours")
1578
+ funding.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
1579
+ _add_json_flag(funding)
1580
+ funding.set_defaults(func=run_funding, renderer=render_funding)
1581
+
1582
+ l2 = subparsers.add_parser("l2", help="Inspect the current L2 book for a market")
1583
+ l2.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC"')
1584
+ l2.add_argument("--levels", type=int, default=10, help="Levels per side to display")
1585
+ l2.add_argument("--n-sig-figs", type=int, default=None, help="Optional server-side book aggregation")
1586
+ l2.add_argument("--mantissa", type=int, default=None, help="Optional mantissa when using nSigFigs")
1587
+ _add_json_flag(l2)
1588
+ l2.set_defaults(func=run_l2, renderer=render_l2)
1589
+
1590
+ state = subparsers.add_parser("state", help="Inspect a user's perp account state")
1591
+ state.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
1592
+ state.add_argument("--dex", default="", help="Perp dex name; empty means first perp dex")
1593
+ _add_json_flag(state)
1594
+ state.set_defaults(func=run_state, renderer=render_state)
1595
+
1596
+ spot_balances = subparsers.add_parser("spot-balances", help="Inspect a user's spot token balances")
1597
+ spot_balances.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
1598
+ spot_balances.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
1599
+ _add_json_flag(spot_balances)
1600
+ spot_balances.set_defaults(func=run_spot_balances, renderer=render_spot_balances)
1601
+
1602
+ fills = subparsers.add_parser("fills", help="Inspect a user's recent fills")
1603
+ fills.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
1604
+ fills.add_argument("--hours", type=float, default=None, help="Optional time window; uses userFillsByTime")
1605
+ fills.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
1606
+ fills.add_argument(
1607
+ "--aggregate-by-time",
1608
+ action="store_true",
1609
+ help="Aggregate partial fills when the API supports it",
1610
+ )
1611
+ _add_json_flag(fills)
1612
+ fills.set_defaults(func=run_fills, renderer=render_fills)
1613
+
1614
+ orders = subparsers.add_parser("orders", help="Inspect a user's historical orders")
1615
+ orders.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
1616
+ orders.add_argument("--limit", type=int, default=20, help="Rows to display; 0 means all")
1617
+ _add_json_flag(orders)
1618
+ orders.set_defaults(func=run_orders, renderer=render_orders)
1619
+
1620
+ review = subparsers.add_parser("review", help="Generate a lightweight post-trade review from recent fills")
1621
+ review.add_argument("user", nargs="?", default="", help=f"Optional address; falls back to ${DEFAULT_USER_ENV}")
1622
+ review.add_argument("--coin", default="", help="Optional exact coin filter, e.g. BTC or PURR/USDC")
1623
+ review.add_argument("--hours", type=float, default=72.0, help="Lookback window in hours")
1624
+ review.add_argument("--fills", type=int, default=50, help="Maximum fills to analyze")
1625
+ review.add_argument("--recent", type=int, default=10, help="Recent fills to display in the review")
1626
+ review.add_argument("--interval", default="1h", help="Candle interval for market context")
1627
+ review.add_argument(
1628
+ "--aggregate-by-time",
1629
+ action="store_true",
1630
+ help="Aggregate partial fills when the API supports it",
1631
+ )
1632
+ _add_json_flag(review)
1633
+ review.set_defaults(func=run_review, renderer=render_review)
1634
+
1635
+ export = subparsers.add_parser("export", help="Export normalized candles and funding history to a JSON file")
1636
+ export.add_argument("coin", help='Coin name, e.g. "BTC" or "PURR/USDC" or "mydex:BTC"')
1637
+ export.add_argument("--interval", default="1h", help="Candle interval for the exported dataset")
1638
+ export.add_argument("--hours", type=float, default=168.0, help="Lookback window in hours")
1639
+ export.add_argument("--end-time-ms", type=int, default=None, help="Optional fixed end time for reproducible exports")
1640
+ export.add_argument("--output", default="", help="Path to the JSON export file")
1641
+ _add_json_flag(export)
1642
+ export.set_defaults(func=run_export, renderer=render_export)
1643
+
1644
+ return parser
1645
+
1646
+
1647
+ def main(argv: Optional[List[str]] = None) -> int:
1648
+ parser = build_parser()
1649
+ args = parser.parse_args(argv)
1650
+
1651
+ payload = args.func(args)
1652
+ if args.json:
1653
+ print(json.dumps(payload, indent=2))
1654
+ else:
1655
+ print(args.renderer(payload))
1656
+ return 0
1657
+
1658
+
1659
+ if __name__ == "__main__":
1660
+ raise SystemExit(main())
optional-skills/creative/ai-presenter-video/LICENSE ADDED
@@ -0,0 +1,21 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ MIT License
2
+
3
+ Copyright (c) 2026 lanshu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
optional-skills/creative/ai-presenter-video/SKILL.md ADDED
@@ -0,0 +1,196 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ name: ai-presenter-video
3
+ description: "Make a verified AI presenter video from script + image."
4
+ version: 1.0.0
5
+ author: cclank (https://github.com/cclank/lanshu-create-ai-presenter-video), ported by Hermes Agent
6
+ license: MIT
7
+ platforms: [linux, macos]
8
+ required_commands: [ffmpeg, ffprobe, python3]
9
+ metadata:
10
+ hermes:
11
+ tags: [video, presenter, avatar, lipsync, tts, captions, creative]
12
+ category: creative
13
+ homepage: https://github.com/cclank/lanshu-create-ai-presenter-video
14
+ related_skills: [hyperframes, kanban-video-orchestrator, comfyui]
15
+ ---
16
+
17
+ # AI Presenter Video
18
+
19
+ Turn a topic (or finished script) plus ONE authorized adult presenter image
20
+ into a complete, publish-ready presenter-led video: locked narration, avatar
21
+ generation with lip-sync QA, captions, deterministic editing, loudness-normalized
22
+ master/share encodes, and machine + visual acceptance reports.
23
+
24
+ Use this skill for new presenter videos AND for continuing, revising,
25
+ captioning, lip-sync-repairing, or re-exporting an existing presenter-video
26
+ job. The workflow is provider-neutral: pick generation capabilities from what
27
+ is actually available in the session (FAL video/image models via
28
+ `image_generate` and the video-gen plugin, TTS via `text_to_speech`, ASR via
29
+ the whisper/STT tooling, ffmpeg for everything deterministic).
30
+
31
+ > Ported from cclank/lanshu-create-ai-presenter-video (MIT). Upstream body
32
+ > kept substantively verbatim in `references/`; Hermes adaptations live in
33
+ > this hub file. Scripts are deterministic (no network, no credentials).
34
+
35
+ ## Hermes adaptations (read first)
36
+
37
+ - **Skill dir resolution** — upstream hardcoded its own agent's skills path.
38
+ In Hermes the loader expands `${HERMES_SKILL_DIR}` to this skill's installed
39
+ directory, so every command below uses that token directly:
40
+
41
+ ```bash
42
+ SKILL_DIR="${HERMES_SKILL_DIR}"
43
+ ```
44
+
45
+ Shell variables do not persist between tool calls — re-paste the assignment
46
+ (or the expanded path) in each terminal call that uses it.
47
+ - **Capability mapping** — where the references say "a voice generation
48
+ capability", use `text_to_speech` (OpenAI/Edge/ElevenLabs per user config);
49
+ "presenter/avatar generation" → FAL image-to-video families (Kling, Wan,
50
+ MiniMax H3 etc.) through the configured video tooling, or an avatar/lipsync
51
+ endpoint the user has access to; "word-timestamp ASR" → whisper via the STT
52
+ tooling or `faster-whisper` in a venv; "deterministic compositor" → ffmpeg
53
+ filtergraphs, or the `hyperframes` skill when installed (the editing
54
+ reference has a HyperFrames section that maps directly onto it).
55
+ - **Visual QA** — do the "normal-speed visual review" steps with
56
+ `vision_analyze` on the generated contact sheet plus sampled frames
57
+ (identity, mouth timing, hands, blinking, continuity). Numeric checks come
58
+ from the scripts' ffprobe output.
59
+ - **Paid-generation consent** — remote avatar/TTS generation is billable.
60
+ Follow the upstream operating rules: before the first paid call state the
61
+ uploaded assets, requested seconds, known cost, pilot size, and retry
62
+ ceiling, and get the user's explicit go-ahead. Never upload the presenter
63
+ image to a remote provider before `remote_upload_approved` is true in
64
+ `job.json`.
65
+ - **Consent flags live under `input`** — `rights_confirmed`,
66
+ `adult_presenter_confirmed`, `remote_upload_approved`, and
67
+ `voice_clone_approved` sit inside the `input` object of `job.json` (init
68
+ flags set them; hand-editing must target `input.*`, not the job root).
69
+ `manual_input_review.*` sits at the root. `preflight.py` distinguishes
70
+ `errors` (block everything) from `remote_blockers` (block only remote
71
+ generation) — local script/audio work may proceed while remote is blocked.
72
+
73
+ ## Workflow
74
+
75
+ 1. **Start or resume a job.** New job:
76
+
77
+ ```bash
78
+ python3 "$SKILL_DIR/scripts/init_job.py" \
79
+ --job-dir ~/Videos/my-presenter-video \
80
+ --presenter-image /path/to/presenter.png \
81
+ --topic "explain context engineering in one minute" \
82
+ --duration 60 --aspect 9:16 \
83
+ --rights-confirmed --adult-presenter-confirmed
84
+ ```
85
+
86
+ Use `--script` for an existing script file; other flags: `--voice-sample`,
87
+ `--supporting-media`, `--width`, `--height`, `--fps`, `--watermark`,
88
+ `--cta`. For an existing job, read `job.json` + QA reports and resume from
89
+ the earliest unfinished state — never regenerate accepted work.
90
+
91
+ 2. **Manual input review.** Actually look at the presenter image
92
+ (`vision_analyze`) and listen to any voice sample; record findings by
93
+ setting the `manual_input_review` booleans in `job.json`, e.g.:
94
+
95
+ ```bash
96
+ python3 - <<'PY'
97
+ import json
98
+ p = "~/Videos/my-presenter-video/job.json" # expand ~ or use an absolute path
99
+ import os; p = os.path.expanduser(p)
100
+ j = json.load(open(p))
101
+ j["manual_input_review"].update(image_viewed=True, single_clear_face=True,
102
+ image_has_no_unwanted_text=True)
103
+ json.dump(j, open(p, "w"), indent=2)
104
+ PY
105
+ ```
106
+
107
+ Then gate:
108
+
109
+ ```bash
110
+ python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json
111
+ ```
112
+
113
+ Proceed only when `ok: true`; do remote generation only when
114
+ `remote_ready: true`. Note: preflight also updates `job.json` in place
115
+ (records the report path) — re-read it after running rather than editing
116
+ a stale copy.
117
+
118
+ 3. **Lock content and audio** — read `references/generation.md`. Script →
119
+ full narration via `text_to_speech` → ASR-verify the narration against the
120
+ script → record real durations. The locked audio is the master clock for
121
+ everything downstream.
122
+
123
+ 4. **Plan and generate the presenter** — read `references/generation.md`.
124
+ Short low-cost pilot first; full run only after the pilot passes identity
125
+ and mouth-timing review.
126
+
127
+ 5. **Edit** — read `references/editing.md`. Deterministic timeline driven by
128
+ the locked audio; captions and keyword callouts only after audio and media
129
+ are final.
130
+
131
+ 6. **Verify and deliver** — read `references/qa-recovery.md`, render, then:
132
+
133
+ ```bash
134
+ bash "$SKILL_DIR/scripts/finalize_delivery.sh" \
135
+ ~/Videos/my-presenter-video/renders/rendered.mp4 \
136
+ ~/Videos/my-presenter-video/outputs my-video
137
+ ```
138
+
139
+ The finalizer preserves aspect ratio, runs two-pass loudness normalization
140
+ (program ≈ −16 LUFS), produces master + share encodes, decode-verifies
141
+ both, writes a delivery report JSON, and emits a nine-frame contact sheet.
142
+ Inspect the contact sheet with `vision_analyze` before claiming completion.
143
+
144
+ ## Operating rules (non-negotiable)
145
+
146
+ - Confirm image rights, adult status, remote-upload approval, and
147
+ voice-cloning authorization before the relevant remote action.
148
+ - Never infer or clone a real person's voice from an image; use an authorized
149
+ sample or a stock TTS voice.
150
+ - Lock the complete narration before presenter generation, caption timing, or
151
+ final scene boundaries.
152
+ - Mute video sources in the final composition; only the approved narration
153
+ and intentional mix tracks carry audio.
154
+ - Preserve provider request bodies and task IDs (minus credentials/expiring
155
+ URLs). Poll interrupted work before resubmitting — avoid double billing.
156
+ - Stop after three rejected paid candidates and summarize the failure mode.
157
+ - Do not claim completion until the final files fully decode and the contact
158
+ sheet or full playback has been reviewed.
159
+
160
+ ## Defaults for minimal input
161
+
162
+ 9:16, 1080×1920, 30fps; topic-derived videos target 45–75s; stock voice when
163
+ no authorized sample; presenter-led layout with hook → 2–4 beats → close;
164
+ no music/CTA unless requested; language inferred from the request.
165
+
166
+ ## Reference routing
167
+
168
+ - `references/generation.md` — intake, content, voice, capability selection,
169
+ presenter prompts, paid generation, provider changes.
170
+ - `references/editing.md` — timeline contract, openings/closes, captions,
171
+ keyword-callout presets, HyperFrames composition, exports.
172
+ - `references/qa-recovery.md` — technical acceptance, visual acceptance, and
173
+ recovery for lip-sync/identity/hands/exposure/freeze/caption/audio faults.
174
+
175
+ ## Pitfalls
176
+
177
+ - `preflight.py` requires ffprobe; on a bare box install ffmpeg first.
178
+ - The consent booleans set by init flags land under `input.*`; editing them
179
+ at the job-json root silently does nothing (preflight keeps blocking).
180
+ - `finalize_delivery.sh` needs bash + jq + awk and a fully decodable input —
181
+ a truncated render fails the decode check by design, not by accident.
182
+ - Long avatar clips drift: prefer one continuous presenter source sliced on
183
+ the audio timeline over many regenerated chapter clips (identity drift
184
+ across regenerations is the #1 visual-QA failure).
185
+ - FAL i2v endpoints cap duration (typically 5–15s); plan chapter-level
186
+ presenter segments accordingly and reuse the pilot's seed/params for
187
+ consistency where the endpoint supports it.
188
+
189
+ ## Verification
190
+
191
+ Validated hands-on (Aug 2026): `init_job.py` → `job.json` with correct state
192
+ machine; `preflight.py` correctly blocked on unreviewed inputs, flipped to
193
+ `ok: true` after review booleans, and kept `remote_ready: false` until
194
+ `input.remote_upload_approved`; `finalize_delivery.sh` on a synthetic 5s
195
+ 1080×1920 render produced decode-verified master (631kbit/s) + share encodes,
196
+ delivery-report JSON, and a 9-frame contact sheet, exit 0.
optional-skills/creative/ai-presenter-video/assets/job.template.json ADDED
@@ -0,0 +1,83 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "schema_version": 1,
3
+ "job_id": "replace-me",
4
+ "state": "intake",
5
+ "mode": "automation",
6
+ "input": {
7
+ "topic": "",
8
+ "script_path": "",
9
+ "presenter_image": "",
10
+ "voice_sample": "",
11
+ "supporting_media": [],
12
+ "rights_confirmed": false,
13
+ "adult_presenter_confirmed": false,
14
+ "remote_upload_approved": false,
15
+ "voice_clone_approved": false
16
+ },
17
+ "creative": {
18
+ "language": "auto",
19
+ "audience": "general",
20
+ "goal": "explain clearly",
21
+ "duration_target_s": 60,
22
+ "aspect": "9:16",
23
+ "width": 1080,
24
+ "height": 1920,
25
+ "fps": 30,
26
+ "style": "credible contemporary presenter",
27
+ "watermark": "",
28
+ "cta": ""
29
+ },
30
+ "voice": {
31
+ "strategy": "auto",
32
+ "voice_id": "",
33
+ "rate": 1.06,
34
+ "segment_lufs": -17,
35
+ "program_lufs": -16
36
+ },
37
+ "plan": {
38
+ "status": "draft",
39
+ "opening_target_s": 4,
40
+ "closing_target_s": 5,
41
+ "chapters": [],
42
+ "requested_generation_seconds": 0,
43
+ "estimated_cost": null,
44
+ "price_evidence_date": "",
45
+ "pilot_approved": false,
46
+ "paid_generation_approved": false,
47
+ "retry_ceiling": 3
48
+ },
49
+ "capabilities": {
50
+ "voice_generation": {},
51
+ "main_presenter": {},
52
+ "short_motion": {},
53
+ "lipsync_repair": {},
54
+ "word_timestamp_asr": {},
55
+ "timeline_compositor": {},
56
+ "encoder_qa": {}
57
+ },
58
+ "manual_input_review": {
59
+ "image_viewed": false,
60
+ "single_clear_face": false,
61
+ "image_has_no_unwanted_text": false,
62
+ "voice_sample_listened": false,
63
+ "single_clear_speaker": false
64
+ },
65
+ "artifacts": {
66
+ "script": "",
67
+ "beat_sheet": "",
68
+ "timeline": "",
69
+ "storyboard": "",
70
+ "final_audio": "",
71
+ "caption_json": "",
72
+ "rendered": "",
73
+ "master": "",
74
+ "share": ""
75
+ },
76
+ "qa": {
77
+ "preflight_report": "",
78
+ "asr_report": "",
79
+ "composition_report": "",
80
+ "delivery_report": "",
81
+ "manual_visual_review": ""
82
+ }
83
+ }
optional-skills/creative/ai-presenter-video/references/editing.md ADDED
@@ -0,0 +1,65 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Editing
2
+
3
+ Read this file for the visual plan, deterministic timeline, openings, closes, screen demos, captions, keyword callouts, covers, previews, and exports.
4
+
5
+ ## Visual routes
6
+
7
+ - **Presenter-led:** the presenter carries the explanation; add one concise visual idea per beat.
8
+ - **Screen-demo:** preserve real UI readability; introduce the presenter large at chapter starts, then shrink the same continuous video into a verified safe region.
9
+ - **Mixed explainer:** assign supporting media only where it proves or clarifies narration.
10
+
11
+ Do not fabricate product evidence. Label conceptual visuals clearly.
12
+
13
+ ## Timeline contract
14
+
15
+ The locked narration defines duration and semantic boundaries. Every clip keeps three independent values:
16
+
17
+ - authored start in the final video;
18
+ - authored duration;
19
+ - source-media start.
20
+
21
+ When an opening changes length, shift authored starts while preserving presenter source offsets. Keep video sources muted and use approved external narration as the program clock. Prefer one continuous presenter source and source-time slices over regenerated chapter clips.
22
+
23
+ Use hard cuts at settled semantic pauses. Add transitions only when they clarify structure. Preserve a quiet tail so the last word, gesture, and mouth position finish naturally.
24
+
25
+ ## Opening, body, and close
26
+
27
+ - Establish the topic and payoff within the first few seconds.
28
+ - Design the time-zero frame as a deliberate cover frame.
29
+ - Keep opening copy away from eyes, mouth, and the hand-motion path.
30
+ - Use the same visual system across the cover, chapters, captions, keywords, progress, and close.
31
+ - End with a conclusion or one requested next step. Do not add promotional copy without a brief requirement.
32
+
33
+ ## Captions
34
+
35
+ Generate word timestamps from the final audio. Split into short semantic phrases, normally one readable line. A practical baseline is about `40ms` visual lead and `120ms` tail hold when neighboring phrases allow it.
36
+
37
+ Keep captions clear of the face, UI, watermark, progress line, and platform controls. Highlight one meaningful term per phrase. Make entrances and exits quick enough to preserve reading stability.
38
+
39
+ ## Presenter-side keyword presets
40
+
41
+ Use keyword callouts to amplify selected spoken beats. Avoid repeating one identical card throughout the video.
42
+
43
+ Rotate a small family of presets such as:
44
+
45
+ - radial burst;
46
+ - tilted ribbon or sticker;
47
+ - hand-drawn circle or marker stroke;
48
+ - large/small type contrast;
49
+ - staggered word-chip cluster;
50
+ - double-layer outline lockup.
51
+
52
+ Bind each callout to a real spoken stress or ASR word anchor. Separate the entry timing of the kicker, main word, secondary word, marker, rays, and outline by a few frames. Let the callout settle briefly, then collapse before the next idea. Keep it inside a consistent presenter-side safe region and verify the complete motion path does not cover the face or hands.
53
+
54
+ ## Composition and preview
55
+
56
+ Use a deterministic compositor available in the environment. For HyperFrames:
57
+
58
+ 1. load the current HyperFrames workflow and domain instructions;
59
+ 2. give all timed media explicit start, duration, track, and source offset;
60
+ 3. run the required composition check with representative emphasis and transition samples;
61
+ 4. inspect time zero, chapter cuts, layout changes, keyword beats, captions, close, and final frame;
62
+ 5. open the final Studio preview and obtain approval before rendering;
63
+ 6. render at delivery quality only after approval.
64
+
65
+ Measure the assembled stereo program after rendering. Mono narration duplicated into stereo can measure about 3 LU louder, so perform final program normalization from the rendered file.
optional-skills/creative/ai-presenter-video/references/generation.md ADDED
@@ -0,0 +1,83 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Generation
2
+
3
+ Read this file for intake, content, narration, capability selection, paid generation, presenter prompts, or provider changes.
4
+
5
+ ## Inputs and authorization
6
+
7
+ Required:
8
+
9
+ - a topic or script;
10
+ - one local presenter image with one clear adult face;
11
+ - confirmed image rights before remote upload;
12
+ - confirmed adult status from the user.
13
+
14
+ Optional:
15
+
16
+ - authorized voice sample;
17
+ - screen recordings, B-roll, images, charts, brand assets, or source links;
18
+ - audience, duration, language, aspect, style, watermark, music, CTA, provider preference, or previous episode.
19
+
20
+ Inspect the real image. Record visible anchors only: framing, hair, glasses, clothing, accessories, hands, furniture, background geometry, camera height, crop, light, exposure, white balance, embedded text, logos, occlusion, multiple faces, and resolution. Do not infer sensitive traits.
21
+
22
+ When a voice sample exists, listen for one speaker, audible speech duration, language, noise, echo, clipping, music, silence, and codec damage. Record whether cloning is authorized. Keep the original unchanged.
23
+
24
+ ## Content and narration
25
+
26
+ For a topic, use one clear spine:
27
+
28
+ ```text
29
+ hook → promise → 2–4 useful beats → synthesis → close
30
+ ```
31
+
32
+ For a supplied script, preserve factual meaning while improving breath, pronunciation, sentence length, and transitions. Flag material factual edits for approval.
33
+
34
+ Generate the complete approved narration before visual work. Keep one voice identity and one synthesis configuration. Split only for operational limits or clean semantic sections. Preserve raw and normalized copies.
35
+
36
+ Run ASR against final audio. Review names, numbers, English tokens, omitted words, repeated words, and tail speech. Use actual audio durations for every later cut.
37
+
38
+ ## Capability routing
39
+
40
+ Resolve capabilities at execution time:
41
+
42
+ | Capability | Acceptance priority |
43
+ |---|---|
44
+ | Voice generation | authorization, identity, pronunciation, rate control, clean audio |
45
+ | Main presenter | exact audio support, semantic lip sync, identity stability, required duration |
46
+ | Short motion | stable face, one controllable gesture, fixed camera, economical retry |
47
+ | Lip-sync repair | preserves accepted motion while replacing mouth timing with exact audio |
48
+ | Word-timestamp ASR | accurate word start/end times and reviewable output |
49
+ | Timeline compositor | explicit source offsets, frame-accurate seek, deterministic render |
50
+ | Encoder and QA | local probe, loudness, decode, black-frame and contact-sheet support |
51
+
52
+ Inspect current installed tools and official documentation when availability, duration, pricing, or request fields may have changed. Prefer a user-selected provider when it passes the gates. Otherwise choose the simplest available capability that does.
53
+
54
+ Record the actual provider, model, version, region, parameters, price evidence date, task ID, and sanitized request body in `job.json`. Ask before a provider change that affects cost, privacy, voice, appearance, or quality.
55
+
56
+ ## Billing and pilot gate
57
+
58
+ Before the first remote or paid call, state:
59
+
60
+ - files or data being uploaded;
61
+ - capability and selected tool;
62
+ - requested seconds or units;
63
+ - known price or that the cost is unknown;
64
+ - pilot duration and retry ceiling;
65
+ - expected output and main risks.
66
+
67
+ Generate the smallest useful pilot. Continue to a full run only after technical checks and visual review pass. Do not generate a long clip when the edit uses only a short range.
68
+
69
+ ## Presenter prompt structure
70
+
71
+ Write prompts in this order:
72
+
73
+ 1. Bind the user image as the sole presenter and scene reference.
74
+ 2. List only visible identity, clothing, accessory, camera, framing, background, light, exposure, and white-balance anchors.
75
+ 3. Request realistic skin, hair, eye moisture, fabric, breathing, bilateral blinking, and restrained head motion.
76
+ 4. Supply exact dialogue through the tool's supported audio or dialogue field.
77
+ 5. Tie one physically plausible gesture to one phrase and approximate time.
78
+ 6. Reserve a settled, closed-mouth tail.
79
+ 7. Exclude identity, face, glasses, hair, wardrobe, skin tone, background, camera, lighting, finger, hand, dialogue, text, logo, watermark, and extra-person drift.
80
+
81
+ For the main presenter, prioritize mouth timing and identity. Keep hands low or outside frame. For an opening or close, one small gesture may carry the hook or CTA. Keep hands below the collarbone, away from the face and lens, and end the movement before the tail hold.
82
+
83
+ If the body performance is accepted but mouth timing is visibly late, preserve the motion plate and apply lip-sync repair with the exact locked audio and no duration extension.
optional-skills/creative/ai-presenter-video/references/qa-recovery.md ADDED
@@ -0,0 +1,73 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # QA and recovery
2
+
3
+ Read this file before accepting generated media or delivery, and whenever a production fault appears.
4
+
5
+ ## Acceptance gates
6
+
7
+ ### Inputs
8
+
9
+ - Topic or script exists.
10
+ - Presenter image decodes and contains one reviewed adult face.
11
+ - Image rights, adult confirmation, and remote-upload permission are recorded.
12
+ - Any voice sample contains one authorized speaker.
13
+ - Supporting media is probed and its provenance is recorded.
14
+
15
+ ### Audio
16
+
17
+ - Final ASR matches the intended script once, without material omissions or additions.
18
+ - Sections have consistent loudness, commonly near `-17 LUFS`.
19
+ - Assembled program loudness is commonly `-16 ± 0.5 LUFS` unless the destination specifies another target.
20
+ - No clipped words, doubled tracks, echo, clicks, unexpected silence, or truncated tail.
21
+ - Measure the final stereo file; section measurements alone are insufficient.
22
+
23
+ ### Presenter
24
+
25
+ - Expected resolution, frame rate, duration, and decodable streams.
26
+ - No black frames, long exact-frame freezes, progressive darkening, or duration extension.
27
+ - Identity, face geometry, hair, glasses, clothing, accessories, background, crop, exposure, and white balance remain coherent.
28
+ - Mouth follows names, numbers, English tokens, plosives, and phrase endings.
29
+ - Blinks are sparse and bilateral; gestures occur once and settle; hands remain plausible and away from the face.
30
+ - Tail ends with a settled face and resting mouth.
31
+
32
+ ### Composition and delivery
33
+
34
+ - No flash, duplicate presenter, source-time reset, missing overlay, overflow, face obstruction, caption collision, or unreadable UI.
35
+ - Opening, callouts, captions, watermark, progress, and platform safe zones remain compatible.
36
+ - Master and share files have the expected duration, dimensions, frame rate, codec, pixel format, and audio rate.
37
+ - Both files fully decode.
38
+ - Contact sheet covers opening, chapters, emphasis graphics, close, and final frame.
39
+ - Watch the complete video at normal speed before delivery.
40
+
41
+ ## Recovery rules
42
+
43
+ ### Interrupted remote task
44
+
45
+ Poll the saved task ID and download a succeeded result. Resubmit only after a confirmed failure or cancellation.
46
+
47
+ ### Voice identity or loudness changes
48
+
49
+ Confirm one synthesis identity and configuration. Regenerate the mismatching section, normalize again, and rerun ASR. If the final render is louder than the source, confirm video is muted and apply whole-program two-pass loudness correction.
50
+
51
+ ### Presenter changes between chapters
52
+
53
+ Use one continuous audio-driven source with source-time slices. When splitting is unavoidable, lock identity, framing, parameters, light, and quiet edge holds.
54
+
55
+ ### Body motion works but mouth is late
56
+
57
+ Keep the accepted motion plate. Apply lip-sync repair with the exact locked audio and no duration extension. Check speech anchors at numbers, plosives, English tokens, and final syllables.
58
+
59
+ ### Face, glasses, hands, or light drift
60
+
61
+ Retry from the original image with reduced motion and explicit camera, exposure, and white-balance locks. Simplify the gesture and keep hands low. Structural face or finger faults require regeneration; grading cannot correct them.
62
+
63
+ ### Frozen picture-in-picture
64
+
65
+ Confirm the layout uses moving video, source offsets advance continuously, and no poster frame or identical-frame padding replaced the presenter.
66
+
67
+ ### Captions or keyword graphics feel wrong
68
+
69
+ Regenerate timings from the final audio. Split by meaning, shorten visible phrases, and adjust small lead/hold margins. Bind keyword motion to actual spoken anchors and verify its complete path against the face, hands, UI, and captions.
70
+
71
+ ### Three rejected paid candidates
72
+
73
+ Stop. Preserve candidates, prompts, task IDs, cost, and rejection notes. Summarize the recurring failure, remaining options, expected additional cost, and the single variable proposed for the next attempt.
optional-skills/creative/ai-presenter-video/scripts/finalize_delivery.sh ADDED
@@ -0,0 +1,166 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env bash
2
+
3
+ set -euo pipefail
4
+
5
+ usage() {
6
+ printf 'Usage: %s rendered.mp4 output-dir output-stem\n' "$(basename "$0")" >&2
7
+ }
8
+
9
+ die() {
10
+ printf 'ERROR: %s\n' "$*" >&2
11
+ exit 1
12
+ }
13
+
14
+ [[ "$#" -eq 3 ]] || { usage; exit 64; }
15
+
16
+ INPUT="$1"
17
+ OUTPUT_DIR="$2"
18
+ STEM="$3"
19
+
20
+ [[ -f "$INPUT" && -s "$INPUT" ]] || die "input render is missing or empty: $INPUT"
21
+ [[ "$STEM" =~ ^[A-Za-z0-9._-]+$ ]] || die "output stem contains unsupported characters: $STEM"
22
+
23
+ for command in ffmpeg ffprobe jq mktemp awk sed; do
24
+ command -v "$command" >/dev/null 2>&1 || die "required command unavailable: $command"
25
+ done
26
+
27
+ mkdir -p "$OUTPUT_DIR"
28
+ OUTPUT_DIR="$(cd "$OUTPUT_DIR" && pwd -P)"
29
+ INPUT="$(cd "$(dirname "$INPUT")" && pwd -P)/$(basename "$INPUT")"
30
+
31
+ MASTER="$OUTPUT_DIR/${STEM}-master.mp4"
32
+ SHARE="$OUTPUT_DIR/${STEM}-share.mp4"
33
+ REPORT="$OUTPUT_DIR/${STEM}-delivery-report.json"
34
+ CONTACT="$OUTPUT_DIR/${STEM}-contact-sheet.png"
35
+
36
+ # Keep shared reports portable and avoid exposing the developer machine path.
37
+ INPUT_REPORT="$(basename "$INPUT")"
38
+ MASTER_REPORT="$(basename "$MASTER")"
39
+ SHARE_REPORT="$(basename "$SHARE")"
40
+ CONTACT_REPORT="$(basename "$CONTACT")"
41
+
42
+ for output in "$MASTER" "$SHARE" "$REPORT" "$CONTACT"; do
43
+ [[ ! -e "$output" ]] || die "refusing to overwrite existing output: $output"
44
+ done
45
+
46
+ TMP_ROOT="${TMPDIR:-/tmp}"
47
+ TMP_DIR="$(mktemp -d "${TMP_ROOT%/}/presenter-finalize.XXXXXX")"
48
+ trap 'rm -rf -- "$TMP_DIR"' EXIT INT TERM
49
+
50
+ STREAM_JSON="$TMP_DIR/source-probe.json"
51
+ ffprobe -v error -show_streams -show_format -of json "$INPUT" >"$STREAM_JSON"
52
+ jq -e '.streams | any(.codec_type == "video") and any(.codec_type == "audio")' "$STREAM_JSON" >/dev/null \
53
+ || die "input must contain decodable video and audio streams"
54
+
55
+ WIDTH="$(jq -r '[.streams[] | select(.codec_type == "video")][0].width' "$STREAM_JSON")"
56
+ HEIGHT="$(jq -r '[.streams[] | select(.codec_type == "video")][0].height' "$STREAM_JSON")"
57
+ FPS="$(jq -r '[.streams[] | select(.codec_type == "video")][0].avg_frame_rate' "$STREAM_JSON")"
58
+ [[ "$FPS" != "0/0" && -n "$FPS" ]] || FPS="30"
59
+
60
+ MEASURE_LOG="$TMP_DIR/loudnorm-pass1.log"
61
+ ffmpeg -hide_banner -nostdin -nostats -i "$INPUT" \
62
+ -map 0:a:0 -vn \
63
+ -af 'loudnorm=I=-16:TP=-1.5:LRA=9:print_format=json' \
64
+ -f null - >/dev/null 2>"$MEASURE_LOG"
65
+
66
+ MEASURE_JSON="$TMP_DIR/measure.json"
67
+ sed -n '/^{/,/^}/p' "$MEASURE_LOG" >"$MEASURE_JSON"
68
+ jq -e . "$MEASURE_JSON" >/dev/null || die "could not parse loudness measurement"
69
+
70
+ MEASURED_I="$(jq -r .input_i "$MEASURE_JSON")"
71
+ MEASURED_TP="$(jq -r .input_tp "$MEASURE_JSON")"
72
+ MEASURED_LRA="$(jq -r .input_lra "$MEASURE_JSON")"
73
+ MEASURED_THRESH="$(jq -r .input_thresh "$MEASURE_JSON")"
74
+ OFFSET="$(jq -r .target_offset "$MEASURE_JSON")"
75
+
76
+ LOUDNORM="loudnorm=I=-16:TP=-1.5:LRA=9:measured_I=${MEASURED_I}:measured_TP=${MEASURED_TP}:measured_LRA=${MEASURED_LRA}:measured_thresh=${MEASURED_THRESH}:offset=${OFFSET}:linear=true:print_format=summary"
77
+ VIDEO_FILTER="scale=trunc(iw/2)*2:trunc(ih/2)*2:flags=lanczos,setsar=1,fps=${FPS},format=yuv420p"
78
+
79
+ encode() {
80
+ local crf="$1"
81
+ local preset="$2"
82
+ local audio_bitrate="$3"
83
+ local destination="$4"
84
+ local temporary="$5"
85
+
86
+ ffmpeg -hide_banner -nostdin -loglevel warning -stats -i "$INPUT" \
87
+ -map 0:v:0 -map 0:a:0 -sn -dn \
88
+ -vf "$VIDEO_FILTER" -af "$LOUDNORM" \
89
+ -c:v libx264 -preset "$preset" -crf "$crf" -profile:v high \
90
+ -pix_fmt yuv420p -tag:v avc1 -fps_mode cfr \
91
+ -color_primaries bt709 -color_trc bt709 -colorspace bt709 \
92
+ -c:a aac -b:a "$audio_bitrate" -ar 48000 -ac 2 \
93
+ -map_metadata -1 -map_chapters -1 -movflags +faststart \
94
+ "$temporary"
95
+ [[ -s "$temporary" ]] || die "encoder produced an empty output"
96
+ mv -- "$temporary" "$destination"
97
+ }
98
+
99
+ encode 16 slow 256k "$MASTER" "$TMP_DIR/master.mp4"
100
+ encode 24 medium 160k "$SHARE" "$TMP_DIR/share.mp4"
101
+
102
+ for file in "$MASTER" "$SHARE"; do
103
+ ffmpeg -hide_banner -nostdin -v error -xerror -i "$file" \
104
+ -map 0:v:0 -map 0:a:0 -f null - >/dev/null
105
+ done
106
+
107
+ ffprobe -v error -show_streams -show_format -of json "$MASTER" >"$TMP_DIR/master-probe.json"
108
+ ffprobe -v error -show_streams -show_format -of json "$SHARE" >"$TMP_DIR/share-probe.json"
109
+
110
+ for probe_file in "$STREAM_JSON" "$TMP_DIR/master-probe.json" "$TMP_DIR/share-probe.json"; do
111
+ jq 'if .format.filename? then .format.filename = (.format.filename | split("/") | last) else . end' \
112
+ "$probe_file" >"${probe_file}.portable"
113
+ mv -- "${probe_file}.portable" "$probe_file"
114
+ done
115
+
116
+ ffmpeg -hide_banner -nostdin -i "$MASTER" \
117
+ -vf 'blackdetect=d=0.10:pix_th=0.02' -an -f null - \
118
+ >/dev/null 2>"$TMP_DIR/blackdetect.log"
119
+ BLACK_EVENTS="$(grep -c 'black_start:' "$TMP_DIR/blackdetect.log" || true)"
120
+
121
+ DURATION="$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$MASTER")"
122
+ awk -v duration="$DURATION" 'BEGIN {
123
+ p[1]=0.2; p[2]=duration*0.125; p[3]=duration*0.25; p[4]=duration*0.375;
124
+ p[5]=duration*0.5; p[6]=duration*0.625; p[7]=duration*0.75;
125
+ p[8]=duration*0.875; p[9]=duration-0.2;
126
+ for(i=1;i<=9;i++) printf "%.6f\n", p[i]
127
+ }' >"$TMP_DIR/timestamps.txt"
128
+
129
+ if (( WIDTH > HEIGHT )); then
130
+ CONTACT_FRAME_FILTER='scale=480:270:force_original_aspect_ratio=decrease:flags=lanczos,pad=480:270:(ow-iw)/2:(oh-ih)/2:color=black'
131
+ elif (( HEIGHT > WIDTH )); then
132
+ CONTACT_FRAME_FILTER='scale=270:480:force_original_aspect_ratio=decrease:flags=lanczos,pad=270:480:(ow-iw)/2:(oh-ih)/2:color=black'
133
+ else
134
+ CONTACT_FRAME_FILTER='scale=360:360:force_original_aspect_ratio=decrease:flags=lanczos,pad=360:360:(ow-iw)/2:(oh-ih)/2:color=black'
135
+ fi
136
+
137
+ index=0
138
+ while IFS= read -r timestamp; do
139
+ index=$((index + 1))
140
+ printf -v frame '%s/frame-%02d.png' "$TMP_DIR" "$index"
141
+ ffmpeg -hide_banner -nostdin -loglevel error -ss "$timestamp" -i "$MASTER" \
142
+ -frames:v 1 -vf "$CONTACT_FRAME_FILTER" -update 1 "$frame"
143
+ done <"$TMP_DIR/timestamps.txt"
144
+
145
+ ffmpeg -hide_banner -nostdin -loglevel error -framerate 1 -start_number 1 \
146
+ -i "$TMP_DIR/frame-%02d.png" -frames:v 1 \
147
+ -vf 'tile=3x3:padding=12:margin=12:color=0x101218' -update 1 "$TMP_DIR/contact.png"
148
+ mv -- "$TMP_DIR/contact.png" "$CONTACT"
149
+
150
+ jq -n \
151
+ --arg status verified \
152
+ --arg input "$INPUT_REPORT" \
153
+ --arg master "$MASTER_REPORT" \
154
+ --arg share "$SHARE_REPORT" \
155
+ --arg contact "$CONTACT_REPORT" \
156
+ --arg duration "$DURATION" \
157
+ --argjson black_events "$BLACK_EVENTS" \
158
+ --slurpfile measured "$MEASURE_JSON" \
159
+ --slurpfile source_probe "$STREAM_JSON" \
160
+ --slurpfile master_probe "$TMP_DIR/master-probe.json" \
161
+ --slurpfile share_probe "$TMP_DIR/share-probe.json" \
162
+ '{status:$status,input:$input,master:$master,share:$share,contact_sheet:$contact,duration_s:($duration|tonumber),source_loudness:$measured[0],source_probe:$source_probe[0],master_probe:$master_probe[0],share_probe:$share_probe[0],full_decode_passed:true,black_frame_events:$black_events}' \
163
+ >"$TMP_DIR/report.json"
164
+ mv -- "$TMP_DIR/report.json" "$REPORT"
165
+
166
+ printf 'Master: %s\nShare: %s\nReport: %s\nContact: %s\n' "$MASTER" "$SHARE" "$REPORT" "$CONTACT"
optional-skills/creative/ai-presenter-video/scripts/init_job.py ADDED
@@ -0,0 +1,151 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Create a non-overwriting presenter-video job from minimal inputs."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import json
8
+ import re
9
+ import sys
10
+ from pathlib import Path
11
+
12
+
13
+ SKILL_DIR = Path(__file__).resolve().parent.parent
14
+ TEMPLATE = SKILL_DIR / "assets" / "job.template.json"
15
+ ASPECT_DEFAULTS = {
16
+ "9:16": (1080, 1920),
17
+ "16:9": (1920, 1080),
18
+ "1:1": (1080, 1080),
19
+ "4:5": (1080, 1350),
20
+ }
21
+
22
+
23
+ def absolute_existing(path_text: str, label: str) -> str:
24
+ path = Path(path_text).expanduser().resolve()
25
+ if not path.is_file():
26
+ raise ValueError(f"{label} does not exist or is not a file: {path}")
27
+ return str(path)
28
+
29
+
30
+ def slugify(value: str) -> str:
31
+ slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
32
+ return slug or "presenter-video"
33
+
34
+
35
+ def parse_args() -> argparse.Namespace:
36
+ parser = argparse.ArgumentParser(description=__doc__)
37
+ parser.add_argument("--job-dir", required=True)
38
+ parser.add_argument("--presenter-image", required=True)
39
+ source = parser.add_mutually_exclusive_group(required=True)
40
+ source.add_argument("--topic")
41
+ source.add_argument("--script", help="Existing local script file")
42
+ parser.add_argument("--voice-sample")
43
+ parser.add_argument("--supporting-media", action="append", default=[])
44
+ parser.add_argument("--language", default="auto")
45
+ parser.add_argument("--audience", default="general")
46
+ parser.add_argument("--duration", type=float, default=60.0)
47
+ parser.add_argument("--aspect", choices=sorted(ASPECT_DEFAULTS), default="9:16")
48
+ parser.add_argument("--width", type=int)
49
+ parser.add_argument("--height", type=int)
50
+ parser.add_argument("--fps", type=int, choices=(24, 25, 30, 50, 60), default=30)
51
+ parser.add_argument("--style", default="credible contemporary presenter")
52
+ parser.add_argument("--watermark", default="")
53
+ parser.add_argument("--cta", default="")
54
+ parser.add_argument("--rights-confirmed", action="store_true")
55
+ parser.add_argument("--adult-presenter-confirmed", action="store_true")
56
+ parser.add_argument("--remote-upload-approved", action="store_true")
57
+ parser.add_argument("--voice-clone-approved", action="store_true")
58
+ return parser.parse_args()
59
+
60
+
61
+ def main() -> int:
62
+ args = parse_args()
63
+ if not 5 <= args.duration <= 1800:
64
+ raise ValueError("--duration must be between 5 and 1800 seconds")
65
+ if (args.width is None) != (args.height is None):
66
+ raise ValueError("--width and --height must be supplied together")
67
+
68
+ width, height = ASPECT_DEFAULTS[args.aspect]
69
+ if args.width is not None and args.height is not None:
70
+ width, height = args.width, args.height
71
+ if min(width, height) < 256 or max(width, height) > 7680:
72
+ raise ValueError("custom dimensions must be between 256 and 7680 pixels")
73
+
74
+ job_dir = Path(args.job_dir).expanduser().resolve()
75
+ if job_dir.exists() and any(job_dir.iterdir()):
76
+ raise ValueError(f"job directory must be absent or empty: {job_dir}")
77
+ job_dir.mkdir(parents=True, exist_ok=True)
78
+
79
+ manifest = json.loads(TEMPLATE.read_text(encoding="utf-8"))
80
+ manifest["job_id"] = slugify(job_dir.name)
81
+ manifest["input"]["topic"] = (args.topic or "").strip()
82
+ manifest["input"]["script_path"] = (
83
+ absolute_existing(args.script, "script") if args.script else ""
84
+ )
85
+ manifest["input"]["presenter_image"] = absolute_existing(
86
+ args.presenter_image, "presenter image"
87
+ )
88
+ manifest["input"]["voice_sample"] = (
89
+ absolute_existing(args.voice_sample, "voice sample")
90
+ if args.voice_sample
91
+ else ""
92
+ )
93
+ manifest["input"]["supporting_media"] = [
94
+ absolute_existing(item, "supporting media") for item in args.supporting_media
95
+ ]
96
+ manifest["input"]["rights_confirmed"] = args.rights_confirmed
97
+ manifest["input"]["adult_presenter_confirmed"] = args.adult_presenter_confirmed
98
+ manifest["input"]["remote_upload_approved"] = args.remote_upload_approved
99
+ manifest["input"]["voice_clone_approved"] = args.voice_clone_approved
100
+
101
+ creative = manifest["creative"]
102
+ creative.update(
103
+ {
104
+ "language": args.language,
105
+ "audience": args.audience,
106
+ "duration_target_s": args.duration,
107
+ "aspect": args.aspect,
108
+ "width": width,
109
+ "height": height,
110
+ "fps": args.fps,
111
+ "style": args.style,
112
+ "watermark": args.watermark,
113
+ "cta": args.cta,
114
+ }
115
+ )
116
+
117
+ directories = [
118
+ "docs",
119
+ "assets/source",
120
+ "assets/audio/reference",
121
+ "assets/audio/raw",
122
+ "assets/audio/final",
123
+ "assets/video/candidates",
124
+ "assets/video/selected",
125
+ "assets/video/render",
126
+ "assets/captions",
127
+ "qa/requests",
128
+ "qa/asr",
129
+ "qa/contacts",
130
+ "qa/reports",
131
+ "renders",
132
+ "outputs",
133
+ ]
134
+ for relative in directories:
135
+ (job_dir / relative).mkdir(parents=True, exist_ok=True)
136
+
137
+ job_path = job_dir / "job.json"
138
+ job_path.write_text(
139
+ json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
140
+ encoding="utf-8",
141
+ )
142
+ print(json.dumps({"job": str(job_path), "state": "intake"}, ensure_ascii=False))
143
+ return 0
144
+
145
+
146
+ if __name__ == "__main__":
147
+ try:
148
+ raise SystemExit(main())
149
+ except ValueError as exc:
150
+ print(f"ERROR: {exc}", file=sys.stderr)
151
+ raise SystemExit(2)
optional-skills/creative/ai-presenter-video/scripts/preflight.py ADDED
@@ -0,0 +1,177 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Validate a presenter-video job and write a machine-readable preflight report."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ import shutil
8
+ import subprocess
9
+ import sys
10
+ from pathlib import Path
11
+ from typing import Any
12
+
13
+
14
+ def probe(path: Path) -> dict[str, Any]:
15
+ result = subprocess.run(
16
+ [
17
+ "ffprobe",
18
+ "-v",
19
+ "error",
20
+ "-show_entries",
21
+ "stream=index,codec_type,codec_name,width,height,pix_fmt,sample_rate,channels,r_frame_rate:format=duration,size,bit_rate",
22
+ "-of",
23
+ "json",
24
+ str(path),
25
+ ],
26
+ check=True,
27
+ capture_output=True,
28
+ text=True,
29
+ )
30
+ return json.loads(result.stdout)
31
+
32
+
33
+ def require_file(value: str, label: str, errors: list[str]) -> Path | None:
34
+ if not value:
35
+ errors.append(f"missing {label}")
36
+ return None
37
+ path = Path(value).expanduser().resolve()
38
+ if not path.is_file():
39
+ errors.append(f"{label} is not a file: {path}")
40
+ return None
41
+ return path
42
+
43
+
44
+ def write_atomic(path: Path, text: str) -> None:
45
+ temporary = path.with_suffix(path.suffix + ".tmp")
46
+ temporary.write_text(text, encoding="utf-8")
47
+ temporary.replace(path)
48
+
49
+
50
+ def main() -> int:
51
+ if len(sys.argv) != 2:
52
+ print("Usage: preflight.py ~/Videos/my-presenter-video/job.json", file=sys.stderr)
53
+ return 64
54
+ if not shutil.which("ffprobe"):
55
+ print("ERROR: ffprobe is required", file=sys.stderr)
56
+ return 2
57
+
58
+ job_path = Path(sys.argv[1]).expanduser().resolve()
59
+ if not job_path.is_file():
60
+ print(f"ERROR: job manifest does not exist: {job_path}", file=sys.stderr)
61
+ return 2
62
+ job = json.loads(job_path.read_text(encoding="utf-8"))
63
+ job_dir = job_path.parent
64
+ errors: list[str] = []
65
+ remote_blockers: list[str] = []
66
+ warnings: list[str] = []
67
+ media: dict[str, Any] = {}
68
+
69
+ input_data = job.get("input", {})
70
+ topic = str(input_data.get("topic", "")).strip()
71
+ script_text = str(input_data.get("script_path", "")).strip()
72
+ if not topic and not script_text:
73
+ errors.append("topic or script_path is required")
74
+ if script_text:
75
+ require_file(script_text, "script", errors)
76
+
77
+ image = require_file(str(input_data.get("presenter_image", "")), "presenter image", errors)
78
+ if image:
79
+ try:
80
+ media["presenter_image"] = probe(image)
81
+ streams = [
82
+ stream
83
+ for stream in media["presenter_image"].get("streams", [])
84
+ if stream.get("codec_type") == "video"
85
+ ]
86
+ if not streams:
87
+ errors.append("presenter image has no decodable image/video stream")
88
+ else:
89
+ width = int(streams[0].get("width") or 0)
90
+ height = int(streams[0].get("height") or 0)
91
+ if min(width, height) < 512:
92
+ warnings.append(f"presenter image is low resolution: {width}x{height}")
93
+ except (subprocess.CalledProcessError, json.JSONDecodeError) as exc:
94
+ errors.append(f"could not decode presenter image: {exc}")
95
+
96
+ voice_value = str(input_data.get("voice_sample", "")).strip()
97
+ if voice_value:
98
+ voice = require_file(voice_value, "voice sample", errors)
99
+ if voice:
100
+ try:
101
+ media["voice_sample"] = probe(voice)
102
+ streams = [
103
+ stream
104
+ for stream in media["voice_sample"].get("streams", [])
105
+ if stream.get("codec_type") == "audio"
106
+ ]
107
+ if not streams:
108
+ errors.append("voice sample has no audio stream")
109
+ duration = float(media["voice_sample"].get("format", {}).get("duration") or 0)
110
+ if duration < 4:
111
+ warnings.append(f"voice sample is short: {duration:.3f}s")
112
+ if duration > 60:
113
+ warnings.append(f"voice sample is unusually long: {duration:.3f}s")
114
+ except (subprocess.CalledProcessError, json.JSONDecodeError, ValueError) as exc:
115
+ errors.append(f"could not decode voice sample: {exc}")
116
+ if not input_data.get("voice_clone_approved"):
117
+ remote_blockers.append("voice_clone_approved must be true before voice cloning")
118
+ else:
119
+ warnings.append("no voice sample supplied; use and record a stock voice")
120
+
121
+ supporting_reports = []
122
+ for value in input_data.get("supporting_media", []):
123
+ path = require_file(str(value), "supporting media", errors)
124
+ if path:
125
+ try:
126
+ supporting_reports.append({"file": path.name, "probe": probe(path)})
127
+ except (subprocess.CalledProcessError, json.JSONDecodeError) as exc:
128
+ errors.append(f"could not decode supporting media {path}: {exc}")
129
+ media["supporting_media"] = supporting_reports
130
+
131
+ if not input_data.get("rights_confirmed"):
132
+ remote_blockers.append("rights_confirmed must be true before presenter synthesis")
133
+ if not input_data.get("adult_presenter_confirmed"):
134
+ remote_blockers.append("adult_presenter_confirmed must be true before presenter synthesis")
135
+ if not input_data.get("remote_upload_approved"):
136
+ remote_blockers.append("remote_upload_approved must be true before remote generation")
137
+
138
+ manual = job.get("manual_input_review", {})
139
+ for key in ("image_viewed", "single_clear_face", "image_has_no_unwanted_text"):
140
+ if not manual.get(key):
141
+ errors.append(f"manual_input_review.{key} must be true")
142
+ if voice_value:
143
+ for key in ("voice_sample_listened", "single_clear_speaker"):
144
+ if not manual.get(key):
145
+ errors.append(f"manual_input_review.{key} must be true")
146
+
147
+ creative = job.get("creative", {})
148
+ duration = float(creative.get("duration_target_s") or 0)
149
+ if not 5 <= duration <= 1800:
150
+ errors.append("creative.duration_target_s must be between 5 and 1800")
151
+ width = int(creative.get("width") or 0)
152
+ height = int(creative.get("height") or 0)
153
+ if min(width, height) < 256 or max(width, height) > 7680:
154
+ errors.append("creative width/height must be between 256 and 7680")
155
+ if int(creative.get("fps") or 0) not in (24, 25, 30, 50, 60):
156
+ errors.append("creative.fps must be one of 24, 25, 30, 50, or 60")
157
+
158
+ report_path = job_dir / "qa" / "reports" / "preflight.json"
159
+ report_path.parent.mkdir(parents=True, exist_ok=True)
160
+ report = {
161
+ "ok": not errors,
162
+ "remote_ready": not errors and not remote_blockers,
163
+ "job": job_path.name,
164
+ "errors": errors,
165
+ "remote_blockers": remote_blockers,
166
+ "warnings": warnings,
167
+ "media": media,
168
+ }
169
+ write_atomic(report_path, json.dumps(report, ensure_ascii=False, indent=2) + "\n")
170
+ job.setdefault("qa", {})["preflight_report"] = "qa/reports/preflight.json"
171
+ write_atomic(job_path, json.dumps(job, ensure_ascii=False, indent=2) + "\n")
172
+ print(json.dumps(report, ensure_ascii=False, indent=2))
173
+ return 0 if not errors else 1
174
+
175
+
176
+ if __name__ == "__main__":
177
+ raise SystemExit(main())
optional-skills/creative/archify/SKILL.md ADDED
@@ -0,0 +1,52 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ name: archify
3
+ description: Validated interactive HTML diagrams, upstream-maintained.
4
+ version: 2.17.0
5
+ author: tt-a1i
6
+ license: MIT
7
+ platforms: [linux, macos, windows]
8
+ metadata:
9
+ hermes:
10
+ tags: [diagram, architecture, workflow, sequence, dataflow, state-machine, mermaid, html, svg]
11
+ category: creative
12
+ related_skills: [architecture-diagram, excalidraw, concept-diagrams]
13
+ upstream:
14
+ repo: tt-a1i/archify
15
+ path: archify
16
+ ---
17
+
18
+ # Archify (upstream-maintained)
19
+
20
+ > **Catalog stub.** This entry is maintained upstream at
21
+ > [tt-a1i/archify](https://github.com/tt-a1i/archify): the project ships a
22
+ > self-contained skill directory (`archify/`) with the Node CLI, schemas,
23
+ > renderers, examples and references. `hermes skills install
24
+ > official/creative/archify` pulls the current tree live from that repo
25
+ > (quarantined and scanned like any hub install) — this directory holds only
26
+ > the catalog metadata, so the vendored copy can never go stale.
27
+
28
+ Archify turns a small typed JSON spec into a self-contained, explorable HTML
29
+ diagram: `architecture`, `workflow`, `sequence`, `dataflow` and `lifecycle`
30
+ (state machine) types, dark/light themes, pan/zoom, search, relationship
31
+ tracing, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. It accepts
32
+ plain-language requirements or pasted Mermaid (`flowchart`, `sequenceDiagram`,
33
+ `stateDiagram`) and can read repository evidence when the diagram must reflect
34
+ real code. Every candidate goes through a 9-check `validate` / `deliver`
35
+ receipt, so the output is verifiable rather than eyeballed.
36
+
37
+ ## Prerequisites
38
+
39
+ - Node.js 18+ on `PATH` (`node bin/archify.mjs doctor` confirms the install;
40
+ no `npm install` is needed inside the skill package).
41
+ - Installs pull ~200 files (~8 MB, mostly upstream tests and examples) from
42
+ GitHub; the fetch is pinned to one tree SHA, recorded in the bundle metadata.
43
+ - Upstream's "Update awareness" step runs `scripts/check-update.mjs`, which
44
+ reads a release manifest from GitHub and only prints a notice — it never
45
+ downloads or installs anything. Skip it if outbound calls are unwanted.
46
+
47
+ After install, the bundled `architecture-diagram` skill remains the
48
+ zero-dependency fallback (it ports the same Cocoon AI lineage archify grew out
49
+ of); prefer archify when the user wants validated receipts, Mermaid conversion,
50
+ sequence/lifecycle types, or export beyond a single HTML file.
51
+
52
+ Full documentation: https://github.com/tt-a1i/archify#readme
optional-skills/creative/ascii-art/SKILL.md ADDED
@@ -0,0 +1,322 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ name: ascii-art
3
+ description: "ASCII art: pyfiglet, cowsay, boxes, image-to-ascii."
4
+ version: 4.0.0
5
+ author: 0xbyt4, Hermes Agent
6
+ license: MIT
7
+ dependencies: []
8
+ platforms: [linux, macos, windows]
9
+ metadata:
10
+ hermes:
11
+ tags: [ASCII, Art, Banners, Creative, Unicode, Text-Art, pyfiglet, figlet, cowsay, boxes]
12
+ related_skills: [excalidraw]
13
+
14
+ ---
15
+
16
+ # ASCII Art Skill
17
+
18
+ Multiple tools for different ASCII art needs. All tools are local CLI programs or free REST APIs — no API keys required.
19
+
20
+ ## Tool 1: Text Banners (pyfiglet — local)
21
+
22
+ Render text as large ASCII art banners. 571 built-in fonts.
23
+
24
+ ### Setup
25
+
26
+ ```bash
27
+ pip install pyfiglet --break-system-packages -q
28
+ ```
29
+
30
+ ### Usage
31
+
32
+ ```bash
33
+ python -m pyfiglet "YOUR TEXT" -f slant
34
+ python -m pyfiglet "TEXT" -f doom -w 80 # Set width
35
+ python -m pyfiglet --list_fonts # List all 571 fonts
36
+ ```
37
+
38
+ ### Recommended fonts
39
+
40
+ | Style | Font | Best for |
41
+ |-------|------|----------|
42
+ | Clean & modern | `slant` | Project names, headers |
43
+ | Bold & blocky | `doom` | Titles, logos |
44
+ | Big & readable | `big` | Banners |
45
+ | Classic banner | `banner3` | Wide displays |
46
+ | Compact | `small` | Subtitles |
47
+ | Cyberpunk | `cyberlarge` | Tech themes |
48
+ | 3D effect | `3-d` | Splash screens |
49
+ | Gothic | `gothic` | Dramatic text |
50
+
51
+ ### Tips
52
+
53
+ - Preview 2-3 fonts and let the user pick their favorite
54
+ - Short text (1-8 chars) works best with detailed fonts like `doom` or `block`
55
+ - Long text works better with compact fonts like `small` or `mini`
56
+
57
+ ## Tool 2: Text Banners (asciified API — remote, no install)
58
+
59
+ Free REST API that converts text to ASCII art. 250+ FIGlet fonts. Returns plain text directly — no parsing needed. Use this when pyfiglet is not installed or as a quick alternative.
60
+
61
+ ### Usage (via terminal curl)
62
+
63
+ ```bash
64
+ # Basic text banner (default font)
65
+ curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello+World"
66
+
67
+ # With a specific font
68
+ curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Slant"
69
+ curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Doom"
70
+ curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Star+Wars"
71
+ curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=3-D"
72
+ curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Banner3"
73
+
74
+ # List all available fonts (returns JSON array)
75
+ curl -s "https://asciified.thelicato.io/api/v2/fonts"
76
+ ```
77
+
78
+ ### Tips
79
+
80
+ - URL-encode spaces as `+` in the text parameter
81
+ - The response is plain text ASCII art — no JSON wrapping, ready to display
82
+ - Font names are case-sensitive; use the fonts endpoint to get exact names
83
+ - Works from any terminal with curl — no Python or pip needed
84
+
85
+ ## Tool 3: Cowsay (Message Art)
86
+
87
+ Classic tool that wraps text in a speech bubble with an ASCII character.
88
+
89
+ ### Setup
90
+
91
+ ```bash
92
+ sudo apt install cowsay -y # Debian/Ubuntu
93
+ # brew install cowsay # macOS
94
+ ```
95
+
96
+ ### Usage
97
+
98
+ ```bash
99
+ cowsay "Hello World"
100
+ cowsay -f tux "Linux rules" # Tux the penguin
101
+ cowsay -f dragon "Rawr!" # Dragon
102
+ cowsay -f stegosaurus "Roar!" # Stegosaurus
103
+ cowthink "Hmm..." # Thought bubble
104
+ cowsay -l # List all characters
105
+ ```
106
+
107
+ ### Available characters (50+)
108
+
109
+ `beavis.zen`, `bong`, `bunny`, `cheese`, `daemon`, `default`, `dragon`,
110
+ `dragon-and-cow`, `elephant`, `eyes`, `flaming-skull`, `ghostbusters`,
111
+ `hellokitty`, `kiss`, `kitty`, `koala`, `luke-koala`, `mech-and-cow`,
112
+ `meow`, `moofasa`, `moose`, `ren`, `sheep`, `skeleton`, `small`,
113
+ `stegosaurus`, `stimpy`, `supermilker`, `surgery`, `three-eyes`,
114
+ `turkey`, `turtle`, `tux`, `udder`, `vader`, `vader-koala`, `www`
115
+
116
+ ### Eye/tongue modifiers
117
+
118
+ ```bash
119
+ cowsay -b "Borg" # =_= eyes
120
+ cowsay -d "Dead" # x_x eyes
121
+ cowsay -g "Greedy" # $_$ eyes
122
+ cowsay -p "Paranoid" # @_@ eyes
123
+ cowsay -s "Stoned" # *_* eyes
124
+ cowsay -w "Wired" # O_O eyes
125
+ cowsay -e "OO" "Msg" # Custom eyes
126
+ cowsay -T "U " "Msg" # Custom tongue
127
+ ```
128
+
129
+ ## Tool 4: Boxes (Decorative Borders)
130
+
131
+ Draw decorative ASCII art borders/frames around any text. 70+ built-in designs.
132
+
133
+ ### Setup
134
+
135
+ ```bash
136
+ sudo apt install boxes -y # Debian/Ubuntu
137
+ # brew install boxes # macOS
138
+ ```
139
+
140
+ ### Usage
141
+
142
+ ```bash
143
+ echo "Hello World" | boxes # Default box
144
+ echo "Hello World" | boxes -d stone # Stone border
145
+ echo "Hello World" | boxes -d parchment # Parchment scroll
146
+ echo "Hello World" | boxes -d cat # Cat border
147
+ echo "Hello World" | boxes -d dog # Dog border
148
+ echo "Hello World" | boxes -d unicornsay # Unicorn
149
+ echo "Hello World" | boxes -d diamonds # Diamond pattern
150
+ echo "Hello World" | boxes -d c-cmt # C-style comment
151
+ echo "Hello World" | boxes -d html-cmt # HTML comment
152
+ echo "Hello World" | boxes -a c # Center text
153
+ boxes -l # List all 70+ designs
154
+ ```
155
+
156
+ ### Combine with pyfiglet or asciified
157
+
158
+ ```bash
159
+ python -m pyfiglet "HERMES" -f slant | boxes -d stone
160
+ # Or without pyfiglet installed:
161
+ curl -s "https://asciified.thelicato.io/api/v2/ascii?text=HERMES&font=Slant" | boxes -d stone
162
+ ```
163
+
164
+ ## Tool 5: TOIlet (Colored Text Art)
165
+
166
+ Like pyfiglet but with ANSI color effects and visual filters. Great for terminal eye candy.
167
+
168
+ ### Setup
169
+
170
+ ```bash
171
+ sudo apt install toilet toilet-fonts -y # Debian/Ubuntu
172
+ # brew install toilet # macOS
173
+ ```
174
+
175
+ ### Usage
176
+
177
+ ```bash
178
+ toilet "Hello World" # Basic text art
179
+ toilet -f bigmono12 "Hello" # Specific font
180
+ toilet --gay "Rainbow!" # Rainbow coloring
181
+ toilet --metal "Metal!" # Metallic effect
182
+ toilet -F border "Bordered" # Add border
183
+ toilet -F border --gay "Fancy!" # Combined effects
184
+ toilet -f pagga "Block" # Block-style font (unique to toilet)
185
+ toilet -F list # List available filters
186
+ ```
187
+
188
+ ### Filters
189
+
190
+ `crop`, `gay` (rainbow), `metal`, `flip`, `flop`, `180`, `left`, `right`, `border`
191
+
192
+ **Note**: toilet outputs ANSI escape codes for colors — works in terminals but may not render in all contexts (e.g., plain text files, some chat platforms).
193
+
194
+ ## Tool 6: Image to ASCII Art
195
+
196
+ Convert images (PNG, JPEG, GIF, WEBP) to ASCII art.
197
+
198
+ ### Option A: ascii-image-converter (recommended, modern)
199
+
200
+ ```bash
201
+ # Install
202
+ sudo snap install ascii-image-converter
203
+ # OR: go install github.com/TheZoraiz/ascii-image-converter@latest
204
+ ```
205
+
206
+ ```bash
207
+ ascii-image-converter image.png # Basic
208
+ ascii-image-converter image.png -C # Color output
209
+ ascii-image-converter image.png -d 60,30 # Set dimensions
210
+ ascii-image-converter image.png -b # Braille characters
211
+ ascii-image-converter image.png -n # Negative/inverted
212
+ ascii-image-converter https://url/image.jpg # Direct URL
213
+ ascii-image-converter image.png --save-txt out # Save as text
214
+ ```
215
+
216
+ ### Option B: jp2a (lightweight, JPEG only)
217
+
218
+ ```bash
219
+ sudo apt install jp2a -y
220
+ jp2a --width=80 image.jpg
221
+ jp2a --colors image.jpg # Colorized
222
+ ```
223
+
224
+ ## Tool 7: Search Pre-Made ASCII Art
225
+
226
+ Search curated ASCII art from the web. Use `terminal` with `curl`.
227
+
228
+ ### Source A: ascii.co.uk (recommended for pre-made art)
229
+
230
+ Large collection of classic ASCII art organized by subject. Art is inside HTML `<pre>` tags. Fetch the page with curl, then extract art with a small Python snippet.
231
+
232
+ **URL pattern:** `https://ascii.co.uk/art/{subject}`
233
+
234
+ **Step 1 — Fetch the page:**
235
+
236
+ ```bash
237
+ curl -s 'https://ascii.co.uk/art/cat' -o /tmp/ascii_art.html
238
+ ```
239
+
240
+ **Step 2 — Extract art from pre tags:**
241
+
242
+ ```python
243
+ import re, html
244
+ with open('/tmp/ascii_art.html') as f:
245
+ text = f.read()
246
+ arts = re.findall(r'<pre[^>]*>(.*?)</pre>', text, re.DOTALL)
247
+ for art in arts:
248
+ clean = re.sub(r'<[^>]+>', '', art)
249
+ clean = html.unescape(clean).strip()
250
+ if len(clean) > 30:
251
+ print(clean)
252
+ print('\n---\n')
253
+ ```
254
+
255
+ **Available subjects** (use as URL path):
256
+ - Animals: `cat`, `dog`, `horse`, `bird`, `fish`, `dragon`, `snake`, `rabbit`, `elephant`, `dolphin`, `butterfly`, `owl`, `wolf`, `bear`, `penguin`, `turtle`
257
+ - Objects: `car`, `ship`, `airplane`, `rocket`, `guitar`, `computer`, `coffee`, `beer`, `cake`, `house`, `castle`, `sword`, `crown`, `key`
258
+ - Nature: `tree`, `flower`, `sun`, `moon`, `star`, `mountain`, `ocean`, `rainbow`
259
+ - Characters: `skull`, `robot`, `angel`, `wizard`, `pirate`, `ninja`, `alien`
260
+ - Holidays: `christmas`, `halloween`, `valentine`
261
+
262
+ **Tips:**
263
+ - Preserve artist signatures/initials — important etiquette
264
+ - Multiple art pieces per page — pick the best one for the user
265
+ - Works reliably via curl, no JavaScript needed
266
+
267
+ ### Source B: GitHub Octocat API (fun easter egg)
268
+
269
+ Returns a random GitHub Octocat with a wise quote. No auth needed.
270
+
271
+ ```bash
272
+ curl -s https://api.github.com/octocat
273
+ ```
274
+
275
+ ## Tool 8: Fun ASCII Utilities (via curl)
276
+
277
+ These free services return ASCII art directly — great for fun extras.
278
+
279
+ ### QR Codes as ASCII Art
280
+
281
+ ```bash
282
+ curl -s "qrenco.de/Hello+World"
283
+ curl -s "qrenco.de/https://example.com"
284
+ ```
285
+
286
+ ### Weather as ASCII Art
287
+
288
+ ```bash
289
+ curl -s "wttr.in/London" # Full weather report with ASCII graphics
290
+ curl -s "wttr.in/Moon" # Moon phase in ASCII art
291
+ curl -s "v2.wttr.in/London" # Detailed version
292
+ ```
293
+
294
+ ## Tool 9: LLM-Generated Custom Art (Fallback)
295
+
296
+ When tools above don't have what's needed, generate ASCII art directly using these Unicode characters:
297
+
298
+ ### Character Palette
299
+
300
+ **Box Drawing:** `╔ ╗ ╚ ╝ ║ ═ ╠ ╣ ╦ ╩ ╬ ┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼ ╭ ╮ ╰ ╯`
301
+
302
+ **Block Elements:** `░ ▒ ▓ █ ▄ ▀ ▌ ▐ ▖ ▗ ▘ ▝ ▚ ▞`
303
+
304
+ **Geometric & Symbols:** `◆ ◇ ◈ ● ○ ◉ ■ □ ▲ △ ▼ ▽ ★ ☆ ✦ ✧ ◀ ▶ ◁ ▷ ⬡ ⬢ ⌂`
305
+
306
+ ### Rules
307
+
308
+ - Max width: 60 characters per line (terminal-safe)
309
+ - Max height: 15 lines for banners, 25 for scenes
310
+ - Monospace only: output must render correctly in fixed-width fonts
311
+
312
+ ## Decision Flow
313
+
314
+ 1. **Text as a banner** → pyfiglet if installed, otherwise asciified API via curl
315
+ 2. **Wrap a message in fun character art** → cowsay
316
+ 3. **Add decorative border/frame** → boxes (can combine with pyfiglet/asciified)
317
+ 4. **Art of a specific thing** (cat, rocket, dragon) → ascii.co.uk via curl + parsing
318
+ 5. **Convert an image to ASCII** → ascii-image-converter or jp2a
319
+ 6. **QR code** → qrenco.de via curl
320
+ 7. **Weather/moon art** → wttr.in via curl
321
+ 8. **Something custom/creative** → LLM generation with Unicode palette
322
+ 9. **Any tool not installed** → install it, or fall back to next option
optional-skills/creative/audiocraft-audio-generation/SKILL.md ADDED
@@ -0,0 +1,569 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ name: audiocraft-audio-generation
3
+ description: "AudioCraft: MusicGen text-to-music, AudioGen text-to-sound."
4
+ version: 1.0.0
5
+ author: Orchestra Research
6
+ license: MIT
7
+ dependencies: [audiocraft, torch>=2.0.0, transformers>=4.30.0]
8
+ platforms: [linux, macos]
9
+ metadata:
10
+ hermes:
11
+ tags: [Multimodal, Audio Generation, Text-to-Music, Text-to-Audio, MusicGen]
12
+ related_skills: [heartmula, songwriting-and-ai-music]
13
+
14
+ ---
15
+
16
+ # AudioCraft: Audio Generation
17
+
18
+ Guide to using Meta's AudioCraft for text-to-music and text-to-audio generation with MusicGen, AudioGen, and EnCodec.
19
+
20
+ ## When to use AudioCraft
21
+
22
+ **Use AudioCraft when:**
23
+ - Need to generate music from text descriptions
24
+ - Creating sound effects and environmental audio
25
+ - Building music generation applications
26
+ - Need melody-conditioned music generation
27
+ - Want stereo audio output
28
+ - Require controllable music generation with style transfer
29
+
30
+ **Key features:**
31
+ - **MusicGen**: Text-to-music generation with melody conditioning
32
+ - **AudioGen**: Text-to-sound effects generation
33
+ - **EnCodec**: High-fidelity neural audio codec
34
+ - **Multiple model sizes**: Small (300M) to Large (3.3B)
35
+ - **Stereo support**: Full stereo audio generation
36
+ - **Style conditioning**: MusicGen-Style for reference-based generation
37
+
38
+ **Use alternatives instead:**
39
+ - **Stable Audio**: For longer commercial music generation
40
+ - **Bark**: For text-to-speech with music/sound effects
41
+ - **Riffusion**: For spectogram-based music generation
42
+ - **OpenAI Jukebox**: For raw audio generation with lyrics
43
+
44
+ ## Quick start
45
+
46
+ ### Installation
47
+
48
+ ```bash
49
+ # From PyPI
50
+ pip install audiocraft
51
+
52
+ # From GitHub (latest)
53
+ pip install git+https://github.com/facebookresearch/audiocraft.git
54
+
55
+ # Or use HuggingFace Transformers
56
+ pip install transformers torch torchaudio
57
+ ```
58
+
59
+ ### Basic text-to-music (AudioCraft)
60
+
61
+ ```python
62
+ import torchaudio
63
+ from audiocraft.models import MusicGen
64
+
65
+ # Load model
66
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
67
+
68
+ # Set generation parameters
69
+ model.set_generation_params(
70
+ duration=8, # seconds
71
+ top_k=250,
72
+ temperature=1.0
73
+ )
74
+
75
+ # Generate from text
76
+ descriptions = ["happy upbeat electronic dance music with synths"]
77
+ wav = model.generate(descriptions)
78
+
79
+ # Save audio
80
+ torchaudio.save("output.wav", wav[0].cpu(), sample_rate=32000)
81
+ ```
82
+
83
+ ### Using HuggingFace Transformers
84
+
85
+ ```python
86
+ from transformers import AutoProcessor, MusicgenForConditionalGeneration
87
+ import scipy
88
+
89
+ # Load model and processor
90
+ processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
91
+ model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
92
+ model.to("cuda")
93
+
94
+ # Generate music
95
+ inputs = processor(
96
+ text=["80s pop track with bassy drums and synth"],
97
+ padding=True,
98
+ return_tensors="pt"
99
+ ).to("cuda")
100
+
101
+ audio_values = model.generate(
102
+ **inputs,
103
+ do_sample=True,
104
+ guidance_scale=3,
105
+ max_new_tokens=256
106
+ )
107
+
108
+ # Save
109
+ sampling_rate = model.config.audio_encoder.sampling_rate
110
+ scipy.io.wavfile.write("output.wav", rate=sampling_rate, data=audio_values[0, 0].cpu().numpy())
111
+ ```
112
+
113
+ ### Text-to-sound with AudioGen
114
+
115
+ ```python
116
+ from audiocraft.models import AudioGen
117
+
118
+ # Load AudioGen
119
+ model = AudioGen.get_pretrained('facebook/audiogen-medium')
120
+
121
+ model.set_generation_params(duration=5)
122
+
123
+ # Generate sound effects
124
+ descriptions = ["dog barking in a park with birds chirping"]
125
+ wav = model.generate(descriptions)
126
+
127
+ torchaudio.save("sound.wav", wav[0].cpu(), sample_rate=16000)
128
+ ```
129
+
130
+ ## Core concepts
131
+
132
+ ### Architecture overview
133
+
134
+ ```
135
+ AudioCraft Architecture:
136
+ ┌──────────────────────────────────────────────────────────────┐
137
+ │ Text Encoder (T5) │
138
+ │ │ │
139
+ │ Text Embeddings │
140
+ └────────────────────────┬─────────────────────────────────────┘
141
+ │
142
+ ┌────────────────────────▼─────────────────────────────────────┐
143
+ │ Transformer Decoder (LM) │
144
+ │ Auto-regressively generates audio tokens │
145
+ │ Using efficient token interleaving patterns │
146
+ └────────────────────────┬─────────────────────────────────────┘
147
+ │
148
+ ┌────────────────────────▼─────────────────────────────────────┐
149
+ │ EnCodec Audio Decoder │
150
+ │ Converts tokens back to audio waveform │
151
+ └──────────────────────────────────────────────────────────────┘
152
+ ```
153
+
154
+ ### Model variants
155
+
156
+ | Model | Size | Description | Use Case |
157
+ |-------|------|-------------|----------|
158
+ | `musicgen-small` | 300M | Text-to-music | Quick generation |
159
+ | `musicgen-medium` | 1.5B | Text-to-music | Balanced |
160
+ | `musicgen-large` | 3.3B | Text-to-music | Best quality |
161
+ | `musicgen-melody` | 1.5B | Text + melody | Melody conditioning |
162
+ | `musicgen-melody-large` | 3.3B | Text + melody | Best melody |
163
+ | `musicgen-stereo-*` | Varies | Stereo output | Stereo generation |
164
+ | `musicgen-style` | 1.5B | Style transfer | Reference-based |
165
+ | `audiogen-medium` | 1.5B | Text-to-sound | Sound effects |
166
+
167
+ ### Generation parameters
168
+
169
+ | Parameter | Default | Description |
170
+ |-----------|---------|-------------|
171
+ | `duration` | 8.0 | Length in seconds (1-120) |
172
+ | `top_k` | 250 | Top-k sampling |
173
+ | `top_p` | 0.0 | Nucleus sampling (0 = disabled) |
174
+ | `temperature` | 1.0 | Sampling temperature |
175
+ | `cfg_coef` | 3.0 | Classifier-free guidance |
176
+
177
+ ## MusicGen usage
178
+
179
+ ### Text-to-music generation
180
+
181
+ ```python
182
+ from audiocraft.models import MusicGen
183
+ import torchaudio
184
+
185
+ model = MusicGen.get_pretrained('facebook/musicgen-medium')
186
+
187
+ # Configure generation
188
+ model.set_generation_params(
189
+ duration=30, # Up to 30 seconds
190
+ top_k=250, # Sampling diversity
191
+ top_p=0.0, # 0 = use top_k only
192
+ temperature=1.0, # Creativity (higher = more varied)
193
+ cfg_coef=3.0 # Text adherence (higher = stricter)
194
+ )
195
+
196
+ # Generate multiple samples
197
+ descriptions = [
198
+ "epic orchestral soundtrack with strings and brass",
199
+ "chill lo-fi hip hop beat with jazzy piano",
200
+ "energetic rock song with electric guitar"
201
+ ]
202
+
203
+ # Generate (returns [batch, channels, samples])
204
+ wav = model.generate(descriptions)
205
+
206
+ # Save each
207
+ for i, audio in enumerate(wav):
208
+ torchaudio.save(f"music_{i}.wav", audio.cpu(), sample_rate=32000)
209
+ ```
210
+
211
+ ### Melody-conditioned generation
212
+
213
+ ```python
214
+ from audiocraft.models import MusicGen
215
+ import torchaudio
216
+
217
+ # Load melody model
218
+ model = MusicGen.get_pretrained('facebook/musicgen-melody')
219
+ model.set_generation_params(duration=30)
220
+
221
+ # Load melody audio
222
+ melody, sr = torchaudio.load("melody.wav")
223
+
224
+ # Generate with melody conditioning
225
+ descriptions = ["acoustic guitar folk song"]
226
+ wav = model.generate_with_chroma(descriptions, melody, sr)
227
+
228
+ torchaudio.save("melody_conditioned.wav", wav[0].cpu(), sample_rate=32000)
229
+ ```
230
+
231
+ ### Stereo generation
232
+
233
+ ```python
234
+ from audiocraft.models import MusicGen
235
+
236
+ # Load stereo model
237
+ model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
238
+ model.set_generation_params(duration=15)
239
+
240
+ descriptions = ["ambient electronic music with wide stereo panning"]
241
+ wav = model.generate(descriptions)
242
+
243
+ # wav shape: [batch, 2, samples] for stereo
244
+ print(f"Stereo shape: {wav.shape}") # [1, 2, 480000]
245
+ torchaudio.save("stereo.wav", wav[0].cpu(), sample_rate=32000)
246
+ ```
247
+
248
+ ### Audio continuation
249
+
250
+ ```python
251
+ from transformers import AutoProcessor, MusicgenForConditionalGeneration
252
+
253
+ processor = AutoProcessor.from_pretrained("facebook/musicgen-medium")
254
+ model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-medium")
255
+
256
+ # Load audio to continue
257
+ import torchaudio
258
+ audio, sr = torchaudio.load("intro.wav")
259
+
260
+ # Process with text and audio
261
+ inputs = processor(
262
+ audio=audio.squeeze().numpy(),
263
+ sampling_rate=sr,
264
+ text=["continue with a epic chorus"],
265
+ padding=True,
266
+ return_tensors="pt"
267
+ )
268
+
269
+ # Generate continuation
270
+ audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=512)
271
+ ```
272
+
273
+ ## MusicGen-Style usage
274
+
275
+ ### Style-conditioned generation
276
+
277
+ ```python
278
+ from audiocraft.models import MusicGen
279
+
280
+ # Load style model
281
+ model = MusicGen.get_pretrained('facebook/musicgen-style')
282
+
283
+ # Configure generation with style
284
+ model.set_generation_params(
285
+ duration=30,
286
+ cfg_coef=3.0,
287
+ cfg_coef_beta=5.0 # Style influence
288
+ )
289
+
290
+ # Configure style conditioner
291
+ model.set_style_conditioner_params(
292
+ eval_q=3, # RVQ quantizers (1-6)
293
+ excerpt_length=3.0 # Style excerpt length
294
+ )
295
+
296
+ # Load style reference
297
+ style_audio, sr = torchaudio.load("reference_style.wav")
298
+
299
+ # Generate with text + style
300
+ descriptions = ["upbeat dance track"]
301
+ wav = model.generate_with_style(descriptions, style_audio, sr)
302
+ ```
303
+
304
+ ### Style-only generation (no text)
305
+
306
+ ```python
307
+ # Generate matching style without text prompt
308
+ model.set_generation_params(
309
+ duration=30,
310
+ cfg_coef=3.0,
311
+ cfg_coef_beta=None # Disable double CFG for style-only
312
+ )
313
+
314
+ wav = model.generate_with_style([None], style_audio, sr)
315
+ ```
316
+
317
+ ## AudioGen usage
318
+
319
+ ### Sound effect generation
320
+
321
+ ```python
322
+ from audiocraft.models import AudioGen
323
+ import torchaudio
324
+
325
+ model = AudioGen.get_pretrained('facebook/audiogen-medium')
326
+ model.set_generation_params(duration=10)
327
+
328
+ # Generate various sounds
329
+ descriptions = [
330
+ "thunderstorm with heavy rain and lightning",
331
+ "busy city traffic with car horns",
332
+ "ocean waves crashing on rocks",
333
+ "crackling campfire in forest"
334
+ ]
335
+
336
+ wav = model.generate(descriptions)
337
+
338
+ for i, audio in enumerate(wav):
339
+ torchaudio.save(f"sound_{i}.wav", audio.cpu(), sample_rate=16000)
340
+ ```
341
+
342
+ ## EnCodec usage
343
+
344
+ ### Audio compression
345
+
346
+ ```python
347
+ from audiocraft.models import CompressionModel
348
+ import torch
349
+ import torchaudio
350
+
351
+ # Load EnCodec
352
+ model = CompressionModel.get_pretrained('facebook/encodec_32khz')
353
+
354
+ # Load audio
355
+ wav, sr = torchaudio.load("audio.wav")
356
+
357
+ # Ensure correct sample rate
358
+ if sr != 32000:
359
+ resampler = torchaudio.transforms.Resample(sr, 32000)
360
+ wav = resampler(wav)
361
+
362
+ # Encode to tokens
363
+ with torch.no_grad():
364
+ encoded = model.encode(wav.unsqueeze(0))
365
+ codes = encoded[0] # Audio codes
366
+
367
+ # Decode back to audio
368
+ with torch.no_grad():
369
+ decoded = model.decode(codes)
370
+
371
+ torchaudio.save("reconstructed.wav", decoded[0].cpu(), sample_rate=32000)
372
+ ```
373
+
374
+ ## Common workflows
375
+
376
+ ### Workflow 1: Music generation pipeline
377
+
378
+ ```python
379
+ import torch
380
+ import torchaudio
381
+ from audiocraft.models import MusicGen
382
+
383
+ class MusicGenerator:
384
+ def __init__(self, model_name="facebook/musicgen-medium"):
385
+ self.model = MusicGen.get_pretrained(model_name)
386
+ self.sample_rate = 32000
387
+
388
+ def generate(self, prompt, duration=30, temperature=1.0, cfg=3.0):
389
+ self.model.set_generation_params(
390
+ duration=duration,
391
+ top_k=250,
392
+ temperature=temperature,
393
+ cfg_coef=cfg
394
+ )
395
+
396
+ with torch.no_grad():
397
+ wav = self.model.generate([prompt])
398
+
399
+ return wav[0].cpu()
400
+
401
+ def generate_batch(self, prompts, duration=30):
402
+ self.model.set_generation_params(duration=duration)
403
+
404
+ with torch.no_grad():
405
+ wav = self.model.generate(prompts)
406
+
407
+ return wav.cpu()
408
+
409
+ def save(self, audio, path):
410
+ torchaudio.save(path, audio, sample_rate=self.sample_rate)
411
+
412
+ # Usage
413
+ generator = MusicGenerator()
414
+ audio = generator.generate(
415
+ "epic cinematic orchestral music",
416
+ duration=30,
417
+ temperature=1.0
418
+ )
419
+ generator.save(audio, "epic_music.wav")
420
+ ```
421
+
422
+ ### Workflow 2: Sound design batch processing
423
+
424
+ ```python
425
+ import json
426
+ from pathlib import Path
427
+ from audiocraft.models import AudioGen
428
+ import torchaudio
429
+
430
+ def batch_generate_sounds(sound_specs, output_dir):
431
+ """
432
+ Generate multiple sounds from specifications.
433
+
434
+ Args:
435
+ sound_specs: list of {"name": str, "description": str, "duration": float}
436
+ output_dir: output directory path
437
+ """
438
+ model = AudioGen.get_pretrained('facebook/audiogen-medium')
439
+ output_dir = Path(output_dir)
440
+ output_dir.mkdir(exist_ok=True)
441
+
442
+ results = []
443
+
444
+ for spec in sound_specs:
445
+ model.set_generation_params(duration=spec.get("duration", 5))
446
+
447
+ wav = model.generate([spec["description"]])
448
+
449
+ output_path = output_dir / f"{spec['name']}.wav"
450
+ torchaudio.save(str(output_path), wav[0].cpu(), sample_rate=16000)
451
+
452
+ results.append({
453
+ "name": spec["name"],
454
+ "path": str(output_path),
455
+ "description": spec["description"]
456
+ })
457
+
458
+ return results
459
+
460
+ # Usage
461
+ sounds = [
462
+ {"name": "explosion", "description": "massive explosion with debris", "duration": 3},
463
+ {"name": "footsteps", "description": "footsteps on wooden floor", "duration": 5},
464
+ {"name": "door", "description": "wooden door creaking and closing", "duration": 2}
465
+ ]
466
+
467
+ results = batch_generate_sounds(sounds, "sound_effects/")
468
+ ```
469
+
470
+ ### Workflow 3: Gradio demo
471
+
472
+ ```python
473
+ import gradio as gr
474
+ import torch
475
+ import torchaudio
476
+ from audiocraft.models import MusicGen
477
+
478
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
479
+
480
+ def generate_music(prompt, duration, temperature, cfg_coef):
481
+ model.set_generation_params(
482
+ duration=duration,
483
+ temperature=temperature,
484
+ cfg_coef=cfg_coef
485
+ )
486
+
487
+ with torch.no_grad():
488
+ wav = model.generate([prompt])
489
+
490
+ # Save to temp file
491
+ path = "temp_output.wav"
492
+ torchaudio.save(path, wav[0].cpu(), sample_rate=32000)
493
+ return path
494
+
495
+ demo = gr.Interface(
496
+ fn=generate_music,
497
+ inputs=[
498
+ gr.Textbox(label="Music Description", placeholder="upbeat electronic dance music"),
499
+ gr.Slider(1, 30, value=8, label="Duration (seconds)"),
500
+ gr.Slider(0.5, 2.0, value=1.0, label="Temperature"),
501
+ gr.Slider(1.0, 10.0, value=3.0, label="CFG Coefficient")
502
+ ],
503
+ outputs=gr.Audio(label="Generated Music"),
504
+ title="MusicGen Demo"
505
+ )
506
+
507
+ demo.launch()
508
+ ```
509
+
510
+ ## Performance optimization
511
+
512
+ ### Memory optimization
513
+
514
+ ```python
515
+ # Use smaller model
516
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
517
+
518
+ # Clear cache between generations
519
+ torch.cuda.empty_cache()
520
+
521
+ # Generate shorter durations
522
+ model.set_generation_params(duration=10) # Instead of 30
523
+
524
+ # Use half precision
525
+ model = model.half()
526
+ ```
527
+
528
+ ### Batch processing efficiency
529
+
530
+ ```python
531
+ # Process multiple prompts at once (more efficient)
532
+ descriptions = ["prompt1", "prompt2", "prompt3", "prompt4"]
533
+ wav = model.generate(descriptions) # Single batch
534
+
535
+ # Instead of
536
+ for desc in descriptions:
537
+ wav = model.generate([desc]) # Multiple batches (slower)
538
+ ```
539
+
540
+ ### GPU memory requirements
541
+
542
+ | Model | FP32 VRAM | FP16 VRAM |
543
+ |-------|-----------|-----------|
544
+ | musicgen-small | ~4GB | ~2GB |
545
+ | musicgen-medium | ~8GB | ~4GB |
546
+ | musicgen-large | ~16GB | ~8GB |
547
+
548
+ ## Common issues
549
+
550
+ | Issue | Solution |
551
+ |-------|----------|
552
+ | CUDA OOM | Use smaller model, reduce duration |
553
+ | Poor quality | Increase cfg_coef, better prompts |
554
+ | Generation too short | Check max duration setting |
555
+ | Audio artifacts | Try different temperature |
556
+ | Stereo not working | Use stereo model variant |
557
+
558
+ ## References
559
+
560
+ - **[Advanced Usage](references/advanced-usage.md)** - Training, fine-tuning, deployment
561
+ - **[Troubleshooting](references/troubleshooting.md)** - Common issues and solutions
562
+
563
+ ## Resources
564
+
565
+ - **GitHub**: https://github.com/facebookresearch/audiocraft
566
+ - **Paper (MusicGen)**: https://arxiv.org/abs/2306.05284
567
+ - **Paper (AudioGen)**: https://arxiv.org/abs/2209.15352
568
+ - **HuggingFace**: https://huggingface.co/facebook/musicgen-small
569
+ - **Demo**: https://huggingface.co/spaces/facebook/MusicGen
optional-skills/creative/audiocraft-audio-generation/references/advanced-usage.md ADDED
@@ -0,0 +1,666 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # AudioCraft Advanced Usage Guide
2
+
3
+ ## Fine-tuning MusicGen
4
+
5
+ ### Custom dataset preparation
6
+
7
+ ```python
8
+ import os
9
+ import json
10
+ from pathlib import Path
11
+ import torchaudio
12
+
13
+ def prepare_dataset(audio_dir, output_dir, metadata_file):
14
+ """
15
+ Prepare dataset for MusicGen fine-tuning.
16
+
17
+ Directory structure:
18
+ output_dir/
19
+ ├── audio/
20
+ │ ├── 0001.wav
21
+ │ ├── 0002.wav
22
+ │ └── ...
23
+ └── metadata.json
24
+ """
25
+ output_dir = Path(output_dir)
26
+ audio_output = output_dir / "audio"
27
+ audio_output.mkdir(parents=True, exist_ok=True)
28
+
29
+ # Load metadata (format: {"path": "...", "description": "..."})
30
+ with open(metadata_file) as f:
31
+ metadata = json.load(f)
32
+
33
+ processed = []
34
+
35
+ for idx, item in enumerate(metadata):
36
+ audio_path = Path(audio_dir) / item["path"]
37
+
38
+ # Load and resample to 32kHz
39
+ wav, sr = torchaudio.load(str(audio_path))
40
+ if sr != 32000:
41
+ resampler = torchaudio.transforms.Resample(sr, 32000)
42
+ wav = resampler(wav)
43
+
44
+ # Convert to mono if stereo
45
+ if wav.shape[0] > 1:
46
+ wav = wav.mean(dim=0, keepdim=True)
47
+
48
+ # Save processed audio
49
+ output_path = audio_output / f"{idx:04d}.wav"
50
+ torchaudio.save(str(output_path), wav, sample_rate=32000)
51
+
52
+ processed.append({
53
+ "path": str(output_path.relative_to(output_dir)),
54
+ "description": item["description"],
55
+ "duration": wav.shape[1] / 32000
56
+ })
57
+
58
+ # Save processed metadata
59
+ with open(output_dir / "metadata.json", "w") as f:
60
+ json.dump(processed, f, indent=2)
61
+
62
+ print(f"Processed {len(processed)} samples")
63
+ return processed
64
+ ```
65
+
66
+ ### Fine-tuning with dora
67
+
68
+ ```bash
69
+ # AudioCraft uses dora for experiment management
70
+ # Install dora
71
+ pip install dora-search
72
+
73
+ # Clone AudioCraft
74
+ git clone https://github.com/facebookresearch/audiocraft.git
75
+ cd audiocraft
76
+
77
+ # Create config for fine-tuning
78
+ cat > config/solver/musicgen/finetune.yaml << 'EOF'
79
+ defaults:
80
+ - musicgen/musicgen_base
81
+ - /model: lm/musicgen_lm
82
+ - /conditioner: cond_base
83
+
84
+ solver: musicgen
85
+ autocast: true
86
+ autocast_dtype: float16
87
+
88
+ optim:
89
+ epochs: 100
90
+ batch_size: 4
91
+ lr: 1e-4
92
+ ema: 0.999
93
+ optimizer: adamw
94
+
95
+ dataset:
96
+ batch_size: 4
97
+ num_workers: 4
98
+ train:
99
+ - dset: your_dataset
100
+ root: /path/to/dataset
101
+ valid:
102
+ - dset: your_dataset
103
+ root: /path/to/dataset
104
+
105
+ checkpoint:
106
+ save_every: 10
107
+ keep_every_states: null
108
+ EOF
109
+
110
+ # Run fine-tuning
111
+ dora run solver=musicgen/finetune
112
+ ```
113
+
114
+ ### LoRA fine-tuning
115
+
116
+ ```python
117
+ from peft import LoraConfig, get_peft_model
118
+ from audiocraft.models import MusicGen
119
+ import torch
120
+
121
+ # Load base model
122
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
123
+
124
+ # Get the language model component
125
+ lm = model.lm
126
+
127
+ # Configure LoRA
128
+ lora_config = LoraConfig(
129
+ r=8,
130
+ lora_alpha=16,
131
+ target_modules=["q_proj", "v_proj", "k_proj", "out_proj"],
132
+ lora_dropout=0.05,
133
+ bias="none"
134
+ )
135
+
136
+ # Apply LoRA
137
+ lm = get_peft_model(lm, lora_config)
138
+ lm.print_trainable_parameters()
139
+ ```
140
+
141
+ ## Multi-GPU Training
142
+
143
+ ### DataParallel
144
+
145
+ ```python
146
+ import torch
147
+ import torch.nn as nn
148
+ from audiocraft.models import MusicGen
149
+
150
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
151
+
152
+ # Wrap LM with DataParallel
153
+ if torch.cuda.device_count() > 1:
154
+ model.lm = nn.DataParallel(model.lm)
155
+
156
+ model.to("cuda")
157
+ ```
158
+
159
+ ### DistributedDataParallel
160
+
161
+ ```python
162
+ import torch.distributed as dist
163
+ from torch.nn.parallel import DistributedDataParallel as DDP
164
+
165
+ def setup(rank, world_size):
166
+ dist.init_process_group("nccl", rank=rank, world_size=world_size)
167
+ torch.cuda.set_device(rank)
168
+
169
+ def train(rank, world_size):
170
+ setup(rank, world_size)
171
+
172
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
173
+ model.lm = model.lm.to(rank)
174
+ model.lm = DDP(model.lm, device_ids=[rank])
175
+
176
+ # Training loop
177
+ # ...
178
+
179
+ dist.destroy_process_group()
180
+ ```
181
+
182
+ ## Custom Conditioning
183
+
184
+ ### Adding new conditioners
185
+
186
+ ```python
187
+ from audiocraft.modules.conditioners import BaseConditioner
188
+ import torch
189
+
190
+ class CustomConditioner(BaseConditioner):
191
+ """Custom conditioner for additional control signals."""
192
+
193
+ def __init__(self, dim, output_dim):
194
+ super().__init__(dim, output_dim)
195
+ self.embed = torch.nn.Linear(dim, output_dim)
196
+
197
+ def forward(self, x):
198
+ return self.embed(x)
199
+
200
+ def tokenize(self, x):
201
+ # Tokenize input for conditioning
202
+ return x
203
+
204
+ # Use with MusicGen
205
+ from audiocraft.models.builders import get_lm_model
206
+
207
+ # Modify model config to include custom conditioner
208
+ # This requires editing the model configuration
209
+ ```
210
+
211
+ ### Melody conditioning internals
212
+
213
+ ```python
214
+ from audiocraft.models import MusicGen
215
+ from audiocraft.modules.codebooks_patterns import DelayedPatternProvider
216
+ import torch
217
+
218
+ model = MusicGen.get_pretrained('facebook/musicgen-melody')
219
+
220
+ # Access chroma extractor
221
+ chroma_extractor = model.lm.condition_provider.conditioners.get('chroma')
222
+
223
+ # Manual chroma extraction
224
+ def extract_chroma(audio, sr):
225
+ """Extract chroma features from audio."""
226
+ import librosa
227
+
228
+ # Compute chroma
229
+ chroma = librosa.feature.chroma_cqt(y=audio.numpy(), sr=sr)
230
+
231
+ return torch.from_numpy(chroma).float()
232
+
233
+ # Use extracted chroma for conditioning
234
+ chroma = extract_chroma(melody_audio, sample_rate)
235
+ ```
236
+
237
+ ## EnCodec Deep Dive
238
+
239
+ ### Custom compression settings
240
+
241
+ ```python
242
+ from audiocraft.models import CompressionModel
243
+ import torch
244
+
245
+ # Load EnCodec
246
+ encodec = CompressionModel.get_pretrained('facebook/encodec_32khz')
247
+
248
+ # Access codec parameters
249
+ print(f"Sample rate: {encodec.sample_rate}")
250
+ print(f"Channels: {encodec.channels}")
251
+ print(f"Cardinality: {encodec.cardinality}") # Codebook size
252
+ print(f"Num codebooks: {encodec.num_codebooks}")
253
+ print(f"Frame rate: {encodec.frame_rate}")
254
+
255
+ # Encode with specific bandwidth
256
+ # Lower bandwidth = more compression, lower quality
257
+ encodec.set_target_bandwidth(6.0) # 6 kbps
258
+
259
+ audio = torch.randn(1, 1, 32000) # 1 second
260
+ encoded = encodec.encode(audio)
261
+ decoded = encodec.decode(encoded[0])
262
+ ```
263
+
264
+ ### Streaming encoding
265
+
266
+ ```python
267
+ import torch
268
+ from audiocraft.models import CompressionModel
269
+
270
+ encodec = CompressionModel.get_pretrained('facebook/encodec_32khz')
271
+
272
+ def encode_streaming(audio_stream, chunk_size=32000):
273
+ """Encode audio in streaming fashion."""
274
+ all_codes = []
275
+
276
+ for chunk in audio_stream:
277
+ # Ensure chunk is right shape
278
+ if chunk.dim() == 1:
279
+ chunk = chunk.unsqueeze(0).unsqueeze(0)
280
+
281
+ with torch.no_grad():
282
+ codes = encodec.encode(chunk)[0]
283
+ all_codes.append(codes)
284
+
285
+ return torch.cat(all_codes, dim=-1)
286
+
287
+ def decode_streaming(codes_stream, output_stream):
288
+ """Decode codes in streaming fashion."""
289
+ for codes in codes_stream:
290
+ with torch.no_grad():
291
+ audio = encodec.decode(codes)
292
+ output_stream.write(audio.cpu().numpy())
293
+ ```
294
+
295
+ ## MultiBand Diffusion
296
+
297
+ ### Using MBD for enhanced quality
298
+
299
+ ```python
300
+ from audiocraft.models import MusicGen, MultiBandDiffusion
301
+
302
+ # Load MusicGen
303
+ model = MusicGen.get_pretrained('facebook/musicgen-medium')
304
+
305
+ # Load MultiBand Diffusion
306
+ mbd = MultiBandDiffusion.get_mbd_musicgen()
307
+
308
+ model.set_generation_params(duration=10)
309
+
310
+ # Generate with standard decoder
311
+ descriptions = ["epic orchestral music"]
312
+ wav_standard = model.generate(descriptions)
313
+
314
+ # Generate tokens and use MBD decoder
315
+ with torch.no_grad():
316
+ # Get tokens
317
+ gen_tokens = model.generate_tokens(descriptions)
318
+
319
+ # Decode with MBD
320
+ wav_mbd = mbd.tokens_to_wav(gen_tokens)
321
+
322
+ # Compare quality
323
+ print(f"Standard shape: {wav_standard.shape}")
324
+ print(f"MBD shape: {wav_mbd.shape}")
325
+ ```
326
+
327
+ ## API Server Deployment
328
+
329
+ ### FastAPI server
330
+
331
+ ```python
332
+ from fastapi import FastAPI, HTTPException
333
+ from pydantic import BaseModel
334
+ import torch
335
+ import torchaudio
336
+ from audiocraft.models import MusicGen
337
+ import io
338
+ import base64
339
+
340
+ app = FastAPI()
341
+
342
+ # Load model at startup
343
+ model = None
344
+
345
+ @app.on_event("startup")
346
+ async def load_model():
347
+ global model
348
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
349
+ model.set_generation_params(duration=10)
350
+
351
+ class GenerateRequest(BaseModel):
352
+ prompt: str
353
+ duration: float = 10.0
354
+ temperature: float = 1.0
355
+ cfg_coef: float = 3.0
356
+
357
+ class GenerateResponse(BaseModel):
358
+ audio_base64: str
359
+ sample_rate: int
360
+ duration: float
361
+
362
+ @app.post("/generate", response_model=GenerateResponse)
363
+ async def generate(request: GenerateRequest):
364
+ if model is None:
365
+ raise HTTPException(status_code=500, detail="Model not loaded")
366
+
367
+ try:
368
+ model.set_generation_params(
369
+ duration=min(request.duration, 30),
370
+ temperature=request.temperature,
371
+ cfg_coef=request.cfg_coef
372
+ )
373
+
374
+ with torch.no_grad():
375
+ wav = model.generate([request.prompt])
376
+
377
+ # Convert to bytes
378
+ buffer = io.BytesIO()
379
+ torchaudio.save(buffer, wav[0].cpu(), sample_rate=32000, format="wav")
380
+ buffer.seek(0)
381
+
382
+ audio_base64 = base64.b64encode(buffer.read()).decode()
383
+
384
+ return GenerateResponse(
385
+ audio_base64=audio_base64,
386
+ sample_rate=32000,
387
+ duration=wav.shape[-1] / 32000
388
+ )
389
+
390
+ except Exception as e:
391
+ raise HTTPException(status_code=500, detail=str(e))
392
+
393
+ @app.get("/health")
394
+ async def health():
395
+ return {"status": "ok", "model_loaded": model is not None}
396
+
397
+ # Run: uvicorn server:app --host 0.0.0.0 --port 8000
398
+ ```
399
+
400
+ ### Batch processing service
401
+
402
+ ```python
403
+ import asyncio
404
+ from concurrent.futures import ThreadPoolExecutor
405
+ import torch
406
+ from audiocraft.models import MusicGen
407
+
408
+ class MusicGenService:
409
+ def __init__(self, model_name='facebook/musicgen-small', max_workers=2):
410
+ self.model = MusicGen.get_pretrained(model_name)
411
+ self.executor = ThreadPoolExecutor(max_workers=max_workers)
412
+ self.lock = asyncio.Lock()
413
+
414
+ async def generate_async(self, prompt, duration=10):
415
+ """Async generation with thread pool."""
416
+ loop = asyncio.get_event_loop()
417
+
418
+ def _generate():
419
+ with torch.no_grad():
420
+ self.model.set_generation_params(duration=duration)
421
+ return self.model.generate([prompt])
422
+
423
+ # Run in thread pool
424
+ wav = await loop.run_in_executor(self.executor, _generate)
425
+ return wav[0].cpu()
426
+
427
+ async def generate_batch_async(self, prompts, duration=10):
428
+ """Process multiple prompts concurrently."""
429
+ tasks = [self.generate_async(p, duration) for p in prompts]
430
+ return await asyncio.gather(*tasks)
431
+
432
+ # Usage
433
+ service = MusicGenService()
434
+
435
+ async def main():
436
+ prompts = ["jazz piano", "rock guitar", "electronic beats"]
437
+ results = await service.generate_batch_async(prompts)
438
+ return results
439
+ ```
440
+
441
+ ## Integration Patterns
442
+
443
+ ### LangChain tool
444
+
445
+ ```python
446
+ from langchain.tools import BaseTool
447
+ import torch
448
+ import torchaudio
449
+ from audiocraft.models import MusicGen
450
+ import tempfile
451
+
452
+ class MusicGeneratorTool(BaseTool):
453
+ name = "music_generator"
454
+ description = "Generate music from a text description. Input should be a detailed description of the music style, mood, and instruments."
455
+
456
+ def __init__(self):
457
+ super().__init__()
458
+ self.model = MusicGen.get_pretrained('facebook/musicgen-small')
459
+ self.model.set_generation_params(duration=15)
460
+
461
+ def _run(self, description: str) -> str:
462
+ with torch.no_grad():
463
+ wav = self.model.generate([description])
464
+
465
+ # Save to temp file
466
+ with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
467
+ torchaudio.save(f.name, wav[0].cpu(), sample_rate=32000)
468
+ return f"Generated music saved to: {f.name}"
469
+
470
+ async def _arun(self, description: str) -> str:
471
+ return self._run(description)
472
+ ```
473
+
474
+ ### Gradio with advanced controls
475
+
476
+ ```python
477
+ import gradio as gr
478
+ import torch
479
+ import torchaudio
480
+ from audiocraft.models import MusicGen
481
+
482
+ models = {}
483
+
484
+ def load_model(model_size):
485
+ if model_size not in models:
486
+ model_name = f"facebook/musicgen-{model_size}"
487
+ models[model_size] = MusicGen.get_pretrained(model_name)
488
+ return models[model_size]
489
+
490
+ def generate(prompt, duration, temperature, cfg_coef, top_k, model_size):
491
+ model = load_model(model_size)
492
+
493
+ model.set_generation_params(
494
+ duration=duration,
495
+ temperature=temperature,
496
+ cfg_coef=cfg_coef,
497
+ top_k=top_k
498
+ )
499
+
500
+ with torch.no_grad():
501
+ wav = model.generate([prompt])
502
+
503
+ # Save
504
+ path = "output.wav"
505
+ torchaudio.save(path, wav[0].cpu(), sample_rate=32000)
506
+ return path
507
+
508
+ demo = gr.Interface(
509
+ fn=generate,
510
+ inputs=[
511
+ gr.Textbox(label="Prompt", lines=3),
512
+ gr.Slider(1, 30, value=10, label="Duration (s)"),
513
+ gr.Slider(0.1, 2.0, value=1.0, label="Temperature"),
514
+ gr.Slider(0.5, 10.0, value=3.0, label="CFG Coefficient"),
515
+ gr.Slider(50, 500, value=250, step=50, label="Top-K"),
516
+ gr.Dropdown(["small", "medium", "large"], value="small", label="Model Size")
517
+ ],
518
+ outputs=gr.Audio(label="Generated Music"),
519
+ title="MusicGen Advanced",
520
+ allow_flagging="never"
521
+ )
522
+
523
+ demo.launch(share=True)
524
+ ```
525
+
526
+ ## Audio Processing Pipeline
527
+
528
+ ### Post-processing chain
529
+
530
+ ```python
531
+ import torch
532
+ import torchaudio
533
+ import torchaudio.transforms as T
534
+ import numpy as np
535
+
536
+ class AudioPostProcessor:
537
+ def __init__(self, sample_rate=32000):
538
+ self.sample_rate = sample_rate
539
+
540
+ def normalize(self, audio, target_db=-14.0):
541
+ """Normalize audio to target loudness."""
542
+ rms = torch.sqrt(torch.mean(audio ** 2))
543
+ target_rms = 10 ** (target_db / 20)
544
+ gain = target_rms / (rms + 1e-8)
545
+ return audio * gain
546
+
547
+ def fade_in_out(self, audio, fade_duration=0.1):
548
+ """Apply fade in/out."""
549
+ fade_samples = int(fade_duration * self.sample_rate)
550
+
551
+ # Create fade curves
552
+ fade_in = torch.linspace(0, 1, fade_samples)
553
+ fade_out = torch.linspace(1, 0, fade_samples)
554
+
555
+ # Apply fades
556
+ audio[..., :fade_samples] *= fade_in
557
+ audio[..., -fade_samples:] *= fade_out
558
+
559
+ return audio
560
+
561
+ def apply_reverb(self, audio, decay=0.5):
562
+ """Apply simple reverb effect."""
563
+ impulse = torch.zeros(int(self.sample_rate * 0.5))
564
+ impulse[0] = 1.0
565
+ impulse[int(self.sample_rate * 0.1)] = decay * 0.5
566
+ impulse[int(self.sample_rate * 0.2)] = decay * 0.25
567
+
568
+ # Convolve
569
+ audio = torch.nn.functional.conv1d(
570
+ audio.unsqueeze(0),
571
+ impulse.unsqueeze(0).unsqueeze(0),
572
+ padding=len(impulse) // 2
573
+ ).squeeze(0)
574
+
575
+ return audio
576
+
577
+ def process(self, audio):
578
+ """Full processing pipeline."""
579
+ audio = self.normalize(audio)
580
+ audio = self.fade_in_out(audio)
581
+ return audio
582
+
583
+ # Usage with MusicGen
584
+ from audiocraft.models import MusicGen
585
+
586
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
587
+ model.set_generation_params(duration=10)
588
+
589
+ wav = model.generate(["chill ambient music"])
590
+ processor = AudioPostProcessor()
591
+ wav_processed = processor.process(wav[0].cpu())
592
+
593
+ torchaudio.save("processed.wav", wav_processed, sample_rate=32000)
594
+ ```
595
+
596
+ ## Evaluation
597
+
598
+ ### Audio quality metrics
599
+
600
+ ```python
601
+ import torch
602
+ from audiocraft.metrics import CLAPTextConsistencyMetric
603
+ from audiocraft.data.audio import audio_read
604
+
605
+ def evaluate_generation(audio_path, text_prompt):
606
+ """Evaluate generated audio quality."""
607
+ # Load audio
608
+ wav, sr = audio_read(audio_path)
609
+
610
+ # CLAP consistency (text-audio alignment)
611
+ clap_metric = CLAPTextConsistencyMetric()
612
+ clap_score = clap_metric.compute(wav, [text_prompt])
613
+
614
+ return {
615
+ "clap_score": clap_score,
616
+ "duration": wav.shape[-1] / sr
617
+ }
618
+
619
+ # Batch evaluation
620
+ def evaluate_batch(generations):
621
+ """Evaluate multiple generations."""
622
+ results = []
623
+ for gen in generations:
624
+ result = evaluate_generation(gen["path"], gen["prompt"])
625
+ result["prompt"] = gen["prompt"]
626
+ results.append(result)
627
+
628
+ # Aggregate
629
+ avg_clap = sum(r["clap_score"] for r in results) / len(results)
630
+ return {
631
+ "individual": results,
632
+ "average_clap": avg_clap
633
+ }
634
+ ```
635
+
636
+ ## Model Comparison
637
+
638
+ ### MusicGen variants benchmark
639
+
640
+ | Model | CLAP Score | Generation Time (10s) | VRAM |
641
+ |-------|------------|----------------------|------|
642
+ | musicgen-small | 0.35 | ~5s | 2GB |
643
+ | musicgen-medium | 0.42 | ~15s | 4GB |
644
+ | musicgen-large | 0.48 | ~30s | 8GB |
645
+ | musicgen-melody | 0.45 | ~15s | 4GB |
646
+ | musicgen-stereo-medium | 0.41 | ~18s | 5GB |
647
+
648
+ ### Prompt engineering tips
649
+
650
+ ```python
651
+ # Good prompts - specific and descriptive
652
+ good_prompts = [
653
+ "upbeat electronic dance music with synthesizer leads and punchy drums at 128 bpm",
654
+ "melancholic piano ballad with strings, slow tempo, emotional and cinematic",
655
+ "funky disco groove with slap bass, brass section, and rhythmic guitar"
656
+ ]
657
+
658
+ # Bad prompts - too vague
659
+ bad_prompts = [
660
+ "nice music",
661
+ "song",
662
+ "good beat"
663
+ ]
664
+
665
+ # Structure: [mood] [genre] with [instruments] at [tempo/style]
666
+ ```
optional-skills/creative/audiocraft-audio-generation/references/troubleshooting.md ADDED
@@ -0,0 +1,504 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # AudioCraft Troubleshooting Guide
2
+
3
+ ## Installation Issues
4
+
5
+ ### Import errors
6
+
7
+ **Error**: `ModuleNotFoundError: No module named 'audiocraft'`
8
+
9
+ **Solutions**:
10
+ ```bash
11
+ # Install from PyPI
12
+ pip install audiocraft
13
+
14
+ # Or from GitHub
15
+ pip install git+https://github.com/facebookresearch/audiocraft.git
16
+
17
+ # Verify installation
18
+ python -c "from audiocraft.models import MusicGen; print('OK')"
19
+ ```
20
+
21
+ ### FFmpeg not found
22
+
23
+ **Error**: `RuntimeError: ffmpeg not found`
24
+
25
+ **Solutions**:
26
+ ```bash
27
+ # Ubuntu/Debian
28
+ sudo apt-get install ffmpeg
29
+
30
+ # macOS
31
+ brew install ffmpeg
32
+
33
+ # Windows (using conda)
34
+ conda install -c conda-forge ffmpeg
35
+
36
+ # Verify
37
+ ffmpeg -version
38
+ ```
39
+
40
+ ### PyTorch CUDA mismatch
41
+
42
+ **Error**: `RuntimeError: CUDA error: no kernel image is available`
43
+
44
+ **Solutions**:
45
+ ```bash
46
+ # Check CUDA version
47
+ nvcc --version
48
+ python -c "import torch; print(torch.version.cuda)"
49
+
50
+ # Install matching PyTorch
51
+ pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121
52
+
53
+ # For CUDA 11.8
54
+ pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118
55
+ ```
56
+
57
+ ### xformers issues
58
+
59
+ **Error**: `ImportError: xformers` related errors
60
+
61
+ **Solutions**:
62
+ ```bash
63
+ # Install xformers for memory efficiency
64
+ pip install xformers
65
+
66
+ # Or disable xformers
67
+ export AUDIOCRAFT_USE_XFORMERS=0
68
+
69
+ # In Python
70
+ import os
71
+ os.environ["AUDIOCRAFT_USE_XFORMERS"] = "0"
72
+ from audiocraft.models import MusicGen
73
+ ```
74
+
75
+ ## Model Loading Issues
76
+
77
+ ### Out of memory during load
78
+
79
+ **Error**: `torch.cuda.OutOfMemoryError` during model loading
80
+
81
+ **Solutions**:
82
+ ```python
83
+ # Use smaller model
84
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
85
+
86
+ # Force CPU loading first
87
+ import torch
88
+ device = "cpu"
89
+ model = MusicGen.get_pretrained('facebook/musicgen-small', device=device)
90
+ model = model.to("cuda")
91
+
92
+ # Use HuggingFace with device_map
93
+ from transformers import MusicgenForConditionalGeneration
94
+ model = MusicgenForConditionalGeneration.from_pretrained(
95
+ "facebook/musicgen-small",
96
+ device_map="auto"
97
+ )
98
+ ```
99
+
100
+ ### Download failures
101
+
102
+ **Error**: Connection errors or incomplete downloads
103
+
104
+ **Solutions**:
105
+ ```python
106
+ # Set cache directory
107
+ import os
108
+ os.environ["AUDIOCRAFT_CACHE_DIR"] = "/path/to/cache"
109
+
110
+ # Or for HuggingFace
111
+ os.environ["HF_HOME"] = "/path/to/hf_cache"
112
+
113
+ # Resume download
114
+ from huggingface_hub import snapshot_download
115
+ snapshot_download("facebook/musicgen-small", resume_download=True)
116
+
117
+ # Use local files
118
+ model = MusicGen.get_pretrained('/local/path/to/model')
119
+ ```
120
+
121
+ ### Wrong model type
122
+
123
+ **Error**: Loading wrong model for task
124
+
125
+ **Solutions**:
126
+ ```python
127
+ # For text-to-music: use MusicGen
128
+ from audiocraft.models import MusicGen
129
+ model = MusicGen.get_pretrained('facebook/musicgen-medium')
130
+
131
+ # For text-to-sound: use AudioGen
132
+ from audiocraft.models import AudioGen
133
+ model = AudioGen.get_pretrained('facebook/audiogen-medium')
134
+
135
+ # For melody conditioning: use melody variant
136
+ model = MusicGen.get_pretrained('facebook/musicgen-melody')
137
+
138
+ # For stereo: use stereo variant
139
+ model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
140
+ ```
141
+
142
+ ## Generation Issues
143
+
144
+ ### Empty or silent output
145
+
146
+ **Problem**: Generated audio is silent or very quiet
147
+
148
+ **Solutions**:
149
+ ```python
150
+ import torch
151
+
152
+ # Check output
153
+ wav = model.generate(["upbeat music"])
154
+ print(f"Shape: {wav.shape}")
155
+ print(f"Max amplitude: {wav.abs().max().item()}")
156
+ print(f"Mean amplitude: {wav.abs().mean().item()}")
157
+
158
+ # If too quiet, normalize
159
+ def normalize_audio(audio, target_db=-14.0):
160
+ rms = torch.sqrt(torch.mean(audio ** 2))
161
+ target_rms = 10 ** (target_db / 20)
162
+ gain = target_rms / (rms + 1e-8)
163
+ return audio * gain
164
+
165
+ wav_normalized = normalize_audio(wav)
166
+ ```
167
+
168
+ ### Poor quality output
169
+
170
+ **Problem**: Generated music sounds bad or noisy
171
+
172
+ **Solutions**:
173
+ ```python
174
+ # Use larger model
175
+ model = MusicGen.get_pretrained('facebook/musicgen-large')
176
+
177
+ # Adjust generation parameters
178
+ model.set_generation_params(
179
+ duration=15,
180
+ top_k=250, # Increase for more diversity
181
+ temperature=0.8, # Lower for more focused output
182
+ cfg_coef=4.0 # Increase for better text adherence
183
+ )
184
+
185
+ # Use better prompts
186
+ # Bad: "music"
187
+ # Good: "upbeat electronic dance music with synthesizers and punchy drums"
188
+
189
+ # Try MultiBand Diffusion
190
+ from audiocraft.models import MultiBandDiffusion
191
+ mbd = MultiBandDiffusion.get_mbd_musicgen()
192
+ tokens = model.generate_tokens(["prompt"])
193
+ wav = mbd.tokens_to_wav(tokens)
194
+ ```
195
+
196
+ ### Generation too short
197
+
198
+ **Problem**: Audio shorter than expected
199
+
200
+ **Solutions**:
201
+ ```python
202
+ # Check duration setting
203
+ model.set_generation_params(duration=30) # Set before generate
204
+
205
+ # Verify in generation
206
+ print(f"Duration setting: {model.generation_params}")
207
+
208
+ # Check output shape
209
+ wav = model.generate(["prompt"])
210
+ actual_duration = wav.shape[-1] / 32000
211
+ print(f"Actual duration: {actual_duration}s")
212
+
213
+ # Note: max duration is typically 30s
214
+ ```
215
+
216
+ ### Melody conditioning fails
217
+
218
+ **Error**: Issues with melody-conditioned generation
219
+
220
+ **Solutions**:
221
+ ```python
222
+ import torchaudio
223
+ from audiocraft.models import MusicGen
224
+
225
+ # Load melody model (not base model)
226
+ model = MusicGen.get_pretrained('facebook/musicgen-melody')
227
+
228
+ # Load and prepare melody
229
+ melody, sr = torchaudio.load("melody.wav")
230
+
231
+ # Resample to model sample rate if needed
232
+ if sr != 32000:
233
+ resampler = torchaudio.transforms.Resample(sr, 32000)
234
+ melody = resampler(melody)
235
+
236
+ # Ensure correct shape [batch, channels, samples]
237
+ if melody.dim() == 1:
238
+ melody = melody.unsqueeze(0).unsqueeze(0)
239
+ elif melody.dim() == 2:
240
+ melody = melody.unsqueeze(0)
241
+
242
+ # Convert stereo to mono
243
+ if melody.shape[1] > 1:
244
+ melody = melody.mean(dim=1, keepdim=True)
245
+
246
+ # Generate with melody
247
+ model.set_generation_params(duration=min(melody.shape[-1] / 32000, 30))
248
+ wav = model.generate_with_chroma(["piano cover"], melody, 32000)
249
+ ```
250
+
251
+ ## Memory Issues
252
+
253
+ ### CUDA out of memory
254
+
255
+ **Error**: `torch.cuda.OutOfMemoryError: CUDA out of memory`
256
+
257
+ **Solutions**:
258
+ ```python
259
+ import torch
260
+
261
+ # Clear cache before generation
262
+ torch.cuda.empty_cache()
263
+
264
+ # Use smaller model
265
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
266
+
267
+ # Reduce duration
268
+ model.set_generation_params(duration=10) # Instead of 30
269
+
270
+ # Generate one at a time
271
+ for prompt in prompts:
272
+ wav = model.generate([prompt])
273
+ save_audio(wav)
274
+ torch.cuda.empty_cache()
275
+
276
+ # Use CPU for very large generations
277
+ model = MusicGen.get_pretrained('facebook/musicgen-small', device="cpu")
278
+ ```
279
+
280
+ ### Memory leak during batch processing
281
+
282
+ **Problem**: Memory grows over time
283
+
284
+ **Solutions**:
285
+ ```python
286
+ import gc
287
+ import torch
288
+
289
+ def generate_with_cleanup(model, prompts):
290
+ results = []
291
+
292
+ for prompt in prompts:
293
+ with torch.no_grad():
294
+ wav = model.generate([prompt])
295
+ results.append(wav.cpu())
296
+
297
+ # Cleanup
298
+ del wav
299
+ gc.collect()
300
+ torch.cuda.empty_cache()
301
+
302
+ return results
303
+
304
+ # Use context manager
305
+ with torch.inference_mode():
306
+ wav = model.generate(["prompt"])
307
+ ```
308
+
309
+ ## Audio Format Issues
310
+
311
+ ### Wrong sample rate
312
+
313
+ **Problem**: Audio plays at wrong speed
314
+
315
+ **Solutions**:
316
+ ```python
317
+ import torchaudio
318
+
319
+ # MusicGen outputs at 32kHz
320
+ sample_rate = 32000
321
+
322
+ # AudioGen outputs at 16kHz
323
+ sample_rate = 16000
324
+
325
+ # Always use correct rate when saving
326
+ torchaudio.save("output.wav", wav[0].cpu(), sample_rate=sample_rate)
327
+
328
+ # Resample if needed
329
+ resampler = torchaudio.transforms.Resample(32000, 44100)
330
+ wav_resampled = resampler(wav)
331
+ ```
332
+
333
+ ### Stereo/mono mismatch
334
+
335
+ **Problem**: Wrong number of channels
336
+
337
+ **Solutions**:
338
+ ```python
339
+ # Check model type
340
+ print(f"Audio channels: {wav.shape}")
341
+ # Mono: [batch, 1, samples]
342
+ # Stereo: [batch, 2, samples]
343
+
344
+ # Convert mono to stereo
345
+ if wav.shape[1] == 1:
346
+ wav_stereo = wav.repeat(1, 2, 1)
347
+
348
+ # Convert stereo to mono
349
+ if wav.shape[1] == 2:
350
+ wav_mono = wav.mean(dim=1, keepdim=True)
351
+
352
+ # Use stereo model for stereo output
353
+ model = MusicGen.get_pretrained('facebook/musicgen-stereo-medium')
354
+ ```
355
+
356
+ ### Clipping and distortion
357
+
358
+ **Problem**: Audio has clipping or distortion
359
+
360
+ **Solutions**:
361
+ ```python
362
+ import torch
363
+
364
+ # Check for clipping
365
+ max_val = wav.abs().max().item()
366
+ print(f"Max amplitude: {max_val}")
367
+
368
+ # Normalize to prevent clipping
369
+ if max_val > 1.0:
370
+ wav = wav / max_val
371
+
372
+ # Apply soft clipping
373
+ def soft_clip(x, threshold=0.9):
374
+ return torch.tanh(x / threshold) * threshold
375
+
376
+ wav_clipped = soft_clip(wav)
377
+
378
+ # Lower temperature during generation
379
+ model.set_generation_params(temperature=0.7) # More controlled
380
+ ```
381
+
382
+ ## HuggingFace Transformers Issues
383
+
384
+ ### Processor errors
385
+
386
+ **Error**: Issues with MusicgenProcessor
387
+
388
+ **Solutions**:
389
+ ```python
390
+ from transformers import AutoProcessor, MusicgenForConditionalGeneration
391
+
392
+ # Load matching processor and model
393
+ processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
394
+ model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
395
+
396
+ # Ensure inputs are on same device
397
+ inputs = processor(
398
+ text=["prompt"],
399
+ padding=True,
400
+ return_tensors="pt"
401
+ ).to("cuda")
402
+
403
+ # Check processor configuration
404
+ print(processor.tokenizer)
405
+ print(processor.feature_extractor)
406
+ ```
407
+
408
+ ### Generation parameter errors
409
+
410
+ **Error**: Invalid generation parameters
411
+
412
+ **Solutions**:
413
+ ```python
414
+ # HuggingFace uses different parameter names
415
+ audio_values = model.generate(
416
+ **inputs,
417
+ do_sample=True, # Enable sampling
418
+ guidance_scale=3.0, # CFG (not cfg_coef)
419
+ max_new_tokens=256, # Token limit (not duration)
420
+ temperature=1.0
421
+ )
422
+
423
+ # Calculate tokens from duration
424
+ # ~50 tokens per second
425
+ duration_seconds = 10
426
+ max_tokens = duration_seconds * 50
427
+ audio_values = model.generate(**inputs, max_new_tokens=max_tokens)
428
+ ```
429
+
430
+ ## Performance Issues
431
+
432
+ ### Slow generation
433
+
434
+ **Problem**: Generation takes too long
435
+
436
+ **Solutions**:
437
+ ```python
438
+ # Use smaller model
439
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
440
+
441
+ # Reduce duration
442
+ model.set_generation_params(duration=10)
443
+
444
+ # Use GPU
445
+ model.to("cuda")
446
+
447
+ # Enable flash attention if available
448
+ # (requires compatible hardware)
449
+
450
+ # Batch multiple prompts
451
+ prompts = ["prompt1", "prompt2", "prompt3"]
452
+ wav = model.generate(prompts) # Single batch is faster than loop
453
+
454
+ # Use compile (PyTorch 2.0+)
455
+ model.lm = torch.compile(model.lm)
456
+ ```
457
+
458
+ ### CPU fallback
459
+
460
+ **Problem**: Generation running on CPU instead of GPU
461
+
462
+ **Solutions**:
463
+ ```python
464
+ import torch
465
+
466
+ # Check CUDA availability
467
+ print(f"CUDA available: {torch.cuda.is_available()}")
468
+ print(f"CUDA device: {torch.cuda.get_device_name(0)}")
469
+
470
+ # Explicitly move to GPU
471
+ model = MusicGen.get_pretrained('facebook/musicgen-small')
472
+ model.to("cuda")
473
+
474
+ # Verify model device
475
+ print(f"Model device: {next(model.lm.parameters()).device}")
476
+ ```
477
+
478
+ ## Common Error Messages
479
+
480
+ | Error | Cause | Solution |
481
+ |-------|-------|----------|
482
+ | `CUDA out of memory` | Model too large | Use smaller model, reduce duration |
483
+ | `ffmpeg not found` | FFmpeg not installed | Install FFmpeg |
484
+ | `No module named 'audiocraft'` | Not installed | `pip install audiocraft` |
485
+ | `RuntimeError: Expected 3D tensor` | Wrong input shape | Check tensor dimensions |
486
+ | `KeyError: 'melody'` | Wrong model for melody | Use musicgen-melody |
487
+ | `Sample rate mismatch` | Wrong audio format | Resample to model rate |
488
+
489
+ ## Getting Help
490
+
491
+ 1. **GitHub Issues**: https://github.com/facebookresearch/audiocraft/issues
492
+ 2. **HuggingFace Forums**: https://discuss.huggingface.co
493
+ 3. **Paper**: https://arxiv.org/abs/2306.05284
494
+
495
+ ### Reporting Issues
496
+
497
+ Include:
498
+ - Python version
499
+ - PyTorch version
500
+ - CUDA version
501
+ - AudioCraft version: `pip show audiocraft`
502
+ - Full error traceback
503
+ - Minimal reproducible code
504
+ - Hardware (GPU model, VRAM)
optional-skills/creative/baoyu-article-illustrator/PORT_NOTES.md ADDED
@@ -0,0 +1,48 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Port Notes — baoyu-article-illustrator
2
+
3
+ Ported from [JimLiu/baoyu-skills](https://github.com/JimLiu/baoyu-skills) v1.57.0.
4
+
5
+ ## Changes from upstream
6
+
7
+ `SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, `references/prompt-construction.md`, and `prompts/system.md` were adapted. The 23 style files and 4 palette files are verbatim copies. The `references/config/` directory was removed entirely.
8
+
9
+ ### Adaptations
10
+
11
+ | Change | Upstream | Hermes |
12
+ |--------|----------|--------|
13
+ | Metadata namespace | `openclaw` | `hermes` |
14
+ | Trigger | `/baoyu-article-illustrator` slash command + CLI flags | Natural language skill matching |
15
+ | User config | EXTEND.md (project/user/XDG paths) + first-time-setup | Removed — not part of Hermes infra |
16
+ | User prompts | `AskUserQuestion` (batched, multi-question) | `clarify` tool (one question at a time) |
17
+ | Image generation | `baoyu-imagine` (Bun/TypeScript, multi-provider, accepts `--ref`, writes to local path) | `image_generate` (returns URL only; agent downloads via `terminal`/`curl`) |
18
+ | Backend selection | User picks provider via CLI flags | Not agent-selectable — `image_generate` uses the user-configured FAL model. Removed hardcoded "nano banana pro" line from `prompts/system.md`. |
19
+ | Reference images | Passed to backend via `--ref`, copied via shell | `vision_analyze` extracts a textual description (binary never touched by `write_file`/`read_file`); description is embedded in prompts. Optional `terminal cp` for a local record. |
20
+ | Platform support | Linux/macOS/Windows/WSL/PowerShell | Linux/macOS only |
21
+ | File operations | Bash commands | Hermes file tools: `write_file`/`read_file` for text, `terminal` for binaries and URL downloads, `vision_analyze` for reading images |
22
+ | Watermark | Driven by EXTEND.md `watermark.enabled` | Optional — user asks for it per-article |
23
+ | Output directory | EXTEND.md `default_output_dir` (imgs-subdir / same-dir / illustrations-subdir / independent) | Defaults based on input type; user overrides in request |
24
+
25
+ ### What was preserved
26
+
27
+ - Type × Style × Palette three-dimension framework
28
+ - All style definitions (23 files, verbatim)
29
+ - All palette definitions (4 files, verbatim)
30
+ - Core reference files (workflow, prompt-construction, styles, style-presets) — adapted for Hermes tooling
31
+ - Core principles and workflow structure (analyze → confirm → outline → prompts → generate)
32
+ - Prompt-file-as-reproducibility-record discipline
33
+ - Author, version, homepage attribution
34
+
35
+ ## Syncing with upstream
36
+
37
+ To pull upstream updates:
38
+
39
+ ```bash
40
+ # Compare versions
41
+ curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/SKILL.md | head -5
42
+ # Look for version: line
43
+
44
+ # Diff style/palette files (safe to overwrite — unchanged from upstream)
45
+ diff <(curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/references/styles/blueprint.md) references/styles/blueprint.md
46
+ ```
47
+
48
+ `references/styles/*` and `references/palettes/*` can be overwritten directly. `SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, `references/prompt-construction.md`, and `prompts/system.md` must be manually merged since they contain Hermes-specific adaptations (tool wiring, backend neutrality, removed EXTEND.md references).
optional-skills/creative/baoyu-article-illustrator/SKILL.md ADDED
@@ -0,0 +1,207 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ name: baoyu-article-illustrator
3
+ description: "Article illustrations: type × style × palette consistency."
4
+ version: 1.57.0
5
+ author: 宝玉 (JimLiu)
6
+ license: MIT
7
+ platforms: [linux, macos, windows]
8
+ metadata:
9
+ hermes:
10
+ tags: [article-illustration, creative, image-generation]
11
+ category: creative
12
+ homepage: https://github.com/JimLiu/baoyu-skills#baoyu-article-illustrator
13
+ ---
14
+
15
+ # Article Illustrator
16
+
17
+ Adapted from [baoyu-article-illustrator](https://github.com/JimLiu/baoyu-skills) for Hermes Agent's tool ecosystem.
18
+
19
+ Analyze articles, identify illustration positions, generate images with **Type × Style × Palette** consistency.
20
+
21
+ ## When to Use
22
+
23
+ Trigger this skill when the user asks to illustrate an article, add images to an article, generate illustrations for content, or uses phrases like "为文章配图", "illustrate article", or "add images". The user provides an article (file path or pasted content) and optionally specifies type, style, palette, or density.
24
+
25
+ ## Three Dimensions
26
+
27
+ | Dimension | Controls | Examples |
28
+ |-----------|----------|----------|
29
+ | **Type** | Information structure | infographic, scene, flowchart, comparison, framework, timeline |
30
+ | **Style** | Rendering approach | notion, warm, minimal, blueprint, watercolor, elegant |
31
+ | **Palette** | Color scheme (optional) | macaron, warm, neon — overrides style's default colors |
32
+
33
+ Combine freely: `type=infographic, style=vector-illustration, palette=macaron`.
34
+
35
+ Or use presets: `edu-visual` → type + style + palette in one shot. See [style-presets.md](references/style-presets.md).
36
+
37
+ ## Types
38
+
39
+ | Type | Best For |
40
+ |------|----------|
41
+ | `infographic` | Data, metrics, technical |
42
+ | `scene` | Narratives, emotional |
43
+ | `flowchart` | Processes, workflows |
44
+ | `comparison` | Side-by-side, options |
45
+ | `framework` | Models, architecture |
46
+ | `timeline` | History, evolution |
47
+
48
+ ## Styles
49
+
50
+ See [references/styles.md](references/styles.md) for Core Styles, the full gallery, and Type × Style compatibility.
51
+
52
+ ## Output Structure
53
+
54
+ ```
55
+ {output-dir}/
56
+ ├── source-{slug}.{ext} # Only for pasted content
57
+ ├── outline.md
58
+ ├── prompts/
59
+ │ └── NN-{type}-{slug}.md
60
+ └── NN-{type}-{slug}.png
61
+ ```
62
+
63
+ **Default output directory**:
64
+
65
+ | Input | Output Directory | Markdown Insert Path |
66
+ |-------|------------------|----------------------|
67
+ | Article file path | `{article-dir}/imgs/` | `imgs/NN-{type}-{slug}.png` |
68
+ | Pasted content | `illustrations/{topic-slug}/` (cwd) | `illustrations/{topic-slug}/NN-{type}-{slug}.png` |
69
+
70
+ If the user asks for a different layout (e.g., images alongside the article, or a `illustrations/` subdirectory), honor that.
71
+
72
+ **Slug**: 2-4 words, kebab-case. **Conflict**: append `-YYYYMMDD-HHMMSS`.
73
+
74
+ ## Core Principles
75
+
76
+ - **Visualize concepts, not metaphors** — if the article uses a metaphor (e.g., "电锯切西瓜"), illustrate the underlying concept, not the literal image.
77
+ - **Labels use article data** — actual numbers, terms, and quotes from the article, not generic placeholders.
78
+ - **Prompt files are reproducibility records** — every illustration must have a saved prompt file under `prompts/` before any image is generated.
79
+ - **Strip secrets** — scan source content for API keys, tokens, or credentials before writing anything to disk.
80
+
81
+ ## Workflow
82
+
83
+ ```
84
+ - [ ] Step 1: Detect reference images (if provided)
85
+ - [ ] Step 2: Analyze content
86
+ - [ ] Step 3: Confirm settings (clarify tool, one question at a time)
87
+ - [ ] Step 4: Generate outline
88
+ - [ ] Step 5: Generate prompts
89
+ - [ ] Step 6: Generate images (image_generate)
90
+ - [ ] Step 7: Finalize
91
+ ```
92
+
93
+ ### Step 1: Detect Reference Images
94
+
95
+ If the user supplies reference images (paths pasted inline, attachments, or a URL):
96
+
97
+ 1. For each reference, call `vision_analyze` with the path/URL and a question asking for style, palette, composition, and subject. Record the returned description in `{output-dir}/references/NN-ref-{slug}.md` via `write_file`.
98
+ 2. **Do not** try to copy the binary via `write_file` / `read_file` — those are text-only. If you want a local copy for the record, use `terminal` (`cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"`). The skill itself never needs to read the binary; it works off the vision description.
99
+ 3. Since `image_generate` doesn't take image inputs, the vision description is what gets embedded in prompts during Step 5.
100
+
101
+ Full procedures: [references/workflow.md](references/workflow.md#step-1-detect-reference-images).
102
+
103
+ ### Step 2: Analyze
104
+
105
+ | Analysis | Output |
106
+ |----------|--------|
107
+ | Content type | Technical / Tutorial / Methodology / Narrative |
108
+ | Purpose | information / visualization / imagination |
109
+ | Core arguments | 2-5 main points |
110
+ | Positions | Where illustrations add value |
111
+
112
+ Read source (file path → `read_file`, or pasted text) and write the analysis to `{output-dir}/analysis.md` using `write_file`.
113
+
114
+ Full procedures: [references/workflow.md](references/workflow.md#step-2-analyze).
115
+
116
+ ### Step 3: Confirm Settings
117
+
118
+ Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question whose answer is already present in the user's request.
119
+
120
+ | Order | Question | Options |
121
+ |-------|----------|---------|
122
+ | Q1 | **Preset or Type** | [Recommended preset], [alt preset], or manual: infographic, scene, flowchart, comparison, framework, timeline, mixed |
123
+ | Q2 | **Density** | minimal (1-2), balanced (3-5), per-section (Recommended), rich (6+) |
124
+ | Q3 | **Style** *(skip if preset chosen in Q1)* | [Recommended], minimal-flat, sci-fi, hand-drawn, editorial, scene, poster |
125
+ | Q4 | **Palette** *(optional)* | Default (style colors), macaron, warm, neon |
126
+ | Q5 | **Language** *(only if article language is ambiguous)* | article language / user language |
127
+
128
+ Don't ask more than 2-3 `clarify` questions in a row. If the user already specified these in their request, skip entirely.
129
+
130
+ Full procedures: [references/workflow.md](references/workflow.md#step-3-confirm-settings).
131
+
132
+ ### Step 4: Generate Outline → `outline.md`
133
+
134
+ Save `{output-dir}/outline.md` using `write_file` with frontmatter (type, density, style, palette, image_count) and one entry per illustration:
135
+
136
+ ```yaml
137
+ ## Illustration 1
138
+ **Position**: [section/paragraph]
139
+ **Purpose**: [why]
140
+ **Visual Content**: [what to show]
141
+ **Filename**: 01-infographic-concept-name.png
142
+ ```
143
+
144
+ Full template: [references/workflow.md](references/workflow.md#step-4-generate-outline).
145
+
146
+ ### Step 5: Generate Prompts
147
+
148
+ **BLOCKING**: Every illustration must have a saved prompt file before any image is generated — the prompt file is the reproducibility record.
149
+
150
+ For each illustration:
151
+
152
+ 1. Create a prompt file per [references/prompt-construction.md](references/prompt-construction.md).
153
+ 2. Save to `{output-dir}/prompts/NN-{type}-{slug}.md` using `write_file` with YAML frontmatter.
154
+ 3. Prompts MUST use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT).
155
+ 4. LABELS MUST include article-specific data: actual numbers, terms, metrics, quotes.
156
+ 5. Process references (`direct`/`style`/`palette`) per prompt frontmatter — for `direct` usage, embed a textual description of the reference in the prompt (since `image_generate` doesn't take reference-image inputs).
157
+
158
+ ### Step 6: Generate Images
159
+
160
+ For each prompt file:
161
+
162
+ 1. Call `image_generate(prompt=..., aspect_ratio=...)`. `image_generate` returns a JSON result containing an image URL; it does NOT write to disk and does NOT accept an output path.
163
+ 2. Map the prompt's `ASPECT` to `image_generate`'s enum: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect.
164
+ 3. Download the returned URL to `{output-dir}/NN-{type}-{slug}.png` via `terminal` (e.g. `curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{url}"`).
165
+ 4. On generation failure, auto-retry once.
166
+
167
+ Note: the underlying image-generation backend is user-configured (default: FAL FLUX 2 Klein 9B) and is NOT agent-selectable via `image_generate`. Do not write model names into prompts expecting them to route.
168
+
169
+ ### Step 7: Finalize
170
+
171
+ Insert `![description]({relative-path}/NN-{type}-{slug}.png)` after the corresponding paragraph. Alt text: concise description in the article's language.
172
+
173
+ Report:
174
+
175
+ ```
176
+ Article Illustration Complete!
177
+ Article: [path] | Type: [type] | Density: [level] | Style: [style] | Palette: [palette or default]
178
+ Images: X/N generated
179
+ ```
180
+
181
+ ## Modification
182
+
183
+ | Action | Steps |
184
+ |--------|-------|
185
+ | Edit | Update prompt → Regenerate → Update reference |
186
+ | Add | Position → Prompt → Generate → Update outline → Insert |
187
+ | Delete | Delete files → Remove reference → Update outline |
188
+
189
+ ## References
190
+
191
+ | File | Content |
192
+ |------|---------|
193
+ | [references/workflow.md](references/workflow.md) | Detailed procedures |
194
+ | [references/usage.md](references/usage.md) | Invocation examples |
195
+ | [references/styles.md](references/styles.md) | Style gallery + Palette gallery |
196
+ | [references/style-presets.md](references/style-presets.md) | Preset shortcuts (type + style + palette) |
197
+ | [references/prompt-construction.md](references/prompt-construction.md) | Prompt templates |
198
+
199
+ ## Pitfalls
200
+
201
+ 1. **Data integrity is paramount** — never summarize, paraphrase, or alter source statistics. "73% increase" stays "73% increase".
202
+ 2. **Strip secrets** — scan source content for API keys, tokens, or credentials before including in any output file.
203
+ 3. **Don't illustrate metaphors literally** — visualize the underlying concept.
204
+ 4. **Prompt files are mandatory** — no image generation without a saved prompt file. The file is what lets you regenerate or switch backends later.
205
+ 5. **`image_generate` aspect ratios** — the tool supports `landscape`, `portrait`, and `square`. Custom ratios map to the nearest option.
206
+ 6. **`image_generate` returns a URL, not a local file** — always download via `terminal` (`curl`) before inserting local image paths into the article.
207
+ 7. **No backend selection from the agent** — `image_generate` uses whatever model the user configured (default: FAL FLUX 2 Klein 9B). Don't write `"use <model> to generate this"` into prompts expecting it to route.
optional-skills/creative/baoyu-article-illustrator/prompts/system.md ADDED
@@ -0,0 +1,32 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Create a cartoon-style infographic illustration following these guidelines:
2
+
3
+ ## Image Specifications
4
+
5
+ - **Type**: Infographic illustration
6
+ - **Orientation**: Landscape (horizontal)
7
+ - **Aspect Ratio**: 16:9
8
+ - **Style**: Hand-drawn illustration
9
+
10
+ ## Core Principles
11
+
12
+ - Hand-drawn quality throughout - NO realistic or photographic elements
13
+ - If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate
14
+ - Keep information concise, highlight keywords and core concepts
15
+ - Use ample whitespace for easy visual scanning
16
+ - Maintain clear visual hierarchy
17
+
18
+ ## Text Style (When Text Included)
19
+
20
+ - **ALL text MUST be hand-drawn style**
21
+ - Text should be readable and complement the visual
22
+ - Font style harmonizes with illustration style
23
+ - **DO NOT use realistic or computer-generated fonts**
24
+
25
+ ## Language
26
+
27
+ - Use the same language as the content provided below for any text elements
28
+ - Match punctuation style to the content language
29
+
30
+ ---
31
+
32
+ Generate the illustration based on the content provided below:
optional-skills/creative/baoyu-article-illustrator/references/palettes/macaron.md ADDED
@@ -0,0 +1,33 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # macaron
2
+
3
+ Soft macaron pastel color blocks on warm cream
4
+
5
+ ## Background
6
+
7
+ - Color: Warm Cream (#F5F0E8)
8
+ - Texture: Subtle warm paper grain
9
+
10
+ ## Colors
11
+
12
+ | Role | Color | Hex | Usage |
13
+ |------|-------|-----|-------|
14
+ | Background | Warm Cream | #F5F0E8 | Primary background |
15
+ | Primary Text | Deep Charcoal | #2D2D2D | Headlines, main text, outlines |
16
+ | Macaron Blue | Sky Blue | #A8D8EA | Info block fill, cool-toned zones |
17
+ | Macaron Mint | Mint Green | #B5E5CF | Info block fill, growth/positive zones |
18
+ | Macaron Lavender | Lavender | #D5C6E0 | Info block fill, abstract/concept zones |
19
+ | Macaron Peach | Peach | #FFD5C2 | Info block fill, warm-toned zones |
20
+ | Accent | Coral Red | #E8655A | Key data, warnings, emphasis |
21
+ | Muted Text | Warm Gray | #6B6B6B | Secondary annotations, small labels |
22
+
23
+ ## Accent
24
+
25
+ Coral Red (#E8655A) for key data, warnings, and emphasis highlights. Use sparingly — one or two elements per illustration.
26
+
27
+ ## Semantic Constraint
28
+
29
+ Soft pastel macaron color palette. Use block colors as rounded card backgrounds for distinct information sections. Accent coral red sparingly for emphasis on key terms only. Do NOT render color names, hex codes, or role labels as visible text in the image.
30
+
31
+ ## Best For
32
+
33
+ Educational content, knowledge sharing, concept explainers, tutorials, tech summaries, onboarding materials
optional-skills/creative/baoyu-article-illustrator/references/palettes/mono-ink.md ADDED
@@ -0,0 +1,42 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # mono-ink
2
+
3
+ Black ink on pure white with sparse semantic accent colors
4
+
5
+ ## Background
6
+
7
+ - Color: Pure White (#FFFFFF)
8
+ - Texture: Clean, no grain, no tint
9
+
10
+ ## Colors
11
+
12
+ | Role | Color | Hex | Usage |
13
+ |------|-------|-----|-------|
14
+ | Background | Pure White | #FFFFFF | Canvas |
15
+ | Primary | Near Black | #1A1A1A | All lines, text, figures, arrows |
16
+ | Accent (risk/emphasis) | Coral Red | #E8655A | Risk, problem, gap, key emphasis |
17
+ | Accent (positive) | Muted Teal | #5FA8A8 | Positive, solution, "after" state |
18
+ | Accent (neutral tag) | Dusty Lavender | #9B8AB5 | Neutral tags, category labels |
19
+ | Soft Fill | Pale Gray | #F0F0F0 | Subtle zone backgrounds (optional) |
20
+
21
+ ## Accent
22
+
23
+ Use black ink for all structural elements — lines, text, figures. Accent colors appear only for semantic highlighting: coral red for risks/gaps/problems, muted teal for positive/solution/after-states, dusty lavender for neutral category tags. Total colored pixels must remain under 10% of canvas. Pale gray may back a subtle zone but must never dominate.
24
+
25
+ ## Semantic Constraint
26
+
27
+ Black ink on white canvas. Accent colors for semantic highlighting only — total colored pixels under 10% of canvas. Do NOT render color names, hex codes, or role labels as visible text in the image.
28
+
29
+ ## Compatible With
30
+
31
+ - `ink-notes` (primary, default pairing)
32
+ - `minimal` (strict monochrome variation, drops the style's built-in accent)
33
+ - `sketch` (pencil + ink hybrid look)
34
+
35
+ ## Not Recommended With
36
+
37
+ - `sketch-notes` — its "no pure white backgrounds" rule conflicts
38
+ - `warm`, `elegant`, `watercolor`, `fantasy-animation` — color-heavy by design, mono-ink strips their identity
39
+
40
+ ## Best For
41
+
42
+ Professional visual notes, Before/After essays, tech manifestos, framework analogies, whiteboard-presentation explainers
optional-skills/creative/baoyu-article-illustrator/references/palettes/neon.md ADDED
@@ -0,0 +1,33 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # neon
2
+
3
+ Vibrant neon colors on dark backgrounds
4
+
5
+ ## Background
6
+
7
+ - Color: Deep Purple (#2D1B4E)
8
+ - Texture: Subtle grid pattern or solid dark
9
+
10
+ ## Colors
11
+
12
+ | Role | Color | Hex | Usage |
13
+ |------|-------|-----|-------|
14
+ | Background | Deep Purple | #2D1B4E | Primary background |
15
+ | Alt Background | Dark Teal | #0F4C5C | Alternative sections |
16
+ | Primary | Hot Pink | #FF1493 | Main accent |
17
+ | Secondary | Electric Cyan | #00FFFF | Supporting elements |
18
+ | Tertiary | Neon Yellow | #FFFF00 | Highlights |
19
+ | Accent 1 | Lime Green | #32CD32 | Energy, success |
20
+ | Accent 2 | Orange | #FF6B35 | Warmth |
21
+ | Text | White | #FFFFFF | Text elements |
22
+
23
+ ## Accent
24
+
25
+ Hot Pink (#FF1493) for primary emphasis. High contrast neon-on-dark creates immediate visual impact.
26
+
27
+ ## Semantic Constraint
28
+
29
+ Vibrant neon-on-dark palette. High contrast, immediate visual impact. Do NOT render color names, hex codes, or role labels as visible text in the image.
30
+
31
+ ## Best For
32
+
33
+ Gaming, retro tech, 80s/90s nostalgic content, bold editorial, trend and pop culture
optional-skills/creative/baoyu-article-illustrator/references/palettes/warm.md ADDED
@@ -0,0 +1,32 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # warm
2
+
3
+ Warm earth tones on soft peach, no cool colors
4
+
5
+ ## Background
6
+
7
+ - Color: Soft Peach (#FFECD2)
8
+ - Texture: Warm paper texture
9
+
10
+ ## Colors
11
+
12
+ | Role | Color | Hex | Usage |
13
+ |------|-------|-----|-------|
14
+ | Background | Soft Peach | #FFECD2 | Primary background |
15
+ | Outlines | Deep Charcoal | #2D2D2D | All element outlines |
16
+ | Primary | Warm Orange | #ED8936 | Main accent color |
17
+ | Secondary | Terracotta | #C05621 | Warm depth |
18
+ | Tertiary | Golden Yellow | #F6AD55 | Highlights, energy |
19
+ | Accent | Deep Brown | #744210 | Grounding, anchoring |
20
+ | Text | Warm Charcoal | #4A4A4A | Text elements |
21
+
22
+ ## Accent
23
+
24
+ Warm Orange (#ED8936) for primary emphasis. Warm-only palette — no cool colors (no green, blue, purple). Modern-retro feel.
25
+
26
+ ## Semantic Constraint
27
+
28
+ Warm earth tone palette. Warm-only — no cool colors (no green, blue, purple). Do NOT render color names, hex codes, or role labels as visible text in the image.
29
+
30
+ ## Best For
31
+
32
+ Product showcases, team introductions, feature grids, brand content, personal growth, lifestyle
optional-skills/creative/baoyu-article-illustrator/references/prompt-construction.md ADDED
@@ -0,0 +1,426 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Prompt Construction
2
+
3
+ ## Prompt File Format
4
+
5
+ Each prompt file uses YAML frontmatter + content:
6
+
7
+ ```yaml
8
+ ---
9
+ illustration_id: 01
10
+ type: infographic
11
+ style: blueprint
12
+ references: # ⚠️ ONLY if files EXIST in references/ directory
13
+ - ref_id: 01
14
+ filename: 01-ref-diagram.png
15
+ usage: direct # direct | style | palette
16
+ ---
17
+
18
+ [Type-specific template content below...]
19
+ ```
20
+
21
+ **⚠️ CRITICAL - When to include `references` field**:
22
+
23
+ | Situation | Action |
24
+ |-----------|--------|
25
+ | Reference file saved to `references/` | Include in frontmatter ✓ |
26
+ | Style extracted verbally (no file) | DO NOT include in frontmatter, append to prompt body instead |
27
+ | File path in frontmatter but file doesn't exist | ERROR - remove references field |
28
+
29
+ **Reference Usage Types** (only when file exists):
30
+
31
+ | Usage | Description | Generation Action |
32
+ |-------|-------------|-------------------|
33
+ | `direct` | Primary visual reference | Describe the reference (composition, subject, style, palette) in prompt text — `image_generate` does not accept reference-image inputs |
34
+ | `style` | Style characteristics only | Describe style in prompt text |
35
+ | `palette` | Color palette extraction | Include colors in prompt |
36
+
37
+ **If no reference file but style/palette extracted verbally**, append directly to prompt body:
38
+ ```
39
+ COLORS (from reference):
40
+ - Primary: #E8756D coral
41
+ - Secondary: #7ECFC0 mint
42
+ ...
43
+
44
+ STYLE (from reference):
45
+ - Clean lines, minimal shadows
46
+ - Gradient backgrounds
47
+ ...
48
+ ```
49
+
50
+ ---
51
+
52
+ ## Default Composition Requirements
53
+
54
+ **Apply to ALL prompts by default**:
55
+
56
+ | Requirement | Description |
57
+ |-------------|-------------|
58
+ | **Clean composition** | Simple layouts, no visual clutter |
59
+ | **White space** | Generous margins, breathing room around elements |
60
+ | **No complex backgrounds** | Solid colors or subtle gradients only, avoid busy textures |
61
+ | **Centered or content-appropriate** | Main visual elements centered or positioned by content needs |
62
+ | **Matching graphics** | Use graphic elements that align with content theme |
63
+ | **Highlight core info** | White space draws attention to key information |
64
+
65
+ **Add to ALL prompts**:
66
+ > Clean composition with generous white space. Simple or no background. Main elements centered or positioned by content needs.
67
+
68
+ ---
69
+
70
+ ## Color Specification Rules
71
+
72
+ Colors in prompts use hex codes for **rendering guidance only** — they tell the model which colors to use, NOT what text to display.
73
+
74
+ **⚠️ CRITICAL**: Image generation models sometimes render color names and hex values as visible text labels in the image (e.g., painting "Macaron Blue #A8D8EA" as a label). This must be prevented.
75
+
76
+ **Add to ALL prompts that contain a COLORS section**:
77
+ > Color values (#hex) and color names are rendering guidance only — do NOT display color names, hex codes, or palette labels as visible text in the image.
78
+
79
+ ---
80
+
81
+ ## Character Rendering
82
+
83
+ When depicting people:
84
+
85
+ | Guideline | Description |
86
+ |-----------|-------------|
87
+ | **Style** | Simplified cartoon silhouettes or symbolic expressions |
88
+ | **Avoid** | Realistic human portrayals, detailed faces |
89
+ | **Diversity** | Varied body types when showing multiple people |
90
+ | **Emotion** | Express through posture and simple gestures |
91
+
92
+ **Add to ALL prompts with human figures**:
93
+ > Human figures: simplified stylized silhouettes or symbolic representations, not photorealistic.
94
+
95
+ ---
96
+
97
+ ## Text in Illustrations
98
+
99
+ | Element | Guideline |
100
+ |---------|-----------|
101
+ | **Size** | Large, prominent, immediately readable |
102
+ | **Style** | Handwritten fonts preferred for warmth |
103
+ | **Content** | Concise keywords and core concepts only |
104
+ | **Language** | Match article language |
105
+
106
+ **Add to prompts with text**:
107
+ > Text should be large and prominent with handwritten-style fonts. Keep minimal, focus on keywords.
108
+
109
+ ---
110
+
111
+ ## Principles
112
+
113
+ Good prompts must include:
114
+
115
+ 1. **Layout Structure First**: Describe composition, zones, flow direction
116
+ 2. **Specific Data/Labels**: Use actual numbers, terms from article
117
+ 3. **Visual Relationships**: How elements connect
118
+ 4. **Semantic Colors**: Meaning-based color choices (red=warning, green=efficient)
119
+ 5. **Style Characteristics**: Line treatment, texture, mood
120
+ 6. **Aspect Ratio**: End with ratio and complexity level
121
+
122
+ ## Type-Specific Templates
123
+
124
+ ### Infographic
125
+
126
+ ```
127
+ [Title] - Data Visualization
128
+
129
+ Layout: [grid/radial/hierarchical]
130
+
131
+ ZONES:
132
+ - Zone 1: [data point with specific values]
133
+ - Zone 2: [comparison with metrics]
134
+ - Zone 3: [summary/conclusion]
135
+
136
+ LABELS: [specific numbers, percentages, terms from article]
137
+ COLORS: [semantic color mapping]
138
+ STYLE: [style characteristics]
139
+ ASPECT: 16:9
140
+ ```
141
+
142
+ **Infographic + vector-illustration**:
143
+ ```
144
+ Flat vector illustration infographic. Clean black outlines on all elements.
145
+ COLORS: Cream background (#F5F0E6), Coral Red (#E07A5F), Mint Green (#81B29A), Mustard Yellow (#F2CC8F)
146
+ ELEMENTS: Geometric simplified icons, no gradients, playful decorative elements (dots, stars)
147
+ ```
148
+
149
+ **Infographic + vector-illustration + warm palette**:
150
+ ```
151
+ Flat vector illustration infographic. Clean black outlines on all elements.
152
+ PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
153
+ COLORS: Soft Peach background (#FFECD2), Warm Orange (#ED8936),
154
+ Terracotta (#C05621), Golden Yellow (#F6AD55), Deep Brown (#744210)
155
+ ELEMENTS: Geometric simplified icons, no gradients, rounded corners,
156
+ modular card layout, consistent icon style
157
+ ```
158
+
159
+ ### Scene
160
+
161
+ ```
162
+ [Title] - Atmospheric Scene
163
+
164
+ FOCAL POINT: [main subject]
165
+ ATMOSPHERE: [lighting, mood, environment]
166
+ MOOD: [emotion to convey]
167
+ COLOR TEMPERATURE: [warm/cool/neutral]
168
+ STYLE: [style characteristics]
169
+ ASPECT: 16:9
170
+ ```
171
+
172
+ ### Flowchart
173
+
174
+ ```
175
+ [Title] - Process Flow
176
+
177
+ Layout: [left-right/top-down/circular]
178
+
179
+ STEPS:
180
+ 1. [Step name] - [brief description]
181
+ 2. [Step name] - [brief description]
182
+ ...
183
+
184
+ CONNECTIONS: [arrow types, decision points]
185
+ STYLE: [style characteristics]
186
+ ASPECT: 16:9
187
+ ```
188
+
189
+ **Flowchart + vector-illustration**:
190
+ ```
191
+ Flat vector flowchart with bold arrows and geometric step containers.
192
+ COLORS: Cream background (#F5F0E6), steps in Coral/Mint/Mustard, black outlines
193
+ ELEMENTS: Rounded rectangles, thick arrows, simple icons per step
194
+ ```
195
+
196
+ **Flowchart + sketch-notes + macaron palette**:
197
+ ```
198
+ Hand-drawn educational flowchart on warm cream paper. Slight wobble on all lines.
199
+ PALETTE: macaron — soft pastel color blocks
200
+ COLORS: Warm Cream background (#F5F0E8), zone fills in Macaron Blue (#A8D8EA),
201
+ Lavender (#D5C6E0), Mint (#B5E5CF), Coral Red (#E8655A) for emphasis
202
+ ELEMENTS: Rounded cards with dashed/solid borders, wavy hand-drawn arrows with labels,
203
+ simple stick-figure characters, doodle decorations (stars, underlines)
204
+ STYLE: Color fills don't completely fill outlines, hand-drawn lettering, generous white space
205
+ ```
206
+
207
+ **Flowchart + ink-notes + mono-ink palette**:
208
+ ```
209
+ Professional hand-drawn visual-note flowchart on pure white. Black ink line work
210
+ with slight wobble, à la Mike Rohde sketchnoting.
211
+ PALETTE: mono-ink — black ink dominant, sparse semantic accents
212
+ COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all lines,
213
+ text, and figures; Coral Red (#E8655A) only for risk/emphasis,
214
+ Muted Teal (#5FA8A8) only for positive/solution states
215
+ ELEMENTS: Left-to-right stage boxes with rounded-rect frames, wavy hand-drawn
216
+ arrows between stages, simple stick-figure characters with role
217
+ labels above (e.g., "ML Engineer", "Team Lead"), dashed-border box
218
+ for future/empty stage, small doodle icons per stage
219
+ STYLE: Hand-lettered titles (bold, oversized), handwritten stage labels and
220
+ annotations, generous white space, bottom tagline summarizing takeaway
221
+ ```
222
+
223
+ ### Comparison
224
+
225
+ ```
226
+ [Title] - Comparison View
227
+
228
+ LEFT SIDE - [Option A]:
229
+ - [Point 1]
230
+ - [Point 2]
231
+
232
+ RIGHT SIDE - [Option B]:
233
+ - [Point 1]
234
+ - [Point 2]
235
+
236
+ DIVIDER: [visual separator]
237
+ STYLE: [style characteristics]
238
+ ASPECT: 16:9
239
+ ```
240
+
241
+ **Comparison + vector-illustration**:
242
+ ```
243
+ Flat vector comparison with split layout. Clear visual separation.
244
+ COLORS: Left side Coral (#E07A5F), Right side Mint (#81B29A), cream background
245
+ ELEMENTS: Bold icons, black outlines, centered divider line
246
+ ```
247
+
248
+ **Comparison + vector-illustration + warm palette**:
249
+ ```
250
+ Flat vector comparison with split layout. Clear visual separation.
251
+ PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
252
+ COLORS: Left side Warm Orange (#ED8936), Right side Terracotta (#C05621),
253
+ Soft Peach background (#FFECD2), Deep Brown (#744210) accents
254
+ ELEMENTS: Bold icons, black outlines, centered divider line
255
+ ```
256
+
257
+ **Comparison + ink-notes + mono-ink palette** (Before/After, Traditional vs New):
258
+ ```
259
+ Professional hand-drawn sketchnote comparison on pure white. Black ink line work
260
+ with slight wobble, à la Mike Rohde sketchnoting.
261
+ PALETTE: mono-ink — black ink dominant, sparse semantic accents
262
+ COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all outlines,
263
+ text, figures, arrows; Coral Red (#E8655A) reserved for risks/gaps
264
+ (left/Before side); Muted Teal (#5FA8A8) reserved for positives
265
+ (right/After side). Color accents under 10% of canvas.
266
+ LAYOUT: Left | Right split with vertical hand-drawn divider. Hand-lettered
267
+ "Before" label (top-left) and "After" label (top-right).
268
+ LEFT SIDE: Stick figure(s) with role label above, speech bubble showing the
269
+ pain point, bulleted pain-point list in handwritten text.
270
+ RIGHT SIDE: Stick figure(s) showing the new state, bulleted improvement list,
271
+ small positive-action icons.
272
+ BRIDGE: Curved hand-drawn "mindset shift" arrow bridging left → right with
273
+ small inline label describing the shift.
274
+ BOTTOM: Single-line hand-lettered tagline summarizing the takeaway.
275
+ STYLE: Hand-lettered headings (bold, oversized), handwritten body annotations,
276
+ generous white space, no computer fonts, no gradients, no shadows.
277
+ ```
278
+
279
+ ### Framework
280
+
281
+ ```
282
+ [Title] - Conceptual Framework
283
+
284
+ STRUCTURE: [hierarchical/network/matrix]
285
+
286
+ NODES:
287
+ - [Concept 1] - [role]
288
+ - [Concept 2] - [role]
289
+
290
+ RELATIONSHIPS: [how nodes connect]
291
+ STYLE: [style characteristics]
292
+ ASPECT: 16:9
293
+ ```
294
+
295
+ **Framework + vector-illustration**:
296
+ ```
297
+ Flat vector framework diagram with geometric nodes and bold connectors.
298
+ COLORS: Cream background (#F5F0E6), nodes in Coral/Mint/Mustard/Blue, black outlines
299
+ ELEMENTS: Rounded rectangles or circles for nodes, thick connecting lines
300
+ ```
301
+
302
+ **Framework + vector-illustration + warm palette**:
303
+ ```
304
+ Flat vector framework diagram with geometric nodes and bold connectors.
305
+ PALETTE OVERRIDE (warm): Warm-only color palette, no cool colors.
306
+ COLORS: Soft Peach background (#FFECD2), nodes in Warm Orange (#ED8936),
307
+ Terracotta (#C05621), Golden Yellow (#F6AD55), black outlines
308
+ ELEMENTS: Rounded rectangles or circles for nodes, thick connecting lines
309
+ ```
310
+
311
+ **Framework + ink-notes + mono-ink palette** (command center, OS analogy):
312
+ ```
313
+ Professional hand-drawn sketchnote framework on pure white. Black ink line work
314
+ with slight wobble, à la Mike Rohde sketchnoting.
315
+ PALETTE: mono-ink — black ink dominant, sparse semantic accents
316
+ COLORS: Pure White background (#FFFFFF), Near Black (#1A1A1A) for all lines,
317
+ text, figures; Dusty Lavender (#9B8AB5) for neutral category tags only;
318
+ Coral Red (#E8655A) for emphasis sparingly. Color accents under 10%.
319
+ STRUCTURE: Central rounded-rectangle frame as "the system" with hand-lettered
320
+ title inside. Inner layer of labeled sub-components (node labels
321
+ above each). Outer layer of feeder arrows from stick-figure
322
+ operators/users with role labels.
323
+ ELEMENTS: Stick figures at the edges with role tags ("Team Lead", "Operator"),
324
+ wavy hand-drawn connector arrows with small inline labels, small
325
+ doodle icons per component, dashed-border placeholder(s) for
326
+ future/empty capabilities.
327
+ BOTTOM: Single-line hand-lettered tagline.
328
+ STYLE: Hand-lettered headings, handwritten annotations, generous white space,
329
+ no computer fonts, no gradients.
330
+ ```
331
+
332
+ ### Timeline
333
+
334
+ ```
335
+ [Title] - Chronological View
336
+
337
+ DIRECTION: [horizontal/vertical]
338
+
339
+ EVENTS:
340
+ - [Date/Period 1]: [milestone]
341
+ - [Date/Period 2]: [milestone]
342
+
343
+ MARKERS: [visual indicators]
344
+ STYLE: [style characteristics]
345
+ ASPECT: 16:9
346
+ ```
347
+
348
+ ### Screen-Print Style Override
349
+
350
+ When `style: screen-print`, replace standard style instructions with:
351
+
352
+ ```
353
+ Screen print / silkscreen poster art. Flat color blocks, NO gradients.
354
+ COLORS: 2-5 colors maximum. [Choose from style palette or duotone pair]
355
+ TEXTURE: Halftone dot patterns, slight color layer misregistration, paper grain
356
+ COMPOSITION: Bold silhouettes, geometric framing, negative space as storytelling element
357
+ FIGURES: Silhouettes only, no detailed faces, stencil-cut edges
358
+ TYPOGRAPHY: Bold condensed sans-serif integrated into composition (not overlaid)
359
+ ```
360
+
361
+ **Scene + screen-print**:
362
+ ```
363
+ Conceptual poster scene. Single symbolic focal point, NOT literal illustration.
364
+ COLORS: Duotone pair (e.g., Burnt Orange #E8751A + Deep Teal #0A6E6E) on Off-Black #121212
365
+ COMPOSITION: Centered silhouette or geometric frame, 60%+ negative space
366
+ TEXTURE: Halftone dots, paper grain, slight print misregistration
367
+ ```
368
+
369
+ **Comparison + screen-print**:
370
+ ```
371
+ Split poster composition. Each side dominated by one color from duotone pair.
372
+ LEFT: [Color A] side with silhouette/icon for [Option A]
373
+ RIGHT: [Color B] side with silhouette/icon for [Option B]
374
+ DIVIDER: Geometric shape or negative space boundary
375
+ TEXTURE: Halftone transitions between sides
376
+ ```
377
+
378
+ ---
379
+
380
+ ## Palette Override
381
+
382
+ When a palette is specified (via `--palette` or preset), it overrides the style's default colors:
383
+
384
+ 1. Read style file → get rendering rules (Visual Elements, Style Rules, line treatment)
385
+ 2. Read palette file (`palettes/<palette>.md`) → get Colors + Background
386
+ 3. Palette Colors **replace** style's default Color Palette in prompt
387
+ 4. Palette Background **replaces** style's Background color (keep style's texture description)
388
+ 5. Build prompt: style rendering instructions + palette colors
389
+
390
+ **Prompt frontmatter** includes palette when specified:
391
+ ```yaml
392
+ ---
393
+ illustration_id: 01
394
+ type: infographic
395
+ style: vector-illustration
396
+ palette: macaron
397
+ ---
398
+ ```
399
+
400
+ **Example**: `vector-illustration` + `macaron` palette:
401
+ ```
402
+ Flat vector illustration infographic. Clean black outlines on all elements.
403
+ PALETTE: macaron — soft pastel color blocks
404
+ COLORS: Warm Cream background (#F5F0E8), Macaron Blue (#A8D8EA), Mint (#B5E5CF),
405
+ Lavender (#D5C6E0), Peach (#FFD5C2), Coral Red (#E8655A) for emphasis
406
+ ELEMENTS: Geometric simplified icons, no gradients, playful decorative elements
407
+ ```
408
+
409
+ When no palette is specified, use the style's built-in Color Palette as before.
410
+
411
+ ---
412
+
413
+ ## What to Avoid
414
+
415
+ - Vague descriptions ("a nice image")
416
+ - Literal metaphor illustrations
417
+ - Missing concrete labels/annotations
418
+ - Generic decorative elements
419
+
420
+ ## Watermark Integration (optional)
421
+
422
+ If the user asks for a watermark, append:
423
+
424
+ ```
425
+ Include a subtle watermark "[content]" positioned at [position].
426
+ ```
optional-skills/creative/baoyu-article-illustrator/references/style-presets.md ADDED
@@ -0,0 +1,80 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Style Presets
2
+
3
+ A preset expands to a type + style + optional palette combination. Users can override any dimension in their request.
4
+
5
+ ## By Category
6
+
7
+ ### Technical & Engineering
8
+
9
+ | Preset | Type | Style | Palette | Best For |
10
+ |----------|------|-------|---------|----------|
11
+ | `tech-explainer` | `infographic` | `blueprint` | — | API docs, system metrics, technical deep-dives |
12
+ | `system-design` | `framework` | `blueprint` | — | Architecture diagrams, system design |
13
+ | `architecture` | `framework` | `vector-illustration` | — | Component relationships, module structure |
14
+ | `science-paper` | `infographic` | `scientific` | — | Research findings, lab results, academic |
15
+
16
+ ### Knowledge & Education
17
+
18
+ | Preset | Type | Style | Palette | Best For |
19
+ |----------|------|-------|---------|----------|
20
+ | `knowledge-base` | `infographic` | `vector-illustration` | — | Concept explainers, tutorials, how-to |
21
+ | `saas-guide` | `infographic` | `notion` | — | Product guides, SaaS docs, tool walkthroughs |
22
+ | `tutorial` | `flowchart` | `vector-illustration` | — | Step-by-step tutorials, setup guides |
23
+ | `process-flow` | `flowchart` | `notion` | — | Workflow documentation, onboarding flows |
24
+ | `warm-knowledge` | `infographic` | `vector-illustration` | `warm` | Product showcases, team intros, feature cards, brand content |
25
+ | `edu-visual` | `infographic` | `vector-illustration` | `macaron` | Knowledge summaries, concept explainers, educational articles |
26
+ | `hand-drawn-edu` | `flowchart` | `sketch-notes` | `macaron` | Hand-drawn educational diagrams, process explainers, onboarding visuals |
27
+ | `ink-notes-compare` | `comparison` | `ink-notes` | `mono-ink` | Before/After essays, Traditional vs New, OS-style comparisons, mindset-shift narratives |
28
+ | `ink-notes-flow` | `flowchart` | `ink-notes` | `mono-ink` | Professional process explainers, workforce pipelines, hand-drawn technical walkthroughs |
29
+ | `ink-notes-framework` | `framework` | `ink-notes` | `mono-ink` | System analogies, command-center diagrams, architecture-as-metaphor, tech manifestos |
30
+
31
+ ### Data & Analysis
32
+
33
+ | Preset | Type | Style | Palette | Best For |
34
+ |----------|------|-------|---------|----------|
35
+ | `data-report` | `infographic` | `editorial` | — | Data journalism, metrics reports, dashboards |
36
+ | `versus` | `comparison` | `vector-illustration` | — | Tech comparisons, framework shootouts |
37
+ | `business-compare` | `comparison` | `elegant` | — | Product evaluations, strategy options |
38
+
39
+ ### Narrative & Creative
40
+
41
+ | Preset | Type | Style | Palette | Best For |
42
+ |----------|------|-------|---------|----------|
43
+ | `storytelling` | `scene` | `warm` | — | Personal essays, reflections, growth stories |
44
+ | `lifestyle` | `scene` | `watercolor` | — | Travel, wellness, lifestyle, creative |
45
+ | `history` | `timeline` | `elegant` | — | Historical overviews, milestones |
46
+ | `evolution` | `timeline` | `warm` | — | Progress narratives, growth journeys |
47
+
48
+ ### Editorial & Opinion
49
+
50
+ | Preset | Type | Style | Palette | Best For |
51
+ |----------|------|-------|---------|----------|
52
+ | `opinion-piece` | `scene` | `screen-print` | — | Op-eds, commentary, critical essays |
53
+ | `editorial-poster` | `comparison` | `screen-print` | — | Debate, contrasting viewpoints |
54
+ | `cinematic` | `scene` | `screen-print` | — | Dramatic narratives, cultural essays |
55
+
56
+ ## Content Type → Preset Recommendations
57
+
58
+ Use this table during Step 3 to recommend presets based on Step 2 content analysis:
59
+
60
+ | Content Type (Step 2) | Primary Preset | Alternatives |
61
+ |------------------------|----------------|--------------|
62
+ | Technical | `tech-explainer` | `system-design`, `architecture` |
63
+ | Tutorial | `tutorial` | `process-flow`, `knowledge-base`, `edu-visual` |
64
+ | Methodology / Framework | `system-design` | `architecture`, `process-flow` |
65
+ | Data / Metrics | `data-report` | `versus`, `tech-explainer` |
66
+ | Comparison / Review | `versus` | `business-compare`, `editorial-poster`, `ink-notes-compare` |
67
+ | Manifesto / Mindset shift / Professional visual note | `ink-notes-compare` | `ink-notes-framework`, `ink-notes-flow` |
68
+ | Narrative / Personal | `storytelling` | `lifestyle`, `evolution` |
69
+ | Opinion / Editorial | `opinion-piece` | `cinematic`, `editorial-poster` |
70
+ | Historical / Timeline | `history` | `evolution` |
71
+ | Academic / Research | `science-paper` | `tech-explainer`, `data-report` |
72
+ | SaaS / Product | `saas-guide` | `knowledge-base`, `process-flow`, `warm-knowledge` |
73
+ | Education / Knowledge | `edu-visual` | `knowledge-base`, `tutorial`, `hand-drawn-edu` |
74
+
75
+ ## Override Examples
76
+
77
+ - "use the tech-explainer preset but swap the style for notion" = infographic type with notion style
78
+ - "storytelling preset with timeline type" = timeline type with warm style
79
+
80
+ Explicit type/style/palette mentions in the user's request always override preset values.
optional-skills/creative/baoyu-article-illustrator/references/styles.md ADDED
@@ -0,0 +1,224 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Style Reference
2
+
3
+ ## Core Styles
4
+
5
+ Simplified style tier for quick selection:
6
+
7
+ | Core Style | Maps To | Best For |
8
+ |------------|---------|----------|
9
+ | `vector` | vector-illustration | Knowledge articles, tutorials, tech content |
10
+ | `minimal-flat` | notion | General, knowledge sharing, SaaS |
11
+ | `sci-fi` | blueprint | AI, frontier tech, system design |
12
+ | `hand-drawn` | sketch/warm | Relaxed, reflective, casual content |
13
+ | `editorial` | editorial | Processes, data, journalism |
14
+ | `scene` | warm/watercolor | Narratives, emotional, lifestyle |
15
+ | `poster` | screen-print | Opinion, editorial, cultural, cinematic |
16
+
17
+ Use Core Styles for most cases. See full Style Gallery below for granular control.
18
+
19
+ ---
20
+
21
+ ## Style Gallery
22
+
23
+ | Style | Description | Best For |
24
+ |-------|-------------|----------|
25
+ | `vector-illustration` | Clean flat vector art with bold shapes | Knowledge articles, tutorials, tech content |
26
+ | `notion` | Minimalist hand-drawn line art | Knowledge sharing, SaaS, productivity |
27
+ | `elegant` | Refined, sophisticated | Business, thought leadership |
28
+ | `warm` | Friendly, approachable | Personal growth, lifestyle, education |
29
+ | `minimal` | Ultra-clean, zen-like | Philosophy, minimalism, core concepts |
30
+ | `blueprint` | Technical schematics | Architecture, system design, engineering |
31
+ | `watercolor` | Soft artistic with natural warmth | Lifestyle, travel, creative |
32
+ | `editorial` | Magazine-style infographic | Tech explainers, journalism |
33
+ | `scientific` | Academic precise diagrams | Biology, chemistry, technical research |
34
+ | `chalkboard` | Classroom chalk drawing style | Education, teaching, explanations |
35
+ | `fantasy-animation` | Ghibli/Disney-inspired hand-drawn | Storybook, magical, emotional |
36
+ | `flat` | Modern bold geometric shapes | Modern digital, contemporary |
37
+ | `flat-doodle` | Cute flat with bold outlines | Cute, friendly, approachable |
38
+ | `intuition-machine` | Technical briefing with aged paper | Technical briefings, academic |
39
+ | `nature` | Organic earthy illustration | Environmental, wellness |
40
+ | `pixel-art` | Retro 8-bit gaming aesthetic | Gaming, retro tech |
41
+ | `playful` | Whimsical pastel doodles | Fun, casual, educational |
42
+ | `retro` | 80s/90s neon geometric | 80s/90s nostalgic, bold |
43
+ | `sketch` | Raw pencil notebook style | Brainstorming, creative exploration |
44
+ | `screen-print` | Bold poster art, halftone textures, limited colors | Opinion, editorial, cultural, cinematic |
45
+ | `sketch-notes` | Soft hand-drawn warm notes | Educational, warm notes |
46
+ | `ink-notes` | Black ink on pure white, sparse semantic accents, hand-lettered (à la Mike Rohde's sketchnoting) | Before/After essays, tech manifestos, framework analogies |
47
+ | `vintage` | Aged parchment historical | Historical, heritage |
48
+
49
+ Full specifications: `references/styles/<style>.md`
50
+
51
+ ## Type × Style Compatibility Matrix
52
+
53
+ | | vector-illustration | notion | warm | minimal | blueprint | watercolor | elegant | editorial | scientific | screen-print |
54
+ |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
55
+ | infographic | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✓✓ | ✓ |
56
+ | scene | ✓ | ✓ | ✓✓ | ✓ | ✗ | ✓✓ | ✓ | ✓ | ✗ | ✓✓ |
57
+ | flowchart | ✓✓ | ✓✓ | ✓ | ✓ | ✓✓ | ✗ | ✓ | ✓✓ | ✓ | ✗ |
58
+ | comparison | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓ | ✓ | ✓✓ | ✓✓ | ✓ | ✓ |
59
+ | framework | ✓✓ | ✓✓ | ✓ | ✓✓ | ✓✓ | ✗ | ✓✓ | ✓ | ✓✓ | ✓ |
60
+ | timeline | ✓ | ✓✓ | ✓ | ✓ | ✓ | ✓✓ | ✓✓ | ✓✓ | ✓ | ✓ |
61
+
62
+ ✓✓ = highly recommended | ✓ = compatible | ✗ = not recommended
63
+
64
+ ## Auto Selection by Type
65
+
66
+ | Type | Primary Style | Secondary Styles |
67
+ |------|---------------|------------------|
68
+ | infographic | vector-illustration | notion, blueprint, editorial |
69
+ | scene | warm | watercolor, elegant |
70
+ | flowchart | vector-illustration | notion, blueprint |
71
+ | comparison | vector-illustration | notion, elegant |
72
+ | framework | blueprint | vector-illustration, notion |
73
+ | timeline | elegant | warm, editorial |
74
+
75
+ ## Auto Selection by Content Signals
76
+
77
+ | Content Signals | Recommended Type | Recommended Style |
78
+ |-----------------|------------------|-------------------|
79
+ | API, metrics, data, comparison, numbers | infographic | blueprint, vector-illustration |
80
+ | Knowledge, concept, tutorial, learning, guide | infographic | vector-illustration, notion |
81
+ | Tech, AI, programming, development, code | infographic | vector-illustration, blueprint |
82
+ | How-to, steps, workflow, process, tutorial | flowchart | vector-illustration, notion |
83
+ | Framework, model, architecture, principles | framework | blueprint, vector-illustration |
84
+ | vs, pros/cons, before/after, alternatives | comparison | vector-illustration, notion |
85
+ | Manifesto, mindset shift, workforce, OS, whiteboard, professional visual note | comparison / framework | ink-notes |
86
+ | Story, emotion, journey, experience, personal | scene | warm, watercolor |
87
+ | History, timeline, progress, evolution | timeline | elegant, warm |
88
+ | Productivity, SaaS, tool, app, software | infographic | notion, vector-illustration |
89
+ | Business, professional, strategy, corporate | framework | elegant |
90
+ | Opinion, editorial, culture, philosophy, cinematic, dramatic, poster | scene | screen-print |
91
+ | Biology, chemistry, medical, scientific | infographic | scientific |
92
+ | Explainer, journalism, magazine, investigation | infographic | editorial |
93
+
94
+ ## Style Characteristics by Type
95
+
96
+ ### infographic + vector-illustration
97
+ - Clean flat vector shapes, bold geometric forms
98
+ - Vibrant but harmonious color palette
99
+ - Clear visual hierarchy with icons and labels
100
+ - Modern, professional, highly readable
101
+ - Perfect for knowledge articles and tutorials
102
+
103
+ ### flowchart + vector-illustration
104
+ - Bold arrows and connectors
105
+ - Distinct step containers with icons
106
+ - Clean progression flow
107
+ - High contrast for readability
108
+
109
+ ### comparison + vector-illustration
110
+ - Split layout with clear visual separation
111
+ - Bold iconography for each side
112
+ - Color-coded distinctions
113
+ - Easy at-a-glance comparison
114
+
115
+ ### framework + vector-illustration
116
+ - Geometric node representations
117
+ - Clear hierarchical structure
118
+ - Bold connecting lines
119
+ - Modern system diagram aesthetic
120
+
121
+ ### infographic + blueprint
122
+ - Technical precision, schematic lines
123
+ - Grid-based layout, clear zones
124
+ - Monospace labels, data-focused
125
+ - Blue/white color scheme
126
+
127
+ ### infographic + notion
128
+ - Hand-drawn feel, approachable
129
+ - Soft icons, rounded elements
130
+ - Neutral palette, clean backgrounds
131
+ - Perfect for SaaS/productivity
132
+
133
+ ### scene + warm
134
+ - Golden hour lighting, cozy atmosphere
135
+ - Soft gradients, natural textures
136
+ - Inviting, personal feeling
137
+ - Great for storytelling
138
+
139
+ ### scene + watercolor
140
+ - Artistic, painterly effect
141
+ - Soft edges, color bleeding
142
+ - Dreamy, creative mood
143
+ - Best for lifestyle/travel
144
+
145
+ ### flowchart + notion
146
+ - Clear step indicators
147
+ - Simple arrow connections
148
+ - Minimal decoration
149
+ - Focus on process clarity
150
+
151
+ ### flowchart + blueprint
152
+ - Technical precision
153
+ - Detailed connection points
154
+ - Engineering aesthetic
155
+ - For complex systems
156
+
157
+ ### comparison + elegant
158
+ - Refined dividers
159
+ - Balanced typography
160
+ - Professional appearance
161
+ - Business comparisons
162
+
163
+ ### framework + blueprint
164
+ - Precise node connections
165
+ - Hierarchical clarity
166
+ - System architecture feel
167
+ - Technical frameworks
168
+
169
+ ### timeline + elegant
170
+ - Sophisticated markers
171
+ - Refined typography
172
+ - Historical gravitas
173
+ - Professional presentations
174
+
175
+ ### timeline + warm
176
+ - Friendly progression
177
+ - Organic flow
178
+ - Personal journey feel
179
+ - Growth narratives
180
+
181
+ ### scene + screen-print
182
+ - Bold silhouettes, symbolic compositions
183
+ - 2-5 flat colors with halftone textures
184
+ - Figure-ground inversion (negative space tells secondary story)
185
+ - Vintage poster aesthetic, conceptual not literal
186
+ - Great for opinion pieces and cultural commentary
187
+
188
+ ### comparison + screen-print
189
+ - Split duotone composition (one color per side)
190
+ - Bold geometric dividers
191
+ - Symbolic icons over detailed rendering
192
+ - High contrast, immediate visual impact
193
+
194
+ ### framework + screen-print
195
+ - Geometric node representations with stencil-cut edges
196
+ - Limited color coding (one color per concept level)
197
+ - Clean silhouette-based iconography
198
+ - Poster-style hierarchy with bold typography
199
+
200
+ ---
201
+
202
+ ## Palette Gallery
203
+
204
+ Palettes override a style's default colors. Combine any style with any palette (e.g. `style=vector-illustration, palette=macaron`).
205
+
206
+ | Palette | Description | Best For |
207
+ |---------|-------------|----------|
208
+ | `macaron` | Soft pastel blocks (blue, mint, lavender, peach) on warm cream | Educational, knowledge, tutorials |
209
+ | `warm` | Warm earth tones (orange, terracotta, gold) on soft peach, no cool colors | Brand, product, lifestyle |
210
+ | `neon` | Vibrant neon (pink, cyan, yellow) on dark purple | Gaming, retro, pop culture |
211
+ | `mono-ink` | Black ink on pure white with sparse semantic accents (coral red, muted teal, dusty lavender) | Professional visual notes, Before/After, manifestos |
212
+
213
+ Full specifications: `references/palettes/<palette>.md`
214
+
215
+ When no palette is specified, the style's built-in Color Palette is used.
216
+
217
+ ## Palette Override Rules
218
+
219
+ 1. Read style file → rendering rules (Visual Elements, Style Rules)
220
+ 2. Read palette file → Colors + Background
221
+ 3. Palette colors **replace** style's default Color Palette
222
+ 4. Palette Background **replaces** style's default Background color
223
+ 5. Style's texture description is preserved
224
+
optional-skills/creative/baoyu-article-illustrator/references/styles/blueprint.md ADDED
@@ -0,0 +1,57 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # blueprint
2
+
3
+ Precise technical blueprint style with engineering precision
4
+
5
+ ## Design Aesthetic
6
+
7
+ Clean, structured visual metaphors using blueprints, diagrams, and schematics. Precise, analytical and aesthetically refined. Information presented in grid-based layouts with engineering precision. Technical drawing quality with professional polish.
8
+
9
+ ## Background
10
+
11
+ - Color: Blueprint Off-White (#FAF8F5)
12
+ - Texture: Subtle grid overlay, engineering paper feel
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Blueprint Paper | #FAF8F5 | Primary background |
19
+ | Grid | Light Gray | #E5E5E5 | Background grid lines |
20
+ | Primary Text | Deep Slate | #334155 | Headlines, body |
21
+ | Primary Accent | Engineering Blue | #2563EB | Key elements |
22
+ | Secondary Accent | Navy Blue | #1E3A5F | Supporting elements |
23
+ | Tertiary | Light Blue | #BFDBFE | Fills, backgrounds |
24
+ | Warning | Amber | #F59E0B | Warnings, emphasis |
25
+
26
+ ## Visual Elements
27
+
28
+ - Precise lines with consistent stroke weights
29
+ - Technical schematics and clean vector graphics
30
+ - Thin line work in technical drawing style
31
+ - Connection lines: straight or 90-degree angles only
32
+ - Data visualization with minimal charts
33
+ - Dimension lines and measurement indicators
34
+ - Cross-section style diagrams
35
+ - Isometric or orthographic projections
36
+
37
+ ## Style Rules
38
+
39
+ ### Do
40
+
41
+ - Maintain consistent line weights
42
+ - Use grid alignment for all elements
43
+ - Keep color palette restrained
44
+ - Create clear visual hierarchy through scale
45
+ - Use geometric precision for all shapes
46
+
47
+ ### Don't
48
+
49
+ - Use hand-drawn or organic shapes
50
+ - Add decorative flourishes
51
+ - Use curved connection lines
52
+ - Include photographic elements
53
+ - Add unnecessary embellishments
54
+
55
+ ## Best For
56
+
57
+ Technical architecture, system design, data analysis, engineering documentation, process flows, infrastructure articles
optional-skills/creative/baoyu-article-illustrator/references/styles/chalkboard.md ADDED
@@ -0,0 +1,62 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # chalkboard
2
+
3
+ Black chalkboard background with colorful chalk drawing style
4
+
5
+ ## Design Aesthetic
6
+
7
+ Classic classroom chalkboard aesthetic with hand-drawn chalk illustrations. Nostalgic educational feel with imperfect, sketchy lines that capture the warmth of traditional teaching. Colorful chalk creates visual hierarchy while maintaining the authentic chalkboard experience.
8
+
9
+ ## Background
10
+
11
+ - Color: Chalkboard Black (#1A1A1A) or Dark Green-Black (#1C2B1C)
12
+ - Texture: Realistic chalkboard texture with subtle scratches, dust particles, and faint eraser marks
13
+
14
+ ## Typography
15
+
16
+ Hand-drawn chalk lettering style with visible chalk texture. Imperfect baseline adds authenticity. White or bright colored chalk for emphasis.
17
+
18
+ ## Color Palette
19
+
20
+ | Role | Color | Hex | Usage |
21
+ |------|-------|-----|-------|
22
+ | Background | Chalkboard Black | #1A1A1A | Primary background |
23
+ | Alt Background | Green-Black | #1C2B1C | Traditional green board |
24
+ | Primary Text | Chalk White | #F5F5F5 | Main text, outlines |
25
+ | Accent 1 | Chalk Yellow | #FFE566 | Highlights, emphasis |
26
+ | Accent 2 | Chalk Pink | #FF9999 | Secondary highlights |
27
+ | Accent 3 | Chalk Blue | #66B3FF | Diagrams, links |
28
+ | Accent 4 | Chalk Green | #90EE90 | Success, nature |
29
+ | Accent 5 | Chalk Orange | #FFB366 | Warnings, energy |
30
+
31
+ ## Visual Elements
32
+
33
+ - Hand-drawn chalk illustrations with sketchy, imperfect lines
34
+ - Chalk dust effects around text and key elements
35
+ - Doodles: stars, arrows, underlines, circles, checkmarks
36
+ - Mathematical formulas and simple diagrams
37
+ - Eraser smudges and chalk residue textures
38
+ - Wooden frame border optional
39
+ - Stick figures and simple icons
40
+ - Connection lines with hand-drawn feel
41
+
42
+ ## Style Rules
43
+
44
+ ### Do
45
+
46
+ - Maintain authentic chalk texture on all elements
47
+ - Use imperfect, hand-drawn quality throughout
48
+ - Add subtle chalk dust and smudge effects
49
+ - Create visual hierarchy with color variety
50
+ - Include playful doodles and annotations
51
+
52
+ ### Don't
53
+
54
+ - Use perfect geometric shapes
55
+ - Create clean digital-looking lines
56
+ - Add photorealistic elements
57
+ - Use gradients or glossy effects
58
+ - Make it look computerized
59
+
60
+ ## Best For
61
+
62
+ Educational articles, tutorials, teaching content, workshops, informal learning, knowledge sharing, how-to guides, classroom-style explanations
optional-skills/creative/baoyu-article-illustrator/references/styles/editorial.md ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # editorial
2
+
3
+ Magazine-style editorial infographic for professional content
4
+
5
+ ## Design Aesthetic
6
+
7
+ High-quality magazine explainer aesthetic. Clear visual storytelling with structured layouts and professional typography. Think Wired, The Verge, or quality science publications. Complex information made digestible.
8
+
9
+ ## Background
10
+
11
+ - Color: Pure White (#FFFFFF) or Light Gray (#F8F9FA)
12
+ - Texture: None or subtle paper grain
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Pure White | #FFFFFF | Primary background |
19
+ | Alt Background | Light Gray | #F8F9FA | Section backgrounds |
20
+ | Primary Text | Near Black | #1A1A1A | Headlines, body |
21
+ | Secondary Text | Dark Gray | #4A5568 | Captions |
22
+ | Accent 1 | Editorial Blue | #2563EB | Primary accent |
23
+ | Accent 2 | Coral | #F97316 | Secondary accent |
24
+ | Accent 3 | Emerald | #10B981 | Positive elements |
25
+ | Accent 4 | Amber | #F59E0B | Attention points |
26
+ | Dividers | Medium Gray | #D1D5DB | Section dividers |
27
+
28
+ ## Visual Elements
29
+
30
+ - Clean flat illustrations
31
+ - Structured multi-section layouts
32
+ - Callout boxes for insights
33
+ - Icon-based visualizations
34
+ - Visual metaphors for concepts
35
+ - Flow diagrams with hierarchy
36
+ - Pull quotes and highlights
37
+ - Clear section dividers
38
+
39
+ ## Style Rules
40
+
41
+ ### Do
42
+
43
+ - Create clear narrative flow
44
+ - Use structured layouts
45
+ - Include callout boxes
46
+ - Design visual metaphors
47
+ - Maintain magazine polish
48
+
49
+ ### Don't
50
+
51
+ - Use photographic imagery
52
+ - Create cluttered layouts
53
+ - Mix too many styles
54
+ - Add purposeless decoration
55
+ - Compromise clarity for style
56
+
57
+ ## Best For
58
+
59
+ Technology explainers, science communication, research articles, policy analysis, investigative pieces, thought leadership, long-form journalism
optional-skills/creative/baoyu-article-illustrator/references/styles/elegant.md ADDED
@@ -0,0 +1,56 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # elegant
2
+
3
+ Refined, sophisticated illustration style for professional content
4
+
5
+ ## Design Aesthetic
6
+
7
+ Elegant and refined visual approach with sophisticated color palette. Professional polish with subtle artistic touches. Emphasizes clarity and thoughtful composition. Conveys authority and trustworthiness without being cold or clinical.
8
+
9
+ ## Background
10
+
11
+ - Color: Warm Cream (#F5F0E6) or Soft Beige (#FAF6F0)
12
+ - Texture: Subtle paper texture, very light grain
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Warm Cream | #F5F0E6 | Primary background |
19
+ | Primary | Soft Coral | #E8A598 | Main accent color |
20
+ | Secondary | Muted Teal | #5B8A8A | Supporting elements |
21
+ | Tertiary | Dusty Rose | #D4A5A5 | Subtle highlights |
22
+ | Accent | Gold | #C9A962 | Premium touches |
23
+ | Alt Accent | Copper | #B87333 | Warm metallic notes |
24
+ | Text | Charcoal | #3D3D3D | Text and outlines |
25
+
26
+ ## Visual Elements
27
+
28
+ - Delicate line work with refined strokes
29
+ - Subtle icons with balanced weight
30
+ - Graceful curves and flowing compositions
31
+ - Soft gradients with smooth transitions
32
+ - Balanced whitespace and breathing room
33
+ - Thin borders and elegant dividers
34
+ - Subtle drop shadows for depth
35
+
36
+ ## Style Rules
37
+
38
+ ### Do
39
+
40
+ - Use refined color combinations
41
+ - Create balanced, harmonious compositions
42
+ - Keep elements light and airy
43
+ - Use subtle gradients sparingly
44
+ - Maintain generous margins
45
+
46
+ ### Don't
47
+
48
+ - Use harsh contrasts
49
+ - Overcrowd the composition
50
+ - Add playful or casual elements
51
+ - Use neon or overly bright colors
52
+ - Create busy or cluttered layouts
53
+
54
+ ## Best For
55
+
56
+ Professional articles, thought leadership pieces, business topics, executive communications, corporate blogs, strategy discussions, industry analysis
optional-skills/creative/baoyu-article-illustrator/references/styles/fantasy-animation.md ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # fantasy-animation
2
+
3
+ Whimsical hand-drawn animation style inspired by Ghibli/Disney
4
+
5
+ ## Design Aesthetic
6
+
7
+ Charming hand-drawn animation aesthetic reminiscent of classic Disney, Studio Ghibli, or European storybook illustration. Soft, painterly textures with warm, inviting colors. Friendly characters, magical elements, and storybook feel. Enchanting, nostalgic, and emotionally engaging.
8
+
9
+ ## Background
10
+
11
+ - Color: Soft Sky Blue (#E8F4FC) or Warm Cream (#FFF8E7)
12
+ - Texture: Subtle watercolor wash, soft brush strokes
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Soft Sky Blue | #E8F4FC | Primary background |
19
+ | Alt Background | Warm Cream | #FFF8E7 | Secondary areas |
20
+ | Primary Text | Deep Forest | #2D5A3D | Headlines |
21
+ | Body Text | Warm Brown | #5D4E37 | Content |
22
+ | Accent 1 | Golden Yellow | #F4D03F | Magic, highlights |
23
+ | Accent 2 | Rose Pink | #E8A0BF | Warmth, charm |
24
+ | Accent 3 | Sage Green | #87A96B | Nature elements |
25
+ | Accent 4 | Sky Blue | #7EC8E3 | Air, water, dreams |
26
+ | Accent 5 | Coral | #F08080 | Emphasis, life |
27
+
28
+ ## Visual Elements
29
+
30
+ - Central illustrated character (friendly, expressive)
31
+ - Small companion creatures (animals, magical beings)
32
+ - Storybook-style environment backgrounds
33
+ - Magical floating objects (books, orbs, sparkles)
34
+ - Decorative elements: stars, flowers, leaves
35
+ - Soft shadows and gentle highlights
36
+ - Layered depth with foreground/background
37
+
38
+ ## Style Rules
39
+
40
+ ### Do
41
+
42
+ - Create warm, inviting compositions
43
+ - Use soft edges and painterly textures
44
+ - Include charming character illustrations
45
+ - Add magical decorative touches
46
+ - Maintain storybook narrative feel
47
+
48
+ ### Don't
49
+
50
+ - Use harsh geometric shapes
51
+ - Create dark or intimidating imagery
52
+ - Add photorealistic elements
53
+ - Use cold color palettes
54
+ - Make it look digital/computerized
55
+
56
+ ## Best For
57
+
58
+ Educational content, children's articles, storytelling, creative topics, fantasy/gaming, inspirational pieces, family-friendly content
optional-skills/creative/baoyu-article-illustrator/references/styles/flat-doodle.md ADDED
@@ -0,0 +1,61 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # flat-doodle
2
+
3
+ Cute flat doodle illustration style with bold outlines
4
+
5
+ ## Design Aesthetic
6
+
7
+ Cheerful and approachable visual style combining flat design with doodle charm. Features bold black outlines around simple shapes. Bright pastel colors with no gradients or shading. Cute rounded proportions that feel friendly. Clean white backgrounds create focus and clarity.
8
+
9
+ ## Background
10
+
11
+ - Color: Clean White (#FFFFFF)
12
+ - Texture: None - pure white isolated background
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | White | #FFFFFF | Primary background |
19
+ | Primary | Pastel Pink | #FFB6C1 | Main elements |
20
+ | Secondary | Mint | #98D8C8 | Supporting elements |
21
+ | Tertiary | Lavender | #C8A2C8 | Accent elements |
22
+ | Accent 1 | Butter Yellow | #FFFACD | Highlight pop |
23
+ | Accent 2 | Sky Blue | #87CEEB | Cool accent |
24
+ | Accent 3 | Soft Coral | #F88379 | Warm accent |
25
+ | Outline | Bold Black | #000000 | All outlines |
26
+ | Text | Black | #1A1A1A | Text elements |
27
+
28
+ ## Visual Elements
29
+
30
+ - Bold black outlines around all shapes
31
+ - Simple flat color fills
32
+ - Cute rounded proportions
33
+ - Minimal geometric shapes
34
+ - Productivity icons (laptops, calendars, checkmarks)
35
+ - Isolated elements on white
36
+ - No shading or gradients
37
+ - Hand-drawn quality with clean edges
38
+
39
+ ## Style Rules
40
+
41
+ ### Do
42
+
43
+ - Use bold black outlines consistently
44
+ - Keep shapes simple and rounded
45
+ - Use bright pastel palette
46
+ - Isolate elements on white background
47
+ - Maintain cute proportions
48
+ - Keep minimal shading
49
+
50
+ ### Don't
51
+
52
+ - Add shadows or depth effects
53
+ - Use gradients or textures
54
+ - Create complex detailed illustrations
55
+ - Overlap too many elements
56
+ - Use dark or moody backgrounds
57
+ - Add realistic proportions
58
+
59
+ ## Best For
60
+
61
+ Productivity articles, SaaS and app content, workflow tutorials, beginner guides, casual business content, tool introductions, lifestyle productivity
optional-skills/creative/baoyu-article-illustrator/references/styles/flat.md ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # flat
2
+
3
+ Modern flat vector illustration style for contemporary content
4
+
5
+ ## Design Aesthetic
6
+
7
+ Contemporary flat design aesthetic with bold shapes and limited depth. Clean geometric forms with no gradients or shadows. Modern, accessible, and highly readable. Optimized for digital consumption with scalable vector quality.
8
+
9
+ ## Background
10
+
11
+ - Color: White (#FFFFFF) or Soft Gray (#F5F5F5)
12
+ - Texture: None - clean solid backgrounds
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | White | #FFFFFF | Primary background |
19
+ | Alt Background | Soft Gray | #F5F5F5 | Accent areas |
20
+ | Primary | Vibrant Blue | #3B82F6 | Main elements |
21
+ | Secondary | Coral | #F97316 | Supporting elements |
22
+ | Tertiary | Emerald | #10B981 | Accent elements |
23
+ | Accent 1 | Purple | #8B5CF6 | Additional accent |
24
+ | Accent 2 | Amber | #F59E0B | Highlight |
25
+ | Text | Dark Slate | #1E293B | Text elements |
26
+ | Light | Light Gray | #E5E7EB | Subtle elements |
27
+
28
+ ## Visual Elements
29
+
30
+ - Bold geometric shapes
31
+ - Flat color fills with no gradients
32
+ - Simple character illustrations
33
+ - Clean icon designs
34
+ - Minimal line work
35
+ - Overlapping shape compositions
36
+ - Abstract concept visualizations
37
+ - Consistent stroke weights
38
+
39
+ ## Style Rules
40
+
41
+ ### Do
42
+
43
+ - Use flat solid colors
44
+ - Create clean geometric shapes
45
+ - Keep elements simple
46
+ - Maintain consistent styling
47
+ - Use bold color combinations
48
+
49
+ ### Don't
50
+
51
+ - Add shadows or depth
52
+ - Use gradients or textures
53
+ - Create realistic illustrations
54
+ - Add unnecessary details
55
+ - Use photographic elements
56
+
57
+ ## Best For
58
+
59
+ Modern articles, app and product content, startup stories, digital topics, contemporary business, tech company blogs, social media content
optional-skills/creative/baoyu-article-illustrator/references/styles/ink-notes.md ADDED
@@ -0,0 +1,90 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ink-notes
2
+
3
+ Professional black-ink visual notes on pure white, in the tradition of Mike Rohde's sketchnoting
4
+
5
+ ## Compared to sketch-notes
6
+
7
+ `ink-notes` and `sketch-notes` are distinct styles. Pick the right one:
8
+
9
+ | | `sketch-notes` | `ink-notes` |
10
+ |---|---|---|
11
+ | Background | Warm Off-White #FAF8F0 with paper grain | Pure White #FFFFFF, clean, no texture |
12
+ | Palette | Soft warm accents (orange, mustard, sage, light blue) | Black ink dominant + sparse semantic accents |
13
+ | Feel | Soft, warm, educational, approachable | Professional, structured, whiteboard-presentation |
14
+ | Best For | Friendly tutorials, onboarding, casual explainers | Before/After essays, tech manifestos, framework analogies |
15
+
16
+ When in doubt: warm & friendly → `sketch-notes`. Disciplined & professional → `ink-notes`.
17
+
18
+ ## Design Aesthetic
19
+
20
+ Disciplined hand-drawn visual note. Confident black ink line work with slight wobble, hand-lettered typography, and sparse color accents used only for semantic emphasis. Feels like a skilled visual notetaker's whiteboard presentation — clean, structured, intentionally hand-drawn rather than decorative.
21
+
22
+ ## Background
23
+
24
+ - Color: Pure White (#FFFFFF)
25
+ - Texture: Clean, no grain, no tint
26
+
27
+ ## Color Palette
28
+
29
+ | Role | Color | Hex | Usage |
30
+ |------|-------|-----|-------|
31
+ | Background | Pure White | #FFFFFF | Canvas |
32
+ | Primary Ink | Near Black | #1A1A1A | All lines, text, figures, arrows |
33
+ | Accent Warm | Coral Red | #E8655A | Risk, problem, gap, emphasis |
34
+ | Accent Cool | Muted Teal | #5FA8A8 | Positive, solution, "after" state |
35
+ | Accent Neutral | Dusty Lavender | #9B8AB5 | Neutral tags, category labels |
36
+ | Soft Fill | Pale Gray | #F0F0F0 | Subtle zone backgrounds (optional) |
37
+
38
+ Color accents must remain under 10% of canvas area and only carry semantic meaning. Black ink does the structural work.
39
+
40
+ ## Visual Elements
41
+
42
+ - Black ink line work with intentional slight wobble on all strokes
43
+ - Hand-lettered titles (bold, oversized) and handwritten body annotations
44
+ - Simple stick-figure characters with expressive poses (pointing, thinking, walking)
45
+ - Role labels above characters (e.g., "Tech Lead", "Compliance Officer")
46
+ - Thought bubbles and speech bubbles with hand-drawn outlines
47
+ - Rounded-rectangle frames for content groupings
48
+ - Dashed-border rectangles for placeholder, "coming next", or empty states
49
+ - Curvy hand-drawn arrows with small inline labels
50
+ - Vertical or horizontal dividers between comparison zones ("Before" | "After")
51
+ - "Mindset shift" curved arrow bridging two zones
52
+ - Bottom tagline: single-line hand-lettered conclusion that points the takeaway
53
+ - Stars, asterisks, underlines for emphasis — used sparingly
54
+
55
+ ## Style Rules
56
+
57
+ ### Do
58
+
59
+ - Keep background pure white with no texture or tint
60
+ - Let black ink dominate outlines, text, and figures
61
+ - Use accent colors only for semantic highlighting
62
+ - Keep all type hand-lettered — no computer-generated fonts
63
+ - Maintain confident line quality (wobble, not mess)
64
+ - Include a bottom tagline summarizing the main takeaway
65
+ - Structure content into clear zones with visible dividers
66
+ - Use dashed boxes for future, empty, or placeholder states
67
+
68
+ ### Don't
69
+
70
+ - Use warm off-white or paper-textured backgrounds (that is sketch-notes' territory)
71
+ - Fill large zones with color blocks
72
+ - Use more than 3 accent colors per image
73
+ - Use perfect geometric shapes — preserve hand-drawn wobble
74
+ - Clutter with decorative doodles; every element must carry meaning
75
+ - Use gradients, shadows, or computer-generated fonts
76
+
77
+ ## Type Compatibility
78
+
79
+ | Type | Rating | Notes |
80
+ |------|--------|-------|
81
+ | comparison | ✓✓ | Best fit — Before/After, Traditional vs New, side-by-side contrasts |
82
+ | framework | ✓✓ | OS-style command centers, layered architectures, organizational models |
83
+ | flowchart | ✓✓ | Process explainers with labeled stages, workforce pipelines |
84
+ | infographic | ✓ | Multi-zone technical summaries, manifesto-style posters |
85
+ | timeline | ✓ | Hand-drawn horizontal arrow with era markers and milestones |
86
+ | scene | ✗ | Not recommended — lacks scenic space |
87
+
88
+ ## Best For
89
+
90
+ Product and engineering essays, tech manifestos, framework introductions, Before/After narratives, OS-level comparisons, workforce and organizational analogies, visual summaries of talks, thought-leadership articles
optional-skills/creative/baoyu-article-illustrator/references/styles/intuition-machine.md ADDED
@@ -0,0 +1,57 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # intuition-machine
2
+
3
+ Technical briefing infographic style with aged paper and bilingual labels
4
+
5
+ ## Design Aesthetic
6
+
7
+ Academic/technical briefing style with clean 2D or isometric technical illustrations. Information-dense but organized with clear visual hierarchy. Vintage blueprint aesthetic with modern clarity. Multiple explanatory elements with bilingual callouts.
8
+
9
+ ## Background
10
+
11
+ - Color: Aged Cream (#F5F0E6)
12
+ - Texture: Subtle paper texture with light creases, vintage technical print feel
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Aged Cream | #F5F0E6 | Primary background |
19
+ | Paper Texture | Warm White | #F5F0E1 | Blueprint effect |
20
+ | Primary Text | Dark Maroon | #5D3A3A | Headlines, titles |
21
+ | Body Text | Near Black | #1A1A1A | Content text |
22
+ | Accent 1 | Teal | #2F7373 | Primary illustrations |
23
+ | Accent 2 | Warm Brown | #8B7355 | Secondary elements |
24
+ | Accent 3 | Maroon | #722F37 | Emphasis |
25
+ | Outline | Deep Charcoal | #2D2D2D | Element outlines |
26
+
27
+ ## Visual Elements
28
+
29
+ - Isometric 3D or flat 2D technical diagrams
30
+ - Explanatory text boxes with labeled content
31
+ - Bilingual callout labels (English + Chinese)
32
+ - Faded thematic background patterns
33
+ - Clean black outlines on elements
34
+ - Split or triptych layouts
35
+ - Key insight boxes
36
+
37
+ ## Style Rules
38
+
39
+ ### Do
40
+
41
+ - Include multiple text boxes with content
42
+ - Use bilingual labels for key elements
43
+ - Add faded thematic background patterns
44
+ - Maintain aged paper texture
45
+ - Create clear visual hierarchy
46
+
47
+ ### Don't
48
+
49
+ - Create photorealistic 3D renders
50
+ - Leave illustrations without explanatory text
51
+ - Add stamps or watermarks in corners
52
+ - Use gradients or glossy effects
53
+ - Make it look too modern/digital
54
+
55
+ ## Best For
56
+
57
+ Technical explanations, concept breakdowns, academic content, research summaries, bilingual audiences, knowledge documentation
optional-skills/creative/baoyu-article-illustrator/references/styles/minimal.md ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # minimal
2
+
3
+ Ultra-clean, zen-like illustration style for focused content
4
+
5
+ ## Design Aesthetic
6
+
7
+ Maximum simplicity with purposeful restraint. Every element serves a function. Zen-like calm and focus through extensive negative space. Single focal point approach that guides attention naturally. Quiet elegance through reduction.
8
+
9
+ ## Background
10
+
11
+ - Color: Pure White (#FFFFFF) or Off-White (#FAFAFA)
12
+ - Texture: None - clean solid backgrounds
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | White | #FFFFFF | Primary background |
19
+ | Alt Background | Off-White | #FAFAFA | Subtle variation |
20
+ | Primary | Pure Black | #000000 | Main elements |
21
+ | Accent | Content-Derived | varies | Single accent color |
22
+ | Text | Black | #000000 | Text elements |
23
+ | Alt Text | Medium Gray | #6B6B6B | Secondary text |
24
+
25
+ Note: Accent color is derived from content context. Use sparingly.
26
+
27
+ ## Visual Elements
28
+
29
+ - Single focal element per illustration
30
+ - Maximum negative space
31
+ - Thin, precise lines
32
+ - Simple geometric forms
33
+ - Subtle shadows if any
34
+ - Typography as primary element
35
+ - Strategic use of single accent
36
+ - Clean, uncluttered compositions
37
+
38
+ ## Style Rules
39
+
40
+ ### Do
41
+
42
+ - Embrace empty space
43
+ - Use single focal points
44
+ - Keep lines thin and precise
45
+ - Let content breathe
46
+ - Question every element
47
+
48
+ ### Don't
49
+
50
+ - Add decorative elements
51
+ - Use multiple accent colors
52
+ - Fill available space
53
+ - Add textures or patterns
54
+ - Create visual complexity
55
+
56
+ ## Best For
57
+
58
+ Philosophy articles, minimalism content, focused explanations, meditation and mindfulness, essential concepts, clarity-focused writing
optional-skills/creative/baoyu-article-illustrator/references/styles/nature.md ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # nature
2
+
3
+ Organic, earthy illustration style for environmental and wellness content
4
+
5
+ ## Design Aesthetic
6
+
7
+ Natural and organic visual approach inspired by the outdoors. Earth tones and natural textures that evoke calm and connection to nature. Flowing lines and organic shapes. Creates a sense of tranquility and environmental awareness.
8
+
9
+ ## Background
10
+
11
+ - Color: Sand Beige (#F5E6D3) or Sky Blue wash (#E0F2FE)
12
+ - Texture: Natural paper texture with organic feel
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Sand Beige | #F5E6D3 | Primary background |
19
+ | Alt Background | Sky Blue | #E0F2FE | Alternative canvas |
20
+ | Primary | Forest Green | #276749 | Main natural color |
21
+ | Secondary | Sage | #9AE6B4 | Supporting green |
22
+ | Tertiary | Earth Brown | #744210 | Grounding element |
23
+ | Accent 1 | Sunset Orange | #ED8936 | Warm accent |
24
+ | Accent 2 | Water Blue | #63B3ED | Cool accent |
25
+ | Text | Deep Brown | #5D4E3C | Text elements |
26
+
27
+ ## Visual Elements
28
+
29
+ - Leaf and plant motifs
30
+ - Tree and branch silhouettes
31
+ - Mountain and landscape shapes
32
+ - Organic flowing lines
33
+ - Natural textures (wood grain, stone)
34
+ - Water and wave patterns
35
+ - Animal silhouettes
36
+ - Sun and moon symbols
37
+
38
+ ## Style Rules
39
+
40
+ ### Do
41
+
42
+ - Use earth-inspired colors
43
+ - Create organic, flowing shapes
44
+ - Include nature elements
45
+ - Evoke outdoor atmosphere
46
+ - Maintain calm and balance
47
+
48
+ ### Don't
49
+
50
+ - Use synthetic or neon colors
51
+ - Create rigid geometric shapes
52
+ - Add tech or digital elements
53
+ - Use stark contrasts
54
+ - Overcomplicate compositions
55
+
56
+ ## Best For
57
+
58
+ Sustainability articles, wellness content, outdoor topics, slow living, environmental issues, health and fitness, gardening, travel nature pieces
optional-skills/creative/baoyu-article-illustrator/references/styles/notion.md ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # notion
2
+
3
+ Minimalist hand-drawn line art style for knowledge content (Default)
4
+
5
+ ## Design Aesthetic
6
+
7
+ Clean, minimalist hand-drawn line art with intellectual feel. Simple doodle-style illustrations with intentional wobble. Maximum whitespace with single concept focus. Notion-like aesthetic that feels thoughtful and organized.
8
+
9
+ ## Background
10
+
11
+ - Color: Pure White (#FFFFFF) or Off-White (#FAFAFA)
12
+ - Texture: None - clean solid backgrounds
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | White | #FFFFFF | Primary background |
19
+ | Alt Background | Off-White | #FAFAFA | Subtle variation |
20
+ | Primary | Black | #1A1A1A | Main outlines |
21
+ | Secondary | Dark Gray | #4A4A4A | Supporting lines |
22
+ | Accent 1 | Pastel Blue | #A8D4F0 | Soft highlight |
23
+ | Accent 2 | Pastel Yellow | #F9E79F | Warm highlight |
24
+ | Accent 3 | Pastel Pink | #FADBD8 | Gentle accent |
25
+ | Text | Near Black | #1A1A1A | Text elements |
26
+
27
+ ## Visual Elements
28
+
29
+ - Simple line doodles
30
+ - Hand-drawn wobble effect
31
+ - Basic geometric shapes
32
+ - Stick figures for people
33
+ - Conceptual icons
34
+ - Clean hand-drawn lettering
35
+ - Minimal decorative elements
36
+ - Single-weight line work
37
+
38
+ ## Style Rules
39
+
40
+ ### Do
41
+
42
+ - Use maximum whitespace
43
+ - Keep illustrations simple
44
+ - Add slight hand-drawn wobble
45
+ - Focus on single concepts
46
+ - Use pastel accents sparingly
47
+
48
+ ### Don't
49
+
50
+ - Create complex illustrations
51
+ - Use many colors at once
52
+ - Add detailed textures
53
+ - Make precise geometric shapes
54
+ - Overcrowd the composition
55
+
56
+ ## Best For
57
+
58
+ Knowledge sharing, concept explanations, SaaS content, productivity articles, educational posts, how-to guides, professional blogs
optional-skills/creative/baoyu-article-illustrator/references/styles/pixel-art.md ADDED
@@ -0,0 +1,57 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # pixel-art
2
+
3
+ Retro 8-bit pixel art aesthetic with nostalgic gaming style
4
+
5
+ ## Design Aesthetic
6
+
7
+ Pixelated retro aesthetic reminiscent of classic 8-bit and 16-bit era games. Chunky pixels, limited color palettes, and nostalgic gaming references. Simple geometric shapes rendered in blocky pixel form. Fun, playful, and immediately recognizable retro tech aesthetic.
8
+
9
+ ## Background
10
+
11
+ - Color: Light Blue (#87CEEB) or Soft Lavender (#E6E6FA)
12
+ - Texture: Subtle pixel grid pattern, optional CRT scanline effect
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Light Blue | #87CEEB | Primary background |
19
+ | Alt Background | Soft Lavender | #E6E6FA | Secondary backgrounds |
20
+ | Primary Text | Dark Navy | #1A1A2E | Main elements |
21
+ | Accent 1 | Pixel Green | #00FF00 | Success, highlights |
22
+ | Accent 2 | Pixel Red | #FF0000 | Alerts, emphasis |
23
+ | Accent 3 | Pixel Yellow | #FFFF00 | Warnings, energy |
24
+ | Accent 4 | Pixel Cyan | #00FFFF | Info, tech elements |
25
+ | Accent 5 | Pixel Magenta | #FF00FF | Special elements |
26
+
27
+ ## Visual Elements
28
+
29
+ - All elements rendered with visible pixel structure
30
+ - Simple iconography: notepad, checkboxes, gears, rockets
31
+ - Text bubbles with pixel borders
32
+ - 8-bit decorations: stars, hearts, arrows
33
+ - Progress bars with chunky pixel segments
34
+ - Dithering patterns for color transitions
35
+ - Limited 16-32 color palette
36
+
37
+ ## Style Rules
38
+
39
+ ### Do
40
+
41
+ - Maintain consistent pixel grid throughout
42
+ - Use limited color palette (16-32 colors max)
43
+ - Create blocky, geometric shapes
44
+ - Add nostalgic gaming references
45
+ - Use dithering for color transitions
46
+
47
+ ### Don't
48
+
49
+ - Use smooth gradients or anti-aliasing
50
+ - Create photorealistic elements
51
+ - Use thin lines or fine details
52
+ - Add modern glossy effects
53
+ - Break the pixel grid alignment
54
+
55
+ ## Best For
56
+
57
+ Gaming articles, tech tutorials, nostalgic content, developer topics, retro-themed pieces, creative tech content
optional-skills/creative/baoyu-article-illustrator/references/styles/playful.md ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # playful
2
+
3
+ Fun, creative illustration style for casual and educational content
4
+
5
+ ## Design Aesthetic
6
+
7
+ Whimsical and entertaining visual approach that sparks joy. Pastel colors with bright pops of energy. Doodle-like quality that feels approachable and fun. Creates a sense of play and discovery. Encourages engagement through visual delight.
8
+
9
+ ## Background
10
+
11
+ - Color: Light Cream (#FFFBEB) or Soft White (#FFF)
12
+ - Texture: Subtle, playful pattern or clean
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Light Cream | #FFFBEB | Primary background |
19
+ | Primary | Pastel Pink | #FED7E2 | Soft warmth |
20
+ | Secondary | Mint | #C6F6D5 | Fresh energy |
21
+ | Tertiary | Lavender | #E9D8FD | Dreamy touch |
22
+ | Accent 1 | Sky Blue | #BEE3F8 | Calm brightness |
23
+ | Accent 2 | Bright Yellow | #FBBF24 | Energy pop |
24
+ | Accent 3 | Coral | #F6AD55 | Warm pop |
25
+ | Accent 4 | Turquoise | #38B2AC | Cool pop |
26
+ | Text | Soft Charcoal | #4A4A4A | Text elements |
27
+
28
+ ## Visual Elements
29
+
30
+ - Doodles and sketchy lines
31
+ - Star and sparkle decorations
32
+ - Swirls and curvy elements
33
+ - Cute character illustrations
34
+ - Speech bubbles and callouts
35
+ - Emoji-style icons
36
+ - Confetti and celebration marks
37
+ - Playful hand-lettering
38
+
39
+ ## Style Rules
40
+
41
+ ### Do
42
+
43
+ - Use varied pastel palette
44
+ - Add whimsical decorations
45
+ - Create friendly characters
46
+ - Include playful details
47
+ - Keep energy high and positive
48
+
49
+ ### Don't
50
+
51
+ - Use dark or moody colors
52
+ - Create serious compositions
53
+ - Add corporate elements
54
+ - Use rigid geometric shapes
55
+ - Make it feel professional
56
+
57
+ ## Best For
58
+
59
+ Tutorials and guides, beginner-friendly content, casual articles, fun topics, children's content, hobby-related posts, entertaining explanations
optional-skills/creative/baoyu-article-illustrator/references/styles/retro.md ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # retro
2
+
3
+ 80s/90s nostalgic aesthetic with vibrant colors and geometric patterns
4
+
5
+ ## Design Aesthetic
6
+
7
+ Nostalgic retro aesthetic inspired by 80s and 90s design trends. Vibrant neon colors, geometric patterns, and Memphis design influence. Energetic, fun, and unapologetically bold. Perfect for content that embraces nostalgia or playful energy.
8
+
9
+ ## Background
10
+
11
+ - Color: Deep Purple (#2D1B4E) or Dark Teal (#0F4C5C)
12
+ - Texture: Subtle grid patterns or geometric shapes
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Deep Purple | #2D1B4E | Primary background |
19
+ | Alt Background | Dark Teal | #0F4C5C | Alternative |
20
+ | Primary | Hot Pink | #FF1493 | Main accent |
21
+ | Secondary | Electric Cyan | #00FFFF | Supporting |
22
+ | Tertiary | Neon Yellow | #FFFF00 | Highlights |
23
+ | Accent 1 | Lime Green | #32CD32 | Energy |
24
+ | Accent 2 | Orange | #FF6B35 | Warmth |
25
+ | Text | White | #FFFFFF | Text elements |
26
+ | Grid | Light Purple | #9D8EC0 | Grid lines |
27
+
28
+ ## Visual Elements
29
+
30
+ - Geometric patterns (triangles, circles)
31
+ - Grid backgrounds and lines
32
+ - Neon glow effects
33
+ - Memphis design shapes
34
+ - Zigzag and wavy patterns
35
+ - Retro computer graphics
36
+ - Bold outline strokes
37
+ - Gradient sunsets
38
+
39
+ ## Style Rules
40
+
41
+ ### Do
42
+
43
+ - Use bold neon colors
44
+ - Create geometric patterns
45
+ - Add retro typography
46
+ - Include Memphis-style shapes
47
+ - Embrace maximalism
48
+
49
+ ### Don't
50
+
51
+ - Use muted or subtle colors
52
+ - Create minimal compositions
53
+ - Add modern flat design
54
+ - Make it look contemporary
55
+ - Use understated elements
56
+
57
+ ## Best For
58
+
59
+ Pop culture articles, gaming content, music and entertainment, nostalgia pieces, youth-focused content, creative industry, party and event content
optional-skills/creative/baoyu-article-illustrator/references/styles/scientific.md ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # scientific
2
+
3
+ Academic scientific illustration style for technical diagrams and processes
4
+
5
+ ## Design Aesthetic
6
+
7
+ Academic scientific illustration aesthetic for biological, chemical, and technical diagrams. Clean, precise diagrams with proper labeling and clear visual flow. Educational clarity with professional polish. Textbook quality illustrations.
8
+
9
+ ## Background
10
+
11
+ - Color: Off-White (#FAFAFA) or Light Blue-Gray (#F0F4F8)
12
+ - Texture: None or subtle paper grain
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Off-White | #FAFAFA | Primary background |
19
+ | Primary Text | Dark Slate | #1E293B | Labels, headers |
20
+ | Label Text | Medium Gray | #475569 | Annotations |
21
+ | Pathway 1 | Teal | #0D9488 | Primary pathway |
22
+ | Pathway 2 | Blue | #3B82F6 | Secondary pathway |
23
+ | Pathway 3 | Purple | #8B5CF6 | Tertiary pathway |
24
+ | Structure | Amber | #F59E0B | Membranes, structures |
25
+ | Alert | Red | #EF4444 | Key elements |
26
+ | Positive | Green | #22C55E | Products, outputs |
27
+
28
+ ## Visual Elements
29
+
30
+ - Precise labeled diagrams
31
+ - Flow arrows showing direction
32
+ - Modular components with colors
33
+ - Chemical formulas and notation
34
+ - Cross-section views
35
+ - Numbered step sequences
36
+ - Molecule and cell representations
37
+ - Process summary boxes
38
+
39
+ ## Style Rules
40
+
41
+ ### Do
42
+
43
+ - Use precise consistent lines
44
+ - Label all components clearly
45
+ - Show directional flow
46
+ - Include technical notation
47
+ - Create clear numbered sequences
48
+
49
+ ### Don't
50
+
51
+ - Use decorative elements
52
+ - Create imprecise diagrams
53
+ - Omit important labels
54
+ - Use inconsistent styling
55
+ - Add artistic flourishes
56
+
57
+ ## Best For
58
+
59
+ Biology articles, chemistry explanations, medical content, research summaries, academic writing, technical documentation, process explanations
optional-skills/creative/baoyu-article-illustrator/references/styles/screen-print.md ADDED
@@ -0,0 +1,70 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # screen-print
2
+
3
+ Bold poster art with limited colors, halftone textures, and symbolic storytelling
4
+
5
+ ## Design Aesthetic
6
+
7
+ Screen print / silkscreen aesthetic inspired by Mondo limited-edition posters and vintage concert prints. Flat color blocks, halftone dot patterns, bold silhouettes, and deliberate print imperfections. Conceptual and symbolic rather than literal — one iconic image tells the whole story. Perfect for opinion pieces, cultural commentary, and editorial content.
8
+
9
+ ## Background
10
+
11
+ - Color: Off-Black (#121212) or Warm Cream (#F5E6D0)
12
+ - Texture: Paper grain with subtle halftone dot overlay
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Off-Black | #121212 | Dark compositions |
19
+ | Background Alt | Warm Cream | #F5E6D0 | Light compositions |
20
+ | Primary | Burnt Orange | #E8751A | Main accent |
21
+ | Secondary | Deep Teal | #0A6E6E | Contrast accent |
22
+ | Tertiary | Crimson | #C0392B | Bold emphasis |
23
+ | Highlight | Amber | #F4A623 | Small accents |
24
+ | Text | Cream White | #FAF3E0 | On dark backgrounds |
25
+
26
+ **Duotone Pairs** (choose ONE pair for high-impact compositions):
27
+
28
+ | Pair | Color A | Color B | Feel |
29
+ |------|---------|---------|------|
30
+ | Orange + Teal | #E8751A | #0A6E6E | Cinematic, action |
31
+ | Red + Cream | #C0392B | #F5E6D0 | Bold, classic |
32
+ | Blue + Gold | #1A3A5C | #D4A843 | Prestigious, premium |
33
+ | Crimson + Navy | #DC143C | #0D1B2A | Dramatic, noir |
34
+
35
+ **Rule**: Use 2-5 colors maximum. Fewer colors = stronger impact.
36
+
37
+ ## Visual Elements
38
+
39
+ - Bold silhouettes and symbolic shapes
40
+ - Halftone dot patterns within color fills
41
+ - Slight color layer misregistration (print offset effect)
42
+ - Geometric framing (circles, arches, triangles)
43
+ - Figure-ground inversion (negative space forms secondary image)
44
+ - Stencil-cut edges, no outlines — shapes defined by color boundaries
45
+ - Typography integrated as design element, not overlay
46
+ - Vintage poster border treatments
47
+
48
+ ## Style Rules
49
+
50
+ ### Do
51
+
52
+ - Limit to 2-5 flat colors
53
+ - Use bold silhouettes over detailed rendering
54
+ - Let negative space tell part of the story
55
+ - Add halftone texture for authenticity
56
+ - Use geometric composition (centered, symmetrical)
57
+ - Reference vintage decades (60s/70s/80s) for era feel
58
+
59
+ ### Don't
60
+
61
+ - Use photorealistic rendering or gradients
62
+ - Add complex facial details (silhouettes preferred)
63
+ - Mix too many visual elements (one focal point)
64
+ - Use modern digital aesthetic
65
+ - Create busy or cluttered compositions
66
+ - Use more than 5 colors
67
+
68
+ ## Best For
69
+
70
+ Opinion/editorial articles, cultural commentary, philosophy and strategy, dramatic narratives, cinematic storytelling, music and entertainment, event announcements, bold branding content
optional-skills/creative/baoyu-article-illustrator/references/styles/sketch-notes.md ADDED
@@ -0,0 +1,56 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # sketch-notes
2
+
3
+ Soft hand-drawn illustration style with warm, educational feel
4
+
5
+ ## Design Aesthetic
6
+
7
+ Hand-drawn feel with soft, relaxed brush strokes. Fresh, refined style with minimalist editorial approach. Emphasis on precision, clarity and intelligent elegance while prioritizing warmth, approachability and friendliness.
8
+
9
+ ## Background
10
+
11
+ - Color: Warm Off-White (#FAF8F0)
12
+ - Texture: Subtle paper grain, warm tone
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Warm Off-White | #FAF8F0 | Primary background |
19
+ | Primary Text | Deep Charcoal | #2C3E50 | Main elements |
20
+ | Alt Text | Deep Brown | #4A4A4A | Secondary elements |
21
+ | Accent 1 | Soft Orange | #F4A261 | Highlights, emphasis |
22
+ | Accent 2 | Mustard Yellow | #E9C46A | Secondary highlights |
23
+ | Accent 3 | Sage Green | #87A96B | Nature, growth concepts |
24
+ | Accent 4 | Light Blue | #7EC8E3 | Tech, digital elements |
25
+ | Accent 5 | Red Brown | #A0522D | Earthy elements |
26
+
27
+ ## Visual Elements
28
+
29
+ - Connection lines with hand-drawn wavy feel
30
+ - Conceptual abstract icons illustrating ideas
31
+ - Color fills don't completely fill outlines (hand-painted feel)
32
+ - Simple geometric shapes with rounded corners
33
+ - Arrows and pointers with sketchy style
34
+ - Doodle decorations: stars, spirals, underlines
35
+
36
+ ## Style Rules
37
+
38
+ ### Do
39
+
40
+ - Keep layouts open and well-structured
41
+ - Emphasize information hierarchy
42
+ - Use hand-drawn quality for all elements
43
+ - Allow imperfection (slight wobbles add character)
44
+ - Layer elements with subtle overlaps
45
+
46
+ ### Don't
47
+
48
+ - Use perfect geometric shapes
49
+ - Create photorealistic elements
50
+ - Overcrowd with too many elements
51
+ - Use pure white backgrounds
52
+ - Make it look computer-generated
53
+
54
+ ## Best For
55
+
56
+ Educational content, knowledge sharing, technical explanations, tutorials, onboarding materials, friendly articles
optional-skills/creative/baoyu-article-illustrator/references/styles/sketch.md ADDED
@@ -0,0 +1,57 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # sketch
2
+
3
+ Raw, authentic notebook-style illustration for ideas and processes
4
+
5
+ ## Design Aesthetic
6
+
7
+ Hand-drawn sketch aesthetic that feels authentic and in-progress. Pencil-on-paper quality with intentional imperfection. Suggests thinking, brainstorming, and creative exploration. Raw and honest visual approach that invites collaboration.
8
+
9
+ ## Background
10
+
11
+ - Color: Off-White Paper (#F7FAFC) or Cream (#FAFAFA)
12
+ - Texture: Paper texture with visible grain
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Paper White | #F7FAFC | Primary background |
19
+ | Primary | Pencil Gray | #4A5568 | Main sketch lines |
20
+ | Secondary | Light Gray | #A0AEC0 | Shading, soft marks |
21
+ | Highlight Blue | Note Blue | #3182CE | Highlight color |
22
+ | Highlight Red | Mark Red | #E53E3E | Emphasis color |
23
+ | Highlight Yellow | Marker Yellow | #F6E05E | Highlighter effect |
24
+ | Text | Charcoal | #2D3748 | Text elements |
25
+
26
+ ## Visual Elements
27
+
28
+ - Rough sketch lines with natural variation
29
+ - Arrows and directional pointers
30
+ - Handwritten labels and notes
31
+ - Crossed-out marks and corrections
32
+ - Underlines and emphasis marks
33
+ - Simple diagram shapes
34
+ - Margin notes style
35
+ - Quick icon sketches
36
+
37
+ ## Style Rules
38
+
39
+ ### Do
40
+
41
+ - Use pencil-like line quality
42
+ - Include natural imperfections
43
+ - Add handwritten annotations
44
+ - Create diagram-style layouts
45
+ - Show thinking process
46
+
47
+ ### Don't
48
+
49
+ - Use perfect geometric shapes
50
+ - Add polished or refined elements
51
+ - Create colorful compositions
52
+ - Use digital effects
53
+ - Make it look finished
54
+
55
+ ## Best For
56
+
57
+ Ideas in progress, brainstorming articles, thought processes, concept exploration, draft-stage thinking, planning content, problem-solving pieces
optional-skills/creative/baoyu-article-illustrator/references/styles/vector-illustration.md ADDED
@@ -0,0 +1,57 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vector-illustration
2
+
3
+ Flat vector illustration style with clear black outlines and retro soft colors
4
+
5
+ ## Design Aesthetic
6
+
7
+ Flat vector illustration with no gradients or 3D effects. Clear, uniform-thickness black outlines on all elements. Geometric simplification reducing complex objects to basic shapes. Toy model aesthetic that's cute, playful, and approachable. Coloring book style with closed outlines.
8
+
9
+ ## Background
10
+
11
+ - Color: Cream Off-White (#F5F0E6)
12
+ - Texture: Subtle paper texture, warm nostalgic feel
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Cream Off-White | #F5F0E6 | Primary background |
19
+ | Outlines | Deep Charcoal | #2D2D2D | All element outlines |
20
+ | Primary | Coral Red | #E07A5F | Primary accent, warmth |
21
+ | Secondary | Mint Green | #81B29A | Nature, growth |
22
+ | Tertiary | Mustard Yellow | #F2CC8F | Highlights, energy |
23
+ | Accent 1 | Burnt Orange | #D4764A | Warm accents |
24
+ | Accent 2 | Rock Blue | #577590 | Cool balance |
25
+ | Text | Black | #1A1A1A | Text elements |
26
+
27
+ ## Visual Elements
28
+
29
+ - All objects have closed black outlines (coloring book style)
30
+ - Rounded line endings, avoid sharp corners
31
+ - Trees simplified to lollipop or triangle shapes
32
+ - Buildings as rectangular blocks with grid windows
33
+ - Depth through layering and overlap
34
+ - Decorative elements: sunbursts, pill-shaped clouds, dots, stars
35
+ - People as simple geometric figures
36
+
37
+ ## Style Rules
38
+
39
+ ### Do
40
+
41
+ - Maintain consistent outline thickness
42
+ - Use soft, vintage color palette
43
+ - Simplify objects to basic geometric shapes
44
+ - Create depth through layering
45
+ - Add playful decorative elements
46
+
47
+ ### Don't
48
+
49
+ - Use gradients or realistic shading
50
+ - Create photorealistic elements
51
+ - Use thin or varying line weights
52
+ - Include complex detailed illustrations
53
+ - Add textures inside shapes
54
+
55
+ ## Best For
56
+
57
+ Educational content, creative articles, children's content, brand showcases, explainer pieces, warm approachable topics
optional-skills/creative/baoyu-article-illustrator/references/styles/vintage.md ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # vintage
2
+
3
+ Nostalgic aged-paper aesthetic for historical and heritage content
4
+
5
+ ## Design Aesthetic
6
+
7
+ Nostalgic vintage aesthetic with aged paper textures and historical document styling. Explorer's journal and antique map quality. Rich warm tones with weathered textures. Evokes discovery, heritage, and timeless knowledge.
8
+
9
+ ## Background
10
+
11
+ - Color: Aged Parchment (#F5E6D3) or Sepia Cream (#FFF8DC)
12
+ - Texture: Heavy aged paper texture with subtle stains and worn edges
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Aged Parchment | #F5E6D3 | Primary background |
19
+ | Alt Background | Sepia Cream | #FFF8DC | Secondary areas |
20
+ | Primary Text | Dark Brown | #3D2914 | Main elements |
21
+ | Secondary | Medium Brown | #6B4423 | Supporting details |
22
+ | Accent 1 | Forest Green | #2D5A3D | Nature, maps |
23
+ | Accent 2 | Navy Blue | #1E3A5F | Ocean, lines |
24
+ | Accent 3 | Burgundy | #722F37 | Emphasis |
25
+ | Accent 4 | Gold | #C9A227 | Highlights |
26
+ | Ink | Sepia Black | #3D3D3D | Fine details |
27
+
28
+ ## Visual Elements
29
+
30
+ - Antique map styling with route lines
31
+ - Compass roses and navigation elements
32
+ - Specimen-style drawings
33
+ - Handwritten annotations
34
+ - Rope, leather, brass decorative motifs
35
+ - Vintage photograph frames
36
+ - Aged paper edge effects
37
+ - Historical document styling
38
+
39
+ ## Style Rules
40
+
41
+ ### Do
42
+
43
+ - Apply consistent aged texture
44
+ - Use period-appropriate styling
45
+ - Include map and journey elements
46
+ - Create layered compositions
47
+ - Maintain warm sepia tones
48
+
49
+ ### Don't
50
+
51
+ - Use modern digital styling
52
+ - Create crisp clean edges
53
+ - Use cold or bright colors
54
+ - Add contemporary elements
55
+ - Make it look new or fresh
56
+
57
+ ## Best For
58
+
59
+ Historical articles, travel and exploration, biography pieces, heritage stories, scientific discovery narratives, museum-style content, classic literature references
optional-skills/creative/baoyu-article-illustrator/references/styles/warm.md ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # warm
2
+
3
+ Friendly, approachable illustration style for human-centered content
4
+
5
+ ## Design Aesthetic
6
+
7
+ Warm and inviting visual approach that feels personal and approachable. Soft, friendly colors that evoke comfort and connection. Emphasizes human elements and emotional resonance. Creates an atmosphere of trust and openness.
8
+
9
+ ## Background
10
+
11
+ - Color: Cream (#FFFAF0) or Soft Peach (#FED7AA)
12
+ - Texture: Soft paper texture with warm undertones
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Cream | #FFFAF0 | Primary background |
19
+ | Alt Background | Soft Peach | #FED7AA | Accent sections |
20
+ | Primary | Warm Orange | #ED8936 | Main accent color |
21
+ | Secondary | Golden Yellow | #F6AD55 | Supporting warmth |
22
+ | Tertiary | Terracotta | #C05621 | Earthy depth |
23
+ | Accent | Deep Brown | #744210 | Grounding elements |
24
+ | Alt Accent | Soft Red | #E53E3E | Emotional touches |
25
+ | Text | Warm Charcoal | #4A4A4A | Text elements |
26
+
27
+ ## Visual Elements
28
+
29
+ - Rounded shapes and soft corners
30
+ - Friendly character illustrations
31
+ - Sun rays and warm light motifs
32
+ - Heart symbols and care icons
33
+ - Cozy lighting effects
34
+ - Gentle gradients with warmth
35
+ - Soft shadows without harsh edges
36
+ - Hand-drawn quality touches
37
+
38
+ ## Style Rules
39
+
40
+ ### Do
41
+
42
+ - Use warm, inviting colors
43
+ - Create rounded, friendly shapes
44
+ - Include human-centered elements
45
+ - Evoke feelings of comfort
46
+ - Maintain soft, gentle contrasts
47
+
48
+ ### Don't
49
+
50
+ - Use cold or stark colors
51
+ - Create sharp, aggressive shapes
52
+ - Add technical or clinical elements
53
+ - Use dark, moody backgrounds
54
+ - Create sterile compositions
55
+
56
+ ## Best For
57
+
58
+ Personal growth articles, lifestyle content, education, human interest stories, wellness topics, relationship advice, self-help content, community building
optional-skills/creative/baoyu-article-illustrator/references/styles/watercolor.md ADDED
@@ -0,0 +1,58 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # watercolor
2
+
3
+ Soft, artistic watercolor illustration style with natural warmth
4
+
5
+ ## Design Aesthetic
6
+
7
+ Gentle watercolor aesthetic with visible brush strokes and natural color bleeding. Hand-painted feel with soft edges and organic shapes. Warm, approachable, and artistically refined. Combines artistic expression with clear visual communication.
8
+
9
+ ## Background
10
+
11
+ - Color: Warm Off-White (#FAF8F0) or Soft Cream (#FFF9E6)
12
+ - Texture: Subtle watercolor paper texture with visible grain
13
+
14
+ ## Color Palette
15
+
16
+ | Role | Color | Hex | Usage |
17
+ |------|-------|-----|-------|
18
+ | Background | Warm Off-White | #FAF8F0 | Primary background |
19
+ | Primary | Soft Coral | #F4A261 | Primary warmth |
20
+ | Secondary | Dusty Rose | #E8A0A0 | Secondary warmth |
21
+ | Tertiary | Sage Green | #87A96B | Nature, growth |
22
+ | Accent 1 | Sky Blue | #7EC8E3 | Water, calm |
23
+ | Accent 2 | Soft Lavender | #C5B4E3 | Accent, creativity |
24
+ | Wash | Pale Yellow | #FFF3C4 | Background washes |
25
+ | Text | Warm Charcoal | #3D3D3D | Text elements |
26
+
27
+ ## Visual Elements
28
+
29
+ - Watercolor washes as backgrounds
30
+ - Illustrated elements with visible brush strokes
31
+ - Natural elements: leaves, flowers, bubbles
32
+ - Color bleeds and soft edges
33
+ - Hand-drawn arrows and lines
34
+ - Layered wash effects
35
+ - Soft gradients through water
36
+ - Expressive character illustrations
37
+
38
+ ## Style Rules
39
+
40
+ ### Do
41
+
42
+ - Allow color to bleed beyond edges
43
+ - Use visible brush stroke textures
44
+ - Create soft, organic shapes
45
+ - Include hand-drawn quality
46
+ - Maintain warm color palette
47
+
48
+ ### Don't
49
+
50
+ - Use sharp geometric shapes
51
+ - Create hard digital edges
52
+ - Use cold or stark colors
53
+ - Add photographic elements
54
+ - Create overly precise illustrations
55
+
56
+ ## Best For
57
+
58
+ Lifestyle articles, wellness content, travel pieces, food and cooking, personal stories, creative topics, artistic portfolios, warm educational content
optional-skills/creative/baoyu-article-illustrator/references/usage.md ADDED
@@ -0,0 +1,50 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Usage
2
+
3
+ This skill is triggered by natural language in Hermes — no slash command or CLI flags.
4
+
5
+ ## Trigger Phrases
6
+
7
+ - "Illustrate this article" / "为文章配图"
8
+ - "Add images to this post"
9
+ - "Generate illustrations for [path/to/article.md]"
10
+
11
+ ## Input Modes
12
+
13
+ | Mode | How to trigger | Output Directory |
14
+ |------|----------------|------------------|
15
+ | File path | Mention an article path (`path/to/article.md`) | `{article-dir}/imgs/` (default) |
16
+ | Pasted content | Paste the article text in the conversation | `illustrations/{topic-slug}/` (cwd) |
17
+
18
+ ## Specifying Options in Natural Language
19
+
20
+ The user can specify any of the following directly in their request. If not specified, the skill asks via the `clarify` tool.
21
+
22
+ | Option | Example phrasing |
23
+ |--------|------------------|
24
+ | Type | "as an infographic", "as a flowchart", "as scenes" |
25
+ | Style | "in blueprint style", "use notion style", "用 watercolor 风格" |
26
+ | Preset | "use the tech-explainer preset", "storytelling preset" |
27
+ | Palette | "with macaron palette", "warm colors only" |
28
+ | Density | "minimal images", "one per section", "rich illustrations" |
29
+ | Language | "images in English" / "图片文字用中文" |
30
+ | Output | "save images alongside the article" / "put them in `illustrations/`" |
31
+
32
+ ## Examples
33
+
34
+ **Technical article with data**:
35
+ > 帮我为 api-design.md 配图,用 infographic + blueprint 风格
36
+
37
+ **Preset shortcut**:
38
+ > Illustrate api-design.md with the tech-explainer preset
39
+
40
+ **Personal story**:
41
+ > Illustrate journey.md using the storytelling preset
42
+
43
+ **Tutorial with rich images**:
44
+ > Generate illustrations for how-to-deploy.md — tutorial preset, rich density
45
+
46
+ **Opinion article**:
47
+ > Illustrate opinion.md with the opinion-piece preset
48
+
49
+ **Preset with style override**:
50
+ > Use the tech-explainer preset for article.md but swap the style for notion
optional-skills/creative/baoyu-article-illustrator/references/workflow.md ADDED
@@ -0,0 +1,332 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Detailed Workflow Procedures
2
+
3
+ ## Step 1: Detect Reference Images
4
+
5
+ If the user provides reference images (local path or URL), the goal is to produce **textual descriptions** that can be embedded in prompts — `image_generate` doesn't accept reference-image inputs, and Hermes' text file tools can't read or write binaries.
6
+
7
+ **Tool rules**:
8
+
9
+ | Task | Tool | Notes |
10
+ |------|------|-------|
11
+ | Analyze a reference image | `vision_analyze` | Accepts URL or local path. Ask for style, palette, composition, subject. |
12
+ | Write the text description | `write_file` | Sidecar `.md` files only — never try to `write_file` a PNG/JPG. |
13
+ | (Optional) Keep a local copy of the binary | `terminal` | `cp "$src" "{output-dir}/references/NN-ref-{slug}.{ext}"` — purely for the record; the skill itself doesn't read the binary. |
14
+
15
+ | Input Type | Action |
16
+ |------------|--------|
17
+ | Image file path provided | `vision_analyze` → write sidecar `.md`. Optional `terminal cp` for a local record. |
18
+ | Image URL provided | `vision_analyze` with the URL → write sidecar `.md`. |
19
+ | Image in conversation (no path, no URL) | Ask via `clarify` for a path or URL, or for a verbal description. |
20
+ | User can't provide either | Extract style/palette verbally from the user → write `references/extracted-style.md`. Do NOT add `references:` to prompt frontmatter. |
21
+
22
+ **Procedure** (when a path/URL is available):
23
+
24
+ 1. Call `vision_analyze(image_url=..., question="Describe the style, color palette (with hex approximations), composition, and subject so this can be used as a style/palette reference for another illustration.")`.
25
+ 2. Write `{output-dir}/references/NN-ref-{slug}.md` via `write_file` with the description.
26
+ 3. (Optional) Run `terminal` with `cp` (or `curl -sSL -o ...` for URLs) to keep a local binary copy. Not required by the skill.
27
+ 4. Mark the reference in the outline with usage `direct` / `style` / `palette`. In Step 5.1 the description gets appended to the prompt body.
28
+
29
+ **Sidecar File Format**:
30
+ ```yaml
31
+ ---
32
+ ref_id: NN
33
+ source: "<original path or URL>"
34
+ local_copy: "NN-ref-{slug}.png" # omit if no copy made
35
+ usage_hint: style # direct | style | palette
36
+ ---
37
+ [vision_analyze description — colors, style, composition, subject]
38
+ ```
39
+
40
+ ---
41
+
42
+ ## Step 2: Analyze
43
+
44
+ ### 2.1 Determine Output Directory
45
+
46
+ | Input | Output Directory | Source-save path |
47
+ |-------|------------------|------------------|
48
+ | Article file path | `{article-dir}/imgs/` (default) | — (read article via `read_file`) |
49
+ | Pasted content | `illustrations/{topic-slug}/` (cwd) | `source-{slug}.{ext}` (save via `write_file`) |
50
+
51
+ If the user explicitly asked for a different layout (e.g., images in the article's folder, or an `illustrations/` subdirectory), honor that.
52
+
53
+ ### 2.2 Analyze Content
54
+
55
+ | Analysis | Description |
56
+ |----------|-------------|
57
+ | Content type | Technical / Tutorial / Methodology / Narrative |
58
+ | Illustration purpose | information / visualization / imagination |
59
+ | Core arguments | 2-5 main points to visualize |
60
+ | Visual opportunities | Positions where illustrations add value |
61
+ | Recommended type | Based on content signals and purpose |
62
+ | Recommended density | Based on length and complexity |
63
+
64
+ Save analysis to `{output-dir}/analysis.md` using `write_file`.
65
+
66
+ ### 2.3 Extract Core Arguments
67
+
68
+ - Main thesis
69
+ - Key concepts reader needs
70
+ - Comparisons/contrasts
71
+ - Framework/model proposed
72
+
73
+ **CRITICAL**: If the article uses metaphors (e.g., "电锯切西瓜"), do NOT illustrate literally. Visualize the **underlying concept**.
74
+
75
+ ### 2.4 Identify Positions
76
+
77
+ **Illustrate**:
78
+ - Core arguments (REQUIRED)
79
+ - Abstract concepts
80
+ - Data comparisons
81
+ - Processes, workflows
82
+
83
+ **Do NOT Illustrate**:
84
+ - Metaphors literally
85
+ - Decorative scenes
86
+ - Generic illustrations
87
+
88
+ ### 2.5 Plan Reference Image Usage (if analyzed in Step 1)
89
+
90
+ For each reference image (use the `vision_analyze` description from Step 1):
91
+
92
+ | Analysis | Description |
93
+ |----------|-------------|
94
+ | Visual characteristics | Style, colors, composition |
95
+ | Content/subject | What the reference depicts |
96
+ | Suitable positions | Which sections match this reference |
97
+ | Style match | Which illustration types/styles align |
98
+ | Usage recommendation | `direct` / `style` / `palette` |
99
+
100
+ | Usage | When to Use | How it's applied in Step 5.1 |
101
+ |-------|-------------|------------------------------|
102
+ | `direct` | Reference matches desired output closely | Paste the description (composition + subject + style + palette) into the prompt body |
103
+ | `style` | Extract visual style characteristics only | Append style traits to prompt body |
104
+ | `palette` | Extract color scheme only | Append extracted hex colors to prompt body |
105
+
106
+ Note: `image_generate` does not accept reference-image inputs under any usage type. Everything is mediated through the `vision_analyze` description.
107
+
108
+ ---
109
+
110
+ ## Step 3: Confirm Settings
111
+
112
+ Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question the user already answered in their request.
113
+
114
+ ### Q1: Preset or Type (highest priority)
115
+
116
+ Based on Step 2 content analysis, recommend a preset first (sets both type & style). Look up [style-presets.md](style-presets.md) "Content Type → Preset Recommendations" table.
117
+
118
+ - [Recommended preset] — [brief: type + style + why]
119
+ - [Alternative preset] — [brief]
120
+ - Or choose type manually: infographic / scene / flowchart / comparison / framework / timeline / mixed
121
+
122
+ **If user picks a preset → skip Q3** (type & style both resolved).
123
+ **If user picks a type → Q3 is required.**
124
+
125
+ ### Q2: Density
126
+
127
+ - minimal (1-2) — Core concepts only
128
+ - balanced (3-5) — Major sections
129
+ - per-section — At least 1 per section/chapter (Recommended)
130
+ - rich (6+) — Comprehensive coverage
131
+
132
+ ### Q3: Style (skip if preset chosen in Q1)
133
+
134
+ Present Core Styles first:
135
+
136
+ - [Best compatible core style] (Recommended)
137
+ - [Other compatible core style 1]
138
+ - [Other compatible core style 2]
139
+ - Other (see full Style Gallery)
140
+
141
+ **Core Styles** (simplified selection):
142
+
143
+ | Core Style | Maps To | Best For |
144
+ |------------|---------|----------|
145
+ | `minimal-flat` | notion | General, knowledge sharing, SaaS |
146
+ | `sci-fi` | blueprint | AI, frontier tech, system design |
147
+ | `hand-drawn` | sketch/warm | Relaxed, reflective, casual |
148
+ | `editorial` | editorial | Processes, data, journalism |
149
+ | `scene` | warm/watercolor | Narratives, emotional, lifestyle |
150
+ | `poster` | screen-print | Opinion, editorial, cultural, cinematic |
151
+
152
+ Style selection based on Type × Style compatibility matrix ([styles.md](styles.md)).
153
+ **In Step 5**, read `styles/<style>.md` for visual elements and rendering rules.
154
+
155
+ ### Q4: Palette (optional)
156
+
157
+ If the preset did not specify a palette, offer:
158
+
159
+ - Default (use style's built-in colors) (Recommended)
160
+ - `macaron` — soft pastel blocks on warm cream
161
+ - `warm` — warm earth tones, no cool colors
162
+ - `neon` — vibrant neon on dark backgrounds
163
+
164
+ **Skip if**: preset already resolved palette, or user specified a palette in the request.
165
+
166
+ See Palette Gallery in [styles.md](styles.md#palette-gallery) and full specs in `palettes/<palette>.md`.
167
+
168
+ ### Q5: Image Text Language (only when ambiguous)
169
+
170
+ If the article language is different from the user's conversational language, ask which to use:
171
+ - Article language (match article content) (Recommended)
172
+ - User's conversational language
173
+
174
+ **Skip if**: languages match, or the user already specified in the request.
175
+
176
+ ### Display Reference Usage (if references saved in Step 1)
177
+
178
+ When presenting the outline preview to the user, show reference assignments:
179
+
180
+ ```
181
+ Reference Images:
182
+ | Ref | Filename | Recommended Usage |
183
+ |-----|----------|-------------------|
184
+ | 01 | 01-ref-diagram.png | direct → Illustration 1, 3 |
185
+ | 02 | 02-ref-chart.png | palette → Illustration 2 |
186
+ ```
187
+
188
+ ---
189
+
190
+ ## Step 4: Generate Outline
191
+
192
+ Save as `{output-dir}/outline.md` using `write_file`:
193
+
194
+ ```yaml
195
+ ---
196
+ type: infographic
197
+ density: balanced
198
+ style: blueprint
199
+ image_count: 4
200
+ references: # Only if references provided
201
+ - ref_id: 01
202
+ filename: 01-ref-diagram.png
203
+ description: "Technical diagram showing system architecture"
204
+ - ref_id: 02
205
+ filename: 02-ref-chart.png
206
+ description: "Color chart with brand palette"
207
+ ---
208
+
209
+ ## Illustration 1
210
+
211
+ **Position**: [section] / [paragraph]
212
+ **Purpose**: [why this helps]
213
+ **Visual Content**: [what to show]
214
+ **Type Application**: [how type applies]
215
+ **References**: [01] # Optional: list ref_ids used
216
+ **Reference Usage**: direct # direct | style | palette
217
+ **Filename**: 01-infographic-concept-name.png
218
+
219
+ ## Illustration 2
220
+ ...
221
+ ```
222
+
223
+ **Backup rule**: If `outline.md` exists, rename to `outline-backup-YYYYMMDD-HHMMSS.md` before writing.
224
+
225
+ **Requirements**:
226
+ - Each position justified by content needs
227
+ - Type applied consistently
228
+ - Style reflected in descriptions
229
+ - Count matches density
230
+ - References assigned based on Step 2.5 analysis
231
+
232
+ ---
233
+
234
+ ## Step 5: Generate Prompts
235
+
236
+ **BLOCKING**: Every illustration must have a saved prompt file before any image is generated.
237
+
238
+ For each illustration in the outline:
239
+
240
+ 1. **Create prompt file**: `{output-dir}/prompts/NN-{type}-{slug}.md` via `write_file`
241
+ 2. **Include YAML frontmatter**:
242
+ ```yaml
243
+ ---
244
+ illustration_id: 01
245
+ type: infographic
246
+ style: custom-flat-vector
247
+ ---
248
+ ```
249
+ 3. **Load style specs**: Read `styles/<style>.md` (via `read_file`) for visual elements, style rules, and rendering instructions
250
+ 4. **Load palette specs** (if palette specified): Read `palettes/<palette>.md` for colors and background. Palette colors **replace** the style's default Color Palette. If no palette specified, use the style's built-in colors.
251
+ 5. **Follow type-specific template** from [prompt-construction.md](prompt-construction.md), using rendering from style + colors from palette (or style default)
252
+ 6. **Prompt quality requirements** (all REQUIRED):
253
+ - `Layout`: Describe overall composition (grid / radial / hierarchical / left-right / top-down)
254
+ - `ZONES`: Describe each visual area with specific content, not vague descriptions
255
+ - `LABELS`: Use **actual numbers, terms, metrics, quotes from the article** — NOT generic placeholders
256
+ - `COLORS`: Specify hex codes from palette (or style default) with semantic meaning
257
+ - `STYLE`: Describe line treatment, texture, mood, character rendering per style rules
258
+ - `ASPECT`: Specify ratio (e.g., `16:9`)
259
+ 7. **Apply defaults**: composition requirements, character rendering, text guidelines
260
+ 8. **Backup rule**: If a prompt file exists, rename to `prompts/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.md`
261
+
262
+ **CRITICAL - References in Frontmatter**:
263
+ - Only add `references` field if a sidecar `.md` description exists in `{output-dir}/references/`
264
+ - If style/palette was extracted verbally (no description file), append info to prompt BODY only
265
+ - Before writing frontmatter, confirm the sidecar exists (try `read_file` on the `.md`)
266
+
267
+ ### 5.1 Process References (if analyzed in Step 1)
268
+
269
+ Read the `vision_analyze` description from the sidecar `references/NN-ref-{slug}.md` (via `read_file`) and embed it in the prompt body. `image_generate` never receives the binary.
270
+
271
+ | Usage | Action |
272
+ |-------|--------|
273
+ | `direct` | Paste the full reference description (composition, subject, style, palette) into the prompt body |
274
+ | `style` | Append only the style traits: "Style: clean lines, gradient backgrounds..." |
275
+ | `palette` | Append only the hex colors: "Colors: #E8756D coral, #7ECFC0 mint..." |
276
+
277
+ ---
278
+
279
+ ## Step 6: Generate Images
280
+
281
+ `image_generate` returns a JSON blob with a URL (`{"success": true, "image": "<url>"}`). It does NOT save a local file, does NOT accept an output path, and does NOT let the agent pick a backend/model. Treat the URL as a temporary artifact and download it explicitly.
282
+
283
+ For each prompt file:
284
+
285
+ 1. Read the prompt file (via `read_file`) and extract the assembled prompt
286
+ 2. Map the prompt's `ASPECT` to `image_generate`'s enum: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect.
287
+ 3. Call `image_generate(prompt=<assembled>, aspect_ratio=<enum>)` and extract the `image` URL from the returned JSON.
288
+ 4. **Backup rule**: If `{output-dir}/NN-{type}-{slug}.png` already exists, rename it via `terminal` (`mv "{output-dir}/NN-{type}-{slug}.png" "{output-dir}/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.png"`) before writing.
289
+ 5. Download the URL via `terminal`:
290
+ ```bash
291
+ curl -sSL -o "{output-dir}/NN-{type}-{slug}.png" "{image_url}"
292
+ ```
293
+ If `curl` is unavailable, fall back to `wget -qO "{output-dir}/NN-{type}-{slug}.png" "{image_url}"`.
294
+ 6. Verify the file exists and has non-zero size (`terminal`: `test -s "{path}" && echo ok`).
295
+ 7. On generation failure, retry `image_generate` once. On download failure, retry `curl` once with a longer timeout. Then log and continue.
296
+ 8. After each generation, report "Generated X/N".
297
+
298
+ ---
299
+
300
+ ## Step 7: Finalize
301
+
302
+ ### 7.1 Update Article
303
+
304
+ Insert after the corresponding paragraph, using the path relative to the article file:
305
+
306
+ | Input | Insert Path |
307
+ |-------|-------------|
308
+ | Article file path (default `imgs-subdir`) | `![description](imgs/NN-{type}-{slug}.png)` |
309
+ | Article file path (images alongside) | `![description](NN-{type}-{slug}.png)` |
310
+ | Article file path (`illustrations/` subdirectory) | `![description](illustrations/NN-{type}-{slug}.png)` |
311
+ | Pasted content | `![description](illustrations/{topic-slug}/NN-{type}-{slug}.png)` (relative to cwd) |
312
+
313
+ Alt text: concise description in the article's language.
314
+
315
+ ### 7.2 Output Summary
316
+
317
+ ```
318
+ Article Illustration Complete!
319
+
320
+ Article: [path]
321
+ Type: [type] | Density: [level] | Style: [style]
322
+ Location: [directory]
323
+ Images: X/N generated
324
+
325
+ Positions:
326
+ - 01-xxx.png → After "[Section]"
327
+ - 02-yyy.png → After "[Section]"
328
+
329
+ [If failures]
330
+ Failed:
331
+ - NN-zzz.png: [reason]
332
+ ```