mcp-relight-harmonize 1.0.2 → 1.0.4

package/.agents/skills/mcp-relight-harmonize/SKILL.md

@@ -1,40 +1,60 @@
 ---
 name: mcp-relight-harmonize
 description: >-
-  Execute end-to-end optical image profiling, physically-grounded relighting variations, contact-aware composite harmonization,
-  and precision diffusion prompt synthesis targeting GPT Image and Nano Banana. Use when inspecting lighting angles or color temperature,
+  Execute end-to-end 6-layer optical image profiling, physically-grounded relighting variations, contact-aware composite harmonization,
+  and precision diffusion prompt synthesis compatible with Any Image Generator Model (optimized for GEMINI Nano Banana in Antigravity). Use when inspecting lighting angles or color temperature,
   generating alternative illumination schemes (Ambient, Dramatic, Rim, Mood), blending foreground cutouts into backgrounds,
   or drafting photorealistic prompts.
 ---
 
 # `mcp-relight-harmonize` Skill Specification
 
-Created by **MarwanDevSpace**, this skill empowers the agent to execute physical lighting analysis, generate relighted variations, perform seamless composite harmonization, and craft production diffusion prompts tailored for **GPT Image** and **Nano Banana**.
+Created by **MarwanDevSpace**, this skill empowers the agent to execute physical lighting analysis, decompose images into 6 visual layers in `Layers/`, generate relighted variations, perform seamless composite harmonization, and craft production diffusion prompts tailored for **Any Image Generator Model** (specifically optimized for **GEMINI Nano Banana** in **Google Antigravity**).
+
+> [!NOTE]
+> **Antigravity Recommended**: This skill is optimized to work with **any Image Generator**, and is **strongly preferred inside Google Antigravity** where native desktop image generation (`generate_image`) with **GEMINI Nano Banana** can immediately execute the desired modifications.
 
 ---
 
 ## 1. When to Activate This Skill
 
 Activate this skill whenever the user asks to:
-1. **Analyze an image's lighting:** Determine Correlated Color Temperature (CCT in Kelvin), lighting direction vector, azimuth/elevation angles, contrast ratio, or surface roughness.
-2. **Relight an image:** Produce 4 physically-grounded lighting variants (`Ambient`, `Dramatic`, `Rim`, `Mood`).
+1. **Decompose & Analyze an image's lighting:** Generate 6 analytical layers into `Layers/` and determine CCT (Kelvin), lighting direction, azimuth/elevation angles, contrast ratio, or surface roughness.
+2. **Relight an image:** Produce physically-grounded lighting variants (`Ambient`, `Dramatic`, `Rim`, `Mood`).
 3. **Composite/Harmonize an image:** Place a cutout foreground onto a background scene, matching ambient color statistics and adding physically grounded contact shadows.
-4. **Generate `/prompt` for diffusion:** Create exact physical lighting and detail enhancement prompts for **GPT Image** (DALL-E 3 / GPT-4o) and **Nano Banana** with calibrated denoising strength (`0.35 - 0.45`).
+4. **Generate `/prompt` for diffusion:** Create exact physical lighting and detail enhancement prompts for **Any Image Generator** / **GEMINI Nano Banana** with calibrated denoising strength (`0.35 - 0.45`).
 
 ---
 
 ## 2. Core Workflows & Execution Procedures
 
-### Workflow A: Optical Profiling
+### Workflow A: Optical Profiling & 6-Layer Decomposition
 Before modifying or inpainting an image, extract its optical geometry:
-1. Call tool `analyze_optical_profile({ image_path: "<path_to_image>" })`.
-2. Review the resulting `OpticalProfileReport`:
-   - **`colorTemperatureKelvin`**: e.g., 3200K tungsten vs 6500K daylight.
-   - **`lightingAngles`**: `azimuthDeg` (horizontal angle) and `elevationDeg` (vertical angle).
+1. Call tool `analyze_optical_profile({ image_path: "<path_to_image>", extract_layers: true })` or run:
+   `python scripts/extract_layers.py --image <path> [--intent "<intent>"]`
+2. Python decomposes the image into 6 visual layers inside `Layers/`:
+   - `01_highlights.png` (Highlights / Specular Zones)
+   - `02_shadows.png` (Shadows / Low-Key Zones)
+   - `03_ambient_occlusion.png` (Deep Ambient Occlusion & Ground Contact)
+   - `04_edges.png` (Sobel High-Frequency Contours)
+   - `05_depth_normals.png` (3D Surface Normal Gradient Field)
+   - `06_chroma_saturation.png` (Chrominance & Saturation Distribution)
+3. Review the resulting `OpticalProfileReport` and dynamic `Layer.md`:
+   - **`colorTemperatureKelvin`**: e.g., 3200K tungsten vs 5500K daylight.
+   - **`lightingAngles`**: `azimuthDeg` and `elevationDeg`.
    - **`luminanceDynamics.contrastRatio`**: Key-to-fill ratio.
-3. Use these physical parameters to inform subsequent relighting or prompt writing.
-
-### Workflow B: Generating 4 Relit Variations
+   - **`aoCoveragePct`**: Contact shadow presence vs floating subject.
+4. Store findings in memory / CoT to guide subsequent generation.
+
+### Workflow B: Interactive Decision & Direct Image Generation
+1. Address the user with the mandatory prompt:
+   **"ماذا تريد من تعديل؟"**
+   accompanied by tailored recommendations derived strictly from the image's detected optical profile.
+2. Upon user selection or intent:
+   - Synthesize the photorealistic prompt for the **Image Generator**.
+   - **Inside Google Antigravity**: Directly trigger `generate_image` using the synthesized prompt to produce the modified image on the spot!
+
+### Workflow C: Physical Relighting Variations
 To produce visual lighting alternatives on disk:
 1. Call tool `generate_relight_variations({ image_path: "<path_to_image>", target_lighting: "All" })`.
 2. The tool produces 4 files in `OUTPUT_CACHE_DIR`:
@@ -42,44 +62,36 @@ To produce visual lighting alternatives on disk:
    - `*_relight_dramatic.png` (-1.5 EV shadow crush, top-left directional chiaroscuro).
    - `*_relight_rim.png` (+1.2 EV high-pass edge halo, cool cyan perimeter).
    - `*_relight_mood.png` (3200K tungsten amber shift, highlight bloom diffusion).
-3. Present the resulting artifact paths to the user with their mathematical adjustment logs.
 
-### Workflow C: Composite Harmonization
+### Workflow D: Composite Harmonization
 To blend a subject or product into a new background:
 1. Call tool `harmonize_composite({ foreground_path: "<fg>", background_path: "<bg>", blend_mode: "seamless" })`.
-2. The engine executes:
-   - **Reinhard Color Statistics Transfer:** Normalizes foreground means and deviations to match background in Ruderman $l\alpha\beta$ space.
-   - **Contact Shadow Synthesis:** Projects an elliptical Gaussian shadow beneath the subject's lowest contact plane.
-   - **Smooth Blending:** Eliminates boundary halo artifacts.
-3. Return the composite image file path.
+2. The engine executes Reinhard Color Statistics Transfer in Ruderman $l\alpha\beta$ space, applies Ground Contact Shadows, and smooths boundaries.
 
-### Workflow D: Diffusion Prompt Synthesis (`/prompt`)
+### Workflow E: Diffusion Prompt Synthesis (`/prompt`)
 To craft targeted generative prompts:
-1. Call tool `synthesize_diffusion_prompt({ image_path: "<path>", user_intent: "<intent>", target_model: "gpt_image" | "nano_banana" })`.
-2. Extract the two specialized prompts:
-   - **`enhancementPrompt`**: Upgrades micro-surface textures, pore fidelity, lens sharpness, and subsurface scattering.
-   - **`relightingPrompt`**: Injects exact lighting angles, Kelvin temperature, volumetric dust rays, and contact shadows.
-3. For **GPT Image**: outputs natural descriptive photography directives (85mm f/2.0, physical illumination).
-4. For **Nano Banana**: outputs dense optical tokens (roughness index, raytraced bounce, ground contact shadow, azimuth).
-
-### Workflow E: Output Cache Inspection
-To inspect or discover previously generated relight variations or composite outputs:
-1. Call tool `list_cached_variations({ cache_dir?: "<path>" })`.
-2. Inspect `files` list containing filename, full path, byte size, and last modified timestamp for all output artifacts.
+1. Call tool `synthesize_diffusion_prompt({ image_path: "<path>", user_intent: "<intent>", target_model: "universal" | "nano_banana" })`.
+2. Extract the specialized prompts:
+   - **`enhancementPrompt`**: Micro-surface textures, pore fidelity, lens sharpness, and subsurface scattering.
+   - **`relightingPrompt`**: Exact lighting angles, Kelvin temperature, volumetric dust rays, and contact shadows.
+
+### Workflow F: Output Cache Inspection
+1. Call tool `list_cached_variations({ cache_dir?: "<path>" })` to inspect generated artifacts.
 
 ---
 
 ## 3. Reference Documentation
 
-For in-depth mathematical formulations and model guides:
 - [Optical Mathematics & Formulations](./references/optical_math.md)
 - [Tool Orchestration & Chaining Standards](./references/tool_orchestration.md)
-- [GPT Image & Nano Banana Guide](./references/diffusion_guide.md)
+- [Image Generator & GEMINI Nano Banana Guide](./references/diffusion_guide.md)
 
 ---
 
 ## 4. Executable Helper Scripts
 
+- Execute 6-layer optical extraction:
+  `python scripts/extract_layers.py --image <image_path> [--intent "<intent>"]`
 - Execute full end-to-end analysis & prompt synthesis from CLI:
   `node .agents/skills/mcp-relight-harmonize/scripts/run_pipeline.js <image_path>`
 - Verify server health and tool registration:

package/.agents/skills/mcp-relight-harmonize/references/diffusion_guide.md

@@ -1,22 +1,23 @@
-# Diffusion Prompt Engineering Guide: GPT Image & Nano Banana
+# Image Generator Prompt Engineering Guide: Universal & GEMINI Nano Banana
 
-This document maps physical optical metrics into specialized prompt directives for **GPT Image** and **Nano Banana**.
+This document maps physical optical metrics into specialized prompt directives compatible with **Any Image Generator Model**, with specific optimization for **GEMINI Nano Banana** in **Google Antigravity**.
 
 ---
 
-## 1. Target Engine Overview
+## 1. Target Engine Paradigms
 
-| Parameter | GPT Image (DALL-E 3 / GPT-4o) | Nano Banana (Optical Inpainting Engine) |
+| Parameter | Universal Image Generator (Natural Studio) | GEMINI Nano Banana (Optical Shaders) |
 |---|---|---|
-| **Prompt Paradigm** | Natural language, photographic directives | Dense tokenized optical descriptors |
+| **Prompt Paradigm** | Natural language, photographic studio directives | Dense tokenized optical descriptors & shaders |
 | **Optics Formulation** | 85mm prime lens f/2.0, authentic falloff | Micro-surface specular roughness, normal angle |
 | **Contact Shadows** | "physically-based contact shadows at base" | "ground contact shadow, ambient occlusion caster" |
 | **Volumetrics** | "subtle volumetric dust rays in air" | "volumetric raytraced bounce" |
 | **Denoising Default** | `0.38` | `0.38` (subtle) to `0.42` (dramatic) |
+| **Recommended Environment** | Any diffusion generator | **Google Antigravity (`generate_image`)** |
 
 ---
 
-## 2. GPT Image Prompt Architecture
+## 2. Universal Image Generator Prompt Architecture
 
 ### Enhancement Prompt Template:
 ```text
@@ -34,7 +35,7 @@ authentic photometric falloff, [User Intent].
 
 ---
 
-## 3. Nano Banana Prompt Architecture
+## 3. GEMINI Nano Banana Prompt Architecture
 
 ### Enhancement Prompt Template:
 ```text
@@ -50,7 +51,8 @@ denoising 0.38, light_azimuth_[Azimuth]deg, [User Intent]
 ```
 
 ### Recommended Parameters:
-- `model`: `"nano-banana-optical-v1"`
+- `model`: `"gemini-nano-banana"`
+- `target_environment`: `"Google Antigravity"`
 - `denoising_strength`: `0.38`
 - `guidance_scale`: `4.5`
 - `steps`: `32`

package/.agents/skills/mcp-relight-harmonize/scripts/extract_layers.py

@@ -0,0 +1,412 @@
+#!/usr/bin/env python3
+"""
+MarwanDevSpace - Dynamic 6-Layer Optical Decomposition & Intelligence Engine
+Extracts 6 analytical visual layers into Layers/ directory:
+  1. 01_highlights.png         - طبقة الألوان الفاتحة (Highlights / Specular Zones)
+  2. 02_shadows.png            - طبقة الألوان الغامقة (Shadows / Low-Key Zones)
+  3. 03_ambient_occlusion.png  - طبقة الظل العالي (Deep Ambient Occlusion & Ground Contact)
+  4. 04_edges.png              - طبقة الحواف (Sobel High-Frequency Contours)
+  5. 05_depth_normals.png      - طبقة العمق (3D Surface Normal Gradient Field)
+  6. 06_chroma_saturation.png  - طبقة الألوان والتشبع والبكسلات (Chroma & Saturation Distribution)
+
+Generates dynamic, on-demand Layer.md reports and physical generative prompts
+specifically targeting Universal Image Generator and Nano Banana without static boilerplate.
+"""
+
+import os
+import sys
+import argparse
+import json
+from typing import Optional, Dict, Any, List
+import numpy as np
+from PIL import Image
+
+def calculate_cct(r_mean: float, g_mean: float, b_mean: float) -> float:
+    """Calculates Correlated Color Temperature (Kelvin) using CIE 1931 xy and McCamy formulation."""
+    r_norm = min(max(r_mean / 255.0, 0.0), 1.0)
+    g_norm = min(max(g_mean / 255.0, 0.0), 1.0)
+    b_norm = min(max(b_mean / 255.0, 0.0), 1.0)
+
+    # Gamma linearization (sRGB -> linear RGB)
+    r_lin = ((r_norm + 0.055) / 1.055) ** 2.4 if r_norm > 0.04045 else r_norm / 12.92
+    g_lin = ((g_norm + 0.055) / 1.055) ** 2.4 if g_norm > 0.04045 else g_norm / 12.92
+    b_lin = ((b_norm + 0.055) / 1.055) ** 2.4 if b_norm > 0.04045 else b_norm / 12.92
+
+    # CIE XYZ matrix transformation
+    X = 0.4124564 * r_lin + 0.3575761 * g_lin + 0.1804375 * b_lin
+    Y = 0.2126729 * r_lin + 0.7151522 * g_lin + 0.0721750 * b_lin
+    Z = 0.0193339 * r_lin + 0.1191920 * g_lin + 0.9503041 * b_lin
+
+    total = X + Y + Z
+    if total <= 1e-7:
+        return 6500.0
+
+    x = X / total
+    y = Y / total
+    denom = 0.1858 - y
+    if abs(denom) < 1e-6:
+        denom = 1e-6 if denom >= 0 else -1e-6
+
+    n = (x - 0.3320) / denom
+    cct = 449.0 * (n ** 3) + 3525.0 * (n ** 2) + 6823.3 * n + 5520.33
+    return float(np.clip(cct, 1500.0, 20000.0))
+
+def build_dynamic_diagnostics(
+    cct_kelvin: float,
+    azimuth_deg: float,
+    elevation_deg: float,
+    hl_coverage_pct: float,
+    shadow_coverage_pct: float,
+    ao_coverage_pct: float,
+    mean_gradient: float,
+    mean_saturation: float,
+    user_intent: Optional[str] = None
+) -> Dict[str, Any]:
+    """Dynamically analyzes layer metrics to produce targeted findings, customized suggestions, and diffusion prompts."""
+    findings: List[str] = []
+    tailored_options: List[str] = []
+
+    # 1. Thermal & Chromatic Diagnostics
+    if cct_kelvin < 3800:
+        thermal_desc = f"طيف لوني دافئ جداً ({round(cct_kelvin)}K - Tungsten/Golden Hour)"
+        findings.append(f"🔥 **انحياز طيفي دافئ**: الصورة مسجلة بحرارة `{round(cct_kelvin)}K` مع غلبة للأطياف البرتقالية والصفراء في القنوات اللونية.")
+        tailored_options.append(f"موازنة حرارة الألوان من `{round(cct_kelvin)}K` إلى 5500K نهارية محايدة لإزالة المسحة الكهرمانية.")
+    elif cct_kelvin > 6500:
+        thermal_desc = f"طيف لوني بارد ({round(cct_kelvin)}K - Cool Atmospheric Skylight)"
+        findings.append(f"❄️ **انحياز طيفي بارد**: الصورة مسجلة بحرارة `{round(cct_kelvin)}K` مع غلبة للزرقة والارتداد السماوي البارد.")
+        tailored_options.append(f"تدفئة المشهد الضوئي برفع حرارة الألوان إلى 3200K (Mood Tungsten) أو 4500K سينمائي.")
+    else:
+        thermal_desc = f"طيف نهاري متوازن ({round(cct_kelvin)}K - Balanced Daylight)"
+        findings.append(f"☀️ **حرارة ألوان متوازنة**: حرارة الألوان عند `{round(cct_kelvin)}K` تماثل الإضاءة الاستوديوية المحايدة.")
+
+    # 2. Lighting Angles & Dynamic Contrast
+    light_dir = "يمين" if 0 <= azimuth_deg < 90 or 270 <= azimuth_deg <= 360 else "يسار"
+    light_vert = "علوية" if elevation_deg > 50 else "أفقية جانبية"
+    findings.append(f"💡 **توجيه الإضاءة الرئيسية**: زاوية السمت `{round(azimuth_deg)}°` (إضاءة من جهة ال{light_dir}) مع زاوية ارتفاع `{round(elevation_deg)}°` ({light_vert}).")
+
+    if shadow_coverage_pct > 35.0 and hl_coverage_pct > 15.0:
+        findings.append(f"⚡ **تباين درامي عالي (Chiaroscuro)**: كثافة الظلال `{round(shadow_coverage_pct, 1)}%` مع سعة مناطق ساطعة `{round(hl_coverage_pct, 1)}%` تدل على تباين قوي بين المفتاح الضوئي والملء.")
+        tailored_options.append("تنعيم التباين ورفع تفاصيل الظلال المغلقة عبر وضع الإضاءة المحيطية (Ambient Fill +0.8 EV).")
+    elif shadow_coverage_pct < 12.0 and hl_coverage_pct < 12.0:
+        findings.append("🌫️ **إضاءة منبسطة ناعمة (Flat Diffuse)**: تباين منخفض وغياب للمناطق الساطعة الحادة، ما يعطي مظهراً هادئاً.")
+        tailored_options.append("إضافة عمق درامي وزيادة التباين بنمط Chiaroscuro عالي التحديد مع إضاءة اتجاهية بارزة.")
+
+    # 3. Grounding & Ambient Occlusion
+    if ao_coverage_pct < 2.0:
+        findings.append(f"⚠️ **فقدان الارتكاز الأرضي (Lack of Grounding)**: نسبة الظلال التلامسية العميقة `{round(ao_coverage_pct, 2)}%` تكاد تنعدم، مما قد يظهر العنصر كأنه طافٍ في الفراغ.")
+        tailored_options.append(f"بناء وتثبيت ظل تلامسي أرضي فيزيائي (Contact Shadow Footprint) أسفل أدنى نقطة ارتكاز.")
+    else:
+        findings.append(f"⚓ **ارتكاز أرضي متماسك**: نسبة ظلال التلامس والانغلاق الموضعي `{round(ao_coverage_pct, 1)}%` تؤمن التصاقاً بصرياً طبيعياً بالأرضية.")
+
+    # 4. Surface Micro-textures & Edges
+    if mean_gradient > 0.03:
+        findings.append(f"🔍 **تفاصيل سطحية دقيقة وحواف حادة**: متوسط تباين سوبل `{round(mean_gradient, 4)}` يشير إلى وفرة في التفاصيل المجهرية والأنسجة السطحية الواضحة.")
+    else:
+        findings.append(f"🎨 **حواف ناعمة وسطح انسيابي**: متوسط تدرج سوبل `{round(mean_gradient, 4)}` يشير إلى مساحات ناعمة متصلة ومناسبة للتنعيم وإعادة التوزيع.")
+
+    # 5. Chroma / Saturation
+    if mean_saturation > 0.40:
+        findings.append(f"🌈 **تشبع لوني مكثف**: متوسط التشبع `{round(mean_saturation, 3)}` يظهر كثافة لونية حيوية في البكسلات.")
+    else:
+        findings.append(f"🔘 **لوحة لونية هادئة أو معتدلة**: متوسط التشبع `{round(mean_saturation, 3)}` يعكس تدرجات رصينة غير مبالغ بها.")
+
+    # Add custom intent option if provided
+    if user_intent:
+        tailored_options.insert(0, f"تطبيق طلبك المخصص فوراً: \"{user_intent}\" بتطابق فيزيائي دقيق مع بيانات الطبقات الست.")
+    else:
+        tailored_options.append("إعادة إضاءة بنمط هالة الحواف (Rim Light Halo +1.2 EV) لإبراز حدود المجسم وعزله عن الخلفية.")
+        tailored_options.append("دمج العنصر في خلفية جديدة مع مطابقة إحصائيات الألوان ودرجة الحرارة وظلال الارتكاز.")
+
+    # Dynamic Generative Prompts tailored to exact metrics
+    intent_clause = f", {user_intent}" if user_intent else ""
+    universal_prompt = (
+        f"A master-quality studio photograph{intent_clause}, calibrated optical lighting at {round(azimuth_deg)}° azimuth "
+        f"and {round(elevation_deg)}° elevation, authentic {round(cct_kelvin)}K color temperature balance, "
+        f"physically-grounded ambient occlusion contact shadows firmly anchoring the base plane, "
+        f"crisp micro-surface geometry (Sobel roughness index {round(mean_gradient, 3)}), "
+        f"smooth luminance falloff and authentic subsurface scattering, 85mm prime lens f/2.0."
+    )
+
+    nano_banana_prompt = (
+        f"optics relight, cct {round(cct_kelvin)}K, light vector azimuth {round(azimuth_deg)} deg elevation {round(elevation_deg)} deg, "
+        f"surface roughness {round(mean_gradient, 4)}, saturation index {round(mean_saturation, 3)}, "
+        f"ground contact occlusion caster, volumetric photon bounce, high-key rim highlight accents, "
+        f"denoising strength 0.38{intent_clause}"
+    )
+
+    return {
+        "thermalDescription": thermal_desc,
+        "findings": findings,
+        "tailoredOptions": tailored_options,
+        "universalImagePrompt": universal_prompt,
+        "nanoBananaPrompt": nano_banana_prompt,
+    }
+
+def extract_layers(image_path: str, output_dir: str = "Layers", user_intent: Optional[str] = None) -> Dict[str, Any]:
+    abs_image_path = os.path.abspath(image_path)
+    if not os.path.exists(abs_image_path):
+        raise FileNotFoundError(f"Source image not found: {abs_image_path}")
+
+    os.makedirs(output_dir, exist_ok=True)
+    abs_output_dir = os.path.abspath(output_dir)
+
+    img = Image.open(abs_image_path).convert("RGB")
+    rgb = np.array(img, dtype=np.float32)
+    height, width, _ = rgb.shape
+    num_pixels = width * height
+
+    # Luminance channel Y
+    lum = 0.2126 * rgb[:, :, 0] + 0.7152 * rgb[:, :, 1] + 0.0722 * rgb[:, :, 2]
+    norm_lum = lum / 255.0
+
+    # 1. طبقة الألوان الفاتحة (Highlights / Specular Zones)
+    hl_mask = np.clip((lum - 170.0) / 75.0, 0.0, 1.0)
+    hl_layer = rgb * hl_mask[:, :, np.newaxis]
+    hl_coverage_pct = float((np.sum(lum > 170.0) / num_pixels) * 100.0)
+    hl_path = os.path.join(abs_output_dir, "01_highlights.png")
+    Image.fromarray(np.uint8(np.clip(hl_layer, 0, 255))).save(hl_path)
+
+    # 2. طبقة الألوان الغامقة (Shadows / Low-Key Zones)
+    shadow_mask = np.clip((95.0 - lum) / 80.0, 0.0, 1.0)
+    shadow_layer = rgb * shadow_mask[:, :, np.newaxis]
+    shadow_coverage_pct = float((np.sum(lum < 85.0) / num_pixels) * 100.0)
+    shadow_path = os.path.join(abs_output_dir, "02_shadows.png")
+    Image.fromarray(np.uint8(np.clip(shadow_layer, 0, 255))).save(shadow_path)
+
+    # 3. طبقة الظل العالي (Deep Ambient Occlusion & Contact Umbra)
+    ao_mask = np.clip((40.0 - lum) / 40.0, 0.0, 1.0)
+    ao_visual = np.zeros((height, width, 3), dtype=np.float32)
+    ao_visual[:, :, 0] = (1.0 - ao_mask) * 230.0
+    ao_visual[:, :, 1] = (1.0 - ao_mask) * 240.0 + (ao_mask * 15.0)
+    ao_visual[:, :, 2] = (1.0 - ao_mask) * 255.0 + (ao_mask * 30.0)
+    ao_coverage_pct = float((np.sum(lum < 35.0) / num_pixels) * 100.0)
+    ao_path = os.path.join(abs_output_dir, "03_ambient_occlusion.png")
+    Image.fromarray(np.uint8(np.clip(ao_visual, 0, 255))).save(ao_path)
+
+    # 4. طبقة الحواف (Sobel Gradient Contours)
+    sobel_x = np.array([[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]], dtype=np.float32)
+    sobel_y = np.array([[-1, -2, -1], [0, 0, 0], [1, 2, 1]], dtype=np.float32)
+    padded_lum = np.pad(norm_lum, 1, mode="edge")
+    gx = np.zeros((height, width), dtype=np.float32)
+    gy = np.zeros((height, width), dtype=np.float32)
+    for i in range(3):
+        for j in range(3):
+            gx += sobel_x[i, j] * padded_lum[i : i + height, j : j + width]
+            gy += sobel_y[i, j] * padded_lum[i : i + height, j : j + width]
+
+    edge_mag = np.sqrt(gx ** 2 + gy ** 2)
+    edge_vis = np.clip(edge_mag * 4.0 * 255.0, 0, 255)
+    mean_gradient = float(np.mean(edge_mag))
+    edge_path = os.path.join(abs_output_dir, "04_edges.png")
+    Image.fromarray(np.uint8(edge_vis)).save(edge_path)
+
+    # 5. طبقة العمق (Depth / 3D Normal Vector Field)
+    scale = 6.0
+    nx = -gx * scale
+    ny = -gy * scale
+    nz = np.ones((height, width), dtype=np.float32)
+    mag = np.sqrt(nx ** 2 + ny ** 2 + nz ** 2) + 1e-7
+    nx_norm = nx / mag
+    ny_norm = ny / mag
+    nz_norm = nz / mag
+
+    normal_rgb = np.zeros((height, width, 3), dtype=np.float32)
+    normal_rgb[:, :, 0] = (nx_norm * 0.5 + 0.5) * 255.0
+    normal_rgb[:, :, 1] = (ny_norm * 0.5 + 0.5) * 255.0
+    normal_rgb[:, :, 2] = (nz_norm * 0.5 + 0.5) * 255.0
+    depth_path = os.path.join(abs_output_dir, "05_depth_normals.png")
+    Image.fromarray(np.uint8(np.clip(normal_rgb, 0, 255))).save(depth_path)
+
+    lum_excess = np.maximum(lum - np.mean(lum), 0.0) ** 2
+    sum_w = np.sum(lum_excess) + 1e-7
+    avg_lx = np.sum(nx_norm * lum_excess) / sum_w
+    avg_ly = np.sum(ny_norm * lum_excess) / sum_w
+    avg_lz = np.sum(nz_norm * lum_excess) / sum_w
+    l_mag = np.sqrt(avg_lx**2 + avg_ly**2 + avg_lz**2) + 1e-7
+    avg_lx, avg_ly, avg_lz = avg_lx / l_mag, avg_ly / l_mag, avg_lz / l_mag
+    azimuth_deg = (np.degrees(np.arctan2(-avg_ly, avg_lx)) + 360.0) % 360.0
+    elevation_deg = np.clip(np.degrees(np.arcsin(np.clip(avg_lz, -1.0, 1.0))), 0.0, 90.0)
+
+    # 6. طبقة الألوان والتشبع (Chrominance / Saturation Distribution)
+    max_c = np.maximum(np.maximum(rgb[:, :, 0], rgb[:, :, 1]), rgb[:, :, 2])
+    min_c = np.minimum(np.minimum(rgb[:, :, 0], rgb[:, :, 1]), rgb[:, :, 2])
+    chroma = max_c - min_c
+    sat = np.zeros_like(chroma)
+    non_zero = max_c > 1e-4
+    sat[non_zero] = chroma[non_zero] / max_c[non_zero]
+
+    sat_vis = np.zeros((height, width, 3), dtype=np.float32)
+    sat_vis[:, :, 0] = np.clip(sat * 255.0 * 1.5, 0, 255)
+    sat_vis[:, :, 1] = np.clip((1.0 - np.abs(sat - 0.5) * 2.0) * 220.0, 0, 255)
+    sat_vis[:, :, 2] = np.clip((1.0 - sat) * 200.0, 0, 255)
+    mean_saturation = float(np.mean(sat))
+    chroma_path = os.path.join(abs_output_dir, "06_chroma_saturation.png")
+    Image.fromarray(np.uint8(sat_vis)).save(chroma_path)
+
+    # Correlated Color Temperature
+    mean_r = float(np.mean(rgb[:, :, 0]))
+    mean_g = float(np.mean(rgb[:, :, 1]))
+    mean_b = float(np.mean(rgb[:, :, 2]))
+    cct_kelvin = calculate_cct(mean_r, mean_g, mean_b)
+
+    # Build Dynamic Diagnostics based purely on calculated data
+    diag = build_dynamic_diagnostics(
+        cct_kelvin=cct_kelvin,
+        azimuth_deg=azimuth_deg,
+        elevation_deg=elevation_deg,
+        hl_coverage_pct=hl_coverage_pct,
+        shadow_coverage_pct=shadow_coverage_pct,
+        ao_coverage_pct=ao_coverage_pct,
+        mean_gradient=mean_gradient,
+        mean_saturation=mean_saturation,
+        user_intent=user_intent
+    )
+
+    report = {
+        "sourceImage": abs_image_path,
+        "layersDirectory": abs_output_dir,
+        "dimensions": [width, height],
+        "opticalMetrics": {
+            "cctKelvin": round(cct_kelvin, 1),
+            "dominantLightVector": [round(float(avg_lx), 4), round(float(avg_ly), 4), round(float(avg_lz), 4)],
+            "lightingAngles": {
+                "azimuthDeg": round(float(azimuth_deg), 1),
+                "elevationDeg": round(float(elevation_deg), 1),
+            },
+            "meanLuminance": round(float(np.mean(lum)), 2),
+            "meanSaturation": round(mean_saturation, 3),
+            "edgeRoughness": round(mean_gradient, 4),
+        },
+        "diagnostics": diag,
+        "layers": {
+            "01_highlights": {
+                "file": "01_highlights.png",
+                "path": hl_path,
+                "description": "طبقة الألوان الفاتحة - High-key Luminance & Specular Zones",
+                "coveragePct": round(hl_coverage_pct, 2),
+            },
+            "02_shadows": {
+                "file": "02_shadows.png",
+                "path": shadow_path,
+                "description": "طبقة الألوان الغامقة - Low-key & Shadow Zones",
+                "coveragePct": round(shadow_coverage_pct, 2),
+            },
+            "03_ambient_occlusion": {
+                "file": "03_ambient_occlusion.png",
+                "path": ao_path,
+                "description": "طبقة الظل العالي - High Contact Shadows & Ground Occlusion",
+                "coveragePct": round(ao_coverage_pct, 2),
+            },
+            "04_edges": {
+                "file": "04_edges.png",
+                "path": edge_path,
+                "description": "طبقة الحواف - Sobel High-Frequency Gradient Contours",
+                "meanGradient": round(mean_gradient, 4),
+            },
+            "05_depth_normals": {
+                "file": "05_depth_normals.png",
+                "path": depth_path,
+                "description": "طبقة العمق - 3D Surface Normal Gradient Field (RGB Tangent Map)",
+                "dominantAzimuth": round(float(azimuth_deg), 1),
+                "dominantElevation": round(float(elevation_deg), 1),
+            },
+            "06_chroma_saturation": {
+                "file": "06_chroma_saturation.png",
+                "path": chroma_path,
+                "description": "طبقة الألوان والتشبع والبكسلات - Chrominance & Saturation Distribution",
+                "meanSaturation": round(mean_saturation, 3),
+            },
+        },
+    }
+
+    # Format findings and tailored suggestions dynamically
+    findings_rendered = "\n\n".join([f"{item}" for item in diag["findings"]])
+    options_rendered = "\n".join([f"- **خيار {idx + 1}**: {opt}" for idx, opt in enumerate(diag["tailoredOptions"])])
+
+    user_intent_header = f"\n**الهدف المخصص المطلوب**: `{user_intent}`\n" if user_intent else ""
+
+    layer_md_path = os.path.join(abs_output_dir, "Layer.md")
+    layer_md_content = f"""# تقرير الطبقات التحليلية الست (Layer.md)
+**مصدر الصورة**: `{abs_image_path}`  
+**أبعاد الصورة**: `{width}x{height}` بكسل  
+**التصنيف الضوئي المكتشف**: `{diag['thermalDescription']}`  
+**زاوية الإضاءة المسجلة**: سمت `{round(azimuth_deg)}°` | ارتفاع `{round(elevation_deg)}°`{user_intent_header}
+
+---
+
+## 1. فهرس الطبقات التحليلية الست (The 6 Extracted Layers)
+
+| # | اسم الطبقة | الملف المولد | القراءة الفيزيائية المكتشفة |
+|---|---|---|---|
+| **1** | **طبقة الألوان الفاتحة (Highlights)** | [`01_highlights.png`](file:///{hl_path.replace(os.sep, '/')}) | نسبة تغطية الأضواء الساطعة: `{round(hl_coverage_pct, 2)}%` |
+| **2** | **طبقة الألوان الغامقة (Shadows)** | [`02_shadows.png`](file:///{shadow_path.replace(os.sep, '/')}) | مساحة الظلال والمناطق الداكنة: `{round(shadow_coverage_pct, 2)}%` |
+| **3** | **طبقة الظل العالي (Ambient Occlusion)** | [`03_ambient_occlusion.png`](file:///{ao_path.replace(os.sep, '/')}) | كثافة الارتكاز الأرضي وظلال التلامس: `{round(ao_coverage_pct, 2)}%` |
+| **4** | **طبقة الحواف (Edges & Contours)** | [`04_edges.png`](file:///{edge_path.replace(os.sep, '/')}) | تباين الحواف المجهرية لسوبل: `{round(mean_gradient, 4)}` |
+| **5** | **طبقة العمق (3D Depth Normals)** | [`05_depth_normals.png`](file:///{depth_path.replace(os.sep, '/')}) | توجيه التنسور المتجهي ثلاثي الأبعاد: سمت `{round(azimuth_deg)}°` |
+| **6** | **طبقة الألوان والتشبع (Chroma / Saturation)** | [`06_chroma_saturation.png`](file:///{chroma_path.replace(os.sep, '/')}) | متوسط تشبع وتوزيع نقاء الألوان: `{round(mean_saturation, 3)}` |
+
+---
+
+## 2. النتائج البصرية الديناميكية المستخلصة من الصورة (Dynamic Findings)
+
+{findings_rendered}
+
+---
+
+## 3. التوجيه التوليدي المخصص (Calibrated Prompts for Image Generators)
+
+### أ. النمط الوصفي الاستوديوي (Any Image Generator Model):
+> "{diag['universalImagePrompt']}"
+
+### ب. نمط الشيدر الضوئي المكثف (GEMINI Nano Banana - Antigravity):
+> "{diag['nanoBananaPrompt']}"
+
+> 💡 **ملاحظة**: هذا التوجيه متوافق مع **أي Image Generator Model**، ويُفضل ويُوصى بشدة باستخدامه داخل **Google Antigravity** لتطبيق التعديل المباشر عبر أداة `generate_image` ومحرك **GEMINI Nano Banana**!
+
+---
+
+## 4. الخطوة التفاعلية الموجهة بالبيانات (Dynamic Interactive Decision)
+
+**ماذا تريد من تعديل؟**
+بناءً على المعطيات الضوئية المكتشفة في هذه الصورة تحديداً، إليك خيارات التعديل المقترحة:
+
+{options_rendered}
+
+💬 *يمكنك أيضاً طلب أي تعديل مخصص بحرية تامة، وسيتم فوراً توليد برومبت دقيق للغاية أو إنشاء الصورة المعدلة بالكامل!*
+"""
+
+    with open(layer_md_path, "w", encoding="utf-8") as f:
+        f.write(layer_md_content)
+
+    report["layerMarkdownPath"] = layer_md_path
+    return report
+
+def main():
+    parser = argparse.ArgumentParser(description="MarwanDevSpace Dynamic 6-Layer Optical Decomposition")
+    parser.add_argument("--image", "-i", required=True, help="Path to input image")
+    parser.add_argument("--output-dir", "-o", default="Layers", help="Output directory for the 6 layers (default: Layers)")
+    parser.add_argument("--intent", "-t", default=None, help="Optional user modification intent to tailor report and prompts")
+    parser.add_argument("--json", action="store_true", help="Print JSON report to stdout")
+    args = parser.parse_args()
+
+    try:
+        report = extract_layers(args.image, args.output_dir, user_intent=args.intent)
+        if args.json:
+            print(json.dumps(report, indent=2))
+        else:
+            diag = report["diagnostics"]
+            print(f"[MarwanDevSpace] 6 Analytical layers successfully extracted to: {report['layersDirectory']}")
+            print(f"[MarwanDevSpace] Dynamic Layer.md report created: {report['layerMarkdownPath']}")
+            print(f"\nOptical Profile: {diag['thermalDescription']} | Azimuth: {report['opticalMetrics']['lightingAngles']['azimuthDeg']}°")
+            print("\nKey Dynamic Findings:")
+            for f in diag["findings"][:3]:
+                print(f"  • {f}")
+            print("\n[Interactive Decision Point]: ماذا تريد من تعديل؟")
+            for opt in diag["tailoredOptions"]:
+                print(f"  - {opt}")
+    except Exception as e:
+        print(f"[Error] Failed to extract layers: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()