@rizom/ops 0.2.0-alpha.17 → 0.2.0-alpha.170

package/templates/rover-pilot/.github/workflows/deploy.yml

@@ -10,12 +10,17 @@ on:
   push:
     branches: ["main"]
     paths:
+      - users/*.yaml
       - users/*/.env
       - users/*/brain.yaml
       - users/*/content/**
       - users/*.secrets.yaml.age
       - deploy/**
       - .github/workflows/deploy.yml
+  workflow_run:
+    workflows: [Reconcile]
+    types: [completed]
+    branches: [main]
 
 permissions:
   contents: write
@@ -23,13 +28,16 @@ permissions:
 
 jobs:
   resolve_handles:
+    if: >
+      github.event_name != 'workflow_run' ||
+      github.event.workflow_run.conclusion == 'success'
     runs-on: ubuntu-latest
     outputs:
       handles_json: ${{ steps.resolve.outputs.handles_json }}
     steps:
       - uses: actions/checkout@v5
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || github.sha }}
           fetch-depth: 0
 
       - uses: oven-sh/setup-bun@v2
@@ -41,7 +49,7 @@ jobs:
         id: resolve
         env:
           HANDLE_INPUT: ${{ inputs.handle || '' }}
-          BEFORE_SHA: ${{ github.event.before || '' }}
+          BEFORE_SHA: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.event.before || '' }}
         run: bun deploy/scripts/resolve-deploy-handles.ts
 
   no_changes:
@@ -68,7 +76,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || github.sha }}
 
       - uses: oven-sh/setup-bun@v2
 
@@ -96,7 +104,8 @@ jobs:
         env:
           SHARED_AI_API_KEY: ${{ secrets[steps.user_secrets.outputs.shared_ai_api_key_secret_name] }}
           SHARED_GIT_SYNC_TOKEN: ${{ secrets[steps.user_secrets.outputs.shared_git_sync_token_secret_name] }}
-          SHARED_MCP_AUTH_TOKEN: ${{ secrets[steps.user_secrets.outputs.shared_mcp_auth_token_secret_name] }}
+          SETUP_EMAIL_API_KEY: ${{ secrets.SETUP_EMAIL_API_KEY }}
+          SETUP_EMAIL_FROM: ${{ secrets.SETUP_EMAIL_FROM }}
           HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
           HCLOUD_SSH_KEY_NAME: ${{ secrets.HCLOUD_SSH_KEY_NAME }}
           HCLOUD_SERVER_TYPE: ${{ secrets.HCLOUD_SERVER_TYPE }}
@@ -104,13 +113,16 @@ jobs:
           KAMAL_SSH_PRIVATE_KEY: ${{ secrets.KAMAL_SSH_PRIVATE_KEY }}
           KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}
           CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
-          CF_ZONE_ID: ${{ secrets.CF_ZONE_ID }}
-          CERTIFICATE_PEM: ${{ secrets.CERTIFICATE_PEM }}
-          PRIVATE_KEY_PEM: ${{ secrets.PRIVATE_KEY_PEM }}
+          CONFIG_CF_ZONE_ID: ${{ steps.user_config.outputs.cloudflare_zone_id }}
+          SHARED_CF_ZONE_ID: ${{ secrets.CF_ZONE_ID }}
+          SHARED_CERTIFICATE_PEM: ${{ secrets.CERTIFICATE_PEM }}
+          SHARED_PRIVATE_KEY_PEM: ${{ secrets.PRIVATE_KEY_PEM }}
         run: |
           export AI_API_KEY="${AI_API_KEY:-$SHARED_AI_API_KEY}"
           export GIT_SYNC_TOKEN="${GIT_SYNC_TOKEN:-$SHARED_GIT_SYNC_TOKEN}"
-          export MCP_AUTH_TOKEN="${MCP_AUTH_TOKEN:-$SHARED_MCP_AUTH_TOKEN}"
+          export CF_ZONE_ID="${CONFIG_CF_ZONE_ID:-${CF_ZONE_ID:-$SHARED_CF_ZONE_ID}}"
+          export CERTIFICATE_PEM="${CERTIFICATE_PEM:-$SHARED_CERTIFICATE_PEM}"
+          export PRIVATE_KEY_PEM="${PRIVATE_KEY_PEM:-$SHARED_PRIVATE_KEY_PEM}"
           bun deploy/scripts/validate-secrets.ts
 
       - name: Seed content repo
@@ -122,7 +134,7 @@ jobs:
           bun deploy/scripts/sync-content-repo.ts
 
       - name: Log in to GHCR
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -130,7 +142,7 @@ jobs:
 
       - name: Wait for shared image tag
         run: |
-          IMAGE_TAG="${{ steps.user_config.outputs.image_repository }}:brain-${{ steps.user_config.outputs.brain_version }}"
+          IMAGE_TAG="${{ steps.user_config.outputs.image_repository }}:${{ steps.user_config.outputs.image_tag }}"
           for attempt in $(seq 1 24); do
             if docker manifest inspect "$IMAGE_TAG" >/dev/null 2>&1; then
               exit 0
@@ -168,14 +180,16 @@ jobs:
         env:
           SHARED_AI_API_KEY: ${{ secrets[steps.user_secrets.outputs.shared_ai_api_key_secret_name] }}
           SHARED_GIT_SYNC_TOKEN: ${{ secrets[steps.user_secrets.outputs.shared_git_sync_token_secret_name] }}
-          SHARED_MCP_AUTH_TOKEN: ${{ secrets[steps.user_secrets.outputs.shared_mcp_auth_token_secret_name] }}
+          SETUP_EMAIL_API_KEY: ${{ secrets.SETUP_EMAIL_API_KEY }}
+          SETUP_EMAIL_FROM: ${{ secrets.SETUP_EMAIL_FROM }}
           KAMAL_REGISTRY_PASSWORD: ${{ secrets.KAMAL_REGISTRY_PASSWORD }}
-          CERTIFICATE_PEM: ${{ secrets.CERTIFICATE_PEM }}
-          PRIVATE_KEY_PEM: ${{ secrets.PRIVATE_KEY_PEM }}
+          SHARED_CERTIFICATE_PEM: ${{ secrets.CERTIFICATE_PEM }}
+          SHARED_PRIVATE_KEY_PEM: ${{ secrets.PRIVATE_KEY_PEM }}
         run: |
           export AI_API_KEY="${AI_API_KEY:-$SHARED_AI_API_KEY}"
           export GIT_SYNC_TOKEN="${GIT_SYNC_TOKEN:-$SHARED_GIT_SYNC_TOKEN}"
-          export MCP_AUTH_TOKEN="${MCP_AUTH_TOKEN:-$SHARED_MCP_AUTH_TOKEN}"
+          export CERTIFICATE_PEM="${CERTIFICATE_PEM:-$SHARED_CERTIFICATE_PEM}"
+          export PRIVATE_KEY_PEM="${PRIVATE_KEY_PEM:-$SHARED_PRIVATE_KEY_PEM}"
           bun deploy/scripts/write-kamal-secrets.ts
 
       - name: Provision server
@@ -191,12 +205,18 @@ jobs:
       - name: Update Cloudflare DNS
         env:
           CF_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
-          CF_ZONE_ID: ${{ secrets.CF_ZONE_ID }}
+          CONFIG_CF_ZONE_ID: ${{ steps.user_config.outputs.cloudflare_zone_id }}
+          SHARED_CF_ZONE_ID: ${{ secrets.CF_ZONE_ID }}
           BRAIN_DOMAIN: ${{ steps.user_config.outputs.brain_domain }}
+          WWW_DOMAIN: ${{ steps.user_config.outputs.www_domain }}
           PREVIEW_DOMAIN: ${{ steps.user_config.outputs.preview_domain }}
           SERVER_IP: ${{ steps.provision.outputs.server_ip }}
         run: |
+          export CF_ZONE_ID="${CONFIG_CF_ZONE_ID:-${CF_ZONE_ID:-$SHARED_CF_ZONE_ID}}"
           bun deploy/scripts/update-dns.ts
+          if [ -n "$WWW_DOMAIN" ]; then
+            BRAIN_DOMAIN="$WWW_DOMAIN" bun deploy/scripts/update-dns.ts
+          fi
           BRAIN_DOMAIN="$PREVIEW_DOMAIN" bun deploy/scripts/update-dns.ts
 
       - name: Validate SSH key
@@ -220,10 +240,11 @@ jobs:
       - name: Deploy
         env:
           SERVER_IP: ${{ steps.provision.outputs.server_ip }}
-          VERSION: brain-${{ steps.user_config.outputs.brain_version }}
+          VERSION: ${{ steps.user_config.outputs.image_tag }}
           IMAGE_REPOSITORY: ${{ steps.user_config.outputs.image_repository }}
           REGISTRY_USERNAME: ${{ steps.user_config.outputs.registry_username }}
           BRAIN_DOMAIN: ${{ steps.user_config.outputs.brain_domain }}
+          WWW_DOMAIN: ${{ steps.user_config.outputs.www_domain }}
           PREVIEW_DOMAIN: ${{ steps.user_config.outputs.preview_domain }}
           BRAIN_YAML_PATH: ${{ steps.user_config.outputs.brain_yaml_path }}
         run: kamal setup --skip-push -c deploy/kamal/deploy.yml
@@ -232,9 +253,13 @@ jobs:
         env:
           SERVER_IP: ${{ steps.provision.outputs.server_ip }}
           BRAIN_DOMAIN: ${{ steps.user_config.outputs.brain_domain }}
+          WWW_DOMAIN: ${{ steps.user_config.outputs.www_domain }}
           PREVIEW_DOMAIN: ${{ steps.user_config.outputs.preview_domain }}
         run: |
           curl -I -k --max-time 20 --resolve "$BRAIN_DOMAIN:443:$SERVER_IP" "https://$BRAIN_DOMAIN/health"
+          if [ -n "$WWW_DOMAIN" ]; then
+            curl -I -k --max-time 20 --resolve "$WWW_DOMAIN:443:$SERVER_IP" "https://$WWW_DOMAIN/"
+          fi
           curl -I -k --max-time 20 --resolve "$PREVIEW_DOMAIN:443:$SERVER_IP" "https://$PREVIEW_DOMAIN/"
 
       - name: Upload generated config
@@ -271,7 +296,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_branch || github.sha }}
 
       - uses: oven-sh/setup-bun@v2
 
@@ -290,11 +315,31 @@ jobs:
 
       - name: Commit generated config
         run: |
+          # A newly added user's generated directory is untracked, and
+          # `git diff` cannot see untracked files — without intent-to-add
+          # the new config is silently dropped here and every later deploy
+          # skips that user (their files never appear in a commit range).
+          git add --intent-to-add -- users views
+
           if git diff --quiet -- users views; then
             exit 0
           fi
+
+          git fetch origin "${{ github.ref_name }}"
+          if git diff --quiet "origin/${{ github.ref_name }}" -- users views; then
+            exit 0
+          fi
+
+          patch_file="$(mktemp)"
+          git diff --binary -- users views > "$patch_file"
+          git reset --hard "origin/${{ github.ref_name }}"
+          git apply --3way --index "$patch_file"
+
+          if git diff --cached --quiet -- users views; then
+            exit 0
+          fi
+
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add users views
           git commit -m "chore(ops): reconcile generated config"
           git push origin HEAD:${{ github.ref_name }}

package/templates/rover-pilot/.github/workflows/reconcile.yml

@@ -35,11 +35,31 @@ jobs:
 
       - name: Commit generated outputs
         run: |
+          # A newly added user's generated directory is untracked, and
+          # `git diff` cannot see untracked files — without intent-to-add
+          # the new config is silently dropped here and every later deploy
+          # skips that user (their files never appear in a commit range).
+          git add --intent-to-add -- views users
+
           if git diff --quiet -- views users; then
             exit 0
           fi
+
+          git fetch origin "${{ github.ref_name }}"
+          if git diff --quiet "origin/${{ github.ref_name }}" -- views users; then
+            exit 0
+          fi
+
+          patch_file="$(mktemp)"
+          git diff --binary -- views users > "$patch_file"
+          git reset --hard "origin/${{ github.ref_name }}"
+          git apply --3way --index "$patch_file"
+
+          if git diff --cached --quiet -- views users; then
+            exit 0
+          fi
+
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add views users
           git commit -m "chore(ops): reconcile pilot outputs"
           git push origin HEAD:${{ github.ref_name }}

package/templates/rover-pilot/README.md

@@ -29,6 +29,7 @@ The repo also checks in its deploy contract:
 - `.github/workflows/*`
 
 `.env.schema` is the single source of truth for required and sensitive deploy vars.
+Use separate GitHub tokens: `CONTENT_REPO_ADMIN_TOKEN` for operator-side content repo creation/checks, and `GIT_SYNC_TOKEN` for runtime directory-sync git access.
 The shared pilot image tag is `brain-${brainVersion}` end to end.
 When `pilot.yaml.brainVersion` changes and you push, CI rebuilds the shared tag, refreshes generated user env files, and redeploys affected users.
 When a push changes only deploy contract files, CI prints `No affected user configs; skipping deploy.` and stops before Kamal.
@@ -37,7 +38,8 @@ When a push changes only deploy contract files, CI prints `No affected user conf
 
 - `brains-ops init <repo>`
 - `brains-ops render <repo>` — regenerates `views/users.md` with live DNS, `/health`, and unauthenticated `/mcp` status checks
-- `brains-ops onboard <repo> <handle>`
+- `brains-ops user:add <repo> <handle> --cohort <cohort>` — scaffolds a user file, per-user secrets template, and cohort membership
+- `brains-ops onboard <repo> <handle>` — creates/seeds the user's content repo with separate admin and sync tokens
 - `brains-ops age-key:bootstrap <repo>`
 - `brains-ops ssh-key:bootstrap <repo>`
 - `brains-ops cert:bootstrap <repo>`

package/templates/rover-pilot/deploy/scripts/decrypt-user-secrets.ts

@@ -20,8 +20,16 @@ const pilot = parseFlatYaml(readFileSync("pilot.yaml", "utf8"));
 
 writeGitHubEnv("AI_API_KEY", secrets["aiApiKey"] ?? "");
 writeGitHubEnv("GIT_SYNC_TOKEN", secrets["gitSyncToken"] ?? "");
-writeGitHubEnv("MCP_AUTH_TOKEN", secrets["mcpAuthToken"] ?? "");
 writeGitHubEnv("DISCORD_BOT_TOKEN", secrets["discordBotToken"] ?? "");
+writeGitHubEnv("ATPROTO_APP_PASSWORD", secrets["atprotoAppPassword"] ?? "");
+writeGitHubEnv(
+  "CERTIFICATE_PEM",
+  decodeEscapedSecret(secrets["certificatePem"]),
+);
+writeGitHubEnv(
+  "PRIVATE_KEY_PEM",
+  decodeEscapedSecret(secrets["privateKeyPem"]),
+);
 
 writeGitHubOutput(
   "shared_ai_api_key_secret_name",
@@ -31,10 +39,6 @@ writeGitHubOutput(
   "shared_git_sync_token_secret_name",
   requireFlatValue(pilot, "gitSyncToken", "pilot.yaml"),
 );
-writeGitHubOutput(
-  "shared_mcp_auth_token_secret_name",
-  requireFlatValue(pilot, "mcpAuthToken", "pilot.yaml"),
-);
 
 function extractAgeIdentity(contents: string): string {
   const line = contents
@@ -70,6 +74,10 @@ function parseFlatYaml(contents: string): Record<string, string> {
   return result;
 }
 
+function decodeEscapedSecret(value: string | undefined): string {
+  return value?.replace(/\\n/g, "\n") ?? "";
+}
+
 function requireFlatValue(
   values: Record<string, string>,
   key: string,

package/templates/rover-pilot/deploy/scripts/resolve-build-config.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+import { createHash } from "node:crypto";
+import { loadPilotRegistry } from "@rizom/ops";
+import { writeGitHubEnv, writeGitHubOutput } from "./helpers";
+
+const requestedBrainVersion = process.env["BRAIN_VERSION_INPUT"]?.trim();
+const registry = await loadPilotRegistry(process.cwd());
+const brainVersion =
+  requestedBrainVersion && requestedBrainVersion.length > 0
+    ? requestedBrainVersion
+    : registry.pilot.brainVersion;
+
+const sitePackages = [
+  ...new Set(
+    registry.users
+      .filter((user) => user.brainVersion === brainVersion)
+      .flatMap((user) =>
+        user.siteOverride
+          ? [`${user.siteOverride.package}@${user.siteOverride.version}`]
+          : [],
+      ),
+  ),
+].sort();
+const sitePackagesValue = sitePackages.join(" ");
+const imageTag = buildImageTag(brainVersion, sitePackages);
+
+writeGitHubEnv("BRAIN_VERSION", brainVersion);
+writeGitHubEnv("SITE_PACKAGES", sitePackagesValue);
+writeGitHubEnv("IMAGE_TAG", imageTag);
+writeGitHubOutput("brain_version", brainVersion);
+writeGitHubOutput("site_packages", sitePackagesValue);
+writeGitHubOutput("image_tag", imageTag);
+
+console.log(`BRAIN_VERSION=${brainVersion}`);
+console.log(`IMAGE_TAG=${imageTag}`);
+console.log(
+  sitePackages.length > 0
+    ? `SITE_PACKAGES=${sitePackagesValue}`
+    : "SITE_PACKAGES=(none)",
+);
+
+function buildImageTag(brainVersion: string, sitePackages: string[]): string {
+  if (sitePackages.length === 0) {
+    return `brain-${brainVersion}`;
+  }
+
+  const siteHash = createHash("sha256")
+    .update(sitePackages.join("\n"))
+    .digest("hex")
+    .slice(0, 12);
+
+  return `brain-${brainVersion}-sites-${siteHash}`;
+}

package/templates/rover-pilot/deploy/scripts/resolve-deploy-handles.ts

@@ -9,14 +9,23 @@ if (eventName === "workflow_dispatch") {
   process.exit(0);
 }
 
-if (eventName !== "push") {
+if (eventName !== "push" && eventName !== "workflow_run") {
   throw new Error(`Unsupported GITHUB_EVENT_NAME: ${eventName}`);
 }
 
 const beforeSha = requireEnv("BEFORE_SHA");
-const currentSha = requireEnv("GITHUB_SHA");
+const currentSha =
+  eventName === "workflow_run"
+    ? execFileSync("git", ["rev-parse", "HEAD"], {
+        encoding: "utf8",
+      }).trim()
+    : requireEnv("GITHUB_SHA");
 
-if (!isUsableGitRevision(beforeSha) || !isUsableGitRevision(currentSha)) {
+if (
+  !isUsableGitRevision(beforeSha) ||
+  !isUsableGitRevision(currentSha) ||
+  beforeSha === currentSha
+) {
   writeGitHubOutput("handles_json", JSON.stringify([]));
   process.exit(0);
 }
@@ -34,6 +43,7 @@ const handles = [
       .map((path) => {
         const match =
           path.match(/^users\/([^/]+)\/(?:\.env|brain\.yaml|content\/.*)$/) ??
+          path.match(/^users\/([^/]+)\.yaml$/) ??
           path.match(/^users\/([^/]+)\.secrets\.yaml\.age$/);
         return match?.[1] ?? null;
       })

package/templates/rover-pilot/deploy/scripts/resolve-user-config.ts

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { loadPilotRegistry } from "@rizom/ops";
 
 import { parseEnvFile, requireEnv, writeGitHubOutput } from "./helpers";
 
@@ -7,6 +9,14 @@ const envPath = `users/${handle}/.env`;
 const brainYamlPath = `users/${handle}/brain.yaml`;
 
 const envEntries = parseEnvFile(envPath);
+const registry = await loadPilotRegistry(process.cwd());
+const user = registry.users.find((candidate) => candidate.handle === handle);
+if (!user) {
+  throw new Error(`Unknown user handle: ${handle}`);
+}
+
+const brainVersion = envEntries["BRAIN_VERSION"] ?? "";
+const imageTag = resolveImageTag(registry, brainVersion);
 const repository = process.env["GITHUB_REPOSITORY"] ?? "";
 const repositoryOwner = repository.split("/")[0] ?? "";
 
@@ -17,23 +27,28 @@ if (!brainDomain) {
   throw new Error(`Missing domain in ${brainYamlPath}`);
 }
 
-const zone =
-  brainDomain.startsWith(`${handle}.`) && brainDomain.length > handle.length + 1
-    ? brainDomain.slice(handle.length + 1)
+const pilotSubdomainPrefix = `${handle}.`;
+const pilotZone =
+  brainDomain.startsWith(pilotSubdomainPrefix) &&
+  brainDomain.length > pilotSubdomainPrefix.length
+    ? brainDomain.slice(pilotSubdomainPrefix.length)
     : "";
-if (!zone) {
-  throw new Error(`Could not derive preview domain from ${brainDomain}`);
-}
-const previewDomain = `${handle}-preview.${zone}`;
+const previewDomain = pilotZone
+  ? `${handle}-preview.${pilotZone}`
+  : `preview.${brainDomain}`;
+const wwwDomain = pilotZone ? "" : `www.${brainDomain}`;
 
 const outputs: Record<string, string> = {
-  brain_version: envEntries["BRAIN_VERSION"] ?? "",
+  brain_version: brainVersion,
   content_repo: envEntries["CONTENT_REPO"] ?? "",
   brain_domain: brainDomain,
   preview_domain: previewDomain,
+  www_domain: wwwDomain,
+  cloudflare_zone_id: user.cloudflareZoneId ?? "",
   brain_yaml_path: brainYamlPath,
   instance_name: `rover-${handle}`,
   image_repository: `ghcr.io/${repository}`,
+  image_tag: imageTag,
   registry_username: repositoryOwner,
 };
 
@@ -47,3 +62,35 @@ for (const key of required) {
 for (const [key, value] of Object.entries(outputs)) {
   writeGitHubOutput(key, value);
 }
+
+function resolveImageTag(
+  registry: Awaited<ReturnType<typeof loadPilotRegistry>>,
+  brainVersion: string,
+): string {
+  if (!brainVersion) {
+    return "";
+  }
+
+  const sitePackages = [
+    ...new Set(
+      registry.users
+        .filter((user) => user.brainVersion === brainVersion)
+        .flatMap((user) =>
+          user.siteOverride
+            ? [`${user.siteOverride.package}@${user.siteOverride.version}`]
+            : [],
+        ),
+    ),
+  ].sort();
+
+  if (sitePackages.length === 0) {
+    return `brain-${brainVersion}`;
+  }
+
+  const siteHash = createHash("sha256")
+    .update(sitePackages.join("\n"))
+    .digest("hex")
+    .slice(0, 12);
+
+  return `brain-${brainVersion}-sites-${siteHash}`;
+}

package/templates/rover-pilot/deploy/scripts/update-dns.ts

@@ -16,8 +16,11 @@ interface CloudflareResult {
   result?: Array<{ id: string }>;
 }
 
-async function upsertRecord(name: string): Promise<void> {
-  const lookupUrl = `${baseUrl}/zones/${zoneId}/dns_records?type=A&name=${encodeURIComponent(name)}`;
+async function findRecordId(
+  name: string,
+  type: "A" | "CNAME",
+): Promise<string | undefined> {
+  const lookupUrl = `${baseUrl}/zones/${zoneId}/dns_records?type=${type}&name=${encodeURIComponent(name)}`;
   const lookup = await fetch(lookupUrl, { headers });
   const payload = (await readJsonResponse(
     lookup,
@@ -27,9 +30,16 @@ async function upsertRecord(name: string): Promise<void> {
     throw new Error(`Cloudflare DNS lookup failed: ${JSON.stringify(payload)}`);
   }
 
-  const existing = payload.result?.[0];
+  return payload.result?.[0]?.id;
+}
+
+async function upsertRecord(name: string): Promise<void> {
+  // Prefer an existing A record. If the hostname currently has a CNAME,
+  // replace that CNAME in-place so deploys can claim legacy www aliases.
+  const existing =
+    (await findRecordId(name, "A")) ?? (await findRecordId(name, "CNAME"));
   const url = existing
-    ? `${baseUrl}/zones/${zoneId}/dns_records/${existing.id}`
+    ? `${baseUrl}/zones/${zoneId}/dns_records/${existing}`
     : `${baseUrl}/zones/${zoneId}/dns_records`;
 
   const response = await fetch(url, {

package/templates/rover-pilot/docs/onboarding-checklist.md

@@ -4,23 +4,43 @@
 2. Run `bunx brains-ops age-key:bootstrap <repo> --push-to gh`.
 3. Fill in `pilot.yaml`.
    - keep your pinned `brainVersion`
-   - confirm shared selectors for `aiApiKey`, `gitSyncToken`, and `mcpAuthToken`
+   - confirm shared selectors for `aiApiKey`, `gitSyncToken`, and `contentRepoAdminToken`
+   - use different tokens for `contentRepoAdminToken` and `gitSyncToken`: admin creates/checks content repos; sync is used by runtime directory-sync
    - confirm `agePublicKey`
-4. Add or edit `users/<handle>.yaml`.
-   - Discord is enabled by default for pilot users
-   - if the user should be an anchor there, set `discord.anchorUserId` to their Discord user ID
-5. Add the user to a cohort in `cohorts/*.yaml`.
+4. Run `bunx brains-ops user:add <repo> <handle> --cohort <cohort>`.
+   - Web chat is the primary interface; it needs no per-user setup beyond the passkey.
+   - `user:add` currently writes `discord: enabled: true`; set it to `false` unless the user's cohort actually uses Discord.
+   - if the user should be an anchor on Discord, add `--anchor-id <discord-user-id>`.
+   - the command creates `users/<handle>.yaml`, `users/<handle>.secrets.yaml`, and the cohort membership without duplicating existing entries.
+5. Edit the generated user file if the anchor profile needs richer metadata.
+   - Set `setup.delivery: email` and `setup.email` so the user gets the passkey setup email — this is the default onboarding path.
+   - For ATProto publishing, add `atproto.identifier` to the user file; put only `atprotoAppPassword` in the per-user secrets file.
+   - Ensure `SETUP_EMAIL_API_KEY` and `SETUP_EMAIL_FROM` exist as GitHub Secrets before deploying any email-setup user.
 6. Run `bunx brains-ops render <repo>`.
 7. Run `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`.
 8. Run `bunx brains-ops cert:bootstrap <repo> --push-to gh`.
-9. Keep raw user secret material locally for now (`.env.local`, file-backed env vars, or equivalent local inputs).
+9. Keep raw user secret material locally for now (`.env.local`, file-backed env vars, or equivalent local inputs), including `CONTENT_REPO_ADMIN_TOKEN` for operator onboarding.
 10. Run `bunx brains-ops secrets:encrypt <repo> <handle>`.
 11. Commit and push `users/<handle>.secrets.yaml.age`.
 12. Run `bunx brains-ops onboard <repo> <handle>`.
-13. Verify the deployed rover core contract:
-    - `https://<handle>.rizom.ai/health` returns `200`
-    - unauthenticated `POST https://<handle>.rizom.ai/mcp` returns `401`
+13. Verify the deployed Rover contract:
+    - all presets:
+      - `https://<handle>.rizom.ai/health` returns `200`
+      - `https://<handle>.rizom.ai/chat` loads the web chat and accepts passkey sign-in
+      - `https://<handle>.rizom.ai/` loads the dashboard (or site surface on `default` preset)
+      - `https://<handle>.rizom.ai/cms` loads the CMS/login surface
+      - unauthenticated `POST https://<handle>.rizom.ai/mcp` returns the expected auth failure
+      - content repo exists and runtime sync is healthy
+      - background jobs are not repeatedly failing, except for expected missing optional integrations
+    - for `presetOverride: default` users:
+      - initial site build completes
 14. For fleet upgrades, edit `pilot.yaml.brainVersion` and push once; CI rebuilds the shared image tag, refreshes generated user env files, and redeploys affected users.
-15. Hand the Discord setup details to the user. If they need direct client access, also hand over the MCP connection details.
-16. If you are also giving them a content repo workflow, describe it first as a normal git repo of markdown/text files; mention Obsidian only as an optional editor.
-17. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.
+15. Confirm the user received the setup email, registered their passkey, and can sign in to web chat at `https://<handle>.rizom.ai/chat`. That completes the default onboarding; everything below is per-cohort extras.
+16. Hand over the browser surfaces:
+    - Chat (primary): `https://<handle>.rizom.ai/chat`
+    - Dashboard: `https://<handle>.rizom.ai/`
+    - CMS: `https://<handle>.rizom.ai/cms`, plus GitHub token guidance if CMS editing is part of their cohort
+17. For Discord-enabled cohorts, hand the Discord setup details to the user as a secondary chat surface.
+18. If they need direct client access (MCP), use OAuth/passkey-capable clients where possible.
+19. If you are also giving them a content repo workflow, describe it as optional and frame git/Obsidian as an advanced file-based path, not the default.
+20. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.