psyclaw 0.28.1 → 0.28.3

package/vendor/nature-skills/skills/nature-figure/references/qa-contract.md

@@ -0,0 +1,344 @@
+# QA Contract
+
+## Contents
+
+- [Current official references to verify](#current-official-references-to-verify)
+- [Pre-submission checklist](#pre-submission-checklist)
+- [Statistics legend minimum](#statistics-legend-minimum)
+- [Image-integrity minimum](#image-integrity-minimum)
+- [Automated source preflight](#automated-source-preflight)
+- [Automatic multi-panel alignment gate](#automatic-multi-panel-alignment-gate)
+- [Automatic rendered collision audit](#automatic-rendered-collision-audit)
+- [Rendered panel-by-panel audit](#rendered-panel-by-panel-audit)
+- [Typography and PDF glyph floor](#typography-and-pdf-glyph-floor)
+- [Uncertainty consistency](#uncertainty-consistency)
+- [Geometry and annotation placement](#geometry-and-annotation-placement)
+- [Color separation and salience](#color-separation-and-salience)
+- [Transformation and paired-effect checks](#transformation-and-paired-effect-checks)
+- [Export checks](#export-checks)
+
+
+Use this before final delivery, before a revision package, and whenever the figure
+contains microscopy, blots, gels, clinical subgroup analysis, or statistical claims.
+Journal rules change, so verify the latest target journal author guide for final
+submission. The values below are conservative defaults for Nature-family style work.
+For the flagship journal Nature, load `nature-article-requirements.md` and use
+its stage-specific main-figure, Extended Data and legend contracts.
+
+## Current official references to verify
+
+- Nature research figure guide: `https://research-figure-guide.nature.com/`
+- Nature building/exporting panels: `https://research-figure-guide.nature.com/figures/building-and-exporting-figure-panels/`
+- Nature preparing figures/specifications: `https://research-figure-guide.nature.com/figures/preparing-figures-our-specifications/`
+- Nature initial submission and statistics guidance: `https://www.nature.com/nature/for-authors/initial-submission`
+- Nature formatting guide: `https://www.nature.com/nature/for-authors/formatting-guide`
+- Journal of Cell Biology figure/video guidelines for microscopy-oriented image QA: `https://rupress.org/jcb/pages/fig-vid-guidelines`
+- Elsevier/Cell-family image-manipulation baseline: `https://www.sciencedirect.com/journal/the-cell-surface/publish/guide-for-authors`
+
+## Pre-submission checklist
+
+| Check | Pass condition |
+|---|---|
+| Core conclusion | One-sentence claim exists and every panel maps to it |
+| Archetype | Figure has a declared archetype and panel hierarchy |
+| Backend exclusivity | The selected backend produced all plotting, previews, exports, and visual QA renders |
+| Final size | Single-column about 89 mm or double-column about 183 mm, height not above target journal limit |
+| Text size | Body/tick/legend text is readable at final size, usually 5-7 pt for dense journal figures |
+| Rendered glyph floor | Every PDF text run, including math superscripts/subscripts, is at least 5 pt |
+| Panel labels | Lowercase, bold, near top-left, typically 8 pt at final size |
+| Editable text | SVG/PDF text remains editable; no outlined text unless unavoidable for special symbols |
+| Font | Arial/Helvetica/sans-serif fallback is used consistently |
+| Color | No rainbow color maps; red/green is not the only encoding; grayscale print remains interpretable |
+| Legend strategy | Shared or direct labels where possible; no repeated redundant legends |
+| Display terminology | Legend labels use display-style initial capitalization and preserve canonical model names |
+| Statistics | `n`, biological/technical repeat definition, center, spread, test, correction, and exact comparison are documented |
+| Comparable uncertainty | Every comparable seed/fold/split aggregate panel shows the same variability definition or documents an exemption |
+| Annotation clearance | Automatic PDF collision audit has no FAIL findings; every WARN is reviewed at final size and justified or fixed |
+| Panel alignment | Every multi-panel figure has a fresh alignment JSON; comparable row/column edges, dimensions, labels and repeated gutters are within 1.5 pt or carry a reasoned exemption |
+| Visual hierarchy | Hero evidence remains more salient than neutral baselines after rendering |
+| Numerical transforms | Interpolation/normalization direction and monotonicity assumptions are asserted in code |
+| Source data | Quantitative panels can be traced to a clean CSV/TSV/XLSX or script output |
+| Raster resolution | Photos/microscopy are high-resolution enough for final size; line art uses vector where possible |
+| Microscopy scale | Scale bar is present, calibrated, and not only a magnification factor |
+| Image integrity | Crop, contrast, pseudo-color, stitching, reuse, and raw-file provenance are recorded |
+| Export bundle | Script, source data, SVG, PDF, TIFF/PNG preview, and QA notes are delivered together when requested; previews are not mislabeled as accepted main-figure upload formats |
+
+## Statistics legend minimum
+
+For each quantitative panel, capture:
+
+```text
+n definition:
+biological replicates:
+technical replicates:
+center statistic:
+spread/interval:
+test:
+multiple-comparison correction:
+p-value display:
+source-data file:
+```
+
+For machine-learning/model figures, also capture:
+
+```text
+train/validation/test split:
+number of seeds or folds:
+metric definition:
+confidence interval or variability definition:
+baseline definition:
+```
+
+## Image-integrity minimum
+
+For each image panel, capture:
+
+```text
+raw file:
+processed file:
+crop:
+brightness/contrast/gamma:
+pseudo-color:
+scale calibration:
+stitching:
+reuse in other figures:
+quantification link:
+```
+
+Global adjustments are generally safer than local selective edits. If an adjustment
+changes the visibility of relevant background or bands, flag it instead of silently
+normalizing it away.
+
+## Automated source preflight
+
+Run the dependency-free validator on the final plotting source before rendering the delivery bundle:
+
+```bash
+# Python source
+python skills/nature-figure/scripts/validate_figure.py path/to/figure.py
+
+# R, R Markdown, or Quarto source
+python skills/nature-figure/scripts/validate_figure.py path/to/figure.R
+
+# Machine-readable report or stricter warning gate
+python skills/nature-figure/scripts/validate_figure.py path/to/figure.py --json
+python skills/nature-figure/scripts/validate_figure.py path/to/figure.py --strict
+
+# Exported-PDF glyph-size audit
+python skills/nature-figure/scripts/audit_pdf_text.py path/to/figure.pdf --min-pt 5
+python skills/nature-figure/scripts/audit_pdf_text.py path/to/figure.pdf --min-pt 5 --json
+
+# Backend-neutral audit of the render-time Python/R panel-layout manifest
+python skills/nature-figure/scripts/audit_panel_alignment.py path/to/figure.alignment-layout.json \
+  --json-out path/to/figure.alignment.json \
+  --overlay-svg path/to/figure.alignment.svg \
+  --strict
+
+# Mandatory rendered collision audit for Python and R figures
+python skills/nature-figure/scripts/audit_figure_collisions.py path/to/figure.pdf \
+  --json-out path/to/figure.collision-audit.json \
+  --overlay-pdf path/to/figure.collision-audit.pdf
+
+# Optional: make ambiguous WARN findings blocking
+python skills/nature-figure/scripts/audit_figure_collisions.py path/to/figure.pdf --strict
+```
+
+The source preflight checks syntax, font configuration and size floor, mathtext shrinkage risk, literal legend-label capitalization, unsafe color maps, editable-text settings, vector/raster exports, DPI, common journal widths, potential sampling or unreported missing-data exclusion, simulated-data leakage, log guards, interpolation monotonicity, stochastic uncertainty encoding, rotated-text anchoring, risky annotation workarounds, and obvious cross-backend plotting references. The panel-alignment gate reads final axes/grob rectangles measured by the selected backend and applies one physical-point contract to Python and R. The PDF text audit scans supported content streams for actual `Tf` font-size operators and catches reduced script glyphs that source-level `fontsize` checks miss. The rendered collision audit uses PyMuPDF geometry from the final PDF and therefore applies equally to Python- and R-generated figures.
+
+Treat the result as a deterministic source audit, not as evidence that the analysis or rendered figure is correct. Resolve all `FAIL` findings before delivery. Review every `WARN`, then run the selected backend and inspect the actual SVG/PDF/TIFF/PNG outputs at final size. A warning may be acceptable only when the QA notes state the reason.
+
+## Automatic multi-panel alignment gate
+
+Run the gate for every figure with at least two comparable panels, after the
+final layout engine has drawn fonts, legends, colorbars and constrained/tight
+layout, and before exporting submission files. Rerun it after any change that
+can affect panel geometry. A single-panel figure is `not applicable`; a
+multi-panel figure with no declared or inferable comparison groups is `NOT
+AUDITABLE`, not a pass.
+
+The default tolerance is `1.5 pt` (about `0.53 mm`) at final physical size. The
+auditor checks:
+
+- panels in one row: common top and bottom edges plus equal plot-area height;
+- three or four same-row panels with equal grid spans: equal final plot-area
+  widths within `1.5 pt`;
+- panels in one column: common left and right edges plus equal plot-area width;
+- unequal-span grid panels: shared outer start/stop edges, including automatic
+  `left two + right one` and `left one + right two` arrangements;
+- three or more comparable panels: uniform repeated horizontal/vertical gutters;
+- detectable bold lowercase top-left panel labels: common y anchors within rows
+  and common x anchors within columns;
+- plot-area rectangles do not overlap.
+
+For Matplotlib, copy `audit_panel_alignment.py` beside the plotting script or
+add the skill scripts directory to `PYTHONPATH`, then call this after the last
+layout change:
+
+```python
+from audit_panel_alignment import require_matplotlib_panel_alignment
+
+require_matplotlib_panel_alignment(
+    fig,
+    json_out="figure.alignment.json",
+    overlay_svg="figure.alignment.svg",
+    tolerance_pt=1.5,
+    gutter_tolerance_pt=1.5,
+    require_panel_labels=True,
+    strict=True,
+)
+```
+
+Ordinary `subplots`/`GridSpec` row and column groups are inferred from
+`SubplotSpec`. A panel spanning both grid rows is automatically compared with
+the upper small panel at their shared top boundary and the lower small panel at
+their shared bottom boundary; this works whether the spanning panel is in the
+left or right column. The spanning panel is not incorrectly required to equal
+either small panel's height. Position outside panel letters with a fixed point
+offset from the axes corner rather than a shared axes-fraction offset, because
+`y=1.02` produces different physical displacements for tall and short panels.
+For a horizontal row of three or four panels, equal column spans imply equal
+final widths. Intentional unequal `width_ratios` must use a narrow exemption
+such as `{"panels": ["b"], "checks": ["panel-width"], "reason": "middle hero panel"}`;
+do not exempt the entire row or increase the tolerance.
+Pass explicit `row_groups` and `column_groups` when axes come from nested grids
+or separately created containers. Exclude a
+colorbar or inset with `exclude_axes=[...]`, or add an exemption containing the
+affected panel, the exact checks and a non-empty scientific/layout reason.
+
+For R/patchwork, source `panel_alignment.R` and call
+`require_patchwork_panel_alignment()` with the same width/height used for final
+export. Common patchwork groups and structured unequal-span designs are inferred
+from gtable cells, including two stacked panels beside a two-row spanning panel
+in either column. Same-row groups of three or four equal gtable spans must also
+have equal final widths. Nested or manually positioned designs must provide explicit
+`row_groups` / `column_groups`. The R helper requires `patchwork`, `grid` and
+`jsonlite`; it measures in R and invokes the Python CLI only to audit the
+resulting JSON, so it does not redraw or replace the R figure.
+
+| Result | Required action |
+|---|---|
+| `NOT APPLICABLE`, exit `0` | Single rendered plot-area only; preserve the JSON and continue |
+| `PASS`, exit `0` | Preserve the alignment JSON and continue to export/PDF QA |
+| `FIX BEFORE DELIVERY`, exit `1` | Correct the selected-backend layout and rerun; do not export the delivery bundle |
+| `REVIEW REQUIRED` | Resolve WARN or document it; `--strict` makes WARN blocking |
+| `NOT AUDITABLE`, exit `2` | Supply valid measured geometry and comparison groups; do not claim alignment passed |
+
+The QA-only alignment SVG shows measured panel rectangles, not scientific
+content. It must not replace the selected backend's figure. Do not weaken the
+global tolerance to hide one exception. Structured grid spanning is audited
+automatically; a free-positioned hero panel, inset, legend-only axis or colorbar
+should be omitted from unrelated groups or carry a specific exemption reason.
+
+## Automatic rendered collision audit
+
+Run `audit_figure_collisions.py` after **every generated figure and every
+revision that can change layout**, including edits to text, fonts, legend,
+annotations, axes, data, uncertainty, panel size or arrangement. Do not reuse a
+report from an earlier render. Preserve the JSON report with the delivery QA;
+the marked PDF is diagnostic only.
+
+| Result | Meaning | Required action |
+|---|---|---|
+| `text-text` FAIL | Two rendered text boxes materially overlap | Separate, shorten, rotate or resize the labels and rerun |
+| `text-stroke` FAIL | A line, curve, marker edge, error bar or other stroked path crosses the interior of text | Move the text or alter the layout; do not hide the path with an opaque white box |
+| `text-page-clipping` FAIL | A rendered text trace extends beyond the final PDF page | Expand/reposition the layout and re-export |
+| `text-fill-edge` WARN | Text only partly overlaps a bar, heatmap cell or other fill | Inspect at final size; fix unless the edge overlap is intentional and legible |
+| `text-image-edge` WARN | Text only partly overlaps a raster image boundary | Inspect panel labels, scale bars and image annotations at final size |
+| contained overlay count | Text is fully inside a fill or image | Informational because in-bar labels, heatmap values and image annotations can be intentional |
+
+Exit code `1` and verdict `FIX BEFORE DELIVERY` block delivery. Exit code `2`
+or `NOT AUDITABLE` means the PDF/dependency could not be checked and must not be
+reported as a pass. `REVIEW REQUIRED` does not silently pass: inspect each WARN
+and record the reason, or use `--strict` to make WARN blocking. PyMuPDF is
+declared in `requirements.txt`; install it with:
+
+```bash
+python -m pip install -r skills/nature-figure/requirements.txt
+```
+
+The detector deliberately separates reliable geometry failures from ambiguous
+fill/image overlays. It does not prove visual quality, semantic correctness,
+adequate contrast or accessibility, so the final-size panel audit remains
+mandatory.
+
+## Rendered panel-by-panel audit
+
+Do not approve a figure from a whole-page glance. Inspect each panel at final physical size, then inspect the assembled figure. Record one row per panel:
+
+| Panel | Unique claim | Center/summary | Spread/interval | Replicate unit | Labels/legend | Alignment group/result | Collision check | Pass |
+|---|---|---|---|---|---|---|---|---|
+| a | What question only this panel answers | mean/median/raw | SD/SE/CI/none + reason | seeds/folds/subjects/etc. | exact display labels | row/column group, deviation or exemption | collision report findings + data/error extent + text bbox | yes/no |
+
+Cover each panel mentally. If the figure's argument remains complete, merge or remove that panel. Compare repeated panels side by side for consistent terminology, uncertainty, axes, and color mapping. After adding error bars or uncertainty bands, remove arrows, brackets, or fills that encode the same gap and occupy the same geometry.
+
+## Typography and PDF glyph floor
+
+- The 5 pt floor applies to every rendered glyph, not only the parent `fontsize` in source code.
+- Matplotlib mathtext commonly scales superscripts/subscripts to about 0.7 of the parent. A 7 pt `$R^2$` can therefore contain a 4.9 pt glyph. Prefer a Unicode glyph such as `R²` when it preserves the intended notation, or increase the parent size and confirm the PDF audit.
+- Measure long labels against their allocated group width at final size. Compare rendered text bounding-box width in millimetres with the available slot; do not rely on the source font number alone.
+- Keep canonical capitalization such as `XGBoost`, `DeepSeek`, `GPT-5.2`, and `RF`. Legend labels start with display-style capitalization, while prose follows normal sentence grammar. Do not use blind string title-casing.
+
+## Uncertainty consistency
+
+- If a line or bar is a mean/median across random seeds, folds, splits, subjects, or repeated experiments, encode the requested spread in every comparable panel.
+- State the exact definition, for example `median ± one seed SD`, in the legend or panel notes. Do not infer or invent it.
+- Presence of one `fill_between`, `errorbar`, `yerr`, or `geom_errorbar` call does not prove coverage. Use the panel audit table to verify every comparable panel.
+- Recompute label clearance from the upper uncertainty extent after error bars are added.
+
+## Geometry and annotation placement
+
+- Measure spacing between the actual objects being compared. Use rendered/tight bounding boxes for panel-to-legend or legend-row gaps; scanning an entire raster row can mix unrelated objects at different horizontal positions.
+- Use plot-area rectangles for axes alignment and tight bounding boxes for outer-content clearance; do not confuse unequal tick-label widths with a shifted data rectangle.
+- Derive label positions from data and uncertainty bounds, for example `max(center + spread) + margin`, rather than a fixed `LABEL_Y`.
+- For rotated Matplotlib text, use `rotation_mode="anchor"` and verify the final bounding box.
+- If a curve crosses a label, reposition the label beyond the local data envelope. Avoid opaque white `bbox` masks that cut a conspicuous hole in a line.
+- Equal pixel y-coordinates can still look uneven when bar heights create unequal whitespace. Diagnose the perceived gap before moving already aligned labels.
+
+## Color separation and salience
+
+- Pairwise ΔE and white-background contrast are necessary checks, not a complete design test.
+- Verify hierarchy after rendering: neutral baselines should not appear stronger than the proposed method or primary evidence.
+- Do not repurpose a sequential light-to-dark palette as unrelated categorical colors merely because the hues look attractive.
+- Check grayscale and color-vision robustness, then inspect the actual figure because metrics do not encode which series should dominate attention.
+
+## Transformation and paired-effect checks
+
+- `numpy.interp` requires increasing `xp`. Use `scripts/figure_safety.py::interp_monotone`, or explicitly assert monotonicity and reverse/sort `xp` and `fp` together. Plausible-looking output is not evidence of correctness.
+- Do not plan one figure per source table. Group panels by the distinct claims they support.
+- When repeated units are matched, inspect paired differences. Broad between-dataset or between-subject heterogeneity can make four marginal distributions overlap even when the within-unit effect is strong; use a paired-difference view when the scientific claim is paired.
+
+## Export checks
+
+Run only the export block for the selected backend. If that backend is unavailable,
+stop and report the missing runtime/package instead of producing a substitute export
+with the other language.
+
+### Python
+
+```python
+import matplotlib as mpl
+mpl.rcParams["svg.fonttype"] = "none"
+mpl.rcParams["pdf.fonttype"] = 42
+fig.savefig("figure.svg", bbox_inches="tight")
+fig.savefig("figure.pdf", bbox_inches="tight")
+fig.savefig("figure.tiff", dpi=600, bbox_inches="tight")
+```
+
+### R
+
+```r
+svglite::svglite("figure.svg", width = width_mm / 25.4, height = height_mm / 25.4)
+print(plot)
+dev.off()
+
+grDevices::cairo_pdf("figure.pdf", width = width_mm / 25.4, height = height_mm / 25.4, family = "Arial")
+print(plot)
+dev.off()
+
+ragg::agg_tiff("figure.tiff", width = width_mm / 25.4, height = height_mm / 25.4, units = "in", res = 600)
+print(plot)
+dev.off()
+```
+
+Open the SVG/PDF after export and verify that text can be selected, labels do not
+overlap, and the figure still reads at final printed size.

package/vendor/nature-skills/skills/nature-figure/references/r-template-index.md

@@ -0,0 +1,66 @@
+# Private R Template Adaptation
+
+Use this reference when the user chooses R and provides or mentions an existing
+R plotting template collection. Treat such material as private working context.
+Do not reveal absolute paths, folder names, filenames, screenshots, provenance, or
+any identifying labels from the source collection in user-facing output.
+
+## Privacy rules
+
+- Never include absolute local paths in generated code, reports, comments, or final replies.
+- Never mention the original source file, folder, template number, course title, download
+  location, chat attachment, or private document name.
+- When a template is useful, describe it generically by chart family: "a grouped bar
+  template", "a ComplexHeatmap workflow", "a survival plotting workflow".
+- If a reusable idea is copied from a private template, rewrite the final code as a clean,
+  self-contained script with neutral function names and neutral comments.
+- If the user asks where a style came from, say it was adapted from the provided working
+  materials without identifying the path or source file.
+
+## Generic search strategy
+
+Search private materials by chart family and package names, not by exposing paths:
+
+```bash
+find <private-template-root> -type f \( -name '*.R' -o -name '*.Rmd' -o -name '*.r' \)
+rg -n "ggplot|patchwork|ComplexHeatmap|ggrepel|svglite|cairo_pdf|survminer|circlize" <private-template-root>
+```
+
+Keep these commands in internal working notes only. Do not paste the user's private
+root path into the final answer.
+
+## Chart-family map
+
+Use these generic families to decide what to inspect:
+
+| Need | Search targets |
+|---|---|
+| Bars and grouped comparisons | `geom_col`, `geom_bar`, `position_dodge`, `stat_compare_means` |
+| Error bars and point-interval plots | `geom_errorbar`, `geom_pointrange`, `mean_se`, `stat_summary` |
+| Stacked or bidirectional bars | `position_stack`, `coord_flip`, signed values, paired positive/negative bars |
+| Box, violin, paired, and raincloud-style distributions | `geom_boxplot`, `geom_violin`, `geom_jitter`, paired sample identifiers |
+| Heatmaps and annotated heatmaps | `ComplexHeatmap`, `HeatmapAnnotation`, `pheatmap`, `geom_tile` |
+| Correlation, scatter, bubble, and volcano plots | `geom_point`, `geom_smooth`, `ggrepel`, `logFC`, `pvalue`, bubble size scales |
+| PCA, PCoA, NMDS, tSNE, UMAP | `prcomp`, `cmdscale`, `vegan`, `Rtsne`, `Seurat`, embedding coordinates |
+| Survival, Cox, subgroup, ROC, forest | `survival`, `survminer`, `coxph`, `forestplot`, `timeROC`, hazard ratios |
+| Enrichment and pathway summaries | `clusterProfiler`, `GSEA`, `enrichGO`, `enrichKEGG`, dot plots, ridge plots |
+| Circular, genome, phylogeny, chromosome | `circlize`, `ggtree`, `karyoploteR`, genome interval tracks |
+| Single-cell and omics workflows | `Seurat`, marker genes, differential expression, cell-type annotation |
+| Maps, anatomy, and spatial summaries | `sf`, `maps`, `gganatogram`, spatial coordinates |
+| Radar, lollipop, dumbbell, UpSet, Venn, Sankey | `ggradar`, `geom_segment`, `UpSetR`, `ggalluvial`, set operations |
+
+## Adaptation checklist
+
+When adapting a private template:
+
+- Keep useful data wrangling, statistics, and geoms.
+- Replace template-specific colors with the figure-level semantic palette.
+- Normalize fonts to final-size 5-7 pt text and 8 pt bold lowercase panel labels.
+- Convert single-output PNG/PDF scripts to SVG/PDF/TIFF export.
+- Remove decorative elements that do not support the core conclusion.
+- Ensure each statistical comparison has `n`, center, spread, test, and correction
+  information in the legend or source-data notes.
+- For image panels, document raw file, crop, contrast, scale-bar calibration, and any
+  stitching or pseudo-coloring in private QA notes.
+- Final code should be self-contained and should not require the original private
+  folder structure unless the user explicitly asks to keep that workflow.

package/vendor/nature-skills/skills/nature-figure/references/r-workflow.md

@@ -0,0 +1,234 @@
+# R Workflow
+
+## Contents
+
+- [R-only execution rule](#r-only-execution-rule)
+- [Required packages by task](#required-packages-by-task)
+- [Contract scaffold](#contract-scaffold)
+- [Panel labels in R](#panel-labels-in-r)
+- [Patchwork layout patterns](#patchwork-layout-patterns)
+- [Patchwork panel-alignment gate](#patchwork-panel-alignment-gate)
+- [ComplexHeatmap export](#complexheatmap-export)
+- [Template reuse rule](#template-reuse-rule)
+
+
+Use this when the user chooses R, brings R data/scripts, or asks to reuse the local
+R plotting templates. The R track should still follow the same figure contract:
+claim first, evidence hierarchy second, plotting code third.
+
+## R-only execution rule
+
+When the user has selected R, do all figure drawing, previewing, exporting, and
+visual QA in R. Do not call Python/matplotlib/seaborn/plotly to create a temporary
+preview, fallback export, or layout approximation. If R, `Rscript`, or required R
+packages are missing, pause rendering, continue independent script or data checks, and report the missing dependency. You
+may still write the R script, provide `install.packages()` commands, or ask permission
+to install dependencies, but do not cross-render the figure in another language.
+
+Allowed non-R utilities are limited to non-visual tasks such as shell file inspection,
+CSV line counts, checksums, archive extraction, or text search. They must not create
+image/vector outputs or alter visual layout.
+
+## Required packages by task
+
+| Task | Preferred packages |
+|---|---|
+| Bars, boxplots, violins, dot plots, lines, volcano plots | `ggplot2`, `ggrepel`, `dplyr`, `tidyr` |
+| Multi-panel assembly and alignment QA | `patchwork`, `grid`, `jsonlite`; use `cowplot` only when inset alignment requires it |
+| Rich omics heatmaps | `ComplexHeatmap`, `circlize`, `grid` |
+| Survival and clinical subgroup plots | `survival`, `survminer`, `forestplot`, `ggplot2` |
+| Circular/genome plots | `circlize`, `ggtree`, `gggenes`, domain-specific packages |
+| Export | `svglite`, `grDevices::cairo_pdf`, `ragg` |
+
+## Contract scaffold
+
+```r
+library(ggplot2)
+library(patchwork)
+source("skills/nature-figure/scripts/panel_alignment.R")
+
+palette_contract <- c(
+  neutral_dark = "#272727",
+  neutral_mid = "#767676",
+  neutral_light = "#D8D8D8",
+  signal_blue = "#3182BD",
+  signal_teal = "#33B5A5",
+  accent_red = "#D24B40",
+  accent_orange = "#E28E2C"
+)
+
+theme_nature_contract <- function(base_size = 6.5, base_family = "Arial") {
+  theme_classic(base_size = base_size, base_family = base_family) +
+    theme(
+      axis.line = element_line(linewidth = 0.35, colour = "black"),
+      axis.ticks = element_line(linewidth = 0.35, colour = "black"),
+      axis.title = element_text(size = base_size),
+      axis.text = element_text(size = base_size - 0.5),
+      legend.title = element_text(size = base_size - 0.3),
+      legend.text = element_text(size = base_size - 0.7),
+      strip.text = element_text(size = base_size - 0.3, face = "bold"),
+      plot.title = element_text(size = base_size + 0.5, face = "bold"),
+      panel.grid = element_blank()
+    )
+}
+
+theme_set(theme_nature_contract())
+
+save_pub_r <- function(plot, filename, width_mm = 183, height_mm = 120, dpi = 600) {
+  w <- width_mm / 25.4
+  h <- height_mm / 25.4
+
+  if (inherits(plot, "patchwork")) {
+    require_patchwork_panel_alignment(
+      plot,
+      manifest_path = paste0(filename, ".alignment-layout.json"),
+      report_path = paste0(filename, ".alignment.json"),
+      overlay_svg = paste0(filename, ".alignment.svg"),
+      width_in = w,
+      height_in = h,
+      tolerance_pt = 1.5,
+      gutter_tolerance_pt = 1.5,
+      strict = TRUE
+    )
+  }
+
+  svglite::svglite(paste0(filename, ".svg"), width = w, height = h)
+  print(plot)
+  dev.off()
+
+  grDevices::cairo_pdf(paste0(filename, ".pdf"), width = w, height = h, family = "Arial")
+  print(plot)
+  dev.off()
+
+  ragg::agg_tiff(paste0(filename, ".tiff"), width = w, height = h, units = "in", res = dpi)
+  print(plot)
+  dev.off()
+}
+```
+
+## Panel labels in R
+
+Use patchwork tags for most multi-panel figures:
+
+```r
+fig <- (p_a | p_b) / (p_c | p_d) +
+  plot_annotation(tag_levels = "a") &
+  theme(plot.tag = element_text(size = 8, face = "bold"))
+```
+
+Use manual labels only when dark image plates or inset geometry make patchwork tags
+misalign.
+
+## Patchwork layout patterns
+
+### Quantitative grid
+
+```r
+fig <- (p_a | p_b | guide_area()) /
+       (p_c | p_d | p_e) +
+  plot_layout(guides = "collect", widths = c(1, 1, 0.45)) &
+  theme(legend.position = "right")
+```
+
+### Schematic-led composite
+
+```r
+design <- "
+AAAA
+BBCD
+"
+fig <- p_schematic + p_b + p_c + p_d +
+  plot_layout(design = design, heights = c(1.8, 1))
+```
+
+### Image plate plus quant
+
+Keep black backgrounds inside image panels only. Put scale bars on the image, then
+place quantification next to or below the representative image.
+
+```r
+p_img <- ggplot(img_df, aes(x, y, fill = intensity)) +
+  geom_raster() +
+  scale_fill_gradient(low = "black", high = "white") +
+  coord_fixed(expand = FALSE) +
+  annotate("segment", x = 10, xend = 40, y = 10, yend = 10,
+           linewidth = 0.6, colour = "white") +
+  theme_void() +
+  theme(legend.position = "none", plot.background = element_rect(fill = "black", colour = NA))
+```
+
+## Patchwork panel-alignment gate
+
+`panel_alignment.R` converts the final patchwork gtable cells to physical-point
+rectangles on a temporary R graphics device with the same dimensions as the
+real export. It then invokes the backend-neutral
+`audit_panel_alignment.py` JSON auditor. Python does not render or modify the R
+figure.
+
+Simple patchwork grids infer row/column groups from gtable cells. Structured
+unequal-span designs are also automatic: two stacked panels in the left column
+beside one two-row panel in the right column, and the mirrored arrangement,
+receive shared top/bottom boundary checks without an invalid equal-height
+comparison. Horizontal groups of three or four equal gtable spans must also
+have equal final widths; intentional unequal widths require a reasoned
+`panel-width` exemption. For nested or manually composed figures, declare the intended
+comparisons explicitly:
+
+```r
+require_patchwork_panel_alignment(
+  fig,
+  manifest_path = "figures/fig2.alignment-layout.json",
+  report_path = "figures/fig2.alignment.json",
+  overlay_svg = "figures/fig2.alignment.svg",
+  width_in = 183 / 25.4,
+  height_in = 120 / 25.4,
+  panel_ids = c("a", "b", "c", "d"),
+  row_groups = list(c("a", "b"), c("c", "d")),
+  column_groups = list(c("a", "c"), c("b", "d")),
+  exemptions = list(
+    list(
+      panels = c("a"),
+      checks = c("column", "panel-width"),
+      reason = "hero panel intentionally spans the evidence columns"
+    )
+  ),
+  tolerance_pt = 1.5,
+  gutter_tolerance_pt = 1.5,
+  strict = TRUE
+)
+```
+
+Every exemption must name the panel, the exact check and the reason. Do not
+increase the global tolerance to hide an inset, colorbar, legend-only cell or
+hero panel. A non-zero audit status stops the R delivery script. Preserve both
+the measured layout manifest and audit JSON; the alignment SVG is QA-only.
+
+## ComplexHeatmap export
+
+`ComplexHeatmap` objects are grid objects, not ggplot objects. Export them by opening
+the graphics device, drawing, then closing it.
+
+```r
+library(ComplexHeatmap)
+library(circlize)
+
+pdf("heatmap.pdf", width = 7.2, height = 4.8, family = "Arial")
+draw(ht, heatmap_legend_side = "right", annotation_legend_side = "right")
+dev.off()
+
+svglite::svglite("heatmap.svg", width = 7.2, height = 4.8)
+draw(ht, heatmap_legend_side = "right", annotation_legend_side = "right")
+dev.off()
+```
+
+## Template reuse rule
+
+The local R materials are examples, not final style. When reusing them:
+
+1. Inspect only the nearest template folder.
+2. Keep useful data wrangling, statistics, and geoms.
+3. Replace ad hoc colors, oversized fonts, dense legends, and PNG-only export.
+4. Rebuild the final script around `theme_nature_contract()` and `save_pub_r()`.
+5. Add source-data output if the figure is manuscript-facing.
+
+Open `references/r-template-index.md` for the local template atlas.