roman-gladius 0.1.0a2__tar.gz

roman_gladius-0.1.0a2/.env.example

@@ -0,0 +1,5 @@
+# Copy this file to .env and paste your MAST token after the equals sign.
+# GUI: put .env in the --workspace directory, then restart the server.
+# CLI: put .env beside the YAML passed to gladius run.
+# Existing environment values take precedence. Do not commit your .env.
+MAST_API_TOKEN=

roman_gladius-0.1.0a2/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff
+        name: Ruff
+        entry: python -m ruff check
+        language: system
+        types: [python]
+        files: ^(src|tests|docs/conf.py)
+      - id: ruff-format
+        name: Ruff format
+        entry: python -m ruff format --check
+        language: system
+        types: [python]
+        files: ^(src|tests|docs/conf.py)

roman_gladius-0.1.0a2/.ruff.toml

@@ -0,0 +1,5 @@
+line-length = 100
+target-version = "py311"
+include = ["src/**/*.py", "tests/**/*.py", "docs/conf.py", "tools/**/*.py"]
+[lint]
+select = ["E4", "E7", "E9", "F", "I", "B", "UP"]

roman_gladius-0.1.0a2/AI_POLICY.md

@@ -0,0 +1,12 @@
+# AI-assisted development
+
+The initial package was developed with OpenAI Codex assistance at the maintainer's
+request. This includes source, tests and documentation. Human maintainers remain
+responsible for scientific correctness, licensing, explanations and releases.
+Synthetic automated tests are evidence of behavior, not a replacement for review
+of scientific assumptions or validation on representative Roman data.
+
+Contributors should disclose substantial AI assistance in proposed changes and
+be able to explain and maintain all submitted material. A human other than the
+contributor should review changes before a public release. Do not submit private
+data or third-party code to tools without appropriate authorization.

roman_gladius-0.1.0a2/CHANGES.rst

@@ -0,0 +1,58 @@
+0.1.0a2 (unreleased)
+===================
+
+* Add ``gladius token`` with hidden input and private dotenv persistence, explicit
+  ``--env-file`` selection, and a real-data ``gladius demo mast-demo`` command
+  with an advertised parent-size preflight and reusable YAML.
+* Add Read the Docs build configuration, branded light/dark documentation and a
+  getting-started guide. Add a separate real-MAST Nexus notebook requiring an
+  explicit credential-file path; notebook outputs are excluded from distributions.
+* Exclude internal handoff material from distributions, enforce archive content
+  checks in CI, and fix minimal-dependency
+  and Windows validation failures.
+* Load local .env credentials at CLI/GUI startup without overriding shell values,
+  and document local MAST authentication in the GUI and configuration guide.
+* Add a real-MAST GUI test preset, Galactic/ecliptic input conversion, zero/unlimited
+  stack limits, context-sensitive help, and icon-only theme controls.
+* Rename the project to Gladius, distribution roman-gladius, import gladius
+  and CLI gladius.
+* Add an opt-in authenticated live MAST download workflow with a 20 MiB cap,
+  generated-query checks, cleanup checks and explicit image/associated-product coverage.
+* Add a bundled loopback web GUI with target CSV upload, configuration builder,
+  YAML import/export, run button and live progress.
+* Generate target-based Roman MAST searches with calibrated Level 2 defaults,
+  configurable cone radius, query-level selections and deduplicated observations.
+  Require Astroquery 0.4.11 for Roman support and report archive authorization errors.
+* Document direct Python configuration/run calls and export Target/CSV helpers.
+* Add --targets CSV overrides for run and validate; preserve catalogue columns
+  as target metadata and embed imported targets in resolved configurations.
+
+0.1.0a1 (unreleased)
+===================
+
+* Generate an independent package scaffold from the pinned STScI template.
+* Add validated YAML, native SCI/ERR/DQ extraction, parent metadata retention,
+  exact astrometry translation, derived ASDF/FITS formats and checksum-based resume.
+* Add local and optional Roman MAST inputs, supplied corrected GWCS support,
+  provisional autocorrelation screening and bounded display median stacks.
+* Add offline examples, scientific regression tests, documentation and CI.
+
+* Fix missing display-stack edge pixels caused by numerical WCS roundtrip errors.
+  Real off-image coordinates remain excluded. Increase the synthetic demo's
+  Gaussian background noise so its effect on the two-exposure median is visible.
+
+* Add optional, timestamped GIF previews of sky-aligned exposures, with a shared
+  brightness stretch and configurable playback duration, independently of median
+  stacks. Add GUI controls, YAML settings and a synthetic documentation example.
+
+* Add optional RGB colour composites with configurable channel filters, one
+  common sky grid, per-filter medians and independent Astropy z-scale display
+  limits, following the ICE dashboard's normalization approach. Record inputs,
+  display settings and missing-filter skips in the stack manifest.
+
+* Support the GUI behind Jupyter Server Proxy with relative asset/API paths,
+  configured public origins, automatic JupyterHub URL detection, and --nexus /
+  --public-url launch options. Print named-server-aware browser links at startup.
+
+* Use ``gladius`` as the Python import and CLI name, and ``roman-gladius`` as
+  the PyPI distribution name (normalized to ``roman_gladius`` in wheel filenames).

roman_gladius-0.1.0a2/CITATION.cff

@@ -0,0 +1,8 @@
+cff-version: 1.2.0
+message: "Please cite the package name and version; an archival DOI has not yet been assigned."
+title: "Gladius"
+type: software
+version: 0.1.0a2
+authors:
+  - name: "Gladius contributors"
+license: BSD-3-Clause

roman_gladius-0.1.0a2/CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+# Code of conduct
+
+We welcome contributors of every background and experience level. Be respectful,
+assume good intent, give evidence-based technical feedback, and credit others'
+work. Harassment, threats, discrimination and disclosure of private information
+are unacceptable in project discussions, reviews or events.
+
+Maintainers may moderate or remove inappropriate contributions and restrict
+participation after considering the context and impact. Report concerns privately
+to a maintainer through the project's hosting platform; do not post sensitive
+reports publicly. A dedicated private reporting contact must be established when
+the project opens to external contributors.
+
+Adapted from the STScI package template's community guidance; see NOTICE.md and
+the retained template license. This is an independent project policy.

roman_gladius-0.1.0a2/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Create a virtual environment and install `python -m pip install -e '.[dev,roman,mast]'`.
+Run pytest, Ruff and the Sphinx documentation build before proposing changes.
+TESTING.md describes the supported verification steps and their limits.
+
+Keep extraction independent of services and UI. Add scientific regression tests
+for changes to centering, flags, timing, GWCS, metadata and serialization. Document
+new configuration keys and regenerate docs/config.schema.json. Changes to product
+semantics require a schema/version decision and migration notes in CHANGES.rst.
+Do not edit historical snapshots as if they were the active implementation.
+
+Report bugs with package/dependency versions, a small redistributable example and
+the resolved configuration. Remove credentials and private data before sharing.
+Do not add external solver code without an explicit compatible license and
+attribution. Contributions must follow CODE_OF_CONDUCT.md and AI_POLICY.md.
+
+There is no hosted repository configured yet. When one is established, use its
+issue tracker and pull requests; this file deliberately does not invent a URL.

roman_gladius-0.1.0a2/LICENSE.txt

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026 Gladius contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above
+       copyright notice, this list of conditions and the following
+       disclaimer in the documentation and/or other materials provided
+       with the distribution.
+
+    3. The names of the copyright holders and contributors may not be used to
+       endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.

roman_gladius-0.1.0a2/MANIFEST.in

@@ -0,0 +1,19 @@
+include README.md LICENSE.txt NOTICE.md THIRD_PARTY.md TEMPLATE.json CITATION.cff CHANGES.rst
+include .env.example
+recursive-include tools *.py
+include CONTRIBUTING.md CODE_OF_CONDUCT.md AI_POLICY.md TESTING.md tox.ini .ruff.toml .pre-commit-config.yaml
+recursive-include licenses *.txt
+recursive-include src *.py *.typed *.yaml *.html *.css *.js *.png *.txt *.ttf
+recursive-include tests *.py
+recursive-include docs *.md *.rst *.py *.json *.css *.png *.jpg *.gif *.js *.ttf *.txt
+recursive-include notebooks *.md *.ipynb
+recursive-include examples *.yaml *.csv
+prune local-snapshot
+prune nexus-snapshot
+prune .agents
+prune .gladius-gui
+prune .github
+prune docs/_build
+exclude nexus-source-snapshot.zip
+exclude docs/commissioning-handoff.md
+global-exclude __pycache__ *.py[cod] .DS_Store

roman_gladius-0.1.0a2/NOTICE.md

@@ -0,0 +1,33 @@
+# Attribution and license scope
+
+The new installable package under src/gladius, its tests and project
+documentation are licensed under BSD-3-Clause (LICENSE.txt). The distribution is
+independent: no Astropy affiliation, STScI ownership or institutional endorsement
+is claimed. The contributor copyright label does not override any underlying
+rights held by contributors or their employers.
+
+The scaffold was generated with Cookiecutter from the STScI package template.
+TEMPLATE.json records its exact commit and options. The original boilerplate
+license is retained in licenses/STSCI_TEMPLATE_LICENSE.txt. Institutional
+branding and project-specific administrative workflows were adapted or removed.
+
+The native geometry convention was adapted from the commissioning extraction
+helper supplied with this project. The new autocorrelation implementation is
+independent and does not import roman_ice_sim or assert identical metrics.
+
+local-snapshot/, nexus-snapshot/, nexus-source-snapshot.zip and .agents/ are
+historical/reference or working material and are excluded from built packages.
+This package license does not relicense those collections. In particular,
+nexus-snapshot/external_reference/gaia_wcs_correction.py is not distributed or
+imported by the package; its separate ownership/licensing remains unresolved.
+No external Gaia solving code was incorporated.
+
+The Gladius logo drafts in assets/brand were generated from the user-supplied
+concept. The bundled RGES-PIT logo was supplied through the team's local website
+source. Project branding retains its respective ownership; the package's BSD
+license is not a grant of rights to RGES-PIT names or logos.
+
+Direct runtime dependency acknowledgements are recorded in THIRD_PARTY.md and
+the GUI Dependencies & acknowledgements page. Reviewed dependency license texts
+identify their corresponding versions; they do not replace notices provided by
+the dependencies installed or redistributed with a particular environment.

roman_gladius-0.1.0a2/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: roman-gladius
+Version: 0.1.0a2
+Summary: Native Roman detector cutouts with parent metadata and explicit astrometry provenance
+Author: Gladius contributors
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/AmberLee2427/gladius
+Project-URL: Repository, https://github.com/AmberLee2427/gladius
+Project-URL: Issues, https://github.com/AmberLee2427/gladius/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+License-File: NOTICE.md
+License-File: licenses/STSCI_TEMPLATE_LICENSE.txt
+Requires-Dist: numpy>=1.24
+Requires-Dist: astropy>=6
+Requires-Dist: asdf>=4.1
+Requires-Dist: asdf-astropy>=0.6
+Requires-Dist: gwcs>=0.21
+Requires-Dist: scipy>=1.10
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: PyYAML>=6
+Requires-Dist: filelock>=3.12
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: Pillow>=10
+Provides-Extra: roman
+Requires-Dist: roman_datamodels>=0.25; extra == "roman"
+Provides-Extra: mast
+Requires-Dist: astroquery>=0.4.11; extra == "mast"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: myst-parser>=2; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=3; extra == "docs"
+Provides-Extra: notebook
+Requires-Dist: ipykernel>=6; extra == "notebook"
+Requires-Dist: matplotlib>=3.8; extra == "notebook"
+Provides-Extra: dev
+Requires-Dist: roman-gladius[docs,test]; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: tox>=4; extra == "dev"
+Dynamic: license-file
+
+# Gladius
+
+Native image cutouts for the Roman Space Telescope.
+
+Python import and command: `gladius`. Distribution name: `roman-gladius`
+(`roman_gladius` is the equivalent PyPI spelling).
+
+Native detector cutouts from calibrated Roman images, with explicit parent-pixel
+mapping, separately retained parent metadata, exact stored astrometry, and optional
+display stacks. An independent alpha package built from the STScI Cookiecutter
+scaffold; it is not affiliated with or endorsed by STScI or Astropy.
+
+## Install and run
+
+Python 3.11 or newer and Git are required. Gladius is not yet on PyPI; install
+from the public repository:
+
+```sh
+git clone https://github.com/AmberLee2427/gladius.git gladius
+cd gladius
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[roman,mast]'
+gladius gui --workspace .
+```
+
+On Windows, activate with `.venv\Scripts\activate` instead. Open the printed
+GUI URL to add targets, choose images and processing, and download a YAML file or
+make cutouts. For the manual YAML workflow:
+
+```sh
+gladius init-config config.yaml
+# Edit targets and inputs in config.yaml.
+gladius validate config.yaml
+gladius run config.yaml
+```
+
+For archive access, set `inputs.mode: mast`. Searches use your targets by default;
+`mast_criteria` adds optional archive constraints. Restricted data use
+`MAST_API_TOKEN` from the environment.
+Directory mode does not perform archive queries or downloads.
+
+Try a complete offline example with no credentials or mission data:
+
+```sh
+gladius demo /tmp/my-gladius-demo
+```
+
+This creates two synthetic ASDF exposures, a YAML file, native ASDF/FITS cutouts,
+a display stack, an exposure GIF, a resolved configuration and a run manifest. Choose a new demo
+folder; existing demo inputs are not overwritten.
+
+Or, with the `roman` and `mast` extras installed, try a real archive image.
+First sign in at the [MAST token page](https://auth.mast.stsci.edu/tokens), create
+an API token, and copy it for the hidden prompt below. The token identifies your
+account; restricted observations still require permission for that account:
+
+```sh
+gladius token             # Hidden prompt; saves MAST_API_TOKEN in .env here.
+gladius demo mast-demo    # Queries MAST, downloads one parent, and makes cutouts.
+```
+
+The MAST demo writes `mast-demo/demo.yaml` and ASDF/FITS cutouts under
+`mast-demo/output/`. It rejects parents advertised above 512 MiB before download;
+use `--max-parent-mib` to change that limit. It uses an explicit 0.01-pixel WCS
+round-trip tolerance and makes no display stack. See the
+[real-data quickstart](docs/quickstart.md#try-one-real-image-from-mast).
+
+## Configuration
+
+[examples/config.yaml](examples/config.yaml) documents every option. Paths are
+relative to the configuration file. Unknown keys, duplicate YAML keys, invalid
+coordinates and inconsistent settings are rejected before input discovery.
+`gladius config-schema schema.json` writes JSON Schema for editor support.
+
+- Select exposure-start dates in a UTC `[start, end)` interval, detectors 1–18,
+  and filters. Empty detector/filter lists mean all; missing metadata needed for
+  a requested selection causes an explicit error.
+- Choose square cutout size, padding/strict edges and fully off-detector policy.
+- Use supplied WCS, validate its numerical consistency, or require a separately
+  supplied corrected GWCS. Validation does **not** establish absolute sky accuracy.
+- Enable an autocorrelation elongation screen and decide whether failures enter
+  display stacks. Native cutouts remain available regardless of quality flags.
+- Retain full parent images or keep only their derived products. Local input
+  files are never deleted. Archive parents are staged one at a time.
+- Create median display stacks, exposure GIFs and configurable false-colour composites.
+- Choose ASDF, FITS or both; configure bounded display stacks, resume and failure
+  handling. Resolved defaults and dependency versions are recorded for each run.
+
+See [configuration](docs/configuration.md), [outputs](docs/products.md),
+[scientific conventions](docs/science.md), and [Python API](docs/api.rst).
+
+## Scientific contract
+
+SCI and ERR are unresampled floating-point pixels with NaN padding. DQ flags stay
+integer; missing pixels are DO_NOT_USE (1), and existing saturation flags survive.
+Centering follows the commissioning convention `floor(position) - (size - 1)//2`,
+including odd sizes. Coordinates are zero-based `(x, y)` on the calibrated SCI
+array, with `array[y, x]` indexing. Origins can be negative.
+
+The cutout WCS is a translation of the chosen parent WCS. The original WCS and
+metadata are retained under `parent_wcs` and `parent_metadata`; derived footprints
+are in `cutout_metadata`. Spatial arrays are cropped using the shared mapping,
+with descriptors recording their original paths, shapes and types. Non-spatial
+metadata arrays and custom fields are retained, including FITS header ordering,
+comments and duplicate HISTORY cards.
+
+ASDF stores the exact GWCS. FITS provides SCI/ERR/DQ extensions, a measured TAN-SIP
+approximation where necessary, auxiliary arrays and a package-specific ASDFMETA
+extension retaining full metadata and exact WCS. These are **derived products**,
+not schema-valid Roman mission datamodels. Read them with `read_cutout`.
+
+## Current boundaries
+
+The first version handles 2D calibrated detector images, not raw ramps, mosaics,
+spectral products or moving-target ephemerides. A supplied correction can be
+applied, but the separately authored Gaia solver is not bundled. The new
+independent autocorrelation method is provisional; its threshold must be
+calibrated, and the old commissioning threshold is not assumed equivalent.
+Stacks are resampled display products, not photometrically or PSF-matched science
+coadds. They do not propagate uncertainties. Execution is sequential and portable.
+
+MAST staging is covered by mocked service tests; real archive access depends on
+service availability, permissions and input metadata. See TESTING.md for actual
+validation scope. No automatic upload, publication or external solver invocation
+occurs.
+
+## Development and provenance
+
+```sh
+python -m pip install -e '.[dev,roman,mast]'
+python -m pytest
+python -m ruff check src tests docs/conf.py
+python -m sphinx -W -b html docs docs/_build/html
+python -m build
+```
+
+Historical source snapshots are local reference material and are excluded from
+distributions. [TEMPLATE.json](TEMPLATE.json) records the
+Cookiecutter template and exact commit; [NOTICE.md](NOTICE.md) explains license
+scope and attribution. The copied external Gaia solver has not been incorporated
+into the package.
+
+New package code is BSD-3-Clause. Template attribution is retained separately.
+See [contributing](CONTRIBUTING.md), [conduct](CODE_OF_CONDUCT.md),
+[AI disclosure](AI_POLICY.md), and [citation](CITATION.cff). The project has not yet
+been published to PyPI or assigned a DOI.
+
+## Local web GUI and target CSVs
+
+The separate [Nexus notebook](notebooks/README.md) queries real MAST data and
+requires an explicit path to your credential file. It is not part of the docs
+site. Install its plotting/kernel dependencies with `pip install -e '.[roman,mast,notebook]'`.
+
+For restricted MAST access, run `gladius token` in your workspace to save the
+token through a hidden prompt. Alternatively copy `.env.example` to `.env`
+and set `MAST_API_TOKEN=your_token_here`. The GUI loads that file when the server
+starts; restart the server after editing it. Existing shell variables take
+precedence. For `gladius run config.yaml`, place `.env` beside the YAML instead.
+Use `--env-file /path/to/credentials.env` with `token`, `run`, `gui`, or the MAST
+demo to select a different credential file.
+Keep `.env` private and out of Git; the repository already ignores it. GitHub
+Actions secrets do not populate this local file. See the
+[authentication instructions](docs/configuration.md#local-mast-authentication).
+
+```sh
+gladius gui --workspace . --port 8768
+```
+
+Open the printed local URL. The GUI builds the same validated configuration used
+by the CLI, imports target CSVs, downloads self-contained YAML, and runs the
+pipeline with live progress. It includes a YAML editor/importer for existing
+configurations. Relative paths resolve from the directory shown in the builder;
+downloaded YAML contains absolute paths. The server binds only to loopback.
+Keep its terminal open during runs; closing a browser tab does not cancel a run.
+
+```sh
+gladius validate config.yaml --targets targets.csv
+gladius run config.yaml --targets targets.csv
+```
+
+`--targets` replaces YAML targets before validation, so the YAML may omit targets
+when that option is supplied. The CSV path is relative to the CLI working
+directory; other paths retain their YAML-relative meaning.
+
+```csv
+id,ra,dec,catalogue
+OGLE-2019-BLG-0011,270.123,-29.456,OGLE
+```
+
+Use decimal ICRS degrees (`ra,dec`) or zero-based pixels (`x,y`), never both.
+`ra_deg/dec_deg` and `name/target_id` aliases are supported. IDs can be omitted to
+generate stable row-order IDs such as `target-000001`. Extra columns are retained
+as strings under each target's `metadata`, including in cutout provenance.
+Invalid rows and duplicate IDs fail explicitly. The GUI preview shows the first
+50 targets; all rows are included in the configuration and run.
+
+Each GUI submission saves its resolved YAML and progress record in
+`.gladius-gui/` under the workspace; scientific outputs still go to the
+configured output directory. Only one GUI-owned run is active at a time. Reloading
+the page reconnects to the last run while the server remains open. After a server
+restart, run history remains on disk rather than being automatically restarted.
+
+On Nexus, start the GUI in a JupyterLab terminal with
+`gladius gui --workspace /path/on/nexus/to/work --nexus` and open the printed
+proxy link. Gladius detects a supplied JupyterHub public URL automatically;
+`--public-url` provides an explicit override. See the
+[Nexus and SSH instructions](docs/configuration.md#roman-research-nexus-and-jupyterhub).
+
+## Python API
+
+The CLI and GUI use the same importable functions:
+
+```python
+from pathlib import Path
+
+from gladius import RunConfig, load_config, load_environment, read_targets_csv, run
+
+# Folder containing this example's YAML, targets, and optional .env file.
+workspace = Path.cwd()
+
+# Python callers explicitly load credentials for restricted MAST access.
+# Reads workspace/.env if present; existing environment variables take precedence.
+load_environment(workspace)
+
+# Existing YAML, with an optional CSV override: returns a validated RunConfig.
+config = load_config(workspace / "config.yaml", targets_path=workspace / "targets.csv")
+manifest_path = run(config, progress=print)
+
+# Or construct the configuration directly:
+config = RunConfig(
+    targets=read_targets_csv(workspace / "targets.csv"),
+    inputs={"mode": "mast"},
+    extraction={"size": 150, "no_overlap": "skip"},
+).resolved(workspace)
+# manifest_path = run(config)
+```
+
+MAST sky searches are generated from target RA/Dec, with Level 2 calibrated
+images and a configurable 6 arcminute candidate radius by default. Additional
+criteria are optional for sky targets; pixel-only targets need an archive
+constraint such as a program ID. See the configuration guide for authentication,
+query limits and overlap conventions. `make_cutout()` also accepts in-memory
+SCI/ERR/DQ arrays, a WCS and a `Target`; see the Python API documentation.
+
+## Live archive tests in GitHub Actions
+
+Add `MAST_API_TOKEN` under **Settings → Secrets and variables → Actions**.
+The **Live Roman MAST download** workflow runs on default-branch code changes,
+or manually from Actions. It downloads one product capped at 20 MiB and reports
+whether it tested a calibrated image/cutout or a small associated product.
+The manual calibrated-image option requires full extraction coverage within the
+same cap. Downloaded science data are not uploaded as artifacts. Normal tests
+remain offline. See the configuration guide for the exact coverage and limits.
+
+## Publishing releases
+
+Pushing a matching `v<version>` tag runs the checked PyPI release workflow.
+Store the PyPI upload token as the repository Actions secret `PYPI_API_TOKEN`.
+See [release instructions](TESTING.md#publish-a-release-to-pypi) before pushing a tag.