PUBLIC_URL comes back, and gen:index takes it as an argument

Removing PUBLIC_URL earlier today was wrong, and the Build section is where it
would have surfaced: gen-index.ts exits 1 without it, so `bun gen:index` fails,
index.gen.html is never written, and `bun start` has no page to serve.

It came out because origin validation was being discontinued — but that was one
of four consumers and the only one that is gone. gen-index needs it for
OpenGraph tags, which crawlers fetch standalone and cannot resolve relative;
task-api-env builds OFFICER_API_HOST from it; and dav/router hard-requires it,
https only, to build an iOS profile.

It is also the one value this machine genuinely cannot derive, which is what
separates it from DATA_PATH and the rest that left today.

gen:index now takes a URL as its first argument, ahead of the environment and
.env: `bun gen:index https://officer.example.com`. Changing the public address is
one command rather than an edit plus a regenerate, and a second address can be
generated for without touching the install's .env.

It also validates now. A relative or scheme-less value substituted silently and
produced OpenGraph tags nothing can resolve — invisible until someone shares a
link and the preview comes back blank.

.env is PORT, PUBLIC_URL, POSTGRES_URL. Verified by running the section; all
three paths through gen:index exercised (absent, valid argument, invalid).

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

.env.example

@@ -2,6 +2,13 @@
 PORT=9000
 POSTGRES_URL="postgres://postgres:password@localhost:5432/officer"
 
+# Where Officer is reached from a browser — the one value the machine cannot derive. Read by
+# `bun gen:index` (OpenGraph tags, which need an absolute URL), the task API host, and the CalDAV iOS
+# profile builder, which additionally requires https.
+#
+# `bun gen:index https://other.example.com` overrides it for one run without editing this file.
+PUBLIC_URL=http://localhost:9000
+
 # ── No secrets live here ───────────────────────────────────────────────────────────────────────
 # JWT_SECRET and VAULT_STORE_KEY were here until 2026-08-13. Every encryption and signing key now
 # lives in the secret store — a 0600 SQLite file at $OFFICER_ROOT/secrets/officer-keys.db, one key
@@ -15,10 +22,6 @@ POSTGRES_URL="postgres://postgres:password@localhost:5432/officer"
 # unreadable, and for the wallet seed that is unrecoverable.
 
 # ── Optional ───────────────────────────────────────────────────────────────────────────────────
-# Where Officer is reached from a browser. Read by the task API host check and the CalDAV iOS profile
-# builder — the latter is the only thing that hard-requires it, and it demands https.
-# PUBLIC_URL=https://officer.example.com
-
 # Guards (CORS origin checks, rate limits, password-strength rules) are ON unless this is set to
 # "dev" or "development". Unset is hardened, which is why officer-setup no longer writes it — set it
 # by hand, on a local machine you trust, to develop. Note that `bun dev` does NOT set it: that script

scripts/gen-index.ts

@@ -16,18 +16,39 @@ const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const template = join(root, 'src/apps/officer-web/index.html');
 const output = join(root, 'src/apps/officer-web/index.gen.html');
 
-// The server reads .env through --env-file, but this script runs standalone.
+// Where the URL comes from, most specific first:
+//
+//   1. the first argument   `bun gen:index https://officer.example.com`
+//   2. PUBLIC_URL in the environment
+//   3. PUBLIC_URL in .env    (this script runs standalone; the server gets it via --env-file)
+//
+// The argument exists so changing the public address is one command rather than an edit plus a
+// regenerate — and so a second address can be generated for without touching the install's own .env.
+const argUrl = process.argv[2]?.trim();
+
 const envPath = join(root, '.env');
-if (!process.env.PUBLIC_URL && existsSync(envPath)) {
+if (!argUrl && !process.env.PUBLIC_URL && existsSync(envPath)) {
   for (const line of (await Bun.file(envPath).text()).split('\n')) {
     const match = line.match(/^\s*PUBLIC_URL\s*=\s*(.*)$/);
     if (match) process.env.PUBLIC_URL = match[1]!.trim().replace(/^["']|["']$/g, '');
   }
 }
 
-const publicUrl = (process.env.PUBLIC_URL ?? '').replace(/\/+$/, '');
+const publicUrl = (argUrl || process.env.PUBLIC_URL || '').replace(/\/+$/, '');
 if (!publicUrl) {
-  console.error('[gen-index] PUBLIC_URL is not set — set it in .env (e.g. https://officer.example.com)');
+  console.error('[gen-index] no public URL. Pass one — `bun gen:index https://officer.example.com` —');
+  console.error('[gen-index] or set PUBLIC_URL in .env.');
+  process.exit(1);
+}
+
+// Caught here rather than left to a crawler: a relative or scheme-less value substitutes without
+// complaint and produces OpenGraph tags nothing can resolve, which is invisible until someone shares a
+// link and the preview is blank.
+try {
+  const parsed = new URL(publicUrl);
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') throw new Error('not http(s)');
+} catch {
+  console.error(`[gen-index] "${publicUrl}" is not an absolute http(s) URL — OpenGraph tags need one.`);
   process.exit(1);
 }
 

scripts/setup/officer-setup.sh

@@ -462,6 +462,7 @@ if ! skip; then
 
   # Read back before anything is asked; existing values become the defaults.
   ENV_PORT="$(env_get PORT)"
+  ENV_PUBLIC_URL="$(env_get PUBLIC_URL)"
 
   if env_exists; then
     echo "     exists — its values are the defaults below"
@@ -473,9 +474,18 @@ if ! skip; then
   echo ""
   ask_required ENV_PORT "Port Officer listens on" "${ENV_PORT:-9000}"
 
+  echo ""
+  echo "     PUBLIC_URL is where Officer is reached from a browser. It is the one"
+  echo "     thing this machine cannot work out for itself, and three things need"
+  echo "     it: the OpenGraph tags baked into the page by 'bun gen:index', the"
+  echo "     host the task API hands to scripts, and the CalDAV profile an iPhone"
+  echo "     installs — that last one requires https."
+  ask_required ENV_PUBLIC_URL "Public URL" "${ENV_PUBLIC_URL:-http://localhost:${ENV_PORT}}"
+
   echo ""
   echo "     to write:"
   echo "       PORT=${ENV_PORT}"
+  echo "       PUBLIC_URL=${ENV_PUBLIC_URL}"
   echo "       POSTGRES_URL=${POSTGRES_URL%%:*}://…"
   echo ""
   echo "     the install root is not written here — the platform derives it as the"

scripts/setup/officer-setup/lib/env.sh

@@ -63,6 +63,9 @@ write_env() {
 
 PORT="${ENV_PORT}"
 
+# Where Officer is reached from a browser. Not derivable — see the section.
+PUBLIC_URL="${ENV_PUBLIC_URL}"
+
 POSTGRES_URL="${POSTGRES_URL}"
 
 ENVF