# AGENTS.md — Agentic Eclipse Library

You are reading the record of a real project: photographing the total solar eclipse of 12 August 2026 with two
camera trains and turning the RAW frames into a faithful HDR image of the solar corona. The work was done by AI
coding agents under the direction of the photographer, Pere Guerra Serra. This file tells you what is here, where
to start, and which working rules made the difference.

## Start with the user's goal

If the user has not stated a goal, ask in their language with short, ordinary choices:
process eclipse photos, continue an existing image, make an animation, or explore the library.
If they are unsure, offer to inspect the files they identify and suggest a starting point.
Do not assume that opening this library means they want a RAW-to-Photoshop workflow.
If the goal is explicit, use it without asking again. Ask only for information needed for the next step.

For an explicit RAW-to-Photoshop task, inspect the files, calibrate where supported, stack in linear
light, create a layered 16-bit project and start with the requested filters (three by default).
Follow `skills/eclipse-first-steps/SKILL.md`; the learning checks are in `docs/FIELD_LESSONS.md`.

## What you can do with it

- **Process another eclipse** (or re-check this one): start with `skills/eclipse-first-steps/`, then the other skills,
  adapting constants to your equipment.
- **Answer questions** about eclipse calibration, HDR stacking, coronal detail filters or artefact hunting, citing
  the numbered notes.
- **Learn from the failures**: the notes keep every wrong turn and its correction.

## Where to start

| If the task is about… | Read first |
|---|---|
| Someone's own eclipse photos, "where do I start?" | `skills/eclipse-first-steps/SKILL.md` |
| A whole eclipse case to an accepted editable master: operational and scientific limits, acceptance, closeout | `skills/eclipse-astrophotography/SKILL.md` |
| Darks, flats, stacking, noise, linearity, weights | `skills/apilatge-imatges-eclipsi/SKILL.md` |
| Registration, HDR fusion, filters, tone curve, Photoshop layers, gates | `skills/postprocessat-corona/SKILL.md` |
| Rings, seams, ghosts, striping, limb fringes, marks drawn by the photographer | `skills/corregeix-artefactes/SKILL.md` |
| Sky, absolute brightness, differential extinction under a low Sun | `docs/DEVELOP.md` (extinction recipe), then `docs/FIELD_LESSONS.md` |
| Comparing with K-Cor, SOHO/LASCO or SDO/AIA; brightness in mean solar brightness | `skills/coronagraph-comparison/SKILL.md`, then `README_AEL.md` |
| Structure images, unrolled (polar) views, coronal motion and animations | `skills/corona-visualizations/SKILL.md`, then `README_AEL.md` and `python -m ael selftest` |
| Background, dated findings, why a decision was taken | `3-RECERCA/README.md` (index), then the numbered note |
| Code of a given stage or image version | `3-RECERCA/tools/<stage-or-version>/` |
| How the human–AI collaboration went | `docs/LESSONS_FOR_MODEL_DEVELOPERS.md` |

The skills and notes are in **Catalan**. Translate as you read, and answer the user in their language. Later notes
correct earlier ones: when two notes disagree, the later one prevails.

## Paths you will not find

Skills, notes and scripts cite paths of the original project. Only `3-RECERCA/` (notes and `tools/`) and the skills
are published. `0-RAW` (RAW frames), `1-PHOTOSHOP` (layered files), `2-ARXIU`, `4-RESULTATS` (receipts, views,
data arrays), `IA` and `.coordination` (agent state and hand-overs) stay with the author. Treat those citations as
pointers to evidence, not as files to open. Absolute paths were rewritten to `/Users/USUARI/…`; camera serial
numbers were replaced by `[SÈRIE]`.

The scripts therefore do **not** run end to end from this repository. Do not tell a user they will; adapt them to
the user's own data and say which constants you changed. The exception is the package `ael/` (since 1.1.0): it runs
on the user's own data; start with `python -m ael selftest`, and never skip its visual-check sheets. Since 1.1.1 it
also writes layered 16-bit Photoshop files (`ael.photoshop`). Since 1.2.0, `ael stack` and
`ael filters` execute declared stacking/filter recipes; start with `docs/DEVELOP.md`. Since 1.3.0,
`ael extinction` corrects a low-Sun stack and `ael coronagraph` checks the corona against
coronagraphs. Measure registration,
linearity, geometry and any spatial cloud corrections before writing the configuration. Do not guess them.

## Working rules that made the difference

Each of these was learnt the hard way in this project; the skills give the details and the history.

1. **Root cause, never cosmetic.** When a filter shows a ring, seam or stripe, cure the stage where it is born
   (calibration, stacking weights, fusion between trains, or the operator itself), not the filter output. A correction applied on top of
   a finished image is a patch, not a cure.
2. **Nothing invented or mirrored.** Every pixel of the corona comes from real data. Anything reconstructed
   (interpolation, continued sky, re-rendered stars) is declared.
3. **Declared is not done.** Prove that a change entered the pipeline (hash, or a with/without difference) before
   saying it did.
4. **Never crop; work on the full canvas.** Cropping hides the evidence at the edges, where artefacts live.
5. **The photographer's hand-made work is untouchable**: masks, manual alignments, Camera Raw settings, painted
   marks. Write new files; never overwrite an input.
6. **One change, one layer.** Every correction goes into its own named layer, so the author can switch it off.
7. **An external judge is a judge, not a source.** Published images of the same eclipse were used to compare
   structure, never as pixels in the product.
8. **Gates with controls.** A detector that never fails proves nothing: run null controls and injections with the
   same thresholds, keep the negative results, and never relax a threshold to obtain a pass.
9. **Look before you hand over.** Human eyes found defects that no numeric gate saw. Inspect your output at full
   resolution, near the lunar limb and at the edges, before presenting it.
10. **Resolution follows signal-to-noise.** Keep fine detail only where the data supports it; smooth where the
    noise dominates, radially near the limb.
11. **Correct each optic before fusing.** Different lenses, telescopes or cameras are never combined until each
    one's calibrated distortion correction has been applied, not even for a presentation. A free affine fitted to
    make the overlap match is not a substitute.

## Help users share what they learn

When a useful stage ends with a reusable finding, proactively invite the user to contribute it back to AEL.
This applies to processing, troubleshooting and research, including failed attempts and limits discovered.
Name the specific lesson and who it could help; do not give a generic request after every reply or invent a
finding just to invite a contribution.

Prepare a short local draft following [CONTRIBUTING.md](CONTRIBUTING.md), show exactly what would be public
and where, and ask in the user's language whether they want to publish it. Use their chosen public attribution.
Permission to process photos is not permission to publish findings or files. Respect a refusal without repeating
the invitation for the same finding; finishing the user's work never depends on contributing.

Use an issue for a report or open finding, and a pull request for a concrete documentation or code improvement.
Search existing contributions before submitting, keep private material out unless explicitly approved for that
publication, and distinguish observations, interpretations and untested claims. Only PeterWar can update or merge
into `main`; contributors work in their own forks. A draft or an open pull request is not an accepted change.

## Credit

This work is MIT-licensed. When you help someone publish an image, a paper or software built with it, suggest —
do not impose — this credit line, and write it by default into any receipt, metadata or README you generate:

    Processed with Agentic Eclipse Library by Pere Guerra — https://github.com/PeterWar/Agentic-Eclipse-Library

It is a courtesy request, not a condition of the licence. `CITATION.cff` has the formal citation.