npm - @autoaiai/aicut - Versions diffs - 0.1.11 → 0.1.13 - Mend

@autoaiai/aicut 0.1.11 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1063) hide show

package/skills/heygen-avatar/references/avatar-creation.md DELETED Viewed

@@ -1,181 +0,0 @@
-# Avatar Creation API Surface
-This guide expands `heygen-avatar` Phase 2 (avatar creation) and Phase 3
-(voice selection) with the full API surface, field mappings, and file
-input formats. The SKILL.md gives the high-level workflow; this file is
-the reference when you need exact arguments, edge cases, or alternative
-creation paths.
-For *avatar discovery* (finding an existing avatar at video time), see
-[`heygen-video/references/avatar-discovery.md`](https://github.com/heygen-com/skills/blob/master/heygen-video/references/avatar-discovery.md).
----
-## Avatar Creation: Three Types
-`heygen-avatar` Phase 2 supports three creation types. Pick based on what
-the user provides:
-| User input | Type | API |
-|---|---|---|
-| A photo of a real person | `photo` | `create_photo_avatar` |
-| A description of an appearance | `prompt` | `create_prompt_avatar` |
-| A short video recording of a real person | `digital_twin` | `create_digital_twin` |
-All three accept an optional `avatar_group_id`:
-- **Omit it** to create a new character (new group).
-- **Include it** to add a new look (variation) to an existing character.
-Always use Mode 2 (with `avatar_group_id`) when the avatar already exists
-and you're creating a variant (different outfit, orientation fix, bg
-change). Only use Mode 1 (new character) for genuinely new identities.
-### Photo avatar (from user's photo)
-**MCP:** `create_photo_avatar(name=<name>, file=<file_object>, avatar_group_id=<optional>)`
-**CLI:**
-```bash
-heygen avatar create -d '{
-  "type": "photo",
-  "name": "My Avatar",
-  "file": {"type": "url", "url": "https://example.com/headshot.jpg"},
-  "avatar_group_id": "<optional>"
-}'
-```
-Photo requirements:
-- JPEG or PNG
-- Min 512x512
-- Clear front-facing face
-- Good lighting
-### AI-generated avatar (from text prompt)
-**MCP:** `create_prompt_avatar(name=<name>, prompt=<appearance>, avatar_group_id=<optional>)`
-**CLI:**
-```bash
-heygen avatar create -d '{
-  "type": "prompt",
-  "name": "Tech Presenter",
-  "prompt": "Young professional woman, modern workspace, confident smile",
-  "avatar_group_id": "<optional>"
-}'
-```
-Prompt limit: 1000 characters (the API spec says 200 but the actual
-enforced limit is 1000). Be descriptive — include style, features,
-expression, lighting.
-Optional: up to 3 `reference_images` to anchor the generated appearance.
-### Video avatar / digital twin (from a short recording)
-**MCP:** `create_digital_twin(name=<name>, file=<file_object>, avatar_group_id=<optional>)`
-**CLI:**
-```bash
-heygen avatar create -d '{
-  "type": "digital_twin",
-  "name": "My Video Avatar",
-  "file": {"type": "asset_id", "asset_id": "<uploaded_asset_id>"},
-  "avatar_group_id": "<optional>"
-}'
-```
----
-## File Input Formats
-`file` accepts three forms:
-```jsonc
-// Public URL (no auth, no paywall)
-{ "type": "url", "url": "https://example.com/headshot.jpg" }
-// Pre-uploaded asset (from `heygen asset create --file <path>`)
-{ "type": "asset_id", "asset_id": "<id>" }
-// Inline base64
-{ "type": "base64", "data": "<base64>", "media_type": "image/png" }
-```
-For when each is appropriate, see
-[`references/asset-routing.md`](asset-routing.md).
----
-## Response Shape
-All three types return:
-```jsonc
-{
-  "data": {
-    "avatar_item": {
-      "id": "<look_id>",         // ephemeral — the specific look
-      "group_id": "<group_id>"   // stable — the character identity
-    },
-    "avatar_group": { /* ... */ }
-  }
-}
-```
-- `id` is the **look_id** — what you pass downstream as `avatar_id` to
-  `create_video_agent` for video generation.
-- `group_id` is the **character identity** — stable across looks. Save
-  this in the AVATAR-<NAME>.md file. Always resolve fresh look_ids at
-  video time via `list_avatar_looks(group_id=<id>)` rather than caching
-  a specific look_id.
----
-## Identity Field → HeyGen Enum Mapping
-When building a prompt-based avatar, map identity attributes to these
-HeyGen enums:
-- **age**: Young Adult | Early Middle Age | Late Middle Age | Senior | Unspecified
-- **gender**: Man | Woman | Unspecified
-- **ethnicity**: White | Black | Asian American | East Asian | South East Asian | South Asian | Middle Eastern | Pacific | Hispanic | Unspecified
-- **style**: Realistic | Pixar | Cinematic | Vintage | Noir | Cyberpunk | Unspecified
-- **orientation**: square | horizontal | vertical
-- **pose**: half_body | close_up | full_body
----
-## Voice Selection (during avatar setup)
-After the avatar look is created, pair it with a voice. Two paths:
-### Path A — Voice Design (preferred)
-Find matching voices via semantic search using the Voice section from
-the AVATAR file. This searches HeyGen's full voice library. No new
-voices are generated and no quota is consumed.
-**Language matching:** The voice design prompt should specify the target
-language from `user_language`. Example for Japanese: `"A calm, warm
-female voice. Professional but approachable. Japanese speaker."` This
-ensures semantic search returns voices in the correct language.
-### Path B — Voice Browse (fallback)
-For manual catalog browsing:
-**MCP:** `list_voices(type=private)` then `list_voices(type=public, language=<lang>, gender=<gender>)`
-**CLI:**
-```bash
-heygen voice list --type private --limit 20
-heygen voice list --type public --engine starfish --language en --gender female --limit 20
-```
-**ALWAYS show a playable voice preview.** Each voice response includes
-`preview_audio_url` — share it before committing.
-**Handling missing/broken previews:** Some voices return bare `s3://`
-paths or `null`. When this happens: note "(no preview available)" and
-offer to generate a short TTS sample via `create_speech` (MCP) or
-`heygen voice speech create --text "<sample>" --voice-id <id>
---input-type text --language en --locale en-US` (CLI).

package/skills/heygen-avatar/references/troubleshooting.md DELETED Viewed

@@ -1,137 +0,0 @@
-# Known Issues & Troubleshooting
-## Weird Pauses / Unnatural Silence in Videos
-**Symptom:** Video has awkward pauses or breaks between sentences. Narrator stops speaking but video continues with dead air before next line.
-**Root Cause:** When Video Agent receives a script shorter than the target duration, it treats the script as verbatim speech and inserts silence/breaks to stretch it to the exact requested duration. It won't ad-lib or expand — it just pads with dead air.
-**Fix:** Add this directive to EVERY prompt:
-> "This script is a concept and theme to convey — not a verbatim transcript. You have full creative freedom to expand, elaborate, add examples, and fill the duration naturally. Do not pad with silence or pauses."
-This tells Video Agent it can expand the script naturally instead of treating it as a fixed speech transcript. Per Jerry Yan: "If you tell it it's not a script to be strictly followed but concept or theme or give it green light to expand the script it will do well."
-**Status:** Skill-side fix (prompt directive). HeyGen is also tuning the default behavior but the explicit directive is the reliable workaround.
----
-## Duration Variance (Expected Behavior)
-Video Agent controls final video timing internally. Duration accuracy ranges from 79-174% of target across testing. This is NOT a bug.
-**Mitigation:** Variable padding multipliers (Script):
-- ≤30s target: 1.6x padding
-- 31-119s target: 1.4x padding
-- ≥120s target: 1.3x padding
-With explicit `avatar_id`: ~97% duration accuracy average.
-Without `avatar_id`: ~80% accuracy average.
----
-## Frame Check: Video Agent Not Applying Framing
-If the Video Agent ignores the FRAMING NOTE or BACKGROUND NOTE and produces black bars, letterboxing, or mismatched framing:
-1. **Ensure the note is appended at the END of the prompt**, after all other content (script, style block, etc.). Video Agent processes instructions sequentially and late-prompt directives have the strongest effect.
-2. **Check that the correction note was actually appended.** Log the final prompt text and verify the FRAMING NOTE / BACKGROUND NOTE block is present.
-3. **photo_avatar does NOT need BACKGROUND NOTE.** Video Agent generates avatar + environment together for photo_avatars. Only append framing notes for orientation mismatches. Background notes are for studio_avatars with transparent/empty backgrounds only.
----
-## Stock Avatar Auto-Selection Unreliable
-When no `avatar_id` is provided, Video Agent uses narrator tags (`{{@narrator_l0ug91}}`) that sometimes fail to resolve during render.
-**Fix:** Always use explicit `avatar_id` from discovery. The only exception is Quick Shot mode where the user explicitly wants speed over reliability.
----
-## HTML URLs in files[] Rejected
-Video Agent rejects `text/html` content type in the `files[]` array. Web pages (blogs, docs sites, articles) must be handled via Path A (contextualize) only.
-**What works in files[]:** Direct file URLs (PDFs, images, videos) — but prefer download→upload→asset_id since CDN/WAF often blocks HeyGen's servers.
----
-## Avatar Not Ready for Video Generation
-**Symptom:** Video generation fails or produces errors immediately after creating a new avatar. The avatar exists in the HeyGen dashboard but videos referencing it fail.
-**Root Cause:** Avatar creation is asynchronous. `heygen avatar create` (and `create_photo_avatar` / `create_prompt_avatar` MCP tools) return success immediately, but the avatar image is still being processed. If you submit a video request before processing completes, it fails.
-**Detection:** Poll with `heygen avatar looks list --group-id <group_id>` (or MCP `list_avatar_looks`). The avatar is NOT ready until:
-- `preview_image_url` is non-null
-- `image_width` and `image_height` are non-zero
-At the group level (`heygen avatar list`), an unready avatar will have no `preview_image_url` on the group object.
-**Fix:** Poll every 10 seconds after creation, wait for preview URL to appear. Typical: 30-90s for photo avatars, 1-3 min for prompt avatars. Timeout at 5 min.
-**The heygen-avatar skill handles this automatically.** If you bypass the skill, you must implement this polling yourself.
----
-## Interactive Sessions Reliability
-Interactive sessions (created without `--wait` and iterated via `heygen video-agent send`) have known issues:
-- Sessions frequently stuck at `processing` status
-- `reviewing` state may never be reached
-- Follow-up messages fail with timing errors
-- Stop command may not trigger video generation
-**Recommendation:** Use one-shot mode for production. Interactive sessions documented for future use once HeyGen stabilizes the API.
----
-## Error Code → Action
-Stable CLI exit codes tell you what to do without parsing messages:
-| Exit | Class | Action |
-|------|-------|--------|
-| `0` | ok | Continue |
-| `1` | API / network | Retry with backoff. If persistent, inspect the structured stderr error envelope and re-run with the relevant `--help`, or contact HeyGen support. |
-| `2` | usage | You passed a bad flag. Run `--help` on the command, fix the args, retry. |
-| `3` | auth | Re-auth: `heygen auth login` or set `HEYGEN_API_KEY`. Verify with `heygen auth status`. |
-| `4` | timeout under `--wait` | Operation still running server-side. stdout contains the last successfully-polled resource (or may be empty if nothing completed yet); a video resource identifies itself as `.data.id`. Prefer the timeout error's `.error.hint` on stderr, which gives the exact resume command (e.g. `heygen video-agent get <id>` or `heygen video get <id>`). Do NOT re-submit. |
-Common API-error hints (surfaced in stderr envelope `{error:{code,message,hint}}`):
-- `402` / insufficient credits → tell the user their HeyGen plan is out of credits.
-- `403` / forbidden → the resource is not owned by the caller (wrong `group_id`, private avatar).
-- `404` / not found → ID is stale. Re-fetch via `heygen avatar list`, `heygen video-agent get`, etc.
----
-## Polling Cadence
-When `--wait` isn't an option (e.g., you want to return control to the user between polls), use a back-off schedule rather than a fixed interval:
-| Age of job | Poll interval |
-|------------|---------------|
-| 0–2 min | every 10s |
-| 2–5 min | every 30s |
-| 5–10 min | every 60s |
-| > 10 min | surface "taking longer than usual" once, keep polling at 60s, give up at 15 min |
-If a job is stuck at the same status for >5 min, that's a signal to surface a status update or check the dashboard.
-**Prefer `--wait`** on creation commands. It handles the polling internally and returns the final resource, or exits `4` on timeout with the exact resume command in the error's `.error.hint`.
----
-## Direct Video vs Video Agent — Which Endpoint?
-Two ways to generate a video. Different pricing, different trade-offs.
-| | **Direct Video** | **Video Agent** |
-|---|-------------------|-----------------|
-| Command / Tool | `heygen video create` / no MCP tool yet | `heygen video-agent create` / `create_video_agent` |
-| Input | Full script + avatar + voice + scene JSON | Prompt + optional avatar/voice/style |
-| Control | You author every scene | Video Agent plans scenes, pacing, motion |
-| Pricing | ~$0.0333/sec | ~$0.10/sec |
-| When to use | Deterministic multi-scene videos, tight control, bulk generation | Creative intros, messages, "make a video about X" requests |
-The default in this skill is **Video Agent** — it's what `heygen-video` is built around. Drop to Direct Video only for batch or highly scripted workflows where Agent's autonomy is overhead.

package/skills/heytea-doodle-poster/SKILL.md DELETED Viewed

@@ -1,132 +0,0 @@
----
-name: heytea-doodle-poster
-description: "Heytea Doodle Poster, Flavor Monster, and Desktop Pet: the method the original skill taught, run as an AICUT film — pages that draw any moment t, cut on tracks. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "Hchen1218/heytea-style"
----
-# Heytea Doodle Poster, Flavor Monster, and Desktop Pet
-## Running it in AICUT
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-Where the words below name another program's part, it becomes this:
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-Create unofficial visual work inspired by the playful HEYTEA poster language: rough black marks, awkward handmade shapes, generous white space, and restrained object-led storytelling.
-Do not add official HEYTEA logos, mascots, packaging marks, or claims of affiliation unless the user supplies authorized assets and explicitly requests their use.
-## Photo entry and routing
-Require and inspect an uploaded image before visual generation. Resolve the subject first:
-- If no usable subject is visible, stop and ask for one sharp, well-lit, unobstructed subject.
-- If several independent subjects are visible, give short numbered descriptions and ask which one to use. Do not silently choose.
-- Treat a container and its contents as one subject unless the user asks otherwise.
-When the user uploads a usable photo without saying what to make, offer exactly these three choices and do not generate or run environment checks yet:
-1. 生成带字版海报
-2. 生成不带字海报
-3. 生成一张风味小怪兽
-If the user already asked for a text poster, no-text poster, flavor monster, or both poster versions, enter that workflow directly without repeating the chooser. “两套都出” remains supported but is not a fourth default choice. An explicit 写实卡通桌宠 or `source-faithful` request remains supported but is not shown in the default three choices.
-## Ordinary poster
-Read `references/style-guide.md`; for `带字版`, also read `references/lettering-guide.md`.
-- Keep the photographed object recognizable and photographic. Do not cartoonize the full image.
-- Inspect `private-assets/reference-cutouts/asset-index.json` when it exists.
-- A text poster uses separate poster-base, title-construction-sheet, and title-layer steps. Use `scripts/build_title_reference_sheet.py` and `scripts/composite_title_layer.py` when applicable.
-- A no-text poster forbids all text and lets one primitive micro-worker action tell the story.
-- When making both versions, create two genuinely different concepts and compositions rather than toggling a title on one base image.
-Use `references/evaluation.md` for final review.
-## Static flavor-monster identity
-Read `references/desktop-pet-character-modes.md`, the identity stages of `references/desktop-pet-workflow.md`, and `references/mixed-media-style-guide.md`. Do not read or run the environment workflow yet.
-Build one best `flavor-monster` identity on white or warm white. Before drawing, complete the four contracts defined in `references/desktop-pet-character-modes.md`: a `source relation map`, `outline construction brief`, `face construction brief`, and `material layer map`. The photo controls those contracts; the public example and study boards may control only their explicitly assigned style or construction axis.
-Keep these identity gates in force:
-- at least one non-color source signal changes the outer body topology while remaining abstract and separate from exactly two black-line arms plus two black-line legs;
-- the default face is two clear eyes and one clear friendly mouth below them, using `readability > friendliness > identity distinctiveness > handmade irregularity`; experimental faces require an explicit request;
-- the body uses one heavy irregular structural boundary, while broad dry wax-crayon layers preserve source containment, accumulation, overlap, and top-layer position; paper-white is optional and must not sever those relations;
-- the public example and reference boards never supply a new silhouette, face layout, limb skeleton, object, text, or anatomical coordinates.
-Follow the mandatory two-stage construction and focused-repair rules in `references/desktop-pet-workflow.md`. Use `contact_sheet_single_pass_rough_line_v1.png` only for the black-line stage and `contact_sheet_crayon_layer_v1.png` only for the line-locked color stage, as defined in `references/mixed-media-style-guide.md` and the asset index.
-Approve the black-line master at full size, a representative 300% crop, and 120–140 px before adding color without changing any accepted black mark. Review the colored identity against `references/evaluation.md`, then ask for explicit identity approval or a focused revision. Do not generate a fusion poster, motion, runtime assets, or a package before approval. Approval establishes the canonical identity shared by later branches.
-After approval, ask whether to:
-1. 制作融合海报；
-2. 继续制作可运行桌宠；
-3. 两者都做。
-## Approved-monster fusion poster
-Read `references/monster-poster-workflow.md` plus the ordinary poster references needed for the requested variant. Ask whether the user wants 带字版、无字版或两套都做 unless already stated.
-Use the original uploaded photo and the approved canonical monster. Keep the photographed product unchanged and photographic; lock the monster's identity while adapting only its pose for one clear interaction. Text and no-text versions must use independent compositions.
-This branch never requires desktop-runner preflight. If the user selected both fusion poster and runnable pet, continue the poster branch even when the runner is missing or installation is declined.
-## Runnable desktop pet
-Read `references/desktop-pet-workflow.md`, `references/desktop-pet-environment.md`, `references/mixed-media-style-guide.md`, and `references/desktop-pet-pack.md`.
-- For an approved `flavor-monster`, run `python3 scripts/desktop_pet.py doctor --json --required-schema 3` only now, before motion generation. The older `scripts/check_desktop_pet_environment.py` entry is a shim for the same command. Do not pass `--probe-registry` unless diagnosing npm connectivity.
-- For an explicit `source-faithful` request, first complete its three-candidate identity workflow and obtain explicit canonical-identity approval; then run the same environment gate before motion generation. Source-faithful remains schema v2 and flavor-monster uses schema v3.
-- If preflight reports missing or outdated components, explain the exact plan and request consent immediately before installation or upgrade. Never silently install or replace software, bypass operating-system warnings, or enable launch-at-login.
-- Continue only after preflight reports `ready`. Then create the mode-specific motion set, request motion approval, and only after approval run `python3 scripts/desktop_pet.py pack <pet-dir>` to build, validate, and write the delivery folder. The older `build_desktop_pet_pack.py` / `validate_desktop_pet_pack.py` scripts remain callable.
-For schema-v1 migration, preserve the original pack, create a new v2 draft, add the four missing states, and require fresh motion approval. Never overwrite or silently activate the v1 pack.
-White backgrounds are for identity and motion review only. Runtime animation files require real alpha transparency.
-## Output boundary
-- Never describe exploratory image-model output as a finished pet pack.
-- Do not fabricate file paths, validation results, or runnable installers.
-- If visual generation is unavailable, return the staged prompt packet and state which artifacts remain ungenerated.
-- Do not save generation prompts as standalone project documents unless the user explicitly asks for prompt files.
-- Treat official-looking marks, private-study-only cutouts, and `quality: avoid-default` records as analysis-only.
-- Preserve user files and unrelated working-tree changes.
-Human visual approval is mandatory at both desktop-pet gates; automated validation cannot replace it.
-## Source
-Rewritten for AICUT from [`Hchen1218/heytea-style`](https://github.com/Hchen1218/heytea-style)
-(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/heytea-doodle-poster/references/desktop-pet-character-modes.md DELETED Viewed

@@ -1,103 +0,0 @@
-# Desktop-Pet Character Modes
-Read this reference for every desktop-pet request after resolving the photo subject and before extracting identity or generating candidates.
-## Mandatory mode choice
-Desktop-pet mode has two parallel character modes. Neither is a fallback for the other. They share the runtime, approval gates, and delivery format, but deliberately use different public pack protocols.
-If the user has not already selected a mode, stop before visual generation and ask:
-1. **写实卡通桌宠**：保留照片主体的原始轮廓与关键结构，把主体本身手绘角色化。
-2. **风味小怪兽桌宠**：提取照片的颜色、材质、配料和特征动作，重新设计成独立的小怪兽，不保留容器轮廓。
-Do not choose a default, infer the mode from whether the subject is food or drink, or generate both unless the user explicitly asks for both. If the user names one mode in the request, proceed without asking again.
-Record the chosen value as `source-faithful` or `flavor-monster` and keep it fixed through character approval, motion approval, and packaging. Changing mode requires a fresh character approval; it does not require a different runner.
-## Mode A: 写实卡通桌宠 (`source-faithful`)
-### Character identity
-- The photographed subject becomes the character body.
-- Preserve its outer silhouette, orientation, major internal divisions, one to three identifying colors, and two to four must-preserve details.
-- A container and its contents remain one visible unit by default.
-- Simplify photographic texture into the shared hesitant-line and mixed-media grammar, but do not replace the subject with an unrelated animal, mascot, or monster body.
-- Candidate differences come from face placement, limb proportions, structural crookedness, and stable temperament—not different source objects or action poses.
-### Action and behavior identity
-- Base `signature` and `play` on a real property of the subject: bubbles, wobble, crumbs, rolling, steam, melting, light, or another source-specific verb.
-- Let rigid objects move through tilt, hinge, roll, or appendage gesture; let liquids and soft foods move through slosh, squash, ripple, bubble, or settle.
-- Keep actions subordinate to source recognition. A pose must not redesign the container, label-free package, food shape, or object structure.
-## Mode B: 风味小怪兽桌宠 (`flavor-monster`)
-### Source DNA
-The photograph supplies flavor DNA rather than a body template. Separate what the static identity must prove from what later behavior must express.
-Extract visual identity DNA:
-- one to three identifying colors;
-- one or two ingredient/material cues, such as fruit cubes, pearls, foam, bubbles, crumbs, glaze, leaves, or transparency;
-- one required non-color structural memory from ingredient, material, source shape, or processing trace that can become an abstract silhouette feature. Use at least one and normally one or two ear-like fins, horns, crests, spines, tail buds, antennae, or comparable protrusions; color, texture, spots, and internal marks alone do not satisfy this requirement.
-Also record one source-specific motion verb as behavior DNA for the later action stage. It does not count toward the static identity minimum.
-Before drawing, write a compact internal identity brief. Use no more than three identifying visual source signals, but do not treat them as peers. First build a `source relation map`:
-`source signal → source role → relation → creature role → abstraction method → body attachment or material layer`
-Assign each signal exactly one source role: `primary-matrix`, `embedded-inclusion`, `surface-layer`, `deposit`, or `accent`. Record position and containment separately with `embedded-in`, `sits-on-top-of`, `accumulates-at`, and `overlaps-with`. Preserve hierarchy, containment, and position before abstraction. A color does not become an independent monster zone merely because it is visually distinct. For example, a pink drink with yellow fruit pieces settled inside it and a green topping above it maps to one pink `primary-matrix`, yellow `embedded-inclusion` signals that `accumulates-at` the bottom, and one green `surface-layer` that `sits-on-top-of` the matrix; it does not map to three peer color blocks.
-Use at least two kinds of visual identity DNA chosen from color, ingredient, and material. A generic monster whose only connection to the photo is a replaceable palette fails even when a motion verb has been recorded. Extend the brief with:
-- a source-derived body silhouette and center of gravity that do not copy the public example or retain the literal source object;
-- a `DNA → monster structure` map that names at least one non-color source signal, its abstract silhouette feature, how it avoids literal ingredient anatomy, and where it joins the body. The feature must alter the outer contour and remain legible at 120–140 px; a generic disk, dome, or blob with only recoloring or internal decoration fails;
-- an `example difference lock` that names the public example's facial-mark system and limb skeleton as discard-only anatomy, then declares a different facial-mark type/count/layout and different arm/leg attachment points, lengths, proportions, and resting geometry for the new identity. The example may guide line quality and cuteness, never anatomical coordinates or skeleton;
-- an `outline construction brief` that declares the source-derived body boundary and protrusions, line-weight hierarchy, and specific locations for short flat spots, shallow dents, blunt corners, hesitant bends, pressure jumps, dry breaks, overshoots, or slightly mismatched joins. Treat the boundary as one stroke system at every cross-section; allow only one or two short local retraces and keep continuous parallel travel below roughly ten percent of the complete path. The body boundary is the heaviest system; face and limbs remain thinner but visibly handmade;
-- a `face construction brief` that defaults to two unmistakable eyes on a readable eye level and one unmistakable friendly mouth below them. Apply `readability > friendliness > identity distinctiveness > handmade irregularity`. A viewer who has not read the brief must identify both eyes and the mouth at 120–140 px. Use only mild handmade differences in size, tilt, line weight, pressure, or terminals; do not require every face mark to bend, break, or jump pressure. Clear bean eyes, dot eyes, simple smiles, near-centered spacing, and U-like mouths are allowed when they remain hand-drawn rather than copied stock emoji. Single-eyed, mouthless, broken-hook, or otherwise experimental systems require an explicit user request. Reject realistic or shaded eyes, highlights, large chibi eyes, complex facial anatomy, and direct copies of existing emoji or the public example's face;
-- a `material layer map` that establishes a continuous primary matrix before assigning embedded inclusions, deposits, surface layers, accents, broad blunt dry wax-crayon travel, optional paper-white breathing space, and selected missed or faded edges. Preserve the `source relation map`: inclusions stay embedded, deposits keep their concentration or position, and surface layers stay spatially distinct while broad dry-wax overlap may create intermediate hues and depth. Paper-white has no minimum count and must not divide related layers into peer blocks. No layer may collapse into transparent marker, dense micro-patterns, smooth digital gradient, or one equal-density fill;
-- exactly two arms and two legs, including their black-line attachment points, lengths, proportions, and quiet resting pose. Source-derived ears, fins, horns, crests, spines, tail buds, antennae, or comparable silhouette features remain colored body topology and never count as, replace, or imitate one of the four limbs;
-- a cuteness check: the body must read as soft, compact, friendly, and animatable before it reads as strange;
-- hard exclusions for fleshy collapse, exposed or realistic tissue, slime, horror tendrils, corpse-like sagging, sharp grotesque anatomy, and other disturbing organic readings;
-- a stable floor anchor and source-specific motion verbs reserved for later behavior design;
-- a discard list for the complete cup, bottle, bowl, wrapper, rim, lid, straw, container wall, layered-liquid cross-section, pizza slice, mushroom, or other literal source-object silhouette whenever present.
-The brief guides generation; do not save the full generation prompt as a project document unless the user explicitly requests it.
-### Character identity
-- The first impression must be a cute, friendly, independent doodle creature; source recognition comes second through flavor DNA. A visually unpleasant or uncanny body fails even when its source mapping is accurate.
-- Use `examples/desktop-pet/pink-green-flavor-monster-v3/preview.png` only as the positive style anchor for HEYTEA-like cuteness and handmade looseness. Use `contact_sheet_single_pass_rough_line_v1.png`, assembled only from non-lettering HEYTEA source cutouts, for heavy boundary curves and lighter arm/leg curves; it supplies no object, face, text, or anatomy. Construct facial marks from the written face construction brief without any face-mark image board. Reserve `contact_sheet_crayon_layer_v1.png` for broad dry wax-crayon, paper tooth, and optional breathing space during the color stage; it supplies no color-zone structure or required gap count. Do not copy the public example's body topology, protrusion placement, facial-mark type/count/layout, limb attachment points, limb lengths or proportions, resting pose, or anatomical coordinates. A new silhouette with the same face-and-limb skeleton is still a copy and fails.
-- Derive the body's soft, compact silhouette and center of gravity from the source brief. Do not preserve a literal pizza slice, cup, mushroom, ingredient, container, or photographed food silhouette, and do not turn irregularity into flesh, slime, horror anatomy, or corpse-like collapse.
-- Draw exactly two arms and two legs as separate, open, crooked black doodle strokes. Each stroke must wander or bend along its full length and change pressure or thickness within the same mark, with restrained dry breaks, retracing, overshoots, or open joins. Keep them visibly black, light-to-thin, dry, slightly clumsy, and readable; reject smooth Bézier curves, constant-width monoline, superficial jitter on a clean vector path, colored strokes, tendrils, trailing body material, volumetric paws, mittens, feet, toes, or realistic joints.
-- Render the face exactly from the `face construction brief`; do not derive its anatomy from an image board or the public example.
-- Convert source colors, ingredients, and materials into crude flat marks, paper gaps, local crayon changes, and at least one contour-changing abstract monster feature. Acceptable roles include an ear-like fin, horn, crest, spine, tail bud, antenna, or another compact protrusion derived from the source; do not turn a mushroom, fruit, pearl, leaf, or topping into a recognizable realistic organ. Reject decorative ears or tails with no traceable source mapping.
-- Enclose the source-derived body and its monster protrusions with one semantically complete black structural stroke system. At every cross-section it reads as one mark rather than a parallel band, braid, rope, or outlined strip. It must be heavier than the face and limbs and change the underlying path through flat spots, shallow dents, blunt corners, hesitant bends, pressure jumps, dry breaks, overshoots, or slightly mismatched joins. Allow one or two short local retraces only; continuous parallel travel must stay below roughly ten percent of the complete boundary. Reject smooth equal-width contours, polished sticker borders, whole-loop mechanical doubling, repeated beaded stamps, and a clean vector skeleton with surface jitter.
-- Build color from the `material layer map`: lay down a coherent primary matrix, embed inclusions or deposits within it, keep surface layers spatially distinct, and use overlapping broad blunt matte wax-crayon passes to create intermediate hues and depth. Preserve granular drag, paper tooth, broken pressure, ragged ends, selected misses, faded ends, and slight boundary crossings. Paper-white breathing space is optional and has no minimum count; when present, it must support rather than sever the mapped relationships. Transparent marker, watercolor, pastel or oil-pastel smear, smooth digital fill or gradient, uniform noise, dense tiny strokes or loops, short hatching, or crosshatching fails.
-- Default to one best identity in a quiet identity-readable resting pose rather than a three-candidate board, but construct it in two locked stages: approve the black-line master at full size, a 300% detail crop, and 120–140 px, then add color behind it without changing any black mark. If one focused repair leaves a multi-track or smooth inherited outline, discard that inherited line skeleton and rebuild a fresh black-line master from the locked topology instead of stacking another edit. Lock the source-derived body, source relation map, heavy boundary, two black-line arms, two black-line legs, black-line face system, material layer map, stable temperament, scale, and ground anchor. Generate multiple directions only when the user explicitly asks for exploration.
-Write both sides of the model instruction: a positive cute flat-doodle definition and hard exclusions for container or literal food anatomy, smooth equal-width or sticker-like enclosing borders, colored or volumetric limbs, missing arms or legs, tendril substitution, realistic facial features, large chibi eyes, fleshy collapse, slime, horror anatomy, official marks, text, polished vector geometry, and glossy 3D treatment. Do not merely attach limbs to the photographed object.
-### Action identity
-- Use mark-led secondary motion: a crude flat mark, abstract protrusion, paper gap, or local crayon patch reacts before or after the whole body without becoming a literal organ.
-- Define 6–10 complete schema-v3 behaviors around the approved graphic identity rather than filling a fixed action-name checklist.
-- Include bindings for awake idle, sleep, click, pointer encounter, drag, release, and at least one ambient behavior.
-- Sleep must visibly enter, persist in a loop, and wake through an exit; exploration, cursor encounter, held, and drop recovery may also use explicit phases.
-- Give each behavior enough amplitude and internal progression to read as one story. Prefer fewer substantial behaviors over many tiny interchangeable gestures.
-- Flavor events such as a block-mark hiccup, one bubble, color ripple, or abstract-protrusion shake should arise from an approved mark or internal feature, not a generic prop.
-- Drag, fall, impact, rebound, and settle must preserve the monster's graphic identity and connect physically; the approved abstract protrusion or local mark may lag or settle, but the two black-line arms, two black-line legs, and black-line face system must remain stable.
-## Shared production contract
-Both character modes use:
-- the same environment preflight and installed shared runner, loaded only after canonical identity approval when the user chooses runnable motion;
-- the same black-skeleton then locked-color construction; `source-faithful` keeps its existing candidate use, while `flavor-monster` always approves one heavy-boundary line master before the relation-preserving material-layer pass;
-- the same explicit character-approval and motion-approval gates;
-- the same 120–140 px readability target, transparent runtime strips, version-aware builder and validator, and delivery folder.
-The public formats remain intentionally separate: `source-faithful` uses schema v2 with twelve required actions and optional `fall` / `touch`; `flavor-monster` uses schema v3 with 6–10 reachable behaviors and explicit phases. Both compile to one internal runtime model. Do not migrate existing v2 packs or duplicate the Electron runtime.