aitoearn-dsh-plugin-test 0.0.1

package/skills/image-creation/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: image-creation
+description: Generate or edit raster images for social posts, product shots, covers, mockups, and variants. Use when the user asks to create, edit, restyle, adapt, or redesign images based on provided images, or batch-generate bitmap images, or mentions posters, covers, product photos, illustrations, or reference-image generation.
+requiredTools:
+  - list_image_models
+  - generate_image
+---
+
+# Image Creation
+
+Generate or edit raster images with `list_image_models` and `generate_image`.
+
+Shared prompt guidance: `references/prompting.md`.
+Copy/paste recipes: `references/sample-prompts.md`.
+
+## Tools
+
+- `list_image_models`: call first. Use only returned `name`, `sizes`, `qualities`, `styles`, `maxInputImages`, and pricing. Do not invent model ids or sizes.
+- `generate_image`: `prompt` required; `model` required; optional `images`, `size`, `quality`, `style`.
+  - No `images` → new generation.
+  - One or more `images` (URLs) → reference/edit generation. Do not exceed `maxInputImages`.
+- Credit (积分) estimate runs automatically. If the user must confirm, wait. Do not retry a rejected cost.
+
+Do not call other image APIs, CLIs, or local scripts.
+
+## When to use
+
+- New image: concept, product shot, cover, poster, social asset, mockup
+- New image guided by reference images (style, composition, mood, subject)
+- Adapt or redesign an image or design the user provided (change format, layout, device framing, restyle) while keeping its content
+- Edit an existing image (object change, background, lighting, compositing, restyle)
+- Many assets or variants for one request
+
+## When not to use
+
+- Matching an existing SVG/vector icon or logo system
+- Simple shapes, diagrams, or icons that should be SVG, HTML/CSS, or canvas
+- A small edit when the source is already an editable native file
+- The user wants deterministic code-native output instead of a bitmap
+
+## Decision tree
+
+1. **Intent:** were images provided, and what role do they play?
+2. **Execution:** one asset or many assets/variants?
+
+Intent:
+
+- User provided images with the request → the images MUST be passed in `images`. Generate from scratch without them only if the user explicitly says the images are irrelevant or inspiration-only. Ignoring provided images and inventing content is a failure mode.
+  - User wants to change an existing image while keeping parts of it → **edit**. Pass those image URLs in `images` and list invariants in the prompt.
+  - User gives images as style/composition/mood/subject references → **generate with references**. Still pass URLs in `images`, and label each role in the prompt.
+  - User gives an image or design to adapt, redesign, or translate into another format/framing → **generate with references**, grounded in the image's real content (see Workflow step 2).
+- No images → **generate**.
+
+Execution:
+
+- Distinct assets need distinct `generate_image` calls and distinct prompts.
+- Variants of one prompt still use one call per variant, with a single targeted change in each prompt.
+
+Assume a new image unless the user clearly asks to change an existing one.
+
+## Workflow
+
+1. Call `list_image_models` and pick `model` / `size` / `quality` / `style` from that catalog. If the user names a target device, format, or aspect (e.g. landscape, poster, phone), pick the size that matches it.
+2. Inspect every image the user provided: identify its actual subject, visible text and its language, colors, and layout. The prompt must describe what is really in the image — never substitute invented content for it.
+3. Collect prompt, verbatim text, constraints/avoid list, and any input image URLs.
+4. Label every input image role: edit target, style reference, compositing insert, or adaptation base.
+5. If the request is a photo, illustration, sprite, product image, or other raster asset, use `generate_image`. If it should match repo-native SVG/vector/code, edit those instead.
+6. Shape the prompt:
+   - Specific user prompt → normalize, do not add creative requirements.
+   - Generic prompt → add only detail that materially improves the result. See `references/prompting.md`.
+   - Grounded on a user image → reproduce its real content faithfully (original text and language, palette, layout) and describe only the requested changes. List what must be preserved as invariants.
+7. Call `generate_image` once per requested asset or variant.
+8. Inspect the result: subject, style, composition, text accuracy, invariants.
+9. Iterate with one targeted change. Repeat invariants on every edit.
+10. Report: write the returned image URL(s) verbatim in your reply (the frontend renders them as previews), plus the final prompt, model, and size. Omitting the URL is a failed delivery. State briefly what came from the input images and what was changed; do not append generic advice unrelated to the images.
+
+## Transparent images
+
+This runtime has no alpha or background-removal tool. `generate_image` returns an image URL, not a local transparent PNG.
+
+If the user asks for a cutout or transparent background:
+
+1. Prompt a perfectly flat solid chroma-key background (`#00ff00` by default; `#ff00ff` for green subjects).
+2. Require no shadows, gradients, floor, reflections, or key color inside the subject.
+3. Tell the user the result is a keyed image URL they can cut out later. Do not claim a true alpha PNG.
+
+## Prompt schema
+
+```text
+Use case: <taxonomy slug>
+Asset type: <where the asset will be used>
+Primary request: <user's main prompt>
+Input images: <Image 1: role; Image 2: role> (optional)
+Scene/backdrop: <environment>
+Subject: <main subject>
+Style/medium: <photo/illustration/3D/etc>
+Composition/framing: <wide/close/top-down; placement>
+Lighting/mood: <lighting + mood>
+Color palette: <palette notes>
+Materials/textures: <surface details>
+Text (verbatim): "<exact text>"
+Constraints: <must keep/must avoid>
+Avoid: <negative constraints>
+```
+
+Use only the lines that help. For edits, list invariants: `change only X; keep Y unchanged`.
+
+## Use-case taxonomy
+
+Generate: `photorealistic-natural`, `product-mockup`, `ui-mockup`, `infographic-diagram`, `scientific-educational`, `ads-marketing`, `productivity-visual`, `logo-brand`, `illustration-story`, `stylized-concept`, `historical-scene`.
+
+Edit: `text-localization`, `identity-preserve`, `precise-object-edit`, `lighting-weather`, `background-extraction`, `style-transfer`, `compositing`, `sketch-to-render`.
+
+## Examples
+
+### Generation
+
+```text
+Use case: product-mockup
+Asset type: landing page hero
+Primary request: a minimal hero image of a ceramic coffee mug
+Style/medium: clean product photography
+Composition/framing: wide composition with usable negative space for page copy if needed
+Lighting/mood: soft studio lighting
+Constraints: no logos, no text, no watermark
+```
+
+### Edit
+
+```text
+Use case: precise-object-edit
+Asset type: product photo background replacement
+Primary request: replace only the background with a warm sunset gradient
+Input images: Image 1: edit target
+Constraints: change only the background; keep the product and its edges unchanged; no text; no watermark
+```

package/skills/image-creation/references/prompting.md

@@ -0,0 +1,103 @@
+# Prompting best practices
+
+Prompt structure, specificity, and iteration for `generate_image`.
+Pick `model`, `size`, `quality`, and `style` from `list_image_models`. Do not invent those values here.
+
+Copy/paste recipes: `references/sample-prompts.md`.
+
+## Structure
+
+- Order: scene/backdrop -> subject -> key details -> constraints -> output intent.
+- Include intended use (ad, UI mock, infographic) to set polish.
+- For complex requests, use short labeled lines instead of one long paragraph.
+- When the user names a target device, format, or aspect (landscape/portrait, poster, phone screen), say so in the prompt and pick a matching `size` from the model catalog.
+
+## Specificity policy
+
+- If the user prompt is already specific, normalize it. Do not add creative requirements.
+- If the prompt is generic, add tasteful detail only when it materially improves the output.
+- Treat `sample-prompts.md` as fully-authored recipes, not the default amount of augmentation.
+- For photorealism, include `photorealistic` plus real texture: pores, wrinkles, fabric wear, material grain, everyday imperfect detail.
+
+## Allowed and disallowed augmentation
+
+Allowed for generic prompts:
+
+- composition and framing cues
+- intended-use or polish-level hints
+- practical layout guidance
+- reasonable scene concreteness that supports the request
+
+Do not add:
+
+- extra characters, props, or objects that are not implied
+- brand palettes, slogans, or story beats that are not implied
+- arbitrary side-specific placement unless the surrounding layout supports it
+
+## Composition and layout
+
+- Specify framing and viewpoint only when it materially helps.
+- Call out negative space if the asset needs room for UI or copy.
+- Avoid left/right layout decisions unless the user or surrounding layout supports them.
+- For people, describe body framing, scale, gaze, and object interactions when they matter.
+
+## Constraints and invariants
+
+- State what must not change (`keep background unchanged`).
+- For edits: `change only X; keep Y unchanged`. Repeat invariants on every iteration.
+
+## Text in images
+
+- Put literal text in quotes or ALL CAPS. Specify typography, size, color, and placement.
+- Spell uncommon words letter-by-letter if accuracy matters.
+- Require verbatim rendering and no extra characters.
+- Prefer a catalog quality meant for dense text when the model exposes quality options.
+
+## Input images and references
+
+- Images the user provided with the request must be passed in `generate_image.images`. Silently ignoring them and generating from scratch is a failure mode; only skip them when the user explicitly says they are irrelevant or inspiration-only.
+- Inspect each provided image first and describe what is actually in it — subject, visible text and its language, colors, layout. Do not replace its real content with invented content.
+- Do not assume every provided image is an edit target.
+- Label each image by index and role (`Image 1: edit target`, `Image 2: style reference`, `Image 1: adaptation base`).
+- Grounded redesign/adaptation: preserve the image's real content — original text, language, palette, key layout — and prompt only the requested change; list preserved items as constraints/invariants.
+- Style/composition/mood references without a request to modify them → generation with `images`.
+- Preserve an existing image while changing specific parts → edit with `images`.
+- For compositing, describe how the images interact (`place the subject from Image 2 into Image 1`).
+- Pass image URLs in `generate_image.images`. Stay within `maxInputImages`.
+
+## Iterate deliberately
+
+- Start with a clean base prompt, then make small single-change edits.
+- Re-specify critical constraints when you iterate.
+- Prefer one targeted follow-up over rewriting the whole prompt.
+
+## Transparent images
+
+There is no alpha or local cutout tool. If the user wants a cutout, prompt a flat solid chroma-key background (`#00ff00`, or `#ff00ff` for green subjects), forbid shadows/gradients/floor/reflections, and tell the user the result is a keyed image URL.
+
+## Use-case tips
+
+Generate:
+
+- photorealistic-natural: photography language; real texture; avoid over-stylized polish unless requested.
+- product-mockup: product/packaging and materials; clean silhouette; verbatim labels if text is required.
+- ui-mockup: state fidelity first (shippable mockup or low-fi wireframe); layout and hierarchy, not concept art.
+- infographic-diagram: audience, layout flow, explicit labels, verbatim text.
+- logo-brand: simple, scalable, strong silhouette, balanced negative space.
+- ads-marketing: creative brief — brand position, audience, vibe, scene, exact tagline.
+- productivity-visual: name the artifact, canvas, hierarchy, real labels/data, readable type.
+- scientific-educational: audience, lesson objective, required labels, scientific constraints.
+- illustration-story: panels or scene beats; keep each action concrete.
+- stylized-concept: style cues, material finish, rendering approach; do not invent story.
+- historical-scene: location/date and period accuracy; constrain clothing, props, environment.
+
+Edit:
+
+- text-localization: change only the text; preserve layout and typography.
+- identity-preserve: lock face, body, pose, hair, expression; change only the specified elements.
+- precise-object-edit: specify exactly what to remove/replace; keep everything else unchanged.
+- lighting-weather: change only light, atmosphere, weather; keep geometry and identity.
+- background-extraction: flat chroma-key background; crisp silhouette; generous padding; no restyling.
+- style-transfer: preserve palette/texture/brushwork; add `no extra elements`.
+- compositing: reference inputs by index; match lighting, perspective, and scale.
+- sketch-to-render: preserve layout, proportions, and perspective; do not add new elements.

package/skills/image-creation/references/sample-prompts.md

@@ -0,0 +1,310 @@
+# Sample prompts
+
+Complete prompt recipes for `generate_image`. They are starting points, not the default amount of augmentation to add to every request.
+
+When adapting a user prompt:
+
+- keep user-provided requirements
+- only add detail according to the specificity policy in `SKILL.md`
+- do not treat every example as permission to invent extra story elements
+
+`Asset type` and `Input images` are prompt scaffolding. Pick `model`, `size`, `quality`, and `style` from `list_image_models`.
+
+For principles, see `references/prompting.md`.
+
+## Generate
+
+### photorealistic-natural
+
+```
+Use case: photorealistic-natural
+Primary request: candid photo of an elderly sailor on a small fishing boat adjusting a net
+Scene/backdrop: coastal water with soft haze
+Subject: weathered skin with wrinkles and sun texture
+Style/medium: photorealistic candid photo
+Composition/framing: medium close-up, eye-level
+Lighting/mood: soft coastal daylight, shallow depth of field, subtle film grain
+Materials/textures: real skin texture, worn fabric, salt-worn wood
+Constraints: natural color balance; no heavy retouching; no glamorization; no watermark
+Avoid: studio polish; staged look
+```
+
+### product-mockup
+
+```
+Use case: product-mockup
+Primary request: premium product photo of a matte black shampoo bottle with a minimal label
+Scene/backdrop: clean studio gradient from light gray to white
+Subject: single bottle centered with subtle reflection
+Style/medium: premium product photography
+Composition/framing: centered, slight three-quarter angle, generous padding
+Lighting/mood: softbox lighting, clean highlights, controlled shadows
+Materials/textures: matte plastic, crisp label printing
+Constraints: no logos or trademarks; no watermark
+```
+
+### ui-mockup
+
+```
+Use case: ui-mockup
+Primary request: mobile app home screen for a local farmers market with vendors and daily specials
+Asset type: mobile app screen
+Style/medium: realistic product UI, not concept art
+Composition/framing: clean vertical mobile layout with clear hierarchy
+Constraints: practical layout, clear typography, no logos or trademarks, no watermark
+```
+
+### infographic-diagram
+
+```
+Use case: infographic-diagram
+Primary request: detailed infographic of an automatic coffee machine flow
+Scene/backdrop: clean, light neutral background
+Subject: bean hopper -> grinder -> brew group -> boiler -> water tank -> drip tray
+Style/medium: clean vector-like infographic with clear callouts and arrows
+Composition/framing: vertical poster layout, top-to-bottom flow
+Text (verbatim): "Bean Hopper", "Grinder", "Brew Group", "Boiler", "Water Tank", "Drip Tray"
+Constraints: clear labels, strong contrast, no logos or trademarks, no watermark
+```
+
+### scientific-educational
+
+```
+Use case: scientific-educational
+Primary request: biology diagram titled "Cellular Respiration at a Glance" for high school students
+Scene/backdrop: clean white classroom handout background
+Subject: glucose turns into energy inside a cell; include glycolysis, Krebs cycle, and electron transport chain
+Style/medium: flat scientific diagram with consistent icons, arrows, and readable labels
+Composition/framing: landscape slide-style layout with clear hierarchy and generous whitespace
+Text (verbatim): "Cellular Respiration at a Glance", "Glucose", "Pyruvate", "ATP", "NADH", "FADH2", "CO2", "O2", "H2O"
+Constraints: scientifically plausible; avoid tiny text; no extra decoration; no watermark
+```
+
+### logo-brand
+
+```
+Use case: logo-brand
+Primary request: original logo for "Field & Flour", a local bakery
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: single centered logo on a plain background with generous padding
+Constraints: strong silhouette, balanced negative space; original design only; no gradients unless essential; no trademarks; no watermark
+```
+
+### illustration-story
+
+```
+Use case: illustration-story
+Primary request: 4-panel comic about a pet left alone at home
+Scene/backdrop: cozy living room across panels
+Subject: pet reacting to the owner leaving, then relaxing, then returning to a composed pose
+Style/medium: comic illustration with clear panels
+Composition/framing: 4 equal-sized vertical panels, readable actions per panel
+Constraints: no text; no logos or trademarks; no watermark
+```
+
+### stylized-concept
+
+```
+Use case: stylized-concept
+Primary request: cavernous hangar interior with tall support beams and drifting fog
+Scene/backdrop: industrial hangar interior, deep scale, light haze
+Subject: compact shuttle parked near the center
+Style/medium: cinematic concept art, industrial realism
+Composition/framing: wide-angle, low-angle
+Lighting/mood: volumetric light rays cutting through fog
+Constraints: no logos or trademarks; no watermark
+```
+
+### ads-marketing
+
+```
+Use case: ads-marketing
+Primary request: campaign image for a streetwear brand called Thread
+Subject: group of friends hanging out together in a stylish urban setting
+Style/medium: polished youth streetwear campaign photography
+Composition/framing: vertical ad layout with natural poses and integrated headline space
+Lighting/mood: contemporary, energetic, tasteful
+Text (verbatim): "Yours to Create."
+Constraints: render the tagline exactly once; clean legible typography; no extra text; no watermarks; no unrelated logos
+```
+
+### productivity-visual
+
+```
+Use case: productivity-visual
+Primary request: one pitch-deck slide titled "Market Opportunity"
+Asset type: fundraising slide image
+Style/medium: clean modern deck slide, white background, crisp sans-serif typography
+Subject: TAM/SAM/SOM concentric-circle diagram plus a small growth bar chart from 2021 to 2026
+Composition/framing: 16:9 landscape slide, clear data hierarchy, polished spacing
+Text (verbatim): "Market Opportunity", "TAM: $42B", "SAM: $8.7B", "SOM: $340M", "AGI Research, 2024", "Internal analysis"
+Constraints: readable labels, no clip art, no stock photography, no decorative clutter, no watermark
+```
+
+### historical-scene
+
+```
+Use case: historical-scene
+Primary request: outdoor crowd scene in Bethel, New York on August 16, 1969
+Scene/backdrop: open field with period-appropriate staging
+Subject: crowd in period-accurate clothing, authentic environment
+Style/medium: photorealistic photo
+Composition/framing: wide shot, eye-level
+Constraints: period-accurate details; no modern objects; no logos or trademarks; no watermark
+```
+
+## Asset type templates
+
+### Website assets
+
+```
+Use case: <photorealistic-natural|stylized-concept|product-mockup|infographic-diagram|ui-mockup>
+Asset type: <hero image / section illustration / blog header>
+Primary request: <short description>
+Scene/backdrop: <environment or abstract backdrop>
+Subject: <main subject>
+Style/medium: <photo/illustration/3D>
+Composition/framing: <wide/centered; note usable negative space only if needed>
+Lighting/mood: <soft/bright/neutral>
+Color palette: <brand colors or neutral>
+Constraints: <no text; no logos; no watermark; leave room for UI if needed>
+```
+
+### Game assets
+
+```
+Use case: stylized-concept
+Asset type: <game environment concept art / game character concept / game UI icon / tileable game texture>
+Primary request: <biome/scene/character/icon/material>
+Scene/backdrop: <location + set dressing> (if applicable)
+Subject: <main focal element(s)>
+Style/medium: <realistic/stylized>; <concept art / character render / UI icon / texture>
+Composition/framing: <wide/establishing/top-down>; <camera angle>; <focal point placement>
+Lighting/mood: <time of day>; <mood>; <volumetric/fog/etc>
+Constraints: no logos or trademarks; no watermark
+```
+
+### Wireframe
+
+```
+Use case: ui-mockup
+Asset type: website wireframe
+Primary request: <page or flow to sketch>
+Style/medium: low-fi grayscale wireframe
+Composition/framing: <landscape or portrait to match expected device>
+Subject: <sections in order; grid/columns; key labels>
+Constraints: no color; no logos; no real photos; no watermark
+```
+
+### Logo
+
+```
+Use case: logo-brand
+Asset type: logo concept
+Primary request: <brand idea or symbol concept>
+Style/medium: vector logo mark; flat colors; minimal
+Composition/framing: centered mark; clear silhouette; generous margin
+Color palette: <1-2 colors; high contrast>
+Text (verbatim): "<exact name>" (only if needed)
+Constraints: no gradients; no mockups; no 3D; no watermark
+```
+
+## Edit
+
+### text-localization
+
+```
+Use case: text-localization
+Input images: Image 1: original infographic
+Primary request: replace "Bean Hopper", "Grinder", "Brew Group", "Boiler", "Water Tank", and "Drip Tray" with "Tolva", "Molino", "Grupo de infusión", "Caldera", "Depósito de agua", and "Bandeja de goteo"
+Constraints: change only the text; preserve layout, typography, spacing, and hierarchy; no extra words; do not alter logos or imagery
+```
+
+### identity-preserve
+
+```
+Use case: identity-preserve
+Input images: Image 1: person photo; Image 2..N: clothing references
+Primary request: replace only the clothing with the provided garments
+Constraints: preserve face, body shape, pose, hair, expression, and identity; match lighting and shadows; keep the background unchanged; no accessories or text
+```
+
+### precise-object-edit
+
+```
+Use case: precise-object-edit
+Input images: Image 1: room photo
+Primary request: replace only the white chairs with wooden chairs
+Constraints: preserve camera angle, room lighting, floor shadows, and surrounding objects; keep all other aspects unchanged
+```
+
+### lighting-weather
+
+```
+Use case: lighting-weather
+Input images: Image 1: original photo
+Primary request: make it look like a winter evening with gentle snowfall
+Constraints: preserve subject identity, geometry, camera angle, and composition; change only lighting, atmosphere, and weather
+```
+
+### background-extraction
+
+```
+Use case: background-extraction
+Input images: Image 1: product photo
+Primary request: isolate the product on a clean keyed background
+Scene/backdrop: perfectly flat solid #00ff00 chroma-key background
+Constraints: background must be one uniform color with no shadows, gradients, texture, reflections, floor plane, or lighting variation; crisp silhouette; generous padding; no halos or fringing; preserve label text exactly; no restyling; do not use #00ff00 anywhere in the subject
+```
+
+The result is a keyed image URL. This runtime cannot emit a local transparent PNG.
+
+### style-transfer
+
+```
+Use case: style-transfer
+Input images: Image 1: style reference
+Primary request: apply Image 1's visual style to a man riding a motorcycle on a plain white backdrop
+Constraints: preserve palette, texture, and brushwork; no extra elements
+```
+
+### compositing
+
+```
+Use case: compositing
+Input images: Image 1: base scene; Image 2: subject to insert
+Primary request: place the subject from Image 2 next to the person in Image 1
+Constraints: match lighting, perspective, and scale; keep the base framing unchanged; no extra elements
+```
+
+### character consistency
+
+```
+Use case: identity-preserve
+Input images: Image 1: previous character anchor illustration
+Primary request: continue the story with the same character in a new scene and action
+Scene/backdrop: snowy forest after a winter storm
+Subject: same young forest hero gently helping a frightened squirrel out of a fallen tree
+Style/medium: same children's book watercolor illustration style as Image 1
+Constraints: do not redesign the character; preserve facial features, proportions, outfit, color palette, and personality; no text; no watermark
+```
+
+### sketch-to-render
+
+```
+Use case: sketch-to-render
+Input images: Image 1: drawing
+Primary request: turn the drawing into a photorealistic image
+Constraints: preserve layout, proportions, and perspective; choose realistic materials and lighting; do not add new elements or text
+```
+
+### reference-grounded adaptation
+
+```
+Use case: ui-mockup
+Input images: Image 1: original design/photo to adapt
+Primary request: adapt Image 1 to a <new format/framing/use>, for example a vertical poster recomposed as a wide banner
+Constraints: preserve all visible text verbatim and its language; preserve colors, typography style, and content; recompose only the layout/framing for the new format; do not replace real content with invented content; no watermark
+```
+
+Replace the `Use case` with whichever taxonomy slug fits the subject. The invariants line is the point of this recipe: everything real in the input image is preserved, only the requested change is described.

package/skills/image-edit/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: image-edit
+description: Edit an existing image with deterministic pixel operations via image_edit — rotate, flip, crop (free/ratio/circle), resize, compress/format-convert, adjust brightness/saturation/contrast, sharpen, blur, mosaic, rounded corners, negate, overlay, and image watermark. Use when the user asks to 裁剪/旋转/翻转/缩放/压缩/打码/马赛克/加水印/叠图/圆角/调亮/调暗/锐化/模糊 an existing image, convert format, or hit a file-size limit. For AI re-creation, restyle, or adding text, use image-creation instead.
+requiredTools:
+  - image_edit
+---
+
+# Image Edit
+
+Edit an existing image with `image_edit` — a local, deterministic pixel pipeline. No AI model, no credits (积分), result is pixel-exact and repeatable.
+
+This is **fine-grained image editing**: unlike AI re-creation (`image-creation`), every operation is pixel-exact. Precision is the premise — free-crop regions, mosaic areas, watermark/overlay positions, and drawn shapes are source-image pixel coordinates, so always work from the real dimensions returned by `get_media_metadata`, never from guesses.
+
+## Tool
+
+- `image_edit`: one call per image. Pass `url` (source image) plus `operations`, an ordered array of 1–20 operations applied in sequence.
+- `get_media_metadata` (auxiliary): read the source image's real width/height, format, and alpha before composing operations that need coordinates, ratios, or margins.
+- Output: `url` (edited image), `width`, `height`, `format`, `sizeBytes`.
+- `compress` must be the **last** operation (it is the export step).
+- Operations that introduce transparency (circle crop, rounded corners) output PNG with alpha.
+
+Do not call other image CLIs, local scripts, or external image APIs.
+
+## When to use
+
+- Deterministic edits that must not alter content: crop to a ratio, resize for a platform, compress under a size limit, convert format
+- 加水印 (logo), 叠图 (composite another image), 打码 (mosaic a region), 圆角, rotate/flip
+- Adjust brightness/contrast/saturation, sharpen, blur, negate
+
+## When not to use
+
+- Change/restyle content, remove objects, generate variants → `image-creation` (`generate_image`)
+- Add text or text watermarks → `generate_image` (AI image editing); this tool renders no text
+- Background removal → not supported here; prompt a chroma-key background per `image-creation`, then (future) key it out
+- The source is not an image URL the tool can download
+
+## Operations quick reference
+
+| operation | key params | default |
+|---|---|---|
+| `rotate` | `angle` (1–359, counter-clockwise), `background` | transparent fill |
+| `flip` | `direction`: `horizontal` (左右镜像) / `vertical` (上下翻转) | — |
+| `crop` | `mode`: `free` + `region{x,y,width,height}`; `ratio` + `ratio:"16:9"` + `position`; `circle` (inscribed circle) | — |
+| `resize` | `width`/`height` (one or both), `fit`: cover/contain/fill/inside/outside, `background` | `inside` |
+| `compress` | `format`: jpeg/png/webp, `quality` (1–100), `targetMaxBytes` | keep source format, quality 80 |
+| `adjust` | `brightness`, `saturation`, `contrast` (multipliers, 1 = unchanged) | — |
+| `sharpen` | `strength`: light/medium/strong | — |
+| `blur` | `sigma` (0.3–100, higher = blurrier) | — |
+| `mosaic` | `region` (default whole image), `pixelSize` (2–200) | — |
+| `watermark` | `image.url` (+`width` or `scale`), `position` (9-grid), `margin`, `opacity`, `tile{spacingX,spacingY,rotate}` | bottom-right, opacity 1 |
+| `overlay` | `url`, `position`/`margin`, `width`/`scale`, `opacity` | center |
+| `draw` | `shapes`: rects (radius, fill), ellipses, lines, points, arrows — each with `color`/`lineWidth` | red, 4px line |
+| `rounded-corners` | `radius` (px) | — |
+| `negate` | — | — |
+
+`position` is a 9-grid value: `top-left` … `center` … `bottom-right`.
+
+## Workflow
+
+1. Get the source image URL (user attachment, media library, or a previous generation result).
+2. Call `get_media_metadata` for the source dimensions. Pixel-exact coordinates are the premise of fine-grained editing: free-crop regions, mosaic areas, and watermark/overlay placement must be computed from the real width/height — never guessed.
+3. Decompose the request into ordered operations. Prefer one call with all steps over many calls; each call re-downloads and re-uploads.
+   - Geometry first (crop → resize → rotate), then color (adjust/sharpen/blur), then composition (overlay/watermark), `compress` last.
+4. Pick sensible defaults without asking: `compress` quality 80; watermark `margin` ≈ 2% of the shorter side; mosaic `pixelSize` ≈ image width / 30; blur sigma 2–8 for background softening.
+5. Call `image_edit` once with the full pipeline.
+6. Verify the output (`width`/`height`/`format`/`sizeBytes` match the request, e.g. size limit honored).
+7. Iterate by re-running the whole pipeline from the original URL with adjusted params — do not chain edits on the edited output (avoids compounding loss).
+8. Report the returned `url` and the final params.
+
+## Recipes
+
+```json
+// 裁成 16:9 再加右下角 logo，最后压到 2MB 内
+{ "url": "…", "operations": [
+  { "operation": "crop", "mode": "ratio", "ratio": "16:9" },
+  { "operation": "watermark", "image": { "url": "…", "scale": 0.2 }, "position": "bottom-right", "margin": 20, "opacity": 0.9 },
+  { "operation": "compress", "format": "jpeg", "targetMaxBytes": 2000000 }
+] }
+
+// 圆形头像（png 透明底）
+{ "url": "…", "operations": [
+  { "operation": "crop", "mode": "circle" }
+] }
+
+// 指定区域打码
+{ "url": "…", "operations": [
+  { "operation": "mosaic", "region": { "x": 120, "y": 80, "width": 200, "height": 100 }, "pixelSize": 12 }
+] }
+```
+
+## Errors
+
+- 下载失败 / 超过 20MB → check the URL is a publicly readable image
+- 无法压缩到目标体积 → raise `targetMaxBytes`, drop `format` conversion, or accept lower quality
+- 区域越界 → coordinates are source-image pixels; call `get_media_metadata` first to get dimensions