Astro DSO Documentation Generator

Generates up to six deliverables for a deep-sky object (DSO) astrophotography project:

1. Project structure + `rig.json` — the on-disk directory skeleton (raw/, processing/, finals/) and a schema-validated JSON file describing the rig, site, and per-filter acquisition sequences, built primarily by reading FITS headers directly out of raw/light, raw/dark, raw/flat rather than by manual entry.
2. `project.json` — a flat JSON file containing the PixInsight project description data (copy the description field value into the Description box of .xosm). Derived automatically from rig.json when the project was bootstrapped (Step 0b).
3. `doc/index.html` — a rich, self-contained HTML documentation page (path goes into the Documentation field of .xosm), using the Catppuccin flavor palette with a theme switcher.
4. `doc/processing-checklist.html` — an interactive step-by-step PixInsight processing checklist adapted to the target's filter set (LRGB, HOO, SHO, RGB-only, etc.), using the same Catppuccin design system.
5. `astrobin.json` — a structured JSON file containing all AstroBin image post fields, ready to copy-paste into the AstroBin upload form.
6. `Process Icons - <common_name> - <workflow_type> workflow.xpsm` — a PixInsight process icon set tailored to the detected workflow (LRGB, RGB, HOO, SHO), generated from the processing checklist phases.

A project can be a smart telescope (single pre-stacked file per session — see Edge Cases) or, more commonly now, an own rig shooting raw calibrated-later frames (light/dark/flat) — the default assumption throughout this skill.

Workflow

Step 0 — Bootstrap Project (Directory Structure + rig.json)

Run this step first whenever the user asks to bootstrap/initialize/setup a project, or whenever the working directory contains only a raw/ folder and no rig.json yet. It replaces manual data entry (Step 2) whenever real acquisition data is available in FITS headers. It produces the on-disk skeleton and a validated rig.json — the source of truth for every other step in this skill.

#### 0.1 — Verify starting state

Only raw/ is expected to exist when bootstrapping. Confirm with Bash:

ls -la ./
ls -la ./raw/

If raw/light, raw/dark, or raw/flat do not exist, create them (empty subfolders are fine — some campaigns have no separate darks, e.g. bias-only calibration):

mkdir -p ./raw/light ./raw/dark ./raw/flat

If a rig.json already exists in the working directory, ask the user whether to overwrite it or reuse it as-is before proceeding — never overwrite silently.

#### 0.2 — Create the rest of the project structure

mkdir -p ./processing/calibrated ./processing/masters ./finals

Directory roles:

#### 0.3 — Extract metadata from FITS headers

Scan every FITS file under raw/light, raw/dark, raw/flat and aggregate per-filter sequences. Install astropy if missing:

pip install astropy --break-system-packages -q 2>/dev/null

python3 << 'PYEOF'
import glob, json, os
from astropy.io import fits
from collections import defaultdict

def scan_folder(folder):
    """Group FITS headers by filter, aggregating exposure/gain/bin/temp/subs."""
    groups = defaultdict(lambda: {"subs": 0, "exposures": set(), "gains": set(),
                                   "bins": set(), "temps": set(), "dates": set()})
    meta = {}
    for path in sorted(glob.glob(os.path.join(folder, "*.fit*"))):
        try:
            hdr = fits.getheader(path)
        except Exception:
            continue
        filt = hdr.get("FILTER", "NONE") or "NONE"
        g = groups[filt]
        g["subs"] += 1
        exptime = hdr.get("EXPTIME", hdr.get("EXPOSURE"))
        if exptime is not None:
            g["exposures"].add(round(float(exptime), 3))
        if hdr.get("GAIN") is not None:
            g["gains"].add(hdr.get("GAIN"))
        g["bins"].add(hdr.get("XBINNING", 1))
        temp = hdr.get("CCD-TEMP", hdr.get("SET-TEMP"))
        if temp is not None:
            g["temps"].add(round(float(temp), 1))
        date_obs = hdr.get("DATE-OBS")
        if date_obs:
            g["dates"].add(str(date_obs)[:10])
        if not meta:
            meta = {
                "object": hdr.get("OBJECT"),
                "telescope": hdr.get("TELESCOP"),
                "camera": hdr.get("INSTRUME"),
                "focal_length": hdr.get("FOCALLEN"),
                "pixel_size": hdr.get("XPIXSZ"),
                "ra": hdr.get("RA", hdr.get("OBJCTRA")),
                "dec": hdr.get("DEC", hdr.get("OBJCTDEC")),
                "site_lat": hdr.get("SITELAT"),
                "site_long": hdr.get("SITELONG"),
                "bayer": hdr.get("BAYERPAT"),
            }
    return groups, meta

result = {}
global_meta = {}
for kind in ("light", "dark", "flat"):
    groups, meta = scan_folder(f"./raw/{kind}")
    if meta and not global_meta:
        global_meta = meta
    result[kind] = {
        filt: {
            "subs": g["subs"],
            "exposures": sorted(g["exposures"]),
            "gains": sorted(x for x in g["gains"] if x is not None),
            "bins": sorted(g["bins"]),
            "temps": sorted(g["temps"]),
            "dates": sorted(g["dates"]),
        }
        for filt, g in groups.items()
    }

print(json.dumps({"meta": global_meta, "sequences": result}, indent=2, default=str))
PYEOF

Present the extracted summary to the user in a compact table (per kind × filter: subs, exposure(s), gain(s), bin, temp) before writing rig.json.

If multiple distinct exposures, gains, or bins are found within the same filter (e.g. an incomplete or mixed session), list them as separate sequence entries rather than collapsing them — never silently average or discard data.

If astropy cannot be installed or no FITS files are found in raw/light, fall back to Block C of Step 2 (session file list) and proceed manually — do not fail the whole bootstrap.

#### 0.4 — Ask only for what FITS headers cannot provide

FITS headers rarely contain: aperture (mm), focal ratio, exact pixel count, filter bandwidth/model, site name, elevation, Bortle class. Ask in one block, pre-filling anything already extracted so the user only fills gaps:

I've read the raw frames. Here's what I found:
  Target      : {object or "not found — please provide"}
  Telescope   : {telescope or "not found"}
  Camera      : {camera or "not found"}
  Focal length: {focal_length or "not found"} mm
  Filters     : {list of distinct FILTER values found}

A few things aren't in the FITS headers — can you fill these in?
  - Aperture (mm) and f-ratio, if not inferable from focal length + known telescope model
  - Pixel size (µm), if not in header
  - Filter bandwidth (nm) and vendor/model, per filter
  - Site name, elevation (m), and Bortle class
  - GPS coordinates, if SITELAT/SITELONG were not present in the headers

Do not re-ask for anything already successfully extracted from the headers.

#### 0.5 — Generate rig.json

Build the file following the schema in references/rig.schema.json. Field sourcing:

Save with Bash:

cat > ./rig.json << 'EOF'
[generated JSON, single object, pretty-printed 2-space indent]
EOF

Validate against the schema before confirming success:

pip install jsonschema --break-system-packages -q 2>/dev/null
python3 -c "
import json, jsonschema
schema = json.load(open('references/rig.schema.json'))
data = json.load(open('./rig.json'))
jsonschema.validate(instance=data, schema=schema)
print('rig.json OK')
"

If validation fails, fix the offending field and re-validate — never present an invalid `rig.json` to the user as final.

#### 0.6 — Confirm and hand off

Tell the user:

• Project structure → raw/{light,dark,flat}, processing/{calibrated,masters}, finals/ created
• rig.json → path, and a one-line summary (target, filters, total subs, total integration time)

Then proceed automatically to Step 0b (internal field mapping) and Step 3 (DSO research) to generate the object documentation. Do not re-ask acquisition questions already answered by rig.json — Step 2 becomes a no-op for any field it already covers.

Step 0b — Map rig.json to Internal Project Fields

The rest of this skill (Steps 3 through 6) is built around a flat project.json structure. Bridge rig.json into that structure in memory (and still write project.json to disk — other tools may expect it) so every downstream step works unchanged.

Also carry forward for Step 5c (astrobin.json) and Step 5d (XPSM), which can now be populated more precisely than with a smart telescope:

• acquisition_details[].gain — from rig.json sequences.lights[].gain, not null
• acquisition_details[].temperature — from tec_setpoint_c
• acquisition_details[].bortle — from capture_location.bortle
• acquisition_details[].binning — from rig.json binning

Step 1 — Identify the Target

Skip this step if the target was already extracted from FITS headers in Step 0.3 (or confirmed in Step 0.4).

Extract the DSO name/catalog number from the user's message. If ambiguous or missing, ask for it before proceeding.

Common catalog prefixes: NGC, IC, M (Messier), Sh2 (Sharpless), B (Barnard), vdB, LBN, LDN, Ced, RCW.

Step 2 — Collect Acquisition Data (interactive fallback)

Skip any block already fully answered by rig.json (Step 0). This step exists for: projects not bootstrapped via Step 0, smart telescope sessions (no raw FITS to scan), or fields Step 0.4 didn't cover.

Ask the remaining questions one block at a time (don't dump all at once). Wait for answers before proceeding.

Block A — Instrument:

What instrument did you use?
  (e.g. telescope model, focal length, f-ratio, camera, built-in filter)

Block B — Site:

Where did you image from?
  (location name, lat/lon if known, approximate altitude)

Block C — Session files:

Please provide the path to the folder or list of session files.
  (e.g. /path/to/sessions/ or paste filenames directly)

If the user gives a directory path, scan it with Bash:

ls -1 /path/to/sessions/ | grep -iE '\.(tiff?|fits?|xisf|cr2|nef|dng|raf|jpg|jpeg|png)$' | sort

Present the sorted list for confirmation before proceeding.

If the user pastes filenames directly, accept them as-is.

Block D — Optional extras (ask once, accept "skip" gracefully):

Any additional notes? (sky conditions, Bortle class, total integration time, etc.)

Step 3 — Research the DSO

Use web_search to gather comprehensive data. Run at least 3 searches in parallel or sequence:

1. {DSO name} {common name} astronomical data distance magnitude type constellation
2. {DSO name} star forming region physical properties HII nebula galaxy cluster
3. {DSO name} NASA Hubble ESA observations history discovery
4. (if nebula) {DSO name} astrophotography imaging narrowband dual-band filter tips

Collect:

• Coordinates (RA / Dec J2000)
• Distance (ly and parsecs)
• Apparent size (arcmin)
• Visual magnitude
• Physical diameter
• Object type (HII region, reflection nebula, galaxy, globular cluster, etc.)
• Discovery history (who, when, instrument)
• Physical structure and processes
• Notable stars or ionizing sources
• Observation/imaging notes
• Key references (NASA, ESA, SIMBAD, catalogues)
• All catalog designations (NGC, IC, Sh2, LBN, etc.)

Step 4 — Generate project.json

Build a flat JSON object (no nesting, no indentation) representing the PixInsight project description. Save it as ./project.json in the current working directory using Bash:

cat > ./project.json << 'EOF'
{"target":"NGC2174","common_name":"Monkey Head Nebula","constellation":"Orion","ra":"06h 09m 42s","dec":"+20° 30' 00\"","object_type":"H II Region","telescope":"Vaonis Vespera 1 (50mm f/4)","camera":"Sony IMX585 (built-in)","filter":"Dual-band built-in (Ha + OIII)","site":"Dark Sky Site","site_coords":"45.0N / 6.0E · ~900m","session_count":6,"sessions":["2026-03-19_19h04.tiff","2026-03-20_18h48.tiff","2026-03-23_20h43.tiff","2026-04-07_20h40.tiff","2026-04-08_19h19.tiff","2026-04-16_19h37.tiff"],"stacking":"Internal stacking by instrument","calibration":"Handled internally by the instrument","subs_integrated":"6 / 6","ref_alignment":"","ref_integration":"","notes":"","created":"2026-05-05","description":"TARGET       : NGC2174 – Monkey Head Nebula\nConstellation: Orion | RA 06h 09m 42s / Dec +20° 30' 00\"\n\n── EQUIPMENT ────────────────────────────────────────────\nTelescope    : Vaonis Vespera 1 (50mm f/4)\nCamera       : Sony IMX585 (built-in)\nFilter       : Dual-band built-in (Ha + OIII)\nSite         : Dark Sky Site (45.0N / 6.0E · ~900m)\n\n── SESSIONS ─────────────────────────────────────────────\n2026-03-19_19h04.tiff\n2026-03-20_18h48.tiff\n2026-03-23_20h43.tiff\n2026-04-07_20h40.tiff\n2026-04-08_19h19.tiff\n2026-04-16_19h37.tiff\n\nTotal        : 6 sessions | Internal stacking by instrument\nCalibration  : Handled internally by the instrument\n\n── INTEGRATION ──────────────────────────────────────────\nSubs integrated  : 6 / 6\nRef. alignment   :\nRef. integration :\n\n────────────────────────────────────────────────────────\nProject created  : 2026-05-05"}
EOF

JSON field rules:

• No indentation — the entire JSON must be a single line (minified)
• All string values use \n for newlines within the description field
• ref_alignment and ref_integration are always empty strings "" — the user fills them in PixInsight
• calibration: "Darks / Flats / Bias" (or "Darks / Flats") for own-rig projects bootstrapped via Step 0 — the default case; "Handled internally by the instrument" only for smart telescopes (see Edge Cases)
• sessions array: filenames sorted chronologically, no path prefix
• description field: the full plain-text block (same format as before, using \n escapes) ready to paste into PixInsight's Description box
• notes: empty string "" if user skipped Block D; otherwise the user's text

After writing the file, confirm the path to the user.

Step 5 — Generate the HTML Documentation Page

Read the full HTML template from references/documentation-template.html.

Fill in all the template placeholders using:

• Research data (Step 3)
• Acquisition data (Step 2)
• Session file list (Step 2C)

Create the doc/ directory if it does not exist, then save the output:

mkdir -p ./doc

Save the file as ./doc/index.html.

Tell the user the full path of the generated file, and remind them:

• Documentation field of the PixInsight project → path to doc/index.html
• Description field of the PixInsight project → copy the value of the description key from project.json

Step 5b — Generate the Processing Checklist

Read the full checklist template from references/processing-checklist-template.html.

#### 5b.1 — Detect filter set

Before filling the template, determine the workflow mode from the filter field in project.json:

#### 5b.2 — Parse per-channel exposure times

Parse the sessions array from project.json to extract per-channel totals.

Case A — sessions is an array of summary strings (e.g. "Luminance: 3h 00m (36 × 300s)"): Extract directly from the string content.

Case B — sessions is an array of filenames (e.g. CHI-1-CMOS_2023-07-26_NGC253_Blue_300s_ID374118_cal.fits): Count files per filter keyword (Blue, Green, Red, Luminance, Ha, Halpha, OIII, SII) and compute total exposure using the sub duration from the filename or from subs_integrated.

If per-channel data cannot be parsed, use — as the placeholder value.

#### 5b.3 — Fill placeholders

Also replace all occurrences of {{DSO_ID}} inside id="step-*" attributes and the STORAGE_KEY constant with a slug version: spaces replaced by hyphens, lowercased (e.g. ngc-4594).

#### 5b.4 — Adapt sections to workflow mode

Apply the following structural modifications based on the detected workflow mode:

LRGB workflow (default — correct order):

• Phase 02: Luminance linear (BXT + NXT only — no stretch)
• Phase 03: RGB linear (SPFC + CC + SPCC + BXT + NXT — no stretch)
• Phase 04: LRGBCombination on linear masters — combine L + RGB before any stretch
• Phase 05: Stretch the LRGB combined image + SCNR
• Phase 06: StarXterminator on stretched LRGB
• Phase 07: Starless LRGB processing (GHS, LHE, USM, SCC, NXT)
• Phase 08: Rescreen stars
• Phase 09: Finalization (Astro Color Mixer, Curves, ICC, Export)
• Phase 10: Project Cleanup (Delete intermediate calibrated files to reduce storage)

RGB workflow (no Luminance):

• Remove section 04 entirely (Phase 02 — Luminance Processing)
• Remove section 06 entirely (Phase 04 — LRGB Combination)
• Update section numbers sequentially to reflect removed sections (e.g. 03→03, 05→04, etc.)
• Change all tag-lrgb tags to tag-rgb in finalization steps
• Update export filenames from {{DSO_ID}}_LRGB_final.* to {{DSO_ID}}_RGB_final.*
• Remove Luminance legend item

HOO / SHO narrowband workflow:

• Remove section 04 (Luminance linear) — keep section 04 if Luminance is present
• In section 05 (RGB linear): rename to "Narrowband Processing (Linear)"
• Replace ChannelCombination step with: "PixelMath — HOO / SHO palette assembly"
• Remove SPCC step; replace with: "BackgroundNeutralization + ColorCalibration"
• Keep BlurXterminator, NoiseXterminator, stretch steps
• Replace SCNR step with: "Correct magenta stars — CorrectMagentaStars script"
• Replace tag-rgb tags with tag-nb throughout narrowband phases
• Uncomment narrowband legend items (tag-ha, tag-oiii) in the legend section
• Uncomment narrowband data cells (Hα, OIII, SII) in section 01
• Update export filenames to {{DSO_ID}}_HOO_final.* or {{DSO_ID}}_SHO_final.*

HαRGB workflow:

• Keep full LRGB structure
• Add one step after ChannelCombination in section 05: "PixelMath — Integrate Hα into Red channel (HαRGB blend)"
• Uncomment Hα legend item and data cell
• Tag the new step with tag-ha and tag-rgb

Smart telescope / pre-stacked (alternate path — single session file per filter, stacking = "Internal stacking by instrument"; not produced by Step 0 bootstrap, only when the user explicitly describes a smart-telescope session in Step 2):

• Replace the entire Phase 01 (section 03) with a single step:

  Import pre-stacked masters
  Copy the stacked output files into the project folder.
  No WBPP run required — calibration and stacking handled by the instrument.

• Remove Blink Comparator steps

#### 5b.5 — Save the file

cat > ./doc/processing-checklist.html << 'EOF'
[filled and adapted template content]
EOF

Tell the user:

• Processing Checklist → doc/processing-checklist.html

Checklist state (checked steps) persists across browser reloads via localStorage, keyed by DSO slug.

Step 5c — Generate astrobin.json

Build the AstroBin post fields JSON from all previously collected data (Steps 2, 3, 4).

#### 5c.1 — Field mapping rules

#### 5c.2 — Dataset link (telescope.live)

If site or telescope contains "telescope.live" or "Telescope.live":

• Set link to "https://app.telescope.live/archive" as the default dataset URL.
• If the user provided a specific dataset URL in Block D, use it instead.
• Otherwise set link to "".

#### 5c.3 — Equipment objects

imaging_telescopes — one object per telescope:

{
  "name": "Telescope.live Remote Observatory",
  "aperture": null,
  "focal_length": null,
  "type": "REFRACTOR"
}

Parse aperture (mm) and focal length (mm) from the telescope string if present (e.g. "50mm f/4" → aperture: 50, focal_length: 200). Type heuristics: contains "Newton" or "Newtonian" → "NEWTONIAN", "Cassegrain" or "SCT" → "SCT", "Refractor" or "APO" or "ED" or "f/" → "REFRACTOR", "Reflector" → "REFLECTOR", otherwise "OTHER".

imaging_cameras — one object:

{
  "name": "QHY 600M",
  "type": "CCD",
  "modified": false
}

Type: if camera name contains "IMX", "CMOS", "ASI", "QHY", "ZWO", "Atik Horizon" → "CCD" (AstroBin uses CCD for all dedicated astro cameras). modified always false unless user stated "modded" or "full spectrum".

software — always:

[{"name": "PixInsight", "version": ""}]

#### 5c.4 — Filters array

Parse the filter field from project.json. Produce one object per distinct channel:

{
  "name": "Luminance",
  "type": "L",
  "bandwidth": null,
  "vendor": "",
  "model": ""
}

Filter type mapping:

If the filter string includes a bandwidth (e.g. "3nm", "6.5nm", "7 nm"), set bandwidth to the numeric value in nm. Extract vendor/model if present (e.g. "Antlia 3nm Ha" → vendor: "Antlia", model: "3nm Ha").

#### 5c.5 — Acquisition details (DeepSky sessions)

Produce one object per filter channel. Parse per-channel data from the sessions array (same logic as Step 5b.2).

{
  "filter": "Luminance",
  "filter_type": "L",
  "number": 36,
  "duration": 300,
  "binning": 1,
  "gain": null,
  "sensor_cooling": null,
  "darks": null,
  "flats": null,
  "flat_darks": null,
  "bias": null,
  "bortle": null,
  "mean_sqm": null,
  "mean_fwhm": null,
  "temperature": null,
  "date": "YYYY-MM-DD"
}

Field rules:

• number — sub count for this filter channel
• duration — sub duration in seconds (parse from filename or session string, e.g. 300s, 300.00s)
• binning — always 1 unless user specified otherwise
• gain — parse from filename if present (e.g. _GAIN100_), otherwise null
• bortle — parse from Block D notes if user mentioned Bortle class, otherwise null
• date — use the first date found for this filter in the sessions array; format YYYY-MM-DD
• All other fields null unless explicitly provided by the user

#### 5c.6 — Subject type mapping

#### 5c.7 — Save the file

Save as ./astrobin.json (pretty-printed, 2-space indent — unlike project.json this one is for human reading):

cat > ./astrobin.json << 'EOF'
{
  "title": "...",
  ...
}
EOF

Example output (M104, LRGB, Telescope.live):

{
  "title": "Sombrero Galaxy (NGC 4594)",
  "description": "The Sombrero Galaxy (NGC 4594) is a spectacular Sa/Sb spiral galaxy in Virgo, located approximately 28 million light-years away. Its iconic silhouette features a brilliant central bulge bisected by a prominent dust lane. Imaged in LRGB from the Telescope.live Chile remote observatory using a QHY 600M camera over 10 hours of total integration (36×300s Luminance, 27×300s Red, 29×300s Green, 28×300s Blue). Processed in PixInsight.",
  "link": "https://app.telescope.live/archive",
  "image_file": "",
  "imaging_telescopes": [
    {
      "name": "Telescope.live Remote Observatory",
      "aperture": null,
      "focal_length": null,
      "type": "REFRACTOR"
    }
  ],
  "imaging_cameras": [
    {
      "name": "QHY 600M",
      "type": "CCD",
      "modified": false
    }
  ],
  "mounts": [],
  "filters": [
    { "name": "Luminance", "type": "L", "bandwidth": null, "vendor": "", "model": "" },
    { "name": "Red",       "type": "R", "bandwidth": null, "vendor": "", "model": "" },
    { "name": "Green",     "type": "G", "bandwidth": null, "vendor": "", "model": "" },
    { "name": "Blue",      "type": "B", "bandwidth": null, "vendor": "", "model": "" }
  ],
  "software": [
    { "name": "PixInsight", "version": "" }
  ],
  "location": {
    "name": "Chile Remote Observatory",
    "coords": "Chile · Southern Hemisphere"
  },
  "subject_type": "GALAXY",
  "data_source": "AMATEUR_HOSTING",
  "remote_source": "TELELIVE",
  "first_acquisition_date": "2023-02-15",
  "last_acquisition_date": "2025-03-06",
  "acquisition_details": [
    {
      "filter": "Luminance", "filter_type": "L",
      "number": 36, "duration": 300, "binning": 1,
      "gain": null, "sensor_cooling": null,
      "darks": null, "flats": null, "flat_darks": null, "bias": null,
      "bortle": null, "mean_sqm": null, "mean_fwhm": null, "temperature": null,
      "date": "2023-02-15"
    },
    {
      "filter": "Red", "filter_type": "R",
      "number": 27, "duration": 300, "binning": 1,
      "gain": null, "sensor_cooling": null,
      "darks": null, "flats": null, "flat_darks": null, "bias": null,
      "bortle": null, "mean_sqm": null, "mean_fwhm": null, "temperature": null,
      "date": "2023-02-15"
    },
    {
      "filter": "Green", "filter_type": "G",
      "number": 29, "duration": 300, "binning": 1,
      "gain": null, "sensor_cooling": null,
      "darks": null, "flats": null, "flat_darks": null, "bias": null,
      "bortle": null, "mean_sqm": null, "mean_fwhm": null, "temperature": null,
      "date": "2023-02-15"
    },
    {
      "filter": "Blue", "filter_type": "B",
      "number": 28, "duration": 300, "binning": 1,
      "gain": null, "sensor_cooling": null,
      "darks": null, "flats": null, "flat_darks": null, "bias": null,
      "bortle": null, "mean_sqm": null, "mean_fwhm": null, "temperature": null,
      "date": "2023-02-15"
    }
  ]
}

Tell the user:

• AstroBin post fields → astrobin.json
• Fields imaging_telescopes, imaging_cameras, filters, acquisition_details map 1:1 to AstroBin's "Equipment" and "Acquisition" sections.
• image_file must be filled manually when uploading.

Step 5d — Generate Process Icons XPSM

Generate a PixInsight process icon set (.xpsm) tailored to the detected workflow mode (Step 5b.1) and the specific target.

#### 5d.1 — Filename

Process Icons - <common_name> - <workflow_type> workflow.xpsm

• <common_name> → common_name from project.json, spaces preserved (e.g. Sombrero Galaxy)
• <workflow_type> → detected workflow mode, title-cased: LRGB, RGB, HOO, SHO, HaRGB

Example: Process Icons - Sombrero Galaxy - LRGB workflow.xpsm

Save to the current working directory (not inside doc/).

#### 5d.2 — XPSM file structure

All XPSM files share this skeleton:

<?xml version="1.0" encoding="UTF-8"?>
<!--
  PixInsight XML Process Serialization Module - XPSM 1.0
  Generated: <GENERATED_DATE>
  Target: <DSO_ID> — <COMMON_NAME>
  Workflow: <WORKFLOW_TYPE>
-->
<xpsm version="1.0"
  xmlns="http://www.pixinsight.com/xpsm"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.pixinsight.com/xpsm http://pixinsight.com/xpsm/xpsm-1.0.xsd">

  [instance blocks]

  [icon blocks]

</xpsm>

Rules:

• Every <instance> block must have a unique id ending in _instance
• Every <icon> block references its instance via instance="<id>"
• xpos always 2000, ypos increments of 40 per icon from top
• workspace always "Workspace01"
• The <description> element on each instance must state the phase number, step number, and a one-line usage note

#### 5d.3 — LRGB workflow icon set

Generate the following instances and icons in this exact order:

PHASE 02 — Luminance Linear (no stretch)

PHASE 03 — RGB Linear (no stretch)

PHASE 04 — LRGB Combination (linear)

PHASE 05 — Stretch LRGB

PHASE 06 — Star Separation

PHASE 07 — Starless LRGB Processing

PHASE 08 — Recombination

PHASE 09 — Finalization

PHASE 10 — Project Cleanup

#### 5d.4 — RGB workflow icon set

Same as LRGB but:

• Remove NXT_Lum, BXT_CorrectOnly_Lum, BXT_Full_Lum, STF_AutoStretch (Lum phase entirely absent)
• Remove LRGBCombination
• Add Stretch_RGB (same GHS parameters as Stretch_LRGB) immediately after NXT_RGB
• Renumber phases: Phase 02 → RGB linear, Phase 03 → Stretch RGB, Phase 04 → Star separation, etc.

#### 5d.5 — HOO / SHO narrowband workflow icon set

Same base as RGB but:

• Replace ChannelCombination with PixelMath_HOO or PixelMath_SHO:

HOO PixelMath expression (3-channel: R=Ha, G=blend, B=OIII):

R: $T[0]*BrightnessControl
G: k= adev($T[0])/adev($T[1]); g1= ((k*OIIIBoost)*($T[1]-med($T[1]))+med($T[0])); iif(OIII_SCurve==0,g1,3*g1^2-2*g1^3)*BrightnessControl
B: k= adev($T[0])/adev($T[1]); b1= ((k*OIIIBoost)*($T[1]-med($T[1]))+med($T[0])); iif(OIII_SCurve==0,b1,3*b1^2-2*b1^3)*BrightnessControl
Symbols: OIIIBoost=1.0; HaBlend=0.6; BrightnessControl=1.0; OIII_SCurve=0; k,g1,b1

• Remove SPCC → replace with a SCNR at green (for magenta star correction after narrowband palette)
• Add CorrectMagentaStars note in description (Script-based, no XPSM instance available)

#### 5d.6 — ypos layout

Icons are placed top-to-bottom in a single column at xpos=2000, starting at ypos=40, incrementing by 40 per icon. A gap of 80 (one empty slot) separates each phase boundary.

#### 5d.7 — Save the file

cat > "Process Icons - <common_name> - <workflow_type> workflow.xpsm" << 'EOF'
[generated XPSM content]
EOF

Tell the user:

• Process Icons → Process Icons - <common_name> - <workflow_type> workflow.xpsm
• Import in PixInsight via File → Import Process Icons
• Icon descriptions include phase, step number, and usage reminders
• Image IDs in PixelMath_Rescreen (starless, stars) must match actual open window names in PixInsight

Step 6 — Copy Description to Clipboard

Run the following command to place the PixInsight description text directly into the clipboard:

cat project.json | jq -r '.description' | pbcopy

If the command succeeds (exit code 0), tell the user:

✓ Description copied to clipboard — paste it directly into the PixInsight project Description field.

If it fails (e.g. jq or pbcopy not found), show the fallback message:

⚠ Clipboard copy unavailable. Open project.json and copy the value of the description key manually.

Template Placeholders Reference

See references/rig.schema.json for the full JSON Schema used to validate rig.json (Step 0.5). See references/documentation-template.html for the full annotated documentation template. See references/processing-checklist-template.html for the full annotated checklist template.

Documentation template (references/documentation-template.html)

Key placeholders:

• {{DSO_ID}} — e.g. NGC2174
• {{COMMON_NAME}} — e.g. Monkey Head Nebula
• {{RA}}, {{DEC}} — J2000 coordinates
• {{DISTANCE_LY}}, {{DISTANCE_PC}} — with uncertainty range if known
• {{APPARENT_SIZE}} — e.g. 40′ × 30′
• {{MAGNITUDE}} — visual magnitude
• {{PHYSICAL_DIAMETER}} — e.g. ~75 ly
• {{OBJECT_TYPE}} — e.g. H II Region
• {{CONSTELLATION}} — full name
• {{CATALOG_ROWS}} — <tr> rows for the catalog table
• {{SCIENTIFIC_DESCRIPTION}} — 3–5 <p> paragraphs
• {{KEY_STAR_BLOCK}} — filled if a dominant ionizing/notable star exists, else empty
• {{TIMELINE_ITEMS}} — <div class="timeline-item"> blocks for history
• {{PHYSICAL_STRUCTURE}} — 3–4 <p> paragraphs
• {{OBSERVATION_TIPS}} — <div class="tip-card"> blocks
• {{INSTRUMENT}}, {{FILTER}}, {{SITE}}, {{SITE_COORDS}} — acquisition fields
• {{SESSION_COUNT}} — integer
• {{SESSION_FILES}} — <span class="session-file">filename</span> per file
• {{REFERENCES_ROWS}} — <tr> rows for references table
• {{GENERATED_DATE}} — today's date YYYY-MM-DD
• {{AUTHOR_NOTES}} — optional free-text notes block (omit section if empty)

Checklist template (references/processing-checklist-template.html)

Key placeholders:

• {{DSO_ID}} — e.g. NGC 4594 (display) and ngc-4594 (slug for IDs and localStorage)
• {{COMMON_NAME}} — e.g. Sombrero Galaxy
• {{CONSTELLATION}} — full name
• {{OBJECT_TYPE}} — uppercased, e.g. SPIRAL GALAXY
• {{CAMERA}} — e.g. QHY 600M
• {{INSTRUMENT}} — e.g. Telescope.live Remote Observatory
• {{FILTER}} — e.g. LRGB
• {{SITE}} — e.g. Chile Remote Observatory
• {{TOTAL_EXPOSURE}} — e.g. 10h 00m
• {{TOTAL_SUBS}} — integer only, e.g. 120
• {{LUM_TIME}} — e.g. 3h 00m (36 × 300s)
• {{RED_TIME}}, {{GREEN_TIME}}, {{BLUE_TIME}} — per-channel exposure
• {{HA_TIME}}, {{OIII_TIME}}, {{SII_TIME}} — narrowband channels (omit if absent)
• {{GENERATED_DATE}} — YYYY-MM-DD
• {{AUTHOR}} — observer name / location
• {{DSO_NOTES}} — free-text processing notes (omit section 13 if empty)

AstroBin JSON (astrobin.json)

Key fields and their sources:

Quality Standards

`rig.json` (Step 0):

• Only raw/ (and its light/dark/flat subfolders) is assumed to exist before bootstrapping — every other directory is created by Step 0.2, never assumed present
• Always validated against references/rig.schema.json before being presented as final — a failed validation is fixed and re-checked, never shipped
• Pretty-printed with 2-space indent (human-readable, hand-editable)
• Values actually read from FITS headers are never overwritten by guesses — if a header field is missing, the corresponding rig.json field is left for the user to fill (Step 0.4), never fabricated
• Distinct exposures/gains/bins within the same filter are kept as separate sequences entries — never merged or averaged
• sequences.lights[], .darks[], .flats[] subs counts always match the actual file count found on disk at bootstrap time
• No CAA/rotator field unless the user's rig actually has one — omit entirely rather than null it out

`project.json`:

• Single-line minified JSON — no indentation, no pretty-printing
• description field contains the full plain-text PixInsight Description block with \n escapes
• ref_alignment and ref_integration always empty strings ""
• sessions array sorted chronologically
• All fields always present; use "" or 0 for missing optional values, never null

`doc/index.html`:

• doc/ directory created automatically if absent
• All 4 Catppuccin flavors wired up: Latte, Frappé, Macchiato (default), Mocha
• Theme preference persists via localStorage
• Fully self-contained — single HTML file, no external dependencies except Google Fonts
• Sections with no data omitted gracefully
• Session files in chronological order
• All scientific content from actual web searches — never fabricate measurements
• Uncertainty ranges cited when distance estimates vary between sources

`doc/processing-checklist.html`:

• doc/ directory created automatically if absent (same run as index.html)
• All 4 Catppuccin flavors wired up with the same theme switcher and localStorage key
• Checklist state (checked / unchecked steps) persists via localStorage keyed by DSO slug
• Workflow mode (LRGB / RGB / HOO / SHO / HαRGB) correctly detected and applied
• Unused filter channels removed from data grid and legend
• Section numbers resequenced after any section removal
• Export filenames match the detected workflow mode
• All {{DSO_ID}} occurrences in HTML attributes replaced with the slug version
• STORAGE_KEY constant in the <script> block updated to checklist-{dso-slug}

`astrobin.json`:

• Pretty-printed with 2-space indent (human-readable)
• title follows the format "Common Name (DSO_ID)"
• description is plain text, 3–5 sentences, no HTML or markdown
• link set to "https://app.telescope.live/archive" for telescope.live data; "" otherwise
• filters array contains one object per distinct channel — never merge channels
• acquisition_details contains one object per channel with correct number and duration
• data_source and remote_source correctly reflect the imaging site
• subject_type derived from object_type using the mapping table in 5c.6
• software always [{"name": "PixInsight", "version": ""}]
• mounts always [] unless user provided mount information explicitly
• All numeric fields use numbers, not strings (300 not "300")
• All unknown/unparseable fields use null, never empty string ""
• first_acquisition_date and last_acquisition_date in YYYY-MM-DD format

`Process Icons - <name> - <workflow> workflow.xpsm`:

• Filename exactly follows the pattern Process Icons - <common_name> - <workflow_type> workflow.xpsm
• Workflow type derived from filter set detection (Step 5b.1): LRGB, RGB, HOO, SHO, HaRGB
• All <instance> IDs end in _instance; all <icon> IDs are clean names without suffix
• histogramBins on LocalHistogramEqualization always uses enum value Bit12 — never an integer
• LRGBCombination only includes known valid parameters: clipHighlights, noiseReduction, layersRemoved, layersProtected, channels table, mL, mc
• ICCProfileTransformation only includes: targetProfile, toDefaultProfile, renderingIntent, useBlackPointCompensation
• Icon layout: single column at xpos=2000, ypos starts at 40, increments 40 per icon, 80 gap between phases
• PixelMath_Rescreen expression always ~((~starless)*(~stars)) — description reminds user to match image IDs
• Narrowband PixelMath expressions use XML-escaped < as <
• XPSM workflow type matches the checklist workflow detected in Step 5b.1 — never hardcoded

Edge Cases