Paloma's Orrery

Paloma's Orrery

Tony Quintanilla, PE | Anthropic's Claude Opus 5 | August 31, 2026

Rewritten under ledger handle L-270. Cut from e382650b at https://github.com/tonylquintanilla/palomas_orrery (branch main). The prior version is archived at documentation/README_archived_20260831.md. The anchor names the state this file was written against, not a promise the repository still sits there. Updated October 4, 2026 with Anthropic's Claude Opus 5.5 (L-409): the License section's years, and its pointer to NOTICE.md.

What this file is. The project's front door, in two halves. Part 1 says what Paloma's Orrery is and where to find the pieces that describe it. Part 2 describes how the work is kept correct -- the provenance discipline, the protocol and skills layer, the maintenance runners, and the commit discipline. That second half is written for whoever picks the project up, including an AI collaborator starting a session cold, rather than summarized for a casual reader.

An astronomical visualization suite that turns NASA, JPL and ESA data into interactive 3D and 2D views of the solar system, the stellar neighborhood, the Galactic Center, and Earth's climate system.

See it without installing anything: palomasorrery.com

Paloma's Orrery is a personal tool, built first for its author's own exploration and learning. Tony Quintanilla -- a retired civil and environmental engineer, artist and anthropologist -- develops it through conversational AI collaboration, and named it for his daughter. The project began in September 2024 and has grown alongside the models that help build it. The account of how it started, in Tony's own words, is PROJECT_ORIGIN.md.

Philosophy: Data Preservation is Climate Action. Scientific accuracy first, visual beauty always.

Table of Contents

Part 1 -- What it is and where to find it

1. What you can reach from where
2. See it
3. What it covers
4. Where things are
5. Running it yourself

Part 2 -- How the work is kept correct

6. The problem this solves
7. Two layers: the protocol and the skills
8. Session start: the SHA round trip
9. The ledger and the handoffs
10. Provenance: where the numbers come from
11. From the orrery to the gallery
12. Before the push: the maintenance runners
13. The push

Part 3 -- Administrative

14. Contributing
15. License
16. Contact

PART 1 -- WHAT IT IS AND WHERE TO FIND IT

What you can reach from where

This project's pieces are not all available in the same place, and the differences matter enough to state before anything else. Four contexts, each one adding to the one above it.

The last row is the one that is easy to get wrong, so it is worth being exact. The protocol and the skills are ordinary files in this repository. Anyone can read them on GitHub. What cannot be reached from GitHub is their installed form -- the copy an AI session actually loads when it starts. That copy lives in the account, not in the repo, and it is invisible to everyone, including the running session that is using it.

This is why a skill lives in three stores rather than one: the repository copy that anyone can read, the account install that a session actually loads, and the generated manifest inside the protocol that says which version is expected. It is also why reinstalling a skill mid-conversation does not reach the conversation already in progress, and why a version bump made during a session is carried forward in writing for the next session to confirm rather than being marked done on the spot. Part 2 returns to this.

See it

Nothing here needs to be installed. All of it runs in a browser.

The two galleries are not competing versions of the same thing. The curated gallery is a published picture: fixed, fast, and exactly what its author chose to show. The interactive gallery is a working instrument the visitor drives. Both are wanted, and the curated one is not being retired.

What it covers

The solar system, in the most detail: planetary and spacecraft positions fetched live from JPL Horizons, comets with their dust and ion tails, planetary interiors, rings, radiation belts and atmospheric shells, Lagrange points, close approaches, spacecraft mission trajectories, and exoplanet systems. Beyond it, the stellar neighborhood mapped from Gaia and Hipparcos, and the Galactic Center's S-stars orbiting Sagittarius A* with their relativistic precession drawn against the Newtonian prediction. Alongside those, an Earth system hub carrying long climate records and forensic heat-wave analysis as 3D layers for Google Earth Pro. Everything can be exported: as standalone HTML, as PNG, as a 9:16 portrait view for social video, or as KML and KMZ.

That paragraph is deliberately the whole of the feature list here. The authoritative, current inventory is generated from the code itself and lives in MODULE_INDEX.md -- go there rather than trusting a hand-written summary that was true on the day it was typed.

Where things are

Two repositories, siblings on disk

The project spans two public repositories. They are kept as sibling folders in the same parent directory, not nested one inside the other.

• palomas_orrery (this one) -- the desktop application, its documentation, and the provenance and maintenance tooling.
• tonyquintanilla.github.io -- the web gallery: both gallery viewers, the published visualization data, the served solar-system cache, the nightly cache builder, and the gallery-side tooling.

GitHub Pages needs its own repository, which is why the split exists at all. The sibling layout matters because tools/gallery_studio.py in the gallery repo reaches back into this one: to attach Object Encyclopedia entries to a figure it walks up the directory tree looking for a folder containing constants_new.py, and imports info_dictionary from there. If it does not find one it degrades quietly and attaches nothing, so a gallery clone without its sibling still works -- it just loses the encyclopedia.

Key documents

The table below is GENERATED by doc_index.py from the documents themselves -- each one carries a one-line Doc-Kind tag saying what it is and what it is for. Do not edit the rows by hand; edit the tag in the document, and the next maintenance run rewrites the table. The Kind column matters: hand-editing a generated document is an error, because the next run of its generator destroys the edit.

Documents in documentation/ are not indexed here. Start with MODULE_INDEX.md for the code and the deep-dive links further down this file for the rest.

The deep-dive documents, which live in documentation/:

Layout

palomas_orrery/                  # this repo
|- *.py                          # Python modules, all at root
|- README.md, LICENSE.md, NOTICE.md   # you are here
|- PROJECT_INSTRUCTIONS.md       # the protocol (Part 2)
|- PROJECT_ORIGIN.md             # how it started
|- MODULE_INDEX.md               # what every module does (generated)
|- MODULE_ATLAS.md               # full architecture atlas (generated)
|- LEDGER_CONSOLIDATED.md        # running work ledger and change log
|- PROVENANCE_AUDIT.md           # citation audit (generated)
|- DATA_INVENTORY.md             # local data store inventory (generated)
|- ADDING_OBJECTS_GUIDE.md       # how to add a new celestial object
|- WORKSHEET_CHECK.md            # cross-check annotation audit (generated)
|- requirements.txt              # annotated dependency spec
|- orrery_maintenance_run.py     # the pre-push suite (Part 2)
|- skills/                       # versioned AI-collaboration skill files
|- documentation/                # deep-dive docs, design manifests,
|                                #   handoffs, spent patch scripts,
|                                #   archived prior versions
|- docs/                         # generated architecture pages
|- data/, star_data/             # local data (large files gitignored)
|- reports/                      # generated analysis reports

Running it yourself

Most people do not want to run the Python, and that is fine -- the galleries above are how the project reaches everyone else. If you do want to run it, the source is the actively maintained path. It works on Python 3.11 through 3.13, on Windows, macOS and Linux.

git clone https://github.com/tonylquintanilla/palomas_orrery.git
cd palomas_orrery
pip install -r requirements.txt
python palomas_orrery.py            # the main solar system GUI
python palomas_orrery_dashboard.py  # launcher for every tool

The data files are not in the repository. The stellar catalogs and the orbit path cache are large and gitignored. Either download a release ZIP from the Releases page and copy its data/ and star_data/ folders into your clone, or just start using the app -- it fetches and caches on demand, so the first plots are slower and the cache fills as you explore.

Two dependency facts worth knowing before you upgrade anything. kaleido is pinned at exactly 0.2.1, and Plotly stays on 5.x to keep it working; Python 3.14 is not yet supported. Both are annotated in full in requirements.txt, including the upgrade path and the issues to watch. Read it there rather than here -- it is maintained, and this paragraph is not.

On Linux, install the system Tk packages first (sudo apt install python3-tk python3-pil.imagetk on Ubuntu and Debian, then add --break-system-packages to the pip command). Minor cosmetic GUI issues appear on some window managers; the visualizations themselves are rendered in the browser and are unaffected.

To update later, git pull. Your local data/ and star_data/ are untouched, since they were never in the repo.

PART 2 -- HOW THE WORK IS KEPT CORRECT

The problem this solves

This codebase is written through conversation with AI models. That arrangement has one structural weakness, and everything in Part 2 is a response to it: every session starts cold.

A model recalls plausibly-wrong specifics with complete confidence. A handoff document between sessions is a claim, and claims drift from the code they describe. A number typed from memory looks exactly like a number read from a paper. Left alone, a project built this way does not hold steady -- it erodes, quietly, while every individual session looks fine.

So the discipline below is not process for its own sake. Each rule exists because a specific failure happened once, and most of them are about declining a shortcut rather than doing extra work: not patching the plausible date, not citing over a recalled value, not building on a stale base, not trusting a handoff over the render.

The general principle, and the one worth carrying away if nothing else is: verify against something that cannot be talked into agreeing with you. The rendered plot, the source paper, the file on disk, the commit hash. When a docum