archilyzer

commit cc3b64f76c0d1f3dd57d32f67f01fb50ffd7ff65
parent 6a947f4363450a40cd14314b241c3d673a869970
Author: I Mean I'm Just Saying <imeanimjustsaying@kiwifarms.st>
Date:   Mon, 28 Sep 2026 02:46:35 -0400

docs: PUBLISH.md — the build mode is a label; the homepage row; four clauses back (review S2, Q4, L3)

- S2: "Building every site in containers" said the pipeline was opt-in
  through Settings → Build pipeline → Docker and that Basic builds one site
  at a time. Build all uses containers whenever `docker version` answers,
  and the mode (Settings or the /sites toggle) is persisted and shown but
  read by no build.
- Q4: the homepage row gains O4's surfaces: /sites → Homepage (Build
  homepage, Deploy after build, Deploy homepage, a preview branch),
  `pnpm ops build-homepage` (`{"deploy":true}`) and `deploy-homepage`
  (`{"preview":…}`), and the CLI's `--preview`.
- L3: `pnpm run deploy` takes SITE_ID too; the cache purge's how-to
  (Caching → Purge, or wrangler/the API); the hotlink rule's dashboard path
  (Security → WAF → Custom rules); the /sites toggle as the mode's second
  home.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Diffstat:
M
PUBLISH.md
 | 
27
++++++++++++++++-----------

1 file changed, 16 insertions(+), 11 deletions(-)
diff --git a/PUBLISH.md b/PUBLISH.md
@@ -50,14 +50,14 @@ entry points in `common/publish/build.ts`.
 | Build, then deploy | *Build & deploy* | `build-deploy` | `build site <id>` then `deploy site <id>` |
 | Build every site | /sites → **Build all sites** | — | `build all [--skip-archives]` |
 | The hub | /sites → Hub → **Build hub** / **Deploy hub** | `build-hub`, `deploy-hub` | `build hub`, `deploy hub [--preview <branch>]` |
-| The homepage | — | — | `build homepage`, `deploy homepage` |
+| The homepage | /sites → Homepage → **Build homepage** (tick *Deploy after build*) / **Deploy homepage**, with an optional preview branch | `build-homepage` (`{"deploy":true}` to deploy after), `deploy-homepage` (`{"preview":"<branch>"}`) | `build homepage`, `deploy homepage [--preview <branch>]` |
 
 `pnpm archilyzer <command>` is the short form of
 `pnpm --filter yt-dlp-transcript-common exec tsx bin/archilyzer.ts <command>`;
 `pnpm archilyzer --help` lists every command, and `pnpm archilyzer doctor` checks that
 this machine has what a build needs. From `export/`, `pnpm run build` is
-`archilyzer build site` (with `SITE_ID`) and `pnpm run deploy` is `archilyzer deploy
-site`.
+`archilyzer build site` and `pnpm run deploy` is `archilyzer deploy site`; both take
+the site from `SITE_ID` when no id is given.
 
 Deploy-only ships whatever is in `export/out`, which the basic build composes one
 site at a time into a single shared directory — so it **refuses, before starting a
@@ -299,8 +299,9 @@ in order of impact:
    repeated downloads are served from cache and **never hit R2**. To make caching
    aggressive, add a **Cache Rule** (**Caching → Cache Rules → Create**): *when* `URI
    Path` contains `/archives/`, *then* Eligible for cache, **Edge TTL → Override → 1
-   day** (or longer). If you raise the TTL a lot, **purge the cache on deploy** so a
-   re-uploaded archive is not served stale.
+   day** (or longer). If you raise the TTL a lot, **purge the cache on deploy**
+   (dashboard **Caching → Purge**, or `wrangler`/the API) so a re-uploaded archive is
+   not served stale.
 2. **Rate limiting — the hard backstop.** A Rate Limiting rule caps how fast any
    single client can pull archives, stopping a flood that misses cache (**Security →
    WAF → Rate limiting rules → Create**; the free plan includes one rule): *when*
@@ -312,7 +313,8 @@ in order of impact:
    (free) blocks the low-effort scripted abuse that makes up most of this traffic; the
    free **WAF managed ruleset** adds a baseline at no cost.
 4. **Hotlink protection (optional).** Stops other sites embedding your archives and
-   spending your ops budget serving their audience. A WAF custom rule: *when* `URI
+   spending your ops budget serving their audience. A WAF custom rule (**Security →
+   WAF → Custom rules**): *when* `URI
    Path` contains `/archives/` **and** `Referer` does not contain your domain **and**
    `Referer` is not empty, *then* Block. (Allow an empty `Referer` so direct clicks and
    privacy-conscious browsers still work.)
@@ -354,10 +356,13 @@ any limit.
 > is about *building sites*: fanning per-site export builds out across containers,
 > using `Dockerfile.build`. The two share nothing but the word "docker".
 
-The docker build mode builds **every site in parallel** in isolated containers, then
+**Build all sites** builds **every site in parallel** in isolated containers, then
 deploys them serially — a large speedup when you host several sites, and stronger
-isolation than the basic single-process build. It is opt-in: **Settings → Build
-pipeline → Docker**. Basic mode, the default, builds one site at a time in `export/`.
+isolation than building one site at a time in `export/`. It does so **whenever a
+container engine answers** (`docker version`), and builds serially on the host when
+none does. The **Build pipeline → mode** (Basic / Docker, in Settings or on the
+/sites toggle) is persisted and shown, but no build reads it today: it is a label,
+not a switch. A single site's build always runs in `export/`, one at a time.
 
 **Prerequisites.**
 
@@ -372,8 +377,8 @@ pipeline → Docker**. Basic mode, the default, builds one site at a time in `ex
 The build image is built (and cached) automatically from `Dockerfile.build` the first
 time you run; **Build image** / **Dockerfile** in Settings override the tag and path.
 
-**How it works.** Trigger it with **Build all sites** on /sites (or `pnpm archilyzer
-build all`, which uses docker when `docker version` answers). One job runs three
+**How it works.** Trigger it with **Build all sites** on /sites, or `pnpm archilyzer
+build all`; both use containers when `docker version` answers. One job runs three
 ordered phases:
 
 1. **Phase A — shared, on the host, once.** The data phase (the search index and the