forgecad 0.9.14 → 0.9.15

package/dist/docs-raw/beta-deployment.md

@@ -1,304 +0,0 @@
-# Beta Deployment — DNS, TLS, and Cloudflare Walkthrough
-
-This is the step-by-step guide for wiring `beta.forgecad.io` on the same Hetzner host as prod, end to end. Every term is defined on first use, and every definition defines the terms it depends on. If you already know a term, skim past it.
-
-**What you'll have at the end**: a separate `beta.forgecad.io` subdomain that points to the same server as prod, terminates TLS the same way, and routes to a separate container (set up later in another doc). Access will be gated via Cloudflare Access with an email allowlist.
-
-**What this doc doesn't cover**: writing `config/deploy.beta.yml`, the Postgres accessory, the scrub script, the CF Access policy itself. Those come after DNS+TLS is working. This doc is strictly the "make the URL resolve securely" layer.
-
-> Short answer: Cloudflare changes are only required when you want the shared
-> hosted beta URL on the real server. For a local browser smoke test of the
-> beta banner/admin flow, run `npm run beta:local` instead — no Cloudflare or
-> Hetzner changes involved.
-
----
-
-## Concepts, defined once
-
-You'll see these terms throughout. Skip to the steps if you already know them.
-
-### DNS (Domain Name System)
-
-The phone book of the internet. You type `forgecad.io` in a browser; DNS translates that name into an IP address like `65.108.210.215`. A **DNS record** is one entry in that phone book: "this name maps to this thing."
-
-### DNS record types (only the ones you need here)
-
-- **A record**: "this name → this IPv4 address." Example: `forgecad.io → 65.108.210.215`.
-- **AAAA record**: Same thing for IPv6. Same server has one of these too, usually.
-- **CNAME record**: "this name is an alias for that other name." Example: `www.forgecad.io → forgecad.io`. When someone asks for `www`, DNS says "go look up `forgecad.io` instead." You can chain them.
-- **TXT record**: Arbitrary text attached to a name. Used for domain verification, email SPF/DKIM, etc. Not used here.
-
-### Subdomain
-
-A name under a main domain. `beta.forgecad.io` is a subdomain of `forgecad.io`. You can add as many subdomains as you want; each gets its own DNS record.
-
-### Cloudflare (CF)
-
-A service that sits in front of your server. DNS for `forgecad.io` is managed in Cloudflare's dashboard. Cloudflare can also proxy traffic — meaning the browser talks to Cloudflare, Cloudflare talks to your server, and Cloudflare handles things like TLS, caching, and WAF rules on the way through.
-
-### "Proxied" vs "DNS only" in Cloudflare
-
-In the Cloudflare DNS dashboard, each record has a toggle called "Proxy status":
-
-- **DNS only** (grey cloud): Cloudflare returns your real server's IP to the browser. Browser talks directly to your server. Cloudflare does nothing else. Your server is exposed on the public internet with its real IP.
-- **Proxied** (orange cloud): Cloudflare returns one of its *own* IPs to the browser. Browser talks to Cloudflare, Cloudflare talks to your server. Cloudflare can do TLS, caching, WAF, and — crucially for us — **Cloudflare Access** (the email-allowlist gate) only works if the record is proxied.
-
-For `beta.forgecad.io`, you want **proxied**. Your prod `forgecad.io` record is already proxied — we'll match that.
-
-### TLS (Transport Layer Security)
-
-The thing that turns `http://` into `https://`. Two jobs: (1) prove the server is really the server (the name on the certificate matches the domain), (2) encrypt the traffic between browser and server so middle-men can't read it.
-
-### Certificate (TLS certificate, SSL certificate — same thing)
-
-A signed document that says "this server is legitimately `forgecad.io`, issued by [some trusted authority]." Browsers check it and either trust it (green padlock) or reject it (big scary warning).
-
-A certificate has:
-- A **subject** — the domain name it covers, e.g. `forgecad.io`.
-- A **SAN list** (Subject Alternative Names) — additional domain names the same certificate covers. `*.forgecad.io` in a SAN covers every single-level subdomain (`beta.forgecad.io`, `api.forgecad.io`, etc).
-- A **validity window** — from/to dates. If it's expired, browsers reject it.
-- A **signature** from the issuer.
-
-### Certificate authority (CA)
-
-Whoever signs certificates. Browsers ship with a list of trusted CAs (Let's Encrypt, DigiCert, etc). Cloudflare acts as a CA for its "Origin Certificates" — see below.
-
-### "Full Strict" mode (Cloudflare)
-
-Cloudflare supports several TLS modes between your server and its edge. You're on **Full Strict**, which means:
-
-- Browser → Cloudflare: TLS, verified by a normal public CA (Cloudflare handles this, you don't manage it).
-- Cloudflare → your Hetzner server: TLS, *and Cloudflare verifies the certificate on your server is valid*.
-
-"Valid" here is lenient — Cloudflare accepts both public CAs and its own Origin CA. It does **not** accept a self-signed cert in Full Strict mode. That's why you have a Cloudflare Origin Certificate on the Hetzner box.
-
-### Origin server
-
-Your actual server. "Origin" is Cloudflare-speak for "the server behind me." In our case: the Hetzner box at `65.108.210.215`.
-
-### Origin Certificate
-
-A TLS certificate issued by Cloudflare specifically for encrypting the Cloudflare-to-origin hop. Two important things:
-
-- It's **only** trusted by Cloudflare — regular browsers reject it. That's fine because browsers never see it directly; only Cloudflare's edge does.
-- Cloudflare will issue it for any domain you own, with any SAN list you request, with validity up to 15 years. You download it once, put it on the origin server, and forget.
-
-Today there's one on the Hetzner box covering `forgecad.io`. We need it to also cover `beta.forgecad.io`.
-
-### SAN (Subject Alternative Name)
-
-The list of extra domain names a certificate covers beyond its primary subject. `*.forgecad.io` is a wildcard SAN — it matches any direct subdomain (`beta`, `api`, `docs`) but NOT double-nested ones (`beta.api.forgecad.io`).
-
-For this setup you want the new origin cert to have:
-- Subject: `forgecad.io`
-- SANs: `forgecad.io`, `*.forgecad.io`
-
-The wildcard means you never have to regenerate the cert when you add the next subdomain.
-
-### kamal-proxy
-
-Kamal's built-in reverse proxy. Lives on the Hetzner server, listens on ports 80 and 443, terminates TLS using the origin certificate you provide, and routes requests to the right container based on the `Host:` header of the incoming request.
-
-So a request for `beta.forgecad.io` hits the kamal-proxy, which then knows "send this to the `forgecad-beta` service container" because that's what `config/deploy.beta.yml` will tell it.
-
-### Reverse proxy
-
-Server-in-front-of-servers. The browser thinks it's talking to one thing (the proxy), but the proxy hands the request off to whichever backend service matches. "Reverse" because the proxy is in front of your *servers* (as opposed to a forward proxy, which is in front of *clients*).
-
-### Host header
-
-Every HTTP request includes `Host: forgecad.io` in its headers. This is how one server can serve many domains — the kamal-proxy reads the `Host:` header and routes accordingly. `beta.forgecad.io` and `forgecad.io` both hit the same IP, but the proxy sends them to different containers based on that header.
-
-### Cloudflare Access
-
-A separate Cloudflare product (in the "Zero Trust" dashboard) that adds an authentication gate in front of proxied domains. Before any request reaches your server, Cloudflare checks whether the user is on your allowlist. If not, they see a login prompt (Google, GitHub, email OTP, etc). If yes, the request proceeds.
-
-Free up to 50 users. Applied per hostname or URL pattern. For `beta.forgecad.io`, you set one policy: "allow these N email addresses; block everyone else."
-
-If you later want one Access app to cover several single-level envs, you can
-use a wildcard application such as `*.forgecad.io`; that matches
-`beta.forgecad.io` and `preview.forgecad.io`, but not `foo.beta.forgecad.io`.
-
-### DNS TTL (Time To Live)
-
-Every DNS record has a TTL — how long resolvers are allowed to cache the answer before re-asking. Cloudflare's default is "Auto" (usually 5 min for proxied records). Matters if you typo the record: you'll be waiting up to TTL for the bad cached answer to expire. Low TTLs = faster propagation, slightly more DNS lookups. Cloudflare handles this well; leave it Auto.
-
----
-
-## Step-by-step
-
-### Step 1 — Add the DNS record
-
-**Goal**: `beta.forgecad.io` resolves to Cloudflare's proxy, which will forward to your Hetzner box.
-
-1. Log in to Cloudflare dashboard → pick the `forgecad.io` zone → click "DNS" in the left sidebar.
-2. Click "Add record".
-3. Fill in:
-   - **Type**: `A`
-   - **Name**: `beta`  (Cloudflare will show this as `beta.forgecad.io` — the root is implied)
-   - **IPv4 address**: `65.108.210.215`  (same as your existing `forgecad.io` A record)
-   - **Proxy status**: toggle to the **orange cloud** (Proxied). If you leave it grey, Cloudflare Access won't work and TLS will go direct instead of through Cloudflare.
-   - **TTL**: leave as Auto.
-4. Click "Save".
-
-If you also have an AAAA (IPv6) record for prod, mirror it: same steps, type AAAA, same IPv6 address, orange cloud. If prod doesn't have AAAA, skip this — IPv4 alone is fine.
-
-**Verify** (from your local machine, a few seconds after saving):
-
-```bash
-dig beta.forgecad.io +short
-```
-
-You should see one of Cloudflare's IPs (something like `104.x.x.x` or `172.67.x.x`), not your Hetzner IP. That's correct — the orange cloud means Cloudflare returns its own IPs, then forwards to yours internally.
-
-If you see your Hetzner IP directly, the record is set to "DNS only" (grey cloud). Go back and toggle it orange.
-
-**Optional future-proofing.** If you expect more single-level same-server
-subdomains later (`preview.forgecad.io`, `demo.forgecad.io`, etc), you can
-also create one proxied wildcard `*` A record to the same Hetzner IP. Exact
-records still win, so `forgecad.io` and `beta` can stay explicit. The wildcard
-removes future DNS edits, but keep the Access note below in mind: wildcard
-Access apps only match the subdomain level you specify.
-
----
-
-### Step 2 — Regenerate the origin certificate with the wildcard SAN
-
-**Goal**: replace the current origin cert on the Hetzner box with one that covers `*.forgecad.io` so `beta.forgecad.io` and any future subdomain "just work".
-
-Today, the origin cert in `.kamal/certs/` (and mirrored into `.kamal/secrets` as `CLOUDFLARE_ORIGIN_CERT` / `CLOUDFLARE_ORIGIN_KEY`) only lists `forgecad.io`. When Cloudflare tries to forward a request for `beta.forgecad.io` to the origin, it presents that hostname in the TLS handshake (via SNI — Server Name Indication), and the origin cert it gets back needs to match. Currently it won't, so you'd see a Cloudflare 526 error ("Invalid SSL certificate").
-
-#### Step 2a — Issue a new origin cert in Cloudflare
-
-1. Cloudflare dashboard → pick `forgecad.io` zone → "SSL/TLS" section in the left sidebar → "Origin Server" tab.
-2. Click "Create Certificate".
-3. Fill in:
-   - **Private key type**: "Let Cloudflare generate a private key and a CSR" (default; easiest).
-   - **Hostnames**: pre-populated with `*.forgecad.io` and `forgecad.io`. Keep both. This is the SAN list on the resulting cert.
-   - **Certificate Validity**: 15 years (max). Rotate it whenever you want; no reason to pick a shorter window.
-4. Click "Create".
-5. Cloudflare shows you the certificate (PEM format, starts with `-----BEGIN CERTIFICATE-----`) and the private key (starts with `-----BEGIN PRIVATE KEY-----`). **The private key is shown only this once.** Copy both into scratch files immediately.
-
-#### Step 2b — Install the new cert on the Hetzner box
-
-There are two paths — pick one based on how you manage the cert today.
-
-**Path A: the cert is stored in `.kamal/certs/` and referenced from `config/deploy.yml` or the kamal-proxy config**
-
-1. On your laptop, replace the old files:
-   ```bash
-   cd /path/to/forgecad-private
-   # back up first
-   cp .kamal/certs/origin.pem     .kamal/certs/origin.pem.bak
-   cp .kamal/certs/origin.key     .kamal/certs/origin.key.bak
-   # paste the new cert + key from Cloudflare into these files
-   ```
-   (Exact filenames may differ in your repo — check `.kamal/certs/` and `config/deploy.yml` to confirm the names kamal-proxy expects.)
-2. These files are gitignored (per the deployment doc). You'll copy them to the server manually in the next step.
-
-**Path B: the cert is stored in `.kamal/secrets` as env vars (`CLOUDFLARE_ORIGIN_CERT` / `CLOUDFLARE_ORIGIN_KEY`)**
-
-1. Edit `.kamal/secrets` (it's a gitignored file you source before running Kamal commands):
-   ```bash
-   export CLOUDFLARE_ORIGIN_CERT="$(cat /tmp/new-origin.pem)"
-   export CLOUDFLARE_ORIGIN_KEY="$(cat /tmp/new-origin.key)"
-   ```
-   Replace the old values entirely. The cert and key are both multi-line — if the file uses `""`-quoted heredocs or `$(cat file)`-style, keep the same format.
-2. This is the most common setup for kamal-proxy. Confirm by grepping:
-   ```bash
-   grep -l CLOUDFLARE_ORIGIN config/deploy.yml .kamal/
-   ```
-
-#### Step 2c — Deploy the cert change
-
-kamal-proxy reads the cert at startup. You need to restart it so it picks up the new one.
-
-```bash
-# from the repo root, with .kamal/secrets sourced
-kamal proxy reboot
-```
-
-This restarts the proxy container in-place. It's a few seconds of downtime — prod clients will see a connection reset and retry. If that's unacceptable, do it at a low-traffic time.
-
-#### Step 2d — Verify
-
-Three checks, from your laptop:
-
-1. Prod still works (didn't break anything):
-   ```bash
-   curl -I https://forgecad.io
-   ```
-   Should return `200 OK` (or `301` for the marketing redirect) without any TLS error.
-
-2. The cert now covers `*.forgecad.io`:
-   ```bash
-   openssl s_client -servername beta.forgecad.io -connect 65.108.210.215:443 < /dev/null 2>/dev/null | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"
-   ```
-   You should see a line listing both `forgecad.io` and `*.forgecad.io`. This bypasses Cloudflare and talks directly to your origin, verifying that the *origin* is presenting the right cert.
-
-3. End-to-end through Cloudflare:
-   ```bash
-   curl -I https://beta.forgecad.io
-   ```
-   Right now this will return a Cloudflare error page (probably 521 "web server is down") because there's no container listening on the `beta.forgecad.io` host yet. **That's the expected result at this stage** — it proves TLS and DNS are working (no 526 "Invalid SSL certificate"), and the only thing missing is the beta container. That's the next doc.
-
----
-
-### Step 3 — Set up Cloudflare Access (the email gate)
-
-**Goal**: only allowlisted emails can reach `beta.forgecad.io`; everyone else gets bounced at Cloudflare's edge before any request touches your server.
-
-1. Cloudflare dashboard → click your profile icon (top-right) → go to "Zero Trust" (separate dashboard from the main one). First time only: Cloudflare will ask you to pick a team name — this is a URL slug for your auth pages (e.g. `forgecad` → `forgecad.cloudflareaccess.com`). Once. Picky.
-2. In Zero Trust → "Access" → "Applications" → "Add an application" → "Self-hosted".
-3. Fill in:
-   - **Application name**: `ForgeCAD Beta`
-   - **Session duration**: 24 hours (testers re-auth daily; bump if annoying).
-   - **Application domain**: `beta.forgecad.io`
-4. Click "Next".
-5. On the policies page:
-   - **Policy name**: `Beta testers`
-   - **Action**: `Allow`
-   - **Configure rules** → Include → "Emails" → add your email, plus any tester emails, one per line. You can also use "Emails ending in" for a domain match (e.g. `@forgecad.io`), but for a small tester list, explicit emails is clearer.
-6. Under the same application, leave identity providers as the defaults — Cloudflare's one-time PIN (emails a code) is on by default, which is what you want for testers without Google/GitHub at your org. If you want them to log in with Google, enable the Google identity provider in Zero Trust → Settings → Authentication first.
-7. Click "Next" through CORS / cookie / advanced settings (defaults are fine). Click "Add application".
-
-**Verify**:
-
-- Open an incognito window → `https://beta.forgecad.io`. You should see Cloudflare's login page, *not* a 521 error. Enter your email → get a one-time PIN → paste it → you'll then see the 521 (because no container yet). That 521 is the good one — it means you authenticated, and you're now talking to the (empty) origin.
-- Open another incognito window → try to access with a non-allowlisted email → it should refuse access with a "policy denied" message.
-
----
-
-## Checkpoint — what you have now
-
-- `beta.forgecad.io` resolves to Cloudflare, proxied.
-- TLS works end-to-end: browser → Cloudflare (valid public cert) → Hetzner (valid origin cert covering `*.forgecad.io`).
-- Cloudflare Access enforces the email allowlist.
-- No container is listening yet, so every authenticated request gets a 521 from Cloudflare. That's the clean "ready for the app" state.
-
-## What's next
-
-The remaining setup — writing `config/deploy.beta.yml`, the beta Postgres accessory, the scrub script, and the first manual `kamal deploy -c config/deploy.beta.yml` — doesn't touch DNS or TLS and is covered separately. Ask me to scaffold those when you've finished the steps above.
-
----
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---------|--------------|-----|
-| `dig beta.forgecad.io` returns your Hetzner IP, not a CF IP | DNS record is "DNS only" (grey cloud) | Toggle to Proxied (orange) |
-| `curl https://beta.forgecad.io` → 526 Invalid SSL | Origin cert doesn't cover `beta.forgecad.io` | Regenerate with `*.forgecad.io` SAN (Step 2) |
-| `curl https://beta.forgecad.io` → 521 Web server is down | No container listening on that Host | Expected until the beta app is deployed. If it persists after deploy, check kamal-proxy is routing `beta.forgecad.io` to the beta service. |
-| `curl https://beta.forgecad.io` → 1000 "DNS points to prohibited IP" | The DNS record points to a Cloudflare IP instead of the origin | You typo'd — an A record should have your Hetzner IP, not a Cloudflare IP |
-| Cloudflare login loop (keeps asking for PIN) | Session cookie domain mismatch | In Zero Trust → Access → your app → Settings, make sure "Application domain" is exactly `beta.forgecad.io`, not `https://beta.forgecad.io` |
-| TLS works but `*.forgecad.io` cert shows expired | Origin cert expired (15 years is the default, so unlikely, but possible if old) | Regenerate per Step 2 |
-
-## Glossary recap
-
-- **Zone** — Cloudflare's word for a managed domain. `forgecad.io` is one zone.
-- **Edge** — Cloudflare's globally-distributed servers that the browser talks to when a record is proxied.
-- **Origin** — your actual server (Hetzner box).
-- **CN** (Common Name) — older term for the "primary" domain on a certificate, now largely superseded by SANs.
-- **Wildcard cert** — a cert whose SAN includes `*.forgecad.io`. Covers any direct subdomain.
-- **SNI** (Server Name Indication) — field in the TLS handshake where the client tells the server which hostname it wants a cert for. Lets one IP serve many TLS hostnames.
-- **521, 526** — Cloudflare-specific HTTP status codes. 521 = origin unreachable; 526 = origin TLS cert invalid; 522 = origin timeout. Useful because they tell you *where* in the chain the failure is.

package/dist/docs-raw/beta-operations.md

@@ -1,325 +0,0 @@
----
----
-
-# ForgeCAD Beta — Operations Runbook
-
-The beta environment at [beta.forgecad.io](https://beta.forgecad.io) is the
-staging ground every change passes through before production. It runs on the
-same Hetzner VPS as prod, fully isolated at the process level.
-
-> **Isolation invariants.** Beta has its own Postgres container, its own
-> volume, its own JWT secret, its own file-storage volume, and its own
-> Kamal secrets file. A failure in beta — including a runaway migration,
-> a rogue query, or a filesystem fill-up — cannot affect prod.
-
-For the DNS, TLS and Cloudflare Access side of the setup, see
-[beta-deployment.md](beta-deployment.md). That document ends where this one
-starts — with `curl https://beta.forgecad.io` returning a 521 because no
-container is listening yet.
-
-## Preferred admin commands
-
-Use the beta operator wrapper instead of memorizing raw `kamal` flags:
-
-```bash
-npm run beta:setup      # first-time setup
-npm run beta:deploy     # routine deploy
-npm run beta:smoke      # deploy, then open beta in the browser
-npm run beta:logs       # tail logs
-npm run beta:refresh    # prod -> beta scrubbed DB refresh (auto local/remote)
-npm run beta:db         # interactive psql
-npm run beta:shell      # app container shell
-npm run beta:local      # local beta-like browser smoke test
-```
-
-All of these are thin wrappers around `scripts/beta.sh` /
-`scripts/beta-local.sh`. They exist for operator ergonomics only; regular
-ForgeCAD users never see them in the public product CLI.
-
-Production has the matching `npm run prod:*` shortcuts in `scripts/prod.sh`
-for the same reason: muscle memory should be environment-prefixed, even though
-production is normally deployed by GitHub Actions on `mainline`.
-
-**Useful overrides**:
-- `FORGE_BETA_DEPLOY_CONFIG` — alternate Kamal config path
-- `FORGE_BETA_DESTINATION` — alternate Kamal destination name (default `beta`)
-- `FORGE_BETA_URL` — hosted beta URL to open after `beta:smoke`
-- `FORGE_BETA_SSH_HOST` — SSH target for remote refresh (default `hetzner`)
-- `FORGE_BETA_REFRESH_MODE=local|remote|auto` — force refresh behavior
-
----
-
-## First-time setup
-
-Run this ONCE to stand beta up. After this, routine deploys are a single
-`npm run beta:deploy` (or `kamal deploy -d beta`).
-
-1. **Finish the DNS + TLS + Cloudflare Access walkthrough**
-   ([beta-deployment.md](beta-deployment.md)) — `curl https://beta.forgecad.io`
-   should return 521, not NXDOMAIN / 526 / anything else. If it's not 521,
-   stop and fix DNS/TLS before continuing.
-
-2. **Populate `.kamal/secrets.beta`** from the template:
-
-   ```bash
-   cp .kamal/secrets.beta.example .kamal/secrets.beta
-   # Edit .kamal/secrets.beta and replace every REPLACE_WITH_* placeholder.
-   # Generate fresh values — do not reuse prod credentials.
-   ```
-
-   Every value MUST differ from `.kamal/secrets`. In particular:
-   - `FORGE_JWT_SECRET` — regenerate with `openssl rand -base64 32`.
-   - `POSTGRES_PASSWORD` — regenerate with `openssl rand -base64 24`.
-   - `FORGE_DB_URL` — host is `forgecad-postgres-beta`, DB is `forgecad_beta`.
-
-3. **Stand up beta with Kamal**:
-
-   ```bash
-   npm run beta:setup
-   ```
-
-   This builds the Docker image (remotely, on the VPS), pushes to GHCR,
-   creates the `forgecad-postgres-beta` accessory with its own
-   `kamal-postgresql-beta-data` volume, creates the `forgecad-project-data-beta`
-   volume, starts the web container, registers `beta.forgecad.io` with
-   kamal-proxy, and runs migrations.
-
-4. **Verify**:
-
-   ```bash
-   curl -s https://beta.forgecad.io/api/health | jq
-   # Expect: { "status": "ok", "environment": "beta", ... }
-   ```
-
-   Open `https://beta.forgecad.io` in a browser. You should see the orange
-   **BETA** banner across the top on every route.
-
-5. **Load real data** — see [Data refresh](#data-refresh) below.
-
-6. **Grant yourself admin on beta** — by default the beta DB has no users
-   until step 5 loads the prod dump. The scrub's admin allowlist at the top
-   of `scripts/beta-scrub.sql` re-grants admin to listed emails.
-
----
-
-## Routine deploys
-
-Beta deploys from whatever commit is about to go to prod next — typically
-`mainline` HEAD. There is no `beta` branch. Under the hood, the wrapper targets
-Kamal destination `beta`, so beta reads its own secrets file
-`.kamal/secrets.beta` rather than the prod `.kamal/secrets`.
-
-```bash
-git checkout mainline && git pull
-npm run beta:deploy    # rolling update, zero downtime
-npm run beta:smoke     # same deploy, then open beta in the browser
-npm run beta:logs      # tail logs
-```
-
-Rollback:
-
-```bash
-npm run beta:rollback
-```
-
-No GitHub Actions are wired up for beta — it's manual, by design. If you
-want beta auto-deploy later, add a separate workflow file; don't piggy-back
-on the prod deploy workflow.
-
----
-
-## Data refresh
-
-Beta should hold a scrubbed copy of prod data so the admin dashboard,
-quota logic, shared-link resolution and audit log all exercise realistic
-shapes. Refresh whenever that data is stale (typically monthly, or
-before a big feature test that depends on prod-like data).
-
-```bash
-# Auto mode: runs locally if you're already on the Hetzner host, otherwise
-# streams the refresh + scrub payload over SSH.
-npm run beta:refresh
-```
-
-Advanced/manual equivalents:
-- On the Hetzner host: `bash scripts/beta-refresh.sh`
-- From your laptop, forced remote mode: `FORGE_BETA_REFRESH_MODE=remote npm run beta:refresh`
-
-What the refresh does, step by step:
-
-1. `pg_dump` the prod DB inside the `forgecad-postgres` container.
-2. Stream the dump into the `forgecad-beta-postgres-beta` container.
-3. `DROP DATABASE forgecad_beta WITH (FORCE)` + recreate.
-4. `pg_restore` the dump into the fresh beta DB.
-5. Run `scripts/beta-scrub.sql`:
-   - Rewrites `users.email` to `user-<short>@beta.local` (non-deliverable).
-   - Rewrites `users.name` to `Beta User <short>`.
-   - Nulls `users.password_hash` and `users.avatar_url`.
-   - Truncates `refresh_tokens`, `api_tokens`, `email_verification_tokens`,
-     `password_reset_tokens`, `accounts`.
-   - Nulls audit-log IP addresses, Stripe IDs on subscriptions.
-   - Re-grants `admin` to the hardcoded allowlist at the top of the script.
-
-The scrub is idempotent and is guarded by a `current_database() NOT LIKE
-'%beta%'` check — it will refuse to run against prod even if you somehow
-aim it there.
-
-**Important identity behavior after refresh.** Beta copies prod users, then
-anonymizes them. Existing prod users do NOT keep their real email address on
-beta: the scrub rewrites imported emails to `user-<short>@beta.local`, clears
-password hashes, and deletes OAuth account links. That means signing in on beta
-with your real email after a refresh creates a separate beta-native account; it
-does not reconnect you to the imported prod-shaped account. That beta-native
-account is also ephemeral — the next refresh drops and recreates the beta DB
-from prod. This is expected today and is the main trade-off of the scrubbed
-shared-beta setup.
-
-**Adding a tester to the admin allowlist.** Edit the `beta_admin_allowlist`
-VALUES block near the top of `scripts/beta-scrub.sql`. The list uses the
-tester's PROD email (the scrub matches BEFORE rewriting emails). Re-run
-`scripts/beta-refresh.sh`, or just run the scrub again on its own:
-
-```bash
-ssh hetzner 'docker exec -i forgecad-beta-postgres-beta \
-  psql -U $(docker exec forgecad-beta-postgres-beta printenv POSTGRES_USER) \
-       -d forgecad_beta -v ON_ERROR_STOP=1' \
-  < scripts/beta-scrub.sql
-```
-
----
-
-## Accessing the beta DB
-
-```bash
-# Interactive psql against beta
-npm run beta:db
-
-# One-shot query
-kamal accessory exec -d beta postgres-beta \
-  "psql -U \$POSTGRES_USER -d forgecad_beta -c 'SELECT count(*) FROM users;'"
-
-# Shell into the beta web container
-npm run beta:shell
-```
-
-## Local smoke test
-
-If you just want to open a browser and sanity-check the beta banner, admin
-page, auth flows, and general feel without touching Cloudflare or the Hetzner
-host:
-
-```bash
-npm run beta:local
-```
-
-That starts the hosted frontend locally, runs the local Fastify server with
-`FORGE_ENVIRONMENT=beta`, opens the browser, and leaves prod/beta infra
-untouched.
-
----
-
-## OAuth on beta
-
-Beta is **password-only** by default. The `GITHUB_CLIENT_ID`,
-`GITHUB_CLIENT_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` env
-vars are intentionally not listed in `config/deploy.beta.yml`, so the
-server's OAuth handlers return unconfigured-provider errors.
-
-**Why not reuse prod OAuth apps?** Prod's OAuth apps have redirect URIs
-pinned to `https://forgecad.io/auth/callback/*`. Either we'd have to add
-`https://beta.forgecad.io/auth/callback/*` to the same app (which
-conflates beta and prod consent screens, and means a compromised beta
-secret can impersonate prod callbacks), or beta gets its own apps.
-
-**Trade-off of password-only**: testers can't click "Sign in with Google"
-on beta. They either (a) already have a password-login account on prod —
-which the scrub copies over with `password_hash = NULL`, so they'd need
-the operator to reset their password via the admin panel, or (b) register
-fresh on beta. That fresh beta-only account is separate from the imported
-scrubbed account and disappears on the next `npm run beta:refresh`. Low cost
-for the isolation win.
-
-**To enable OAuth on beta later**:
-
-1. Create a **new** GitHub OAuth App. Set the callback URL to
-   `https://beta.forgecad.io/auth/callback/github`. Do NOT add this
-   callback to the prod app.
-2. Create a **new** Google OAuth client (OAuth 2.0 client ID, web app).
-   Authorised redirect URI `https://beta.forgecad.io/auth/callback/google`.
-
-   Use Google Auth Platform → Clients in the Google Cloud Console for this.
-   Do not use `gcloud iam oauth-clients`; that command creates IAM/IAP OAuth
-   application resources, not the normal Google Sign-In web client that
-   ForgeCAD's `/auth/callback/google` flow expects.
-3. Add the four secrets to `.kamal/secrets.beta`:
-
-   ```bash
-   GITHUB_CLIENT_ID=...
-   GITHUB_CLIENT_SECRET=...
-   GOOGLE_CLIENT_ID=...
-   GOOGLE_CLIENT_SECRET=...
-   ```
-4. Add them to `env.secret:` in `config/deploy.beta.yml`.
-5. `kamal deploy -d beta`.
-
----
-
-## Adding a new tester
-
-Access to `beta.forgecad.io` is gated by Cloudflare Access (email
-allowlist). Adding a tester is a two-step process:
-
-1. Add their email to the Cloudflare Access policy. See the "Adding a
-   tester" section of [beta-deployment.md](beta-deployment.md) — that
-   doc owns the CF Access console walkthrough.
-2. If they need admin rights on beta (i.e. access to `/admin`):
-   - Add their prod email to the `beta_admin_allowlist` block in
-     `scripts/beta-scrub.sql`, OR
-   - Run `UPDATE users SET role = 'admin' WHERE email = 'user-<short>@beta.local';`
-     directly (non-persistent — gets reset on the next data refresh).
-
----
-
-## Adding beta compute later
-
-The geometry compute backend (`Dockerfile.backend`) is NOT deployed to beta
-initially. `FORGE_COMPUTE_URL=http://unavailable.local:9999` in
-`config/deploy.beta.yml` means Pro compute requests on beta fail fast
-rather than silently routing through to prod's backend container.
-
-When a test case genuinely needs the compute path on beta:
-
-1. Create `config/deploy.backend.beta.yml`, cloned from
-   `config/deploy.backend.yml`:
-   - `service: forgecad-backend-beta`
-   - `network-alias: forgecad-backend-beta`
-   - `host: backend-beta.internal` (internal only, not Cloudflare-routed)
-2. Update `config/deploy.beta.yml` env:
-   `FORGE_COMPUTE_URL: http://forgecad-backend-beta:4510`.
-3. `kamal deploy -c config/deploy.backend.beta.yml`, then
-   `kamal deploy -d beta`.
-
-Keep the backend deploy config symmetrical with its web counterpart —
-separate service name, separate network alias, separate secrets.
-
----
-
-## Debugging connectivity
-
-| Symptom                                       | Likely cause                                        |
-|-----------------------------------------------|-----------------------------------------------------|
-| `curl beta.forgecad.io` → `NXDOMAIN`          | DNS not propagated yet; see [beta-deployment.md](beta-deployment.md) |
-| `curl beta.forgecad.io` → 521                 | Web container not running — `kamal deploy -d beta` |
-| `curl beta.forgecad.io` → 526                 | Origin cert missing `beta.forgecad.io` SAN; see [beta-deployment.md](beta-deployment.md) § "Regenerating the origin cert" |
-| 502 / `no server available`                   | kamal-proxy has the route but the container is failing healthchecks. `kamal app logs -d beta`. |
-| App loads but no BETA banner                  | `FORGE_ENVIRONMENT` missing from the container env. Check `kamal app exec -d beta "env \| grep FORGE_ENVIRONMENT"`. |
-| BETA banner shown on `forgecad.io` (prod)     | **Stop and investigate immediately** — this means prod is running beta env vars. Check `kamal app exec "env \| grep FORGE_ENVIRONMENT"` on prod. |
-| Admin page shows `environment: production` on beta | Same as above — env var mis-set. |
-
----
-
-## Related docs
-
-- [beta-deployment.md](beta-deployment.md) — DNS, TLS, Cloudflare Access.
-- [deployment.md](deployment.md) — overall deployment architecture.
-- [runbook.md](runbook.md) — day-to-day operations (prod).