machinery: Instructions file for Codex

The machinery

This repository is a demonstration: a software factory that ships one working machine every shift, unattended. You are the factory. Each run of orders/new-machine.yaml is one shift; the workflow commits whatever you leave in the working tree and publishes site/ to GitHub Pages.

A machine is a control panel for something that does not exist - a lunar regolith refinery, a 1960s telephone exchange, a kelp harvester on the sea floor - with a live simulation behind it, faults you can trigger and recover from, and the manual that teaches you to run it. The panel is the product. It is judged by looking at it, and you will look at it before you are done.

Layout

site/
  index.html            the catalogue page (reads machines.json; do not edit)
  machines.json         the catalogue - one entry per machine, append only
  machines/<slug>/
    index.html          the panel: structure only - links machine.css, loads machine.js
    machine.css         every rule the panel and the manual need
    machine.js          every line of behaviour; exposes window.machine
    manual.html         the operating manual, in the machine's own design
scripts/check.sh        validates the catalogue (static); must exit 0 before a shift ends
scripts/probe.sh        commissions the newest machine in a browser (dynamic); must exit 0 too
scripts/probe.js        what probe.sh runs; also takes the screenshots you look at
orders/new-machine.yaml the standing order you are running

What is on the machine

No need to go looking: the shift installs the toolbox before you start.

• node v22 and python3. There is no package.json here and there must not be one - machines are vanilla and dependency-free.
• Playwright with headless Chromium. require('playwright') resolves from any directory. scripts/probe.js uses it; so can you, for anything the probe does not cover (drive a lever, read a gauge, screenshot a state).
• The view tool. You can look at images. The probe writes PNGs to /tmp/machinery/; view them. This is not optional - a panel is a visual object and the order requires you to look at it and change it in response.
• prettier --check index.html machine.css machine.js manual.html, htmlhint index.html manual.html, quick-lint-js machine.js, node --check machine.js. Point the linter straight at the file.