Merge branch 'main' into main

Author: RankFTW

.agents/skills/AGENTS.md

@@ -0,0 +1,40 @@
+# AGENTS: RenoDX skill authoring
+
+This folder contains project-local workflow skills. Keep skills focused, discoverable, and useful for agents that may not have prior RenoDX context.
+
+## Skill frontmatter
+
+- Each skill must use `SKILL.md` under `.agents/skills/<skill-name>/`.
+- Keep `name` identical to the folder name.
+- Quote `description` values, especially when they contain colons, commas, or trigger phrases.
+- Treat `description` as the discovery surface: include the concrete words a user or agent will mention.
+- Keep `argument-hint` short and focused on the minimum context needed to start the workflow.
+
+## Bundled resources
+
+- Skill folders may include `templates/`, `snippets/`, `scripts/`, `references/`, or other small support files.
+- Reference any bundled file from `SKILL.md` with a relative Markdown link; agents load skill resources progressively and may not discover unreferenced files.
+- Prefer small templates and snippets that remove repeated scratch scaffolds or copy-paste shader boilerplate.
+- Do not bundle large captures, generated plots, game dumps, binaries, or one-off investigation artifacts.
+- Keep snippets clearly marked as starting points, not copy-paste replacements for game-specific proof.
+
+## Scope and overlap
+
+- Keep always-on repository rules in root or nested `AGENTS.md`; keep task-specific procedures in skills.
+- Start each broad skill with a short boundary or related-skills section when overlap is likely.
+- Prefer handoff language over duplication when another skill owns the next step.
+- Do not turn skills into scratch logs; move only stable workflow guidance into committed skill files.
+
+## RenoDX-specific expectations
+
+- Preserve the RenoDX distinction between upstream HDR/source recovery and final-frame inverse-tonemap postprocessing.
+- Treat RenoDX mods as neutral by default: preserve vanilla/original SDR contrast, saturation, hue, and grade while extending proven range/resource limits into HDR. Default settings should match the original as closely as practical; visual augmentation belongs in explicit sliders or presets such as `HDR Look`. Do not bake in "HDR = more contrast/saturation" looks.
+- For swapchain/resource work, keep `SwapChainPass`, proxy resources, output presets, color-space synchronization, and UI/HUD separation together.
+- For shader math, require a proven target pass/resource before applying tonemap, LUT, hard-clip, or HDR bridge guidance.
+- For analysis images and plots, keep source data and scripts reproducible and prefer dark-theme output.
+
+## Maintenance checks
+
+- After editing skills, validate Markdown diagnostics for the changed files.
+- Check that new trigger phrases are in the relevant `description`, not only in the body.
+- Keep `.agents/skills/README.md` in sync when adding, removing, or substantially changing a skill.

.agents/skills/README.md

@@ -0,0 +1,32 @@
+# RenoDX Workflow Skills
+
+This folder contains project-local workflow skills for AI agents and contributors. Skills are on-demand procedures: use them when a task matches their domain instead of putting every workflow detail in always-on instructions.
+
+RenoDX keeps shared workflow skills under `.agents/skills/` for the tool-neutral Agent Skills convention.
+
+Default RenoDX mod behavior should be neutral: preserve the vanilla/original SDR art direction and extend its proven pipeline limits into HDR. Default settings should match the original look as closely as practical; visual augmentation belongs in explicit sliders or presets such as `HDR Look`, not in the baseline. Do not assume HDR means more contrast, more saturation, or a new look.
+
+## How to use
+
+- Agents: match the request to the table below, read the relevant `SKILL.md`, then follow its boundaries and handoffs.
+- Users: mention the skill name or trigger terms in chat when you want a specific RenoDX workflow.
+- Keep `AGENTS.md` for always-on repository rules; keep skills for specialized multi-step work.
+
+## Skill index
+
+| Skill | Use when | Handoff boundary |
+|---|---|---|
+| `setup-game-mod-dev` | Starting or resuming a game mod, setting up DevKit, configuring build targets, linking into a game folder, or creating baseline verification. | Hand off to `swapchain-resource-analysis` for resource/output proof and to `handle-sdr-tonemap-lut` for proven shader math. |
+| `swapchain-resource-analysis` | Tracing final output, swapchain formats, render resources, `SwapChainPass`, proxy resources, SDR/HDR toggles, or proving whether scene HDR data still exists. | Hand off to `setup-game-mod-dev` for addon wiring/builds and to `handle-sdr-tonemap-lut` after the shader-side target signal is proven. |
+| `handle-sdr-tonemap-lut` | Editing shader-side tonemap, hard clip, LUT/color grade, RenoDRT, vanilla/0 `ToneMapPass`, Preset Off vanilla reset, PsychoV, gamut compression, hue/saturation clip emulation, or HDR bridge logic after upstream signals are known. | Hand off to `swapchain-resource-analysis` if the target pass/resource or source signal is not proven. |
+| `analysis-graphing` | Creating dark-theme plots, curve comparisons, hue sweeps, gamut comparisons, LUT statistics, or image diagnostic panels. | Hand off to `hdr-test-pattern-generation` for source pattern generation and to `bt2020-png-generation` for final HDR PNG output. |
+| `hdr-test-pattern-generation` | Generating deterministic SDR/HDR ramps, charts, sweeps, color bars, checkerboards, gamut stress images, or validation sources. | Hand off to `analysis-graphing` for plotting results and to `bt2020-png-generation` for PQ PNG encoding/signaling. |
+| `bt2020-png-generation` | Producing or validating BT.2020/BT.2100 PQ PNGs, cICP chunks, ICC/cicpTag behavior, or HDR PNG artifacts from analysis data. | Hand off to `hdr-test-pattern-generation` for synthetic sources and to `analysis-graphing` for plots. |
+
+## Maintenance notes
+
+- The `description` field in each `SKILL.md` is the discovery surface. Put important trigger phrases there.
+- Skill folders may include referenced templates, snippets, scripts, and resources; link them from `SKILL.md` so agents can load them when needed.
+- Keep overlapping skills connected by explicit handoff text instead of copying the same procedure into multiple files.
+- Keep examples tied to stable RenoDX concepts or committed project patterns.
+- Validate changed Markdown files before committing.

.agents/skills/analysis-graphing/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: analysis-graphing
+description: "RenoDX workflow for creating readable analysis graphs and plots from shader math, CSVs, EXRs, LUTs, hue sweeps, tone curves, gamut comparisons, energy/scalar maps, and test-pattern statistics. Use when graphing, plotting, visualizing, comparing curves, making dark-theme matplotlib figures, or avoiding repeated one-off plot scripts."
+argument-hint: "data source, variables to compare, output path, units/axis scale, and whether the graph is scratch or durable"
+---
+
+# RenoDX Analysis Graphing
+
+Use this small skill for **plots and graphs**. Larger skills should call this out instead of embedding graphing rules.
+
+## Boundaries
+
+- Focus on visualizing data, not generating source test images or editing shaders.
+- Keep one-off plots and source scripts in a scratch output path unless the graph becomes a durable analysis artifact.
+- Promote repeated graph workflows into `tools/analysis/` with the data export beside the image.
+- Prefer `matplotlib` for Python analysis unless an existing script in the same workflow already uses another plotting library.
+- Use `bt2020-png-generation` for final HDR PQ PNG writing and signaling.
+- Use `hdr-test-pattern-generation` for ramps, sweeps, charts, and synthetic image inputs.
+
+## Default style
+
+- Use a dark theme by default: `plt.style.use("dark_background")`.
+- Save readable static images: usually PNG at `dpi=150` to `180`.
+- Choose figure sizes for labels first, not minimum pixels; common overview plots are `14x9`, `16x11`, or `17x11` inches.
+- Close figures after saving to avoid leaking state in batch scripts.
+- If the graph will be inspected in an issue or PR, prefer a single self-contained overview image plus any focused split images.
+
+## Plot checklist
+
+For every generated graph, make the output self-describing:
+
+- Title states the experiment and transform/version being compared.
+- Axes include units: nits, linear RGB, PQ code value, hue degrees, stops, frame index, etc.
+- Legends use stable method names matching CSV column names or shader function names.
+- Include reference lines for anchors such as zero, diffuse white, mid-gray, `1.0`, peak nits, or gamut boundary when relevant.
+- Do not normalize silently. If data is normalized, show the normalization factor in the title, label, or CSV.
+- Use log/stops axes only when the labels make the scale obvious.
+- Save the plotted source data as CSV when values are generated rather than loaded from an existing CSV.
+
+## Common RenoDX graph types
+
+| Graph type | Use for | Notes |
+|---|---|---|
+| Tone/inverse diagnostic curve | Vanilla vs RenoDRT/PsychoV/ACES matching | Mark diffuse white, mid-gray, peak, and shoulder anchors; inverse plots are for fitting/diagnosis, not final-frame inverse-tonemap strategy. |
+| Gain/loss or delta plot | Comparing old/new math or fitted curves | Plot absolute output and error/delta, not only one. |
+| Hue sweep | Gamut compression, hue preservation, negative-channel checks | Hue degrees on x-axis; include min/max channel or perceptual metric. |
+| Gamut scatter / chip grid | BT.709, BT.2020, AP1/AP0 comparisons | State source gamut and adaptation path. |
+| LUT/stat overview | LUT pair comparisons, channel summaries, error histograms | Keep CSV summaries beside the graph. |
+| Image diagnostic panel | EXR/test-pattern before/after comparisons | Use fixed scales when comparing panels. |
+
+## Existing examples
+
+- [Dark plot template](./templates/dark_plot.py) for a minimal reusable matplotlib setup.
+- `tools/analysis/plot_cp2077_*` for readable dark-theme multi-panel graphs.
+- `tools/analysis/validate_mb_compress.py` for hue sweep validation and CSV-plus-plot output.
+- scratch `zelda_*` curve and derivative plots.
+
+## Common mistakes to avoid
+
+- Do not output light-theme graphs unless the user explicitly requests that style.
+- Do not crop legends, tick labels, or colorbars; use `tight_layout()` or explicit layout spacing.
+- Do not mix scene-linear, display-linear nits, and encoded PQ values on one axis without clear labels.
+- Do not present a graph without preserving the script or source CSV needed to reproduce it.
+- Do not keep copying a repeated plotting scaffold across scratch scripts; promote the pattern when it recurs.

.agents/skills/analysis-graphing/templates/dark_plot.py

@@ -0,0 +1,48 @@
+"""Minimal RenoDX dark-theme matplotlib template.
+
+Copy this into a scratch experiment or promote it into `tools/analysis/` when the
+plot workflow becomes durable. Keep generated source data beside the image.
+"""
+
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+
+
+def configure_dark_plot() -> None:
+    plt.style.use("dark_background")
+    plt.rcParams.update(
+        {
+            "figure.dpi": 150,
+            "savefig.dpi": 170,
+            "axes.grid": True,
+            "grid.alpha": 0.22,
+            "legend.framealpha": 0.85,
+        }
+    )
+
+
+def save_figure(fig: plt.Figure, output_path: str | Path) -> None:
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    fig.tight_layout()
+    fig.savefig(output_path)
+    plt.close(fig)
+
+
+def example_plot(output_path: str | Path) -> None:
+    configure_dark_plot()
+    fig, ax = plt.subplots(figsize=(14, 9))
+    x = [0, 0.18, 1, 4, 8]
+    y = [0, 0.18, 1, 2, 3]
+    ax.plot(x, y, label="candidate")
+    ax.axvline(1, color="white", alpha=0.35, linestyle="--", label="diffuse white")
+    ax.set_title("RenoDX comparison: replace with experiment name")
+    ax.set_xlabel("Scene-linear input relative to diffuse white")
+    ax.set_ylabel("Display-linear output relative to diffuse white")
+    ax.legend()
+    save_figure(fig, output_path)
+
+
+if __name__ == "__main__":
+    example_plot(Path("scratch_outputs") / "renodx_dark_plot_example.png")