The Publish Gate: gist + Cloudflare Pages

Every loop ends the same way. The artifact converges — it actually meets the measurable "done" you set at the start — and a small, self-contained course is written to explain it. At that exact moment one last thing happens automatically: the course gets published, so it lives somewhere other than the folder it was born in. That final step is the Publish Gate.

Publishing happens in two tiers, and they are independent. The first tier is a private gist — a single, link-only snapshot you can hand to anyone, that opens as a navigable little site. The second tier is a hosted website on Cloudflare Pages — a real, live URL on a global network, kept private by a login gate. You can have one, both, or neither, and the system tells you exactly which tiers actually went out.

This is the one moment in the whole loop where the system reaches outward on its own — it creates something on the internet without stopping to ask. That sounds bold, so the rule around it is deliberately narrow: it is the only standing-authorized outward action, it only ever publishes the course you just made, and it skips itself the instant the situation says it shouldn't. Everything else the loop does stays on your machine.

Think of it like… finishing a book. The manuscript on your desk is the real, editable original — that never goes away. But once it's done, you also make two copies that leave the desk: a single bound proof you can mail to a friend (the gist), and a copy placed on a library shelf where anyone with a library card can read it (the hosted site). The desk copy is still home; the other two just let the work travel.

It helps to hold three places in your head, because they do different jobs.

The repo course/ directory is the original. It is where the course is authored and where every link already resolves. Nothing about publishing replaces it — it stays the canonical, navigable home for the course, and it is the place you keep editing.

The gist is a private, off-machine snapshot. Think of it as a frozen copy you can share with a link, without giving anyone access to your repo or your machine. It is always attempted, because it needs almost nothing to work.

The Cloudflare Pages site is the hosted tier — a genuine website with its own address, served from a fast global network, that you can keep private behind a login. It is the tier you reach for when you want people to simply open a link in a browser and read, with no download step.

The key idea: these are layers, not replacements. The repo is home; the gist is a portable copy; the hosted site is the public-facing reading room. Publishing adds reach without ever taking the original away.

The gist is the tier that almost always goes out, because it asks for so little. You point one script at the finished course folder, it bundles up every page into a single private gist, and it prints back a URL. The gist is secret — which on GitHub means link-only: not listed anywhere, not searchable, visible only to someone you hand the link to. That is as close to private as a gist gets.

What you get is a snapshot frozen in time. It does not track your repo, it does not change when you keep editing — it is the course exactly as it stood the moment you published. Anyone with the link can read it in the browser, or download the whole thing as a ZIP and open it offline, and it still works as a clickable course.

There is one small piece of plumbing worth knowing: a gist cannot contain folders. The course lives in folders. So before it uploads, the script quietly flattens everything into a single layer of files and rewrites the links between pages so they still point to the right place. You never see this — you just get a gist that behaves like the real course.

The second tier puts the course on a real website. Instead of a snapshot you download, this is a live address on Cloudflare's global network — fast to load from anywhere, and a true site where the folders and links work just as they do at home, with nothing to flatten. You reach for it when you want the simplest possible reader experience: send a link, they click, they read.

This tier asks for a little more setup. Once, on your machine, you log into Cloudflare through a tool called wrangler. That login is a one-time, human step — you do it in a browser, and the access token never leaves your computer. After that, the publish script can deploy the site whenever the loop converges.

By default a freshly deployed Pages site is reachable by anyone who knows the URL. To make it genuinely private — readable only by people you name, from anywhere — you turn on Cloudflare Access, a login gate, in the Cloudflare dashboard. That is a one-time click-through the human does; it cannot be automated with the publish token, so the script simply reminds you to do it rather than pretending it can.

Because publishing is the one outward move the loop makes on its own, it follows a simple, conservative rule: publish on convergence unless there is a clear reason not to. There are exactly two reasons to skip a tier — the scope of the task explicitly forbids publishing, or the tool that tier needs isn't logged in. If the scope says "keep this internal," nothing goes out. If gh isn't authenticated, the gist tier is skipped; if wrangler isn't logged in, the Pages tier is skipped. No drama, no failure — just a tier that quietly doesn't run.

It's worth seeing how the three kinds of participants in the harness relate to this one gate, because each has a different stake in it.

Feel how the two tiers depend on their preconditions. Each publish tier — gist and cloudflare-pages — only goes out when the loop has converged and the right CLI is authenticated. Flip a publish tier on while its precondition is off and a warning slides in telling you exactly what's missing; the summary line always reads back which tiers are actually live, with the repo course/ always standing behind them.