@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/run-experiment/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: "run-experiment"
+description: "Deploy and run ML experiments on local or remote GPU servers. Use when user says \"run experiment\", \"deploy to server\", \"\u8dd1\u5b9e\u9a8c\", or needs to launch training jobs."
+---
+
+# Run Experiment
+
+Deploy and run ML experiment: $ARGUMENTS
+
+## Workflow
+
+### Step 1: Detect Environment
+
+Read the project's `AGENTS.md` to determine the experiment environment:
+
+- **Local GPU**: Look for local CUDA/MPS setup info
+- **Remote server**: Look for SSH alias, conda env, code directory
+- **Vast.ai instance**: Look for `gpu: vast`, `vast_instance`, SSH host/port, remote path, and optional `auto_destroy`
+- **Modal serverless**: Look for `gpu: modal`, app/function name, image/dependency setup, and secrets
+
+If no server info is found in `AGENTS.md`, ask the user.
+
+### Step 2: Pre-flight Check
+
+Check GPU availability on the target machine:
+
+**Remote:**
+```bash
+ssh <server> nvidia-smi --query-gpu=index,memory.used,memory.total --format=csv,noheader
+```
+
+**Local:**
+```bash
+nvidia-smi --query-gpu=index,memory.used,memory.total --format=csv,noheader
+# or for Mac MPS:
+python -c "import torch; print('MPS available:', torch.backends.mps.is_available())"
+```
+
+Free GPU = memory.used < 500 MiB.
+
+### Step 3: Sync Code (Remote Only)
+
+Check the project's `AGENTS.md` for a `code_sync` setting. If not specified, default to `rsync`.
+
+#### Option A: rsync (default)
+
+Only sync necessary files — NOT data, checkpoints, or large files:
+```bash
+rsync -avz --include='*.py' --exclude='*' <local_src>/ <server>:<remote_dst>/
+```
+
+#### Option B: git (when `code_sync: git` is set in AGENTS.md)
+
+Push local changes to remote repo, then pull on the server:
+```bash
+# 1. Push from local
+git add -A && git commit -m "sync: experiment deployment" && git push
+
+# 2. Pull on server
+ssh <server> "cd <remote_dst> && git pull"
+```
+
+Benefits: version-tracked, multi-server sync with one push, no rsync include/exclude rules needed.
+
+#### Option C: Vast.ai instance
+
+If `gpu: vast` is configured, treat the Vast.ai machine as a remote server with an explicit lifecycle:
+
+1. Verify the instance is running and reachable.
+2. Sync code to the configured remote path.
+3. Confirm data/checkpoints are already mounted or intentionally copied.
+4. Record the instance id in the launch summary for later cleanup.
+
+Do not silently ignore a requested Vast.ai route. If Vast.ai CLI credentials or instance metadata are missing, stop and ask the user to configure them.
+
+### Step 3.5: W&B Integration (when `wandb: true` in AGENTS.md)
+
+**Skip this step entirely if `wandb` is not set or is `false` in AGENTS.md.**
+
+Before deploying, ensure the experiment scripts have W&B logging:
+
+1. **Check if wandb is already in the script** — look for `import wandb` or `wandb.init`. If present, skip to Step 4.
+
+2. **If not present, add W&B logging** to the training script:
+   ```python
+   import wandb
+   wandb.init(project=WANDB_PROJECT, name=EXP_NAME, config={...hyperparams...})
+
+   # Inside training loop:
+   wandb.log({"train/loss": loss, "train/lr": lr, "step": step})
+
+   # After eval:
+   wandb.log({"eval/loss": eval_loss, "eval/ppl": ppl, "eval/accuracy": acc})
+
+   # At end:
+   wandb.finish()
+   ```
+
+3. **Metrics to log** (add whichever apply to the experiment):
+   - `train/loss` — training loss per step
+   - `train/lr` — learning rate
+   - `eval/loss`, `eval/ppl`, `eval/accuracy` — eval metrics per epoch
+   - `gpu/memory_used` — GPU memory (via `torch.cuda.max_memory_allocated()`)
+   - `speed/samples_per_sec` — throughput
+   - Any custom metrics the experiment already computes
+
+4. **Verify wandb login on the target machine:**
+   ```bash
+   ssh <server> "wandb status"  # should show logged in
+   # If not logged in:
+   ssh <server> "wandb login <WANDB_API_KEY>"
+   ```
+
+> The W&B project name and API key come from `AGENTS.md` (see example below). The experiment name is auto-generated from the script name + timestamp.
+
+### Step 4: Deploy
+
+#### Remote (via SSH + screen)
+
+For each experiment, create a dedicated screen session with GPU binding:
+```bash
+ssh <server> "screen -dmS <exp_name> bash -c '\
+  eval \"\$(<conda_path>/conda shell.bash hook)\" && \
+  conda activate <env> && \
+  CUDA_VISIBLE_DEVICES=<gpu_id> python <script> <args> 2>&1 | tee <log_file>'"
+```
+
+#### Vast.ai instance
+
+Use the same SSH + screen pattern, but include the Vast.ai instance id, public SSH endpoint, and remote working directory in the report. If `auto_destroy: true`, write a cleanup command to the run notes before launch.
+
+Record the estimated hourly cost, expected run duration, and cleanup owner. If the command fails to start or the instance becomes unreachable, do not relaunch blindly; capture logs and ask for a rescue / second opinion before spending more GPU time.
+
+#### Modal (serverless)
+
+If `gpu: modal` is configured, deploy through Modal instead of SSH:
+
+```bash
+modal run <module_or_app>.py -- <args>
+```
+
+Before launch, verify required secrets, volumes, image dependencies, and output persistence. If Modal is requested but the project lacks Modal configuration, stop and ask the user to configure it rather than falling back to local execution.
+
+Record the Modal app/function name, GPU type, timeout, mounted volumes, and where results will be stored. If Modal reports an image, secret, or volume error, preserve the exact error and run a configuration fix before retrying.
+
+#### Local
+
+```bash
+# Linux with CUDA
+CUDA_VISIBLE_DEVICES=<gpu_id> python <script> <args> 2>&1 | tee <log_file>
+
+# Mac with MPS (PyTorch uses MPS automatically)
+python <script> <args> 2>&1 | tee <log_file>
+```
+
+For local long-running jobs, use `run_in_background: true` to keep the conversation responsive.
+
+### Step 5: Verify Launch
+
+**Remote:**
+```bash
+ssh <server> "screen -ls"
+```
+
+**Local:**
+Check process is running and GPU is allocated.
+
+### Step 6: Feishu Notification (if configured)
+
+After deployment is verified, check `~/.codex/feishu.json`:
+- Send `experiment_done` notification: which experiments launched, which GPUs, estimated time
+- If config absent or mode `"off"`: skip entirely (no-op)
+
+### Step 7: Auto-Destroy Vast.ai Instance (when `gpu: vast` and `auto_destroy: true`)
+
+Only run this after the experiment has completed and results/logs/checkpoints have been copied or otherwise persisted.
+
+1. Verify the target process has exited.
+2. Copy result files and logs to the configured durable location.
+3. Ask for confirmation unless AGENTS.md explicitly says `auto_destroy: true`.
+4. Destroy only the recorded instance id for this run.
+
+If any artifact copy fails, do not destroy the instance.
+
+## Key Rules
+
+- ALWAYS check GPU availability first — never blindly assign GPUs
+- Each experiment gets its own screen session + GPU (remote) or background process (local)
+- Use `tee` to save logs for later inspection
+- Run deployment commands with `run_in_background: true` to keep conversation responsive
+- Report back: which GPU, which screen/process, what command, estimated time
+- If multiple experiments, launch them in parallel on different GPUs
+
+## AGENTS.md Example
+
+Users should add their server info to their project's `AGENTS.md`:
+
+```markdown
+## Remote Server
+- SSH: `ssh my-gpu-server`
+- GPU: 4x A100 (80GB each)
+- Conda: `eval "$(/opt/conda/bin/conda shell.bash hook)" && conda activate research`
+- Code dir: `/home/user/experiments/`
+- code_sync: rsync          # default. Or set to "git" for git push/pull workflow
+- wandb: false              # set to "true" to auto-add W&B logging to experiment scripts
+- wandb_project: my-project # W&B project name (required if wandb: true)
+- wandb_entity: my-team     # W&B team/user (optional, uses default if omitted)
+
+## Vast.ai
+- gpu: vast
+- vast_instance: 123456
+- SSH: `ssh -p 12345 root@ssh.vast.ai`
+- Code dir: `/workspace/experiments/`
+- auto_destroy: false
+
+## Modal
+- gpu: modal
+- modal_app: `train.py`
+- modal_secrets: `wandb-secret`
+- modal_volume: `experiment-results`
+
+## Local Environment
+- Mac MPS / Linux CUDA
+- Conda env: `ml` (Python 3.10 + PyTorch)
+```
+
+> **W&B setup**: Run `wandb login` on your server once (or set `WANDB_API_KEY` env var). The skill reads project/entity from `AGENTS.md` and adds `wandb.init()` + `wandb.log()` to your training scripts automatically. Dashboard: `https://wandb.ai/<entity>/<project>`.

package/dist/skills/scientific-figure-making/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: scientific-figure-making
+description: >-
+  Covers publication-ready matplotlib figures for academic papers, slides, and
+  reports—bars, trends, scatter, heatmaps, and multi-panel layouts—with this
+  repository’s house style, print/vector export conventions, and parity with
+  figures4papers demos. Use when the user is finalizing or creating such figures
+  in matplotlib. Do not use for interactive dashboards or web viz (Plotly, Altair,
+  Bokeh), exploratory-only plots without a publication target, dominant 3D or
+  geographic mapping, or Illustrator/Figma-first infographic workflows.
+---
+
+# Scientific figure making
+
+Open `references/` only as needed; do not preload every file. Start from the table below, then follow links inside the document you opened (and into `figure_*` code via [references/demos.md](references/demos.md)) instead of loading the full reference set up front.
+
+## When to load this skill
+
+- Matplotlib figures for **papers, slides, or reports** that must match **this repo’s publication look** (fonts, palette, spines, legends, export).
+- Requests involving **grouped bars, trend lines, heatmaps, multi-panel grids**, or **PDF/SVG/high-DPI** output in a scientific-figure context.
+- References to **figures4papers** `figure_*` projects or “same style as the repo figures.”
+
+## When not to load
+
+- **Plotly, Altair, Bokeh**, or other interactive / web-first plotting.
+- **EDA-only** plots where seaborn or pandas is enough until there is a publication target.
+- Primary workflow is **3D, GIS**, or **non-matplotlib** tooling.
+- **Illustrator / Figma–first** layout or infographic (not matplotlib data plots).
+
+## Related files
+
+| File | Open when |
+|------|-----------|
+| [references/tutorials.md](references/tutorials.md) | End-to-end walkthroughs (bar, trends, heatmap) |
+| [references/api.md](references/api.md) | Function signatures, `PALETTE`, validation rules |
+| [references/common-patterns.md](references/common-patterns.md) | Layout patterns, legend panel, print-safe bars |
+| [references/design-theory.md](references/design-theory.md) | Typography, export policy, palette rationale |
+| [references/demos.md](references/demos.md) | Canonical `figure_*` demo links in figures4papers |

package/dist/skills/scientific-figure-making/references/api.md

@@ -0,0 +1,152 @@
+# API Reference
+
+This document specifies the conventions, constants, and function signatures that implementations should follow for publication-style figures. Implement these in your own code or adapt from the [figure_* demos](demos.md).
+
+---
+
+## Constants
+
+### PALETTE
+
+Semantic color map for publication figures.
+
+```python
+PALETTE = {
+    "blue_main": "#0F4D92",
+    "blue_secondary": "#3775BA",
+    "green_1": "#DDF3DE", "green_2": "#AADCA9", "green_3": "#8BCF8B",
+    "red_1": "#F6CFCB", "red_2": "#E9A6A1", "red_strong": "#B64342",
+    "neutral": "#CFCECE", "highlight": "#FFD700",
+    "teal": "#42949E", "violet": "#9A4D8E",
+}
+```
+
+Use blues for key/proposed methods, greens for improvements, reds for baselines/contrasts, neutral for background.
+
+### DEFAULT_COLORS
+
+Ordered list of colors used when `colors` is not passed to plot helpers: `[blue_main, green_3, red_strong, teal, violet, neutral]`.
+
+---
+
+## FigureStyle
+
+```python
+@dataclass(frozen=True)
+class FigureStyle:
+    font_size: int = 16
+    axes_linewidth: float = 2.5
+    use_tex: bool = False
+    font_family: tuple[str, ...] = ("DejaVu Sans", "Helvetica", "Arial", "sans-serif")
+```
+
+- **font_size:** Base font size (use 24 for large bar panels, 15-16 for compact plots).
+- **axes_linewidth:** Spine width (3 for big bars, 2 for compact).
+- **use_tex:** Set `True` only when LaTeX is installed and math labels are required.
+- **font_family:** Fallback list for sans-serif fonts.
+
+---
+
+## Style and Layout
+
+### apply_publication_style(style=None)
+
+Configures matplotlib rcParams: spines (top/right off), frameless legend, font family/size, vector export options. Call once before creating figures.
+
+```python
+apply_publication_style(FigureStyle(font_size=24, axes_linewidth=3))
+```
+
+### create_subplots(nrows=1, ncols=1, figsize=None, **kwargs)
+
+Returns `(fig, axes)` with `axes` a flattened 1D array of Axes. Pass `figsize=(width, height)` in inches.
+
+```python
+fig, axes = create_subplots(2, 2, figsize=(12, 8))
+```
+
+### finalize_figure(fig, out_path, formats=None, dpi=300, close=True, pad=0.05, **kwargs)
+
+Saves the figure to one or more formats (e.g. `['png', 'pdf']`). If `formats` is None, uses extension of `out_path` or defaults to pdf/svg/eps. Creates parent directories. Returns list of saved `Path`s.
+
+```python
+finalize_figure(fig, "output/result", formats=["png", "pdf"], dpi=300, pad=0.06)
+```
+
+---
+
+## Plot Helpers
+
+### make_grouped_bar(ax, categories, series, labels, ylabel='Value', colors=None, annotate=False)
+
+Renders grouped bars. `categories`: list of x labels; `series`: list of arrays (one per group), same length as categories; `labels`: legend labels. Returns the last `BarContainer` (for use with `annotate_bars`).
+
+```python
+make_grouped_bar(ax, ["A", "B", "C"], [[1,2,3], [2,1,2]], ["X", "Y"], ylabel="Score", annotate=True)
+```
+
+### annotate_bars(ax, bars, fmt='{:.2f}', fontsize=10, padding=3)
+
+Adds text above each bar in a `BarContainer`.
+
+```python
+bars = make_grouped_bar(ax, cats, series, labels, annotate=False)
+annotate_bars(ax, bars, fmt="{:.1f}", fontsize=12)
+```
+
+### make_trend(ax, x, y_series, labels, colors=None, ylabel=None, xlabel=None, show_shadow=True)
+
+Plots multiple lines with optional uncertainty band. `y_series`: list of 1D arrays (same length as `x`).
+
+```python
+make_trend(ax, epochs, [acc_a, acc_b], ["Model A", "Model B"], ylabel="Accuracy", show_shadow=True)
+```
+
+### make_heatmap(ax, matrix, x_labels=None, y_labels=None, cmap='magma', cbar_label=None, annotate=False)
+
+Renders a 2D heatmap. Optionally adds colorbar label and cell annotations.
+
+```python
+make_heatmap(ax, corr_matrix, x_labels=names, y_labels=names, cbar_label="Correlation")
+```
+
+### make_scatter(ax, x, y, label=None, color=None, size=50, alpha=0.7)
+
+Single-series scatter. `x`, `y` must be same-length 1D arrays.
+
+```python
+make_scatter(ax, x_vals, y_vals, label="Samples", color=PALETTE["blue_main"])
+```
+
+### make_sphere_illustration(ax, light_dir=(-0.5, 0.5, 0.8), resolution=128, alpha=0.6)
+
+Draws a shaded 2D disk to mimic a 3D sphere. Use for conceptual diagrams.
+
+```python
+make_sphere_illustration(ax, light_dir=(-0.55, 0.65, 0.55), resolution=280)
+```
+
+---
+
+## Validation Rules
+
+- All numeric sequences are converted to numpy arrays; 1D/2D and length checks are enforced.
+- `make_grouped_bar`: `len(categories)` must equal number of columns in `series`.
+- `make_trend`: each series must have same length as `x`.
+- `finalize_figure`: supported formats are pdf, svg, eps, png, jpg, jpeg, tif, tiff.
+
+See [design-theory.md](design-theory.md) for visual and export conventions.
+
+## Conventions
+
+- Save script outputs under a project `figures/` directory (or the path the user gives) with stable basenames; `finalize_figure` creates parent directories as needed.
+- In batch or headless runs, set a non-interactive backend before `import matplotlib.pyplot` (for example `matplotlib.use("Agg")`).
+- When comparisons, panel count, color roles, resolution, or data layout are underspecified in a way that would change the figure, confirm with the user before finalizing.
+
+## Related files
+
+- [SKILL.md](../SKILL.md) — When to load this skill
+- [demos.md](demos.md) — Canonical `figure_*` repo links
+- [common-patterns.md](common-patterns.md) — Layout, legend panel, print-safe encoding
+- [design-theory.md](design-theory.md) — Rationale and rcParams-style presets
+- [tutorials.md](tutorials.md) — End-to-end examples and pointers beyond the three core tutorials

package/dist/skills/scientific-figure-making/references/common-patterns.md

@@ -0,0 +1,74 @@
+# Common Patterns for Publication Figures
+
+These patterns are used across the repository for consistent, publication-ready figures. Apply them when building bar charts, multi-panel layouts, and print-safe graphics. Step-by-step flows that use many of these ideas are in [tutorials.md](tutorials.md); for chart types not covered there, use the closing section of that file and [demos.md](demos.md).
+
+---
+
+## Ultra-wide aspect for multi-metric panels
+
+For 3-4 metrics or many categories in a single row, use a wide canvas so bars/labels don't crowd vertically.
+
+- **Example:** `figsize=(45, 12)` or `(28, 6)`.
+- **Rule:** Width often 3-4× height for comparison bars.
+- **Why:** Lets the reader scan left-to-right without squinting; keeps y-axis and legend readable.
+
+---
+
+## Dedicated legend panel
+
+When multiple curves or groups make the legend large, put it in its own subplot so it doesn't cover data.
+
+- **Steps:**
+  1. Create one extra subplot (e.g. last in the grid).
+  2. Call `ax.set_axis_off()` on that axis.
+  3. Build the legend on that axis (e.g. gather handles/labels from other axes and call `ax.legend(handles, labels)` there), or use a single legend that you place in the extra axis.
+- **Result:** Data panels stay clean; legend is fully visible.
+
+---
+
+## Categorical bars without x-tick labels
+
+When the x-axis is "method" or "condition" and the legend already identifies them, hide x ticks and rely on the legend/title.
+
+- **Code:** `ax.set_xticks([])` or set tick labels to empty.
+- **Use when:** Many methods across multiple metrics; names are in the legend or panel title.
+
+---
+
+## Dynamic y-axis scaling
+
+Tighten y-limits to the relevant range so differences are visible instead of squashed.
+
+- **Idea:** Use something like `data.min() - margin` to `data.max() + margin` (e.g. margin = small fraction of range or one std).
+- **Avoid:** Fixed 0-100 when all values are in 85-95; use e.g. 80-100 instead.
+
+---
+
+## Bar edge and hatch for print-safe separation
+
+Bars that differ only by fill can blur in grayscale. Use edges and optional hatching.
+
+- **Edges:** `edgecolor='black'`, `linewidth=1.5`-`3` for clear separation.
+- **Hatch:** Same color with different hatch (e.g. `'/'`, `'\\'`, `'.'`) for ablation or subgroups so they remain distinct in print.
+
+---
+
+## Semantic color mapping
+
+Stick to the skill palette so "proposed vs baseline" is consistent across figures.
+
+- **Blues:** Proposed method / key result.
+- **Greens:** Improvements / positive variants.
+- **Reds:** Baselines / contrasts / alternatives.
+- **Neutral:** Reference or background categories.
+- **Highlight:** Single callout only.
+
+See [design-theory.md](design-theory.md) for the full palette and [api.md](api.md) for `PALETTE` and `DEFAULT_COLORS`.
+
+## Related files
+
+- [SKILL.md](../SKILL.md) — When to load this skill
+- [api.md](api.md) — `PALETTE`, helpers, validation
+- [demos.md](demos.md) — Real scripts mirroring these patterns
+- [design-theory.md](design-theory.md) — Visual and color theory
+- [tutorials.md](tutorials.md) — Walkthroughs that apply these patterns

package/dist/skills/scientific-figure-making/references/demos.md

@@ -0,0 +1,30 @@
+# Real-World Demos and Figure Scripts
+
+The design theory, patterns, and guidance in this skill are derived from the figure-making scripts in the [figures4papers](https://github.com/ChenLiu-1996/figures4papers) repository. Those scripts are the canonical demos for this skill.
+
+**Repository:** [https://github.com/ChenLiu-1996/figures4papers](https://github.com/ChenLiu-1996/figures4papers)
+
+## Project folders (demos)
+
+Each folder contains Python scripts and (in `figures/`) outputs that follow the skill's house style. Use them as references for bar charts, trend and line panels, heatmaps, radar or polar comparisons, and multi-panel layouts.
+
+| Project | Link | Notes |
+|--------|------|--------|
+| **figure_ImmunoStruct** | [figures4papers/figure_ImmunoStruct](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_ImmunoStruct) | Bar plots for quantitative comparison |
+| **figure_CellSpliceNet** | [figures4papers/figure_CellSpliceNet](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_CellSpliceNet) | Bar comparison, ablation |
+| **figure_brainteaser** | [figures4papers/figure_brainteaser](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_brainteaser) | Bar composition breakdown |
+| **figure_VIGIL** | [figures4papers/figure_VIGIL](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_VIGIL) | Radar plots, line plots |
+| **figure_ophthal_review** | [figures4papers/figure_ophthal_review](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_ophthal_review) | Trend plots |
+| **figure_RNAGenScape** | [figures4papers/figure_RNAGenScape](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_RNAGenScape) | Heat maps |
+| **figure_Dispersion** | [figures4papers/figure_Dispersion](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_Dispersion) | 3D-style spheres, performance plots |
+| **figure_Cflows** | [figures4papers/figure_Cflows](https://github.com/ChenLiu-1996/figures4papers/tree/main/figure_Cflows) | Comparison, ablation, trajectory plots |
+
+For full scripts, outputs, and data, clone or browse the repo. The figure_* folders are the canonical implementations of this skill's style.
+
+## Related files
+
+- [SKILL.md](../SKILL.md) — When to load this skill
+- [api.md](api.md) — Constants, helpers, validation
+- [common-patterns.md](common-patterns.md) — Layout and legend patterns
+- [design-theory.md](design-theory.md) — Style theory and reproduction rules
+- [tutorials.md](tutorials.md) — Step-by-step figure builds

package/dist/skills/scientific-figure-making/references/design-theory.md

@@ -0,0 +1,138 @@
+# Publication Figure Design Theory (Derived from Repository Scripts)
+
+This theory is inferred from the Python plotting scripts in the [figures4papers](https://github.com/ChenLiu-1996/figures4papers) repository (the `figure_*` project folders). See [demos.md](demos.md) for links to those demos.
+
+## 1) Core Matplotlib Style System
+
+The dominant house style is minimalist, high-contrast, and publication-oriented:
+
+- Typography:
+  - Primary: `font.family = 'helvetica'` (used in 16 scripts).
+  - Secondary exception: `font.family = 'sans-serif'` (2 scripts, mostly geometric illustrations).
+  - Practical portability recommendation: prefer fallback stack `['Arial', 'Helvetica', 'DejaVu Sans', 'sans-serif']`.
+- Size hierarchy:
+  - Large-panel bar/comparison figures: `font.size = 24`, `axes.linewidth = 3`.
+  - Paper subfigures/compact analytic plots: `font.size = 15-16`, `axes.linewidth = 2`.
+- Axes cleanup:
+  - `axes.spines.right = False`
+  - `axes.spines.top = False`
+- LaTeX usage:
+  - `text.usetex = True` appears in TeX-heavy scripts (6 files), especially when math-rich labels are needed.
+- Vector text:
+  - `svg.fonttype = 'none'` appears when preserving editable text in vector exports.
+
+## 2) Export and Output Policy
+
+- DPI defaults:
+  - Standard: `dpi=300` (dominant: 23 save calls).
+  - Very dense bar panels: `dpi=600` (used in ImmunoStruct bars).
+- Layout finalization:
+  - `fig.tight_layout(pad=2)` is the default finishing pass (21 occurrences).
+  - `pad=1` is used for compact multi-panel plots.
+- Mostly opaque white-background output; occasional `bbox_inches='tight'` with explicit `pad_inches` for edge-to-edge composites.
+
+## 3) Color Theory and Palette Structure
+
+The repository uses a consistent semantic palette family:
+
+- Anchor/brand blue:
+  - `#0F4D92` and `#3775BA` (method-of-interest / reference baseline).
+- Green performance bands (often incremental gains):
+  - `#DDF3DE`, `#AADCA9`, `#8BCF8B`.
+- Warm red/pink comparator bands:
+  - `#F6CFCB`, `#E9A6A1`, `#B64342`.
+- Neutral support grays:
+  - `#CFCECE`, `#767676`, `#4D4D4D`, `#272727`.
+- Occasional accent/highlight colors:
+  - Gold `#FFD700`, magenta-like `#EA84DD`, teal `#42949E`, violet `#9A4D8E`.
+
+Design intent:
+
+- Use blue for "proposed" or key method.
+- Use green shades for related positives/improvements.
+- Use pink/red shades for alternatives or contrasts.
+- Keep neutrals for baselines and background categories.
+
+## 4) Layout and Composition Logic
+
+Common geometric/layout decisions:
+
+- **Ultra-Wide Aspect Ratios:** For multi-metric comparisons (e.g., 3-4 metrics), the repository uses extremely wide canvases (e.g., `figsize=(45, 12)` or `(28, 6)`). This prevents vertical crowding and allows metrics to be read as a narrative from left to right.
+- **Dedicated Legend Panels:** In complex multi-axis figures, a sub-plot is often dedicated solely to the legend (`ax.set_axis_off()`). This keeps the data panels clean and prevents legend boxes from overlapping critical data regions.
+- **Categorical Abstracting:** Category bars usually hide x-tick labels (`ax.set_xticks([])`) and rely on legends/titles instead. This is particularly effective when comparing many methods across multiple metrics.
+- **Dynamic Y-Axis Scaling:** Y-limits are manually tightened to relevant ranges (often derived from `data.min() - data.std()`), emphasizing comparative differences rather than absolute values.
+- **Consistency over Embellishment:** Multi-panel consistency is favored over per-axis embellishment. All subplots in a row share the same font sizes, linewidths, and color semantic mapping.
+
+## 5) Bar Encoding Strategy
+
+For publication-grade grouped/ablation bars:
+
+- **In-Place Annotation:** Scientific values are often printed directly above bars (`ax.text`) with large fonts (36pt) to make exact numbers readable without a grid.
+- **Manual Tick Positioning:** Uses `FixedLocator` for precise control over Y-axis granularity.
+- **Strong edge treatment:** Bars use black edges (`edgecolor='black'`) with `linewidth=1.5-3` for sharp separation.
+- **Alpha-Based Ablation:** Ablation studies often use the same primary color (e.g., `blue_secondary`) with varying `alpha` levels (0.2 to 1.0) to represent the "completeness" of a method.
+- **Hatch Encoding:** Optional hatch channels (slashes/backslashes/dots) are used for subtype overlays to remain readable in grayscale print.
+
+## 6) Trend/Line Encoding Strategy
+
+- Limited line count per axis (usually 2-4 primary curves).
+- Use consistent line width around `2-3` with controlled alpha.
+- Use `fill_between` for uncertainty when needed.
+- Keep grid minimal or absent; rely on axis ticks and direct legend reading.
+
+**Polar / radar:** Keep the number of series readable at publication size; use the same line-weight and label discipline as Cartesian trends. Repository examples live under `figure_VIGIL` (see [demos.md](demos.md)).
+
+## 7) Scatter/Illustration Encoding Strategy
+
+- Dense geometric scenes use lowered alpha and muted fills.
+- Important trajectories/relations use saturated warm accents with arrows.
+- Axis ticks often removed for conceptual diagrams.
+
+## 8) Recommended Reusable rcParams Preset
+
+```python
+PUBLICATION_RCPARAMS = {
+    "font.family": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
+    "font.size": 16,            # use 24 for large comparison bars
+    "axes.spines.right": False,
+    "axes.spines.top": False,
+    "axes.linewidth": 2.5,      # 3 for big bars, 2 for compact figures
+    "legend.frameon": False,
+    "svg.fonttype": "none",
+}
+```
+
+## 9) Recommended Default Palette
+
+```python
+PALETTE = {
+    "blue_main": "#0F4D92",
+    "blue_secondary": "#3775BA",
+    "green_1": "#DDF3DE",
+    "green_2": "#AADCA9",
+    "green_3": "#8BCF8B",
+    "red_1": "#F6CFCB",
+    "red_2": "#E9A6A1",
+    "red_strong": "#B64342",
+    "neutral": "#CFCECE",
+    "highlight": "#FFD700",
+}
+```
+
+## 10) Reproduction Rules
+
+To match the repository's visual identity for new figures:
+
+1. Apply minimalist spines (top/right off), frameless legends, and explicit y-limits.
+2. Use Helvetica/Arial-like sans fonts with larger sizing for bars.
+3. Choose colors from the blue-green-red-neutral family above; avoid unrelated palettes.
+4. Finalize with `tight_layout(pad=2)` and export at `dpi=300` (or `600` for dense bar panels).
+5. Use hatch/edge encodings for print-safe category separation when bars overlap in hue.
+
+## Related files
+
+- [SKILL.md](../SKILL.md) — When to load this skill
+- [api.md](api.md) — Formal `PALETTE` and function contracts
+- [demos.md](demos.md) — Repository scripts this theory summarizes
+- [common-patterns.md](common-patterns.md) — Operational patterns from the theory
+- [tutorials.md](tutorials.md) — Hands-on flows grounded in this theory