cue-ai 0.3.0

package/resources/skills/skills/design/industrial-brutalist-ui/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: industrial-brutalist-ui
+description: >-
+  Use when user asks for "brutalist", "Swiss design", "terminal UI", "tactical/military HUD", "blueprint", or "industrial" interfaces. Rigid grids, extreme type contrast, monospace, halftones/scanlines.
+---
+
+# SKILL: Industrial Brutalism & Tactical Telemetry UI
+
+## 1. Skill Meta
+**Name:** Industrial Brutalism & Tactical Telemetry Interface Engineering
+**Description:** Advanced proficiency in architecting web interfaces that synthesize mid-century Swiss Typographic design, industrial manufacturing manuals, and retro-futuristic aerospace/military terminal interfaces. This discipline requires absolute mastery over rigid modular grids, extreme typographic scale contrast, purely utilitarian color palettes, and the programmatic simulation of analog degradation (halftones, CRT scanlines, bitmap dithering). The objective is to construct digital environments that project raw functionality, mechanical precision, and high data density, deliberately discarding conventional consumer UI patterns.
+
+## 2. Visual Archetypes
+The design system operates by merging two distinct but highly compatible visual paradigms. **Pick ONE per project and commit to it. Do not alternate or mix both modes within the same interface.**
+
+### 2.1 Swiss Industrial Print
+Derived from 1960s corporate identity systems and heavy machinery blueprints.
+*   **Characteristics:** High-contrast light modes (newsprint/off-white substrates). Reliance on monolithic, heavy sans-serif typography. Unforgiving structural grids outlined by visible dividing lines. Aggressive, asymmetric use of negative space punctuated by oversized, viewport-bleeding numerals or letterforms. Heavy use of primary red as an alert/accent color.
+
+### 2.2 Tactical Telemetry & CRT Terminal
+Derived from classified military databases, legacy mainframes, and aerospace Heads-Up Displays (HUDs).
+*   **Characteristics:** Dark mode exclusivity. High-density tabular data presentation. Absolute dominance of monospaced typography. Integration of technical framing devices (ASCII brackets, crosshairs). Application of simulated hardware limitations (phosphor glow, scanlines, low bit-depth rendering).
+
+## 3. Typographic Architecture
+Typography is the primary structural and decorative infrastructure. Imagery is secondary. The system demands extreme variance in scale, weight, and spacing.
+
+### 3.1 Macro-Typography (Structural Headers)
+*   **Classification:** Neo-Grotesque / Heavy Sans-Serif.
+*   **Optimal Web Fonts:** Neue Haas Grotesk (Black), Inter (Extra Bold/Black), Archivo Black, Roboto Flex (Heavy), Monument Extended.
+*   **Implementation Parameters:**
+    *   **Scale:** Deployed at massive scales using fluid typography (e.g., `clamp(4rem, 10vw, 15rem)`).
+    *   **Tracking (Letter-spacing):** Extremely tight, often negative (`-0.03em` to `-0.06em`), forcing glyphs to form solid architectural blocks.
+    *   **Leading (Line-height):** Highly compressed (`0.85` to `0.95`).
+    *   **Casing:** Exclusively uppercase for structural impact.
+
+### 3.2 Micro-Typography (Data & Telemetry)
+*   **Classification:** Monospace / Technical Sans.
+*   **Optimal Web Fonts:** JetBrains Mono, IBM Plex Mono, Space Mono, VT323, Courier Prime.
+*   **Implementation Parameters:**
+    *   **Scale:** Fixed and small (`10px` to `14px` / `0.7rem` to `0.875rem`).
+    *   **Tracking:** Generous (`0.05em` to `0.1em`) to simulate mechanical typewriter spacing or terminal matrices.
+    *   **Leading:** Standard to tight (`1.2` to `1.4`).
+    *   **Casing:** Exclusively uppercase. Used for all metadata, navigation, unit IDs, and coordinates.
+
+### 3.3 Textural Contrast (Artistic Disruption)
+*   **Classification:** High-Contrast Serif.
+*   **Optimal Web Fonts:** Playfair Display, EB Garamond, Times New Roman.
+*   **Implementation Parameters:** Used exceedingly sparingly. Must be subjected to heavy post-processing (halftone filters, 1-bit dithering) to degrade vector perfection and create textural juxtaposition against the clean sans-serifs.
+
+## 4. Color System
+The color architecture is uncompromising. Gradients, soft drop shadows, and modern translucency are strictly prohibited. Colors simulate physical media or primitive emissive displays.
+
+**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.**
+
+### If Swiss Industrial Print (Light):
+*   **Background:** `#F4F4F0` or `#EAE8E3` (Matte, unbleached documentation paper).
+*   **Foreground:** `#050505` to `#111111` (Carbon Ink).
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). This is the ONLY accent color. Used for strike-throughs, thick structural dividing lines, or vital data highlights.
+
+### If Tactical Telemetry (Dark):
+*   **Background:** `#0A0A0A` or `#121212` (Deactivated CRT. Avoid pure `#000000`).
+*   **Foreground:** `#EAEAEA` (White phosphor). This is the primary text color.
+*   **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). Same red, same rules.
+*   **Terminal Green (`#4AF626`):** Optional. Use ONLY for a single specific UI element (e.g., one status indicator or one data readout) — never as a general text color. If it doesn't serve a clear purpose, omit it entirely.
+
+## 5. Layout and Spatial Engineering
+The layout must appear mathematically engineered. It rejects conventional web padding in favor of visible compartmentalization.
+
+*   **The Blueprint Grid:** Strict adherence to CSS Grid architectures. Elements do not float; they are anchored precisely to grid tracks and intersections.
+*   **Visible Compartmentalization:** Extensive utilization of solid borders (`1px` or `2px solid`) to delineate distinct zones of information. Horizontal rules (`<hr>`) frequently span the entire container width to segregate operational units.
+*   **Bimodal Density:** Layouts oscillate between extreme data density (tightly packed monospace metadata clustered together) and vast expanses of calculated negative space framing macro-typography.
+*   **Geometry:** Absolute rejection of `border-radius`. All corners must be exactly 90 degrees to enforce mechanical rigidity.
+
+## 6. UI Components and Symbology
+Standard web UI conventions are replaced with utilitarian, industrial graphic elements.
+
+*   **Syntax Decoration:** Utilization of ASCII characters to frame data points.
+    *   *Framing:* `[ DELIVERY SYSTEMS ]`, `< RE-IND >`
+    *   *Directional:* `>>>`, `///`, `\\\\`
+*   **Industrial Markers:** Prominent integration of registration (`®`), copyright (`©`), and trademark (`™`) symbols functioning as structural geometric elements rather than legal text.
+*   **Technical Assets:** Integration of crosshairs (`+`) at grid intersections, repeating vertical lines (barcodes), thick horizontal warning stripes, and randomized string data (e.g., `REV 2.6`, `UNIT / D-01`) to simulate active mechanical processes.
+
+## 7. Textural and Post-Processing Effects
+To prevent the design from appearing purely digital, simulated analog degradation is engineered into the frontend via CSS and SVG filters.
+
+*   **Halftone and 1-Bit Dithering:** Transforming continuous-tone images or large serif typography into dot-matrix patterns. Achieved via pre-processing or CSS `mix-blend-mode: multiply` overlays combined with SVG radial dot patterns.
+*   **CRT Scanlines:** For terminal interfaces, applying a `repeating-linear-gradient` to the background to simulate horizontal electron beam sweeps (e.g., `repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.1) 2px, rgba(0,0,0,0.1) 4px)`).
+*   **Mechanical Noise:** A global, low-opacity SVG static/noise filter applied to the DOM root to introduce a unified physical grain across both dark and light modes.
+
+## 8. Web Engineering Directives
+1.  **Grid Determinism:** Utilize `display: grid; gap: 1px;` with contrasting parent/child background colors to generate mathematically perfect, razor-thin dividing lines without complex border declarations.
+2.  **Semantic Rigidity:** Construct the DOM using precise semantic tags (`<data>`, `<samp>`, `<kbd>`, `<output>`, `<dl>`) to accurately reflect the technical nature of the telemetry.
+3.  **Typography Clamping:** Implement CSS `clamp()` functions exclusively for macro-typography to ensure massive text scales aggressively while maintaining structural integrity across viewports.

package/resources/skills/skills/design/kitty-visualize/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: kitty-visualize
+description: Use when user asks to "visualize", "show me", "draw", "render", "diagram", "picture this", "layout", or "open in kitty/another window" — for diagrams, ASCII layouts, tmux pictures, dependency graphs, or image previews. Renders to a temp file and opens detached kitty so it does NOT clutter the chat. Default visualization surface for this user.
+metadata:
+  type: design-tool
+---
+
+# kitty-visualize
+
+The user wants visualizations on a **separate kitty window**, not inline in the chat.
+
+Default rule: when a user request resolves to producing a diagram, ASCII layout, dependency graph, tmux/pane picture, fleet topology, or image preview — **do not** dump it in the chat response. Render it to a temp file under `/tmp/claude-viz/` and spawn a detached kitty window pointed at that file. Confirm in chat with ONE short line containing the path.
+
+## When the trigger fires
+
+User intent keywords:
+- "visualize", "visualization", "show me a diagram", "draw it"
+- "render", "picture", "layout", "topology"
+- "open it in kitty", "another window", "not in the chat"
+- Any explicit "make me a chart / diagram / graph"
+
+If the user wants a **textual** answer with a small inline ASCII sketch (e.g. "what does the dir tree look like" → 5 lines of tree), keep it inline — that is not a visualization. The skill applies when the artifact is the *point*.
+
+## How to render
+
+### 1. Pick the artifact type
+
+| Artifact | File ext | Viewer |
+| --- | --- | --- |
+| ASCII / Unicode diagram | `.txt` | `kitty --hold less -R <file>` |
+| Markdown with code blocks | `.md` | `kitty --hold less -R <file>` (or glow if available) |
+| Single image (PNG, JPG, SVG) | `.png` / `.svg` | `kitty +kitten icat --hold <file>` |
+| Mermaid / Graphviz source | render first with `mmdc` / `dot -Tpng`, then icat | |
+
+For ASCII layouts (the most common case here) **always use the `.txt` path** — readable in less, scrollable, copy-friendly.
+
+### 2. Write the file
+
+```bash
+mkdir -p /tmp/claude-viz
+TS=$(date +%Y%m%d-%H%M%S)
+FILE=/tmp/claude-viz/viz-${TS}-<short-label>.txt
+cat > "$FILE" <<'EOF'
+<diagram content>
+EOF
+```
+
+Pick a short kebab-case label that describes the picture (`fleet-panes`, `ph13-waves`, `coolify-topology`). Never overwrite an existing viz file — the timestamp prevents that.
+
+### 3. Spawn kitty detached
+
+```bash
+setsid kitty --title "claude-viz: <label>" --hold \
+  less -R "$FILE" </dev/null >/dev/null 2>&1 &
+disown 2>/dev/null || true
+```
+
+Why each flag:
+- `setsid` + `&` + `disown` — detach so kitty survives the parent shell exiting.
+- `--title` — so the user can find the window in their taskbar / picker.
+- `--hold` — keep the window open after `less` exits (Ctrl-C, `q`).
+- `less -R` — `-R` passes ANSI colors through (box-drawing chars and color codes both render).
+- `</dev/null` — don't inherit the agent shell's stdin.
+
+If kitty is **not on PATH**, fall back to printing a single-line: `"kitty not installed; saved to $FILE"` and exit — do NOT inline-dump the diagram.
+
+### 4. Confirm in chat
+
+One line, no preview:
+
+```
+kitty window opened: <FILE>
+```
+
+That's it. No "here's what I drew", no inline copy of the same diagram, no markdown headings.
+
+## What NOT to do
+
+- Do not also paste the diagram into the chat. The whole point is to keep chat clean.
+- Do not open kitty *attached* (foreground) — it would block the agent shell and the user's terminal.
+- Do not use temp files outside `/tmp/claude-viz/`; that directory is the agreed parking lot.
+- Do not pre-clean `/tmp/claude-viz/` between turns. The user may want to re-open an older viz.
+- Do not call `kitty +kitten icat` for plain ASCII text — `less -R` is faster and scrollable.
+- Do not invent diagrams when the user asks a textual question. Trigger ONLY when the artifact is what they want.
+
+## Examples
+
+**User**: "visualize the fleet panes"
+→ write `/tmp/claude-viz/viz-20260513-222600-fleet-panes.txt` with the 6-pane grid
+→ `setsid kitty --title "claude-viz: fleet-panes" --hold less -R … &`
+→ chat: `kitty window opened: /tmp/claude-viz/viz-20260513-222600-fleet-panes.txt`
+
+**User**: "show me the ph13/14/15 dep graph in another window"
+→ write `.txt` with the wave-by-wave dependency graph
+→ spawn kitty as above
+→ chat: one line
+
+**User**: "what files are in this dir?"
+→ Not a visualization. Reply textually. Do NOT trigger this skill.
+
+**User**: "render the coolify topology as an image"
+→ Use `dot -Tpng` → `kitty +kitten icat --hold` flow.
+
+## Cleanup
+
+The user owns `/tmp/claude-viz/`. Don't remove anything from it. If they ask to clean up, suggest `rm /tmp/claude-viz/viz-*.txt` and let them run it.

package/resources/skills/skills/design/minimalist-ui/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: minimalist-ui
+description: >-
+  Use when user asks for "minimalist", "editorial", "Notion-style", or "ultra-flat" interfaces. Warm monochrome, serif/sans contrast, bento, muted pastels. Bans Inter/Roboto, gradients, neon, glassmorphism.
+---
+
+# Protocol: Premium Utilitarian Minimalism UI Architect
+
+## 1. Protocol Overview
+Name: Premium Utilitarian Minimalism & Editorial UI
+Description: An advanced frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.
+
+## 2. Absolute Negative Constraints (Banned Elements)
+The AI must strictly avoid the following generic web development defaults:
+- DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces.
+- DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons".
+- DO NOT use Tailwind's default heavy drop shadows (e.g., `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
+- DO NOT use primary colored backgrounds for large elements or sections (e.g., no bright blue, green, or red hero sections).
+- DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
+- DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
+- DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper icons or clean SVG primitives.
+- DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
+- DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.
+
+## 3. Typographic Architecture
+The interface must rely on extreme typographic contrast and premium font selection to establish an editorial feel.
+- Primary Sans-Serif (Body, UI, Buttons): Use clean, geometric, or system-native fonts with character. Target: `font-family: 'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`.
+- Editorial Serif (Hero Headings & Quotes): Target: `font-family: 'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`. Apply tight tracking (`letter-spacing: -0.02em` to `-0.04em`) and tight line-height (`1.1`).
+- Monospace (Code, Keystrokes, Meta-data): Target: `font-family: 'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`.
+- Text Colors: Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous `line-height` of `1.6` for legibility. Secondary text should be muted gray (`#787774`).
+
+## 4. Color Palette (Warm Monochrome + Spot Pastels)
+Color is a scarce resource, utilized only for semantic meaning or subtle accents.
+- Canvas / Background: Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`.
+- Primary Surface (Cards): `#FFFFFF` or `#F9F9F8`.
+- Structural Borders / Dividers: Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`.
+- Accent Colors: Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds.
+  - Pale Red: `#FDEBEC` (Text: `#9F2F2D`)
+  - Pale Blue: `#E1F3FE` (Text: `#1F6C9F`)
+  - Pale Green: `#EDF3EC` (Text: `#346538`)
+  - Pale Yellow: `#FBF3DB` (Text: `#956400`)
+
+## 5. Component Specifications
+- Bento Box Feature Grids:
+  - Utilize asymmetrical CSS Grid layouts.
+  - Cards must have exactly `border: 1px solid #EAEAEA`.
+  - Border-radius must be crisp: `8px` or `12px` maximum.
+  - Internal padding must be generous (e.g., `24px` to `40px`).
+- Primary Call-To-Action (Buttons):
+  - Solid background `#111111`, text `#FFFFFF`. 
+  - Slight border-radius (`4px` to `6px`). No box-shadow. 
+  - Hover state should be a subtle color shift to `#333333` or a micro-scale `transform: scale(0.98)`.
+- Tags & Status Badges:
+  - Pill-shaped (`border-radius: 9999px`), very small typography (`text-xs`), uppercase with wide tracking (`letter-spacing: 0.05em`).
+  - Background must use the defined Muted Pastels.
+- Accordions (FAQ):
+  - Strip all container boxes. Separate items only with a `border-bottom: 1px solid #EAEAEA`.
+  - Use a clean, sharp `+` and `-` icon for the toggle state.
+- Keystroke Micro-UIs:
+  - Render shortcuts as physical keys using `<kbd>` tags: `border: 1px solid #EAEAEA`, `border-radius: 4px`, `background: #F7F6F3`, using the Monospace font.
+- Faux-OS Window Chrome:
+  - When mocking up software, wrap it in a minimalist container with a white top bar containing three small, light gray circles (replicating macOS window controls).
+
+## 6. Iconography & Imagery Directives
+- System Icons: Use "Phosphor Icons (Bold or Fill weights)" or "Radix UI Icons" for a technical, slightly thicker-stroke aesthetic. Standardize stroke width across all icons.
+- Illustrations: Monochromatic, rough continuous-line ink sketches on a white background, featuring a single offset geometric shape filled with a muted pastel color.
+- Photography: Use high-quality, desaturated images with a warm tone. Apply subtle overlays (`opacity: 0.04` warm grain) to blend photos into the monochrome palette. Never use oversaturated stock photos. Use reliable placeholders like `https://picsum.photos/seed/{context}/1200/800` when real assets are unavailable.
+- Hero & Section Backgrounds: Sections should not feel empty and flat. Use subtle full-width background imagery at very low opacity, soft radial light spots (`radial-gradient` with warm tones at `opacity: 0.03`), or minimal geometric line patterns to add depth without breaking the clean aesthetic.
+
+## 7. Subtle Motion & Micro-Animations
+Motion should feel invisible — present but never distracting. The goal is quiet sophistication, not spectacle.
+- Scroll Entry: Elements fade in gently as they enter the viewport. Use `translateY(12px)` + `opacity: 0` resolving over `600ms` with `cubic-bezier(0.16, 1, 0.3, 1)`. Use `IntersectionObserver`, never `window.addEventListener('scroll')`.
+- Hover States: Cards lift with an ultra-subtle shadow shift (`box-shadow` transitioning from `0 0 0` to `0 2px 8px rgba(0,0,0,0.04)` over `200ms`). Buttons respond with `scale(0.98)` on `:active`.
+- Staggered Reveals: Lists and grid items enter with a cascade delay (`animation-delay: calc(var(--index) * 80ms)`). Never mount everything at once.
+- Background Ambient Motion: Optional. A single, very slow-moving radial gradient blob (`animation-duration: 20s+`, `opacity: 0.02-0.04`) drifting behind hero sections. Must be applied to a `position: fixed; pointer-events: none` layer. Never on scrolling containers.
+- Performance: Animate exclusively via `transform` and `opacity`. No layout-triggering properties (`top`, `left`, `width`, `height`). Use `will-change: transform` sparingly and only on actively animating elements.
+
+## 8. Execution Protocol
+When tasked with writing frontend code (HTML, React, Tailwind, Vue) or designing a layout:
+1. Establish the macro-whitespace first. Use massive vertical padding between sections (e.g., `py-24` or `py-32` in Tailwind).
+2. Constrain the main typography content width to `max-w-4xl` or `max-w-5xl`.
+3. Apply the custom typographic hierarchy and monochromatic color variables immediately.
+4. Ensure every card, divider, and border adheres strictly to the `1px solid #EAEAEA` rule.
+5. Add scroll-entry animations to all major content blocks.
+6. Ensure sections have visual depth through imagery, ambient gradients, or subtle textures — no empty flat backgrounds.
+7. Provide code that reflects this high-end, uncluttered, editorial aesthetic natively without requiring manual adjustments.

package/resources/skills/skills/design/png-alpha-cleaner/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: "png-alpha-cleaner"
+description: >-
+  Use when user says "clean PNG alpha", "remove transparent fringe", or "fix PNG edges". Alpha-channel cleanup.
+---
+
+# PNG Alpha Cleaner
+
+Use this for logo/image fixes like "make this actually a PNG", "transparent background", "remove checkerboard", or "PNG has no alpha".
+
+## Fast Path
+
+Run the bundled script instead of re-deriving masks by hand:
+
+```bash
+python3 ~/.codex/skills/png-alpha-cleaner/scripts/fix_png_alpha.py INPUT.png --in-place --preview-color '#202020' --preview-color '#ff00ff'
+```
+
+For non-destructive output:
+
+```bash
+python3 ~/.codex/skills/png-alpha-cleaner/scripts/fix_png_alpha.py INPUT.png --output OUTPUT.png --preview-color '#202020'
+```
+
+## Workflow
+
+1. Confirm what is wrong:
+   - `file INPUT`
+   - `identify -format '%m %w %h %[channels]\n' INPUT`
+2. If the file is RGB-only or has baked checkerboard/background pixels, run `fix_png_alpha.py`.
+3. Inspect a preview on a dark or magenta background when edges matter.
+4. Verify before claiming done:
+   - `file OUTPUT` says `PNG image data`.
+   - `identify -format '%[channels]\n' OUTPUT` includes alpha (`srgba` or `rgba`).
+   - A background corner reads transparent, for example `srgba(0,0,0,0)`.
+
+## Script Behavior
+
+- Uses ImageMagick plus Python stdlib only; no Pillow, NumPy, or network.
+- Backs up in-place edits under `/tmp/png-alpha-cleaner-backups/...`.
+- Detects already-transparent PNGs and normalizes them without destroying alpha.
+- Removes light/neutral edge-connected backgrounds and baked checkerboards.
+- Applies a small morphology pass to remove thin checkerboard leftovers.
+
+## Tuning
+
+If logo highlights are being removed, lower cleanup:
+
+```bash
+python3 ~/.codex/skills/png-alpha-cleaner/scripts/fix_png_alpha.py INPUT.png --output OUTPUT.png --open-radius 2 --min-light 228
+```
+
+If checkerboard leftovers remain, increase cleanup:
+
+```bash
+python3 ~/.codex/skills/png-alpha-cleaner/scripts/fix_png_alpha.py INPUT.png --output OUTPUT.png --open-radius 5 --min-light 214
+```

package/resources/skills/skills/design/png-alpha-cleaner/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "PNG Alpha Cleaner"
+  short_description: "Fix fake PNG transparency fast"
+  default_prompt: "Use $png-alpha-cleaner to make this logo a real transparent PNG and verify RGBA output."
+
+policy:
+  allow_implicit_invocation: true

package/resources/skills/skills/design/png-alpha-cleaner/scripts/fix_png_alpha.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""Create a real transparent PNG from logos with baked light/checker backgrounds."""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import datetime as dt
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+def tool(name: str) -> str:
+    found = shutil.which(name)
+    if not found:
+        raise SystemExit(f"missing required tool: {name}")
+    return found
+
+
+def image_tools() -> tuple[str, str]:
+    identify = tool("identify")
+    convert = shutil.which("magick") or tool("convert")
+    return identify, convert
+
+
+def run(args: list[str], *, input_bytes: bytes | None = None) -> bytes:
+    proc = subprocess.run(args, input=input_bytes, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if proc.returncode != 0:
+        cmd = " ".join(args)
+        err = proc.stderr.decode("utf-8", "replace").strip()
+        raise SystemExit(f"command failed: {cmd}\n{err}")
+    return proc.stdout
+
+
+def identify_info(path: Path, identify: str) -> tuple[int, int, str]:
+    out = run([identify, "-format", "%w %h %[channels]", str(path)]).decode().strip()
+    parts = out.split()
+    if len(parts) < 3:
+        raise SystemExit(f"could not read image info for {path}: {out}")
+    return int(parts[0]), int(parts[1]), parts[2]
+
+
+def corner_is_transparent(path: Path, convert: str) -> bool:
+    pixel = run([convert, str(path), "-format", "%[pixel:p{0,0}]", "info:"]).decode().strip()
+    if "srgba" not in pixel and "rgba" not in pixel:
+        return False
+    tail = pixel.rsplit(",", 1)[-1].rstrip(")")
+    try:
+        return float(tail) == 0.0
+    except ValueError:
+        return tail in {"0", "0.0"}
+
+
+def rgb_bytes(path: Path, convert: str) -> bytes:
+    return run([convert, str(path), "-alpha", "remove", "-depth", "8", "rgb:-"])
+
+
+def make_background_mask(
+    rgb: bytes,
+    width: int,
+    height: int,
+    *,
+    min_light: int,
+    neutral_tolerance: int,
+) -> bytearray:
+    total = width * height
+    seen = bytearray(total)
+    queue: collections.deque[int] = collections.deque()
+
+    def is_candidate(index: int) -> bool:
+        base = index * 3
+        r, g, b = rgb[base], rgb[base + 1], rgb[base + 2]
+        return max(r, g, b) - min(r, g, b) <= neutral_tolerance and (r + g + b) / 3 >= min_light
+
+    def add(index: int) -> None:
+        if not seen[index] and is_candidate(index):
+            seen[index] = 1
+            queue.append(index)
+
+    for x in range(width):
+        add(x)
+        add((height - 1) * width + x)
+    for y in range(height):
+        add(y * width)
+        add(y * width + width - 1)
+
+    while queue:
+        index = queue.popleft()
+        x = index % width
+        y = index // width
+        for dy in (-1, 0, 1):
+            ny = y + dy
+            if not 0 <= ny < height:
+                continue
+            for dx in (-1, 0, 1):
+                if dx == 0 and dy == 0:
+                    continue
+                nx = x + dx
+                if 0 <= nx < width:
+                    add(ny * width + nx)
+
+    return seen
+
+
+def write_rgba_png(rgb: bytes, mask: bytearray, width: int, height: int, output: Path, convert: str) -> None:
+    rgba = bytearray(width * height * 4)
+    for index in range(width * height):
+        rgba[index * 4 : index * 4 + 3] = rgb[index * 3 : index * 3 + 3]
+        rgba[index * 4 + 3] = 0 if mask[index] else 255
+    run(
+        [
+            convert,
+            "-size",
+            f"{width}x{height}",
+            "-depth",
+            "8",
+            "rgba:-",
+            f"png32:{output}",
+        ],
+        input_bytes=bytes(rgba),
+    )
+
+
+def apply_open_mask(source: Path, radius: int, output: Path, convert: str, tmpdir: Path) -> None:
+    if radius <= 0:
+        if source != output:
+            shutil.copy2(source, output)
+        return
+    alpha = tmpdir / "alpha.png"
+    opened = tmpdir / "alpha-open.png"
+    run([convert, str(source), "-alpha", "extract", str(alpha)])
+    run([convert, str(alpha), "-morphology", "Open", f"Disk:{radius}", str(opened)])
+    run(
+        [
+            convert,
+            str(source),
+            str(opened),
+            "-alpha",
+            "off",
+            "-compose",
+            "CopyOpacity",
+            "-composite",
+            f"png32:{output}",
+        ]
+    )
+
+
+def backup_input(path: Path) -> Path:
+    stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup_dir = Path(tempfile.gettempdir()) / "png-alpha-cleaner-backups" / stamp
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    backup = backup_dir / path.name
+    shutil.copy2(path, backup)
+    return backup
+
+
+def preview(output: Path, colors: list[str], convert: str) -> list[Path]:
+    previews: list[Path] = []
+    for raw_color in colors:
+        safe = raw_color.replace("#", "").replace("/", "-")
+        path = output.with_name(f"{output.stem}.preview-{safe}.png")
+        run([convert, str(output), "-background", raw_color, "-alpha", "remove", str(path)])
+        previews.append(path)
+    return previews
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", type=Path)
+    parser.add_argument("-o", "--output", type=Path)
+    parser.add_argument("--in-place", action="store_true")
+    parser.add_argument("--min-light", type=int, default=220)
+    parser.add_argument("--neutral-tolerance", type=int, default=12)
+    parser.add_argument("--open-radius", type=int, default=4)
+    parser.add_argument("--preview-color", action="append", default=[])
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+    if not args.input.exists():
+        raise SystemExit(f"input not found: {args.input}")
+    if args.output and args.in_place:
+        raise SystemExit("use either --output or --in-place, not both")
+    if not args.output and not args.in_place:
+        args.output = args.input.with_name(f"{args.input.stem}.alpha.png")
+    output = args.input if args.in_place else args.output
+    assert output is not None
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    identify, convert = image_tools()
+    width, height, channels = identify_info(args.input, identify)
+    backup = backup_input(args.input) if args.in_place else None
+
+    with tempfile.TemporaryDirectory(prefix="png-alpha-cleaner-") as tmp:
+        tmpdir = Path(tmp)
+        if "a" in channels.lower() and corner_is_transparent(args.input, convert):
+            run([convert, str(args.input), f"png32:{output}"])
+            transparent_count = "already-alpha"
+        else:
+            rgb = rgb_bytes(args.input, convert)
+            if len(rgb) != width * height * 3:
+                raise SystemExit("unexpected RGB byte count from ImageMagick")
+            mask = make_background_mask(
+                rgb,
+                width,
+                height,
+                min_light=args.min_light,
+                neutral_tolerance=args.neutral_tolerance,
+            )
+            transparent = sum(1 for value in mask if value)
+            if transparent == 0:
+                raise SystemExit("no edge-connected light/neutral background detected")
+            raw = tmpdir / "raw-alpha.png"
+            write_rgba_png(rgb, mask, width, height, raw, convert)
+            apply_open_mask(raw, args.open_radius, output, convert, tmpdir)
+            transparent_count = str(transparent)
+
+    out_width, out_height, out_channels = identify_info(output, identify)
+    corner = run([convert, str(output), "-format", "%[pixel:p{0,0}]", "info:"]).decode().strip()
+    preview_paths = preview(output, args.preview_color, convert)
+
+    print(f"output={output}")
+    print(f"format=PNG size={out_width}x{out_height} channels={out_channels}")
+    print(f"corner={corner}")
+    print(f"background_pixels={transparent_count}")
+    if backup:
+        print(f"backup={backup}")
+    for item in preview_paths:
+        print(f"preview={item}")
+
+    if out_width != width or out_height != height:
+        raise SystemExit("output size changed unexpectedly")
+    if "a" not in out_channels.lower():
+        raise SystemExit("output does not contain alpha")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))