agent.md

# Agent Notes

- Use the `edit` conda environment for ChartPipeline commands:
  `/data/wangzheng/miniconda3/envs/edit/bin/python`.
- When invoking Python commands directly, prefer:
  `PYTHONPATH=. /data/wangzheng/miniconda3/envs/edit/bin/python ...`.
- For rendering, set:
  `PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome` and `RENDER_LONGEST_SIDE=1600`.
- For full pipeline runs in a non-login shell, include both runtime dirs in PATH:
  `export PATH=/data/wangzheng/miniconda3/envs/edit/bin:/data/wangzheng/miniconda3/envs/edit/lib/python3.12/site-packages/playwright/driver:$PATH`.
- The post-generation icon/image module is `modules.asset_regenerator.asset_regenerator`.
  It runs after `infographics_generator`, builds one contact sheet containing the full infographic
  plus all selected SVG `<image>` assets, calls `gpt-image-2`, chroma-keys the generated cells,
  and replaces only the original SVG `<image href>` / `xlink:href` values with data URI PNGs.
- During variation repair, do not call `gpt-image-2` while iterating on template/data fixes.
  First regenerate with `--modules infographics_generator` only, or run asset regeneration with
  `--dry-run` if candidate discovery needs checking. Run the real `asset_regenerator` only after
  the template-side repair passes structural/rendered validation.
- Keep before/after evidence for each repaired variation. Preserve the original sample SVG/PNG or
  render a baseline from the unmodified template, then store side-by-side comparison artifacts
  under an `output/chart_repair_comparison_*` directory.
- Keep complete code backups for every full variation-repair or style-reference iteration. Before
  editing a variation, create a timestamped backup directory under `backups/` and include every
  variation template plus every support file that may be changed in the iteration, such as docs,
  agent notes, pipeline modules, generator utilities, asset-regenerator code, and helper scripts.
- Each complete iteration backup must keep three separate trees:
  - `before_head`: the original repair-before version from `HEAD:<path>` for tracked files, or a
    missing marker for files added during repair work.
  - `before`: the exact workspace state immediately before the iteration edits begin.
  - `after`: the exact workspace state after patching, regenerating, verifying, and documenting the
    iteration.
- Never overwrite an older backup tree. If a file was already modified before the next iteration,
  preserve that pre-edit copy in `before` so the new iteration can be separated from earlier repairs.
  For untracked support files, write a missing marker in `before_head`, copy the pre-edit file into
  `before`, and copy the final file into `after`.
- Every backup directory must include `files.tsv`, `manifest.md`, pre/post `git status --short`,
  relevant `git diff --stat`, generated output paths, comparison evidence paths, verification
  evidence paths, and whether `gpt-image-2` or `asset_regenerator` was called. The manifest must make
  clear which tree is the repair-before code and which tree is the current/final code.
- Run it in the pipeline with:
  `--modules infographics_generator asset_regenerator`.
- To test without calling the image model:
  `PYTHONPATH=. /data/wangzheng/miniconda3/envs/edit/bin/python -m modules.asset_regenerator.asset_regenerator --svg <final.svg> --png <final.png> --dry-run`.
- The image edit call defaults to `--model gpt-image-2 --input-fidelity high` so the model sees
  the rendered infographic as context while only regenerating the green contact-sheet asset cells.
- Keep this module scoped to decorative icon/image assets. Do not use it to raster-overwrite the
  chart, title, labels, axes, legends, data values, chart marks, or background unless explicitly
  passing `--include-background` for a controlled experiment.
- For style-reference iterations, compare the current baseline for a variation against existing
  PNGs under `../chart_template_samples_20260527_083945/gpt_image_2_improved/<variation>`. If the
  variation was repaired in `docs/variation_repair_status.md`, use the repaired output as the
  baseline; otherwise use `../data/all_variations_check/template_variations_20260527/<variation>`.
  Choose one simple, readable, low-decoration GPT-improved reference as the style anchor, but do
  not copy its chart geometry or numeric values when they conflict with source data.
- During style-reference iterations, do not call `gpt-image-2`; existing GPT-improved PNGs are
  references only. Keep title/icon/image generation on the existing pipeline path for now.
- For every style-reference iteration, keep a timestamped code backup under `backups/`, regenerate
  5 outputs, write a baseline/reference/after comparison under `output/style_ref_comparison_*`,
  verify chart type and data mappings structurally, and record the iteration in
  `docs/style_reference_repair_status.md`.