aicodewith-image-generation-skill 1.0.0

package/bin/install.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+const sourceSkillDir = path.join(packageRoot, "skill");
+const targetSkillDir = path.join(
+  os.homedir(),
+  ".codex",
+  "skills",
+  "aicodewith-image-generation",
+);
+const codexEnvPath = path.join(os.homedir(), ".codex", ".env");
+
+function installSkill() {
+  if (!fs.existsSync(path.join(sourceSkillDir, "SKILL.md"))) {
+    throw new Error(`Skill source not found: ${sourceSkillDir}`);
+  }
+
+  fs.rmSync(targetSkillDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(targetSkillDir), { recursive: true });
+  fs.cpSync(sourceSkillDir, targetSkillDir, { recursive: true });
+}
+
+function upsertEnvValue(filePath, key, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const nextLine = `${key}=${value}`;
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, `${nextLine}\n`, { mode: 0o600 });
+    return;
+  }
+
+  const existing = fs.readFileSync(filePath, "utf8");
+  const lines = existing.split(/\r?\n/);
+  let replaced = false;
+  const updated = lines.map((line) => {
+    if (line.startsWith(`${key}=`)) {
+      replaced = true;
+      return nextLine;
+    }
+    return line;
+  });
+
+  if (!replaced) {
+    if (updated.length > 0 && updated[updated.length - 1] === "") {
+      updated[updated.length - 1] = nextLine;
+      updated.push("");
+    } else {
+      updated.push(nextLine, "");
+    }
+  }
+
+  fs.writeFileSync(filePath, updated.join("\n"), { mode: 0o600 });
+  fs.chmodSync(filePath, 0o600);
+}
+
+async function configureKey() {
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("请输入 AICodeWith API Key: ");
+    const apiKey = answer.trim();
+    if (!apiKey) {
+      console.log("未配置 API key。之后可重新运行安装命令进行配置。");
+      return false;
+    }
+
+    upsertEnvValue(codexEnvPath, "AICODEWITH_API_KEY", apiKey);
+    return true;
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  installSkill();
+  const configured = await configureKey();
+
+  console.log("");
+  console.log("AICodeWith image generation skill installed.");
+  console.log(`Skill: ${targetSkillDir}`);
+  if (configured) {
+    console.log(`API key saved to: ${codexEnvPath}`);
+  }
+  console.log("请重启 Codex，然后直接提出生图需求。");
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "aicodewith-image-generation-skill",
+  "version": "1.0.0",
+  "description": "Installer for the AICodeWith image generation Codex skill.",
+  "type": "module",
+  "bin": {
+    "aicodewith-image-generation-skill": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skill"
+  ],
+  "license": "UNLICENSED",
+  "private": false
+}

package/skill/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: aicodewith-image-generation
+description: Mandatory skill for ALL image-generation related requests. Always use this skill whenever the user asks to 生图, 生成图片, 画图, 做图, 出图, 海报, logo, icon, illustration, poster, product shot, edit an image, image-to-image, reference image editing, or any task whose deliverable is a generated/edited image. Use AICodeWith image generation API to create images, edit images from reference URLs, poll async image tasks, and return generated image URLs. Do not use generic image generation tools or answer with only prompts unless this skill/API is unavailable or the user explicitly asks only for a prompt.
+---
+
+# AICodeWith Image Generation
+
+This is the mandatory workflow for any image-generation or image-editing task. If the user asks for 生图/生成图片/画图/做图/出图/海报/logo/icon/illustration/poster/product shot/image editing, load and follow this skill before using any image tool. Prefer the AICodeWith API path below; only fall back to a generic prompt or another image provider if this API is unavailable, lacks credentials, or the user explicitly requests a different provider/prompt-only output.
+
+Use this skill whenever the user wants image generation through `https://api.aicodewith.com`, including text-to-image and image-to-image with reference URLs.
+
+## Credentials
+
+- API key is stored in environment variable `AICODEWITH_API_KEY`.
+- Do not print, reveal, or write the raw key in responses, logs, or generated files.
+- If `AICODEWITH_API_KEY` is missing from the subprocess environment, check these `.env` files in order and load only the value needed for the request:
+  1. `~/.codex/.env`
+  2. `~/.aicodewith/.env`
+- Never echo the key value. If it is missing from all locations, tell the user to run `npx aicodewith-image-generation-skill` and configure the key before using this skill.
+
+## API summary
+
+Base URL: `https://api.aicodewith.com`
+
+Create task:
+
+```http
+POST /v1/images/generations
+Authorization: Bearer $AICODEWITH_API_KEY
+Content-Type: application/json
+```
+
+Query task:
+
+```http
+GET /v1/tasks/{task_id}
+Authorization: Bearer $AICODEWITH_API_KEY
+```
+
+Completion result images are in `result_data[].url`.
+
+## Supported request fields
+
+- `model`: required. Prefer `gpt-image-2` unless user explicitly asks for `gpt-image-2-beta`.
+- `prompt`: required, non-empty.
+- `size`: optional. Recommended values: `auto`, `1:1`, `2:1`, `1:2`, `3:1`, `1:3`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `21:9`, `9:21`.
+- `resolution`: optional. `1K`, `2K`, `4K`; only for `gpt-image-2` when `size` is a ratio.
+- `n`: optional. `1-10`; only `gpt-image-2` supports multiple images. `gpt-image-2-beta` must use `n=1`.
+- `quality`: optional. `low`, `medium`, `high`; only for `gpt-image-2`.
+- `image_urls`: optional list of public reference image URLs. Use for image-to-image/reference editing/outpainting.
+- `background`: optional; use `auto` by default.
+
+## Interaction rules — mandatory confirmation gate
+
+Before creating any image-generation task, the assistant MUST get explicit user confirmation for these fields, even if the user's message already implies some of them:
+
+- 模型 / `model`
+- 比例 / `size`
+- 数量 / `n`
+- 质量 / `quality`
+- 分辨率 / `resolution`
+
+The assistant may propose values, but must not start the API request until the user confirms the full option set.
+
+Required confirmation format:
+
+```text
+请确认本次生图参数：
+- 模型：...
+- 比例：...
+- 数量：...
+- 质量：...
+- 分辨率：...
+
+确认后我再开始生成。
+```
+
+Model-specific rules:
+
+1. Always ask/confirm the model first or include it in the parameter confirmation:
+   - `gpt-image-2`
+   - `gpt-image-2-beta`
+2. If using `gpt-image-2`, the confirmation must include actual selectable values for:
+   - quality: `low`, `medium`, `high`
+   - size/aspect ratio: `auto`, `1:1`, `16:9`, `9:16`, etc.
+   - resolution: `1K`, `2K`, `4K` when size is a ratio; use `不适用（auto 比例）` when size is `auto`
+   - image count `n`: `1-10`
+3. If using `gpt-image-2-beta`, the confirmation must still show all five fields, but mark unsupported fields as fixed/not applicable:
+   - 模型：`gpt-image-2-beta`
+   - 比例：user-selected or proposed size
+   - 数量：`1（beta 固定）`
+   - 质量：`不适用（beta 不支持）`
+   - 分辨率：`不适用（beta 不支持）`
+4. If the user's prompt is missing or too vague, ask for the image prompt before or together with the parameter confirmation.
+5. Do not silently apply defaults. Even when the user says “默认 / 随便 / 你决定”, propose the default values in the five-field confirmation and wait for the user to confirm.
+6. Only proceed to API creation after the user clearly confirms, e.g. “确认”, “可以”, “就按这个”, “开始生成”.
+
+## Defaults
+
+Defaults are suggestions only. They are never permission to skip confirmation.
+
+- `model`: `gpt-image-2`
+- `size`: `1:1`
+- `resolution`: `1K`
+- `n`: `1`
+- `quality`: `medium`
+- `background`: `auto`
+
+For quick/cheap drafts, suggest `quality: low`.
+For high quality/final artwork, suggest `quality: high`.
+
+## Workflow
+
+1. Parse the user's generation request into API parameters.
+1b. **Reference image analysis** — when the user provides a reference image (local file, URL, or Telegram image cache path) and asks to create a derivative visual asset, analyze the reference FIRST before proceeding to parameter confirmation:
+   - Extract dominant colors, color distribution, and palette
+   - Assess composition: symmetry, visual weight distribution (top/bottom/left/right density)
+   - Identify edge density patterns and shape distribution
+   - Summarize findings and discuss design direction with the user
+   - Only when aligned, continue to parameter confirmation in step 2
+   - **Fallback**: when `vision_analyze` is unavailable (missing vision provider), use the programmatic Pillow+NumPy approach in `references/programmatic-image-analysis.md` to extract color, composition, and shape data from the image file directly.
+2. Before creating the task, run the interaction rules above and collect missing choices.
+3. If reference images are provided as URLs, put up to 16 URLs in `image_urls`.
+4. If the user attaches or references a local image file, first make sure it is available as a public URL before using this external API. The API expects public `image_urls`, not local file paths.
+5. Normalize model-specific fields:
+   - For `gpt-image-2-beta`: set `n=1`; omit `quality` and `resolution`.
+   - For `gpt-image-2`: include `quality`; include `resolution` only when `size` is a ratio, not `auto`.
+6. Create the task with `POST /v1/images/generations`.
+7. Read the returned `id` as `task_id`. If no `id` exists, treat task creation as failed and report the raw non-secret error details.
+8. Poll `GET /v1/tasks/{task_id}` every 3-5 seconds.
+   - If polling hits a transient network/TLS timeout, do not assume the task failed. Retry the task-status query later using the same `task_id`.
+   - If a 5-minute script/tool timeout kills the polling loop, make one separate lightweight status query for the same `task_id` before reporting timeout; tasks may complete after the polling process died.
+9. Stop polling when:
+   - `status == completed`: return every `result_data[].url`.
+   - `status == failed`: report the error code/message and whether retry is reasonable.
+   - 5 minutes elapsed with follow-up status still not completed: report timeout and include the `task_id` so the user can ask to continue checking.
+10. In the final response, include:
+   - task id
+   - status
+   - generated image URLs
+   - selected model/options
+
+## Python helper pattern
+
+Use `terminal` or `execute_code` to run an actual request. Example structure:
+
+```python
+import os, time, requests
+
+api_key = os.environ["AICODEWITH_API_KEY"]
+base_url = "https://api.aicodewith.com"
+headers = {"Authorization": f"Bearer {api_key}"}
+
+body = {
+    "model": "gpt-image-2",
+    "prompt": prompt,
+    "size": size,
+    "resolution": resolution,
+    "n": n,
+    "quality": quality,
+    "background": "auto",
+}
+if image_urls:
+    body["image_urls"] = image_urls[:16]
+
+resp = requests.post(
+    f"{base_url}/v1/images/generations",
+    headers={**headers, "Content-Type": "application/json"},
+    json=body,
+    timeout=60,
+)
+resp.raise_for_status()
+task_id = resp.json()["id"]
+
+start = time.time()
+while True:
+    result = requests.get(f"{base_url}/v1/tasks/{task_id}", headers=headers, timeout=60).json()
+    if result.get("status") == "completed":
+        urls = [item.get("url") for item in result.get("result_data", []) if item.get("url")]
+        break
+    if result.get("status") == "failed":
+        raise RuntimeError(result.get("error"))
+    if time.time() - start > 300:
+        raise TimeoutError(task_id)
+    time.sleep(3)
+```
+
+## Error handling
+
+Transient network errors can happen on both create and poll requests. If task creation fails with a transport/TLS error (for example `SSLEOFError`, timeout, reset, or temporary connection failure) and no task id was returned, retry the same create request once before reporting failure. If a task id was already returned, never create a duplicate task just because polling failed; continue querying the existing task id.
+
+Common HTTP status meanings:
+
+- `400`: parameter error, unsupported size, prompt too long, invalid image.
+- `401`: invalid API key.
+- `402`: insufficient balance.
+- `404`: task not found or unauthorized.
+- `503`: no available channel.
+
+Known upstream error codes:
+
+- `content_policy_violation`: content violates policy; ask user to revise prompt.
+- `invalid_parameters`: check prompt length, image size, or parameter values.
+- `image_processing_error`: reference image inaccessible/unsupported/corrupt.
+- `image_dimension_mismatch`: reference image dimensions mismatch request.
+- `request_cancelled`: task cancelled.
+- `generation_failed_no_content`: model produced no image; optimize prompt and retry.
+- `service_error`, `service_unavailable`: temporary service issue; retry later.
+- `generation_timeout`: generation timed out; retry later.
+- `resource_exhausted`: resources busy; retry is reasonable.
+- `quota_exceeded`: too frequent; wait before retrying.
+- `resource_not_found`: task expired/not found.
+
+## Pitfalls
+
+- Never expose the raw API key.
+- **Skipping reference analysis**: when the user provides a reference image and asks to create a derivative visual asset, do not jump straight to generation or parameter confirmation. Analyze the reference first (colors, composition, style), discuss findings with the user, then proceed. The user's expected workflow is: analyze → discuss → plan → confirm → generate. Skipping analysis wastes iterations and frustrates the user.
+- Do not use local file paths in `image_urls`; they must be public URLs.
+- Do not pass `quality` or `resolution` with `gpt-image-2-beta`.
+- Do not set `n > 1` for `gpt-image-2-beta`.
+- For `gpt-image-2`, only include `resolution` for ratio sizes like `1:1` or `16:9`; omit it for `auto`.
+- If generating multiple images or high resolution, it can help to also mention count/resolution requirements in the prompt.
+- For IP/reference-style illustration tasks, preserve concrete IP recognition anchors and reference style constraints explicitly; do not let the prompt drift into a generic product illustration. See `references/ip-style-controlled-generation.md`.
+- When the user asks for an IP-only asset from a busy scene/reference image, explicitly strip every non-IP element in the prompt: no background, no ground, no game/world props, no UI, no text, no icons, and request an isolated centered transparent/alpha-ready PNG-style mascot. If the reference is only available as a local Telegram cache path and no public URL exists, use the visible image description/recognition anchors rather than passing the local path to `image_urls`. See `references/ip-only-transparent-assets.md`.
+- For iterative campaign/banner variants, reuse the approved visual recipe: original IP recognition anchors + prior accepted 3D style + new business theme. Keep the style constant unless the user asks to change it; only swap the thematic objects/actions (e.g. server, recharge, analytics dashboard). See `references/session-notes-2026-06-17.md` for a concrete run pattern and transient API retry notes.
+- For AI model/logo mascot banners, preserve official-logo recognition before adding cuteness. Do not substitute Codex with the OpenAI/GPT knot or a generic black terminal; use the Codex rounded-square app icon with purple-blue cloud/blob and `>_` terminal glyph. See `references/ai-model-logo-mascot-banners.md`.
+- For iterative website/hero banner variants based on an approved mascot set, treat the existing IP/mascots as locked. Explicitly instruct: preserve the exact original mascot identities, silhouettes, and recognition anchors; do not redesign, replace, merge, or invent new mascots; only improve layout, background, glassmorphism UI, lighting, spacing, and composition. When the user says the design needs “more design sense/设计感”, improve hierarchy, UI framing, depth, gradients, and polish rather than swapping characters.
+- For landing-page hero covers derived from busy game/fantasy reference art, first study the target template style and convert the reference into a web-usable brand hero background: reserve top navigation space, left-side low-detail text space, center/right focal mascot placement, and reduce clutter/protected-IP-like game props. See `references/landing-page-hero-banners.md`.
+- For cute website/banner assets derived from a generated image, especially when the user asks to remove background/text/buttons while keeping mascot artwork, follow the cleaned-banner edit pattern in `references/token-leaderboard-banner-edits.md`.
+- On Telegram and similar messaging platforms, markdown image syntax `![alt](url)` is delivered as a native image. Do not repeat the same markdown image in follow-up confirmations unless the user explicitly asks to resend/download it; otherwise it looks like multiple images were generated. For follow-ups, mention the task id/options and use a plain URL or say “上一条那张”.
+
+## Verification
+
+A successful run is verified only when the task status is `completed` and at least one URL exists in `result_data[].url`.

package/skill/references/ai-model-logo-mascot-banners.md

@@ -0,0 +1,39 @@
+# AI model logo mascot banners
+
+Session learning from a 3:1 token leaderboard banner iteration.
+
+## Class of task
+
+When generating cute/3D/jelly mascot banners for AI model leaderboards, users may expect strong official-logo recognition, not loose brand-color inspiration. If the user asks for model IPs like Claude, Codex, DeepSeek, Gemini, clarify whether they want:
+
+- brand-inspired mascots, or
+- official-logo-recognizable mascots made cuter.
+
+If they say “一看就知道是 X” or “官方 logo 复刻然后可爱一点”, preserve the logo silhouette and core marks first; add cuteness second.
+
+## Codex logo anchors
+
+Do **not** represent Codex with the OpenAI/GPT knot logo, and do not default to a generic black terminal/code block. The user corrected that this is visually wrong.
+
+Use these anchors for Codex:
+
+- app-style rounded-square icon
+- white/light-gray icon base with large rounded corners and soft shadow
+- inner cloud/blob terminal symbol
+- smooth purple/violet-to-deep-blue gradient on the inner blob
+- pale lavender/white terminal glyphs: `>_`
+- developer-terminal feeling, but still app-icon clean
+
+Good prompt fragment:
+
+> Codex mascot must match an app-style rounded-square white/light-gray icon with large rounded corners and soft shadow; inside it a rounded cloud/blob terminal symbol with smooth purple/violet at the top to deep blue at the bottom; inside the cloud are pale lavender/white terminal prompt marks like `>_`. Make it cute and glossy 3D, but do not obscure the cloud shape or `>_`. It should look like the Codex logo reference, not the OpenAI knot, GPT logo, or a generic black terminal.
+
+## Iteration pattern
+
+For incremental edits:
+
+1. Reuse the previous generated public image URL as `image_urls` when available.
+2. If the user provides a local Telegram/cache image as logo reference, do not pass the local path to AICodeWith; describe its visual anchors in the prompt unless a public URL is available.
+3. Preserve approved parts explicitly: “Keep Claude, DeepSeek, Gemini as close as possible; ONLY fix Codex.”
+4. State negative constraints explicitly: “not OpenAI knot, not GPT logo, not black terminal, no text, no buttons.”
+5. Keep the web banner constraints: `3:1`, no background/card/text/buttons if the user has already removed them, open space above for website overlay text.

package/skill/references/ip-only-transparent-assets.md

@@ -0,0 +1,31 @@
+# IP-only transparent asset generation
+
+Use this reference when the user supplies a busy scene/image but asks for only the mascot/IP as a web asset.
+
+## Durable pattern
+
+1. Confirm whether the user wants the whole scene or only the IP. If they say “只要 IP / 不要背景”, treat every environmental element as negative prompt material.
+2. Preserve concrete recognition anchors from the IP reference:
+   - species/character type
+   - face/body colors
+   - ear/limb colors
+   - expression details
+   - body proportions
+   - material/style, e.g. toy-like 3D, chibi, polished platform-game look
+3. Convert the business intent into pose/action only, not into background clutter. Example: for a workspace empty state, use “waving hello” and “subtly pointing down-right toward a Create Workspace button” while keeping the image itself free of UI/text.
+4. Explicitly strip all non-IP elements from the source scene.
+5. Request web-asset suitability: isolated, centered, clean edges, transparent/alpha-ready PNG-style output.
+
+## Prompt skeleton
+
+```text
+Create a standalone transparent-background PNG-style 3D mascot character only, based on this IP description: [recognition anchors].
+Pose: [business intent as gesture/action].
+No background, no ground, no grass, no blocks, no stars, no mushrooms, no coins, no UI, no text, no icons, no scene props, no environment. Isolated character centered with clean edges, web empty-state illustration asset, friendly, minimal, high quality, transparent or plain alpha-ready background.
+```
+
+## Pitfalls
+
+- Do not pass local Telegram cache paths to external image APIs as `image_urls`; the AICodeWith API expects public URLs. If no public URL exists, use the image description/recognition anchors in the prompt.
+- Do not let the model recreate the busy reference scene when the user asks for “IP only”. Name every unwanted prop/category explicitly.
+- Avoid adding readable UI labels inside the PNG even if the asset points toward a button; button text belongs in the web UI, not the mascot image.

package/skill/references/ip-style-controlled-generation.md

@@ -0,0 +1,48 @@
+# IP/style-controlled image generation notes
+
+Use when the user provides a character/IP reference and says the generated image must follow that style.
+
+## Lesson
+
+If the user asks for an illustration based on an IP/reference image, do not only describe the task category (e.g. “AI Agent illustration”). The prompt must explicitly preserve the IP’s recognizable visual anchors and the reference image’s style constraints.
+
+## Prompt structure
+
+1. State the deliverable and usage context.
+2. Add a hard requirement: “core IP must be visually recognizable.”
+3. List concrete IP anchors from the reference image:
+   - body/head orientation
+   - color blocks
+   - ears/eyes/nose/mouth shape
+   - distinctive patches/accessories
+   - expression/personality
+4. List style constraints from the reference image:
+   - palette
+   - background
+   - flat/vector/3D/photographic style
+   - line weight, cards, nodes, icons, decoration
+   - forbidden style drift (e.g. no blue-purple tech glow, no 3D)
+5. Then add the new product/theme content.
+6. For multiple images, define different compositions while keeping the same IP and visual system.
+
+## Example skeleton
+
+```text
+Generate N website illustrations for [product/context].
+
+Core IP must be very recognizable: [specific character orientation, colors, ear/face/body markings, expression, silhouette]. Do not transform the IP into a generic mascot, robot, or different species. Preserve [top 3 most recognizable anchors].
+
+Visual style must strictly follow the reference: [palette], [background], [flat/vector/etc.], [shape language], [UI motif]. Avoid [style drift].
+
+Theme/content: [agent/workflow/product concept].
+
+Composition variants:
+1. ...
+2. ...
+
+No readable text, no logos, no watermark.
+```
+
+## Pitfall
+
+Do not rely on “based on this IP” alone. If the generated image loses recognizability, the prompt was underspecified even if the product theme was correct.

package/skill/references/landing-page-hero-banners.md

@@ -0,0 +1,47 @@
+# Landing Page Hero Banner Adaptation Notes
+
+Use when a user provides a busy fantasy/game reference image and wants a website hero/landing-page cover, especially for a premium ecommerce template such as v0 Evasion.
+
+## Design sequence
+
+1. **Do not generate immediately.** First analyze the reference image and the target template/page style.
+2. For premium ecommerce templates, convert the reference into a **brand hero background**, not a game screenshot or poster.
+3. Preserve the reference's emotional anchors while reducing clutter:
+   - keep: cute mascot, fantasy/adventure mood, floating islands, waterfalls, atmospheric depth
+   - reduce/replace: classic game props that resemble protected IP, dense collectibles, obvious question blocks, excessive coins
+4. Reserve composition zones for web use:
+   - left 35–40%: darker, low-detail negative space for title/navigation
+   - top band: clean sky/gradient for nav overlay
+   - center-right: main mascot/focal island
+   - right side: brighter fantasy world detail
+   - bottom: calm water/grass transition for crop tolerance
+5. Discuss style before generation. A useful balanced target is: **premium brand feel 60% + game adventure feel 40%**.
+6. Only after style is agreed, confirm the mandatory generation parameters.
+
+## Prompt recipe
+
+Core wording:
+
+```text
+A cinematic 16:9 hero banner for a premium landing page, a whimsical fantasy adventure world in polished stylized 3D illustration. The left 40% of the image is a calm dark blue misty valley with distant cliffs, soft fog, subtle water reflections and low-detail negative space for website text and navigation. The center-right features a cute dog adventurer mascot standing confidently on a small floating grassy island with flowers, vines and soft glowing particles. The right side opens into a bright colorful fairytale world with floating islands, waterfalls, clouds, lush greenery, delicate flowers, a charming mushroom house and a distant ivy-covered stone tower.
+
+Premium website hero composition, clean top area for navigation overlay, strong depth, atmospheric perspective, soft cinematic lighting, vibrant but refined color palette, high-end 3D game promotional art, cute but not childish, adventurous and joyful mood.
+
+No text, no logo, no UI, no buttons, no captions, no watermark, no classic question blocks, no Mario-style objects, no pixel art, no flat vector, no anime.
+```
+
+## Recommended option set
+
+For a first high-quality hero master:
+
+- model: `gpt-image-2`
+- size: `16:9` when 21:9 is uncertain or not desired
+- n: `1`
+- quality: `high`
+- resolution: `2K`
+
+If the final page needs an ultra-wide crop, generate 16:9 as a flexible master first, then crop/extend after visual approval.
+
+## Implementation note
+
+If the runtime does not have `requests`, do not stop. Use Python stdlib `urllib.request` to call the AICodeWith API and poll the task. The lesson is to have a dependency-free fallback, not to assume the image API is unavailable.

package/skill/references/programmatic-image-analysis.md

@@ -0,0 +1,126 @@
+# Programmatic Image Analysis (Pillow + NumPy fallback)
+
+When `vision_analyze` fails (missing vision provider, model doesn't support vision), use this
+approach to extract actionable visual data from an image file without seeing it.
+
+## Dependencies
+
+```bash
+uv pip install Pillow numpy
+```
+
+If already in venv, runs with `/opt/hermes/.venv/bin/python`.
+
+## Analysis recipe
+
+Run these analyses in order — each builds on the previous:
+
+### 1. Basic info + dominant colors
+
+```python
+from PIL import Image
+import collections
+
+img = Image.open('/path/to/image.jpg')
+print(f'Format: {img.format}')
+print(f'Size: {img.size[0]}x{img.size[1]}')
+print(f'Mode: {img.mode}')
+
+img_small = img.resize((100, 100))
+pixels = list(img_small.getdata())
+color_counts = collections.Counter(pixels)
+
+for color, count in color_counts.most_common(20):
+    pct = count / len(pixels) * 100
+    if pct > 0.5:
+        r, g, b = color[0], color[1], color[2] if len(color) >= 3 else (color[0],)*3
+        print(f'  #{r:02x}{g:02x}{b:02x} RGB({r},{g},{b}) = {pct:.1f}%')
+```
+
+### 2. Composition: content bounding box + quadrant density
+
+```python
+import numpy as np
+arr = np.array(img)
+mask = ~((arr[:,:,0] > 240) & (arr[:,:,1] > 240) & (arr[:,:,2] > 240))
+rows = np.any(mask, axis=1)
+cols = np.any(mask, axis=0)
+
+if rows.any():
+    rmin, rmax = np.where(rows)[0][[0, -1]]
+    cmin, cmax = np.where(cols)[0][[0, -1]]
+    print(f'Content region: ({cmin},{rmin}) to ({cmax},{rmax})')
+    
+    crop = arr[rmin:rmax, cmin:cmax]
+    h, w = crop.shape[0], crop.shape[1]
+    for qname, q in [('top-left', crop[:h//2,:w//2]),
+                      ('top-right', crop[:h//2,w//2:]),
+                      ('bot-left', crop[h//2:,:w//2]),
+                      ('bot-right', crop[h//2:,w//2:])]:
+        non_white = ((q[:,:,0] < 240) | (q[:,:,1] < 240) | (q[:,:,2] < 240)).mean()
+        print(f'  {qname}: {non_white*100:.0f}% non-white')
+
+# Row-by-row density profile
+for r in range(rmin, rmax+1, max(1, (rmax-rmin)//15)):
+    content_pct = mask[r, cmin:cmax].mean()
+    bar = '#' * int(content_pct * 50)
+    print(f'  row {r:4d}: {bar} ({content_pct*100:.0f}%)')
+```
+
+### 3. Edge density (shape/contour distribution)
+
+```python
+from PIL import ImageFilter
+edges = np.array(img.filter(ImageFilter.FIND_EDGES))
+edge_mask = (edges[:,:,0] > 30) | (edges[:,:,1] > 30) | (edges[:,:,2] > 30)
+
+h, w = arr.shape[:2]
+dh, dw = h//8, w//8
+print('Edge density grid (8x8):')
+for row in range(8):
+    line = ''
+    for col in range(8):
+        density = edge_mask[row*dh:(row+1)*dh, col*dw:(col+1)*dw].mean()
+        if density > 0.20: line += '██'
+        elif density > 0.10: line += '▓▓'
+        elif density > 0.05: line += '▒▒'
+        elif density > 0.01: line += '░░'
+        else: line += '  '
+    print(f'  {line}')
+```
+
+### 4. Symmetry check
+
+```python
+mid = w // 2
+left = arr[:, :mid]
+right = arr[:, mid:][:, ::-1]  # flipped
+diff = np.abs(left.astype(float) - right.astype(float)).mean()
+print(f'Left-right avg diff: {diff:.0f} (0=perfect symmetry)')
+```
+
+### 5. Color banding (horizontal slices)
+
+```python
+for r in range(50, arr.shape[0], 50):
+    strip = arr[r:r+10, 50:-50]
+    avg = strip.mean(axis=(0,1))
+    rc, gc, bc = int(avg[0]), int(avg[1]), int(avg[2])
+    label = 'DARK' if rc<100 and gc<100 and bc<100 else \
+            'WARM' if rc>150 and gc>100 and bc<170 else \
+            'LITE' if rc>200 and gc>200 and bc>200 else 'GRAY'
+    print(f'  row {r:4d}: #{rc:02x}{gc:02x}{bc:02x} [{label}]')
+```
+
+## What to infer from these outputs
+
+- **Color palette** → the brand's color language; guides hero background palette
+- **Composition quadrants** → where the visual weight sits; asymmetrical logos need backgrounds that balance them
+- **Edge density grid** → locates complex/detailed regions vs. flat areas
+- **Symmetry** → low diff = centered/symmetric logo; high diff = dynamic/off-center
+- **Color banding** → reveals gradients and transitions across the image
+
+## When to use this
+
+Only when `vision_analyze` fails with a provider error. If vision works, prefer it —
+it gives richer results including text recognition and semantic understanding.

package/skill/references/session-notes-2026-06-17.md

@@ -0,0 +1,7 @@
+# Session notes: AICodeWith image generation
+
+- During task creation, a transient TLS/SSL transport error can occur before any task id is returned (`SSLEOFError: [SSL: UNEXPECTED_EOF_WHILE_READING]`).
+- If that happens on the *create* request, retry the same create request once before declaring failure.
+- If a task id has already been returned, never create a duplicate task just because polling hits a transport error; keep polling the same task id.
+- Polling can also see intermittent SSL EOFs; treat them as transient and continue polling.
+- This session successfully generated multiple banners with `gpt-image-2` using 3:1 / 2K / high and one square variant with 1:1 / 1K / medium.

package/skill/references/token-leaderboard-banner-edits.md

@@ -0,0 +1,30 @@
+# Token leaderboard banner edit pattern
+
+Use this reference for iterative website/banner image generation where the user starts from a cute promotional graphic and asks for a cleaned banner asset.
+
+## Durable pattern
+
+1. Confirm required AICodeWith parameters before generation, even for edits:
+   - model, size/aspect ratio, n, quality, resolution.
+2. For website hero banners, ask/propose a wide ratio such as `3:1` when the user wants a horizontal banner.
+3. If the prior generated image already has a public URL, reuse it in `image_urls` for the next edit. Do not attempt to pass local Telegram cache paths to the API.
+4. When the user says to remove background/text/buttons, explicitly enumerate all removals in the prompt:
+   - remove beige/yellow/background card if requested
+   - remove all text, typography, headline, subtitle, badges with words, brand text
+   - remove CTA buttons and UI controls
+   - preserve only mascot/illustration/ranking decorative elements
+5. Ask the model to leave empty space for the site to overlay its own title later if it is a banner asset.
+
+## Prompt recipe
+
+```text
+Edit the provided 3:1 website banner image.
+Remove the pale beige/yellow background entirely. Remove ALL text, typography, labels, badges with words, brand text, headline, subtitle, and remove the CTA button.
+Keep and improve only the cute glossy token/blob mascot illustration elements: colorful jelly-like blob characters, token coins, small flames, trophy, upward arrows, rank badges like #1 #2 #3 only if they are decorative, and cheerful leaderboard/AI usage energy.
+Create a clean transparent-background or pure white-background banner asset suitable for placing over a website hero section. No words, no sentences, no UI button. Preserve the playful glossy vector/soft-3D style, saturated colors, polished highlights, cute expressions, wide horizontal composition, bottom-heavy mascot cluster with empty space above for the website to overlay its own title later.
+Important: output should be a 3:1 horizontal banner illustration, no watermark, no photorealism, no visible text.
+```
+
+## Final response
+
+Return the task id, completion status, selected options, and one markdown image URL only. Avoid resending prior images unless requested.