@augurworks/augur 0.15.1

package/templates/shell/roster-update.yml

@@ -0,0 +1,110 @@
+name: Roster update (from Augur Admin)
+
+# Receiver for Admin-panel roster changes. Inviting or removing a person in the
+# Augur Admin UI fires a `roster-update` repository_dispatch here (same channel
+# as "Delete forever"), and this job commits the change to identity.json — so
+# the identity file stays the ONE durable record and the KV roster overlay only
+# bridges the minute this takes. The deploy this push triggers sends the fresh
+# config back to the worker, which then drains the superseded overlay entry
+# itself. Both directions are idempotent: an email already in (or already gone
+# from) the file exits green with no commit.
+#
+# The push uses AUGUR_PIN_TOKEN so the commit retriggers deploy.yml — the
+# default GITHUB_TOKEN deliberately would not.
+
+on:
+  repository_dispatch:
+    types: [roster-update]
+
+concurrency:
+  group: roster-update
+  cancel-in-progress: false
+
+permissions:
+  contents: read # the push below authenticates with AUGUR_PIN_TOKEN
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.AUGUR_PIN_TOKEN }}
+          submodules: false
+
+      - name: Apply the change to identity.json and push (retry on races)
+        env:
+          ACTION: ${{ github.event.client_payload.action }}
+          EMAIL: ${{ github.event.client_payload.user.email || github.event.client_payload.email }}
+          USER_NAME: ${{ github.event.client_payload.user.name }}
+          USER_INITIALS: ${{ github.event.client_payload.user.initials }}
+          USER_COLOR: ${{ github.event.client_payload.user.color }}
+          USER_ROLE: ${{ github.event.client_payload.user.role }}
+          BY: ${{ github.event.client_payload.by }}
+        run: |
+          set -euo pipefail
+          case "$ACTION" in add|remove|role) ;; *) echo "::error::bad action '$ACTION'"; exit 1;; esac
+          if ! printf '%s' "$EMAIL" | grep -Eq '^[^[:space:]@]+@[^[:space:]@]+\.[^[:space:]@]+$'; then
+            echo "::error::client_payload does not carry a valid email"; exit 1
+          fi
+
+          # The edit, as an idempotent script we can re-run after a lost push race.
+          cat > "$RUNNER_TEMP/edit.cjs" <<'EOF'
+          const fs = require("fs");
+          const { ACTION, EMAIL, USER_NAME, USER_INITIALS, USER_COLOR, USER_ROLE } = process.env;
+          const lc = (s) => String(s || "").toLowerCase();
+          const users = JSON.parse(fs.readFileSync("identity.json", "utf8"));
+          const known = (u) => lc(u.email) === lc(EMAIL) || (u.emails || []).some((e) => lc(e) === lc(EMAIL));
+          let out = users, changed = false;
+          // `user` is the legacy spelling of `editor` and both mean the same thing, so
+          // neither is written out: an absent role IS an editor, and storing one would
+          // only give the file two ways to say the same thing.
+          const ROLES = ["admin", "editor", "viewer"];
+          const wanted = ROLES.includes(USER_ROLE) ? USER_ROLE : "editor";
+          if (ACTION === "add" && !users.some(known)) {
+            const entry = {
+              email: EMAIL,
+              name: USER_NAME || EMAIL.split("@")[0],
+              initials: USER_INITIALS || "",
+              emails: [],
+              color: USER_COLOR || "#4f46e5",
+            };
+            if (wanted !== "editor") entry.role = wanted;
+            out = [...users, entry];
+            changed = true;
+          }
+          if (ACTION === "remove") {
+            out = users.filter((u) => !known(u));
+            changed = out.length !== users.length;
+          }
+          // A role change from the Admin panel. The KV overlay already made it true;
+          // this is what makes it durable, and what lets the overlay entry drain.
+          if (ACTION === "role") {
+            out = users.map((u) => {
+              if (!known(u)) return u;
+              const current = u.role === "admin" || u.role === "viewer" ? u.role : "editor";
+              if (current === wanted) return u;
+              changed = true;
+              const { role, ...rest } = u;
+              return wanted === "editor" ? rest : { ...rest, role: wanted };
+            });
+          }
+          if (changed) fs.writeFileSync("identity.json", JSON.stringify(out, null, 2) + "\n");
+          console.log(changed ? "identity.json updated" : "already in the desired state");
+          EOF
+
+          git config user.name "augur-deploy"
+          git config user.email "augur-deploy@users.noreply.github.com"
+          for attempt in 1 2 3 4 5; do
+            node "$RUNNER_TEMP/edit.cjs"
+            if git diff --quiet identity.json; then
+              echo "nothing to commit — the file already agrees"; exit 0
+            fi
+            git commit -q -m "[roster] $ACTION $EMAIL${USER_ROLE:+ → $USER_ROLE} (via Augur Admin${BY:+, by $BY})" identity.json
+            if git push origin HEAD; then exit 0; fi
+            echo "push rejected (concurrent commit) — refetching and reapplying"
+            git fetch origin main
+            git reset --hard --quiet origin/main
+            sleep "$attempt"
+          done
+          echo "::error::push still rejected after 5 attempts — re-run this dispatch"; exit 1

package/templates/shell/space-preflight.yml

@@ -0,0 +1,35 @@
+name: Preflight — can CI read a space repo?
+
+# Part of the add-a-space ritual: BEFORE mounting a new space repo as a submodule,
+# verify SUBMODULE_PAT can read it — mounting first would break every deploy at the
+# checkout step until the grant is fixed. Run from the Actions tab (or
+# `gh workflow run space-preflight.yml -f repo=<owner/name>`); green = safe to mount.
+
+on:
+  workflow_dispatch:
+    inputs:
+      repo:
+        description: "Space repo (owner/name)"
+        required: true
+
+permissions: {}
+
+jobs:
+  probe:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Probe SUBMODULE_PAT read access
+        env:
+          PAT: ${{ secrets.SUBMODULE_PAT }}
+          REPO: ${{ inputs.repo }}
+        run: |
+          set -euo pipefail
+          if ! printf '%s' "$REPO" | grep -Eq '^[A-Za-z0-9][A-Za-z0-9_.-]*/[A-Za-z0-9._-]+$'; then
+            echo "::error::bad repo '$REPO' (expected owner/name)"; exit 1
+          fi
+          # Output fully discarded so the token-bearing URL can never reach the log.
+          if git ls-remote "https://x-access-token:${PAT}@github.com/${REPO}.git" HEAD >/dev/null 2>&1; then
+            echo "OK — SUBMODULE_PAT can read ${REPO}; safe to mount at spaces/<id>."
+          else
+            echo "::error::SUBMODULE_PAT cannot read ${REPO} — add it to the token's repository access (Settings → Developer settings → Fine-grained tokens), then re-run."; exit 1
+          fi

package/templates/shell/space-rebake.yml

@@ -0,0 +1,79 @@
+# Re-bake any roster space whose LIVE baked chrome (/_build.json builtWithEngine)
+# is behind this shell's pinned engine. Two triggers, one job:
+#   - workflow_call: deploy.yml runs it after every deploy (drift converges on
+#     every pin bump / config push).
+#   - repository_dispatch [space-rebake]: the WORKER fires this the moment a
+#     publish arrives baked with a non-current engine — the stale window is
+#     minutes, not until-the-next-deploy. The publisher is never involved.
+# Runtime chrome does NOT make this obsolete: serve-time composition fixes
+# marker-wrapped chrome, but pages baked before the markers existed — and all
+# baked generated markup (galleries, indexes) — only converge by republishing.
+# Drift-driven and idempotent: a converged space is a curl + skip, so over-firing
+# is harmless. Publishes from a dirty working tree are someone's live session and
+# are left alone; health.yml alarms if drift outlives its grace.
+name: Space re-bake
+on:
+  workflow_call: {}
+  workflow_dispatch:
+  repository_dispatch:
+    types: [space-rebake]
+concurrency:
+  group: space-rebake
+  cancel-in-progress: false
+jobs:
+  rebake:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true          # the engine, at the pinned sha — bakes exactly it
+          token: ${{ secrets.SUBMODULE_PAT }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      # For each stale roster space: clone it (full history — publish.mjs dates
+      # cards from git), check out the LIVE published sha when the clone has it
+      # (a re-bake must republish what IS live, never quietly ship someone's
+      # pushed-but-unpublished work), and publish with the star token, the pinned
+      # engine, and an explicit AUGUR_ORIGIN. When live's sha isn't in the clone
+      # (a direct publish that never pushed), publish main — the client-side
+      # reconcile adopts the live bytes, so nothing is lost either way.
+      - name: Re-bake roster spaces whose baked chrome is behind the engine
+        env:
+          GH_TOKEN: ${{ secrets.SUBMODULE_PAT }}   # clone the space repos
+          AUGUR_TOKEN: ${{ secrets.AUGUR_TOKEN }}  # *-scoped: publishes any space's content
+        run: |
+          set -uo pipefail
+          if [ -z "${AUGUR_TOKEN:-}" ]; then echo "AUGUR_TOKEN unset (assets-mode) — nothing to re-bake"; exit 0; fi
+          NEW="$(git rev-parse 'HEAD:engine' 2>/dev/null || true)"
+          [ -n "$NEW" ] || { echo "no engine pin on disk — skipping"; exit 0; }
+          ORIGIN="$(jq -r '.siteOrigin // empty' deploy.config.json)"
+          [ -n "$ORIGIN" ] || { echo "no siteOrigin in deploy.config.json — skipping"; exit 0; }
+          STAMP="$(curl -fsS --max-time 30 "$ORIGIN/_build.json" 2>/dev/null || echo '{}')"
+          FAILED=""
+          while read -r ID REPO; do
+            [ -n "$ID" ] && [ -n "$REPO" ] || continue
+            BW="$(printf '%s' "$STAMP" | jq -r --arg id "$ID" '.spaces[$id].builtWithEngine // empty')"
+            DIRTY="$(printf '%s' "$STAMP" | jq -r --arg id "$ID" '.spaces[$id].dirty // false')"
+            LIVE_SHA="$(printf '%s' "$STAMP" | jq -r --arg id "$ID" '.spaces[$id].sha // empty')"
+            if [ "$BW" = "$NEW" ]; then echo "$ID already on ${NEW:0:12} — skip"; continue; fi
+            if [ "$DIRTY" = "true" ]; then echo "$ID is a working-tree publish — leaving it"; continue; fi
+            DIR="$RUNNER_TEMP/space-$ID"; rm -rf "$DIR"
+            if ! git clone --quiet "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git" "$DIR"; then
+              echo "::warning::clone of $REPO failed — skipping $ID"; FAILED="$FAILED $ID"; continue
+            fi
+            if [ -n "$LIVE_SHA" ] && git -C "$DIR" cat-file -e "$LIVE_SHA^{commit}" 2>/dev/null; then
+              git -C "$DIR" checkout --quiet "$LIVE_SHA"
+              echo "re-baking $ID at live sha ${LIVE_SHA:0:12} (${BW:-<none>}→${NEW:0:12})"
+            else
+              echo "re-baking $ID from main — live sha ${LIVE_SHA:-<none>} not in clone; reconcile adopts live bytes (${BW:-<none>}→${NEW:0:12})"
+            fi
+            if ( cd "$DIR" && AUGUR_ORIGIN="$ORIGIN" GV_SPACES_ROOT="$DIR" node "$GITHUB_WORKSPACE/engine/scripts/publish.mjs" ); then
+              echo "re-baked $ID"
+            else
+              echo "::warning::re-bake of $ID failed"; FAILED="$FAILED $ID"
+            fi
+          done < <(jq -r '.spaces[]? | "\(.id) \(.repo)"' deploy.config.json)
+          if [ -n "$FAILED" ]; then echo "::error::re-bake failed for:$FAILED — see warnings above"; exit 1; fi
+          echo "re-bake pass complete."

package/templates/shell/store-backup.yml

@@ -0,0 +1,152 @@
+name: Bundle-store backup
+
+# Off-Cloudflare copies of everything the live site serves.
+#
+# The store is the only copy of published content, and R2 has no point-in-time
+# restore. Most of it is reproducible — clone a space at the sha /_build.json
+# reports and publish again — but a publish made from an uncommitted working tree
+# serves bytes held in NO repository, and those are gone with the bucket.
+# `augur ship` makes that state rare by committing first; this makes it
+# survivable.
+#
+# The copy is a plain directory: manifests/<id>.json + blobs/<sha256> +
+# export.json. Restore is `augur restore <dir>` from any machine holding a
+# publish token — see the engine's docs/store-recovery.md.
+#
+# TWO SLOTS, ON PURPOSE — one recent copy and one old one:
+#
+#   weekly   Sunday, kept 10 days  → there is always a copy under a week old
+#   monthly  the 1st, kept 40 days → there is always a copy roughly a month old
+#
+# The old slot is the one that matters against a quiet compromise. Anything that
+# corrupts or empties the store on a Tuesday is in every copy taken after it, so
+# a rolling week of dailies protects you from accidents and not from an attack
+# you notice late. A month-old copy does.
+#
+# Cost: each run uploads a FULL copy (the export's incremental skip saves nothing
+# across runs, because a fresh runner starts empty), and Actions artifact storage
+# is shared across every repo in the account — not per-repo. Two slots is roughly
+# two full copies steady state. Frequency and retention are the only real knobs.
+#
+# Residual risk worth naming: anyone with write access to THIS repo can delete
+# these artifacts as easily as read them. Genuine immutability needs an offsite
+# with object-lock, which is a different job from this one.
+#
+# SET BEFORE USE: AUGUR_ORIGIN below. Secrets: AUGUR_TOKEN, star-scoped — a
+# space-scoped token silently skips the spaces it cannot read, and this job fails
+# if anything was skipped.
+
+on:
+  schedule:
+    - cron: "40 2 * * 0" # weekly  — Sunday 02:40 UTC (offset: GitHub drops top-of-hour crons)
+    - cron: "40 3 1 * *" # monthly — the 1st, 03:40 UTC
+  workflow_dispatch: # take one on demand before anything risky
+    inputs:
+      slot:
+        description: "Which slot this manual copy fills"
+        type: choice
+        default: weekly
+        options: [weekly, monthly]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: store-backup
+  cancel-in-progress: false
+
+# github.event.schedule carries the cron line that fired, so one workflow serves
+# both slots without duplicating the job.
+env:
+  SLOT: ${{ github.event.schedule == '40 3 1 * *' && 'monthly' || inputs.slot || 'weekly' }}
+
+jobs:
+  backup:
+    runs-on: ubuntu-latest
+    steps:
+      # ⛔ REFUSE TO RUN ON A PUBLIC REPOSITORY. First step, on purpose.
+      #
+      # A COMMENT IS NOT A GUARD, AND THIS HAS ALREADY HAPPENED. A public fork of the
+      # engine ran a workflow of this shape and published a full production KV export of
+      # a live instance — 58 keys, 26 internal comment threads, five real names and
+      # personal addresses — reachable with no authentication. GitHub shares git objects
+      # across a fork network, so the commit resolved through the PARENT repository's own
+      # raw URL: deleting the branch, deleting the fork and rewriting the parent's history
+      # all leave it fetchable, and only a GitHub Support object purge closes it. The
+      # header above this job said "the shell repo must be private" the whole time.
+      #
+      # IT FAILS, IT DOES NOT SKIP. A skip is worse than having no backup workflow at all,
+      # because the operator goes on believing a backup exists.
+      #
+      # AND IT FAILS WHEN IT CANNOT TELL. `github.event.repository.private` is absent on
+      # some event types, and an absent value is not a private repository — it is an
+      # unanswered question, and this is the one question that must not have a default.
+      - name: Refuse to run on a public repository
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CTX_PRIVATE: ${{ github.event.repository.private }}
+        run: |
+          set -uo pipefail
+          PRIVATE="$(gh api "repos/${GITHUB_REPOSITORY}" --jq .private 2>/dev/null || true)"
+          if [ -z "$PRIVATE" ]; then PRIVATE="${CTX_PRIVATE:-}"; fi
+          case "$PRIVATE" in
+            true)
+              echo "OK: ${GITHUB_REPOSITORY} is private"
+              ;;
+            false)
+              echo "::error::REFUSING TO RUN: ${GITHUB_REPOSITORY} is a PUBLIC repository. This job exports the instance's whole state and writes it into this repo. On a public repo that publishes it to anyone, permanently — a fork network keeps the objects fetchable through the parent's URL after the branch, the fork and the history are all gone. Make the repository private, or delete this workflow."
+              exit 1
+              ;;
+            *)
+              echo "::error::REFUSING TO RUN: could not determine whether ${GITHUB_REPOSITORY} is private (got '${PRIVATE}'). An unanswered question is not a private repository."
+              exit 1
+              ;;
+          esac
+
+      - uses: actions/checkout@v4
+        with:
+          submodules: true # the engine carries the export script
+          token: ${{ secrets.SUBMODULE_PAT }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Export the store
+        env:
+          AUGUR_TOKEN: ${{ secrets.AUGUR_TOKEN }}
+          AUGUR_ORIGIN: https://your-site-origin.example # ← your deploy.config.json siteOrigin
+        run: |
+          set -euo pipefail
+          if [ -z "$AUGUR_TOKEN" ]; then
+            echo "::error::AUGUR_TOKEN is not configured — nothing can be backed up."; exit 1
+          fi
+          node engine/scripts/export.mjs --out backup
+
+      # A backup that quietly omits a space is the one you discover is short on
+      # the day you need it. export.json records anything it could not read;
+      # refuse to publish an artifact that claims to be a copy and isn't.
+      - name: Refuse an incomplete copy
+        run: |
+          set -euo pipefail
+          SKIPPED="$(jq -r '.skipped | length' backup/export.json)"
+          if [ "$SKIPPED" != "0" ]; then
+            echo "::error::the export skipped $SKIPPED target(s) — check AUGUR_TOKEN is star-scoped:"
+            jq -r '.skipped[] | "  - \(.id): \(.reason)"' backup/export.json
+            exit 1
+          fi
+          echo "Spaces copied:"; jq -r '.spaces[] | "  \(.id) v\(.version)\(if .source.dirty then "  [DIRTY — these bytes exist in no repo]" else "" end)"' backup/export.json
+          echo "Blobs: $(jq -r .blobs backup/export.json)  ·  $(du -sh backup | cut -f1)"
+
+      - name: Stamp the copy
+        id: stamp
+        run: echo "on=$(date -u +%Y-%m-%d)" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: store-${{ env.SLOT }}-${{ steps.stamp.outputs.on }}
+          path: backup
+          # Each slot outlives its own interval, so a copy always exists even in
+          # the moments around a scheduled run.
+          retention-days: ${{ env.SLOT == 'monthly' && 40 || 10 }}
+          compression-level: 0 # the payload is already-compressed images and woff2

package/templates/shell/wrangler.example.toml

@@ -0,0 +1,266 @@
+# TEMPLATE — copy this into YOUR DEPLOY SHELL as wrangler.toml and fill it in.
+#
+# It is deliberately not a live wrangler.toml: a worker's name, its account, its KV
+# namespace and its R2 bucket belong to ONE instance, so the shared engine must not carry
+# them. `wrangler` ignores this filename, which also means a stray `npx wrangler` run
+# inside an engine clone cannot pick it up. Same pattern as realtime/wrangler.example.toml.
+#
+# It is hand-authored per shell rather than generated from deploy.config.json ON PURPOSE:
+# five of the six mandatory values below (worker name, account id, compatibility date, KV
+# namespace id, R2 bucket) have no source in any deploy.config.json today, so generating
+# it would mean inventing a config block, bumping the shell contract, and committing
+# account and namespace ids into shell repos — for a file each shell writes once.
+#
+#   npx wrangler deploy --dry-run -c wrangler.toml   # resolves every binding, ships nothing
+#   node engine/scripts/wrangler-preflight.mjs -c wrangler.toml
+#
+# ─────────────────────────────────────────────────────────────────────────────────────
+# ⛔ READ THIS BEFORE CHANGING [assets]. IT IS THE LOGIN GATE.
+#
+# Pages and Workers invert request precedence, and the inversion is silent.
+#
+#   Pages    runs _worker.js FIRST for every request; the worker decides what is public
+#            and falls through to the static asset only when it chooses to.
+#   Workers  serves a MATCHING STATIC ASSET FIRST and only invokes the worker on a miss —
+#            unless `run_worker_first = true`.
+#
+# `engine/dist` is the asset directory, and it contains `__config/instance.json`, which
+# carries the instance's user roster INCLUDING SEED PASSWORDS (build.js writes `users:
+# IDENTITY`, unstripped, and says so in its own comment). It also contains the admin page
+# and, in assets mode, every built page.
+#
+# So without `run_worker_first = true`, a deploy that passes every test in the engine and
+# answers a health check with "healthy" serves the roster, the admin panel and every gated
+# page to anyone who asks. That is not a hardening flag. It IS the gate.
+#
+# `scripts/wrangler-preflight.mjs` refuses to pass a config whose asset directory holds
+# __config/instance.json without it, and runs in the workflow that gates the deploy.
+# ─────────────────────────────────────────────────────────────────────────────────────
+
+name = "<your-instance>"                  # the Worker's name, e.g. augur-<instance>
+account_id = "<your-cloudflare-account-id>"
+main = "engine/src/entry.js"              # relative to THIS file, i.e. your shell's root
+compatibility_date = "2026-07-01"
+
+[assets]
+directory = "engine/dist"                 # what `node engine/build.js` emits
+binding = "ASSETS"                        # the worker reads its own config through this
+# The line the gate depends on. See the block above before touching it.
+run_worker_first = true
+# Stated explicitly rather than left to the default. "none" is what keeps the worker's own
+# `asset.status === 404` branches firing; "single-page-application" would answer every
+# unknown path with the index page at status 200, which is the bug engine/dist/404.html
+# exists to prevent.
+not_found_handling = "none"
+# /foo, /foo/ and /foo/index.html all resolve, which is what published prototype folders
+# rely on. Stated explicitly for the same reason as above.
+html_handling = "auto-trailing-slash"
+
+# Comments, pins, statuses, rosters, canvas boards, publish tokens. The SAME namespace the
+# Pages project binds as COMMENTS and the realtime worker binds as BOARD_KV — during a
+# migration both front doors read one store, which is what makes the cutover reversible.
+[[kv_namespaces]]
+binding = "COMMENTS"
+id = "<your-kv-namespace-id>"
+
+# The bundle store: content-addressed blobs plus per-space manifests. A live instance
+# serves published content from here, never from the asset directory, so an instance with
+# no BUNDLES binding is a site with nothing published in it.
+[[r2_buckets]]
+binding = "BUNDLES"
+bucket_name = "<your-r2-bucket>"
+
+# ── Canvas rooms, once this instance serves them from its own worker ────────────────────
+#
+# Uncomment BOTH blocks together, and only when you are ready to retire this instance's
+# standalone `augur-realtime-<instance>` worker. The class already ships in the engine's
+# deploy entry, so wrangler resolves it; what these add is the binding and the migration
+# that creates the Durable Object namespace.
+#
+# The room's KV mirror uses the COMMENTS binding above — the same namespace the standalone
+# worker binds as BOARD_KV, which is why folding realtime in here removes a binding rather
+# than adding one. The room accepts either name for as long as both deployments exist.
+#
+# ⚠️ The rooms in THIS namespace are new and empty: a Durable Object's storage belongs to
+# the script that created it, so boards do not travel from the standalone worker. They
+# migrate on first touch from the KV mirror, which lags by up to 45 seconds — so cut over
+# when boards are quiet, not mid-session.
+#
+# ⚠️ THE BINDING ALSO MOVES THE BOARD KEY, and that is one cutover, not two. With rooms
+# bound, `/__rt` names each room `<workspace>:<path>` and the board document is written to
+# `board:<workspace>:<path>`; without it, both keep the unscoped spelling they have always
+# had. The two ride together because the rail and the room's mirror are one script only
+# here — scoping one of them while the other is in a separate worker would leave the rail
+# reading a key nothing writes. A board written before the cutover is still found: both
+# readers fall back to the unscoped key, serve it, and write it back scoped.
+#
+# So the cutover, in order:
+#   1. deploy with the blocks below uncommented (the worker now serves its own rooms)
+#   2. CLOUDFLARE_API_TOKEN=… CLOUDFLARE_ACCOUNT_ID=… AUGUR_KV_NS=… \
+#        node engine/scripts/migrate-board-keys.mjs --workspace <id>
+#      — a DRY RUN, and it has to report `differing 0` before anything else happens
+#   3. the same command with --apply
+#   4. stop the standalone worker only after the boards look right
+# `<id>` is the `tenantId` the build stamped into __config/instance.json, which is the
+# deploy config's `tenantId` if it sets one and otherwise EMPTY — an empty one resolves to
+# the literal `default`, and that is what to pass. Guessing it wrong is silent: the site
+# keeps working on the read-through while a second, stale copy of every board accumulates.
+#
+# [[durable_objects.bindings]]
+# name = "ROOMS"
+# class_name = "BoardRoom"
+#
+# [[migrations]]
+# tag = "v1"
+# new_sqlite_classes = ["BoardRoom"]
+
+# ── The workspace store, once membership moves off KV ───────────────────────────────────
+#
+# One Durable Object per workspace, holding the roster, roles, invites, publish tokens and
+# profile photos this instance's KV holds under `users:*` and `publish:tokens` today.
+# Schema and reasoning: engine/src/tenant-do.js.
+#
+# The point of it is that the isolation stops being a rule about key naming: a DO's storage
+# belongs to that object, so there is no key you can construct in one workspace that reads
+# another. Which is why it only pays for itself once a deployment serves more than one —
+# a single-workspace instance gains nothing here and should leave this commented.
+#
+# ⚠️ NOT A CUTOVER ON ITS OWN. Uncommenting creates the namespace and applies the schema;
+# it moves no data and no read. The families move over in their own steps, and until then
+# every read still comes from KV. Do not delete anything from KV on the strength of this
+# block existing.
+#
+# ⚠️ THE MIGRATION TAG IS SHARED. If ROOMS above is already live on `v1`, this needs its
+# own `tag = "v2"` with only the new class in it — tags are applied in order and are never
+# re-run, so amending a tag that has already shipped does nothing at all, silently.
+#
+# [[durable_objects.bindings]]
+# name = "TENANTS"
+# class_name = "TenantStore"
+#
+# [[migrations]]
+# tag = "v1"
+# new_sqlite_classes = ["TenantStore"]
+
+# ── The unit store: drafts that land ────────────────────────────────────────────────────
+#
+# One Durable Object per prototype, holding its main revision, open drafts, landing history
+# and the landing lease. Without it `augur open` answers 501 and nothing else changes.
+# Schema and reasoning: engine/src/unit-object.mjs, design: engine/docs/drafts-that-land.md.
+#
+# [[durable_objects.bindings]]
+# name = "UNITS"
+# class_name = "UnitObject"
+#
+# [[migrations]]
+# tag = "v2"
+# new_sqlite_classes = ["UnitObject"]
+
+[vars]
+# Bundle mode. Without this the worker falls back to assets mode and every published page
+# answers 404 while the site itself looks healthy.
+GV_ASSET_SOURCE = "r2"
+
+# NO tenantId HERE, on purpose. Which workspace a deployment serves already flows
+# deploy.config.json -> build.js -> dist/__config/instance.json -> resolveTenant(), pinned
+# to a single call site by scripts/one-tenant-resolver.mjs. A var would be a second source
+# of truth for the one value the whole isolation model is keyed on.
+#
+# TENANT_HOST_SUFFIX is the exception, and it is not that value — it is the switch between
+# ONE workspace and MANY. Leave it unset and this deployment serves the single workspace
+# its build named, which is what a self-hosted instance is. Set it and the workspace comes
+# from the Host header instead: `TENANT_HOST_SUFFIX = ".example.com"` makes
+# `acme.example.com` the workspace `acme`, and a hostname that names no workspace gets a
+# 404 rather than somebody else's site.
+#
+# RESERVED_LABELS_EXTRA adds this deployment's OWN reserved first labels to the engine's
+# list (src/tenant-host.mjs): names that must never become somebody's workspace address —
+# the fallback origin a certificate product points at, an address you intend to alias to a
+# workspace by operator grant. Comma or space separated; anything that is not a legal label
+# is dropped, never widened. A reserved label resolves nobody literally, which is exactly
+# what lets the alias table answer for it.
+#
+# RESERVED_LABELS_EXTRA = "service"
+#
+# The suffix is LITERAL, which is worth a moment. A dotted suffix puts workspaces one level
+# down and needs a wildcard certificate; a hyphenated one (`-team.example.com`) keeps every
+# workspace on a first-level hostname that a universal certificate already covers. Pick
+# before the first workspace exists — changing it later changes everybody's URL.
+#
+# Set it ONLY together with the TENANTS binding above. Without it there is nowhere for a
+# workspace's own state to live, and the deployment would resolve names it cannot serve.
+#
+# ── TENANT_JURISDICTION — WHERE those workspace objects are, and it is part of their
+# address ──────────────────────────────────────────────────────────────────────────────
+#
+# Leave it unset and workspace objects carry no jurisdictional restriction, which is what
+# every deployment does today. Set it — `TENANT_JURISDICTION = "eu"` — and the platform
+# keeps each workspace's storage inside that jurisdiction and runs it there.
+#
+# ⚠️ IT IS NOT A SETTING ON THE BINDING ABOVE, AND THAT IS THE TRAP. There is no wrangler
+# key for it: the restriction is applied when an object is ADDRESSED, so
+# `idFromName("acme")` and `jurisdiction("eu").idFromName("acme")` are two different ids —
+# two different objects, in two different places, that know nothing about each other. A
+# Durable Object's storage belongs to its id, so this cannot be changed after a workspace
+# exists: it is not a setting you flip, it is an export and a replay into a new object.
+# DECIDE BEFORE THE FIRST WORKSPACE IS CREATED.
+#
+# ⚠️ AND EVERYTHING ELSE THAT ADDRESSES THESE WORKSPACES HAS TO BE TOLD THE SAME VALUE.
+# Anything holding this namespace binding — a provisioning worker, an operator tool —
+# resolves a DIFFERENT object if it applies a different jurisdiction, or none. The symptom
+# is not an error: one side creates a workspace, the other resolves an empty one.
+#
+# The value is handed to the platform as written. It is case-sensitive, `"EU"` is not
+# `"eu"`, and a value the platform does not accept fails EVERY request rather than quietly
+# addressing without a restriction — engine/scripts/wrangler-preflight.mjs refuses the
+# unknown value and the missing binding before the deploy, so the typo costs a re-run
+# rather than an outage.
+#
+# NO SECRETS HERE EITHER — [vars] is plaintext in the repo. These go in with
+# `npx wrangler secret put <NAME> -c wrangler.toml`:
+#
+#   SESSION_SECRET         REQUIRED. Without it sessions degrade to an unkeyed digest,
+#                          silently, and anyone who knows an address can forge a cookie.
+#   RT_SHARED_SECRET       canvas multiplayer; the realtime worker fails closed without it
+#   MAIL_API_KEY           only if this instance sends mail (with MAIL_PROVIDER/MAIL_FROM)
+#   DELETE_DISPATCH_TOKEN  only if prototype-delete / roster-update dispatch to a repo
+#
+# And never PUBLISH_BOOTSTRAP_TOKEN on a live instance: it is compared as a bare string
+# and grants star-scope publish. The preflight refuses a config that names it.
+
+# ── The health cron, once you want to stop paying GitHub to run your canary ─────────────
+#
+# Uncomment and this deployment checks ITSELF on a schedule: whether any workspace is
+# serving a working-tree publish that has outlived its window, whether any is serving page
+# chrome baked by an older engine than the one deployed, and whether the engine you are
+# running is behind the newest RELEASE. The last one is the point — if your own CI is
+# broken, this is the only thing left that will tell you your engine is months old.
+#
+# The report lands at `/__admin/health`, admin-only. That endpoint READS; it never runs the
+# checks, deliberately, so that "the cron is dead" and "nobody opened this page" cannot
+# produce the same green answer. An absent report says so in words.
+#
+# ⚠️ IT DOES NOT ASK WHETHER YOUR SITE IS GATED, and that omission is deliberate rather
+# than missing. A worker probing its own front door is a detector inside the thing it
+# detects: the request re-enters this deployment, so the misconfiguration that would make
+# the platform serve assets before the worker is exactly the condition under which the
+# worker's own answer stops being worth anything. That question stays with
+# `scripts/frontdoor-parity.mjs`, run from OUTSIDE — health.yml step (g), or by hand.
+#
+# ⚠️ ONE WORKSPACE ONLY. A cron has no Host header, so on a deployment that tells
+# workspaces apart by hostname (TENANT_HOST_SUFFIX above) there is no single workspace to
+# check, and it declines rather than picking one. Nothing is lost — that deployment wants a
+# job that holds the workspace list, not a cron that guesses.
+#
+# [triggers]
+# crons = ["23 */6 * * *"]   # every six hours, offset off the hour
+
+# The front door. A route attaches to a hostname that already has a proxied DNS record —
+# which a Pages custom domain is — and takes precedence over Pages on the same hostname,
+# so adding this is the cutover and deleting it is the rollback, in seconds, with no DNS
+# propagation and no certificate reissue. Keep the Pages project and its last deployment
+# until the new front door has been watched for a while.
+#
+# [[routes]]
+# pattern = "<your-site-host>/*"
+# zone_name = "<your-zone>"