Skip to content

0006: Phase 2 workflow: two parallel tracks joined by one catalog

Date: 2026-10-03. Status: accepted by the owner.

Context

Phase 1 is complete (decision 0005). Phase 2 (PROGRAM.md §14–15) has two kinds of work with different owners and paces:

  • the website, which Claude builds and the owner reviews;
  • the physical pieces, where Claude screens and exports, and the owner prints, photographs and uploads to Printables.

Four baseline pieces were already printed before Phase 2 started: the cube–octahedron dual, the dodecahedron–icosahedron dual (130 mm), the icosidodecahedral star (130 mm) and the icosahedral crown (130 mm).

Decisions

  1. Two parallel tracks. Track A is the website; track B covers screening, printing, photography and Printables (PHASE2.md).
  2. A single catalog is the interface between the tracks. One file, catalog/pieces.yaml, with one entry per object. It holds:
  3. the recipe and solid;
  4. the status (candidate → screened → meshed → printed → photographed → listed);
  5. the printed size;
  6. the STL hashes;
  7. the photo paths;
  8. the Printables URL.

The site's gallery and the print/upload checklist are both generated from it, so they cannot drift apart. The owner's track only edits catalog fields. 3. Printables: one listing per piece, each offering both sizes. Each listing has the 80 mm and 130 mm STLs, tip to tip. The pieces are grouped in a Printables collection, and the site links each piece to its own listing. Media and meshes are CC BY 4.0 (decision 0001), and each listing states it. 4. Screen every candidate at both sizes, and choose the printed size per piece. The screening sheet reports, at 80 and 130 mm: - extent, waist (minimum radius) and volume; - mesh closure; - the closest zero–pole separation in millimetres, the "spike next to a pit" risk. 5. Printed pieces keep their printed files. For the four baseline prints, and any baseline piece printed later, Printables gets the exact STLs from figures_repo @ 292bec4, with their hashes recorded in the catalog. They are not regenerated by the new pipeline, which differs by the exact normalization (0.55% on the cube–octahedron dual), so the files match the photos. New pieces use the new pipeline. 6. Build locally, then release in one step. GitHub Pages serves only public repositories on the free plan. CI builds the site strictly on every push, and review happens on local builds. Flipping the repository public and running the (manual) deploy workflow is one explicit owner action at release.

Consequences

  • STLs stay out of git, as before. The catalog records their hashes, and a script regenerates the new ones.
  • Photos are the owner's and are committed under the media licence (CC BY 4.0), downscaled for the site.
  • Printables URLs exist only after upload. The site shows "print files coming" until then, so the site can be finished before every piece is listed.

Released (2026-10-04)

The repository was made public, and the deploy workflow published the site to https://kuvychko.github.io/polyhedra-to-rational-functions/. A crawl of the live site found every internal link and image in place. The first piece listed on Printables is the Cube–Octahedron Dual.

Amendment (2026-10-04): deploy on push

After the release, a manual deploy for every catalog update was a step easy to forget. The deploy workflow now also runs automatically when CI completes successfully for a push to main, and it deploys the commit CI tested. Lint, the tests on both platforms and the strict site build therefore gate every publication. Running it by hand still works, for redeploying without a new commit. Other branches and pull requests never deploy. Pushing to main is now a publishing step.

Amendment (2026-10-04): one group photo, not a photo per piece

Photographs of individual prints go on each piece's Printables listing, not on the site. The object pages already show the piece through the precomputed renders, including the uncolored relief, which does that job well. Once every piece is printed, one group photograph of the whole set goes on the home page. So:

  • the catalog has no photos field, and its status chain is candidate → screened → exported → printed → listed;
  • the checklist's next action after printing is the Printables listing;
  • the object pages have no photograph section.

PROGRAM.md's photograph items (§4's regression reference, the home page's strong photograph) are met by the group photo.