feat(skills): bundle BitFun skin authoring skill

src/crates/assembly/core/builtin_skills/create-bitfun-skin/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: create-bitfun-skin
+description: Inspect the current BitFun Appearance contract and author, repair, package, or validate sparse .bitfun-appearance skins. Use when Codex needs to discover registered scenes/components/parts/states/facets, check Style IR properties or renderer tokens, initialize or inspect a package, diagnose import failures, verify a skin against a BitFun checkout, or choose a bundled style example for design-specific guidance.
+---
+
+# BitFun Appearance Authoring
+
+Use this Skill as the authority for what a BitFun skin may change and how that change is represented. Let the user's assets, product direction, and the selected example determine the visual design.
+
+The bundled registry and package references define capabilities. Files under `examples/` define optional style choices; they never expand the contract or prescribe coverage for another skin.
+
+## Route the task
+
+- For a new or repaired package, read [authoring-workflow.md](references/authoring-workflow.md) and [package-contract.md](references/package-contract.md).
+- For renderer configuration, also read [renderer-contracts.md](references/renderer-contracts.md).
+- For generated video or WebP assets, also read [media-quality-policy.md](references/media-quality-policy.md).
+- For a style-specific design, load only the closest example after reading the parent workflow.
+- For import failures, inspect the issue path, query that surface, and repair the sparse manifest instead of copying another package.
+- For BitFun contract changes, synchronize the registry before changing examples or skins.
+
+## Discover the exposed surface
+
+Run commands from this Skill directory:
+
+```powershell
+python scripts/bitfun_appearance.py contract list components
+python scripts/bitfun_appearance.py contract list scenes
+python scripts/bitfun_appearance.py contract list renderers
+python scripts/bitfun_appearance.py contract show components <component-id>
+python scripts/bitfun_appearance.py contract show scenes <scene-id>
+python scripts/bitfun_appearance.py contract properties
+python scripts/bitfun_appearance.py contract tokens css
+python scripts/bitfun_appearance.py contract tokens widget
+```
+
+Only author registered surfaces, Parts, facets, states, renderer adapters, tokens, and Style IR properties returned by these commands. A Part descriptor may further restrict its allowed properties.
+
+A component owns only the Parts returned for that component. Nested visual owners expose their own component ids and must be styled through those ids. Do not infer Parts from DOM structure, another skin, or an example surface plan.
+
+Surface-level states may use an `ancestorPart` selector rooted at `root`. Define the state rule using the registered state id; do not reproduce host selectors in the package.
+
+Important independent owners include `toolbar-mode`, `floating-mini-chat`, `session-menu`, `composer-voice-input`, `miniapp-bubble-welcome`, `session-title-config`, `assistant-card`, `workspace-item`, `external-mcp-overview`, `miniapp-customize-panel`, `user-message-edit-composer`, `voice-input-diagnostics`, `flow-chat-turn-rail`, and `copyable-text-preview`. Query each owner before styling it.
+
+The following Parts are not registered and must not be used:
+
+- `toolbar-mode.input`
+- `toolbar-mode.sessionMenu`
+- `floating-mini-chat.input`
+- `floating-mini-chat.inputBar`
+- `floating-mini-chat.sessionMenu`
+
+## Author a sparse package
+
+Initialize the smallest valid overlay:
+
+```powershell
+python scripts/bitfun_appearance.py init <project-dir> --id <id> --name "<name>" --mode <light-or-dark>
+```
+
+Edit `<project-dir>/appearance.json` and declare only the values the skin needs to change. BitFun merges the package over its built-in light or dark Appearance.
+
+Packages may contain PNG, JPEG, WebP, and GIF images. MP4 or WebM is allowed only through top-level `backgroundMedia`, and every video requires an image poster. CSS files, selectors, markup, scripts, fonts, remote URLs, SVG, and executable content are unsupported.
+
+## Select a style example
+
+Currently bundled:
+
+| Example | Load when | Do not inherit blindly |
+| --- | --- | --- |
+| [cinematic-animated-wallpaper](examples/cinematic-animated-wallpaper/SKILL.md) | Animated character artwork, source-derived glass materials, image-led cards, or illustrated dialogs | Its asset roles, crop defaults, palette, and 43-component/7-scene surface selection |
+
+Read [style-example-contract.md](references/style-example-contract.md) before adding or restructuring an example. An example is a design recipe validated against the registry, not a second contract snapshot.
+
+## Validate importability
+
+```powershell
+python scripts/bitfun_appearance.py validate <project-dir>
+python scripts/bitfun_appearance.py build <project-dir> --output <skin>.bitfun-appearance
+python scripts/bitfun_appearance.py validate <skin>.bitfun-appearance
+python scripts/bitfun_appearance.py inspect <project-or-archive>
+```
+
+When a BitFun checkout is available, verify with the production registry, Validator, Compiler, and packaged-video display-dimension probe:
+
+```powershell
+python scripts/verify_host.py <bitfun-repo> <skin>.bitfun-appearance --report <host-verification.json> --strict-warnings
+```
+
+Standalone validation proves package and bundled-registry compatibility. Host verification proves the selected checkout accepts and compiles the package. Neither proves runtime visual quality; import the skin and inspect the actual surfaces.
+
+## Reuse deterministic support
+
+Example authors may import:
+
+- `scripts/build_support.py` for JSON, hashing, package initialization, validation, archive creation, host verification, build-record checks, and runtime checklist creation.
+- `scripts/media_support.py` for video probing, contact sheets, robust frame extraction, normalized crops, WebP output, VP9 encoding, preview sheets, and host video limits.
+
+Keep style-specific asset roles, crop decisions, palettes, material construction, renderer choices, surface selection, and runtime checks inside the example.
+
+## Maintain the registry
+
+Treat the bundled registry as the offline authority. Confirm it before targeting a checkout:
+
+```powershell
+python scripts/sync_registry.py <bitfun-repo> --check
+```
+
+Refresh it only from a clean checkout after BitFun changes Appearance descriptors:
+
+```powershell
+python scripts/sync_registry.py <bitfun-repo>
+```
+
+Do not hand-edit `references/appearance-registry.json`. Use `--allow-dirty` only for local investigation, never for a distributed snapshot.

src/crates/assembly/core/builtin_skills/create-bitfun-skin/examples/cinematic-animated-wallpaper/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: create-bitfun-cinematic-wallpaper-skin
+description: Apply the cinematic animated-wallpaper style recipe to a BitFun Appearance skin. Use after loading the parent create-bitfun-skin Skill when the user provides animated character artwork and wants a host-managed video background, source-derived glass materials, image-led cards, illustrated dialogs, reproducible builds, or cinematic drift checks.
+---
+
+# Cinematic animated-wallpaper recipe
+
+Load the parent `create-bitfun-skin` Skill first. The parent registry and package references define what can be changed; this example defines one optional visual strategy.
+
+Do not reuse this example's 43-component/7-scene coverage, asset roles, crop defaults, palette, opacity, or material choices unless they fit the user's artwork and intent. Its [surface-plan.json](references/surface-plan.json) is an example style selection validated against one registry revision, not a list of all current Appearance surfaces.
+
+Read [style-playbook.md](references/style-playbook.md) for visual decisions and [palette-contract.md](references/palette-contract.md) before creating a custom palette.
+Read the parent [media-quality-policy.md](../../references/media-quality-policy.md) before overriding video or WebP quality.
+
+## Style strategy
+
+This recipe uses:
+
+- a host-managed VP9 WebM background with an image poster;
+- source-derived artwork for floating surfaces, sidebars, cards, and dialogs;
+- translucent cinematic materials over the artwork;
+- a semantic palette shared by Style IR and renderer adapters;
+- broad surface coverage suitable for an immersive character-led skin.
+
+Keep the built-in Appearance for any owner that does not benefit from this treatment. Query the parent registry before adding, removing, or changing a selected surface.
+
+## Output layout
+
+Keep the importable project isolated from source and report files:
+
+```text
+<skin-root>/
+  package/
+    appearance.json
+    assets/
+      background.webm
+      floating.webp
+      sidebar.webp
+      card-detail.webp
+      card-portrait.webp
+      dialog.webp
+      preview.webp
+  sources/
+    palette.json
+    surface-plan.json
+  contact-sheet.png
+  asset-preview-sheet.png
+  <skin-id>.bitfun-appearance
+  host-verification.json
+  skin-build.json
+  runtime-checklist.json
+```
+
+Validate and build only `<skin-root>/package`. Reports and source files inside that directory invalidate the project.
+
+## Choose a source frame
+
+Generate only the timestamped contact sheet:
+
+```powershell
+python examples/cinematic-animated-wallpaper/scripts/build_cinematic_skin.py contact `
+  --source <animated-wallpaper.mp4> `
+  --output <skin-root>
+```
+
+Inspect `contact-sheet.png`, select a frame time, and decide normalized crops. Do not continue with blind crops.
+
+## Create a palette
+
+Copy [default-palette.json](references/default-palette.json) outside the Skill and tune it to the source artwork. Keep every required semantic key and six-digit hex value.
+
+The recipe maps the palette into cinematic materials plus CSS, Widget, Monaco, xterm, Mermaid, and Canvas renderer settings. The parent Skill does not prescribe these mappings for other styles.
+
+## Build the recipe
+
+Run from the parent Skill directory:
+
+```powershell
+python examples/cinematic-animated-wallpaper/scripts/build_cinematic_skin.py build `
+  --source <animated-wallpaper.mp4> `
+  --output <skin-root> `
+  --id <skin-id> `
+  --name "<Skin name>" `
+  --frame-time <seconds> `
+  --palette <palette.json> `
+  --bitfun-repo <bitfun-repo>
+```
+
+The thin recipe entrypoint combines cinematic asset generation and manifest construction with the parent's generic build support. It initializes the package, generates previews and assets, copies resolved recipe inputs, scaffolds the manifest, validates project and archive, runs strict host verification, and writes the reproducibility record.
+
+Production host warnings fail by default. Use `--allow-warnings` only for diagnosis.
+
+The default `--video-quality auto` tries codec-lossless VP9 only for small workloads, otherwise starts at CRF 20 and adapts only when the encoded file exceeds the host limit. The default `--static-quality-mode auto` tries lossless WebP before a quality fallback. Use `--video-quality lossless` only when exceeding 64 MiB should be treated as a hard failure; use `--video-crf` to reproduce a known fixed encoding.
+
+Inspect `asset-preview-sheet.png`. Re-run `build --force` with adjusted crop arguments when any role is poorly framed.
+
+## Rebuild and check
+
+```powershell
+python examples/cinematic-animated-wallpaper/scripts/build_cinematic_skin.py rebuild `
+  --output <skin-root>
+
+python examples/cinematic-animated-wallpaper/scripts/build_cinematic_skin.py check `
+  --output <skin-root>
+```
+
+Build records use `bitfun.appearance.recipe-build` and identify this recipe.
+
+`skin-build.json` records the requested policy, every attempted encoding, and the selected codec-lossless/CRF or WebP quality result. `check` verifies source, palette, surface-plan, manifest and archive drift, package validity, and current host compatibility. Add `--skip-host-verify` only for an offline check.
+
+## Recipe implementation
+
+- [cinematic_recipe.py](scripts/cinematic_recipe.py) owns palette interpretation, materials, renderers, asset declarations, and manifest generation.
+- [build_assets.py](scripts/build_assets.py) owns cinematic asset roles and their crop, tint, brightness, and blur decisions.
+- [build_cinematic_skin.py](scripts/build_cinematic_skin.py) is the thin command entrypoint.
+- Parent `scripts/build_support.py` owns generic package and verification lifecycle operations.
+- Parent `scripts/media_support.py` owns generic probing, extraction, crop, encoding, and preview primitives.
+
+Use [scaffold_cinematic.py](scripts/scaffold_cinematic.py) only when generating or checking the cinematic manifest without the full build.
+
+## Runtime inspection
+
+After importing the package, inspect at minimum:
+
+- normal workbench and collapsed navigation;
+- detached Toolbar Mode and in-app floating mini chat with long conversations;
+- Skills, MiniApp gallery, Agents, and Insights views;
+- Settings, archived sessions, and keyboard shortcuts;
+- terminal navigation, bottom terminal, files, and auxiliary panels;
+- generic and dedicated dialogs;
+- text over calm and bright animation frames;
+- reduced-motion poster fallback.
+
+Record evidence in `runtime-checklist.json`. `skin-build.json` keeps `runtimeVisualInspection: false` until a real import is inspected; compiler validation does not replace runtime inspection.

src/crates/assembly/core/builtin_skills/create-bitfun-skin/examples/cinematic-animated-wallpaper/references/default-palette.json

@@ -0,0 +1,21 @@
+{
+  "schema": "bitfun.appearance.cinematic-palette",
+  "schemaVersion": 1,
+  "id": "cold-cinematic",
+  "colors": {
+    "background": "#08111f",
+    "surface": "#102235",
+    "surfaceElevated": "#182b3c",
+    "text": "#edf7fa",
+    "textSecondary": "#c5d6dc",
+    "textMuted": "#8aa2ab",
+    "textDisabled": "#60757c",
+    "accent": "#52e5f5",
+    "accentStrong": "#2fc4d7",
+    "accentContrast": "#041416",
+    "info": "#78a9ff",
+    "success": "#7dcc9c",
+    "warning": "#e2b96b",
+    "danger": "#e47b74"
+  }
+}

src/crates/assembly/core/builtin_skills/create-bitfun-skin/examples/cinematic-animated-wallpaper/references/palette-contract.md

@@ -0,0 +1,37 @@
+# Cinematic palette contract
+
+Use a semantic palette to generate materials and renderer settings. Palette
+files use this shape:
+
+```json
+{
+  "schema": "bitfun.appearance.cinematic-palette",
+  "schemaVersion": 1,
+  "id": "cold-cinematic",
+  "colors": {
+    "background": "#08111f",
+    "surface": "#102235",
+    "surfaceElevated": "#182b3c",
+    "text": "#edf7fa",
+    "textSecondary": "#c5d6dc",
+    "textMuted": "#8aa2ab",
+    "textDisabled": "#60757c",
+    "accent": "#52e5f5",
+    "accentStrong": "#2fc4d7",
+    "accentContrast": "#041416",
+    "info": "#78a9ff",
+    "success": "#7dcc9c",
+    "warning": "#e2b96b",
+    "danger": "#e47b74"
+  }
+}
+```
+
+Every color is required and must be a six-digit hex value. `background`,
+`surface`, and `surfaceElevated` drive translucent materials. `accent` drives
+focus, borders, and primary highlights. Semantic status colors remain distinct
+from the primary accent.
+
+Prefer colors sampled from the source artwork. Preserve readable contrast and
+keep Monaco and xterm backgrounds opaque. The scaffold derives alpha values;
+do not put alpha channels in the palette.