@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/heytea-doodle-poster/references/desktop-pet-environment.md

@@ -0,0 +1,122 @@
+# Desktop Pet Environment and Installation
+
+Read this reference only after the user has explicitly approved a canonical identity and chosen to continue into runnable desktop-pet motion. Static monster identities and fusion posters do not require this environment.
+
+## Required motion-branch gate
+
+Before generating any motion assets, run the read-only preflight:
+
+```bash
+python3 scripts/desktop_pet.py doctor --json --required-schema 3
+```
+
+The older `scripts/check_desktop_pet_environment.py` entry is a shim for `desktop_pet.py doctor`. Registry probing is opt-in via `--probe-registry`.
+
+Interpret the result:
+
+- `ready`: the installed runner meets the requested schema's minimum version.
+- `upgradeable`: a runner exists but is too old for the requested schema; show the exact in-place or side-by-side plan and request upgrade consent.
+- `installable`: the runner is missing, but the bundled source and local Node/npm toolchain can build it.
+- `needs-toolchain`: the runner is missing and Node.js 22.12.0+ or npm must be installed first.
+- `missing-source`: the skill package does not contain the runner source. Stop and report that the runtime cannot be installed from this package.
+- `unsupported`: stop. v1 supports only macOS and Windows.
+
+Do not begin motion generation until the preflight is resolved. Identity generation and approved-monster fusion posters may proceed without the runner. If the user selected both poster and runnable-pet outputs, a missing runner blocks only the motion and packaging branch. A user may decline installation and keep the approved static identity or continue the fusion poster, but do not promise a runnable desktop pet in that case.
+
+## Consent boundary
+
+The preflight is read-only and does not need confirmation. Installation changes the user's computer and always requires a concise confirmation immediately before execution.
+
+Tell the user:
+
+- what is missing;
+- what will be installed;
+- where the application will be placed;
+- whether Node.js will also be installed;
+- that macOS/Windows may display a security or permission prompt;
+- that launch-at-login remains off unless the user separately enables it.
+
+Never treat “make me a desktop pet” as permission to install software. Never silently run a package manager, accept a system prompt, change security settings, or enable launch-at-login.
+
+## Automatic repair after approval
+
+First inspect the exact plan:
+
+```bash
+python3 scripts/desktop_pet.py install --json-plan
+python3 scripts/desktop_pet.py install --json-plan --upgrade
+```
+
+`--json-plan` must use the same flags you intend to pass with `--yes` (`--upgrade`, `--mirror`, `--install-toolchain`, `--no-launch`). Otherwise the printed plan can disagree with what `install()` will do.
+
+After the user explicitly approves:
+
+```bash
+python3 scripts/desktop_pet.py install --yes
+```
+
+When Node.js/npm are also missing and the preflight reports Homebrew or winget:
+
+```bash
+python3 scripts/desktop_pet.py install --yes --install-toolchain
+```
+
+For an installed legacy runner that preflight marks `upgradeable`, explicit consent authorizes:
+
+```bash
+python3 scripts/desktop_pet.py install --yes --upgrade
+```
+
+If `npm ci` or Electron downloads fail because the default registry is unreachable, retry with `--mirror` (npmmirror):
+
+```bash
+python3 scripts/desktop_pet.py install --yes --mirror
+```
+
+The JSON plan includes `reuseCachedBuild`. When a previous local `dist/` bundle matches the current runtime source hash, installation copies that bundle and skips `npm ci` and electron-builder. `scripts/install_desktop_pet_runtime.py` is a shim for `desktop_pet.py install`.
+
+The JSON report identifies the installed runner as `runtimeScope: "user"` or `"system"`. The install plan exposes the matching `installMode`: `in-place-upgrade` for a per-user legacy runner and `user-side-by-side` for a system-wide legacy runner.
+
+The report also exposes `minimumNodeVersion`, `dependencyStatus`, `electronVersion`, and `electronBuilderVersion`. `dependencyStatus` is `missing`, `ready`, or `drifted`; the backward-compatible `dependenciesInstalled` field is true only when the installed Electron and builder exactly match the bundled lockfile contract.
+
+For `in-place-upgrade`, the upgrader verifies the new build, then asks the running app to quit, preserves it as a versioned backup beside the application, copies the new build atomically with rollback on copy failure, and leaves imported pets/settings in Application Support untouched. For `user-side-by-side`, it verifies the new build, then asks the system-wide runner to quit, leaves that installation unchanged, and installs the new runner in the per-user location without requesting administrator privileges or claiming to create a system-level backup.
+
+The script uses no shell interpolation. It refuses to replace a per-user installed application unless both `--yes` and `--upgrade` are supplied, never overwrites an existing backup (repeated refreshes receive a numbered backup), and installs new or side-by-side builds to:
+
+- macOS: `~/Applications/Doodle Desktop Pet.app`
+- Windows: `%LOCALAPPDATA%\Programs\Doodle Desktop Pet\Doodle Desktop Pet.exe`
+
+On macOS it can use Homebrew to install Node.js. On Windows it can use winget to install the Node.js LTS package. If the applicable package manager is absent, stop and give the user the official manual prerequisite rather than downloading or executing an arbitrary installer.
+
+## What gets repaired
+
+The approved installer may perform only the missing steps:
+
+1. install Node.js/npm through the detected trusted package manager when explicitly allowed;
+2. reuse a hash-matching local `dist/` bundle when one exists; otherwise run `npm ci` inside the bundled runner source when dependencies are absent or drifted;
+3. build only the current operating-system target, unless a matching cached bundle is reused;
+4. copy the unsigned local MVP into the per-user application directory, clear the macOS quarantine xattr on that local copy, and apply an ad-hoc signature so Finder does not mark it as damaged;
+5. launch the runner once for verification.
+
+A matching cached bundle is identified by a source hash over `src/**`, `package.json`, `package-lock.json`, and `scripts/after-pack.js`. The hash is stamped into the built app after a successful `--self-test`. Clearing quarantine applies only to the locally built copy the installer just wrote; it does not disable Gatekeeper, SIP, or SmartScreen.
+
+Before an old runner is stopped or any application is copied, the build must pass both layers of verification: the packaging hook parses `app.asar` and confirms `package.json` plus the declared main entry, then the built executable runs `--self-test` without creating a window, tray, or user-data state. `default_app.asar` is Electron's template fallback and is deliberately absent from a finished build; its absence is not a packaging failure.
+
+If the standard build fails with an archive-stream, `unzipper`, or `Invalid package` signature, the installer may retry exactly once. The retry runs Electron's bundled `install-electron` helper, then points electron-builder at the checksum-verified unpacked `node_modules/electron/dist` directory. It never deletes or mutates the user's global Electron cache. A second failure stops installation and returns structured stage, version, log-tail, fallback, artifact-check, Chinese `summary`, and `nextSteps` diagnostics. Network failures include an explicit `--mirror` retry suggestion.
+
+It does not:
+
+- install Linux support;
+- bypass Gatekeeper, SmartScreen, antivirus, or browser security warnings;
+- grant accessibility, screen-recording, camera, microphone, or other sensitive permissions;
+- enable launch-at-login;
+- replace a compatible runtime or silently delete the versioned backup;
+- claim that an unsigned local build is a notarized production release.
+
+## After installation
+
+Run the preflight again. Continue only when it reports `ready`. If installation succeeds but the current process cannot yet find a newly installed Node/npm, ask the user to reopen the terminal or Codex task, then rerun preflight. Do not repeat package-manager installation indefinitely.
+
+Once the role pack is built, import it through the runner. Installation is a one-time system step; future pets receive a lightweight delivery folder with the validated ZIP plus start/quit entrypoints. Never copy Electron, `node_modules`, or another full application into each role folder.
+
+The start entrypoint checks the installed runner's full semantic version against the pack schema before invoking `--open-pet <zip>`. Schema v3 currently requires 3.1.0 because phase grounding and display-edge floor policy are runtime features. It must report an actionable upgrade message instead of handing a newer pack to an older runner. A compatible single running instance validates, imports or refreshes that pack, activates it, and shows the pet. Commands that arrive while the runner is still initializing are queued until ready. The quit entrypoint invokes `--quit`, allowing settings and position to be saved before exit. Launchers never install or upgrade software silently.

package/skills/heytea-doodle-poster/references/desktop-pet-pack.md

@@ -0,0 +1,106 @@
+# Desktop Pet Pack v2 / v3
+
+Read this reference when exporting, validating, importing, or upgrading a desktop-pet pack.
+
+## Schema-v2 directory contract
+
+```text
+pet-id/
+├── pet.json
+├── preview.png
+└── animations/
+    ├── idle.webp
+    ├── walk.webp
+    ├── rest.webp
+    ├── happy.webp
+    ├── drag.webp
+    ├── land.webp
+    ├── wave.webp
+    ├── signature.webp
+    ├── curious.webp
+    ├── stretch.webp
+    ├── tiptoe.webp
+    ├── play.webp
+    ├── fall.webp        # optional runtime extension
+    └── touch.webp       # optional runtime extension
+```
+
+PNG is also accepted. Every animation is one horizontal strip with real alpha; each frame matches the declared canvas. `preview.png` is a human-facing review image and is not rendered in the overlay.
+
+## Manifest v2
+
+Keep the v1 field shape, set `schemaVersion` to `2`, declare all twelve actions, and default new characters to `defaultScale: 0.6`. Each action declares `file`, `frames`, `fps`, `loop`, and `mirrorable`. `walk` must be mirrorable. Recommended current-pet values are `idle` 4 frames at 4 FPS and non-looping, and `walk` 6 frames at 6 FPS.
+
+Required actions are `idle`, `walk`, `rest`, `happy`, `drag`, `land`, `wave`, `signature`, `curious`, `stretch`, `tiptoe`, and `play`.
+
+Recognized optional actions are `fall` and `touch`. A v2 pack remains valid without them; the runner falls back to `drag → land` and `wave`. Unknown action names remain invalid. If present, `fall` should loop and `touch` should be mirrorable.
+
+## Manifest v3
+
+Schema v3 is the public format for `flavor-monster`. It keeps the common identity, canvas, anchor, hitbox, palette, and scale fields, replaces `actions` with 6–10 freely named `behaviors`, and adds trigger `bindings`. Required bindings are `idle`, `ambient`, `sleep`, `click`, `pointer`, `drag`, and `release`.
+
+Packs using the current v3 grounding and physical-floor contract require runner 3.1.0 or newer.
+
+The optional common field `floorMode` chooses the physical bottom plane: `work-area` stays above the macOS Dock or Windows taskbar and remains the backward-compatible default; `display-edge` uses the true display edge for pets that should not appear suspended above an unused reserved strip.
+
+Each behavior contains one or more ordered phases. Every phase owns a PNG/WebP horizontal strip and declares:
+
+- a unique phase `id`, safe relative `file`, and `frames`;
+- exactly one timing form: `fps` or per-frame `durationsMs`;
+- `playback` as `once` or `loop`;
+- `completeOn` as `animation-finished`, `motion-finished`, `floor-impact`, `pointer-released`, `wake-requested`, or `timeout`;
+- optional `motion` as `walk`, `fall`, `cursor-approach`, or `cursor-return`;
+- a boolean `mirrorable`.
+- optional `grounding` as `floor` or `free`; floor phases align each visible frame's transparent-pixel bottom to `anchor.y`, while free phases preserve airborne or held poses.
+
+An optional v3 `cadence` object may define `idleIntervalMs`, `ambientIntervalMs`, `postEpisodeQuietMs`, `pointerDwellMs`, `pointerCooldownMs`, `dragThresholdPx`, `pointerResetsSleep`, and `profileMultipliers` (`quiet`, `balanced`, `lively`). Cadence is character data: the runner applies the profile multiplier only to autonomous timing and cooldowns; click, drag, sleep duration, and animation timing remain unscaled.
+
+A loop may not complete on `animation-finished`; it needs an explicit external exit. All behaviors must be reachable through bindings. Sleep declares inactivity delay and an automatic wake range, and its behavior must include a persistent wake-requested phase.
+
+## Invariants
+
+- `schemaVersion` is `2` or `3`; ids use lowercase ASCII letters, digits, and hyphens.
+- Canvas is 32–1024 px; anchor and hitbox stay inside it; palette has one to three `#RRGGBB` colors.
+- Every action or phase path is safe and relative, uses PNG or WebP, and has 1–24 frames. v2 uses 1–30 FPS; v3 may instead use per-frame durations.
+- Strip width is `canvas.width × frames`; height is `canvas.height`; every frame is non-empty and corners are transparent.
+- In schema v2, stable `idle` and `walk` body-center drift is at most 1 px and their grounded baseline drift is at most 1 px. In schema v3, use phase-level `grounding: "floor"` for variable-height poses; the runner normalizes each visible frame to the shared anchor.
+- `floorMode: "display-edge"` is appropriate only when the approved pet should sit on the actual screen frame; omit it to preserve Dock/taskbar avoidance.
+- `idle` visible-height variation is at most 1.5%; loop seams must not make a large silhouette jump.
+- At `defaultScale`, visible height should land near 120–140 px.
+- ZIP has one top-level directory named after the id and contains no traversal, symlink, encryption, or oversized members.
+
+## Review and build
+
+Before motion approval, create artifacts only:
+
+```bash
+python3 scripts/desktop_pet.py review path/to/pet-id
+```
+
+For v2, the required-only contact sheet is 3×4. For v3, the overview contains one cell per behavior and `behavior-timelines.png` shows phase boundaries and completion events. Both formats also produce `motion-preview.gif` and `frame-audit.png`, which places every frame on a contrasting dark background. After explicit approval, build, independently validate, and write the delivery folder in one step:
+
+```bash
+python3 scripts/desktop_pet.py pack path/to/pet-id
+```
+
+Defaults write the ZIP, review artifacts, and start/quit entrypoints under `generated-pets/`. Pass `--out`, `--review-dir`, and `--delivery-dir` to override. The older `build_desktop_pet_pack.py` / `validate_desktop_pet_pack.py` commands remain valid. Validation errors name the file and frame and include a one-line fix hint; `--json` is available on `validate_desktop_pet_pack.py`.
+
+For a non-technical-user delivery, `pack` already writes the platform folder. To target another OS:
+
+```bash
+python3 scripts/desktop_pet.py pack path/to/pet-id --delivery-platform windows
+```
+
+The delivery folder contains the ZIP, `preview.png`, `使用说明.txt`, and two lightweight entrypoints: `启动桌宠` passes `--open-pet` to the installed shared runner; `关闭桌宠` passes `--quit`. macOS uses executable `.command` files and Windows uses `.cmd` files. Do not place the Electron application, dependencies, imported runtime data, or a second copy of the runner in this folder.
+
+## v1 upgrade boundary
+
+The runner must never run, delete, or overwrite a schema-v1 pack. It lists v1 packs as needing upgrade and offers their folder. The Skill copies the original eight actions into a new draft, reloads the canonical identity, stabilizes old frames, generates the four new actions, asks for motion approval, and only then builds a new v2 ZIP. The v1 ZIP remains recoverable.
+
+## Runner contract
+
+The Electron source template imports validated v2 and v3 ZIPs and compiles both into one internal episode model. It keeps one active pet, uses alpha click-through, constrains movement to display work areas, and persists scale, activity level, cursor awareness, position, pause, visibility, topmost, and launch-at-login. Interactions preempt autonomous episodes; reduced-motion selects quiet behavior and disables autonomous exploration and cursor chase while preserving required drag-release recovery. v3 sleep remains in its loop until a wake request, and physical completion events advance walk, cursor, and fall phases. Right-clicking an opaque pet pixel opens the native pause/activity/size/switch/hide/quit menu; the tray remains the fallback when the pet is hidden.
+
+For v3, a pointer press is pending until it moves past `dragThresholdPx`: release before the threshold is one click, while movement past it is one drag/release chain. Pointer proximity does not count as sleep-resetting interaction when `pointerResetsSleep` is false.
+
+Do not copy `node_modules`, build output, imported packs, or user app data into the skill.

package/skills/heytea-doodle-poster/references/desktop-pet-workflow.md

@@ -0,0 +1,264 @@
+# Desktop Pet Workflow
+
+Read the identity stages of this reference for static character requests. Read the environment, motion, approval, and packaging stages only when the user chooses a runnable desktop pet.
+
+## Outcome
+
+Turn one photographed subject into an approved canonical character and, only when requested, a quiet runnable desktop companion recognizable at small size and importable into the bundled runner.
+
+This mode is a full illustration conversion. Unlike poster mode, it does not preserve photographic texture.
+
+## Stage 1: Subject gate
+
+Classify the input before prompt writing:
+
+- **No usable subject**: stop. Ask for a new image with one sharp, well-lit subject and a readable outline.
+- **Several independent subjects**: show short numbered descriptions, optionally with crop callouts when the image tool supports them, and ask which one to use.
+- **One subject**: proceed without another question.
+- **Container plus contents**: use the visible unit as one character by default. A cup and its drink, bowl and food, or bottle and water share one silhouette.
+
+Record a compact identity brief:
+
+- one to three source colors;
+- subject orientation and material regions;
+- two to four source features that can identify the result;
+- parts that may be simplified or translated;
+- a subject-specific motion idea.
+
+## Stage 2: Character-mode and identity-brief gate
+
+Read `desktop-pet-character-modes.md`. If the user has not already chosen a mode, ask whether they want:
+
+1. `source-faithful`（写实卡通桌宠）—the photographed subject remains the character body; or
+2. `flavor-monster`（风味小怪兽桌宠）—the photograph supplies flavor DNA for a newly designed creature.
+
+Stop before candidate generation until the mode is explicit. Do not recommend, default, or infer one from the subject category. When the request already says 写实卡通、保留原物形态、小怪兽, or otherwise makes the choice unambiguous, record it and continue without asking again.
+
+Extend the identity brief according to the selected mode:
+
+- `source-faithful`: record outer silhouette, major internal divisions, and must-preserve object/container details.
+- `flavor-monster`: complete the identity brief defined in `desktop-pet-character-modes.md`, including its source relation map, DNA-to-monster-structure map, example difference lock, outline and face briefs, material layer map, 2+2 inventory, ground anchor, cuteness check, discard list, and motion verb. That reference is the sole source of role taxonomy, face semantics, topology, and identity exclusions. Do not lock the source silhouette or save the full generation prompt unless the user explicitly requests a prompt file.
+
+## Stage 3: Identity design
+
+Before prompt writing, apply the stage-specific reference roles in `mixed-media-style-guide.md`. State each included image's role in the generation instruction and preserve the exclusions recorded there. The workflow must not promote a color-stage, motion-only, repair-only, or failure reference into the black-line stage.
+
+### Two-pass construction and repair
+
+For `source-faithful` mixed-media drinks and soft foods, retain the existing two-pass construction. For `flavor-monster`, two-pass construction is mandatory because topology, black-line anatomy, source relations, and dry pigment layers are independent acceptance axes:
+
+1. **Line master**: generate the three `source-faithful` candidates, or the one `flavor-monster` master, in black on warm white with no color or shading. For `flavor-monster`, use only the approved line-stage board and the locked topology, outline, face, and 2+2 contracts from `desktop-pet-character-modes.md`. Review at full size, a representative 300% crop, and 120–140 px; a failed line master cannot advance.
+2. **Line-locked crayon pass**: use the accepted line master as the edit target. Preserve every black stroke, gap, face, limb, attachment, and position exactly. Add color behind the line using the approved source relation and material layer maps plus the color-stage boards from `mixed-media-style-guide.md`. Do not redraw, complete, smooth, thin, thicken, or replace any line while coloring. Review source relations, material coherence, and small-size legibility before approval.
+
+Keep both construction artifacts. The colored result is not allowed to bypass a failed line master. If one focused line repair still inherits a multi-track, smooth, or sticker-like legacy path, discard the inherited line skeleton and generate a fresh black-line master from the locked topology; do not apply another stacked line edit.
+
+For `source-faithful`, generate one review board with three full-body candidates on white or warm white. All three must use the same source at the same scale, in the same neutral front-facing stance, with arms relaxed and feet on one shared ground anchor. A candidate board compares identity design, not animation poses.
+
+For `flavor-monster`, generate exactly one best two-stage identity on white or warm white unless the user explicitly asks for multiple directions. Use a quiet identity-readable resting pose, generous negative space, and one shared ground anchor. The first impression must be a cute, friendly, independent flat doodle creature; source recognition comes second through the identity brief. The public example supplies cuteness and looseness only, while the photo-derived brief supplies the new body topology.
+
+Apply the complete `flavor-monster` identity contract from `desktop-pet-character-modes.md`; do not restate or weaken its source-DNA, topology, face, limb, material, or cuteness decisions here.
+
+Keep constant in both modes:
+
+- source palette;
+- hesitant black line structure whose important strokes meander along their full length and vary pressure or thickness within the same mark, with occasional dry breaks, retracing, open joins, and overshoot; for `flavor-monster`, use a heavy irregular body boundary and thinner but still variable face plus 2+2 limbs;
+- structurally crooked geometry rather than a clean template with a wobble filter;
+- source-appropriate material layering; for `source-faithful`, retain its existing mixed-media choices. For `flavor-monster`, use broad blunt dry wax-crayon as the dominant color tool, preserve the source relation map, and use optional paper-white only when it supports rather than severs those relations.
+
+For `source-faithful`, also keep the source outer silhouette, major internal divisions, and recognizable container, topping, label-free package, or ingredient details. Vary only:
+
+- placement and size of the minimal crooked face;
+- short arm and leg proportions;
+- structural crookedness and stable temperament: quiet, curious, or gently clumsy, expressed without changing pose.
+
+For `flavor-monster`, lock:
+
+- the approved four briefs and their mapped body topology;
+- the example difference lock, 2+2 attachment geometry, pose, scale, temperament, and ground anchor;
+- the source-specific motion verb for later behavior design;
+- the discard list and every passed visual acceptance axis.
+
+Do not use waving, walking, leaning, jumping, sleeping, or other action differences to create the illusion of three concepts. If removing the pose would make the candidates indistinguishable, the board has failed.
+
+In `source-faithful`, the subject is the body; do not put it in an animal costume or replace it with a monster. In `flavor-monster`, the creature is the body; do not retain a complete cup, bowl, bottle, wrapper, pizza slice, mushroom, ingredient, or other literal source silhouette. In both modes avoid detailed clothing, uniform heavy outlines, smooth digital gradients, solid textureless fills, polished vector outlines, sticker borders, kawaii rendering, glossy 3D shading, realistic faces, text, watermarks, or official brand marks. For `flavor-monster`, also reject colored, volumetric, missing, or tendril-replaced limbs and any fleshy, slimy, corpse-like, sharp, or horrific body reading. Cuteness should come from soft compact proportions, material marks, sparse black doodle features, and friendly temperament rather than large eyes.
+
+For `source-faithful`, ask the user to choose candidate 1, 2, or 3, or request a focused revision. For `flavor-monster`, ask the user to approve the single concept or request a focused revision of it. Repair only the failed axis: topology, source relation or dependent material layer, copied anatomy, black-line construction, pigment, face readability, or limb inventory. Lock every passing axis. If one focused line repair preserves the old multi-track or smooth skeleton, keep the valid topology, relation map, palette, material layers, optional breathing space, attachments, pose, and anchor but start a fresh black-line master rather than editing the failed line again. Do not infer approval from silence, and do not turn a rejected monster concept into a three-candidate board unless the user requests broader exploration.
+
+Before presenting the identity, perform an appendage inventory. `source-faithful` candidates default to exactly two arms and two clearly visible legs. Every `flavor-monster` must have exactly two separate open black-line arms and two separate open black-line legs. Broken-line style may create gaps, but it must not change the 2+2 count, merge a limb into the body, replace a limb with a tendril or colored stroke, or turn it into a volumetric paw, mitten, foot, toe cluster, or realistic joint.
+
+### Identity-scale gate
+
+Inspect the generated identity at full resolution, inspect representative boundary, face, and limb crops at 300%, then render or view it at 120–140 px. Apply the observable desktop-pet pass and failure criteria in `evaluation.md`. A failed axis returns to the focused-repair rule above; passing axes remain locked.
+
+White or warm-white paper is review-only. Approval locks the identity but does not authorize a paper background in runtime assets, which must use real alpha transparency.
+
+### Pose-only consolidation
+
+If a `source-faithful` board, or a user-requested multi-direction monster board, already has one shared identity and differs only through pose:
+
+1. State that these are motion sketches, not valid identity variants; do not force a meaningless three-way choice.
+2. Use the most neutral standing pose to create one canonical master with fixed source geometry or monster graphic grammar, face placement, appendage count and proportions, line behavior, media zoning, and ground anchor.
+3. Treat the other poses only as motion references. A raised arm may inform `wave`; a tilt may inform `happy` or `land`.
+4. Obtain explicit approval of the consolidated identity before motion generation. Keep the canonical master as the sole identity reference for every action.
+
+## Stage 4: Identity approval and continuation gate
+
+Do not infer approval from silence or from a request that originally mentioned a desktop pet. Explicit identity approval locks one canonical master; it does not authorize motion generation, environment installation, or poster generation.
+
+For an approved `flavor-monster`, ask the user to choose:
+
+1. 制作融合海报；
+2. 继续制作可运行桌宠；
+3. 两者都做。
+
+If the user chooses a fusion poster, route that branch to `monster-poster-workflow.md` and ask for 带字版、无字版或两套都做 unless already specified. The poster branch does not use the runner environment gate.
+
+If the user chooses a runnable pet, or explicitly requested a `source-faithful` runnable pet and has now approved its canonical identity, continue to Stage 5. If both branches were selected, they proceed independently: a blocked runtime branch must not block the static fusion poster.
+
+## Stage 5: Runnable-branch environment gate
+
+Only after canonical identity approval and explicit selection of a runnable desktop pet, read `desktop-pet-environment.md` and run the read-only preflight:
+
+```bash
+python3 scripts/desktop_pet.py doctor --json --required-schema 3
+```
+
+If anything is missing, show one concrete repair plan and ask for installation or upgrade consent immediately before making that change. After approval, fill only the missing components, rerun preflight, and stop the motion branch if it still does not report `ready`. If the user declines, keep the approved static identity and any fusion-poster branch available without promising runnable output.
+
+This system gate is separate from both human visual approval gates. It must pass before motion generation, but it must never run merely to create a static monster or fusion poster.
+
+## Stage 6: Motion design
+
+After character approval, make a consistent action model sheet. Use the approved candidate as the only identity reference.
+
+For `flavor-monster`, this is the first stage where `contact_sheet_figure_actions_v2.png` may be passed as a positive reference. It controls gesture economy and primitive limb movement only; the approved canonical master remains the sole identity source and the action board must not redesign the color mass, face, marks, or appendage inventory.
+
+Before drawing actions, record a compact canonical lock from the master: selected character mode, black-line facial marks and coordinates, exactly two black-line arms and two black-line legs with their attachment points and lengths, outer silhouette or color-mass proportions, defining object geometry or monster graphic features, color/material zones, foot anchor, and the characteristic amplitude of line waviness. Pose references may change gesture but never override this lock.
+
+For `source-faithful`, keep the public schema-v2 action set:
+
+| State | Visual purpose | Runtime trigger | Art expectation |
+|---|---|---|---|
+| `idle` | Breathing and occasional blink | Default loop | 2–4 key frames; runner adds subtle bob |
+| `walk` | Short floor movement | Autonomous movement | 4–6 frames; faces right and may be mirrored |
+| `rest` | Sitting or sleeping | Long inactivity | 3–4 frames; quiet pose with optional Zzz overlay |
+| `happy` | Acknowledges affection | Single click | 3–5 frames; readable at small size |
+| `drag` | Reacts to being held | Pointer drag | 2–3 frames; tucked limbs, no distress |
+| `land` | Recovers after release | Drag release | 3–5 frames; squash then settle |
+| `wave` | Rare autonomous greeting | Low-frequency ambient action | 3–5 frames; one short limb gesture |
+| `signature` | Expresses subject identity | Low-frequency ambient action | 3–6 frames; bubbles, wobble, crumbs, roll, steam, or another subject-specific verb |
+| `curious` | Looks around | Cursor-near or ambient | 3–4 frames; small eye/head shift without body drift |
+| `stretch` | Releases tension | Ambient | 4–5 frames; full readable stretch and settle |
+| `tiptoe` | Peers upward | Cursor-near or ambient | 3–4 frames; intentional vertical lift without lateral drift |
+| `play` | Entertains itself | Ambient | 4–6 frames; interacts with a subject-specific internal feature |
+
+Interpret these v2 states through source identity:
+
+- Object physics and source-specific verbs lead. Preserve the source silhouette and structure through every action; use bubbles, wobble, crumbs, roll, steam, melt, light, or another real property for `signature` and `play`.
+
+Optional runtime-extension actions stay compatible with schema v2:
+
+| State | Visual purpose | Runtime trigger | Art expectation |
+|---|---|---|---|
+| `fall` | Bridges a high drag release into `land` | Release above the floor | 3–5 looping frames; held/tucked pose → airborne pose → landing anticipation; no floor line |
+| `touch` | Gently acknowledges a nearby cursor | End of one bounded cursor chase | 4–6 frames; neutral → reach toward one side → retract → neutral; mirrorable |
+
+For `flavor-monster`, define 6–10 schema-v3 behaviors; do not pad the set to twelve. Every required binding must resolve to one behavior, and every behavior must be reachable from a binding. The current eight-behavior reference is:
+
+| Behavior | Phases | Purpose |
+|---|---|---|
+| `awake-story` | one complete awake episode | Neutral life with one readable internal beat |
+| `explore-walk` | `start → walk-loop → stop` | One bounded autonomous exploration |
+| `sleep-cycle` | `sleep-enter → sleeping-loop → wake-exit` | Persistent sleep without snapping to neutral |
+| `affection-click` | one complete response | Acknowledges one click |
+| `cursor-encounter` | `notice → approach → touch → retreat → settle` | One bounded cursor meeting and return |
+| `held` | `grab-enter → held-loop` | Continues until pointer release |
+| `drop-recover` | `fall-loop → impact → rebound → settle` | Connects gravity impact to recovery |
+| `fruit-hiccup` | one complete flavor event | Expresses source DNA with larger amplitude |
+
+Use per-phase PNG/WebP strips. A phase declares either fixed `fps` or one `durationsMs` value per frame, never both. `once` phases normally finish on animation; loops must have an explicit external exit such as motion completion, floor impact, pointer release, wake request, or timeout. Mark grounded phases with `grounding: "floor"` so the runner aligns each frame's visible bottom to the fixed foot anchor; use `grounding: "free"` for held or airborne phases. Reuse approved frames by splitting and ping-ponging where the boundary is clean; do not redraw approved motion merely to satisfy a file layout.
+
+Choose the physical floor separately from the drawing baseline. Keep the default `work-area` when a pet must avoid the Dock/taskbar. Use manifest `floorMode: "display-edge"` when the approved composition explicitly sits on the screen frame and the reserved system strip would make it look suspended.
+
+When replacing earlier actions, the newest explicitly approved action family is the style baseline. Match its line weight, waviness, media zoning, opacity, face system, and limb construction; do not average old and new styles together. For transition-linked groups (`drag → fall → land`, `walk → touch → walk`), review adjacent end frames side by side and make each boundary share a compatible silhouette.
+
+Use handcrafted/model-generated frames for silhouette-changing poses. Let the runtime supply mirroring, translation, subtle breathing, light sway, heart/Zzz particles, and squash/stretch.
+
+## Stage 7: Motion approval
+
+Provide both for either mode:
+
+- a labeled contact sheet showing every action or behavior at one consistent scale;
+- a phase timeline with enter/loop/exit boundaries for schema v3;
+- a looping preview that plays the full set without hiding identity drift;
+- a dark-background frame audit of every phase.
+
+Review before asking for approval:
+
+1. Does every state still look like the chosen candidate?
+2. Are the face, limbs, palette, line weight, and object features stable?
+3. Do the feet share a consistent ground anchor?
+4. Are loops free of obvious jumps or clipped pixels?
+5. Are actions readable around a 120–140 px default desktop size?
+6. Does the character remain quiet rather than hyperactive or disruptive?
+
+If one state fails, regenerate that state only. Do not rerun the full set unless the identity system itself is wrong.
+
+Ask for explicit motion approval. Package only after approval.
+
+## Stage 8: Package and validate
+
+After motion approval, export transparent animation strips, then build, validate, and write the delivery folder in one step:
+
+```bash
+python3 scripts/desktop_pet.py pack <pet-dir>
+```
+
+`prepare` and `review` are available when strips still need normalization or when you only need contact-sheet / timeline / GIF / frame-audit artifacts. The older `build_desktop_pet_pack.py` and `validate_desktop_pet_pack.py` scripts remain callable.
+
+Return the review artifacts, validated ZIP, manifest summary, and delivery folder. For v3, keep cadence, gesture, per-phase grounding (`floor` or `free`), and any explicit display-edge floor policy in the manifest. The shared Electron runner is installed once; each pet delivery contains only its pack, preview, start/quit entrypoints, and short usage note.
+
+## Generation prompt frame
+
+Use the uploaded photo and approved candidate as references. Adapt details to the subject rather than copying this wording mechanically:
+
+```text
+Create a coherent desktop-pet animation strip for the approved character.
+Preserve exactly the same silhouette, one-to-three-color palette, minimal crooked face,
+appendage inventory, structurally crooked hand-redrawn geometry, hesitant mixed-weight pen,
+and source-appropriate hand color. Preserve the approved mode-specific media zoning in every frame.
+[source-faithful: the photographed subject remains the body and keeps its object structure.]
+[flavor-monster: the approved creature remains the body and keeps its heavy irregular black
+structural boundary, source relation map, layered broad dry wax-crayon matrix/inclusions/surface layers,
+optional breathing space, clear friendly two-eye-and-mouth black-line face, exactly two open black-line arms,
+exactly two open black-line legs, and abstract flavor marks;
+do not reintroduce a complete source container silhouette.]
+Transparent background, no white rectangle, no text, no logo, no watermark, no costume,
+no new accessories, no polished vector line.
+
+Action: [state and one clear verb].
+Frames: [count], laid out left to right on a single horizontal strip.
+Keep one fixed canvas per frame and one fixed foot anchor. Do not crop motion.
+```
+
+Generate each state as a separate strip so a failed action can be replaced without changing the others.
+
+Every generated cell must have a clear empty gutter. No limb, color patch, motion mark, floor line, or neighboring character may cross the cell boundary. After conversion, build `frame-audit.png` on a contrasting dark background and inspect every frame—not only the representative contact-sheet frame. Detached side marks, partial neighboring limbs, pale rectangles, and checkerboard residue fail the motion gate.
+
+Ambient actions should remain readable for roughly 1.5–3 seconds at runtime. Prefer 2–4 FPS for hand-drawn key poses; a higher FPS does not create smoothness when the strip contains only four to six distinct drawings. The first and last pose should settle toward the same neutral identity so transitions do not snap.
+
+## Default behavior personality
+
+The bundled runner implements quiet companionship:
+
+- idle is dominant;
+- walking is short and infrequent;
+- wave and signature actions are rare;
+- rest begins after prolonged inactivity;
+- click and drag responses preempt ambient actions;
+- no hunger, feeding, chat, sound, cursor theft, window manipulation, or prank behavior.
+- stable idle never continuously redraws or moves the window; v3 characters may declare a longer 24–36-second idle interval in `cadence`;
+- v3 ambient checks and cooldowns are character data, with the current monster using a 15–25-second check, 60-second hiccup cooldown, and 140-second walk cooldown at the balanced baseline;
+- cursor proximity may trigger one bounded interaction episode: move toward the cursor by at most 80 px, play `touch`, then return to the exact pre-trigger x position. Lock the target at trigger time; never continuously follow, capture input, or request accessibility permissions.
+- releasing a dragged pet above the floor plays `fall` while the window descends monotonically, then `land`; never snap directly to the ground.
+- for v3, a press becomes `held` only after the pointer crosses the manifest drag threshold; a stationary release is click-only, and pointer proximity does not reset the sleep clock unless the manifest opts in.