create-op-node 0.0.1 → 0.2.0

package/dist/cli.js

@@ -1,12 +1,21 @@
 #!/usr/bin/env node
 import { Command, Option } from 'commander';
-import pc from 'picocolors';
-import * as p from '@clack/prompts';
+import pc2 from 'picocolors';
+import * as p3 from '@clack/prompts';
+import { execa } from 'execa';
+import { Octokit } from '@octokit/rest';
+import { randomBytes } from 'crypto';
+import { join, resolve, dirname } from 'path';
+import { mkdir, writeFile, access, rm, chmod } from 'fs/promises';
+import { homedir } from 'os';
+import { readFileSync } from 'fs';
+import * as tls from 'tls';
+import { Validator } from '@cfworker/json-schema';
 
 // src/lib/cloudflare.ts
 var CF_API = "https://api.cloudflare.com/client/v4";
-async function get(token, path) {
-  const res = await fetch(`${CF_API}${path}`, {
+async function get(token, path, fetchImpl = fetch) {
+  const res = await fetchImpl(`${CF_API}${path}`, {
     headers: { Authorization: `Bearer ${token}` }
   });
   let body = null;
@@ -55,190 +64,3624 @@ async function probeCloudflareToken(input) {
   }
   return { ok: issues.length === 0, issues };
 }
+async function tunnelStatus(input) {
+  const fetchImpl = input.fetchImpl ?? fetch;
+  try {
+    const res = await get(
+      input.token,
+      `/accounts/${input.accountId}/cfd_tunnel/${input.tunnelId}`,
+      fetchImpl
+    );
+    if (res.status !== 200) {
+      return {
+        ok: false,
+        reason: `tunnel lookup failed (HTTP ${res.status}): ${shortError(res.body)}`
+      };
+    }
+    const env = res.body;
+    const status = env.result?.status ?? "<no status>";
+    const connections = env.result?.connections?.length ?? 0;
+    return { ok: true, connections, status };
+  } catch (err) {
+    return { ok: false, reason: `tunnel lookup threw: ${err.message}` };
+  }
+}
+
+// src/lib/tfc.ts
+var TFC_API = "https://app.terraform.io/api/v2";
+var ORG_SLUG_RE = /^[A-Za-z0-9_-]{1,40}$/;
+function isValidTfcOrgSlug(slug) {
+  return ORG_SLUG_RE.test(slug);
+}
+function authHeaders(token) {
+  return {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/vnd.api+json"
+  };
+}
+async function getJson(token, path) {
+  const res = await fetch(`${TFC_API}${path}`, { headers: authHeaders(token) });
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+  }
+  return { status: res.status, body };
+}
+async function probeTfcToken(input) {
+  const issues = [];
+  if (!isValidTfcOrgSlug(input.organization)) {
+    issues.push(
+      `Organization "${input.organization}" isn't a valid TFC slug (letters, digits, hyphens, underscores; up to 40 chars).`
+    );
+    return { ok: false, issues };
+  }
+  const account = await getJson(input.token, "/account/details");
+  if (account.status !== 200) {
+    issues.push(
+      `TFC token invalid (HTTP ${account.status}). Regenerate at https://app.terraform.io/app/settings/tokens.`
+    );
+    return { ok: false, issues };
+  }
+  const userName = extractUserName(account.body);
+  const org = await getJson(
+    input.token,
+    `/organizations/${encodeURIComponent(input.organization)}`
+  );
+  if (org.status === 404) {
+    issues.push(
+      `TFC organization "${input.organization}" not found, or this token lacks access. Check the org slug at https://app.terraform.io.`
+    );
+  } else if (org.status === 401 || org.status === 403) {
+    issues.push(
+      `TFC token doesn't have permission to access org "${input.organization}".`
+    );
+  } else if (org.status !== 200) {
+    issues.push(`TFC org probe returned HTTP ${org.status}.`);
+  }
+  return {
+    ok: issues.length === 0,
+    issues,
+    ...userName ? { userName } : {}
+  };
+}
+function extractUserName(body) {
+  if (typeof body === "object" && body !== null && "data" in body && typeof body.data === "object") {
+    const data = body.data;
+    return data.attributes?.username;
+  }
+  return void 0;
+}
+async function findWorkspace(input) {
+  if (!isValidTfcOrgSlug(input.organization)) return null;
+  const tagFilter = encodeURIComponent(input.tags.join(","));
+  const res = await getJson(
+    input.token,
+    `/organizations/${encodeURIComponent(input.organization)}/workspaces?filter[tagged]=${tagFilter}&page[size]=100`
+  );
+  if (res.status !== 200) return null;
+  const items = extractWorkspaceList(res.body);
+  if (items.length === 0) return null;
+  const match = input.name ? items.find((w) => w.name === input.name) : items[0];
+  return match ?? null;
+}
+function extractWorkspaceList(body) {
+  if (typeof body !== "object" || body === null || !("data" in body) || !Array.isArray(body.data)) {
+    return [];
+  }
+  const data = body.data;
+  return data.map((w) => ({
+    id: w.id,
+    name: w.attributes?.name ?? "",
+    currentRunId: w.relationships?.["current-run"]?.data?.id ?? null
+  }));
+}
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "applied",
+  "errored",
+  "canceled",
+  "discarded",
+  "policy_soft_failed",
+  "force_canceled"
+]);
+async function getRunStatus(auth, runId) {
+  const res = await getJson(auth.token, `/runs/${encodeURIComponent(runId)}`);
+  if (res.status !== 200) return null;
+  const body = res.body;
+  const id = body.data?.id;
+  const status = body.data?.attributes?.status;
+  if (!id || !status) return null;
+  return {
+    id,
+    status,
+    finished: TERMINAL_STATUSES.has(status),
+    succeeded: status === "applied"
+  };
+}
+async function fetchOutput(auth, workspaceId, outputName) {
+  const res = await getJson(
+    auth.token,
+    `/workspaces/${encodeURIComponent(workspaceId)}/current-state-version-outputs`
+  );
+  if (res.status !== 200) return null;
+  const body = res.body;
+  const match = body.data?.find((o) => o.attributes?.name === outputName);
+  if (!match) return null;
+  const value = match.attributes?.value;
+  return typeof value === "string" ? value : null;
+}
+async function safeExeca(cmd, args, options) {
+  try {
+    const result2 = await execa(cmd, args, { reject: false, ...options });
+    return {
+      exitCode: result2.exitCode,
+      stdout: result2.stdout,
+      stderr: result2.stderr
+    };
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT" || e.code === "ENOTDIR") return null;
+    throw err;
+  }
+}
+
+// src/lib/onepassword.ts
+async function detectOp() {
+  const version = await safeExeca("op", ["--version"]);
+  if (version === null) {
+    return { installed: false, signedIn: false };
+  }
+  const installed = true;
+  const whoami = await safeExeca("op", ["whoami", "--format=json"]);
+  if (whoami === null || whoami.exitCode !== 0) {
+    return { installed, signedIn: false };
+  }
+  let email;
+  try {
+    const parsed = JSON.parse(whoami.stdout);
+    email = parsed.email;
+  } catch {
+  }
+  return {
+    installed,
+    signedIn: true,
+    ...email ? { email } : {}
+  };
+}
+async function saveSecretToOp(input) {
+  const vaultArg = input.vault ? ["--vault", input.vault] : [];
+  const existing = await safeExeca("op", ["item", "get", input.title, ...vaultArg, "--format=json"]);
+  if (existing === null) {
+    return {
+      written: false,
+      alreadyExisted: false,
+      reason: "`op` CLI not installed"
+    };
+  }
+  if (existing.exitCode === 0) {
+    if (!input.overwrite) {
+      return { written: false, alreadyExisted: true };
+    }
+    const edit = await safeExeca(
+      "op",
+      ["item", "edit", input.title, ...vaultArg, `notesPlain=${input.value}`]
+    );
+    if (edit === null || edit.exitCode !== 0) {
+      return {
+        written: false,
+        alreadyExisted: true,
+        reason: `op item edit failed: ${edit?.stderr || edit?.stdout || "`op` not installed"}`
+      };
+    }
+    return { written: true, alreadyExisted: true };
+  }
+  const create = await safeExeca("op", [
+    "item",
+    "create",
+    "--category",
+    "Secure Note",
+    "--title",
+    input.title,
+    ...vaultArg,
+    `notesPlain=${input.value}`
+  ]);
+  if (create === null || create.exitCode !== 0) {
+    return {
+      written: false,
+      alreadyExisted: false,
+      reason: `op item create failed: ${create?.stderr || create?.stdout || "`op` not installed"}`
+    };
+  }
+  return { written: true, alreadyExisted: false };
+}
+async function readSecretFromOp(input) {
+  const vaultArg = input.vault ? ["--vault", input.vault] : [];
+  const res = await safeExeca(
+    "op",
+    ["item", "get", input.title, ...vaultArg, "--fields", "notesPlain", "--reveal"]
+  );
+  if (res === null || res.exitCode !== 0) return null;
+  const value = res.stdout.trim();
+  return value.length > 0 ? value : null;
+}
+function unwrap(value) {
+  if (p3.isCancel(value)) {
+    p3.cancel("Cancelled.");
+    process.exit(0);
+  }
+  return value;
+}
+var _client = null;
+var _clientToken = null;
+function client(token) {
+  if (_client && _clientToken === token) return _client;
+  _client = new Octokit({ auth: token });
+  _clientToken = token;
+  return _client;
+}
+async function createRepoFromTemplate(input) {
+  const [templateOwner, templateRepo] = input.template.split("/");
+  if (!templateOwner || !templateRepo) {
+    throw new Error(`Bad template spec "${input.template}" \u2014 expected <owner>/<repo>`);
+  }
+  const res = await client(input.token).request(
+    "POST /repos/{template_owner}/{template_repo}/generate",
+    {
+      template_owner: templateOwner,
+      template_repo: templateRepo,
+      owner: input.owner,
+      name: input.name,
+      private: input.private ?? false,
+      include_all_branches: input.includeAllBranches ?? false,
+      ...input.description ? { description: input.description } : {}
+    }
+  );
+  return {
+    fullName: res.data.full_name,
+    htmlUrl: res.data.html_url,
+    defaultBranch: res.data.default_branch ?? "main"
+  };
+}
+async function setRepoSecret(input) {
+  const res = await safeExeca(
+    "gh",
+    ["secret", "set", input.name, "--repo", input.repo, "--body", "-"],
+    { input: input.value }
+  );
+  if (res === null) {
+    return {
+      written: false,
+      reason: "`gh` CLI not installed \u2014 install from https://cli.github.com or seed secrets manually"
+    };
+  }
+  if (res.exitCode !== 0) {
+    return {
+      written: false,
+      reason: `gh secret set failed (${res.exitCode ?? "signal"}): ${res.stderr || res.stdout}`
+    };
+  }
+  return { written: true };
+}
+async function commitFile(input) {
+  const [owner, repo] = input.repo.split("/");
+  if (!owner || !repo) {
+    throw new Error(`Bad repo "${input.repo}" \u2014 expected <owner>/<repo>`);
+  }
+  const octokit = client(input.token);
+  let existingSha;
+  try {
+    const existing = await octokit.repos.getContent({
+      owner,
+      repo,
+      path: input.path,
+      ref: input.branch
+    });
+    if (!Array.isArray(existing.data) && existing.data.type === "file") {
+      existingSha = existing.data.sha;
+    }
+  } catch (err) {
+    if (!is404(err)) throw err;
+  }
+  const res = await octokit.repos.createOrUpdateFileContents({
+    owner,
+    repo,
+    path: input.path,
+    branch: input.branch,
+    message: input.message,
+    content: Buffer.from(input.content, "utf8").toString("base64"),
+    ...existingSha ? { sha: existingSha } : {}
+  });
+  return {
+    commitSha: res.data.commit.sha ?? "",
+    contentSha: res.data.content?.sha ?? ""
+  };
+}
+function is404(err) {
+  return typeof err === "object" && err !== null && "status" in err && err.status === 404;
+}
+async function createBranch(input) {
+  const [owner, repo] = input.repo.split("/");
+  if (!owner || !repo) {
+    throw new Error(`Bad repo "${input.repo}" \u2014 expected <owner>/<repo>`);
+  }
+  const octokit = client(input.token);
+  const ref = await octokit.git.getRef({
+    owner,
+    repo,
+    ref: `heads/${input.fromBranch}`
+  });
+  await octokit.git.createRef({
+    owner,
+    repo,
+    ref: `refs/heads/${input.branch}`,
+    sha: ref.data.object.sha
+  });
+}
+async function openPullRequest(input) {
+  const [owner, repo] = input.repo.split("/");
+  if (!owner || !repo) {
+    throw new Error(`Bad repo "${input.repo}" \u2014 expected <owner>/<repo>`);
+  }
+  const octokit = client(input.token);
+  const res = await octokit.pulls.create({
+    owner,
+    repo,
+    head: input.head,
+    base: input.base,
+    title: input.title,
+    body: input.body
+  });
+  return { number: res.data.number, htmlUrl: res.data.html_url };
+}
+function generatePgsodiumRootKey() {
+  return randomBytes(32).toString("hex");
+}
+function renderProdTfvars(input) {
+  const project = input.project ?? "opuspopuli";
+  const api = input.apiSubdomain ?? "api";
+  const app = input.appSubdomain ?? "app";
+  const port = input.tunnelApiPort ?? 8080;
+  const r2 = input.r2LocationHint ?? "WNAM";
+  return `# =============================================================================
+# Production environment \u2014 generated by create-op-node init
+# =============================================================================
+# Region-specific values for the OpusPopuli/opuspopuli-node template's
+# infra/cloudflare/ Terraform. Edit by hand to tweak.
+
+project = ${JSON.stringify(project)}
+
+domain_name = ${JSON.stringify(input.domain)}
+
+api_subdomain = ${JSON.stringify(api)}
+app_subdomain = ${JSON.stringify(app)}
+
+tunnel_api_port = ${port}
+
+r2_location_hint = ${JSON.stringify(r2)}
+
+enable_tunnel   = true
+enable_frontend = true
+enable_r2       = true
+`;
+}
+
+// src/lib/polling.ts
+var DEFAULT_BUDGETS = {
+  discoveryMs: 60 * 1e3,
+  runMs: 10 * 60 * 1e3,
+  pollMs: 10 * 1e3
+};
+var realDeps = {
+  findWorkspace,
+  getRunStatus,
+  fetchOutput,
+  sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
+  now: () => Date.now()
+};
+async function waitForApply(input, budgets = DEFAULT_BUDGETS, deps = realDeps) {
+  let runId = input.runId;
+  if (!runId) {
+    deps.onProgress?.("discovery");
+    const discoveryStart = deps.now();
+    while (deps.now() - discoveryStart < budgets.discoveryMs) {
+      await deps.sleep(budgets.pollMs);
+      const ws = await deps.findWorkspace({
+        token: input.token,
+        organization: input.organization,
+        tags: input.workspaceTags
+      });
+      if (ws?.currentRunId) {
+        runId = ws.currentRunId;
+        break;
+      }
+    }
+    if (!runId) return { kind: "no-run-started" };
+  }
+  deps.onProgress?.("run");
+  const runStart = deps.now();
+  while (deps.now() - runStart < budgets.runMs) {
+    const r = await deps.getRunStatus(
+      { token: input.token, organization: input.organization },
+      runId
+    );
+    if (r?.finished) {
+      if (!r.succeeded) return { kind: "run-failed", status: r.status };
+      deps.onProgress?.("fetching");
+      const value = await deps.fetchOutput(
+        { token: input.token, organization: input.organization },
+        input.workspaceId,
+        input.outputName
+      );
+      return value !== null ? { kind: "success", value } : { kind: "output-missing" };
+    }
+    await deps.sleep(budgets.pollMs);
+  }
+  return { kind: "timeout" };
+}
 
 // src/commands/init.ts
+async function ghTokenFromCli() {
+  const r = await safeExeca("gh", ["auth", "token"]);
+  if (r === null || r.exitCode !== 0) return null;
+  const token = r.stdout.trim();
+  return token.length > 0 ? token : null;
+}
 var initCommand = new Command("init").description(
   "Stand up the node repo + Cloudflare infrastructure for a new region. Run this on your laptop."
+).addOption(new Option("--domain <domain>", "Your registered domain (e.g. example.org)")).addOption(new Option("--region <slug>", "Short label for your region (e.g. us-ca)")).addOption(new Option("--owner <owner>", "GitHub owner for the new node repo").default("OpusPopuli")).addOption(
+  new Option("--template <owner/repo>", "Template repo to clone from").default(
+    "OpusPopuli/opuspopuli-node"
+  )
+).addOption(new Option("--project <name>", "tfvars project prefix").default("opuspopuli")).addOption(new Option("--cf-token <token>", "Cloudflare Account API token").env("CF_TOKEN")).addOption(new Option("--cf-account <id>", "Cloudflare account ID").env("CF_ACCOUNT")).addOption(new Option("--cf-zone <id>", "Cloudflare zone ID for your domain").env("CF_ZONE")).addOption(new Option("--tf-token <token>", "Terraform Cloud user/team token").env("TF_API_TOKEN")).addOption(new Option("--tf-org <org>", "Terraform Cloud organization").env("TF_CLOUD_ORGANIZATION")).addOption(new Option("--gh-token <token>", "GitHub Personal Access Token (else gh CLI)").env("GH_TOKEN")).addOption(new Option("--vault <vault>", "1Password vault for secrets").default("Private")).addOption(
+  new Option(
+    "--overwrite",
+    "Overwrite existing 1Password items (pgsodium key, Tunnel token) on a re-run"
+  ).default(false)
 ).addOption(
-  new Option("--domain <domain>", "Your registered domain (e.g. example.org)")
-).addOption(
-  new Option("--region <slug>", "Short label for your region (e.g. us-ca)")
-).addOption(
-  new Option("--cf-token <token>", "Cloudflare Account API token").env("CF_TOKEN")
-).addOption(
-  new Option("--cf-account <id>", "Cloudflare account ID").env("CF_ACCOUNT")
-).addOption(
-  new Option("--cf-zone <id>", "Cloudflare zone ID for your domain").env("CF_ZONE")
-).addOption(new Option("-y, --yes", "Skip confirmation prompts").default(false)).action(async (opts) => {
-  p.intro(pc.bgCyan(pc.black(" create-op-node ")));
-  p.note(
+  new Option(
+    "--use-existing-repo",
+    "Continue using a previously-created node repo (don't fail on 'already exists')"
+  ).default(false)
+).addOption(new Option("--skip-wait", "Don't poll for Terraform apply; exit after PR open").default(false)).addOption(new Option("-y, --yes", "Skip the final confirmation").default(false)).action(async (opts) => {
+  p3.intro(pc2.bgCyan(pc2.black(" create-op-node init ")));
+  p3.note(
     [
       "This walks you from a sealed Mac Studio + a Cloudflare account to a",
       "live federation node serving traffic at api.<your-domain>.",
       "",
-      pc.dim("Phase 1: laptop side \u2014 Cloudflare, GitHub, Terraform Cloud."),
-      pc.dim("Phase 2: Studio side \u2014 run `create-op-node bootstrap` on the Mac.")
+      pc2.dim("Phase 1: laptop side (now) \u2014 Cloudflare, GitHub, Terraform Cloud."),
+      pc2.dim("Phase 2: Studio side \u2014 run `create-op-node bootstrap` on the Mac.")
     ].join("\n"),
     "Welcome"
   );
-  const values = await p.group(
-    {
-      domain: () => opts.domain ? Promise.resolve(opts.domain) : p.text({
-        message: "Domain registered in Cloudflare?",
-        placeholder: "example.org",
-        validate: (v) => !v ? "Required" : v.includes(".") ? void 0 : "Looks like that domain is missing a TLD"
-      }),
-      region: () => opts.region ? Promise.resolve(opts.region) : p.text({
-        message: "Short region label (used as a prefix in 1Password + R2)?",
-        placeholder: "us-ca",
-        validate: (v) => /^[a-z0-9-]{2,32}$/.test(v ?? "") ? void 0 : "lowercase letters, digits, hyphens; 2\u201332 chars"
-      })
-    },
-    {
-      onCancel: () => {
-        p.cancel("Cancelled.");
-        process.exit(0);
-      }
-    }
+  const region = opts.region ? opts.region : unwrap(
+    await p3.text({
+      message: "Short region label (used as a prefix in 1Password + R2)?",
+      placeholder: "us-ca",
+      validate: (v) => /^[a-z0-9-]{2,32}$/.test(v ?? "") ? void 0 : "lowercase letters, digits, hyphens; 2\u201332 chars"
+    })
   );
-  const tokenSpinner = p.spinner();
-  let cfToken = opts.cfToken;
-  if (!cfToken) {
-    const v = await p.password({
-      message: "Paste your Cloudflare Account API token (input hidden)",
-      validate: (v2) => v2 && v2.length >= 30 ? void 0 : "Token looks too short"
-    });
-    if (p.isCancel(v)) {
-      p.cancel("Cancelled.");
-      process.exit(0);
+  const domain = opts.domain ? opts.domain : unwrap(
+    await p3.text({
+      message: "Domain registered in Cloudflare?",
+      placeholder: "example.org",
+      validate: (v) => !v ? "Required" : v.includes(".") ? void 0 : "Missing a TLD?"
+    })
+  );
+  const owner = opts.owner ?? "OpusPopuli";
+  const newRepoName = `opuspopuli-node-${region}`;
+  const newRepoFull = `${owner}/${newRepoName}`;
+  const cfToken = await collectSecret(
+    opts.cfToken,
+    "Cloudflare Account API token (input hidden)",
+    "cloudflare"
+  );
+  const cfAccount = await collectId(opts.cfAccount, "Cloudflare account ID");
+  const cfZone = await collectId(opts.cfZone, `Cloudflare zone ID for ${domain}`);
+  const cfSpin = p3.spinner();
+  cfSpin.start("Verifying Cloudflare token + 5 scopes\u2026");
+  const cfProbe = await probeCloudflareToken({
+    token: cfToken,
+    accountId: cfAccount,
+    zoneId: cfZone
+  });
+  if (!cfProbe.ok) {
+    cfSpin.stop(pc2.red("\u2717 Cloudflare token check failed."));
+    for (const issue of cfProbe.issues) console.error(`  - ${issue}`);
+    p3.cancel("Fix the token in the Cloudflare dashboard, then re-run.");
+    process.exit(1);
+  }
+  cfSpin.stop(pc2.green("\u2713 Cloudflare token valid, 5 scopes present."));
+  const tfToken = await collectSecret(
+    opts.tfToken,
+    "Terraform Cloud user/team API token",
+    "tfc"
+  );
+  const tfOrg = opts.tfOrg ? opts.tfOrg : unwrap(
+    await p3.text({
+      message: "Terraform Cloud organization name?",
+      placeholder: "op-region-ca"
+    })
+  );
+  const tfSpin = p3.spinner();
+  tfSpin.start("Verifying Terraform Cloud token + organization\u2026");
+  const tfProbe = await probeTfcToken({ token: tfToken, organization: tfOrg });
+  if (!tfProbe.ok) {
+    tfSpin.stop(pc2.red("\u2717 Terraform Cloud check failed."));
+    for (const issue of tfProbe.issues) console.error(`  - ${issue}`);
+    p3.cancel("Fix the token / org, then re-run.");
+    process.exit(1);
+  }
+  tfSpin.stop(
+    pc2.green(
+      `\u2713 TFC token valid${tfProbe.userName ? ` (as ${tfProbe.userName})` : ""}, org "${tfOrg}" reachable.`
+    )
+  );
+  let ghToken = opts.ghToken;
+  if (!ghToken) {
+    const fromCli = await ghTokenFromCli();
+    if (fromCli) {
+      const useCli = unwrap(
+        await p3.confirm({
+          message: "Found a signed-in `gh` CLI \u2014 use its token?",
+          initialValue: true
+        })
+      );
+      if (useCli) ghToken = fromCli;
     }
-    cfToken = v;
   }
-  let cfAccount = opts.cfAccount;
-  if (!cfAccount) {
-    const v = await p.text({
-      message: "Cloudflare account ID",
-      placeholder: "0000000000000000000000000000000",
-      validate: (v2) => /^[a-f0-9]{32}$/.test(v2 ?? "") ? void 0 : "Expected 32 hex characters"
-    });
-    if (p.isCancel(v)) {
-      p.cancel("Cancelled.");
+  if (!ghToken) {
+    ghToken = await collectSecret(
+      void 0,
+      "GitHub Personal Access Token (repo scope)",
+      "github"
+    );
+  }
+  const op = await detectOp();
+  const opNote = op.installed ? op.signedIn ? `\u2713 1Password CLI signed in${op.email ? ` (${op.email})` : ""} \u2014 pgsodium key + Tunnel token will be saved automatically.` : `\u26A0 1Password CLI installed but not signed in. Run \`op signin\` in another shell, or you'll be prompted to paste secrets.` : `\u26A0 1Password CLI not installed. Secrets will be printed for you to paste into 1Password by hand.`;
+  p3.note(opNote, "1Password");
+  p3.note(
+    [
+      `Region label:        ${pc2.cyan(region)}`,
+      `Domain:              ${pc2.cyan(domain)}`,
+      `New node repo:       ${pc2.cyan(newRepoFull)}`,
+      `Template:            ${pc2.dim(opts.template ?? "OpusPopuli/opuspopuli-node")}`,
+      `TFC organization:    ${pc2.cyan(tfOrg)}`,
+      ``,
+      `Will create the repo, seed 5 secrets, write prod.tfvars on a branch,`,
+      `open a PR, generate a fresh pgsodium key, and (after you merge) wait`,
+      `for terraform apply to finish and retrieve the Tunnel token.`
+    ].join("\n"),
+    "Plan"
+  );
+  if (!opts.yes) {
+    const go = unwrap(
+      await p3.confirm({ message: "Proceed?", initialValue: true })
+    );
+    if (!go) {
+      p3.cancel("Cancelled.");
       process.exit(0);
     }
-    cfAccount = v;
   }
-  let cfZone = opts.cfZone;
-  if (!cfZone) {
-    const v = await p.text({
-      message: `Cloudflare zone ID for ${values.domain}`,
-      placeholder: "0000000000000000000000000000000",
-      validate: (v2) => /^[a-f0-9]{32}$/.test(v2 ?? "") ? void 0 : "Expected 32 hex characters"
+  const repoSpin = p3.spinner();
+  repoSpin.start(`Creating ${newRepoFull} from ${opts.template}\u2026`);
+  let created;
+  try {
+    created = await createRepoFromTemplate({
+      token: ghToken,
+      template: opts.template ?? "OpusPopuli/opuspopuli-node",
+      owner,
+      name: newRepoName,
+      description: `Opus Populi node deployment for ${region}`
     });
-    if (p.isCancel(v)) {
-      p.cancel("Cancelled.");
+    repoSpin.stop(pc2.green(`\u2713 Created ${created.fullName}`));
+  } catch (err) {
+    const status = typeof err === "object" && err !== null && "status" in err ? err.status : 0;
+    const message = err.message ?? "unknown error";
+    if (status !== 422) {
+      repoSpin.stop(pc2.red(`\u2717 Couldn't create repo: ${message}`));
+      p3.cancel("Fix the issue and re-run.");
+      process.exit(1);
+    }
+    repoSpin.stop(pc2.yellow(`\u26A0 ${newRepoFull} already exists.`));
+    const reuse = opts.useExistingRepo || unwrap(
+      await p3.confirm({
+        message: `Continue with the existing ${newRepoFull}? (Re-seeds secrets + re-commits prod.tfvars on a fresh branch.)`,
+        initialValue: true
+      })
+    );
+    if (!reuse) {
+      p3.cancel(
+        `Delete ${newRepoFull} on GitHub and re-run, or pass --use-existing-repo to skip this prompt.`
+      );
       process.exit(0);
     }
-    cfZone = v;
+    created = {
+      fullName: newRepoFull,
+      htmlUrl: `https://github.com/${newRepoFull}`,
+      defaultBranch: "main"
+    };
   }
-  tokenSpinner.start("Verifying token + scopes against the Cloudflare API\u2026");
-  const probe = await probeCloudflareToken({
-    token: cfToken,
-    accountId: cfAccount,
-    zoneId: cfZone
-  });
-  if (probe.ok) {
-    tokenSpinner.stop(pc.green("\u2713 Token valid, all 5 scopes present."));
-  } else {
-    tokenSpinner.stop(pc.red("\u2717 Token check failed."));
-    for (const issue of probe.issues) {
-      console.error(`  - ${issue}`);
+  const secrets = [
+    { name: "CLOUDFLARE_API_TOKEN", value: cfToken },
+    { name: "CLOUDFLARE_ACCOUNT_ID", value: cfAccount },
+    { name: "CLOUDFLARE_ZONE_ID", value: cfZone },
+    { name: "TF_API_TOKEN", value: tfToken },
+    { name: "TF_CLOUD_ORGANIZATION", value: tfOrg }
+  ];
+  const secSpin = p3.spinner();
+  secSpin.start(`Seeding ${secrets.length} repo secrets\u2026`);
+  const seeded = [];
+  for (const s of secrets) {
+    const r = await setRepoSecret({ repo: newRepoFull, name: s.name, value: s.value });
+    if (!r.written) {
+      secSpin.stop(pc2.red(`\u2717 Failed to set ${s.name}: ${r.reason ?? "unknown"}`));
+      const remaining = secrets.slice(secrets.findIndex((x) => x.name === s.name)).map((x) => x.name);
+      p3.cancel(
+        [
+          seeded.length > 0 ? `Already seeded on ${newRepoFull}: ${seeded.join(", ")}.` : `Nothing seeded yet on ${newRepoFull}.`,
+          `Still pending: ${remaining.join(", ")}.`,
+          "",
+          `Make sure \`gh\` is installed and signed in (\`gh auth login\`).`,
+          `Re-run with --use-existing-repo to retry (GitHub will overwrite the already-set secrets idempotently).`
+        ].join("\n")
+      );
+      process.exit(1);
     }
-    p.cancel("Fix the token in the Cloudflare dashboard, then re-run.");
+    seeded.push(s.name);
+  }
+  secSpin.stop(pc2.green(`\u2713 Seeded ${secrets.length} secrets on ${newRepoFull}`));
+  const branch = `init/region-${region}-${isoStampUtc(/* @__PURE__ */ new Date())}`;
+  const setupSpin = p3.spinner();
+  setupSpin.start(`Writing prod.tfvars on branch ${branch}\u2026`);
+  try {
+    await createBranch({
+      token: ghToken,
+      repo: newRepoFull,
+      branch,
+      fromBranch: created.defaultBranch
+    });
+    const tfvars = renderProdTfvars({
+      project: opts.project ?? "opuspopuli",
+      domain
+    });
+    await commitFile({
+      token: ghToken,
+      repo: newRepoFull,
+      branch,
+      path: "infra/cloudflare/environments/prod.tfvars",
+      content: tfvars,
+      message: `init: prod.tfvars for ${region}`
+    });
+  } catch (err) {
+    setupSpin.stop(pc2.red(`\u2717 Couldn't write tfvars: ${err.message}`));
+    p3.cancel("The repo exists but the branch / commit failed. Open it on GitHub and inspect.");
+    process.exit(1);
+  }
+  setupSpin.stop(pc2.green("\u2713 Wrote prod.tfvars"));
+  const prSpin = p3.spinner();
+  prSpin.start("Opening pull request\u2026");
+  let pr;
+  try {
+    pr = await openPullRequest({
+      token: ghToken,
+      repo: newRepoFull,
+      head: branch,
+      base: created.defaultBranch,
+      title: `init: bring up region ${region}`,
+      body: [
+        `Initial region deployment for **${region}** (${domain}).`,
+        "",
+        "Adds `infra/cloudflare/environments/prod.tfvars`. Merging this PR triggers",
+        "`cloudflare-infra.yml` which runs `terraform apply` against the",
+        `\`${tfOrg}\` Terraform Cloud organization, provisioning the Cloudflare`,
+        "Tunnel, DNS records, R2 buckets, and Pages project.",
+        "",
+        `Generated by \`create-op-node init\`.`
+      ].join("\n")
+    });
+  } catch (err) {
+    prSpin.stop(pc2.red(`\u2717 Couldn't open PR: ${err.message}`));
+    p3.cancel("Branch + tfvars are committed; open the PR by hand on GitHub.");
     process.exit(1);
   }
-  p.note(
+  prSpin.stop(pc2.green(`\u2713 Opened PR #${pr.number}`));
+  const keyTitle = `opuspopuli-${region}-pgsodium-root-key`;
+  const vaultArg = opts.vault ? { vault: opts.vault } : {};
+  if (op.installed && op.signedIn) {
+    const existing = opts.overwrite ? null : await readSecretFromOp({ title: keyTitle, ...vaultArg });
+    if (existing && /^[a-f0-9]{64}$/.test(existing)) {
+      p3.note(
+        `${pc2.green("\u2713")} Re-using existing pgsodium master key from 1Password (${pc2.cyan(keyTitle)}). Pass --overwrite to rotate.`,
+        "Secret"
+      );
+    } else {
+      const fresh = generatePgsodiumRootKey();
+      const r = await saveSecretToOp({
+        title: keyTitle,
+        value: fresh,
+        overwrite: opts.overwrite ?? false,
+        ...vaultArg
+      });
+      if (r.written) {
+        p3.note(
+          `${pc2.green("\u2713")} pgsodium master key${r.alreadyExisted ? " rotated" : " saved"} to 1Password as ${pc2.cyan(keyTitle)}.`,
+          "Secret"
+        );
+      } else if (r.alreadyExisted) {
+        p3.note(
+          `${pc2.yellow("!")} 1Password has an item titled ${pc2.cyan(keyTitle)} but its value is NOT a 64-hex pgsodium key. Inspect it in 1Password; re-run with --overwrite to replace.`,
+          "Secret"
+        );
+      } else {
+        await printKeyForManualSave(fresh, keyTitle, r.reason);
+      }
+    }
+  } else {
+    const fresh = generatePgsodiumRootKey();
+    await printKeyForManualSave(fresh, keyTitle);
+  }
+  if (opts.skipWait) {
+    p3.outro(
+      pc2.cyan(
+        `Review + merge ${pr.htmlUrl} when ready. Re-run with no --skip-wait or run \`npx create-op-node verify\` afterwards.`
+      )
+    );
+    return;
+  }
+  p3.note(
     [
-      pc.yellow("Stopping here in v0.0.1. Coming next:"),
+      `Open the PR: ${pc2.cyan(pr.htmlUrl)}`,
       "",
-      "  \u2022 Validate Terraform Cloud token",
-      "  \u2022 `gh repo create --template OpusPopuli/opuspopuli-node`",
-      "  \u2022 Seed 5 GitHub Secrets via Octokit",
-      "  \u2022 Write environments/prod.tfvars from your answers",
-      "  \u2022 Generate pgsodium master key + stash in 1Password (via `op` if available)",
-      "  \u2022 Open the first PR; wait for `terraform apply` to complete",
-      "  \u2022 Retrieve Tunnel token from TF Cloud outputs",
-      "  \u2022 Print next steps for `create-op-node bootstrap` on the Mac Studio"
+      "Review the `terraform plan` comment, then merge to main.",
+      "The workflow then runs `terraform apply` against Terraform Cloud."
     ].join("\n"),
-    "Roadmap"
+    "Next step: review + merge"
   );
-  p.outro(pc.cyan(`Ready for the next session. Your region: opuspopuli-node-${values.region}`));
-});
-var bootstrapCommand = new Command("bootstrap").description(
-  "Configure the Mac Studio and bring the stack up. Run this on the Studio itself, after `init` has finished on your laptop."
-).action(async () => {
-  p.intro(pc.bgCyan(pc.black(" create-op-node bootstrap ")));
-  p.note(
-    [
-      pc.yellow("Stub \u2014 coming in v0.0.3."),
-      "",
-      "Will run:",
-      "  \u2022 macOS sanity checks (auto-restart, FileVault off, disk-sleep off)",
-      "  \u2022 Homebrew install (if missing) + brew install git gh pnpm jq cloudflared rclone ollama",
-      "  \u2022 Docker Desktop install + GUI config prompts",
-      "  \u2022 `gh auth login` (browser flow)",
-      "  \u2022 `tailscale up` (browser flow)",
-      "  \u2022 Clone the node repo created by `init`",
-      "  \u2022 Materialize pgsodium key (from 1Password via `op`, or paste)",
-      "  \u2022 Write LaunchAgent plist + load it",
-      "  \u2022 Login to ghcr.io",
-      "  \u2022 `ollama pull qwen3.5:9b` (+ embeddings)",
-      "  \u2022 `docker compose -f docker-compose-prod.yml pull && up -d`",
-      "  \u2022 Health-check loop until all 10 containers report (healthy)"
-    ].join("\n"),
-    "Roadmap"
+  const merged = unwrap(
+    await p3.confirm({ message: "PR merged?", initialValue: false })
+  );
+  if (!merged) {
+    p3.outro(
+      pc2.cyan(`No worries \u2014 re-run \`create-op-node init --skip-wait\` later to skip this step, or finish manually.`)
+    );
+    return;
+  }
+  const ws = await findWorkspace({
+    token: tfToken,
+    organization: tfOrg,
+    tags: ["opuspopuli", "cloudflare"]
+  });
+  if (!ws) {
+    p3.cancel(
+      `Couldn't find a TFC workspace tagged opuspopuli + cloudflare in ${tfOrg}. Check the workflow's run log; the workspace is created on first apply.`
+    );
+    process.exit(1);
+  }
+  const tunnelToken = await waitForApplyAndFetchTunnelToken({
+    token: tfToken,
+    organization: tfOrg,
+    workspaceId: ws.id,
+    runId: ws.currentRunId
+  });
+  if (!tunnelToken) {
+    p3.cancel(
+      `Terraform apply didn't produce a tunnel_token output. Check the run on TFC; if it succeeded, the output may be named differently \u2014 patch and re-run, or fetch via 'terraform output -raw tunnel_token'.`
+    );
+    process.exit(1);
+  }
+  const tunnelTitle = `opuspopuli-${region}-tunnel-token`;
+  if (op.installed && op.signedIn) {
+    const r = await saveSecretToOp({
+      title: tunnelTitle,
+      value: tunnelToken,
+      ...opts.vault ? { vault: opts.vault } : {},
+      overwrite: true
+    });
+    if (r.written) {
+      p3.note(
+        `${pc2.green("\u2713")} Tunnel token saved to 1Password as ${pc2.cyan(tunnelTitle)}.`,
+        "Secret"
+      );
+    } else {
+      await printKeyForManualSave(tunnelToken, tunnelTitle, r.reason);
+    }
+  } else {
+    await printKeyForManualSave(tunnelToken, tunnelTitle);
+  }
+  p3.outro(
+    pc2.cyan(
+      `Region ${region} is provisioned. Next: \`npx create-op-node bootstrap\` on the Mac Studio.`
+    )
   );
-  p.outro(pc.dim("See you next session."));
 });
-var verifyCommand = new Command("verify").description(
-  "Off-LAN health probe of a live node \u2014 TLS, Apollo Federation reachability, GraphQL smoke. Run from anywhere with internet access."
-).addOption(
-  new Option("--domain <domain>", "Domain to probe (e.g. example.org \u2192 checks api.example.org)")
-).action(async (opts) => {
-  p.intro(pc.bgCyan(pc.black(" create-op-node verify ")));
-  p.note(
+var MIN_TOKEN_LENGTH = {
+  cloudflare: 40,
+  tfc: 40,
+  github: 40,
+  generic: 20
+};
+async function collectSecret(preset, message, kind = "generic") {
+  if (preset) return preset;
+  const min = MIN_TOKEN_LENGTH[kind];
+  const v = unwrap(
+    await p3.password({
+      message,
+      validate: (v2) => v2 && v2.length >= min ? void 0 : `That looks too short \u2014 expected at least ${min} characters for a ${kind} token`
+    })
+  );
+  return v;
+}
+async function collectId(preset, message) {
+  if (preset) return preset;
+  const v = unwrap(
+    await p3.text({
+      message,
+      placeholder: "0000000000000000000000000000000",
+      validate: (v2) => /^[a-f0-9]{32}$/.test(v2 ?? "") ? void 0 : "Expected 32 hex characters"
+    })
+  );
+  return v;
+}
+async function printKeyForManualSave(value, title, reason) {
+  p3.note(
     [
-      pc.yellow("Stub \u2014 coming in v0.0.4."),
+      reason ? `${pc2.red("\u2717")} ${reason}` : "",
+      `Save this value to 1Password as ${pc2.cyan(title)}:`,
       "",
-      opts.domain ? `Will probe api.${opts.domain}.` : "Will prompt for domain.",
+      pc2.yellow(value),
       "",
-      "Will check:",
-      "  \u2022 TLS handshake to api.<domain>",
-      "  \u2022 GET /health returns 200",
-      "  \u2022 POST /api with a public introspection query returns valid GraphQL",
-      "  \u2022 cloudflared registered tunnel connections",
-      "  \u2022 Cosign signatures on the running images"
-    ].join("\n"),
-    "Roadmap"
+      pc2.dim("It will not be shown again.")
+    ].filter((line) => line.length > 0).join("\n"),
+    "Manual save"
   );
-  p.outro(pc.dim("See you next session."));
-});
+  unwrap(
+    await p3.confirm({
+      message: "Value stashed in 1Password?",
+      initialValue: true
+    })
+  );
+}
+function isoStampUtc(d) {
+  const pad = (n, w = 2) => n.toString().padStart(w, "0");
+  return `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}-${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}Z`;
+}
+async function waitForApplyAndFetchTunnelToken(input) {
+  const spin = p3.spinner();
+  spin.start("Waiting for terraform apply to finish (polling every 10s)\u2026");
+  const outcome = await waitForApply({
+    token: input.token,
+    organization: input.organization,
+    workspaceId: input.workspaceId,
+    runId: input.runId,
+    workspaceTags: ["opuspopuli", "cloudflare"],
+    outputName: "tunnel_token"
+  });
+  switch (outcome.kind) {
+    case "success":
+      spin.stop(pc2.green("\u2713 Tunnel token retrieved."));
+      return outcome.value;
+    case "output-missing":
+      spin.stop(pc2.red("\u2717 Apply succeeded but tunnel_token output is missing."));
+      return null;
+    case "no-run-started":
+      spin.stop(pc2.red("\u2717 No run started in the workspace yet."));
+      return null;
+    case "run-failed":
+      spin.stop(pc2.red(`\u2717 Run finished with status "${outcome.status}".`));
+      return null;
+    case "timeout":
+      spin.stop(pc2.red("\u2717 Timed out after 10 minutes."));
+      return null;
+  }
+}
+
+// src/lib/constants.ts
+var PGSODIUM_KEY_RE = /^[a-f0-9]{64}$/;
+var TUNNEL_TOKEN_RE = /^[A-Za-z0-9_\-.=]+$/;
+var SAFE_PATH_RE = /^[A-Za-z0-9_\-./ ]+$/;
+var VERIFY_NETWORK_TIMEOUT_MS = 1e4;
+var BODY_PREVIEW_MAX = 200;
+
+// src/lib/homebrew.ts
+var STUDIO_PACKAGES = [
+  { name: "git", kind: "formula" },
+  { name: "gh", kind: "formula" },
+  { name: "pnpm", kind: "formula" },
+  { name: "jq", kind: "formula" },
+  { name: "cloudflared", kind: "formula" },
+  { name: "rclone", kind: "formula" },
+  { name: "ollama", kind: "formula" },
+  { name: "docker", kind: "cask" },
+  { name: "tailscale", kind: "cask" }
+];
+async function detectBrew() {
+  const res = await safeExeca("brew", ["--version"]);
+  if (res === null || res.exitCode !== 0) {
+    return { installed: false };
+  }
+  const version = res.stdout.split("\n").find((l) => l.startsWith("Homebrew "));
+  return { installed: true, ...version ? { version } : {} };
+}
+var HOMEBREW_INSTALL_COMMAND = '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"';
+async function isPackageInstalled(pkg) {
+  const flag = pkg.kind === "cask" ? "--cask" : "--formula";
+  const res = await safeExeca("brew", ["list", flag, pkg.name]);
+  return res !== null && res.exitCode === 0;
+}
+async function installPackage(pkg) {
+  const args = pkg.kind === "cask" ? ["install", "--cask", pkg.name] : ["install", pkg.name];
+  const res = await safeExeca("brew", args);
+  if (res === null) {
+    return { ok: false, reason: "`brew` not on PATH" };
+  }
+  if (res.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `brew install ${pkg.name} failed (${res.exitCode ?? "signal"}): ${res.stderr || res.stdout}`
+    };
+  }
+  return { ok: true };
+}
+async function installPackages(packages, onEach) {
+  const report = {
+    installed: [],
+    alreadyPresent: [],
+    failed: []
+  };
+  for (const pkg of packages) {
+    onEach?.(pkg, "checking");
+    if (await isPackageInstalled(pkg)) {
+      report.alreadyPresent.push(pkg);
+      onEach?.(pkg, "present");
+      continue;
+    }
+    onEach?.(pkg, "installing");
+    const r = await installPackage(pkg);
+    if (r.ok) {
+      report.installed.push(pkg);
+      onEach?.(pkg, "installed");
+    } else {
+      report.failed.push({ pkg, reason: r.reason ?? "unknown" });
+      onEach?.(pkg, "failed");
+    }
+  }
+  return report;
+}
+
+// src/lib/macos.ts
+async function inspectSystem() {
+  const [hostnameOut, osVersionOut, pmsetOut, fdesetupOut, unameOut] = await Promise.all([
+    safeExeca("hostname", []),
+    safeExeca("sw_vers", ["-productVersion"]),
+    safeExeca("pmset", ["-g"]),
+    safeExeca("fdesetup", ["status"]),
+    safeExeca("uname", ["-m"])
+  ]);
+  return {
+    hostname: hostnameOut?.stdout.trim() ?? "unknown",
+    osVersion: osVersionOut && osVersionOut.exitCode === 0 ? osVersionOut.stdout.trim() : null,
+    autoRestartOnPowerFailure: parsePmsetBool(pmsetOut?.stdout ?? "", "autorestart", 1),
+    diskSleepDisabled: parsePmsetBool(pmsetOut?.stdout ?? "", "disksleep", 0),
+    fileVaultEnabled: parseFileVault(fdesetupOut?.stdout ?? ""),
+    isAppleSilicon: (unameOut?.stdout.trim() ?? "") === "arm64"
+  };
+}
+function parsePmsetBool(output, key, expected) {
+  for (const line of output.split("\n")) {
+    const match = line.match(/^\s*([a-z]+)\s+(-?\d+)\s*$/);
+    if (match && match[1] === key) {
+      return Number(match[2]) === expected;
+    }
+  }
+  return false;
+}
+function parseFileVault(output) {
+  const trimmed = output.trim();
+  if (/^FileVault is On\.?/i.test(trimmed)) return true;
+  if (/^FileVault is Off\.?/i.test(trimmed)) return false;
+  if (/encryption in progress/i.test(trimmed)) return true;
+  return "unknown";
+}
+async function enableAutoRestartOnPowerFailure() {
+  return runSudoPmset(["autorestart", "1"]);
+}
+async function disableDiskSleep() {
+  return runSudoPmset(["disksleep", "0"]);
+}
+async function runSudoPmset(args) {
+  const res = await safeExeca("sudo", ["pmset", "-a", ...args]);
+  if (res === null) {
+    return { ok: false, reason: "`sudo` not on PATH" };
+  }
+  if (res.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `pmset ${args.join(" ")} failed (${res.exitCode ?? "signal"}): ${res.stderr || res.stdout}`
+    };
+  }
+  return { ok: true };
+}
+var LAUNCH_AGENT_LABEL = "org.opuspopuli.envloader";
+function defaultPaths(home = homedir()) {
+  return {
+    keyFile: `${home}/.config/opuspopuli/pgsodium_root_key`,
+    plistFile: `${home}/Library/LaunchAgents/${LAUNCH_AGENT_LABEL}.plist`
+  };
+}
+async function writePgsodiumKeyFile(key, keyFile) {
+  if (!PGSODIUM_KEY_RE.test(key)) {
+    return {
+      ok: false,
+      reason: `pgsodium key must be 64 lowercase hex characters (got ${key.length} chars)`
+    };
+  }
+  try {
+    const dir = dirname(keyFile);
+    await mkdir(dir, { recursive: true, mode: 448 });
+    await writeFile(keyFile, key, { mode: 256 });
+    await chmod(dir, 448);
+    await chmod(keyFile, 256);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: `writing ${keyFile} failed: ${err.message}` };
+  }
+}
+function renderLaunchAgentPlist(input) {
+  if (!TUNNEL_TOKEN_RE.test(input.tunnelToken)) {
+    throw new Error("Tunnel token contains characters outside the expected base64-url set");
+  }
+  if (!SAFE_PATH_RE.test(input.keyFilePath)) {
+    throw new Error(
+      `keyFilePath ${JSON.stringify(input.keyFilePath)} contains characters not allowed in a launchd path interpolation`
+    );
+  }
+  const command = `launchctl setenv PGSODIUM_ROOT_KEY "$(cat ${input.keyFilePath})"; launchctl setenv TUNNEL_TOKEN "${input.tunnelToken}"`;
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    `  <key>Label</key><string>${LAUNCH_AGENT_LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    "    <string>/bin/sh</string>",
+    "    <string>-c</string>",
+    `    <string>${command}</string>`,
+    "  </array>",
+    "  <key>RunAtLoad</key><true/>",
+    "</dict>",
+    "</plist>",
+    ""
+  ].join("\n");
+}
+async function writeLaunchAgentPlist(plistFile, content) {
+  try {
+    await mkdir(dirname(plistFile), { recursive: true });
+    await writeFile(plistFile, content, { mode: 384 });
+    await chmod(plistFile, 384);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: `writing ${plistFile} failed: ${err.message}` };
+  }
+}
+async function loadLaunchAgent(plistFile) {
+  await safeExeca("launchctl", ["unload", plistFile]);
+  const load = await safeExeca("launchctl", ["load", plistFile]);
+  if (load === null) {
+    return { ok: false, reason: "`launchctl` not on PATH" };
+  }
+  if (load.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `launchctl load failed (${load.exitCode ?? "signal"}): ${load.stderr || load.stdout}`
+    };
+  }
+  return { ok: true };
+}
+async function setupLaunchAgent(input) {
+  const paths = input.paths ?? defaultPaths();
+  const keyResult = await writePgsodiumKeyFile(input.pgsodiumKey, paths.keyFile);
+  if (!keyResult.ok) {
+    return { ok: false, paths, step: "key-file", ...keyResult.reason ? { reason: keyResult.reason } : {} };
+  }
+  let plistContent;
+  try {
+    plistContent = renderLaunchAgentPlist({
+      keyFilePath: paths.keyFile,
+      tunnelToken: input.tunnelToken
+    });
+  } catch (err) {
+    return { ok: false, paths, step: "plist", reason: err.message };
+  }
+  const plistResult = await writeLaunchAgentPlist(paths.plistFile, plistContent);
+  if (!plistResult.ok) {
+    return { ok: false, paths, step: "plist", ...plistResult.reason ? { reason: plistResult.reason } : {} };
+  }
+  const loadResult = await loadLaunchAgent(paths.plistFile);
+  if (!loadResult.ok) {
+    return { ok: false, paths, step: "load", ...loadResult.reason ? { reason: loadResult.reason } : {} };
+  }
+  return { ok: true, paths };
+}
+async function teardownLaunchAgent(paths, opts = {}) {
+  const steps = [];
+  const unload = await safeExeca("launchctl", ["unload", paths.plistFile]);
+  steps.push({
+    step: "unload",
+    ok: true,
+    ...unload === null ? { reason: "`launchctl` not on PATH" } : {}
+  });
+  try {
+    await rm(paths.plistFile, { force: true });
+    steps.push({ step: "rm-plist", ok: true });
+  } catch (err) {
+    steps.push({ step: "rm-plist", ok: false, reason: err.message });
+  }
+  if (!opts.keepKeyFile) {
+    try {
+      await rm(paths.keyFile, { force: true });
+      steps.push({ step: "rm-key-file", ok: true });
+    } catch (err) {
+      steps.push({ step: "rm-key-file", ok: false, reason: err.message });
+    }
+  }
+  return { ok: steps.every((s) => s.ok), steps };
+}
+
+// src/lib/docker.ts
+var GHCR_REGISTRY = "ghcr.io";
+async function loginToGhcr() {
+  const tokenRes = await safeExeca("gh", ["auth", "token"]);
+  if (tokenRes === null) return { ok: false, reason: "`gh` not installed" };
+  if (tokenRes.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `gh auth token failed (${tokenRes.exitCode ?? "signal"}): ${tokenRes.stderr || tokenRes.stdout}`
+    };
+  }
+  const token = tokenRes.stdout.trim();
+  if (token.length === 0) {
+    return { ok: false, reason: "gh auth token returned empty \u2014 run `gh auth login` first" };
+  }
+  const userRes = await safeExeca("gh", ["api", "user", "--jq", ".login"]);
+  if (userRes === null || userRes.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `couldn't resolve GitHub user via gh api: ${userRes?.stderr || userRes?.stdout || "gh missing"}`
+    };
+  }
+  const user = userRes.stdout.trim();
+  if (user.length === 0) {
+    return { ok: false, reason: "gh api user returned empty \u2014 gh not signed in" };
+  }
+  const loginRes = await safeExeca(
+    "docker",
+    ["login", GHCR_REGISTRY, "-u", user, "--password-stdin"],
+    { input: token }
+  );
+  if (loginRes === null) return { ok: false, reason: "`docker` not installed" };
+  if (loginRes.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `docker login ${GHCR_REGISTRY} failed (${loginRes.exitCode ?? "signal"}): ${loginRes.stderr || loginRes.stdout}`
+    };
+  }
+  return { ok: true };
+}
+function composeArgs(opts, sub) {
+  const files = opts.files.flatMap((f) => ["-f", f]);
+  const env = opts.envFile ? ["--env-file", opts.envFile] : [];
+  return ["compose", ...files, ...env, ...sub];
+}
+async function composePull(opts) {
+  const res = await safeExeca("docker", composeArgs(opts, ["pull"]));
+  return result(res, "compose pull");
+}
+async function composeUp(opts) {
+  const res = await safeExeca("docker", composeArgs(opts, ["up", "-d", "--remove-orphans"]));
+  return result(res, "compose up");
+}
+async function composeDown(opts) {
+  const flags = ["down"];
+  if (opts.wipeVolumes) flags.push("-v");
+  if (opts.removeOrphans) flags.push("--remove-orphans");
+  const res = await safeExeca("docker", composeArgs(opts, flags));
+  return result(res, opts.wipeVolumes ? "compose down -v" : "compose down");
+}
+async function dockerLogout(registry = GHCR_REGISTRY) {
+  const res = await safeExeca("docker", ["logout", registry]);
+  return result(res, `docker logout ${registry}`);
+}
+function result(res, label) {
+  if (res === null) return { ok: false, reason: "`docker` not installed" };
+  if (res.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `${label} failed (${res.exitCode ?? "signal"}): ${res.stderr || res.stdout}`
+    };
+  }
+  return { ok: true };
+}
+function parseComposePs(stdout) {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) return [];
+  const lines = trimmed.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+  const out = [];
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      if (Array.isArray(parsed)) {
+        for (const item of parsed) out.push(normalize(item));
+      } else {
+        out.push(normalize(parsed));
+      }
+    } catch {
+    }
+  }
+  return out;
+}
+function normalize(raw) {
+  const r = raw ?? {};
+  const name = r["Name"] ?? r["Service"] ?? "<unknown>";
+  const state = (r["State"] ?? "unknown").toLowerCase();
+  const healthRaw = (r["Health"] ?? "").toLowerCase();
+  const health = healthRaw === "healthy" || healthRaw === "unhealthy" || healthRaw === "starting" ? healthRaw : "none";
+  const exitCodeRaw = r["ExitCode"];
+  const exitCode = typeof exitCodeRaw === "number" ? exitCodeRaw : null;
+  return { name, state, health, exitCode };
+}
+async function composePs(opts) {
+  const res = await safeExeca("docker", composeArgs(opts, ["ps", "--format", "json"]));
+  if (res === null || res.exitCode !== 0) return null;
+  return parseComposePs(res.stdout);
+}
+var realWaitDeps = {
+  ps: composePs,
+  sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
+  now: () => Date.now()
+};
+async function waitForHealthy(composeOpts, options = {}, deps = realWaitDeps) {
+  const timeoutMs = options.timeoutMs ?? 5 * 60 * 1e3;
+  const basePollMs = options.pollMs ?? 5 * 1e3;
+  const start = deps.now();
+  let last = [];
+  let pollCount = 0;
+  while (deps.now() - start < timeoutMs) {
+    pollCount++;
+    const ps = await deps.ps(composeOpts);
+    if (ps !== null) {
+      last = ps;
+      options.onPoll?.(ps);
+      if (ps.length > 0) {
+        const verdict = assessHealth(ps, options.requireHealthy);
+        if (verdict.kind === "healthy") return { kind: "healthy", snapshots: ps };
+        if (verdict.kind === "unhealthy") {
+          return {
+            kind: "unhealthy",
+            snapshots: ps,
+            problem: verdict.problem ?? "unhealthy"
+          };
+        }
+      }
+    }
+    const interval = pollCount < 3 ? basePollMs : basePollMs * 2;
+    await deps.sleep(interval);
+  }
+  return { kind: "timeout", snapshots: last };
+}
+function assessHealth(snapshots, requireHealthy) {
+  for (const s of snapshots) {
+    if (s.health === "unhealthy") {
+      return { kind: "unhealthy", problem: `${s.name} reports unhealthy` };
+    }
+    if (s.state === "exited" && (s.exitCode ?? 0) !== 0) {
+      return { kind: "unhealthy", problem: `${s.name} exited with code ${s.exitCode}` };
+    }
+  }
+  const required = requireHealthy ?? [];
+  if (required.length > 0) {
+    const byName = new Map(snapshots.map((s) => [s.name, s]));
+    for (const name of required) {
+      const s = byName.get(name);
+      if (!s) return { kind: "pending" };
+      if (s.state === "exited" && s.exitCode === 0) continue;
+      if (s.state !== "running") return { kind: "pending" };
+      if (s.health === "starting") return { kind: "pending" };
+      if (s.health === "unhealthy") {
+        return { kind: "unhealthy", problem: `${s.name} reports unhealthy` };
+      }
+    }
+    return { kind: "healthy" };
+  }
+  for (const s of snapshots) {
+    if (s.state === "exited" && s.exitCode === 0) continue;
+    if (s.state !== "running") return { kind: "pending" };
+    if (s.health === "starting") return { kind: "pending" };
+  }
+  return { kind: "healthy" };
+}
+
+// src/lib/ollama.ts
+var OLLAMA_URL = "http://localhost:11434";
+var DEFAULT_MODELS = ["qwen3.5:9b", "nomic-embed-text"];
+var PROBE_ALPINE_TAG = "3.20";
+async function startOllamaService() {
+  const res = await safeExeca("brew", ["services", "start", "ollama"]);
+  if (res === null) return { ok: false, reason: "`brew` not on PATH" };
+  if (res.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `brew services start ollama failed (${res.exitCode ?? "signal"}): ${res.stderr || res.stdout}`
+    };
+  }
+  return { ok: true };
+}
+async function checkOllamaHealth(url = OLLAMA_URL) {
+  try {
+    const res = await fetch(`${url}/api/tags`);
+    if (!res.ok) return { reachable: false, models: [] };
+    const body = await res.json();
+    const models = (body.models ?? []).map((m) => m.name ?? "").filter((n) => n.length > 0);
+    return { reachable: true, models };
+  } catch {
+    return { reachable: false, models: [] };
+  }
+}
+async function pullModel(name) {
+  const res = await safeExeca("ollama", ["pull", name]);
+  if (res === null) return { ok: false, reason: "`ollama` not on PATH" };
+  if (res.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `ollama pull ${name} failed (${res.exitCode ?? "signal"}): ${res.stderr || res.stdout}`
+    };
+  }
+  return { ok: true };
+}
+async function warmModel(name, url = OLLAMA_URL) {
+  try {
+    const res = await fetch(`${url}/api/generate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model: name, prompt: "hi", stream: false })
+    });
+    if (!res.ok) {
+      const text6 = await res.text().catch(() => "");
+      return {
+        ok: false,
+        reason: `warm ${name} returned HTTP ${res.status}: ${text6 || "(no body)"}`
+      };
+    }
+    await res.text();
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `warm ${name} failed: ${err.message}`
+    };
+  }
+}
+async function probeHostDockerInternal() {
+  const res = await safeExeca("docker", [
+    "run",
+    "--rm",
+    `alpine:${PROBE_ALPINE_TAG}`,
+    "sh",
+    "-c",
+    "apk add --no-cache curl >/dev/null 2>&1 && curl -fsS http://host.docker.internal:11434/api/tags"
+  ]);
+  if (res === null) return { ok: false, reason: "`docker` not on PATH" };
+  if (res.exitCode !== 0) {
+    return {
+      ok: false,
+      reason: `container couldn't reach host.docker.internal:11434 \u2014 check Docker Desktop settings \u2192 Resources \u2192 Network \u2192 Enable host.docker.internal`
+    };
+  }
+  return { ok: true };
+}
+async function setupModels(models, onProgress) {
+  const report = {
+    pulled: [],
+    alreadyPresent: [],
+    failed: [],
+    warmed: []
+  };
+  const health = await checkOllamaHealth();
+  const present = new Set(health.models);
+  for (const m of models) {
+    if (present.has(m)) {
+      report.alreadyPresent.push(m);
+      onProgress?.(m, "present");
+      continue;
+    }
+    onProgress?.(m, "pulling");
+    const r = await pullModel(m);
+    if (r.ok) {
+      report.pulled.push(m);
+      onProgress?.(m, "pulled");
+    } else {
+      report.failed.push({ model: m, reason: r.reason ?? "unknown" });
+      onProgress?.(m, "failed");
+    }
+  }
+  const warmTarget = models.find((m) => present.has(m) || report.pulled.includes(m));
+  if (warmTarget) {
+    onProgress?.(warmTarget, "warming");
+    const w = await warmModel(warmTarget);
+    if (w.ok) {
+      report.warmed.push(warmTarget);
+      onProgress?.(warmTarget, "warmed");
+    }
+  }
+  return report;
+}
+var NODE_REPO_MARKERS = [
+  "docker-compose-prod.yml",
+  "supabase/init/pgsodium_getkey_env.sh"
+];
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function looksLikeNodeRepo(dir) {
+  const checks = await Promise.all(
+    NODE_REPO_MARKERS.map((m) => fileExists(join(dir, m)))
+  );
+  return checks.every((ok) => ok);
+}
+async function locateOrCloneRepo(input) {
+  if (input.explicit) {
+    if (await looksLikeNodeRepo(input.explicit)) {
+      return { kind: "found", path: input.explicit, source: "explicit" };
+    }
+    return { kind: "explicit-not-a-node-repo", path: input.explicit };
+  }
+  const cwd = input.cwd ?? process.cwd();
+  if (await looksLikeNodeRepo(cwd)) {
+    return { kind: "found", path: cwd, source: "cwd" };
+  }
+  if (input.allowClone === false) {
+    return { kind: "clone-disallowed" };
+  }
+  const target = input.cloneInto ?? join(homedir(), "Development", input.name);
+  const res = await safeExeca("gh", ["repo", "clone", `${input.owner}/${input.name}`, target]);
+  if (res === null) return { kind: "gh-not-installed" };
+  if (res.exitCode !== 0) {
+    return {
+      kind: "clone-failed",
+      reason: `gh repo clone failed (${res.exitCode ?? "signal"}): ${res.stderr || res.stdout}`
+    };
+  }
+  return { kind: "cloned", path: target };
+}
+
+// src/commands/bootstrap.ts
+var bootstrapCommand = new Command("bootstrap").description(
+  "Configure the Mac Studio and bring the stack up. Run this on the Studio itself, after `init` has finished on your laptop."
+).addOption(new Option("--region <slug>", "Region label set during init (e.g. us-ca)")).addOption(new Option("--owner <owner>", "GitHub owner for the node repo").default("OpusPopuli")).addOption(new Option("--vault <vault>", "1Password vault to read secrets from").default("Private")).addOption(new Option("--repo-dir <path>", "Explicit path to a checked-out node repo (overrides cwd + clone)")).addOption(
+  new Option(
+    "--compose-file <path>",
+    "Repeatable. Compose file relative to repo root. Default: docker-compose-prod.yml + docker-compose-backup.yml"
+  ).default(["docker-compose-prod.yml", "docker-compose-backup.yml"])
+).addOption(new Option("--env-file <path>", "Compose --env-file. Default: .env.production")).addOption(new Option("--skip-brew", "Skip the Homebrew package install pass").default(false)).addOption(
+  new Option(
+    "--skip-launch-agent",
+    "Skip the LaunchAgent setup (assumes one is already in place)"
+  ).default(false)
+).addOption(new Option("--skip-ollama", "Skip the Ollama model pull + warm").default(false)).addOption(new Option("--skip-stack", "Stop before `docker compose pull && up`").default(false)).addOption(new Option("-y, --yes", "Skip confirmation prompts").default(false)).action(async (opts) => {
+  p3.intro(pc2.bgCyan(pc2.black(" create-op-node bootstrap ")));
+  const region = opts.region ? opts.region : unwrap(
+    await p3.text({
+      message: "Region label (the slug used during init \u2014 e.g. us-ca)?",
+      placeholder: "us-ca",
+      validate: (v) => /^[a-z0-9-]{2,32}$/.test(v ?? "") ? void 0 : "lowercase letters, digits, hyphens; 2\u201332 chars"
+    })
+  );
+  const owner = opts.owner ?? "OpusPopuli";
+  const repoName = `opuspopuli-node-${region}`;
+  const sysSpin = p3.spinner();
+  sysSpin.start("Inspecting macOS\u2026");
+  const snap = await inspectSystem();
+  sysSpin.stop(pc2.green("\u2713 macOS inspected."));
+  if (!snap.isAppleSilicon) {
+    p3.cancel(
+      `Bootstrap requires an Apple Silicon Mac (the runbook targets M-series). Detected: ${snap.osVersion ?? "unknown"} (uname -m != arm64).`
+    );
+    process.exit(1);
+  }
+  p3.note(
+    [
+      `Hostname:                 ${pc2.cyan(snap.hostname)}`,
+      `macOS:                    ${pc2.cyan(snap.osVersion ?? "(sw_vers failed)")}`,
+      `Auto-restart on power:    ${kvBool(snap.autoRestartOnPowerFailure)}`,
+      `Disk sleep disabled:      ${kvBool(snap.diskSleepDisabled)}`,
+      `FileVault:                ${kvFileVault(snap.fileVaultEnabled)}`
+    ].join("\n"),
+    "System snapshot"
+  );
+  if (!snap.autoRestartOnPowerFailure) {
+    const fix = unwrap(
+      await p3.confirm({
+        message: "Auto-restart-on-power-failure is OFF. Enable now (requires sudo)?",
+        initialValue: true
+      })
+    );
+    if (fix) {
+      const r = await enableAutoRestartOnPowerFailure();
+      if (!r.ok) p3.note(`${pc2.red("\u2717")} ${r.reason}`, "pmset failed");
+    }
+  }
+  if (!snap.diskSleepDisabled) {
+    const fix = unwrap(
+      await p3.confirm({
+        message: "Disk sleep is enabled. Disable now (requires sudo)?",
+        initialValue: true
+      })
+    );
+    if (fix) {
+      const r = await disableDiskSleep();
+      if (!r.ok) p3.note(`${pc2.red("\u2717")} ${r.reason}`, "pmset failed");
+    }
+  }
+  if (!opts.skipBrew) {
+    const brewInfo = await detectBrew();
+    if (!brewInfo.installed) {
+      p3.note(
+        [
+          `Homebrew is not installed. Open another shell and run:`,
+          "",
+          pc2.cyan(HOMEBREW_INSTALL_COMMAND),
+          "",
+          pc2.dim("Then come back and press Enter.")
+        ].join("\n"),
+        "Manual step"
+      );
+      unwrap(await p3.confirm({ message: "Homebrew installed?", initialValue: true }));
+    }
+    const brewSpin = p3.spinner();
+    brewSpin.start("Installing Studio packages\u2026");
+    const report = await installPackages(STUDIO_PACKAGES, (pkg, status) => {
+      brewSpin.message(`${status}: ${pkg.name}`);
+    });
+    brewSpin.stop(
+      report.failed.length === 0 ? pc2.green(
+        `\u2713 ${report.installed.length} installed, ${report.alreadyPresent.length} already present`
+      ) : pc2.yellow(
+        `\u26A0 ${report.installed.length} installed, ${report.alreadyPresent.length} present, ${report.failed.length} failed`
+      )
+    );
+    if (report.failed.length > 0) {
+      p3.note(
+        [
+          report.failed.map((f) => `${pc2.red("\u2022")} ${f.pkg.name}: ${f.reason}`).join("\n"),
+          "",
+          pc2.dim("A partial install usually fails downstream (Docker / Ollama / compose)."),
+          pc2.dim("Install the failed packages manually and re-run with --skip-brew.")
+        ].join("\n"),
+        "Brew failures"
+      );
+      const cont = unwrap(
+        await p3.confirm({
+          message: "Continue anyway? (Default no \u2014 recommended to fix and re-run.)",
+          initialValue: false
+        })
+      );
+      if (!cont) process.exit(1);
+    }
+  }
+  await ensureGhAuth();
+  await promptTailscaleSignin();
+  const repoSpin = p3.spinner();
+  repoSpin.start("Locating your region node repo\u2026");
+  const located = await locateOrCloneRepo({
+    owner,
+    name: repoName,
+    cwd: process.cwd(),
+    ...opts.repoDir ? { explicit: opts.repoDir } : {}
+  });
+  const repoPath = repoPathFromLocate(located);
+  if (!repoPath) {
+    repoSpin.stop(pc2.red("\u2717 Couldn't locate or clone the region repo."));
+    handleLocateError(located, owner, repoName);
+    process.exit(1);
+  }
+  repoSpin.stop(
+    located.kind === "cloned" ? pc2.green(`\u2713 Cloned ${owner}/${repoName} to ${repoPath}`) : pc2.green(`\u2713 Found region repo at ${repoPath}`)
+  );
+  const op = await detectOp();
+  if (!op.installed || !op.signedIn) {
+    p3.cancel(
+      "1Password CLI not installed or not signed in. Run `op signin` and re-run bootstrap. (Or paste pgsodium key + Tunnel token by hand \u2014 manual path not in v0.1.)"
+    );
+    process.exit(1);
+  }
+  const keyTitle = `opuspopuli-${region}-pgsodium-root-key`;
+  const tunnelTitle = `opuspopuli-${region}-tunnel-token`;
+  const vaultArg = opts.vault ? { vault: opts.vault } : {};
+  const opSpin = p3.spinner();
+  opSpin.start("Reading pgsodium key + Tunnel token from 1Password\u2026");
+  const pgsodiumKey = await readSecretFromOp({ title: keyTitle, ...vaultArg });
+  const tunnelToken = await readSecretFromOp({ title: tunnelTitle, ...vaultArg });
+  if (!pgsodiumKey || !tunnelToken) {
+    opSpin.stop(pc2.red("\u2717 Required 1Password items missing."));
+    const missing = [
+      pgsodiumKey ? null : keyTitle,
+      tunnelToken ? null : tunnelTitle
+    ].filter(Boolean);
+    p3.cancel(
+      `Missing in 1Password (vault: ${opts.vault ?? "Private"}): ${missing.join(", ")}. Run \`create-op-node init\` first, or pass --vault if your items live elsewhere.`
+    );
+    process.exit(1);
+  }
+  if (!PGSODIUM_KEY_RE.test(pgsodiumKey)) {
+    opSpin.stop(pc2.red("\u2717 pgsodium item exists but isn't a 64-hex key."));
+    p3.cancel("Inspect the item in 1Password; it should be 64 lowercase hex characters.");
+    process.exit(1);
+  }
+  opSpin.stop(pc2.green("\u2713 Secrets read from 1Password."));
+  if (!opts.skipLaunchAgent) {
+    const laSpin = p3.spinner();
+    laSpin.start("Writing pgsodium key file + LaunchAgent plist\u2026");
+    const la = await setupLaunchAgent({ pgsodiumKey, tunnelToken });
+    if (!la.ok) {
+      laSpin.stop(pc2.red(`\u2717 LaunchAgent step ${la.step} failed.`));
+      p3.cancel(la.reason ?? "LaunchAgent setup failed.");
+      process.exit(1);
+    }
+    laSpin.stop(pc2.green(`\u2713 LaunchAgent loaded (${la.paths.plistFile}).`));
+  }
+  const ghcrSpin = p3.spinner();
+  ghcrSpin.start("Authenticating Docker to ghcr.io\u2026");
+  const ghcr = await loginToGhcr();
+  if (!ghcr.ok) {
+    ghcrSpin.stop(pc2.red("\u2717 ghcr.io login failed."));
+    p3.cancel(ghcr.reason ?? "ghcr.io login failed.");
+    process.exit(1);
+  }
+  ghcrSpin.stop(pc2.green("\u2713 Logged in to ghcr.io."));
+  if (!opts.skipOllama) {
+    const olSpin = p3.spinner();
+    olSpin.start("Pulling + warming Ollama models\u2026");
+    let olHealth = await checkOllamaHealth();
+    if (!olHealth.reachable) {
+      olSpin.message("Ollama not reachable \u2014 running `brew services start ollama`\u2026");
+      const start = await startOllamaService();
+      if (!start.ok) {
+        olSpin.stop(pc2.red("\u2717 Couldn't start Ollama service."));
+        p3.cancel(
+          `${start.reason ?? "unknown"} \u2014 start it manually with \`brew services start ollama\` and re-run with --skip-brew --skip-launch-agent.`
+        );
+        process.exit(1);
+      }
+      await new Promise((res) => setTimeout(res, 3e3));
+      olHealth = await checkOllamaHealth();
+      if (!olHealth.reachable) {
+        olSpin.stop(
+          pc2.yellow("\u26A0 Ollama service started but daemon not yet answering on :11434.")
+        );
+        p3.cancel(
+          "Give it another few seconds, then re-run with --skip-brew --skip-launch-agent."
+        );
+        process.exit(1);
+      }
+    }
+    const modelReport = await setupModels(DEFAULT_MODELS, (model, status) => {
+      olSpin.message(`${status}: ${model}`);
+    });
+    olSpin.stop(
+      modelReport.failed.length === 0 ? pc2.green(
+        `\u2713 ${modelReport.pulled.length} pulled, ${modelReport.alreadyPresent.length} present, ${modelReport.warmed.length} warmed`
+      ) : pc2.yellow(`\u26A0 ${modelReport.failed.length} model pull(s) failed`)
+    );
+    const probe = await probeHostDockerInternal();
+    if (!probe.ok) {
+      p3.note(`${pc2.yellow("\u26A0")} ${probe.reason}`, "Docker host networking");
+    }
+  }
+  if (opts.skipStack) {
+    p3.outro(
+      pc2.cyan(
+        `Stack-up skipped. Run \`docker compose -f ${(opts.composeFile ?? ["docker-compose-prod.yml"]).join(" -f ")} pull && up -d\` from ${repoPath} when ready.`
+      )
+    );
+    return;
+  }
+  const composeFiles = resolveComposeFiles(repoPath, opts.composeFile);
+  const composeOpts = {
+    files: composeFiles,
+    cwd: repoPath,
+    ...opts.envFile ? { envFile: opts.envFile } : {}
+  };
+  const pullSpin = p3.spinner();
+  pullSpin.start("Pulling images from ghcr.io\u2026");
+  const pull = await composePull(composeOpts);
+  if (!pull.ok) {
+    pullSpin.stop(pc2.red("\u2717 compose pull failed."));
+    p3.cancel(pull.reason ?? "compose pull failed.");
+    process.exit(1);
+  }
+  pullSpin.stop(pc2.green("\u2713 Images pulled."));
+  const upSpin = p3.spinner();
+  upSpin.start("Starting the stack\u2026");
+  const up = await composeUp(composeOpts);
+  if (!up.ok) {
+    upSpin.stop(pc2.red("\u2717 compose up failed."));
+    p3.cancel(up.reason ?? "compose up failed.");
+    process.exit(1);
+  }
+  upSpin.stop(pc2.green("\u2713 Containers started \u2014 waiting for healthy\u2026"));
+  const healthSpin = p3.spinner();
+  healthSpin.start("Polling for healthy containers (5s, up to 5 minutes)\u2026");
+  const outcome = await waitForHealthy(composeOpts, {
+    onPoll: (snaps) => {
+      const healthy = snaps.filter((s) => s.health === "healthy").length;
+      const running = snaps.filter((s) => s.state === "running").length;
+      healthSpin.message(`${healthy}/${running} healthy`);
+    }
+  });
+  switch (outcome.kind) {
+    case "healthy":
+      healthSpin.stop(pc2.green(`\u2713 All ${outcome.snapshots.length} containers healthy.`));
+      p3.outro(
+        pc2.cyan(
+          `Region ${region} is up. Next: verify off-LAN with \`npx create-op-node verify --domain <your-domain>\`.`
+        )
+      );
+      return;
+    case "unhealthy":
+      healthSpin.stop(pc2.red(`\u2717 ${outcome.problem}`));
+      p3.note(
+        outcome.snapshots.map((s) => `  ${kvHealth(s.health)} ${s.name} (${s.state})`).join("\n"),
+        "Container state"
+      );
+      p3.cancel(
+        `Inspect with \`docker compose -f ${composeFiles.join(" -f ")} logs\`. Fix and re-run.`
+      );
+      process.exit(1);
+    // eslint-disable-next-line no-fallthrough
+    case "timeout":
+      healthSpin.stop(pc2.yellow("\u26A0 Timed out waiting for all containers to report healthy."));
+      p3.note(
+        outcome.snapshots.map((s) => `  ${kvHealth(s.health)} ${s.name} (${s.state})`).join("\n"),
+        "Container state at timeout"
+      );
+      p3.cancel(
+        `Re-run \`create-op-node bootstrap --skip-brew --skip-launch-agent --skip-ollama\` to skip the already-done phases and poll again once containers settle.`
+      );
+      process.exit(1);
+    // eslint-disable-next-line no-fallthrough
+    default: {
+      return;
+    }
+  }
+});
+function resolveComposeFiles(repoPath, composeFile) {
+  const inputs = composeFile ?? ["docker-compose-prod.yml"];
+  return inputs.map((f) => f.startsWith("/") ? f : join(repoPath, f));
+}
+function kvBool(b) {
+  return b ? pc2.green("on") : pc2.yellow("off");
+}
+function kvFileVault(v) {
+  if (v === "unknown") return pc2.dim("unknown");
+  return v ? pc2.green("on") : pc2.dim("off");
+}
+function kvHealth(h) {
+  switch (h) {
+    case "healthy":
+      return pc2.green("\u2713");
+    case "unhealthy":
+      return pc2.red("\u2717");
+    case "starting":
+      return pc2.yellow("\u2026");
+    case "none":
+      return pc2.dim("-");
+  }
+}
+function repoPathFromLocate(out) {
+  if (out.kind === "found" || out.kind === "cloned") return out.path;
+  return null;
+}
+function handleLocateError(out, owner, name) {
+  switch (out.kind) {
+    case "explicit-not-a-node-repo":
+      p3.cancel(
+        `${out.path} doesn't look like a node repo (missing one of docker-compose-prod.yml / supabase/init/pgsodium_getkey_env.sh). Point --repo-dir at the right place.`
+      );
+      return;
+    case "gh-not-installed":
+      p3.cancel("`gh` not installed \u2014 install via `brew install gh` and re-run.");
+      return;
+    case "clone-failed":
+      p3.cancel(
+        `Couldn't clone ${owner}/${name}: ${out.reason}. Check repo exists + you have access.`
+      );
+      return;
+    case "clone-disallowed":
+      p3.cancel(
+        "No checked-out node repo found and --no-clone (or similar) was set. Provide --repo-dir."
+      );
+      return;
+    case "found":
+    case "cloned":
+      return;
+    default: {
+      return;
+    }
+  }
+}
+async function ensureGhAuth() {
+  const status = await safeExeca("gh", ["auth", "status"]);
+  if (status === null) {
+    p3.cancel("`gh` not on PATH. Install via `brew install gh` and re-run.");
+    process.exit(1);
+  }
+  if (status.exitCode === 0) return;
+  const detail = (status.stderr || status.stdout).trim();
+  p3.note(
+    [
+      "`gh` is not signed in (or signed in to a different account / missing scope).",
+      detail ? "" : void 0,
+      detail ? pc2.dim(detail) : void 0,
+      "",
+      "In another shell:",
+      "",
+      pc2.cyan("gh auth login --web"),
+      "",
+      pc2.dim("Then come back and press Enter.")
+    ].filter((l) => typeof l === "string").join("\n"),
+    "Manual step"
+  );
+  unwrap(await p3.confirm({ message: "gh signed in?", initialValue: true }));
+}
+async function promptTailscaleSignin() {
+  const status = await safeExeca("tailscale", ["status"]);
+  if (status !== null && status.exitCode === 0) return;
+  p3.note(
+    [
+      "Tailscale needs to be signed in (or you can skip \u2014 Tailscale is",
+      "optional; it provides out-of-band SSH from your laptop. The rest",
+      "of the bootstrap continues without it).",
+      "",
+      "In another shell:",
+      "",
+      pc2.cyan("tailscale up"),
+      "",
+      pc2.dim("Accept the device on your tailnet, then come back and press Enter.")
+    ].join("\n"),
+    "Manual step"
+  );
+  unwrap(await p3.confirm({ message: "Tailscale signed in (or skipped)?", initialValue: true }));
+}
+var REGION_RE = /^[a-z0-9-]{2,32}$/;
+var RESET_PHASES = {
+  STOP_STACK: "Stop stack",
+  LAUNCH_AGENT: "LaunchAgent",
+  DOCKER_LOGOUT: "docker logout"
+};
+var DEFAULT_DEPS = {
+  composeDown,
+  teardownLaunchAgent,
+  dockerLogout
+};
+async function runReset(input, deps = DEFAULT_DEPS) {
+  const phases = [];
+  const push = (ph) => {
+    phases.push(ph);
+    deps.onPhase?.(ph);
+  };
+  if (!input.stack) {
+    push({
+      name: RESET_PHASES.STOP_STACK,
+      status: "skipped",
+      detail: "--skip-stack or no repo path resolved"
+    });
+  } else if (input.dryRun) {
+    push({
+      name: RESET_PHASES.STOP_STACK,
+      status: "dry-run",
+      detail: `would run: docker compose -f ${input.stack.composeFiles.join(" -f ")} down${input.stack.wipeVolumes ? " -v" : ""}${input.stack.removeOrphans ? " --remove-orphans" : ""}`
+    });
+  } else {
+    const result2 = await deps.composeDown({
+      files: input.stack.composeFiles,
+      cwd: input.stack.repoPath,
+      ...input.stack.envFile ? { envFile: input.stack.envFile } : {},
+      wipeVolumes: input.stack.wipeVolumes,
+      removeOrphans: input.stack.removeOrphans
+    });
+    if (result2.ok) {
+      push({
+        name: RESET_PHASES.STOP_STACK,
+        status: "ok",
+        detail: input.stack.wipeVolumes ? "volumes destroyed" : "containers stopped, volumes preserved"
+      });
+    } else {
+      push({ name: RESET_PHASES.STOP_STACK, status: "fail", detail: result2.reason ?? "unknown failure" });
+    }
+  }
+  if (!input.launchAgent) {
+    push({ name: RESET_PHASES.LAUNCH_AGENT, status: "skipped", detail: "--skip-launch-agent or no plist found" });
+  } else if (input.dryRun) {
+    push({
+      name: RESET_PHASES.LAUNCH_AGENT,
+      status: "dry-run",
+      detail: `would unload ${input.launchAgent.paths.plistFile}, rm plist${input.launchAgent.keepKeyFile ? "" : " + key file"}`
+    });
+  } else {
+    const result2 = await deps.teardownLaunchAgent(
+      input.launchAgent.paths,
+      { keepKeyFile: input.launchAgent.keepKeyFile }
+    );
+    if (result2.ok) {
+      const removed = result2.steps.filter((s) => s.step !== "unload").map((s) => s.step).join(", ");
+      push({ name: RESET_PHASES.LAUNCH_AGENT, status: "ok", detail: `unloaded + ${removed}` });
+    } else {
+      const fail = result2.steps.find((s) => !s.ok);
+      push({
+        name: RESET_PHASES.LAUNCH_AGENT,
+        status: "fail",
+        detail: `${fail?.step}: ${fail?.reason ?? "unknown"}`
+      });
+    }
+  }
+  if (!input.dockerLogout) {
+    push({ name: RESET_PHASES.DOCKER_LOGOUT, status: "skipped", detail: "--skip-docker-logout" });
+  } else if (input.dryRun) {
+    push({
+      name: RESET_PHASES.DOCKER_LOGOUT,
+      status: "dry-run",
+      detail: `would run: docker logout ${input.dockerLogout.registry}`
+    });
+  } else {
+    const result2 = await deps.dockerLogout(input.dockerLogout.registry);
+    if (result2.ok) {
+      push({
+        name: RESET_PHASES.DOCKER_LOGOUT,
+        status: "ok",
+        detail: `credentials removed from ${input.dockerLogout.registry}`
+      });
+    } else {
+      push({ name: RESET_PHASES.DOCKER_LOGOUT, status: "warn", detail: result2.reason ?? "unknown" });
+    }
+  }
+  return { phases };
+}
+async function fileExists2(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function phaseIcon(ph) {
+  switch (ph.status) {
+    case "ok":
+      return pc2.green("\u2713");
+    case "warn":
+      return pc2.yellow("\u26A0");
+    case "skipped":
+      return pc2.dim("\xB7");
+    case "dry-run":
+      return pc2.cyan("?");
+    case "fail":
+      return pc2.red("\u2717");
+  }
+}
+var resetCommand = new Command("reset").description(
+  "Reverse the Mac Studio side of bootstrap: stop containers, unload the LaunchAgent, remove the pgsodium key file. Preserves docker volumes by default \u2014 pass --wipe-data for a full data nuke (requires retyping the region label)."
+).addOption(new Option("--region <slug>", "Region label (used for --wipe-data confirmation + finding the repo)")).addOption(new Option("--owner <owner>", "GitHub owner for the node repo").default("OpusPopuli")).addOption(new Option("--repo-dir <path>", "Explicit path to a checked-out node repo")).addOption(
+  new Option(
+    "--compose-file <path>",
+    "Repeatable. Compose file relative to repo root. Default: docker-compose-prod.yml"
+  ).default(["docker-compose-prod.yml"])
+).addOption(new Option("--env-file <path>", "Compose --env-file. Default: .env.production")).addOption(
+  new Option(
+    "--wipe-data",
+    "DESTROYS docker volumes (adds -v to `compose down`). Requires retyping the region label as confirmation. Default off \u2014 volumes preserved."
+  ).default(false)
+).addOption(
+  new Option(
+    "--no-remove-orphans",
+    "Do NOT pass --remove-orphans to compose down. Preserves containers from compose files no longer included."
+  )
+).addOption(new Option("--skip-stack", "Don't touch docker compose").default(false)).addOption(new Option("--skip-launch-agent", "Don't touch the LaunchAgent").default(false)).addOption(
+  new Option(
+    "--keep-key-file",
+    "Preserve the pgsodium key file (only matters when LaunchAgent teardown runs). Useful as belt-and-suspenders backup before a wipe-data run."
+  ).default(false)
+).addOption(new Option("--skip-docker-logout", "Don't run `docker logout`").default(false)).addOption(new Option("--registry <registry>", "Registry to log out of").default(GHCR_REGISTRY)).addOption(new Option("--dry-run", "Show what would happen without acting").default(false)).addOption(new Option("-y, --yes", "Skip non-destructive confirmations (wipe still confirms)").default(false)).action(async (opts) => {
+  p3.intro(pc2.bgCyan(pc2.black(" create-op-node reset ")));
+  const wipeData = opts.wipeData ?? false;
+  const removeOrphans = opts.removeOrphans ?? true;
+  const region = opts.region ? opts.region : unwrap(
+    await p3.text({
+      message: "Region label (the slug used during init \u2014 e.g. us-ca)?",
+      placeholder: "us-ca",
+      validate: (v) => REGION_RE.test(v ?? "") ? void 0 : "lowercase letters, digits, hyphens; 2\u201332 chars"
+    })
+  );
+  if (!REGION_RE.test(region)) {
+    p3.cancel(`--region ${JSON.stringify(region)} is not a valid region slug.`);
+    process.exit(2);
+  }
+  const owner = opts.owner ?? "OpusPopuli";
+  const repoName = `opuspopuli-node-${region}`;
+  const launchAgentPaths = defaultPaths();
+  const plistExists = await fileExists2(launchAgentPaths.plistFile);
+  const keyFileExists = await fileExists2(launchAgentPaths.keyFile);
+  let repoPath;
+  let stackSkipReason;
+  if (!opts.skipStack) {
+    const located = await locateOrCloneRepo({
+      owner,
+      name: repoName,
+      cwd: process.cwd(),
+      allowClone: false,
+      ...opts.repoDir ? { explicit: opts.repoDir } : {}
+    });
+    switch (located.kind) {
+      case "found":
+        repoPath = located.path;
+        break;
+      case "explicit-not-a-node-repo":
+        p3.cancel(
+          `--repo-dir ${JSON.stringify(located.path)} doesn't look like a node repo (missing one of: ${NODE_REPO_MARKERS.join(", ")}). Verify the path or drop --repo-dir to let reset search the cwd.`
+        );
+        process.exit(2);
+        break;
+      case "clone-disallowed":
+        stackSkipReason = `no checkout found at ${process.cwd()}; pass --repo-dir to target one`;
+        break;
+      case "cloned":
+      case "gh-not-installed":
+      case "clone-failed":
+        stackSkipReason = `unexpected outcome ${located.kind} from locateOrCloneRepo with allowClone=false`;
+        break;
+    }
+  } else {
+    stackSkipReason = "--skip-stack";
+  }
+  let runningContainers = null;
+  if (repoPath) {
+    runningContainers = await composePs({
+      files: resolveComposeFiles(repoPath, opts.composeFile),
+      ...opts.envFile ? { envFile: opts.envFile } : {}
+    });
+  }
+  p3.note(
+    [
+      `Region:                ${pc2.cyan(region)}`,
+      `Repo path:             ${repoPath ? pc2.cyan(repoPath) : pc2.dim(`not used (${stackSkipReason ?? "no repo path resolved"})`)}`,
+      `Running containers:    ${runningContainers === null ? pc2.dim("unknown") : runningContainers.length === 0 ? pc2.dim("none") : pc2.cyan(`${runningContainers.length} listed by compose ps`)}`,
+      `LaunchAgent plist:     ${plistExists ? pc2.cyan(launchAgentPaths.plistFile) : pc2.dim("not present")}`,
+      `pgsodium key file:     ${keyFileExists ? pc2.cyan(launchAgentPaths.keyFile) : pc2.dim("not present")}`,
+      `Registry to log out:   ${pc2.cyan(opts.registry ?? GHCR_REGISTRY)}`,
+      `Volume policy:         ${wipeData ? pc2.red("WIPE") : pc2.green("preserve (default)")}`,
+      `Dry run:               ${opts.dryRun ? pc2.yellow("yes") : pc2.dim("no")}`
+    ].join("\n"),
+    "Snapshot"
+  );
+  if (wipeData && !opts.dryRun) {
+    unwrap(
+      await p3.text({
+        message: pc2.red(`Type the region label to confirm WIPING all volumes (the slug you'd use with --region):`),
+        validate: (v) => v === region ? void 0 : `must match the region label exactly`
+      })
+    );
+  } else if (!opts.dryRun && !opts.yes) {
+    const cont = unwrap(
+      await p3.confirm({
+        message: "Proceed with reset? (volumes will be preserved)",
+        initialValue: true
+      })
+    );
+    if (!cont) {
+      p3.cancel("Cancelled.");
+      process.exit(0);
+    }
+  }
+  const stack = repoPath ? {
+    repoPath,
+    composeFiles: resolveComposeFiles(repoPath, opts.composeFile),
+    wipeVolumes: wipeData,
+    removeOrphans,
+    ...opts.envFile ? { envFile: opts.envFile } : {}
+  } : void 0;
+  const launchAgent = plistExists && !opts.skipLaunchAgent ? {
+    paths: launchAgentPaths,
+    keepKeyFile: opts.keepKeyFile ?? false
+  } : void 0;
+  const dockerLogoutInput = !opts.skipDockerLogout ? { registry: opts.registry ?? GHCR_REGISTRY } : void 0;
+  const phaseSpins = /* @__PURE__ */ new Map();
+  const actingPhases = [];
+  if (stack && !opts.dryRun) actingPhases.push(RESET_PHASES.STOP_STACK);
+  if (launchAgent && !opts.dryRun) actingPhases.push(RESET_PHASES.LAUNCH_AGENT);
+  if (dockerLogoutInput && !opts.dryRun) actingPhases.push(RESET_PHASES.DOCKER_LOGOUT);
+  for (const name of actingPhases) {
+    const s = p3.spinner();
+    s.start(`${name}\u2026`);
+    phaseSpins.set(name, s);
+  }
+  const renderPhase = (ph) => {
+    const spin = phaseSpins.get(ph.name);
+    const line = `${phaseIcon(ph)} ${ph.name}: ${pc2.dim(ph.detail)}`;
+    if (spin) {
+      spin.stop(line);
+      phaseSpins.delete(ph.name);
+    } else {
+      p3.log.info(line);
+    }
+  };
+  const report = await runReset(
+    {
+      ...stack ? { stack } : {},
+      ...launchAgent ? { launchAgent } : {},
+      ...dockerLogoutInput ? { dockerLogout: dockerLogoutInput } : {},
+      dryRun: opts.dryRun ?? false
+    },
+    { ...DEFAULT_DEPS, onPhase: renderPhase }
+  );
+  for (const [, spin] of phaseSpins) spin.stop(pc2.dim("\u2014 skipped"));
+  const failed = report.phases.filter((ph) => ph.status === "fail").length;
+  if (failed > 0) {
+    p3.outro(pc2.red(`${failed} step${failed === 1 ? "" : "s"} failed.`));
+    process.exit(1);
+  } else if (opts.dryRun) {
+    p3.outro(pc2.cyan("Dry run complete. Re-run without --dry-run to apply."));
+  } else {
+    p3.outro(
+      pc2.green(
+        wipeData ? `Reset complete \u2014 volumes wiped. Re-run \`create-op-node bootstrap --region ${region}\` to start fresh.` : `Reset complete \u2014 volumes preserved. Re-run \`create-op-node bootstrap --region ${region}\` to bring the stack back up.`
+      )
+    );
+  }
+});
+
+// src/lib/cosign.ts
+var COSIGN_OIDC_ISSUER = "https://token.actions.githubusercontent.com";
+var DEFAULT_IDENTITY_REGEXP = "^https://github\\.com/OpusPopuli/opuspopuli/\\.github/workflows/.*$";
+async function cosignVerifyImage(input) {
+  const idRegex = input.certificateIdentityRegexp ?? DEFAULT_IDENTITY_REGEXP;
+  const issuer = input.certificateOidcIssuer ?? COSIGN_OIDC_ISSUER;
+  const res = await safeExeca("cosign", [
+    "verify",
+    "--certificate-identity-regexp",
+    idRegex,
+    "--certificate-oidc-issuer",
+    issuer,
+    input.image
+  ]);
+  if (res === null) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: "`cosign` not on PATH (install with `brew install cosign` and rerun to enable signature checks)"
+    };
+  }
+  if (res.exitCode !== 0) {
+    return {
+      ok: false,
+      skipped: false,
+      reason: `cosign verify ${input.image} failed (${res.exitCode ?? "signal"}): ${res.stderr || res.stdout}`
+    };
+  }
+  return { ok: true, output: res.stdout || res.stderr };
+}
+
+// src/lib/http.ts
+var GRAPHQL_ACCEPT = "application/graphql-response+json, application/json";
+async function readBodyCapped(res) {
+  const text6 = await res.text();
+  return text6.slice(0, BODY_PREVIEW_MAX);
+}
+async function httpProbe(input) {
+  const expected = input.expectedStatus ?? 200;
+  const timeoutMs = input.timeoutMs ?? VERIFY_NETWORK_TIMEOUT_MS;
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(input.url, { method: "GET", signal: ctrl.signal });
+    const bodyPreview = await readBodyCapped(res);
+    if (res.status !== expected) {
+      return {
+        ok: false,
+        status: res.status,
+        reason: bodyPreview ? `expected HTTP ${expected}, got ${res.status}: ${bodyPreview}` : `expected HTTP ${expected}, got ${res.status}`
+      };
+    }
+    return { ok: true, status: res.status, bodyPreview };
+  } catch (err) {
+    const reason = err.name === "AbortError" ? `GET ${input.url} timed out after ${timeoutMs}ms` : `GET ${input.url} failed: ${err.message}`;
+    return { ok: false, reason };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function graphqlProbe(input) {
+  const timeoutMs = input.timeoutMs ?? VERIFY_NETWORK_TIMEOUT_MS;
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(input.url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: GRAPHQL_ACCEPT },
+      body: JSON.stringify({ query: "{ __typename }" }),
+      signal: ctrl.signal
+    });
+    const text6 = await readBodyCapped(res);
+    if (res.status !== 200) {
+      return {
+        ok: false,
+        status: res.status,
+        reason: `expected HTTP 200, got ${res.status}: ${text6}`
+      };
+    }
+    let envelope;
+    try {
+      envelope = JSON.parse(text6);
+    } catch {
+      return {
+        ok: false,
+        status: res.status,
+        reason: `response was not JSON: ${text6}`
+      };
+    }
+    const data = envelope.data;
+    const typename = data?.__typename;
+    if (typeof typename !== "string") {
+      return {
+        ok: false,
+        status: res.status,
+        reason: `response missing { data: { __typename: string } }: ${text6}`
+      };
+    }
+    return { ok: true, typename };
+  } catch (err) {
+    const reason = err.name === "AbortError" ? `POST ${input.url} timed out after ${timeoutMs}ms` : `POST ${input.url} failed: ${err.message}`;
+    return { ok: false, reason };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function first(v) {
+  if (v === void 0) return void 0;
+  return Array.isArray(v) ? v[0] : v;
+}
+function tlsHandshake(input) {
+  const host = input.host;
+  const port = input.port ?? 443;
+  const timeoutMs = input.timeoutMs ?? VERIFY_NETWORK_TIMEOUT_MS;
+  const connect2 = input.connect ?? tls.connect;
+  const now = input.now ?? /* @__PURE__ */ new Date();
+  return new Promise((resolve2) => {
+    let socket;
+    let settled = false;
+    const settle = (r) => {
+      if (settled) return;
+      settled = true;
+      socket?.destroy();
+      resolve2(r);
+    };
+    try {
+      socket = connect2({
+        host,
+        port,
+        servername: host,
+        timeout: timeoutMs
+      });
+    } catch (err) {
+      settle({ ok: false, reason: `tls.connect to ${host}:${port} threw: ${err.message}` });
+      return;
+    }
+    socket.once("secureConnect", () => {
+      const cert = socket.getPeerCertificate(false);
+      if (!cert || Object.keys(cert).length === 0) {
+        settle({ ok: false, reason: "TLS connected but peer presented no certificate" });
+        return;
+      }
+      const notAfter = new Date(cert.valid_to);
+      if (Number.isNaN(notAfter.getTime())) {
+        settle({ ok: false, reason: `cert presented an unparseable notAfter: ${cert.valid_to}` });
+        return;
+      }
+      const msPerDay = 1e3 * 60 * 60 * 24;
+      const daysToExpiry = Math.floor((notAfter.getTime() - now.getTime()) / msPerDay);
+      const subject = first(cert.subject?.CN) ?? "<no CN>";
+      const issuer = first(cert.issuer?.O) ?? first(cert.issuer?.CN) ?? "<no issuer>";
+      settle({ ok: true, subject, issuer, daysToExpiry });
+    });
+    socket.once("timeout", () => {
+      settle({ ok: false, reason: `TLS handshake to ${host}:${port} timed out after ${timeoutMs}ms` });
+    });
+    socket.once("error", (err) => {
+      settle({ ok: false, reason: `TLS handshake to ${host}:${port} failed: ${err.message}` });
+    });
+  });
+}
+
+// src/commands/verify.ts
+var DOMAIN_RE = /^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/i;
+function summarize(report) {
+  let failed = 0;
+  let warned = 0;
+  for (const ph of report.phases) {
+    if (ph.status === "fail") failed++;
+    if (ph.status === "warn") warned++;
+  }
+  return { ok: failed === 0, failed, warned };
+}
+function formatExpiry(days) {
+  if (days < 0) return `expired ${-days}d ago`;
+  if (days === 0) return "expires today";
+  return `${days}d to expiry`;
+}
+var DEFAULT_DEPS2 = {
+  tls: tlsHandshake,
+  http: httpProbe,
+  graphql: graphqlProbe,
+  tunnel: tunnelStatus,
+  cosign: cosignVerifyImage
+};
+async function runVerify(input, deps = DEFAULT_DEPS2) {
+  const phases = [];
+  const push = (ph) => {
+    phases.push(ph);
+    deps.onPhase?.(ph);
+  };
+  const tls2 = await deps.tls({ host: input.apiHost });
+  if (!tls2.ok) {
+    push({ name: "TLS handshake", status: "fail", detail: tls2.reason });
+  } else {
+    const line = `subject=${tls2.subject}, issuer=${tls2.issuer}, ${formatExpiry(tls2.daysToExpiry)}`;
+    const warn = tls2.daysToExpiry < input.certWarnDays;
+    if (warn) {
+      push({
+        name: "TLS handshake",
+        status: "warn",
+        detail: tls2.daysToExpiry < 0 ? line : `${line} (< warn threshold ${input.certWarnDays}d)`
+      });
+    } else {
+      push({ name: "TLS handshake", status: "ok", detail: line });
+    }
+  }
+  const healthUrl = `https://${input.apiHost}/health`;
+  const health = await deps.http({ url: healthUrl });
+  if (health.ok) {
+    push({ name: "GET /health", status: "ok", detail: `HTTP ${health.status}` });
+  } else {
+    push({ name: "GET /health", status: "fail", detail: health.reason });
+  }
+  const gqlUrl = `https://${input.apiHost}/api`;
+  const gql = await deps.graphql({ url: gqlUrl });
+  if (gql.ok) {
+    push({ name: "GraphQL { __typename }", status: "ok", detail: `typename=${gql.typename}` });
+  } else {
+    push({ name: "GraphQL { __typename }", status: "fail", detail: gql.reason });
+  }
+  const cfFields = [
+    ["--cf-token", input.cf?.token],
+    ["--cf-account-id", input.cf?.accountId],
+    ["--tunnel-id", input.cf?.tunnelId]
+  ];
+  const cfSet = cfFields.filter(([, v]) => v !== void 0 && v !== "");
+  if (cfSet.length === 0) {
+    push({
+      name: "Cloudflare Tunnel",
+      status: "skipped",
+      detail: "pass --cf-token + --cf-account-id + --tunnel-id to enable"
+    });
+  } else if (cfSet.length < cfFields.length) {
+    const missing = cfFields.filter(([, v]) => v === void 0 || v === "").map(([name]) => name).join(", ");
+    push({
+      name: "Cloudflare Tunnel",
+      status: "warn",
+      detail: `partial CF config \u2014 missing ${missing}; check skipped`
+    });
+  } else {
+    const tun = await deps.tunnel({
+      token: input.cf.token,
+      accountId: input.cf.accountId,
+      tunnelId: input.cf.tunnelId
+    });
+    if (!tun.ok) {
+      push({ name: "Cloudflare Tunnel", status: "fail", detail: tun.reason });
+    } else if (tun.connections === 0) {
+      push({
+        name: "Cloudflare Tunnel",
+        status: "warn",
+        detail: `status=${tun.status}, 0 connections \u2014 cloudflared on the Studio appears offline`
+      });
+    } else {
+      push({
+        name: "Cloudflare Tunnel",
+        status: "ok",
+        detail: `${tun.connections} connections, status=${tun.status}`
+      });
+    }
+  }
+  if (input.images.length === 0) {
+    push({
+      name: "cosign verify",
+      status: "skipped",
+      detail: "pass --image <ref> (repeatable) to enable"
+    });
+  } else {
+    for (const image of input.images) {
+      const cos = await deps.cosign({ image });
+      if (cos.ok) {
+        push({ name: `cosign verify ${image}`, status: "ok", detail: "signature valid" });
+      } else if (cos.skipped) {
+        push({ name: `cosign verify ${image}`, status: "skipped", detail: cos.reason });
+      } else {
+        push({ name: `cosign verify ${image}`, status: "fail", detail: cos.reason });
+      }
+    }
+  }
+  return { phases };
+}
+function readTokenFile(path) {
+  const raw = readFileSync(path, "utf8").trim();
+  if (!raw) throw new Error(`--cf-token-file ${path} was empty`);
+  return raw;
+}
+var verifyCommand = new Command("verify").description(
+  "Off-LAN health probe of a live node \u2014 TLS, Apollo Federation reachability, GraphQL smoke. Run from anywhere with internet access."
+).addOption(
+  new Option("--domain <domain>", "Domain to probe (e.g. example.org \u2192 checks api.example.org)")
+).addOption(new Option("--api-host <host>", "Override the API hostname (default: api.<domain>)")).addOption(new Option("--cf-token <token>", "Cloudflare API token (enables tunnel-status probe)")).addOption(
+  new Option("--cf-token-file <path>", "Read CF token from a file (avoids exposing it via ps)")
+).addOption(new Option("--cf-account-id <id>", "Cloudflare account ID (required with --cf-token)")).addOption(
+  new Option("--tunnel-id <id>", "Cloudflare Tunnel ID to query (required with --cf-token)")
+).addOption(
+  new Option("--image <ref>", "Repeatable. Image to cosign-verify (e.g. ghcr.io/opuspopuli/api:tag)").default(
+    []
+  )
+).addOption(
+  new Option("--cert-warn-days <n>", "Warn if cert expires within N days").default("14")
+).addOption(
+  new Option("--show-skipped", "Include skipped phases in the summary").default(false)
+).action(async (opts) => {
+  p3.intro(pc2.bgCyan(pc2.black(" create-op-node verify ")));
+  const domain = opts.domain ? opts.domain : unwrap(
+    await p3.text({
+      message: "Public domain of the node?",
+      placeholder: "yournode.example.org",
+      validate: (v) => DOMAIN_RE.test(v ?? "") ? void 0 : "lowercase letters, digits, hyphens, dots; must contain a dot and a TLD"
+    })
+  );
+  if (!DOMAIN_RE.test(domain)) {
+    p3.cancel(`--domain ${JSON.stringify(domain)} doesn't look like a domain.`);
+    process.exit(2);
+  }
+  const rawDays = opts.certWarnDays ?? "14";
+  const certWarnDays = Number.parseInt(rawDays, 10);
+  if (!Number.isFinite(certWarnDays) || certWarnDays < 0 || !/^\d+$/.test(rawDays)) {
+    p3.cancel(`--cert-warn-days must be a non-negative integer (got ${JSON.stringify(rawDays)}).`);
+    process.exit(2);
+  }
+  if (opts.cfToken && opts.cfTokenFile) {
+    p3.cancel("Pass either --cf-token or --cf-token-file, not both.");
+    process.exit(2);
+  }
+  let cfToken = opts.cfToken;
+  if (!cfToken && opts.cfTokenFile) {
+    try {
+      cfToken = readTokenFile(opts.cfTokenFile);
+    } catch (err) {
+      p3.cancel(err.message);
+      process.exit(2);
+    }
+  }
+  const apiHost = opts.apiHost ?? `api.${domain}`;
+  const images = opts.image ?? [];
+  const totalPhases = 4 + (images.length === 0 ? 1 : images.length);
+  let phaseIndex = 0;
+  let activeSpin = null;
+  const renderPhase = (ph) => {
+    phaseIndex++;
+    const prefix = `[${phaseIndex}/${totalPhases}] ${ph.name}`;
+    activeSpin?.stop(formatPhaseLine(prefix, ph));
+    activeSpin = null;
+  };
+  const deps = {
+    ...DEFAULT_DEPS2,
+    onPhase: renderPhase
+  };
+  activeSpin = p3.spinner();
+  activeSpin.start("Running checks\u2026");
+  const report = await runVerify(
+    {
+      apiHost,
+      certWarnDays,
+      cf: {
+        ...cfToken ? { token: cfToken } : {},
+        ...opts.cfAccountId ? { accountId: opts.cfAccountId } : {},
+        ...opts.tunnelId ? { tunnelId: opts.tunnelId } : {}
+      },
+      images
+    },
+    deps
+  );
+  activeSpin?.stop("Done.");
+  const visible = opts.showSkipped ?? false ? report.phases : report.phases.filter((ph) => ph.status !== "skipped");
+  const lines = visible.map((ph, i) => {
+    const idx = report.phases.indexOf(ph) + 1;
+    return `${phaseIcon2(ph)} [${idx}/${totalPhases}] ${ph.name}: ${pc2.dim(ph.detail)}`;
+  });
+  const skippedCount = report.phases.length - visible.length;
+  if (skippedCount > 0 && !opts.showSkipped) {
+    lines.push(pc2.dim(`\xB7 ${skippedCount} phase${skippedCount === 1 ? "" : "s"} skipped (run with --show-skipped to see them)`));
+  }
+  p3.note(lines.join("\n"), "Summary");
+  const summary = summarize(report);
+  if (summary.ok) {
+    p3.outro(
+      summary.warned === 0 ? pc2.green("All checks passed.") : pc2.yellow(`Passed with ${summary.warned} warning${summary.warned === 1 ? "" : "s"}.`)
+    );
+  } else {
+    p3.outro(pc2.red(`${summary.failed} check${summary.failed === 1 ? "" : "s"} failed.`));
+    process.exit(1);
+  }
+});
+function phaseIcon2(ph) {
+  switch (ph.status) {
+    case "ok":
+      return pc2.green("\u2713");
+    case "warn":
+      return pc2.yellow("\u26A0");
+    case "skipped":
+      return pc2.dim("\xB7");
+    case "fail":
+      return pc2.red("\u2717");
+  }
+}
+function formatPhaseLine(prefix, ph) {
+  const icon = phaseIcon2(ph);
+  const colorize = ph.status === "ok" ? pc2.green : ph.status === "warn" ? pc2.yellow : ph.status === "skipped" ? pc2.dim : pc2.red;
+  return colorize(`${icon} ${prefix}: ${ph.detail}`);
+}
+
+// src/lib/region-schema.json
+var region_schema_default = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://github.com/OpusPopuli/opuspopuli-regions/schema/region-plugin.schema.json",
+  title: "Region Plugin File",
+  description: "A declarative region configuration file for the Opus Populi civic data platform. A handful of string-valued fields (ApiSourceConfig.queryParams, BulkDownloadConfig.filters) support ${variableName} placeholders that the consumer resolves at runtime \u2014 see those field descriptions for the supported variable list.",
+  type: "object",
+  required: ["name", "displayName", "description", "version", "config"],
+  additionalProperties: false,
+  properties: {
+    name: {
+      type: "string",
+      minLength: 1,
+      description: "Region identifier (e.g., 'california')"
+    },
+    displayName: {
+      type: "string",
+      minLength: 1,
+      description: "Human-readable region name (e.g., 'California')"
+    },
+    description: {
+      type: "string",
+      description: "Brief description of this region's data coverage"
+    },
+    version: {
+      type: "string",
+      pattern: "^\\d+\\.\\d+\\.\\d+$",
+      description: "Semantic version of this config file"
+    },
+    config: {
+      $ref: "#/definitions/DeclarativeRegionConfig"
+    }
+  },
+  definitions: {
+    DeclarativeRegionConfig: {
+      type: "object",
+      required: ["regionId", "regionName", "description", "timezone", "dataSources"],
+      additionalProperties: false,
+      properties: {
+        regionId: {
+          type: "string",
+          minLength: 1,
+          description: "Region identifier (e.g., 'california')"
+        },
+        regionName: {
+          type: "string",
+          minLength: 1,
+          description: "Human-readable region name (e.g., 'California')"
+        },
+        description: {
+          type: "string",
+          description: "Region description"
+        },
+        timezone: {
+          type: "string",
+          description: "IANA timezone (e.g., 'America/Los_Angeles')"
+        },
+        stateCode: {
+          type: "string",
+          pattern: "^[A-Z]{2}$",
+          description: "Two-letter US state code (e.g., 'CA')"
+        },
+        parentRegionId: {
+          type: "string",
+          minLength: 1,
+          description: "Region identifier of this region's parent in the geographic hierarchy. Top-level regions (states, federal) omit this field. Counties set parentRegionId to their state's regionId (e.g., 'california'); cities will set it to their county's regionId. Presence of this field is the canonical signal that a region is a sub-region; the consumer loader uses it to build the region tree."
+        },
+        fipsCode: {
+          type: "string",
+          pattern: "^\\d{2,7}$",
+          description: "Census FIPS code: 2 digits for states (e.g., '06' for CA), 5 digits for counties (e.g., '06037' for Los Angeles County \u2014 state FIPS + county FIPS), 7 digits for places/cities. This is the canonical join key against the consumer's PostGIS counties/places tables used today for user-to-district placement."
+        },
+        dataSources: {
+          type: "array",
+          minItems: 1,
+          items: {
+            $ref: "#/definitions/DataSourceConfig"
+          },
+          description: "Data sources to scrape"
+        },
+        rateLimit: {
+          type: "object",
+          properties: {
+            requestsPerSecond: { type: "number", minimum: 0 },
+            burstSize: { type: "integer", minimum: 1 }
+          },
+          required: ["requestsPerSecond", "burstSize"],
+          additionalProperties: false,
+          description: "Rate limiting defaults"
+        },
+        cacheTtlMs: {
+          type: "integer",
+          minimum: 0,
+          description: "Cache TTL in milliseconds"
+        },
+        requestTimeoutMs: {
+          type: "integer",
+          minimum: 0,
+          description: "Request timeout in milliseconds"
+        },
+        normalizeExternalIdDistrict: {
+          type: "boolean",
+          description: "Strip leading zeros from representative externalId trailing segment (e.g. ca-assembly-01 \u2192 ca-assembly-1). Opt-in; default false. Only needed for regions whose LLM manifests emit zero-padded district numbers."
+        },
+        bioNoisePatterns: {
+          type: "array",
+          items: { type: "string" },
+          description: "Regex pattern strings (case-insensitive) matched against scraped representative bio text. Bios matching any pattern are treated as nav junk and discarded. Defaults to no filtering if omitted."
+        },
+        boundarySources: {
+          $ref: "#/definitions/BoundarySourcesConfig",
+          description: "Civic-boundary geometry sources used to populate the consumer's `jurisdictions` table (counties, cities, state legislative districts, school districts, special districts). The consumer's BoundaryLoaderService reads this block, dispatches to TIGER and ArcGIS FeatureServer fetchers, and upserts on fipsCode/ocdId. Omit when a region has no public boundary data \u2014 addresses still resolve via Census Geocoder string fields, but PostGIS point-in-polygon queries return no matches. See opuspopuli#804."
+        }
+      }
+    },
+    BoundarySourcesConfig: {
+      type: "object",
+      additionalProperties: false,
+      required: ["ocdIdPrefix"],
+      description: "Per-region declarative recipe for loading civic boundaries. Pure config \u2014 no per-region code lives in the consumer.",
+      properties: {
+        ocdIdPrefix: {
+          type: "string",
+          minLength: 1,
+          description: "Open Civic Data ID prefix for this region, e.g. 'ocd-division/country:us/state:ca'. All jurisdiction OCD-IDs are composed as `${ocdIdPrefix}${TigerLayerConfig.ocdIdSegment}` (or the Geoportal equivalent)."
+        },
+        tigerLayers: {
+          type: "array",
+          minItems: 1,
+          items: { $ref: "#/definitions/TigerLayerConfig" },
+          description: "US Census TIGER/Line layers to ingest as jurisdictions. Each entry maps one ArcGIS MapServer layer to a JurisdictionType. Omit the field entirely when the region has no TIGER coverage \u2014 do not pass an empty array (the schema rejects it to prevent silent typos that strip the configured layers)."
+        },
+        geoportalLayers: {
+          type: "array",
+          minItems: 1,
+          items: { $ref: "#/definitions/GeoportalLayerConfig" },
+          description: "Region-specific ArcGIS FeatureServer endpoints \u2014 typically state geoportals serving boundary data Census TIGER doesn't cover (fire districts, water districts, transit districts, etc.). Omit when unused \u2014 empty arrays are rejected (see tigerLayers note)."
+        }
+      }
+    },
+    JurisdictionTypeEnum: {
+      type: "string",
+      enum: ["COUNTY", "CITY", "STATE_SENATE_DISTRICT", "STATE_ASSEMBLY_DISTRICT", "CONGRESSIONAL_DISTRICT", "SCHOOL_DISTRICT_UNIFIED", "SCHOOL_DISTRICT_ELEMENTARY", "SCHOOL_DISTRICT_HIGH", "COMMUNITY_COLLEGE_DISTRICT", "WATER_DISTRICT", "FIRE_DISTRICT", "TRANSIT_DISTRICT", "SPECIAL_DISTRICT"],
+      description: "Maps each feature to a JurisdictionType row in the consumer's `jurisdictions` table. Single source of truth \u2014 TigerLayerConfig and GeoportalLayerConfig both reference this so a new jurisdiction type can't be added to one without the other."
+    },
+    JurisdictionLevelEnum: {
+      type: "string",
+      enum: ["FEDERAL", "STATE", "COUNTY", "MUNICIPAL", "DISTRICT"],
+      description: "Hierarchy level for the resulting jurisdiction rows. Single source of truth \u2014 referenced from TigerLayerConfig and GeoportalLayerConfig."
+    },
+    TigerLayerConfig: {
+      type: "object",
+      additionalProperties: false,
+      required: ["layer", "outFields", "jurisdictionType", "level", "nameField"],
+      description: "One TIGER/Line layer mapped to a JurisdictionType. The consumer hits `https://tigerweb.geo.census.gov/arcgis/rest/services/TIGERweb/${layer}/query` with GeoJSON output. Supported placeholders inside `where`, `ocdIdSegment`, `nameTemplate`: ${fipsCode} (this region's fipsCode), ${stateCode} (two-letter code), ${name} (the layer's nameField value for a given feature), ${district} (the districtField value).",
+      properties: {
+        layer: {
+          type: "string",
+          minLength: 1,
+          description: "TIGER MapServer service+layer path, e.g. 'State_County/MapServer/1', 'Legislative/MapServer/1' (state senate), 'Legislative/MapServer/2' (state assembly), 'School/MapServer/0' (unified school districts)."
+        },
+        where: {
+          type: "string",
+          description: "ESRI WHERE clause filtering features. Defaults to `STATE='${fipsCode}'` when omitted. Use `${fipsCode}` / `${stateCode}` placeholders."
+        },
+        outFields: {
+          type: "string",
+          minLength: 1,
+          description: "Comma-separated TIGER attribute fields to return, e.g. 'GEOID,NAME' or 'GEOID,SLDUST'."
+        },
+        jurisdictionType: {
+          $ref: "#/definitions/JurisdictionTypeEnum"
+        },
+        level: {
+          $ref: "#/definitions/JurisdictionLevelEnum"
+        },
+        nameField: {
+          type: "string",
+          minLength: 1,
+          description: "TIGER attribute key whose value becomes the substitution for `${name}` placeholders. Typically 'NAME' for human-readable layers, or a district code field like 'SLDUST'/'SLDLST' for legislative layers."
+        },
+        fipsField: {
+          type: "string",
+          description: "TIGER attribute key holding the canonical fips_code for an upsert. Defaults to 'GEOID'."
+        },
+        fipsPrefix: {
+          type: "string",
+          description: "Optional prefix prepended to the fipsField value before persisting as fips_code. Use when the raw GEOID would collide with another layer's GEOID (e.g. state senate GEOID overlapping county GEOID format). Example: 'sldu-' for state senate, 'sldl-' for state assembly."
+        },
+        districtField: {
+          type: "string",
+          description: "TIGER attribute key supplying the ${district} placeholder. Required when ocdIdSegment or nameTemplate contains ${district}."
+        },
+        ocdIdSegment: {
+          type: "string",
+          description: "Segment appended to `boundarySources.ocdIdPrefix` to form the full OCD-ID, e.g. '/county:${name}', '/sldu:${district}'. Supports ${name} and ${district} placeholders. Inside `${name}` substitutions the consumer normalizes whitespace to underscores and lowercases the value for OCD-ID compatibility \u2014 so a NAME of 'Alameda County' produces 'alameda_county' in the OCD-ID. Omit when this layer's rows don't carry an OCD-ID."
+        },
+        nameTemplate: {
+          type: "string",
+          description: "Template for the persisted jurisdiction name (NOT for OCD-ID composition). Supports ${name}, ${district}, ${stateCode}. The ${name} value is substituted verbatim (case + whitespace preserved). Defaults to ${name} when omitted."
+        }
+      }
+    },
+    GeoportalLayerConfig: {
+      type: "object",
+      additionalProperties: false,
+      required: ["url", "outFields", "jurisdictionType", "level", "nameField"],
+      description: "One arbitrary ArcGIS FeatureServer layer for jurisdictions Census TIGER doesn't cover. Same placeholder rules as TigerLayerConfig.",
+      properties: {
+        url: {
+          type: "string",
+          format: "uri",
+          pattern: "^https://",
+          description: "Full ArcGIS FeatureServer layer URL ending in /FeatureServer/<n>. Must be HTTPS \u2014 the consumer rejects other schemes. The consumer paginates via resultOffset/resultRecordCount."
+        },
+        where: {
+          type: "string",
+          description: "ESRI WHERE clause. Defaults to '1=1'."
+        },
+        outFields: {
+          type: "string",
+          minLength: 1,
+          description: "Comma-separated FeatureServer attribute fields to return."
+        },
+        jurisdictionType: {
+          $ref: "#/definitions/JurisdictionTypeEnum"
+        },
+        level: {
+          $ref: "#/definitions/JurisdictionLevelEnum"
+        },
+        nameField: {
+          type: "string",
+          minLength: 1,
+          description: "FeatureServer attribute key supplying the human-readable name and the ${name} placeholder."
+        },
+        fipsField: {
+          type: "string",
+          description: "FeatureServer attribute key used as fips_code. No default \u2014 geoportal attribute names vary widely (no GEOID convention). Omit when the layer has no FIPS analog; the upsert then matches on ocdId only."
+        },
+        fipsPrefix: {
+          type: "string",
+          description: "Optional prefix prepended to fipsField, mirroring TigerLayerConfig.fipsPrefix."
+        },
+        ocdIdSegment: {
+          type: "string",
+          description: "Appended to boundarySources.ocdIdPrefix. Supports ${name} placeholder. Same OCD-ID normalization as TigerLayerConfig.ocdIdSegment \u2014 whitespace to underscores, lowercased."
+        },
+        nameTemplate: {
+          type: "string",
+          description: "Template for persisted name (NOT for OCD-ID). ${name} substituted verbatim. Defaults to ${name}."
+        }
+      }
+    },
+    DataSourceConfig: {
+      type: "object",
+      required: ["url", "dataType", "contentGoal"],
+      additionalProperties: false,
+      properties: {
+        url: {
+          type: "string",
+          format: "uri",
+          description: "URL to fetch data from"
+        },
+        dataType: {
+          type: "string",
+          enum: ["propositions", "meetings", "representatives", "campaign_finance", "lobbying", "civics", "bills"],
+          description: "What type of content this source provides. Daily journals / meeting minutes go under 'meetings' with sourceType=pdf_archive \u2014 the consumer partitions by sourceType internally. 'civics' marks a source of region governmental structure, process, and vocabulary; the civics-ingest handler scrapes it and uses the private prompt-service to extract structured shape (chambers, measure types, lifecycle stages with status patterns, glossary) plus a plain-language rewrite for laypeople. Verbatim source text and the AI rewrite are stored together \u2014 never one without the other. 'bills' marks a source of individual legislative bills (AB, SB, ACA, SCA, etc.) scraped from an official legislature website; the bills-ingest handler BFS-crawls from the seed URL and extracts one Bill record per detail page. See opuspopuli#686."
+        },
+        contentGoal: {
+          type: "string",
+          minLength: 1,
+          description: "Natural language description of what to find/extract"
+        },
+        category: {
+          type: "string",
+          description: "Sub-category for grouping (e.g., 'Assembly', 'Senate')"
+        },
+        hints: {
+          type: "array",
+          items: { type: "string" },
+          description: "Hints to help the AI find the right content"
+        },
+        rateLimitOverride: {
+          type: "number",
+          minimum: 0,
+          description: "Override rate limit for this specific source"
+        },
+        syncCadence: {
+          type: "string",
+          pattern: "^[^ ]+ [^ ]+ [^ ]+ [^ ]+ [^ ]+$",
+          description: "5-field cron expression (minute hour dom month dow) controlling how often this source is synced. The worker applies a deterministic per-source minute offset at registration time to spread load across gov hosts \u2014 the minute field you specify is the base, not the exact fire time. Omit to inherit the global daily fallback. Common patterns: '0 2 * * *' daily at 2 AM, '0 2 * * 0' weekly on Sunday, '0 * * * *' hourly."
+        },
+        statusScanCadence: {
+          type: "string",
+          pattern: "^[^ ]+ [^ ]+ [^ ]+ [^ ]+ [^ ]+$",
+          description: "5-field cron expression for a periodic full status-page sweep of all bills (dataType='bills' only). Runs forceStatusRecheck=true \u2014 bypasses the needsStatusRecheck flag and the sourcePublishedAt skip to catch governor actions and off-session changes the journal linker can't see. Per-source minute offset is applied like syncCadence. Typical: '0 2 * * 0' weekly Sunday 2 AM. See #689."
+        },
+        sourceType: {
+          type: "string",
+          enum: ["html_scrape", "bulk_download", "api", "pdf", "pdf_archive"],
+          description: "Source type determines the extraction strategy (default: html_scrape). 'pdf_archive' selects the listing-walk + per-PDF-extract pipeline: the URL is a paginated listing page that links to a series of dated PDF documents, each fetched and parsed (text only at V1) into one Minutes record."
+        },
+        bulk: {
+          $ref: "#/definitions/BulkDownloadConfig"
+        },
+        api: {
+          $ref: "#/definitions/ApiSourceConfig"
+        },
+        pdf: {
+          $ref: "#/definitions/PdfSourceConfig"
+        },
+        pdfArchive: {
+          $ref: "#/definitions/PdfArchiveConfig"
+        },
+        billDiscovery: {
+          $ref: "#/definitions/BillDiscoveryConfig"
+        },
+        detailFields: {
+          type: "object",
+          additionalProperties: {
+            oneOf: [
+              { type: "string" },
+              { $ref: "#/definitions/StructuredFieldConfig" }
+            ]
+          },
+          description: "Detail page extraction plan: maps domain field names to CSS selectors (string) or structured array configs (object). Supports dot notation and '|attr:name' suffix."
+        },
+        staticManifest: {
+          type: "object",
+          required: ["containerSelector", "itemSelector", "fieldMappings"],
+          additionalProperties: false,
+          description: "Explicit extraction selectors that bypass AI structural analysis entirely. Use when the page structure is known and stable, or when the local LLM consistently generates wrong selectors.",
+          properties: {
+            containerSelector: { type: "string" },
+            itemSelector: { type: "string" },
+            fieldMappings: {
+              type: "array",
+              items: {
+                type: "object",
+                required: ["fieldName", "selector", "extractionMethod", "required"],
+                additionalProperties: true,
+                properties: {
+                  fieldName: { type: "string" },
+                  selector: { type: "string" },
+                  extractionMethod: { type: "string" },
+                  attribute: { type: "string" },
+                  regexPattern: { type: "string" },
+                  regexGroup: { type: "integer" },
+                  transform: { type: "object" },
+                  required: { type: "boolean" },
+                  defaultValue: { type: "string" },
+                  scope: {
+                    type: "string",
+                    enum: ["item", "container"]
+                  },
+                  children: {
+                    type: "object",
+                    additionalProperties: {
+                      oneOf: [
+                        { type: "string" },
+                        { $ref: "#/definitions/ChildFieldConfig" }
+                      ]
+                    },
+                    description: "For extractionMethod='structured': child field selectors. Each value is a string shortcut or a ChildFieldConfig object."
+                  }
+                }
+              }
+            }
+          }
+        },
+        crawlDepth: {
+          type: "integer",
+          minimum: 0,
+          description: "Crawl depth from the seed URL for sync handlers that walk a site's link graph (currently civics \u2014 see opuspopuli#669). 0 (default) = no crawl, fetch only the seed. N = N hops from seed. Crawls are scoped to same host + same path prefix as the seed, HTML responses only."
+        },
+        crawlMaxPages: {
+          type: "integer",
+          minimum: 1,
+          description: "Cap on total pages a crawler will visit per sync run regardless of crawlDepth. Defaults to 20. Each page costs one LLM call, so this bounds runtime + token spend."
+        },
+        llmMaxTokens: {
+          type: "integer",
+          minimum: 1,
+          description: "Per-source override for the LLM maxTokens generation cap. Useful when a source needs a much longer or shorter output than its siblings (e.g., a 150-term glossary needs ~32000; a short bio prompt finishes well under 2000). Overrides the sync handler's hardcoded default."
+        },
+        llmRequestTimeoutMs: {
+          type: "integer",
+          minimum: 1,
+          description: "Per-source override for the LLM provider request timeout (milliseconds). Useful when a single source legitimately runs much longer than the platform-wide default \u2014 civics-glossary extraction on qwen3.5:9b can take 15-20 min, while bio gen finishes in 2 min on the same hardware. Overrides the provider's constructor-configured default."
+        }
+      }
+    },
+    BulkDownloadConfig: {
+      type: "object",
+      required: ["format", "columnMappings"],
+      additionalProperties: false,
+      properties: {
+        format: {
+          type: "string",
+          enum: ["tsv", "csv", "zip_tsv", "zip_csv"],
+          description: "File format"
+        },
+        filePattern: {
+          type: "string",
+          description: "For ZIP archives: path/glob of target file(s) within the ZIP"
+        },
+        delimiter: {
+          type: "string",
+          description: "Column delimiter override"
+        },
+        headerLines: {
+          type: "integer",
+          minimum: 0,
+          description: "Number of header lines to skip"
+        },
+        headers: {
+          type: "array",
+          items: { type: "string" },
+          description: "Explicit column headers for files without a header row (e.g., FEC bulk files)"
+        },
+        columnMappings: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Column name mappings: source column name -> domain field name"
+        },
+        filters: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: `Filter expressions applied during parse. Values support \${variableName} placeholders that the consumer resolves at runtime from the active local region. Supported variables: \${stateCode} (the 2-letter US state code of the active local region, e.g. 'CA'). Placeholders must appear verbatim. Example: '"STATE": "\${stateCode}"' on an FEC bulk filter.`
+        },
+        batchSize: {
+          type: "integer",
+          minimum: 1,
+          description: "Records per batch for streaming processing (default: 10000)"
+        }
+      }
+    },
+    ApiSourceConfig: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        method: {
+          type: "string",
+          enum: ["GET", "POST"],
+          description: "HTTP method (default: GET)"
+        },
+        apiKeyEnvVar: {
+          type: "string",
+          description: "Environment variable name containing the API key"
+        },
+        apiKeyHeader: {
+          type: "string",
+          description: "Header name for the API key"
+        },
+        pagination: {
+          $ref: "#/definitions/ApiPaginationConfig"
+        },
+        resultsPath: {
+          type: "string",
+          description: "JSON path to the items array in the response"
+        },
+        queryParams: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: `Query parameters appended to every request. Values support \${variableName} placeholders that the consumer resolves at runtime from the active local region. Supported variables: \${stateCode} (the 2-letter US state code of the active local region, e.g. 'CA'). Placeholders must appear verbatim \u2014 no escaping, no nested expressions. Example: '"contributor_state": "\${stateCode}"'.`
+        },
+        fieldMappings: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Field name mappings: API response field -> domain model field (e.g., committee_id -> committeeId)"
+        }
+      }
+    },
+    ApiPaginationConfig: {
+      type: "object",
+      required: ["type"],
+      additionalProperties: false,
+      properties: {
+        type: {
+          type: "string",
+          enum: ["offset", "cursor", "page"],
+          description: "Pagination strategy type"
+        },
+        pageParam: {
+          type: "string",
+          description: "Query parameter name for page/offset"
+        },
+        limitParam: {
+          type: "string",
+          description: "Query parameter name for page size"
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          description: "Number of items per page"
+        }
+      }
+    },
+    PdfSourceConfig: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        skipPages: {
+          type: "integer",
+          minimum: 0,
+          description: "Skip first N pages (e.g., skip cover page)"
+        },
+        maxPages: {
+          type: "integer",
+          minimum: 1,
+          description: "Maximum pages to process (default: all)"
+        },
+        followPdfLink: {
+          type: "boolean",
+          description: "If true, treats the URL as a gateway page and follows the first PDF link"
+        }
+      }
+    },
+    StructuredFieldConfig: {
+      type: "object",
+      required: ["selector", "children"],
+      additionalProperties: false,
+      properties: {
+        selector: {
+          type: "string",
+          description: "CSS selector matching each repeating item (e.g., '.office-card')"
+        },
+        children: {
+          type: "object",
+          additionalProperties: {
+            oneOf: [
+              { type: "string" },
+              { $ref: "#/definitions/ChildFieldConfig" }
+            ]
+          },
+          description: "Child field selectors relative to each item. Each entry is either a string shortcut (e.g. 'h3', 'a|attr:href') or a richer ChildFieldConfig object with extractionMethod / regex / transform."
+        },
+        multiple: {
+          type: "boolean",
+          description: "If true, extracts all matches as an array (default: true)"
+        }
+      }
+    },
+    ChildFieldConfig: {
+      type: "object",
+      additionalProperties: false,
+      description: "Per-child extraction config for structured extraction. Object form supports the same shape as the top-level FieldMapping (selector + extractionMethod + attribute / regex / transform), minus fieldName/required/defaultValue which don't apply at child scope.",
+      properties: {
+        selector: {
+          type: "string",
+          description: "CSS selector relative to the matched parent item. Optional for regex on full element text."
+        },
+        extractionMethod: {
+          type: "string",
+          description: "How to extract: 'text', 'attribute', 'regex', 'html', etc."
+        },
+        attribute: {
+          type: "string",
+          description: "For extractionMethod='attribute': which attribute to read (e.g. 'href', 'src')."
+        },
+        regexPattern: {
+          type: "string",
+          description: "For extractionMethod='regex': the pattern."
+        },
+        regexGroup: {
+          type: "integer",
+          description: "For extractionMethod='regex': capture group (default: 1)."
+        },
+        transform: {
+          type: "object",
+          description: "Optional transform applied after extraction (e.g. trim, regex_replace, url_resolve)."
+        }
+      }
+    },
+    BillDiscoveryConfig: {
+      type: "object",
+      required: ["navLinkPattern", "statusPageTemplate", "votesPageTemplate"],
+      additionalProperties: false,
+      description: "Declarative bill discovery for legislature sites that list per-bill nav-hub links on a search results page (e.g. CA leginfo). The bills-ingest handler fetches the seed once, extracts bill IDs with navLinkPattern, and constructs status + votes URLs from the templates \u2014 bypassing generic BFS which would exhaust crawlMaxPages with nav-hub links before reaching detail pages.",
+      properties: {
+        navLinkPattern: {
+          type: "string",
+          description: 'Regex string applied to the decoded seed-page HTML to extract bill IDs. Capture group 1 must be the bill ID. Example for CA leginfo: "/faces/billNavClient\\\\.xhtml\\\\?bill_id=([^\\"&\\\\s]+)"'
+        },
+        statusPageTemplate: {
+          type: "string",
+          description: 'URL path + query template for the bill status page. Use {bill_id} as the placeholder; the service prepends the seed origin. Example: "/faces/billStatusClient.xhtml?bill_id={bill_id}"'
+        },
+        votesPageTemplate: {
+          type: "string",
+          description: 'URL path + query template for the bill votes page. Same substitution as statusPageTemplate. Example: "/faces/billVotesClient.xhtml?bill_id={bill_id}"'
+        },
+        textPageTemplate: {
+          type: "string",
+          description: `Optional URL path + query template for the bill text page. When set, the sync fetches this page before LLM extraction to check the 'Date Published' timestamp and skip unchanged bills. Example: "/faces/billTextClient.xhtml?bill_id={bill_id}"`
+        }
+      }
+    },
+    PdfArchiveConfig: {
+      type: "object",
+      required: ["linkSelector"],
+      additionalProperties: false,
+      description: "Listing-walk configuration for sourceType=pdf_archive. The page at `url` is treated as a paginated index of dated PDF documents; each linked PDF is fetched, pdf-parsed, and stored as a Minutes record. Cold-start work is bounded by maxNew (default 10) so first-run sync doesn't ingest years of historical archives. Per-document parsing (text \u2192 action records) is a downstream backend pass \u2014 this block carries no parser DSL.",
+      properties: {
+        linkSelector: {
+          type: "string",
+          description: "CSS selector for PDF anchor elements on the listing page. Each match yields a candidate document."
+        },
+        datePattern: {
+          type: "string",
+          description: "Regex applied to the link href (falling back to anchor text) to extract the document's date. Capture groups depend on dateFormat."
+        },
+        dateFormat: {
+          type: "string",
+          description: "Date format hint for interpreting datePattern's captures. Supported: 'MMDDYY' (3 captures: month, day, two-digit year \u2014 assumed 20YY), 'YYYY-MM-DD' (3 captures), 'MM/DD/YYYY' (3 captures)."
+        },
+        revisionPattern: {
+          type: "string",
+          description: "Regex against the link href whose match indicates this URL is a revision. Capture group 1 is the revision sequence number (1, 2, ...). Unmatched URLs are revisionSeq=0."
+        },
+        maxPages: {
+          type: "integer",
+          minimum: 1,
+          description: "Maximum number of listing pages to walk during one sync cycle. Default: 10."
+        },
+        maxNew: {
+          type: "integer",
+          minimum: 1,
+          description: "Hard cap on number of new documents ingested per sync cycle. Cold-start protection. Default: 10."
+        },
+        paginationParam: {
+          type: "string",
+          description: "Query parameter name used to paginate the listing page (e.g., 'page'). Omitted when the listing isn't paginated."
+        }
+      }
+    }
+  }
+};
+
+// src/lib/region.ts
+var DATA_TYPES = [
+  "propositions",
+  "meetings",
+  "representatives",
+  "campaign_finance",
+  "lobbying",
+  "civics",
+  "bills"
+];
+var SOURCE_TYPES = [
+  "html_scrape",
+  "bulk_download",
+  "api",
+  "pdf",
+  "pdf_archive"
+];
+var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var STATE_CODE_RE = /^[A-Z]{2}$/;
+function slugify(input) {
+  return input.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function isValidSlug(v) {
+  return SLUG_RE.test(v);
+}
+function isValidStateCode(v) {
+  return STATE_CODE_RE.test(v);
+}
+function isValidFips(v, level) {
+  return level === "state" ? /^\d{2}$/.test(v) : /^\d{5}$/.test(v);
+}
+function supportedTimeZones() {
+  const intl = Intl;
+  if (typeof intl.supportedValuesOf !== "function") return null;
+  try {
+    return new Set(intl.supportedValuesOf("timeZone"));
+  } catch {
+    return null;
+  }
+}
+function isValidTimezone(v) {
+  if (!v.includes("/")) return false;
+  const zones = supportedTimeZones();
+  return zones ? zones.has(v) : true;
+}
+function buildRegionConfig(input) {
+  const config = {
+    // The regions repo requires `name === config.regionId`; we tie them
+    // together at construction so they can never drift.
+    regionId: input.regionId,
+    regionName: input.regionName,
+    description: input.description,
+    timezone: input.timezone,
+    stateCode: input.stateCode,
+    fipsCode: input.fipsCode,
+    dataSources: input.dataSources.map(normalizeDataSource)
+  };
+  if (input.parentRegionId) {
+    config.parentRegionId = input.parentRegionId;
+  }
+  return {
+    name: input.regionId,
+    displayName: input.displayName,
+    description: input.description,
+    version: input.version,
+    config
+  };
+}
+function normalizeDataSource(src) {
+  const out = {
+    url: src.url,
+    dataType: src.dataType,
+    sourceType: src.sourceType,
+    contentGoal: src.contentGoal
+  };
+  if (src.category) out.category = src.category;
+  return out;
+}
+function regionFilePath(input) {
+  if (input.level === "state") {
+    return `regions/${input.regionId}/${input.regionId}.json`;
+  }
+  const parent = input.parentRegionId;
+  const countySlug = input.countySlug;
+  if (!parent || !countySlug) {
+    throw new Error(
+      "regionFilePath: county requires both parentRegionId and countySlug"
+    );
+  }
+  return `regions/${parent}/counties/${countySlug}/${countySlug}.json`;
+}
+var schemaValidator = new Validator(region_schema_default, "7");
+function validateRegionConfig(file) {
+  const issues = [];
+  const { config } = file;
+  if (!/^\d+\.\d+\.\d+$/.test(file.version)) {
+    issues.push(`version "${file.version}" is not a valid semver (expected MAJOR.MINOR.PATCH)`);
+  }
+  if (file.name !== config.regionId) {
+    issues.push(`name "${file.name}" must equal config.regionId "${config.regionId}"`);
+  }
+  if (!isValidSlug(config.regionId)) {
+    issues.push(`regionId "${config.regionId}" must be kebab-case`);
+  }
+  if (config.parentRegionId !== void 0 && !config.regionId.startsWith(`${config.parentRegionId}-`)) {
+    issues.push(
+      `county regionId "${config.regionId}" should be prefixed with its parent "${config.parentRegionId}-"`
+    );
+  }
+  const isCounty = config.parentRegionId !== void 0;
+  if (config.fipsCode !== void 0) {
+    const expected = isCounty ? 5 : 2;
+    if (!/^\d+$/.test(config.fipsCode) || config.fipsCode.length !== expected) {
+      issues.push(
+        `fipsCode "${config.fipsCode}" must be ${expected} digits for a ${isCounty ? "county" : "state"}`
+      );
+    }
+  }
+  if (Array.isArray(config.dataSources)) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const src of config.dataSources) {
+      const key = `${src.dataType} ${src.url}`;
+      if (seen.has(key)) {
+        issues.push(`duplicate data source: ${src.dataType} ${src.url}`);
+      }
+      seen.add(key);
+    }
+  }
+  const result2 = schemaValidator.validate(file);
+  if (!result2.valid) {
+    for (const err of result2.errors) {
+      const path = err.instanceLocation || "<root>";
+      issues.push(`schema: ${path} ${err.error}`);
+    }
+  }
+  return issues;
+}
+
+// src/commands/region.ts
+var regionCommand = new Command("region").description(
+  "Scaffold a schema-valid region config for the OpusPopuli/opuspopuli-regions repo. Run this from inside your checkout of that repo."
+).addOption(
+  new Option("--level <level>", "Region level").choices(["state", "county"])
+).addOption(new Option("--name <name>", 'Region name (e.g. "California" or "Alameda")')).addOption(
+  new Option("--parent <slug>", "Parent state slug for a county (e.g. california)")
+).addOption(new Option("--state-code <code>", "Two-letter US state code (e.g. CA)")).addOption(new Option("--fips <code>", "FIPS code (2 digits state, 5 digits county)")).addOption(new Option("--timezone <tz>", "IANA timezone (e.g. America/Los_Angeles)")).addOption(
+  new Option("--out-dir <dir>", "Repo root to write under").default(
+    process.cwd(),
+    "current directory"
+  )
+).addOption(new Option("-f, --force", "Overwrite an existing config file").default(false)).action(async (opts) => {
+  p3.intro(pc2.bgMagenta(pc2.black(" create-op-node region ")));
+  p3.note(
+    [
+      "Scaffolds a declarative region config JSON for opuspopuli-regions \u2014",
+      "the file that defines WHAT civic data a region collects.",
+      "",
+      pc2.dim("Run this from the root of your opuspopuli-regions checkout."),
+      pc2.dim("It validates the same invariants the repo\u2019s `pnpm test` enforces,"),
+      pc2.dim("so the file lands green and you just commit + open a PR.")
+    ].join("\n"),
+    "Welcome"
+  );
+  const targetDir = opts.outDir ?? process.cwd();
+  const looksRight = await looksLikeRegionsRepo(targetDir);
+  if (!looksRight) {
+    const proceed = unwrap(
+      await p3.confirm({
+        message: `${targetDir} doesn't look like an opuspopuli-regions checkout (no schema/region-plugin.schema.json). Continue anyway?`,
+        initialValue: false
+      })
+    );
+    if (!proceed) {
+      p3.cancel("Cancelled \u2014 run again from your opuspopuli-regions checkout, or pass --out-dir.");
+      process.exit(0);
+    }
+  }
+  const level = opts.level === "state" || opts.level === "county" ? opts.level : unwrap(
+    await p3.select({
+      message: "What level is this region?",
+      options: [
+        { value: "state", label: "State", hint: "e.g. California" },
+        { value: "county", label: "County", hint: "e.g. Alameda, within California" }
+      ]
+    })
+  );
+  const rawName = opts.name ?? unwrap(
+    await p3.text({
+      message: level === "county" ? "County name?" : "State name?",
+      placeholder: level === "county" ? "Alameda" : "California",
+      validate: (v) => v && v.trim().length > 0 ? void 0 : "Required"
+    })
+  );
+  let parentSlug;
+  if (level === "county") {
+    parentSlug = opts.parent ?? unwrap(
+      await p3.text({
+        message: "Parent state slug?",
+        placeholder: "california",
+        validate: (v) => isValidSlug(v ?? "") ? void 0 : "kebab-case (lowercase letters, digits, hyphens)"
+      })
+    );
+    if (!isValidSlug(parentSlug)) {
+      p3.cancel(`Parent slug "${parentSlug}" must be kebab-case.`);
+      process.exit(1);
+    }
+  }
+  const ownSlug = slugify(rawName);
+  const regionId = level === "county" ? `${parentSlug}-${ownSlug}` : ownSlug;
+  if (!isValidSlug(regionId)) {
+    p3.cancel(`Derived regionId "${regionId}" is not valid kebab-case. Try a simpler name.`);
+    process.exit(1);
+  }
+  const displayName = unwrap(
+    await p3.text({
+      message: "Display name?",
+      defaultValue: rawName
+    })
+  );
+  const regionName = displayName || rawName;
+  const description = unwrap(
+    await p3.text({
+      message: "One-line description of the data coverage?",
+      placeholder: level === "county" ? `Civic data for ${rawName} County` : `Civic data for the state of ${rawName}`,
+      validate: (v) => v && v.trim().length > 0 ? void 0 : "Required"
+    })
+  );
+  const stateCode = (opts.stateCode ?? unwrap(
+    await p3.text({
+      message: "Two-letter state code?",
+      placeholder: "CA",
+      validate: (v) => isValidStateCode((v ?? "").toUpperCase()) ? void 0 : "Two letters, e.g. CA"
+    })
+  )).toUpperCase();
+  if (!isValidStateCode(stateCode)) {
+    p3.cancel(`State code "${stateCode}" must be two letters.`);
+    process.exit(1);
+  }
+  const fipsCode = opts.fips ?? unwrap(
+    await p3.text({
+      message: level === "county" ? "County FIPS (5 digits)?" : "State FIPS (2 digits)?",
+      placeholder: level === "county" ? "06001" : "06",
+      validate: (v) => isValidFips(v ?? "", level) ? void 0 : `Expected ${level === "county" ? "5" : "2"} digits`
+    })
+  );
+  if (!isValidFips(fipsCode, level)) {
+    p3.cancel(`FIPS "${fipsCode}" is the wrong length for a ${level}.`);
+    process.exit(1);
+  }
+  const timezone = opts.timezone ?? unwrap(
+    await p3.text({
+      message: "IANA timezone?",
+      defaultValue: "America/Los_Angeles",
+      placeholder: "America/Los_Angeles",
+      validate: (v) => isValidTimezone(v || "America/Los_Angeles") ? void 0 : "Not a recognized IANA zone (e.g. America/New_York)"
+    })
+  );
+  const dataSources = [];
+  do {
+    const url = unwrap(
+      await p3.text({
+        message: `Data source #${dataSources.length + 1} \u2014 URL?`,
+        placeholder: "https://example.gov/meetings",
+        validate: (v) => /^https?:\/\//.test(v ?? "") ? void 0 : "Must start with http(s)://"
+      })
+    );
+    const dataType = unwrap(
+      await p3.select({
+        message: "Data type?",
+        options: DATA_TYPES.map((t) => ({ value: t, label: t }))
+      })
+    );
+    const sourceType = unwrap(
+      await p3.select({
+        message: "Source type?",
+        initialValue: "html_scrape",
+        options: SOURCE_TYPES.map((t) => ({ value: t, label: t }))
+      })
+    );
+    const contentGoal = unwrap(
+      await p3.text({
+        message: "Content goal (what should the scraper extract)?",
+        placeholder: "Fetch upcoming board meeting agendas and minutes",
+        validate: (v) => v && v.trim().length > 0 ? void 0 : "Required"
+      })
+    );
+    const category = unwrap(
+      await p3.text({
+        message: "Category label (optional)?",
+        placeholder: "Board of Supervisors"
+      })
+    );
+    const src = { url, dataType, sourceType, contentGoal };
+    if (category && category.trim().length > 0) src.category = category.trim();
+    dataSources.push(src);
+    const again = unwrap(
+      await p3.confirm({ message: "Add another data source?", initialValue: false })
+    );
+    if (!again) break;
+  } while (true);
+  const input = {
+    regionId,
+    displayName: regionName,
+    regionName,
+    description,
+    // New region configs start at 0.1.0 — the documented convention in the
+    // regions repo's CLAUDE.md. Bump to a higher version manually as the
+    // config matures.
+    version: "0.1.0",
+    timezone,
+    stateCode,
+    fipsCode,
+    dataSources,
+    ...parentSlug ? { parentRegionId: parentSlug } : {},
+    ...level === "county" ? { countySlug: ownSlug } : {}
+  };
+  const file = buildRegionConfig(input);
+  const issues = validateRegionConfig(file);
+  if (issues.length > 0) {
+    p3.note(issues.map((i) => `${pc2.red("\u2022")} ${i}`).join("\n"), "Validation failed");
+    p3.cancel("The generated config would not pass the regions repo CI. Re-run and adjust.");
+    process.exit(1);
+  }
+  const relPath = regionFilePath({
+    level,
+    regionId,
+    ...parentSlug ? { parentRegionId: parentSlug } : {},
+    ...level === "county" ? { countySlug: ownSlug } : {}
+  });
+  const absPath = resolve(targetDir, relPath);
+  const json = `${JSON.stringify(file, null, 2)}
+`;
+  p3.note(json, `${relPath} (preview)`);
+  if (!opts.force && await fileExists3(absPath)) {
+    p3.cancel(`${relPath} already exists. Re-run with --force to overwrite.`);
+    process.exit(1);
+  }
+  const write = unwrap(
+    await p3.confirm({ message: `Write ${relPath}?`, initialValue: true })
+  );
+  if (!write) {
+    p3.cancel("Nothing written.");
+    process.exit(0);
+  }
+  await mkdir(dirname(absPath), { recursive: true });
+  await writeFile(absPath, json, "utf8");
+  p3.note(
+    [
+      `${pc2.green("\u2713")} Wrote ${pc2.cyan(relPath)}`,
+      "",
+      "Next steps in your opuspopuli-regions checkout:",
+      pc2.dim("  pnpm test                 # schema + hierarchy validation"),
+      pc2.dim("  pnpm test:connectivity    # URL reachability (informational)"),
+      pc2.dim(`  git add ${relPath} && git commit && open a PR`)
+    ].join("\n"),
+    "Done"
+  );
+  p3.outro(pc2.magenta(`Region scaffolded: ${regionId}`));
+});
+async function fileExists3(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function looksLikeRegionsRepo(dir) {
+  const [hasSchema, hasRegions] = await Promise.all([
+    fileExists3(join(dir, "schema", "region-plugin.schema.json")),
+    fileExists3(join(dir, "regions"))
+  ]);
+  return hasSchema && hasRegions;
+}
 
 // src/cli.ts
-var VERSION = "0.0.1";
+var VERSION = "0.2.0";
 var program = new Command();
 program.name("create-op-node").description(
   "Interactive bootstrap for an Opus Populi federation node.\nCloudflare infrastructure \u2192 Mac Studio \u2192 live public API."
 ).version(VERSION, "-v, --version", "show version");
 program.addCommand(initCommand);
 program.addCommand(bootstrapCommand);
+program.addCommand(resetCommand);
 program.addCommand(verifyCommand);
+program.addCommand(regionCommand);
 if (process.argv.length === 2) {
   process.argv.push("init");
 }
 await program.parseAsync(process.argv).catch((err) => {
   const msg = err instanceof Error ? err.message : String(err);
   console.error(`
-${pc.red("\u2717")} ${msg}
+${pc2.red("\u2717")} ${msg}
 `);
   process.exit(1);
 });