feat: add 20 specialized project skills for image quality enhancement and CPU performance

.agents/skills/arcface-identity-loss-tuning/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: arcface-identity-loss-tuning
+description: Integrating ArcFace/CosFace identity feature extractors into PyTorch GAN loss pipelines to preserve facial identity during fine-tuning.
+---
+
+# ArcFace Identity Loss Integration & Fine-Tuning Skill
+
+## Overview
+Standard pixel (L1) and perceptual (LPIPS) losses focus on surface appearance, which can drift human identity features during high-fidelity face restoration. ArcFace extracts deep 512-dimensional face embedding vectors. Computing cosine distance between restored and target embeddings guarantees identity preservation.
+
+## Mathematical Formulation
+$$\mathcal{L}_{id} = 1 - rac{	ext{ArcFace}(I_{rec}) \cdot 	ext{ArcFace}(I_{gt})}{\|	ext{ArcFace}(I_{rec})\| \|	ext{ArcFace}(I_{gt})\|}$$
+
+## Code Snippet
+```python
+import torch
+import torch.nn.functional as F
+
+class ArcFaceLoss(torch.nn.Module):
+    def __init__(self, net):
+        super().__init__()
+        self.net = net.eval()
+        for p in self.net.parameters():
+            p.requires_grad = False
+            
+    def forward(self, pred, target):
+        emb_pred = F.normalize(self.net(pred), p=2, dim=1)
+        emb_gt = F.normalize(self.net(target), p=2, dim=1)
+        return 1.0 - torch.sum(emb_pred * emb_gt, dim=1).mean()
+```

.agents/skills/blind-degradation-pipeline/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: blind-degradation-pipeline
+description: Synthesizing real-world image degradation pipelines including anisotropic Gaussian blur, motion kernels, Poisson/Gaussian noise, JPEG compression artifacts, and multi-stage downsampling.
+---
+
+# Blind Degradation Pipeline Modeling Skill
+
+## Overview
+Training robust face restoration models requires simulating realistic real-world corruptions. A multi-stage degradation pipeline combines blur, noise, downsampling, and JPEG compression in randomized orders.
+
+## Degradation Order
+1. **Blur**: Anisotropic Gaussian Blur ($\sigma \in [0.2, 3.0]$) + Motion blur kernel.
+2. **Downsampling**: Random resize (area, bilinear, bicubic) down to scale factor $r \in [1, 8]$.
+3. **Noise**: Additive Gaussian noise ($\sigma \in [0, 30]$) + Poisson noise.
+4. **JPEG Compression**: Quality factor $Q \in [10, 70]$.
+5. **Final Downscale**: Resize to network input shape ($512 	imes 512$).

.agents/skills/chromatic-aberration-correction/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: chromatic-aberration-correction
+description: Detection and correction of lateral and longitudinal chromatic aberration (color fringing), radial channel alignment, and lens distortion repair.
+---
+
+# Chromatic Aberration & Color Fringing Correction Skill
+
+## Overview
+Chromatic aberration produces red/cyan or blue/yellow color fringes along high-contrast edges. Radial channel shift aligns Red and Blue channels to Green.
+
+## Code Example
+```python
+import cv2
+import numpy as np
+
+def correct_chromatic_aberration(img_bgr):
+    b, g, r = cv2.split(img_bgr)
+    # Estimate warp matrix between channels using ECC or phase correlation
+    warp_mode = cv2.MOTION_TRANSLATION
+    warp_matrix = np.eye(2, 3, dtype=np.float32)
+    criteria = (cv2.TERMCRITERIA_EPS | cv2.TERMCRITERIA_COUNT, 50, 1e-4)
+    
+    try:
+        _, warp_matrix_r = cv2.findTransformECC(g, r, warp_matrix.copy(), warp_mode, criteria)
+        r_corr = cv2.warpAffine(r, warp_matrix_r, (g.shape[1], g.shape[0]), flags=cv2.INTER_LINEAR + cv2.WARP_INVERSE_MAP)
+    except cv2.error:
+        r_corr = r
+        
+    return cv2.merge((b, g, r_corr))
+```

.agents/skills/eye-and-teeth-enhancement/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: eye-and-teeth-enhancement
+description: Facial parsing targeted enhancements for boosting iris clarity, catchlight sparkle, ocular contrast, and natural teeth brightening without over-bleaching.
+---
+
+# Eye & Teeth Targeted Enhancement Skill
+
+## Overview
+Eyes and teeth are central focal points in portrait photography. This skill targets parsed eye and mouth masks to boost iris sharpness, add catchlight clarity, and gently brighten teeth while maintaining natural skin balance.
+
+## Procedures
+1. **Iris & Ocular Boost**:
+   - Extract eye mask from face parsing output.
+   - Apply localized CLAHE and high-pass sharpening on the ocular region ($1.2	imes$ scale).
+2. **Teeth Brightening**:
+   - Isolate inner mouth/teeth mask.
+   - Convert to HSV space; slightly desaturate yellow ($S 	imes 0.85$) and boost luminance ($V 	imes 1.08$).
+
+## Code Example
+```python
+import cv2
+import numpy as np
+
+def enhance_eyes_and_teeth(img_bgr, eye_mask, teeth_mask):
+    out = img_bgr.copy()
+    
+    # Eye sharpness boost
+    if np.any(eye_mask > 0):
+        eyes_sharp = cv2.addWeighted(img_bgr, 1.3, cv2.GaussianBlur(img_bgr, (0,0), 2.0), -0.3, 0)
+        mask_eye_f = (eye_mask.astype(np.float32) / 255.0)[:, :, None]
+        out = np.uint8(out * (1 - mask_eye_f) + eyes_sharp * mask_eye_f)
+        
+    # Teeth whitening in HSV
+    if np.any(teeth_mask > 0):
+        hsv = cv2.cvtColor(out, cv2.COLOR_BGR2HSV).astype(np.float32)
+        hsv[:, :, 1] *= np.where(teeth_mask > 0, 0.85, 1.0) # desaturate yellow
+        hsv[:, :, 2] *= np.where(teeth_mask > 0, 1.08, 1.0) # boost brightness
+        hsv = np.clip(hsv, 0, 255).astype(np.uint8)
+        out = cv2.cvtColor(hsv, cv2.COLOR_HSV2BGR)
+        
+    return out
+```

.agents/skills/face-landmark-alignment-5pt/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: face-landmark-alignment-5pt
+description: Extracting 5-point facial landmarks (eyes, nose, mouth corners), computing similarity transformation matrices, $512 	imes 512$ alignment, and reverse warp-back.
+---
+
+# 5-Point Facial Landmark Alignment & Inverse Warp Skill
+
+## Overview
+Face restoration models require normalized face crops aligned to standard 5-point landmark canonical coordinates (left eye, right eye, nose tip, left mouth corner, right mouth corner). After restoration, the inverse affine transformation warps the crop back to the exact spatial location on the original frame.
+
+## Canonical 512x512 Landmark Anchors
+- Left Eye: $(192.98, 239.95)$
+- Right Eye: $(318.55, 240.14)$
+- Nose Tip: $(256.63, 314.02)$
+- Left Mouth Corner: $(201.26, 371.41)$
+- Right Mouth Corner: $(313.00, 371.19)$
+
+## Code Snippet
+```python
+import cv2
+import numpy as np
+
+def get_similarity_transform(src_pts, dst_pts):
+    # Computes 2x3 affine matrix for similarity transform (scale, rotation, translation)
+    tfm = cv2.estimateAffinePartial2D(src_pts, dst_pts)[0]
+    return tfm
+```

.agents/skills/face-parsing-segmentation-masks/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: face-parsing-segmentation-masks
+description: Facial component segmentation using ParseNet/BiSeNet, extracting eye, lip, skin, and hair masks for targeted post-processing and seamless edge blending.
+---
+
+# Face Parsing & Segmentation Masks Skill
+
+## Overview
+Face parsing segments a face image into semantic components: eyes, eyebrows, nose, mouth/lips, skin, hair, and background. Using these parsing masks allows targeted visual enhancements (e.g. skin grain injection, eye sharpening, lip tone balancing) without affecting non-target regions.
+
+## Key Concepts
+1. **Model Architecture**: BiSeNet or ParseNet trained on CelebAMask-HQ. Outputs 19 semantic channels.
+2. **Mask Generation**:
+   - `skin_mask = (parsing == 1)`
+   - `eye_mask = (parsing == 4) | (parsing == 5)`
+   - `mouth_mask = (parsing == 11) | (parsing == 12) | (parsing == 13)`
+3. **Blending & Dilated Boundaries**:
+   - Apply Gaussian blur (`cv2.GaussianBlur`) to mask edges for soft alpha transitions.
+   - Use morphological erosion (`cv2.erode`) to avoid seam artifacts near hairline or jawline.
+
+## Code Example
+```python
+import cv2
+import numpy as np
+
+def extract_parsing_masks(parsing_out):
+    # parsing_out shape: (512, 512) containing class indices 0..18
+    skin = np.uint8((parsing_out == 1) * 255)
+    eyes = np.uint8(((parsing_out == 4) | (parsing_out == 5)) * 255)
+    lips = np.uint8(((parsing_out == 11) | (parsing_out == 12) | (parsing_out == 13)) * 255)
+    return skin, eyes, lips
+```

.agents/skills/fast-cpu-vectorization-numpy/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: fast-cpu-vectorization-numpy
+description: Optimizing Python image pipelines with C-vectorized NumPy operations, OpenCV inplace buffer operations, and OpenMP multi-threading controls for <20ms CPU latency.
+---
+
+# Fast CPU Vectorization & NumPy Optimization Skill
+
+## Overview
+Running image post-processing in Python loops creates severe latency bottlenecks. Vectorizing image math with NumPy broadcasting, OpenCV inplace buffers (`dst=out`), and contiguous memory layouts ensures lightning-fast execution (<20ms per face).
+
+## Golden Rules
+1. **Never Python Loops over Pixels**: Always use vectorized slice operations (`img[:, :, 0]`).
+2. **Inplace OpenCV Buffers**: Pass output buffer directly `cv2.addWeighted(img1, 0.5, img2, 0.5, 0, dst=buffer)`.
+3. **Memory Contiguity**: Call `np.ascontiguousarray()` before passing arrays to C/C++ extensions.

.agents/skills/frequency-separation-skin-grain/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: frequency-separation-skin-grain
+description: High/low frequency image decomposition, extracting authentic skin pore textures from original images, and blending texture back onto neural network face crops to eliminate plastic skin.
+---
+
+# Frequency Separation & Skin Grain Retention Skill
+
+## Overview
+Neural face restoration models (like CodeFormer) can produce over-smoothed, 'plastic' or 'soapy' skin textures. Frequency separation splits an image into Low Frequency (tones, color, shading) and High Frequency (fine pores, micro-textures, wrinkles). By injecting original high-frequency details onto the restored face crop, skin looks natural and hyper-realistic.
+
+## Key Concepts
+1. **Low Frequency Extraction**: Apply Gaussian blur (`sigma = 2.0 to 4.0`).
+2. **High Frequency Extraction**: Subtract Low Frequency from original image: $HF = Original - LF + 128$.
+3. **Texture Injection**: Blend original high frequency onto the restored face using parsing skin masks.
+
+## Vectorized NumPy Implementation
+```python
+import cv2
+import numpy as np
+
+def inject_skin_grain(orig_crop, restored_crop, skin_mask, weight=0.15):
+    # Convert to float32
+    orig_f = orig_crop.astype(np.float32)
+    rest_f = restored_crop.astype(np.float32)
+    
+    # Extract original high frequency
+    lf_orig = cv2.GaussianBlur(orig_f, (0, 0), sigmaX=3.0)
+    hf_orig = orig_f - lf_orig
+    
+    # Inject onto restored image inside skin mask
+    blended = rest_f + hf_orig * weight
+    blended = np.clip(blended, 0, 255).astype(np.uint8)
+    
+    # Mask blend
+    mask_3ch = (skin_mask.astype(np.float32) / 255.0)[:, :, None]
+    result = np.uint8(restored_crop * (1 - mask_3ch) + blended * mask_3ch)
+    return result
+```

.agents/skills/guided-filter-detail-enhancement/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: guided-filter-detail-enhancement
+description: Guided image filtering, edge-preserving smoothing, detail layer amplification, and halo artifact suppression for ultra-sharp facial details without harsh noise.
+---
+
+# Guided Filter Detail Enhancement Skill
+
+## Overview
+Guided Filtering performs edge-preserving smoothing using a guidance image. By subtracting the guided-filtered base layer from the original image, we extract a pure edge-detail layer that can be amplified without causing ringing or halo artifacts typical of standard unsharp masking.
+
+## Code Example
+```python
+import cv2
+import numpy as np
+
+def guided_detail_enhance(img, radius=4, eps=0.01, scale=1.4):
+    # Guided filter edge-preserving smooth
+    guided = cv2.ximgproc.guidedFilter(guide=img, src=img, radius=radius, eps=eps)
+    detail = img.astype(np.float32) - guided.astype(np.float32)
+    enhanced = img.astype(np.float32) + detail * (scale - 1.0)
+    return np.clip(enhanced, 0, 255).astype(np.uint8)
+```

.agents/skills/hdr-tone-mapping-exposure/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: hdr-tone-mapping-exposure
+description: High Dynamic Range tone mapping, shadow detail enhancement, highlight clipping control, gamma adjustments, and local tone mapping.
+---
+
+# HDR Tone Mapping & Exposure Recovery Skill
+
+## Overview
+Under-exposed shadows and over-exposed highlights lose texture details. Local tone mapping using Durand / Mantiuk tone mapping curves brings out hidden details in portrait shadows and backgrounds.
+
+## Code Example
+```python
+import cv2
+import numpy as np
+
+def recover_shadows_and_highlights(img_bgr, gamma=1.1, shadow_boost=1.2):
+    # Convert to float 0..1
+    img_f = img_bgr.astype(np.float32) / 255.0
+    
+    # Shadow mask based on luminance
+    gray = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2GRAY).astype(np.float32) / 255.0
+    shadow_mask = np.power(1.0 - gray, 2.0)[:, :, None]
+    
+    # Apply gamma & shadow boost
+    corrected = np.power(img_f, 1.0 / gamma)
+    boosted = corrected * (1.0 + (shadow_boost - 1.0) * shadow_mask)
+    
+    return np.clip(boosted * 255.0, 0, 255).astype(np.uint8)
+```

.agents/skills/huggingface-space-docker-deploy/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: huggingface-space-docker-deploy
+description: Packaging AI web apps into lightweight Docker containers for HuggingFace Spaces deployment, managing CPU thread limits, memory leaks, and model downloading caches.
+---
+
+# HuggingFace Space Docker Deployment & Optimization Skill
+
+## Overview
+Deploying AI web applications to HuggingFace Spaces via Docker SDK allows full environment control, CPU PyTorch optimization, custom system packages (`libgl1-mesa-glx`), and automated runtime weight downloading.
+
+## Standard Dockerfile Template
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+RUN apt-get update && apt-get install -y git libgl1-mesa-glx libglib2.0-0 && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+CMD ["streamlit", "run", "app.py", "--server.port=7860", "--server.address=0.0.0.0", "--server.headless=true"]
+```

.agents/skills/image-quality-metrics-eval/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: image-quality-metrics-eval
+description: Quantitative and qualitative image evaluation using PSNR, SSIM, LPIPS perceptual distance, FID distribution score, NIQE no-reference quality, and ArcFace identity metrics.
+---
+
+# Image Quality Metrics & Evaluation Suite Skill
+
+## Overview
+Accurate evaluation of image restoration quality requires both full-reference metrics (comparing restored against ground truth) and no-reference quality metrics.
+
+## Supported Metrics
+1. **PSNR (Peak Signal-to-Noise Ratio)**: Measures pixel reconstruction fidelity ($dB$). Higher is better ($>28	ext{dB}$).
+2. **SSIM (Structural Similarity Index)**: Measures structural/luminance closeness ($0..1$). Higher is better ($>0.85$).
+3. **LPIPS (Learned Perceptual Image Patch Similarity)**: Measures perceptual distance via VGG/AlexNet features. Lower is better ($<0.15$).
+4. **NIQE (Natural Image Quality Evaluator)**: No-reference naturalness score. Lower is better ($<4.5$).
+5. **ArcFace Cosine Identity**: Facial identity preservation score ($0..1$). Higher is better ($>0.70$).

.agents/skills/lab-clahe-color-grading/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: lab-clahe-color-grading
+description: LAB color space transformation, Contrast Limited Adaptive Histogram Equalization (CLAHE) on L-channel, and skin-tone preserving color enhancement.
+---
+
+# LAB CLAHE & Dynamic Color Grading Skill
+
+## Overview
+Restoring degraded images often leaves colors washed out or unevenly exposed. CLAHE (Contrast Limited Adaptive Histogram Equalization) applied in the LAB color space boosts local contrast and shadow detail without distorting human skin tones.
+
+## Key Concepts
+1. **LAB Color Space**: Separates Luminance ($L$) from color channels ($a$ for red-green, $b$ for yellow-blue).
+2. **L-Channel CLAHE**: Enhances contrast locally on $L$ only, avoiding color shifts.
+3. **Clip Limit & Tile Size**: Use `clipLimit=1.5` to `2.0` and `tileGridSize=(8,8)` for realistic enhancements.
+
+## Implementation
+```python
+import cv2
+
+def apply_lab_clahe(img_bgr, clip_limit=1.8, tile_size=(8,8)):
+    lab = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2LAB)
+    l, a, b = cv2.split(lab)
+    
+    clahe = cv2.createCLAHE(clipLimit=clip_limit, tileGridSize=tile_size)
+    cl = clahe.apply(l)
+    
+    merged = cv2.merge((cl, a, b))
+    return cv2.cvtColor(merged, cv2.COLOR_LAB2BGR)
+```

.agents/skills/lmdb-dataset-binary-storage/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: lmdb-dataset-binary-storage
+description: Converting loose image folders to Lightning Memory-Mapped Database (LMDB) binary datasets for ultra-fast sequential training I/O and zero disk fragmentation.
+---
+
+# LMDB Dataset Binary Storage & High-Speed I/O Skill
+
+## Overview
+Reading thousands of small loose image files during neural network training causes severe disk I/O bottlenecks and OS page cache thrashing. LMDB maps binary image buffers directly into virtual memory for instant zero-copy reads.
+
+## Build LMDB Script Pattern
+```python
+import lmdb
+import cv2
+
+def build_lmdb(image_paths, lmdb_path):
+    env = lmdb.open(lmdb_path, map_size=1099511627776) # 1TB max allocation
+    with env.begin(write=True) as txn:
+        for idx, path in enumerate(image_paths):
+            with open(path, 'rb') as f:
+                img_bin = f.read()
+            key = f"{idx:08d}".encode('ascii')
+            txn.put(key, img_bin)
+    env.close()
+```

.agents/skills/noise-estimation-denoising/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: noise-estimation-denoising
+description: Non-Local Means (NLM) denoising, wavelet thresholding, and bilateral filtering for noise estimation and suppression prior to super-resolution.
+---
+
+# Noise Estimation & Pre-Denoising Skill
+
+## Overview
+High-frequency noise in input images gets amplified during AI super-resolution and face restoration. Pre-denoising with Fast Non-Local Means or Bilateral filtering smooths uniform noise while preserving structural edges.
+
+## Key Methods
+1. **Noise Estimation**: Compute standard deviation of Laplacian response ($\sigma_n = 	ext{std}(
+abla^2 I)$).
+2. **Fast NLM Denoising**: `cv2.fastNlMeansDenoisingColored(img, None, h=3, hColor=3, templateWindowSize=7, searchWindowSize=21)`.
+3. **Bilateral Filter**: `cv2.bilateralFilter(img, d=5, sigmaColor=25, sigmaSpace=25)`.

.agents/skills/onnx-static-int8-quantization/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: onnx-static-int8-quantization
+description: Converting PyTorch models to ONNX static INT8 format with calibration data readers, preserving accuracy while achieving 3x-4x CPU speedup.
+---
+
+# ONNX Static INT8 Quantization & Calibration Skill
+
+## Overview
+Static INT8 quantization uses a calibration dataset to determine exact tensor activation ranges ($[\min, \max]$). This results in faster execution and lower memory bandwidth on CPU compared to dynamic quantization.
+
+## Key Concepts
+1. **Calibration Data Reader**: Implements `CalibrationDataReader` class providing 50-100 real face inputs.
+2. **Quantization Mode**: `QuantFormat.QDQ` (Quantize-Dequantize) with `QuantType.QInt8`.
+3. **Execution Provider**: CPUExecutionProvider optimized for AVX2/AVX512.
+
+## Implementation Code
+```python
+from onnxruntime.quantization import quantize_static, CalibrationDataReader, QuantFormat, QuantType
+
+class FaceDataReader(CalibrationDataReader):
+    def __init__(self, sample_inputs):
+        self.enum_data = iter([{"input": x} for x in sample_inputs])
+    def get_next(self):
+        return next(self.enum_data, None)
+
+def quantize_onnx_static(in_onnx, out_onnx, sample_inputs):
+    reader = FaceDataReader(sample_inputs)
+    quantize_static(
+        in_onnx, out_onnx, reader,
+        quant_format=QuantFormat.QDQ,
+        weight_type=QuantType.QInt8,
+        activation_type=QuantType.QInt8
+    )
+```

.agents/skills/streamlit-side-by-side-visualizer/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: streamlit-side-by-side-visualizer
+description: Designing responsive Streamlit visualizer widgets, interactive split-screen image slider comparison components, pixel zoom inspectors, and performance metrics.
+---
+
+# Streamlit Side-by-Side Visualizer & UI Component Skill
+
+## Overview
+Presenting image enhancement results effectively requires interactive UI components like side-by-side split screens, before/after image sliders, and detailed metric breakdown cards (processing time, resolution boost, face count).
+
+## Recommended Patterns
+1. **Interactive Image Comparison Widget**: Use custom HTML/JS or Streamlit image comparison components.
+2. **Dynamic Zoom Inspector**: Allow users to inspect $100\%$ face crop regions side-by-side.
+3. **Download Options**: Provide high-speed PNG/JPEG download buttons with custom file naming.

.agents/skills/streamlit-thread-state-guidelines/SKILL.md

@@ -1,4 +1,4 @@
----
+ ---
 name: streamlit-thread-state-guidelines
 description: Architectural rules and patterns for Streamlit background threading, thread-safe queue IPC, cached function guards, session_state initialization, and progress polling in AI web applications.
 ---

.agents/skills/super-resolution-tile-stitching/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: super-resolution-tile-stitching
+description: Tile-based image processing for ultra-high-resolution images under strict memory limits, including tile padding, overlap cosine blending, and seam removal.
+---
+
+# Super-Resolution Tile Processing & Stitching Skill
+
+## Overview
+High-resolution images (4K, 8K) exceed CPU/GPU RAM limits when passed whole through deep learning models. Tiling breaks images into overlapping patches, processes each patch independently, and stitches them with smooth cosine blending to eliminate visible seam borders.
+
+## Key Concepts
+1. **Tile Size & Overlap**: e.g., tile size $400 	imes 400$, overlap $40	ext{px}$.
+2. **Padding**: Mirror pad outer borders to handle edge tiles seamlessly.
+3. **Cosine Weight Mask**: Generate 2D Gaussian/cosine weight maps so patch overlap areas smoothly transition.
+
+## Implementation Pattern
+```python
+import numpy as np
+
+def generate_tile_weights(tile_h, tile_w, pad):
+    # Smooth linear/cosine weight ramp at borders
+    w_x = np.ones(tile_w, dtype=np.float32)
+    w_y = np.ones(tile_h, dtype=np.float32)
+    w_x[:pad] = np.linspace(0, 1, pad)
+    w_x[-pad:] = np.linspace(1, 0, pad)
+    w_y[:pad] = np.linspace(0, 1, pad)
+    w_y[-pad:] = np.linspace(1, 0, pad)
+    return np.outer(w_y, w_x)[:, :, None]
+```

.agents/skills/unsharp-masking-deconvolution/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: unsharp-masking-deconvolution
+description: Dynamic unsharp masking (USM), Richardson-Lucy non-blind deconvolution, and high-pass frequency boosting for crisp edge recovery.
+---
+
+# Unsharp Masking & Deconvolution Skill
+
+## Overview
+Restoring high-frequency details requires carefully tuned sharpening. Standard USM uses a Gaussian blur kernel to isolate high frequencies, while Richardson-Lucy deconvolution reverses point spread function (PSF) blurring.
+
+## Formula & Code
+USM Formula: $I_{sharp} = I + lpha (I - G_\sigma * I)$
+
+```python
+import cv2
+import numpy as np
+
+def adaptive_unsharp_mask(img, amount=0.5, radius=1.0, threshold=2):
+    blurred = cv2.GaussianBlur(img, (0, 0), radius)
+    diff = img.astype(np.float32) - blurred.astype(np.float32)
+    mask = np.abs(diff) >= threshold
+    sharpened = img.astype(np.float32) + amount * diff
+    result = np.where(mask, sharpened, img.astype(np.float32))
+    return np.clip(result, 0, 255).astype(np.uint8)
+```

.agents/skills/vqgan-codebook-fine-tuning/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: vqgan-codebook-fine-tuning
+description: Fine-tuning VQGAN discrete codebooks, discrete code dictionary index lookup, stage I VQ autoencoders, and codebook matching for photo & illustration styles.
+---
+
+# VQGAN Codebook Fine-Tuning & Dictionary Matching Skill
+
+## Overview
+CodeFormer relies on a VQGAN codebook (Stage I) that encapsulates high-quality clean face priors. When restoring domain-specific images (game characters, vintage portraits), fine-tuning codebook vectors or adjusting codebook lookup weights improves naturalness and reduces vector quantization quantization loss.
+
+## Key Components
+1. **Codebook Size**: $N=1024$ codebook vectors of dimension $d=512$.
+2. **Quantization Loss**: Commitment loss + Codebook update loss.
+3. **Cross-Entropy Code Prediction Transformer**: Stage II maps low-quality features to discrete codebook indices.

models/CodeFormer/options/cf_runtime_szvghq3h.yml

@@ -0,0 +1,166 @@
+name: CodeFormer_stage3_custom
+model_type: CodeFormerJointModel
+num_gpu: 0
+manual_seed: 0
+datasets:
+  train:
+    name: CustomDataset
+    type: FFHQBlindJointDataset
+    dataroot_gt: datasets/ffhq/ffhq_512
+    filename_tmpl: '{}'
+    io_backend:
+      type: disk
+    in_size: 512
+    gt_size: 512
+    mean:
+    - 0.5
+    - 0.5
+    - 0.5
+    std:
+    - 0.5
+    - 0.5
+    - 0.5
+    use_hflip: true
+    use_corrupt: true
+    blur_kernel_size: 41
+    use_motion_kernel: true
+    motion_kernel_prob: 0.15
+    kernel_list:
+    - iso
+    - aniso
+    kernel_prob:
+    - 0.5
+    - 0.5
+    blur_sigma:
+    - 0.1
+    - 10.0
+    downsample_range:
+    - 1.0
+    - 20.0
+    noise_range:
+    - 0.0
+    - 30.0
+    jpeg_range:
+    - 10
+    - 70
+    blur_sigma_large:
+    - 1.0
+    - 15.0
+    downsample_range_large:
+    - 4.0
+    - 30.0
+    noise_range_large:
+    - 0.0
+    - 30.0
+    jpeg_range_large:
+    - 5
+    - 50
+    latent_gt_path: null
+    num_worker_per_gpu: 0
+    batch_size_per_gpu: 1
+    dataset_enlarge_ratio: 5
+    prefetch_mode: null
+network_g:
+  type: CodeFormer
+  dim_embd: 512
+  n_head: 8
+  n_layers: 9
+  codebook_size: 1024
+  connect_list:
+  - '32'
+  - '64'
+  - '128'
+  - '256'
+  fix_modules:
+  - quantize
+  - generator
+network_vqgan:
+  type: VQAutoEncoder
+  img_size: 512
+  nf: 64
+  ch_mult:
+  - 1
+  - 2
+  - 2
+  - 4
+  - 4
+  - 8
+  quantizer: nearest
+  codebook_size: 1024
+network_d:
+  type: VQGANDiscriminator
+  nc: 3
+  ndf: 64
+  n_layers: 4
+path:
+  pretrain_network_g: null
+  param_key_g: params_ema
+  strict_load_g: false
+  pretrain_network_d: null
+  resume_state: D:\.gemini-scratch\custom-ai-enhancer\models\CodeFormer\experiments\20260708_201102_CodeFormer_stage3_custom\training_states\2150.state
+train:
+  use_hq_feat_loss: true
+  feat_loss_weight: 1.0
+  cross_entropy_loss: true
+  entropy_loss_weight: 0.5
+  identity_loss_weight: 0.5
+  scale_adaptive_gan_weight: 0.1
+  optim_g:
+    type: Adam
+    lr: 5.0e-05
+    weight_decay: 0
+    betas:
+    - 0.9
+    - 0.99
+  optim_d:
+    type: Adam
+    lr: 5.0e-05
+    weight_decay: 0
+    betas:
+    - 0.9
+    - 0.99
+  scheduler:
+    type: CosineAnnealingRestartLR
+    periods:
+    - 20000
+    restart_weights:
+    - 1
+    eta_min: 5.0e-06
+  total_iter: 20000
+  warmup_iter: -1
+  ema_decay: 0.997
+  pixel_opt:
+    type: L1Loss
+    loss_weight: 1.0
+    reduction: mean
+  perceptual_opt:
+    type: LPIPSLoss
+    loss_weight: 1.0
+    use_input_norm: true
+    range_norm: true
+  gan_opt:
+    type: GANLoss
+    gan_type: hinge
+    loss_weight: 1.0
+  use_adaptive_weight: true
+  net_g_start_iter: 0
+  net_d_iters: 1
+  net_d_start_iter: 0
+  manual_seed: 0
+val:
+  val_freq: 500
+  save_img: true
+  metrics:
+    psnr:
+      type: calculate_psnr
+      crop_border: 4
+      test_y_channel: false
+logger:
+  print_freq: 1
+  save_checkpoint_freq: 50
+  use_tb_logger: false
+  wandb:
+    project: null
+find_unused_parameters: true
+dist_params: null
+dist: false

models/CodeFormer/options/cf_runtime_vmvjxo41.yml

@@ -0,0 +1,166 @@
+name: CodeFormer_stage3_custom
+model_type: CodeFormerJointModel
+num_gpu: 0
+manual_seed: 0
+datasets:
+  train:
+    name: CustomDataset
+    type: FFHQBlindJointDataset
+    dataroot_gt: datasets/ffhq/ffhq_512
+    filename_tmpl: '{}'
+    io_backend:
+      type: disk
+    in_size: 512
+    gt_size: 512
+    mean:
+    - 0.5
+    - 0.5
+    - 0.5
+    std:
+    - 0.5
+    - 0.5
+    - 0.5
+    use_hflip: true
+    use_corrupt: true
+    blur_kernel_size: 41
+    use_motion_kernel: true
+    motion_kernel_prob: 0.15
+    kernel_list:
+    - iso
+    - aniso
+    kernel_prob:
+    - 0.5
+    - 0.5
+    blur_sigma:
+    - 0.1
+    - 10.0
+    downsample_range:
+    - 1.0
+    - 20.0
+    noise_range:
+    - 0.0
+    - 30.0
+    jpeg_range:
+    - 10
+    - 70
+    blur_sigma_large:
+    - 1.0
+    - 15.0
+    downsample_range_large:
+    - 4.0
+    - 30.0
+    noise_range_large:
+    - 0.0
+    - 30.0
+    jpeg_range_large:
+    - 5
+    - 50
+    latent_gt_path: null
+    num_worker_per_gpu: 0
+    batch_size_per_gpu: 1
+    dataset_enlarge_ratio: 5
+    prefetch_mode: null
+network_g:
+  type: CodeFormer
+  dim_embd: 512
+  n_head: 8
+  n_layers: 9
+  codebook_size: 1024
+  connect_list:
+  - '32'
+  - '64'
+  - '128'
+  - '256'
+  fix_modules:
+  - quantize
+  - generator
+network_vqgan:
+  type: VQAutoEncoder
+  img_size: 512
+  nf: 64
+  ch_mult:
+  - 1
+  - 2
+  - 2
+  - 4
+  - 4
+  - 8
+  quantizer: nearest
+  codebook_size: 1024
+network_d:
+  type: VQGANDiscriminator
+  nc: 3
+  ndf: 64
+  n_layers: 4
+path:
+  pretrain_network_g: null
+  param_key_g: params_ema
+  strict_load_g: false
+  pretrain_network_d: null
+  resume_state: D:\.gemini-scratch\custom-ai-enhancer\models\CodeFormer\experiments\20260708_201102_CodeFormer_stage3_custom\training_states\2150.state
+train:
+  use_hq_feat_loss: true
+  feat_loss_weight: 1.0
+  cross_entropy_loss: true
+  entropy_loss_weight: 0.5
+  identity_loss_weight: 0.5
+  scale_adaptive_gan_weight: 0.1
+  optim_g:
+    type: Adam
+    lr: 5.0e-05
+    weight_decay: 0
+    betas:
+    - 0.9
+    - 0.99
+  optim_d:
+    type: Adam
+    lr: 5.0e-05
+    weight_decay: 0
+    betas:
+    - 0.9
+    - 0.99
+  scheduler:
+    type: CosineAnnealingRestartLR
+    periods:
+    - 20000
+    restart_weights:
+    - 1
+    eta_min: 5.0e-06
+  total_iter: 20000
+  warmup_iter: -1
+  ema_decay: 0.997
+  pixel_opt:
+    type: L1Loss
+    loss_weight: 1.0
+    reduction: mean
+  perceptual_opt:
+    type: LPIPSLoss
+    loss_weight: 1.0
+    use_input_norm: true
+    range_norm: true
+  gan_opt:
+    type: GANLoss
+    gan_type: hinge
+    loss_weight: 1.0
+  use_adaptive_weight: true
+  net_g_start_iter: 0
+  net_d_iters: 1
+  net_d_start_iter: 0
+  manual_seed: 0
+val:
+  val_freq: 500
+  save_img: true
+  metrics:
+    psnr:
+      type: calculate_psnr
+      crop_border: 4
+      test_y_channel: false
+logger:
+  print_freq: 1
+  save_checkpoint_freq: 50
+  use_tb_logger: false
+  wandb:
+    project: null
+find_unused_parameters: true
+dist_params: null
+dist: false

wink_enhancer.py

@@ -35,17 +35,20 @@ class WinkQualityEnhancer:
             grain_layer = (high_freq * grain_amount).clip(-128, 127)
 
             if skin_mask is not None:
-                if skin_mask.shape[:2] != restored_face.shape[:2]:
-                    skin_mask_resized = cv2.resize(skin_mask.astype(np.uint8), (restored_face.shape[1], restored_face.shape[0]), interpolation=cv2.INTER_NEAREST)
+                skin_mask_2d = np.squeeze(skin_mask)
+                if skin_mask_2d.ndim == 2:
+                    if skin_mask_2d.shape != restored_face.shape[:2]:
+                        skin_mask_resized = cv2.resize(skin_mask_2d.astype(np.uint8), (restored_face.shape[1], restored_face.shape[0]), interpolation=cv2.INTER_NEAREST)
+                    else:
+                        skin_mask_resized = skin_mask_2d
+                    
+                    # Skin category in facexlib parse mask is index 1
+                    skin_binary = (skin_mask_resized == 1).astype(np.float32)
+                    # Smooth mask edge
+                    skin_binary = cv2.GaussianBlur(skin_binary, (5, 5), 0)[:, :, np.newaxis]
+                    blended = restored_face.astype(np.float32) + grain_layer * skin_binary
                 else:
-                    skin_mask_resized = skin_mask
-                
-                # Skin category in facexlib parse mask is index 1
-                skin_binary = (skin_mask_resized == 1).astype(np.float32)
-                # Smooth mask edge
-                skin_binary = cv2.GaussianBlur(skin_binary, (5, 5), 0)[:, :, np.newaxis]
-                
-                blended = restored_face.astype(np.float32) + grain_layer * skin_binary
+                    blended = restored_face.astype(np.float32) + grain_layer
             else:
                 blended = restored_face.astype(np.float32) + grain_layer
 
@@ -64,11 +67,17 @@ class WinkQualityEnhancer:
             return cv2.addWeighted(face_img, 1.15, blur, -0.15, 0)
 
         try:
+            parse_mask_2d = np.squeeze(parse_mask)
+            if parse_mask_2d.ndim != 2:
+                blur = cv2.GaussianBlur(face_img, (0, 0), 2.0)
+                return cv2.addWeighted(face_img, 1.15, blur, -0.15, 0)
+
             h, w = face_img.shape[:2]
-            if parse_mask.shape[:2] != (h, w):
-                parse_mask_res = cv2.resize(parse_mask.astype(np.uint8), (w, h), interpolation=cv2.INTER_NEAREST)
+            if parse_mask_2d.shape[:2] != (h, w):
+                parse_mask_res = cv2.resize(parse_mask_2d.astype(np.uint8), (w, h), interpolation=cv2.INTER_NEAREST)
             else:
-                parse_mask_res = parse_mask
+                parse_mask_res = parse_mask_2d
+
 
             # Facial feature mask IDs in facexlib:
             # 4: Left Eye, 5: Right Eye, 6: Glasses, 11: Upper Lip, 12: Lower Lip, 13: Inner Mouth